@authrim/server 0.1.0

package/dist/types-CzpMdWFR.d.cts

@@ -0,0 +1,435 @@
+import { P as PublicJwk, A as AuthrimServerConfig, R as ResolvedAuthrimServerConfig } from './config-I0GIVJA_.cjs';
+
+/**
+ * JWT Claims Type Definitions
+ *
+ * Based on RFC 7519 (JSON Web Token) and OIDC Core 1.0
+ */
+/**
+ * Standard JWT claims (RFC 7519 Section 4.1)
+ */
+interface StandardClaims {
+    /** Issuer */
+    iss?: string;
+    /** Subject */
+    sub?: string;
+    /** Audience (string or array) */
+    aud?: string | string[];
+    /** Expiration Time (Unix timestamp) */
+    exp?: number;
+    /** Not Before (Unix timestamp) */
+    nbf?: number;
+    /** Issued At (Unix timestamp) */
+    iat?: number;
+    /** JWT ID */
+    jti?: string;
+}
+/**
+ * DPoP confirmation claim (RFC 9449)
+ */
+interface ConfirmationClaim {
+    /** JWK Thumbprint (RFC 7638) */
+    jkt?: string;
+}
+/**
+ * Access token claims
+ */
+interface AccessTokenClaims extends StandardClaims {
+    /** Client ID */
+    client_id?: string;
+    /** Scope (space-separated string) */
+    scope?: string;
+    /** Token ID (for introspection reference) */
+    token_id?: string;
+    /** Confirmation claim (for DPoP-bound tokens) */
+    cnf?: ConfirmationClaim;
+    /** Allow additional custom claims */
+    [key: string]: unknown;
+}
+/**
+ * ID token claims (OIDC Core 1.0)
+ */
+interface IdTokenClaims extends StandardClaims {
+    /** Nonce */
+    nonce?: string;
+    /** Authentication time */
+    auth_time?: number;
+    /** Access token hash */
+    at_hash?: string;
+    /** Code hash */
+    c_hash?: string;
+    /** ACR (Authentication Context Class Reference) */
+    acr?: string;
+    /** AMR (Authentication Methods References) */
+    amr?: string[];
+    /** Authorized party */
+    azp?: string;
+    /** Allow additional custom claims */
+    [key: string]: unknown;
+}
+/**
+ * Validated token result
+ */
+interface ValidatedToken {
+    /** Parsed and validated claims */
+    claims: AccessTokenClaims;
+    /** Raw token string */
+    token: string;
+    /** Token type */
+    tokenType: 'Bearer' | 'DPoP';
+    /** Time remaining until expiration (seconds) */
+    expiresIn?: number;
+}
+/**
+ * JWT header (RFC 7519 Section 5)
+ */
+interface JwtHeader {
+    /** Algorithm */
+    alg: string;
+    /** Type (should be 'JWT') */
+    typ?: string;
+    /** Key ID */
+    kid?: string;
+    /** JWK (for DPoP proofs) */
+    jwk?: Record<string, unknown>;
+}
+/**
+ * Parsed JWT structure
+ */
+interface ParsedJwt<T = Record<string, unknown>> {
+    header: JwtHeader;
+    payload: T;
+    signature: string;
+}
+
+/**
+ * Token-related Type Definitions
+ */
+
+/**
+ * Token validation options
+ */
+interface TokenValidationOptions {
+    /** Expected issuer(s) */
+    issuer: string | string[];
+    /** Expected audience(s) */
+    audience: string | string[];
+    /** Clock tolerance in seconds (default: 60) */
+    clockToleranceSeconds?: number;
+    /** Required scopes (if any) */
+    requiredScopes?: string[];
+    /** Whether to validate DPoP binding if cnf claim is present */
+    validateDPoP?: boolean;
+}
+/**
+ * Claims validation options
+ */
+interface ClaimsValidationOptions {
+    /** Expected issuer(s) */
+    issuer: string | string[];
+    /** Expected audience(s) */
+    audience: string | string[];
+    /** Clock tolerance in seconds */
+    clockToleranceSeconds: number;
+    /** Current timestamp (Unix seconds) */
+    now: number;
+    /**
+     * Require exp claim to be present
+     * Per OIDC Core 1.0 Section 3.1.3.7, ID Tokens MUST have exp claim
+     * Default: false (for generic JWT validation)
+     */
+    requireExp?: boolean;
+    /**
+     * Require iat claim to be present
+     * Per OIDC Core 1.0 Section 3.1.3.7, ID Tokens MUST have iat claim
+     * Default: false (for generic JWT validation)
+     */
+    requireIat?: boolean;
+}
+/**
+ * Claims validation result
+ */
+interface ClaimsValidationResult {
+    valid: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Token validation result (success case)
+ */
+interface TokenValidationSuccess {
+    data: ValidatedToken;
+    error: null;
+}
+/**
+ * Token validation result (error case)
+ */
+interface TokenValidationError {
+    data: null;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Token validation result (discriminated union)
+ */
+type TokenValidationResult = TokenValidationSuccess | TokenValidationError;
+/**
+ * Token introspection request (RFC 7662)
+ */
+interface IntrospectionRequest {
+    /** Token to introspect */
+    token: string;
+    /** Token type hint */
+    token_type_hint?: 'access_token' | 'refresh_token';
+}
+/**
+ * Token introspection response (RFC 7662)
+ */
+interface IntrospectionResponse {
+    /** Whether the token is active */
+    active: boolean;
+    /** Scope */
+    scope?: string;
+    /** Client ID */
+    client_id?: string;
+    /** Username */
+    username?: string;
+    /** Token type */
+    token_type?: string;
+    /** Expiration time */
+    exp?: number;
+    /** Issued at */
+    iat?: number;
+    /** Not before */
+    nbf?: number;
+    /** Subject */
+    sub?: string;
+    /** Audience */
+    aud?: string | string[];
+    /** Issuer */
+    iss?: string;
+    /** JWT ID */
+    jti?: string;
+    /** Confirmation (DPoP binding) */
+    cnf?: {
+        jkt?: string;
+    };
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Token revocation request (RFC 7009)
+ */
+interface RevocationRequest {
+    /** Token to revoke */
+    token: string;
+    /** Token type hint */
+    token_type_hint?: 'access_token' | 'refresh_token';
+}
+
+/**
+ * DPoP Type Definitions (RFC 9449)
+ *
+ * Demonstrating Proof of Possession at the Application Layer
+ */
+
+/**
+ * DPoP proof header (RFC 9449 Section 4.2)
+ */
+interface DPoPProofHeader {
+    /** Type (must be 'dpop+jwt') */
+    typ: 'dpop+jwt';
+    /** Algorithm */
+    alg: string;
+    /** Public key (required in header) */
+    jwk: PublicJwk;
+}
+/**
+ * DPoP proof payload (RFC 9449 Section 4.2)
+ */
+interface DPoPProofPayload {
+    /** Unique identifier (for replay prevention) */
+    jti: string;
+    /** HTTP method (uppercase) */
+    htm: string;
+    /** HTTP URI (scheme + authority + path, no query/fragment) */
+    htu: string;
+    /** Issued at (Unix timestamp) */
+    iat: number;
+    /** Server-provided nonce (optional) */
+    nonce?: string;
+    /** Access token hash (optional, for resource requests) */
+    ath?: string;
+}
+/**
+ * DPoP validation options
+ */
+interface DPoPValidationOptions {
+    /** Expected HTTP method */
+    method: string;
+    /** Expected HTTP URI */
+    uri: string;
+    /** Access token (for ath validation) */
+    accessToken?: string;
+    /** Expected JWK thumbprint (from token's cnf.jkt) */
+    expectedThumbprint?: string;
+    /** Server-provided nonce to validate */
+    expectedNonce?: string;
+    /** Maximum age for iat claim (seconds, default: 60) */
+    maxAge?: number;
+    /** Clock tolerance (seconds, default: 60) */
+    clockTolerance?: number;
+}
+/**
+ * DPoP validation result
+ */
+interface DPoPValidationResult {
+    /** Whether validation succeeded */
+    valid: boolean;
+    /** JWK thumbprint of the proof key */
+    thumbprint?: string;
+    /** Error code if validation failed */
+    errorCode?: string;
+    /** Error message if validation failed */
+    errorMessage?: string;
+}
+
+/**
+ * AuthrimServer - Main entry point for the server SDK
+ */
+
+/**
+ * AuthrimServer
+ *
+ * Main class for server-side token validation and DPoP handling.
+ */
+declare class AuthrimServer {
+    private readonly config;
+    private jwksManager;
+    private tokenValidator;
+    private dpopValidator;
+    private introspectionClient;
+    private revocationClient;
+    private initPromise;
+    private initialized;
+    constructor(config: AuthrimServerConfig);
+    /**
+     * Initialize the server (discovers JWKS endpoint if needed)
+     *
+     * This method is idempotent and thread-safe. Multiple concurrent calls
+     * will wait for the same initialization to complete.
+     */
+    init(): Promise<void>;
+    private doInit;
+    /**
+     * Discover JWKS URI from OpenID Configuration
+     */
+    private discoverJwksUri;
+    /**
+     * Validate a JWT access token
+     *
+     * @param token - JWT string
+     * @returns Validation result
+     */
+    validateToken(token: string): Promise<TokenValidationResult>;
+    /**
+     * Validate a DPoP proof
+     *
+     * @param proof - DPoP proof JWT
+     * @param options - Validation options
+     * @returns Validation result
+     */
+    validateDPoP(proof: string, options: DPoPValidationOptions): Promise<DPoPValidationResult>;
+    /**
+     * Introspect a token
+     *
+     * @param token - Token to introspect
+     * @param tokenTypeHint - Optional token type hint
+     * @returns Introspection response
+     */
+    introspect(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<IntrospectionResponse>;
+    /**
+     * Revoke a token
+     *
+     * @param token - Token to revoke
+     * @param tokenTypeHint - Optional token type hint
+     */
+    revoke(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<void>;
+    /**
+     * Get the resolved configuration
+     */
+    getConfig(): ResolvedAuthrimServerConfig;
+    /**
+     * Invalidate JWKS cache
+     */
+    invalidateJwksCache(): void;
+}
+/**
+ * Create an AuthrimServer instance
+ *
+ * @param config - Server configuration
+ * @returns AuthrimServer instance
+ */
+declare function createAuthrimServer(config: AuthrimServerConfig): AuthrimServer;
+
+/**
+ * Middleware Type Definitions
+ */
+
+/**
+ * Framework-agnostic request representation
+ */
+interface AuthenticateRequest {
+    /** HTTP headers (keys should be lowercase) */
+    headers: Record<string, string | string[] | undefined>;
+    /** HTTP method */
+    method: string;
+    /** Full URL (scheme://host:port/path) */
+    url: string;
+}
+/**
+ * Authentication result (success case)
+ */
+interface AuthenticateSuccess {
+    data: {
+        /** Validated token claims */
+        claims: ValidatedToken;
+        /** Token type */
+        tokenType: 'Bearer' | 'DPoP';
+    };
+    error: null;
+}
+/**
+ * Authentication result (error case)
+ */
+interface AuthenticateError {
+    data: null;
+    error: {
+        code: string;
+        message: string;
+        httpStatus: number;
+    };
+}
+/**
+ * Authentication result (discriminated union)
+ */
+type AuthenticateResult = AuthenticateSuccess | AuthenticateError;
+/**
+ * Middleware options
+ */
+interface MiddlewareOptions {
+    /** Optional realm for WWW-Authenticate header */
+    realm?: string;
+    /** Required scopes (optional) */
+    requiredScopes?: string[];
+    /** Whether to validate DPoP binding */
+    validateDPoP?: boolean;
+    /** Custom error handler */
+    onError?: (error: AuthenticateError['error']) => void;
+}
+
+export { AuthrimServer as A, type ClaimsValidationOptions as C, type DPoPValidationOptions as D, type IntrospectionRequest as I, type JwtHeader as J, type MiddlewareOptions as M, type ParsedJwt as P, type RevocationRequest as R, type StandardClaims as S, type TokenValidationOptions as T, type ValidatedToken as V, type AuthenticateRequest as a, type AuthenticateResult as b, type ClaimsValidationResult as c, type TokenValidationResult as d, type IntrospectionResponse as e, type DPoPValidationResult as f, type AccessTokenClaims as g, type AuthenticateError as h, type AuthenticateSuccess as i, type ConfirmationClaim as j, type DPoPProofHeader as k, type DPoPProofPayload as l, type IdTokenClaims as m, createAuthrimServer as n };