syntax = "proto3";

package tars.tokens.v1;

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "tars/auth/v1/auth_options.proto";

option go_package = "github.com/tetrateio/fraser/api/tars/tokens/v1;tokensv1";

// TokensService provides APIs for user token management from dataplane.
// These endpoints are called by dataplane instances using service account
// tokens.
service TokensService {
  // GetRevocationList returns a list of revoked token JTIs.
  // This is used by dataplane to cache and check token revocations locally.
  rpc GetRevocationList(GetRevocationListRequest) returns (GetRevocationListResponse) {
    option (google.api.http) = {get: "/v1/tokens/revocations"};
    option (tars.auth.v1.auth) = {
      auth_types: [
        AUTH_TYPE_SERVICE_ACCOUNT,
        AUTH_TYPE_API_KEY
      ]
      scopes: [
        "read",
        "admin"
      ]
    };
  }

  // UpdateLastUsed updates the last used timestamp for a token.
  // Called by dataplane when a token is used for authentication.
  rpc UpdateLastUsed(UpdateLastUsedRequest) returns (UpdateLastUsedResponse) {
    option (google.api.http) = {
      post: "/v1/tokens/usage"
      body: "*"
    };
    option (tars.auth.v1.auth) = {
      auth_types: [AUTH_TYPE_SERVICE_ACCOUNT]
      scopes: ["write"]
    };
  }
}

// GetRevocationListRequest requests the revocation list.
message GetRevocationListRequest {
  // Optional: Only return revocations updated after this timestamp.
  // Used for incremental updates.
  optional google.protobuf.Timestamp since = 1;

  // Optional: Maximum number of entries to return.
  // If not specified, returns all revoked tokens.
  optional int32 limit = 2;
}

// GetRevocationListResponse contains the revocation list.
message GetRevocationListResponse {
  // List of revoked token information.
  repeated RevokedTokenInfo revocations = 1;

  // Timestamp of this revocation list snapshot.
  // Can be used for 'since' in next request for incremental updates.
  google.protobuf.Timestamp snapshot_at = 2;

  // Total number of revoked tokens (may be more than returned if limit was
  // set).
  int64 total_count = 3;
}

// RevokedTokenInfo contains information about a revoked token.
message RevokedTokenInfo {
  // JWT ID (jti) of the revoked token.
  string jti = 1;

  // When the token was revoked.
  google.protobuf.Timestamp revoked_at = 2;

  // Optional: Reason for revocation.
  optional string reason = 3;
}

// UpdateLastUsedRequest updates the last used timestamp for a token.
message UpdateLastUsedRequest {
  // JWT ID (jti) of the token.
  string jti = 1;

  // Timestamp when the token was used.
  // If not provided, server will use current time.
  optional google.protobuf.Timestamp used_at = 2;
}

// UpdateLastUsedResponse confirms the update.
message UpdateLastUsedResponse {
  // Whether the update was successful.
  bool success = 1;

  // The timestamp that was recorded.
  google.protobuf.Timestamp recorded_at = 2;
}
