@openagentid/oidc API

export declare class OidcBridge {
  constructor(input: OidcConfig | SingleProviderInput): OidcBridge;
  getConfig(): Readonly<OidcConfig>;
  deriveAgentFromJwt(token: string, agentName: string): Promise<DerivedAgent>;
  actToJwt(claims: ActJwtClaims, signingKey: jose.KeyLike | Uint8Array, algorithm: string, kid?: string): Promise<string>;
  wrapActAsJwt(opts: { agentDid: string; bridgeIssuer: string; audience?: string; scopes: readonly string[]; lineageDepth: number; parentHmr: string; actB64: string; signingKey: jose.KeyLike | Uint8Array; algorithm: string; kid?: string; }): Promise<string>;
  exchangeToken(humanJwt: string, requestedScopes: readonly string[], signingKey?: jose.KeyLike | Uint8Array, algorithm?: string, bridgeIssuer?: string): Promise<TokenExchangeResponse>;
  executeExchange(request: TokenExchangeRequest, signingKey: jose.KeyLike | Uint8Array | undefined, algorithm: string, bridgeIssuer: string): Promise<TokenExchangeResponse>;
  validateJwt(token: string): Promise<ValidatedClaims>;
  refreshAllJwks(): Promise<void>;
}

export type ProviderConfig = z.infer<typeof providerConfigSchema>;

export type OidcConfig = z.infer<typeof oidcConfigSchema>;

/** Shorthand input for single-provider setup. */
export interface SingleProviderInput {
    /** Provider name. */
    name?: string;
    /** OIDC issuer URL. */
    issuer: string;
    /** Expected audience. */
    audience?: string;
    /** JWKS URL override. */
    jwksUrl?: string;
    /** HMR claim name. */
    hmrClaim?: string;
    /** Scope mapping. */
    scopeMapping?: Record<string, string[]>;
    /** OAS namespace. */
    namespace?: string;
    /** JWT TTL seconds. */
    jwtTtlSeconds?: number;
    /** HTTP timeout ms. */
    httpTimeoutMs?: number;
    /** Custom fetch. */
    fetch?: typeof globalThis.fetch;
}

export declare const providerConfigSchema: z.ZodObject<{ name: z.ZodString; issuer: z.ZodString; audience: z.ZodOptional<z.ZodString>; jwksUrl: z.ZodOptional<z.ZodString>; hmrClaim: z.ZodDefault<z.ZodString>; scopeMapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>; }, z.core.$strip>;

export declare const oidcConfigSchema: z.ZodObject<{ providers: z.ZodArray<z.ZodObject<{ name: z.ZodString; issuer: z.ZodString; audience: z.ZodOptional<z.ZodString>; jwksUrl: z.ZodOptional<z.ZodString>; hmrClaim: z.ZodDefault<z.ZodString>; scopeMapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>; }, z.core.$strip>>; namespace: z.ZodDefault<z.ZodString>; jwtTtlSeconds: z.ZodDefault<z.ZodNumber>; httpTimeoutMs: z.ZodDefault<z.ZodNumber>; fetch: z.ZodOptional<z.ZodFunction<z.core.$ZodFunctionArgs, z.core.$ZodFunctionOut>>; }, z.core.$strip>;

export declare const singleProviderConfig: (input: SingleProviderInput) => OidcConfig;

export declare const findProvider: (config: OidcConfig, issuer: string) => ProviderConfig | undefined;

export declare const resolveFetch: (config: OidcConfig) => typeof globalThis.fetch;

export type DiscoveryDocument = z.infer<typeof discoveryDocumentSchema>;

export declare class DiscoveryClient {
  constructor(fetchImpl: typeof globalThis.fetch, timeoutMs?: number, cacheTtlMs?: number): DiscoveryClient;
  discover(issuer: string): Promise<DiscoveryDocument>;
  invalidate(issuer: string): void;
  invalidateAll(): void;
}

export declare const discoveryDocumentSchema: z.ZodObject<{ issuer: z.ZodString; authorization_endpoint: z.ZodDefault<z.ZodString>; token_endpoint: z.ZodDefault<z.ZodString>; jwks_uri: z.ZodString; response_types_supported: z.ZodDefault<z.ZodArray<z.ZodString>>; subject_types_supported: z.ZodDefault<z.ZodArray<z.ZodString>>; id_token_signing_alg_values_supported: z.ZodDefault<z.ZodArray<z.ZodString>>; scopes_supported: z.ZodDefault<z.ZodArray<z.ZodString>>; token_exchange_endpoint: z.ZodOptional<z.ZodString>; }, z.core.$strip>;

export declare const wellKnownUrl: (issuer: string) => string;

export declare class OidcBridgeError {
  code: OidcErrorCode;
  constructor(code: OidcErrorCode, message: string): OidcBridgeError;
  config(message: string): OidcBridgeError;
  discovery(message: string): OidcBridgeError;
  jwks(message: string): OidcBridgeError;
  jwtValidation(message: string): OidcBridgeError;
  unknownIssuer(issuer: string): OidcBridgeError;
  mapping(message: string): OidcBridgeError;
  exchange(message: string): OidcBridgeError;
  signing(message: string): OidcBridgeError;
  transport(message: string): OidcBridgeError;
}

/**
 * Error types for the OIDC bridge.
 */
/** Error codes for OIDC bridge errors. */
export type OidcErrorCode = 'DISCOVERY_ERROR' | 'JWKS_ERROR' | 'JWT_VALIDATION_ERROR' | 'UNKNOWN_ISSUER' | 'MAPPING_ERROR' | 'EXCHANGE_ERROR' | 'SIGNING_ERROR' | 'CONFIG_ERROR' | 'TRANSPORT_ERROR';

export type TokenExchangeRequest = z.infer<typeof tokenExchangeRequestSchema>;

/** Token exchange response (RFC 8693 Section 2.2). */
export interface TokenExchangeResponse {
    readonly accessToken: string;
    readonly issuedTokenType: string;
    readonly tokenType: 'Bearer';
    readonly expiresIn: number;
    readonly scope?: string;
}

/** RFC 8693 error response. */
export interface TokenExchangeError {
    readonly error: string;
    readonly errorDescription?: string;
}

export declare const tokenExchangeRequestSchema: z.ZodObject<{ grantType: z.ZodLiteral<"urn:ietf:params:oauth:grant-type:token-exchange">; subjectToken: z.ZodString; subjectTokenType: z.ZodEnum<{ "urn:ietf:params:oauth:token-type:jwt": "urn:ietf:params:oauth:token-type:jwt"; "urn:ietf:params:oauth:token-type:access_token": "urn:ietf:params:oauth:token-type:access_token"; }>; requestedTokenType: z.ZodOptional<z.ZodEnum<{ "urn:ietf:params:oauth:token-type:jwt": "urn:ietf:params:oauth:token-type:jwt"; "urn:ietf:params:oauth:token-type:access_token": "urn:ietf:params:oauth:token-type:access_token"; "urn:openagent:token-type:act": "urn:openagent:token-type:act"; }>>; scope: z.ZodOptional<z.ZodString>; audience: z.ZodOptional<z.ZodString>; resource: z.ZodOptional<z.ZodString>; actorToken: z.ZodOptional<z.ZodString>; actorTokenType: z.ZodOptional<z.ZodString>; }, z.core.$strip>;

export declare const GRANT_TYPE_TOKEN_EXCHANGE: "urn:ietf:params:oauth:grant-type:token-exchange";

export declare const TOKEN_TYPE_JWT: "urn:ietf:params:oauth:token-type:jwt";

export declare const TOKEN_TYPE_ACT: "urn:openagent:token-type:act";

export declare const TOKEN_TYPE_ACCESS: "urn:ietf:params:oauth:token-type:access_token";

export declare const createJwtToActRequest: (subjectToken: string, scopes?: readonly string[]) => TokenExchangeRequest;

export declare const validateExchangeRequest: (request: TokenExchangeRequest) => void;

export declare const parseScopes: (scope: string | undefined) => string[];

export declare const successResponse: (accessToken: string, issuedTokenType: string, expiresIn: number, scope?: string) => TokenExchangeResponse;

export declare const exchangeErrors: { readonly invalidRequest: (desc: string) => TokenExchangeError; readonly invalidGrant: (desc: string) => TokenExchangeError; readonly unsupportedTokenType: (desc: string) => TokenExchangeError; readonly invalidTarget: (desc: string) => TokenExchangeError; };

export declare class JwksClient {
  constructor(fetchImpl: typeof globalThis.fetch, timeoutMs?: number, cacheTtlMs?: number): JwksClient;
  fetchJwks(jwksUri: string): Promise<jose.JSONWebKeySet>;
  refresh(jwksUri: string): Promise<jose.JSONWebKeySet>;
  selectKey(jwks: jose.JSONWebKeySet, kid: string | undefined, alg: string | undefined): jose.JWK;
  invalidate(jwksUri: string): void;
}

/** Claims extracted from a validated human JWT. */
export interface ValidatedClaims {
    /** Issuer (`iss` claim). */
    readonly issuer: string;
    /** Subject (`sub` claim). */
    readonly subject: string;
    /** Audience (`aud` claim). */
    readonly audience: readonly string[];
    /** Expiration (epoch seconds). */
    readonly exp: number;
    /** Issued-at (epoch seconds). */
    readonly iat: number;
    /** The claim value that maps to the HMR. */
    readonly hmrValue: string;
    /** OIDC scopes extracted from the token. */
    readonly scopes: readonly string[];
    /** All original claims. */
    readonly rawClaims: Readonly<Record<string, unknown>>;
}

/** Claims for an outbound JWT wrapping an Arsenal ACT (Flow 2). */
export interface ActJwtClaims {
    /** Subject: the agent's DID. */
    readonly sub: string;
    /** Issuer: the bridge's own issuer identifier. */
    readonly iss: string;
    /** Audience. */
    readonly aud?: string;
    /** Expiration (epoch seconds). */
    readonly exp: number;
    /** Issued-at (epoch seconds). */
    readonly iat: number;
    /** JWT ID. */
    readonly jti: string;
    /** Arsenal scope strings. */
    readonly scope: string;
    /** Lineage depth (hops from HMR root). */
    readonly lineage_depth: number;
    /** Parent HMR DID. */
    readonly parent_hmr: string;
    /** Serialized ACT (base64url). */
    readonly act: string;
}

export declare const decodeJwtHeader: (token: string) => { kid?: string; alg?: string; };

export declare const extractUnverifiedIssuer: (token: string) => string;

export declare const validateJwt: (token: string, jwk: jose.JWK, provider: ProviderConfig) => Promise<ValidatedClaims>;

export declare const buildActClaims: (opts: { agentDid: string; bridgeIssuer: string; audience?: string; scopes: readonly string[]; lineageDepth: number; parentHmr: string; actB64: string; ttlSeconds: number; }) => ActJwtClaims;

export declare const signActJwt: (claims: ActJwtClaims, signingKey: jose.KeyLike | Uint8Array, algorithm: string, kid?: string) => Promise<string>;

/** Result of deriving an agent DID from a human JWT. */
export interface DerivedAgent {
    /** Agent DID (did:oas:<ns>:agent:<name>). */
    readonly agentDid: string;
    /** Agent keypair (Ed25519 public + private key bytes). */
    readonly agentKeypair: {
        readonly publicKey: Uint8Array;
        readonly privateKey: Uint8Array;
    };
    /** Lineage proof (JSON structure). */
    readonly lineageProof: Record<string, unknown> | null;
    /** Parent HMR DID. */
    readonly parentHmrDid: string;
    /** Lineage depth (0 for HMR, 1 for direct child). */
    readonly lineageDepth: number;
}

export declare const deriveAgentFromClaims: (namespace: string, claims: ValidatedClaims, agentName: string) => DerivedAgent;

export declare const hmrIdentifierFromClaims: (issuer: string, hmrValue: string) => string;

export declare const mapScopes: (oidcScopes: readonly string[], scopeMapping: Readonly<Record<string, readonly string[]>>) => string[];

export declare const VERSION: "0.1.1";