syntax = "proto3";

package tars.api_keys.v1;

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

option go_package = "github.com/tetrateio/fraser/api/tars/api_keys/v1;apikeysv1";

// ApiKeysService provides management-plane APIs for creating and managing user API keys.
// These endpoints are intended to be called by internal services (e.g. the Next.js app)
// using an admin-scoped management-plane API key.
service ApiKeysService {
  // CreateApiKey creates a new JWT user-token API key for a user and returns the plaintext token exactly once.
  rpc CreateApiKey(CreateApiKeyRequest) returns (CreateApiKeyResponse) {
    option (tars.docs.v1.group) = "API Keys";
    option (google.api.http) = {
      post: "/v1/api-keys"
      body: "*"
    };
    option (tars.auth.v1.auth) = {
      auth_types: [AUTH_TYPE_API_KEY]
      scopes: ["admin"]
    };
  }

  // UpdateApiKey updates mutable fields of an API key (name and/or active state).
  rpc UpdateApiKey(UpdateApiKeyRequest) returns (UpdateApiKeyResponse) {
    option (tars.docs.v1.group) = "API Keys";
    option (google.api.http) = {
      patch: "/v1/api-keys/{key_id}"
      body: "*"
    };
    option (tars.auth.v1.auth) = {
      auth_types: [AUTH_TYPE_API_KEY]
      scopes: ["admin"]
    };
  }

  // DeleteApiKey soft-deletes an API key (sets deleted_at).
  rpc DeleteApiKey(DeleteApiKeyRequest) returns (DeleteApiKeyResponse) {
    option (tars.docs.v1.group) = "API Keys";
    option (google.api.http) = {delete: "/v1/api-keys/{key_id}"};
    option (tars.auth.v1.auth) = {
      auth_types: [AUTH_TYPE_API_KEY]
      scopes: ["admin"]
    };
  }
}

message EnterpriseContext {
  // Customer identifier (e.g. "default", "acme").
  string customer_id = 1;
  // Workspace identifier (defaults to "default" when empty).
  string workspace_id = 2;
  // Organization unit for the user (e.g. "engineering").
  string organization_unit = 3;
}

message CreateApiKeyRequest {
  // User ID that will own the API key.
  string user_id = 1;

  // User key address input (typically email or user id).
  // Required for API parity with client flows and request provenance checks.
  // In JWT-based issuance, returned key_address is derived from user_id by the token service.
  string user_key_address = 2;

  // Human-readable key name.
  string name = 3;

  // Optional enterprise context overrides for JWT user-token issuance.
  // When omitted, service defaults are used.
  optional EnterpriseContext enterprise_context = 4;
}

message CreateApiKeyResponse {
  // Key ID (UUID).
  string id = 1;
  // User ID that owns the key.
  string user_id = 2;
  // Plaintext key (returned once).
  string api_key = 3;
  // 12-char key prefix.
  string prefix = 4;
  // 64-char hex HMAC hash of the full key.
  string key_hash = 5;
  // 16-char hex key address from the token service (currently xxhash64(user_id) for JWT issuance).
  string key_address = 6;
  // Last 4 chars of the plaintext key (for display).
  string key_suffix = 7;
}

message UpdateApiKeyRequest {
  // User ID that owns the API key.
  string user_id = 1;
  // Key ID (UUID).
  string key_id = 2;

  // Optional new name.
  optional string name = 3;
  // Optional active state.
  optional bool is_active = 4;
}

message UpdateApiKeyResponse {
  // True when the update was applied; failures surface as RPC errors instead.
  bool success = 1;
}

message DeleteApiKeyRequest {
  // User ID that owns the API key.
  string user_id = 1;
  // Key ID (UUID).
  string key_id = 2;
}

message DeleteApiKeyResponse {
  // True when the key was soft-deleted; failures surface as RPC errors instead.
  bool success = 1;
}
