/**
 * OIDC type definitions for SentryAgent.ai AgentIdP.
 * Covers ID token claims, JWKS response, discovery document, and agent-info response.
 */

// ============================================================================
// JWKS Key and Response
// ============================================================================

/**
 * A single JSON Web Key as returned in the JWKS endpoint.
 * Supports both RSA (RS256) and EC P-256 (ES256) keys.
 */
export interface IJWKSKey {
  /** Key ID — matches the `kid` header in signed JWTs. */
  kid: string;
  /** Key type: "RSA" or "EC". */
  kty: string;
  /** Intended use: always "sig" for signing keys. */
  use: string;
  /** Algorithm: "RS256" or "ES256". */
  alg: string;
  /** RSA: Base64url-encoded modulus. */
  n?: string;
  /** RSA: Base64url-encoded public exponent. */
  e?: string;
  /** EC: Curve name, e.g. "P-256". */
  crv?: string;
  /** EC: Base64url-encoded x coordinate. */
  x?: string;
  /** EC: Base64url-encoded y coordinate. */
  y?: string;
}

/**
 * JWKS (JSON Web Key Set) response returned by the `/.well-known/jwks.json` endpoint.
 */
export interface IJWKSResponse {
  /** Array of JSON Web Keys. Includes all non-expired keys (for rotation grace period). */
  keys: IJWKSKey[];
}

// ============================================================================
// OIDC Key record (database row)
// ============================================================================

/**
 * Represents a row in the `oidc_keys` table.
 */
export interface IOIDCKey {
  /** UUID primary key. */
  id: string;
  /** Key identifier (e.g. "key-20260330-001"). Used as JWT `kid` header. */
  kid: string;
  /** Signing algorithm: "RS256" or "ES256". */
  algorithm: string;
  /** Public key in JWK format as stored in DB. */
  public_key_jwk: IJWKSKey;
  /** Vault KV2 path where the private key is stored, or "dev:no-vault" in dev mode. */
  vault_key_path: string;
  /** True if this is the active signing key. Only one key is current at a time. */
  is_current: boolean;
  /** Timestamp when this key was generated. */
  created_at: Date;
  /** Timestamp when all tokens signed with this key will have expired. */
  expires_at: Date;
}

// ============================================================================
// ID Token Claims
// ============================================================================

/**
 * Claims payload of an OIDC ID token.
 * Conforms to OpenID Connect Core 1.0 §2 with additional agent-specific claims.
 */
export interface IIDTokenClaims {
  /** Issuer — the OIDC provider URL. */
  iss: string;
  /** Subject — the agent UUID. */
  sub: string;
  /** Audience — the client_id that requested the token. */
  aud: string;
  /** Issued-at time (Unix seconds). */
  iat: number;
  /** Expiry time (Unix seconds). */
  exp: number;
  /** Nonce — if provided in the original request, echoed here for replay protection. */
  nonce?: string;
  /** Functional classification of the agent. */
  agent_type: string;
  /** Target deployment environment of the agent. */
  deployment_env: string;
  /** Organization UUID the agent belongs to. */
  organization_id: string;
  /** W3C DID identifier for the agent, if one has been generated. */
  did?: string;
}

// ============================================================================
// OIDC Discovery Document
// ============================================================================

/**
 * OpenID Connect Discovery 1.0 document returned by `/.well-known/openid-configuration`.
 * All standard fields are included; `authorization_endpoint` is a stub (not implemented in Phase 3).
 */
export interface IOIDCDiscoveryDocument {
  /** OIDC Issuer URL. Must match the `iss` claim in ID tokens. */
  issuer: string;
  /** Authorization endpoint (stub — not implemented in Phase 3). */
  authorization_endpoint: string;
  /** Token endpoint for the client_credentials grant. */
  token_endpoint: string;
  /** JWKS endpoint for ID token verification public keys. */
  jwks_uri: string;
  /** Supported response types. */
  response_types_supported: string[];
  /** Supported subject types. */
  subject_types_supported: string[];
  /** Supported ID token signing algorithms. */
  id_token_signing_alg_values_supported: string[];
  /** Supported OAuth 2.0 scopes. */
  scopes_supported: string[];
  /** Claims that may appear in ID tokens or the agent-info response. */
  claims_supported: string[];
  /** Supported grant types. */
  grant_types_supported: string[];
}

// ============================================================================
// GitHub OIDC Trust Policy
// ============================================================================

/**
 * Supported OIDC provider identifiers.
 * Currently only "github" is supported; the type is extensible.
 */
export type OIDCProvider = 'github';

/**
 * Request body for registering an OIDC trust policy via POST /oidc/trust-policies.
 */
export interface ICreateTrustPolicyRequest {
  /** OIDC provider. Currently only "github" is supported. */
  provider: OIDCProvider;
  /** GitHub repository in "org/repo" format. Only workflows in this repo may exchange tokens. */
  repository: string;
  /** Optional branch constraint. When omitted, any branch is allowed. */
  branch?: string;
  /** UUID of the agent this trust policy grants access to. */
  agentId: string;
}

/**
 * A persisted OIDC trust policy record.
 */
export interface IOIDCTrustPolicy {
  /** UUID primary key. */
  id: string;
  /** OIDC provider identifier. */
  provider: OIDCProvider;
  /** GitHub repository (e.g. "org/repo"). */
  repository: string;
  /** Optional branch constraint. Null means any branch is allowed. */
  branch: string | null;
  /** UUID of the agent this trust policy grants access to. */
  agentId: string;
  /** Timestamp when the policy was created. */
  createdAt: Date;
  /** Timestamp when the policy was last updated. */
  updatedAt: Date;
}

// ============================================================================
// Agent Info Response
// ============================================================================

/**
 * Response body for the `GET /agent-info` endpoint.
 * Returns agent identity claims for the authenticated agent, similar to OIDC UserInfo.
 */
export interface IAgentInfoResponse {
  /** Agent UUID (subject). */
  sub: string;
  /** Functional classification of the agent. */
  agent_type: string;
  /** Target deployment environment of the agent. */
  deployment_env: string;
  /** Organization UUID the agent belongs to. */
  organization_id: string;
  /** W3C DID identifier, if one has been generated. */
  did?: string;
  /** The OAuth 2.0 scope associated with the Bearer token used to call this endpoint. */
  scope: string;
}
