@authrim/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2090 @@
+/**
+ * HTTP Client Provider Interface
+ *
+ * Platform-agnostic HTTP client abstraction.
+ * Implementations must be injected - @authrim/core does not use fetch directly.
+ */
+/**
+ * HTTP request options
+ */
+interface HttpOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers?: Record<string, string>;
+    body?: string | FormData | URLSearchParams;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Signal for request cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * HTTP response wrapper
+ */
+interface HttpResponse<T = unknown> {
+    /** HTTP status code */
+    status: number;
+    /** HTTP status text */
+    statusText: string;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** Parsed response body */
+    data: T;
+    /** Whether the response was successful (2xx) */
+    ok: boolean;
+}
+/**
+ * HTTP Client interface
+ *
+ * Implementations should:
+ * - Handle JSON parsing automatically when Content-Type is application/json
+ * - Handle form data submissions
+ * - Implement timeout handling
+ * - Propagate network errors appropriately
+ */
+interface HttpClient {
+    /**
+     * Make an HTTP request
+     *
+     * @param url - Full URL to request
+     * @param options - Request options
+     * @returns Promise resolving to the response
+     * @throws Error on network failure or timeout
+     */
+    fetch<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+}
+
+/**
+ * Crypto Provider Interface
+ *
+ * Platform-agnostic cryptographic operations abstraction.
+ * Implementations must be injected - @authrim/core does not use crypto.subtle directly.
+ */
+/**
+ * Crypto Provider interface
+ *
+ * Implementations should:
+ * - Use cryptographically secure random number generation
+ * - Implement SHA-256 using platform-native crypto APIs
+ * - Generate PKCE code verifiers and challenges per RFC 7636
+ */
+interface CryptoProvider {
+    /**
+     * Generate cryptographically secure random bytes
+     *
+     * @param length - Number of bytes to generate
+     * @returns Promise resolving to random bytes
+     */
+    randomBytes(length: number): Promise<Uint8Array>;
+    /**
+     * Compute SHA-256 hash of a string
+     *
+     * @param data - String to hash (UTF-8 encoded)
+     * @returns Promise resolving to hash bytes
+     */
+    sha256(data: string): Promise<Uint8Array>;
+    /**
+     * Generate a PKCE code verifier (RFC 7636)
+     *
+     * Requirements:
+     * - 43-128 characters
+     * - URL-safe characters only: [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
+     * - Recommended: 43 characters of base64url-encoded random bytes
+     *
+     * @returns Promise resolving to code verifier string
+     */
+    generateCodeVerifier(): Promise<string>;
+    /**
+     * Generate a PKCE code challenge from a code verifier (RFC 7636)
+     *
+     * Computes: BASE64URL(SHA256(code_verifier))
+     *
+     * @param verifier - Code verifier string
+     * @returns Promise resolving to code challenge string
+     */
+    generateCodeChallenge(verifier: string): Promise<string>;
+}
+
+/**
+ * Storage Provider Interface
+ *
+ * Platform-agnostic storage abstraction.
+ * Implementations must be injected - @authrim/core does not use localStorage directly.
+ */
+/**
+ * Storage Provider interface
+ *
+ * Implementations:
+ * - Browser: localStorage, sessionStorage, IndexedDB
+ * - React Native: AsyncStorage
+ * - Node.js: Memory, Redis, Database
+ * - Cookie-based: Server-side session storage
+ *
+ * Note: getAll() and clear() are optional. The SDK functions correctly without them,
+ * but providing them enables automatic cleanup of expired state entries.
+ */
+interface AuthrimStorage {
+    /**
+     * Get a value from storage
+     *
+     * @param key - Storage key
+     * @returns Promise resolving to the value, or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a value in storage
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     * @returns Promise resolving when complete
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Remove a value from storage
+     *
+     * @param key - Storage key
+     * @returns Promise resolving when complete
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Get all key-value pairs from storage (optional)
+     *
+     * Used for cleanup of expired state entries.
+     * If not implemented, cleanup operations are skipped (security is not affected).
+     *
+     * @returns Promise resolving to all stored values
+     */
+    getAll?(): Promise<Record<string, string>>;
+    /**
+     * Clear all values from storage (optional)
+     *
+     * Use with caution - clears ALL stored data including tokens.
+     *
+     * @returns Promise resolving when complete
+     */
+    clear?(): Promise<void>;
+}
+
+/**
+ * Client Configuration
+ */
+
+/**
+ * Endpoint overrides
+ */
+interface EndpointOverrides {
+    /** Authorization endpoint */
+    authorization?: string;
+    /** Token endpoint */
+    token?: string;
+    /** UserInfo endpoint */
+    userinfo?: string;
+    /** Revocation endpoint */
+    revocation?: string;
+    /** End session endpoint (null to disable) */
+    endSession?: string | null;
+}
+/**
+ * Hash options for storage key generation
+ */
+interface HashOptions {
+    /**
+     * Hash length for storage keys
+     *
+     * Default: 16 characters (96 bits)
+     * Alternative: 22 characters (132 bits) for lower collision risk
+     */
+    hashLength?: number;
+}
+/**
+ * Authrim Client Configuration
+ */
+interface AuthrimClientConfig {
+    /**
+     * OpenID Connect issuer URL
+     *
+     * This is used to fetch the discovery document and validate tokens.
+     * Trailing slashes are automatically normalized.
+     */
+    issuer: string;
+    /**
+     * OAuth 2.0 client ID
+     */
+    clientId: string;
+    /**
+     * HTTP client implementation
+     *
+     * Required for @authrim/core.
+     * @authrim/web provides a default browser implementation.
+     */
+    http: HttpClient;
+    /**
+     * Crypto provider implementation
+     *
+     * Required for @authrim/core.
+     * @authrim/web provides a default browser implementation.
+     */
+    crypto: CryptoProvider;
+    /**
+     * Storage provider implementation
+     *
+     * Required for @authrim/core.
+     * @authrim/web provides localStorage/sessionStorage implementations.
+     */
+    storage: AuthrimStorage;
+    /**
+     * Default redirect URI for authorization requests
+     */
+    redirectUri?: string;
+    /**
+     * Default scopes to request
+     *
+     * Default: ['openid', 'profile']
+     */
+    scopes?: string[];
+    /**
+     * Manual endpoint overrides
+     *
+     * Use these to override discovery document endpoints.
+     * Set endSession to null to disable logout redirect.
+     */
+    endpoints?: EndpointOverrides;
+    /**
+     * Enable Flow Engine (server-driven UI)
+     *
+     * Default: false
+     * Set to true to enable server-driven UI flows.
+     * Note: Both SDK and server must have Flow Engine enabled for it to work.
+     */
+    flowEngine?: boolean;
+    /**
+     * Discovery cache TTL in milliseconds
+     *
+     * Default: 3600000 (1 hour)
+     */
+    discoveryCacheTtlMs?: number;
+    /**
+     * Token refresh skew in seconds
+     *
+     * Refresh tokens this many seconds before expiration.
+     * Default: 30
+     */
+    refreshSkewSeconds?: number;
+    /**
+     * State/nonce TTL in seconds
+     *
+     * Default: 600 (10 minutes)
+     */
+    stateTtlSeconds?: number;
+    /**
+     * Hash options for storage key generation
+     */
+    hashOptions?: HashOptions;
+}
+/**
+ * Resolved configuration with defaults applied
+ */
+interface ResolvedConfig extends Required<Omit<AuthrimClientConfig, 'endpoints' | 'redirectUri' | 'hashOptions'>> {
+    endpoints?: EndpointOverrides;
+    redirectUri?: string;
+    hashOptions: Required<HashOptions>;
+}
+/**
+ * Apply defaults to configuration
+ */
+declare function resolveConfig(config: AuthrimClientConfig): ResolvedConfig;
+
+/**
+ * OIDC / OAuth 2.0 Types
+ */
+/**
+ * OIDC Discovery Document
+ * https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+interface OIDCDiscoveryDocument {
+    /** Issuer identifier (REQUIRED) */
+    issuer: string;
+    /** Authorization endpoint URL (REQUIRED) */
+    authorization_endpoint: string;
+    /** Token endpoint URL (REQUIRED unless only implicit flow is used) */
+    token_endpoint: string;
+    /** UserInfo endpoint URL (RECOMMENDED) */
+    userinfo_endpoint?: string;
+    /** JWKS URI (REQUIRED) */
+    jwks_uri: string;
+    /** Registration endpoint URL (RECOMMENDED) */
+    registration_endpoint?: string;
+    /** Scopes supported (RECOMMENDED) */
+    scopes_supported?: string[];
+    /** Response types supported (REQUIRED) */
+    response_types_supported: string[];
+    /** Response modes supported (OPTIONAL) */
+    response_modes_supported?: string[];
+    /** Grant types supported (OPTIONAL) */
+    grant_types_supported?: string[];
+    /** ACR values supported (OPTIONAL) */
+    acr_values_supported?: string[];
+    /** Subject types supported (REQUIRED) */
+    subject_types_supported: string[];
+    /** ID Token signing algs supported (REQUIRED) */
+    id_token_signing_alg_values_supported: string[];
+    /** ID Token encryption algs supported (OPTIONAL) */
+    id_token_encryption_alg_values_supported?: string[];
+    /** ID Token encryption enc supported (OPTIONAL) */
+    id_token_encryption_enc_values_supported?: string[];
+    /** UserInfo signing algs supported (OPTIONAL) */
+    userinfo_signing_alg_values_supported?: string[];
+    /** UserInfo encryption algs supported (OPTIONAL) */
+    userinfo_encryption_alg_values_supported?: string[];
+    /** UserInfo encryption enc supported (OPTIONAL) */
+    userinfo_encryption_enc_values_supported?: string[];
+    /** Request object signing algs supported (OPTIONAL) */
+    request_object_signing_alg_values_supported?: string[];
+    /** Request object encryption algs supported (OPTIONAL) */
+    request_object_encryption_alg_values_supported?: string[];
+    /** Request object encryption enc supported (OPTIONAL) */
+    request_object_encryption_enc_values_supported?: string[];
+    /** Token endpoint auth methods supported (OPTIONAL) */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Token endpoint auth signing algs supported (OPTIONAL) */
+    token_endpoint_auth_signing_alg_values_supported?: string[];
+    /** Display values supported (OPTIONAL) */
+    display_values_supported?: string[];
+    /** Claim types supported (OPTIONAL) */
+    claim_types_supported?: string[];
+    /** Claims supported (RECOMMENDED) */
+    claims_supported?: string[];
+    /** Service documentation URL (OPTIONAL) */
+    service_documentation?: string;
+    /** Claims locales supported (OPTIONAL) */
+    claims_locales_supported?: string[];
+    /** UI locales supported (OPTIONAL) */
+    ui_locales_supported?: string[];
+    /** Claims parameter supported (OPTIONAL) */
+    claims_parameter_supported?: boolean;
+    /** Request parameter supported (OPTIONAL) */
+    request_parameter_supported?: boolean;
+    /** Request URI parameter supported (OPTIONAL) */
+    request_uri_parameter_supported?: boolean;
+    /** Require request URI registration (OPTIONAL) */
+    require_request_uri_registration?: boolean;
+    /** OP policy URI (OPTIONAL) */
+    op_policy_uri?: string;
+    /** OP ToS URI (OPTIONAL) */
+    op_tos_uri?: string;
+    /** End session endpoint (OPTIONAL) */
+    end_session_endpoint?: string;
+    /** Revocation endpoint (OPTIONAL) */
+    revocation_endpoint?: string;
+    /** Revocation endpoint auth methods supported (OPTIONAL) */
+    revocation_endpoint_auth_methods_supported?: string[];
+    /** Revocation endpoint auth signing algs supported (OPTIONAL) */
+    revocation_endpoint_auth_signing_alg_values_supported?: string[];
+    /** Introspection endpoint (OPTIONAL) */
+    introspection_endpoint?: string;
+    /** Introspection endpoint auth methods supported (OPTIONAL) */
+    introspection_endpoint_auth_methods_supported?: string[];
+    /** Introspection endpoint auth signing algs supported (OPTIONAL) */
+    introspection_endpoint_auth_signing_alg_values_supported?: string[];
+    /** Code challenge methods supported (OPTIONAL) */
+    code_challenge_methods_supported?: string[];
+    /** Flow Engine support indicator (OPTIONAL, Authrim-specific) */
+    flow_engine_supported?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Standard OIDC claims in ID Token
+ */
+interface IdTokenClaims {
+    /** Issuer Identifier */
+    iss: string;
+    /** Subject Identifier */
+    sub: string;
+    /** Audience */
+    aud: string | string[];
+    /** Expiration time */
+    exp: number;
+    /** Issued at time */
+    iat: number;
+    /** Authentication time */
+    auth_time?: number;
+    /** Nonce */
+    nonce?: string;
+    /** ACR - Authentication Context Class Reference */
+    acr?: string;
+    /** AMR - Authentication Methods References */
+    amr?: string[];
+    /** Authorized party */
+    azp?: string;
+    /** Access token hash */
+    at_hash?: string;
+    /** Code hash */
+    c_hash?: string;
+    /** Session ID */
+    sid?: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: {
+        formatted?: string;
+        street_address?: string;
+        locality?: string;
+        region?: string;
+        postal_code?: string;
+        country?: string;
+    };
+    updated_at?: number;
+    [key: string]: unknown;
+}
+/**
+ * Address claim
+ */
+interface AddressClaim {
+    formatted?: string;
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+}
+/**
+ * Standard OIDC claims (profile, email, phone, address)
+ */
+interface StandardClaims {
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: AddressClaim;
+    updated_at?: number;
+}
+/**
+ * UserInfo response
+ */
+interface UserInfo extends StandardClaims {
+    sub: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Token Types
+ */
+/**
+ * Token set returned from token endpoint
+ *
+ * Note: expiresAt is epoch seconds (not milliseconds)
+ */
+interface TokenSet {
+    /** Access token */
+    accessToken: string;
+    /** Refresh token (if provided) */
+    refreshToken?: string;
+    /** ID token (if openid scope was requested) */
+    idToken?: string;
+    /** Token type (always 'Bearer' for OAuth 2.0) */
+    tokenType: 'Bearer';
+    /**
+     * Token expiration time as epoch seconds
+     *
+     * Calculated from expires_in at token exchange time:
+     * expiresAt = Math.floor(Date.now() / 1000) + expires_in
+     */
+    expiresAt: number;
+    /** Scope granted (may differ from requested scope) */
+    scope?: string;
+}
+/**
+ * Token endpoint response (raw)
+ */
+interface TokenEndpointResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+/**
+ * Alias for TokenEndpointResponse
+ */
+type TokenResponse = TokenEndpointResponse;
+/**
+ * Token exchange request (RFC 8693)
+ */
+interface TokenExchangeRequest {
+    /** The subject token to exchange */
+    subjectToken: string;
+    /** Subject token type (default: access_token) */
+    subjectTokenType?: 'access_token' | 'refresh_token' | 'id_token';
+    /** Target audience for the new token */
+    audience?: string;
+    /** Requested scope for the new token */
+    scope?: string;
+    /** Requested token type (default: access_token) */
+    requestedTokenType?: 'access_token' | 'refresh_token' | 'id_token';
+    /** Actor token (for delegation) */
+    actorToken?: string;
+    /** Actor token type */
+    actorTokenType?: 'access_token' | 'id_token';
+}
+/**
+ * Token exchange response (RFC 8693)
+ *
+ * Extends standard token response with issued_token_type
+ */
+interface TokenExchangeResponse extends TokenEndpointResponse {
+    /** URI of the issued token type */
+    issued_token_type: string;
+}
+/**
+ * Token type URIs (RFC 8693)
+ */
+declare const TOKEN_TYPE_URIS: {
+    readonly access_token: "urn:ietf:params:oauth:token-type:access_token";
+    readonly refresh_token: "urn:ietf:params:oauth:token-type:refresh_token";
+    readonly id_token: "urn:ietf:params:oauth:token-type:id_token";
+};
+/**
+ * Token type URI type
+ */
+type TokenTypeUri = (typeof TOKEN_TYPE_URIS)[keyof typeof TOKEN_TYPE_URIS];
+/**
+ * Token exchange result
+ */
+interface TokenExchangeResult {
+    /** Token set from exchange */
+    tokens: TokenSet;
+    /** Issued token type URI */
+    issuedTokenType: TokenTypeUri | string;
+}
+
+/**
+ * Authrim SDK Error Types
+ */
+/**
+ * User action recommended for error recovery
+ */
+type AuthrimErrorUserAction = 'retry' | 'reauthenticate' | 'contact_support' | 'check_network' | 'none';
+/**
+ * Error severity level
+ */
+type AuthrimErrorSeverity = 'fatal' | 'error' | 'warning';
+/**
+ * Error metadata for recovery information
+ */
+interface AuthrimErrorMeta {
+    /** Whether this is a transient error */
+    transient: boolean;
+    /** Whether automatic retry is possible */
+    retryable: boolean;
+    /** Suggested retry wait time in milliseconds */
+    retryAfterMs?: number;
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Recommended user action */
+    userAction: AuthrimErrorUserAction;
+    /** Error severity level */
+    severity: AuthrimErrorSeverity;
+}
+/**
+ * Error codes used by the SDK
+ */
+type AuthrimErrorCode = 'invalid_request' | 'unauthorized_client' | 'access_denied' | 'unsupported_response_type' | 'invalid_scope' | 'server_error' | 'temporarily_unavailable' | 'invalid_grant' | 'invalid_token' | 'invalid_state' | 'expired_state' | 'invalid_nonce' | 'nonce_mismatch' | 'session_expired' | 'session_check_failed' | 'network_error' | 'timeout_error' | 'discovery_error' | 'discovery_mismatch' | 'configuration_error' | 'storage_error' | 'flow_engine_error' | 'no_tokens' | 'token_expired' | 'token_error' | 'refresh_error' | 'token_exchange_error' | 'oauth_error' | 'missing_code' | 'missing_state' | 'not_initialized' | 'no_discovery' | 'no_userinfo_endpoint' | 'userinfo_error' | 'introspection_error' | 'revocation_error' | 'no_introspection_endpoint' | 'no_revocation_endpoint' | 'login_required' | 'interaction_required' | 'consent_required' | 'account_selection_required';
+/**
+ * Options for creating an AuthrimError
+ */
+interface AuthrimErrorOptions {
+    details?: Record<string, unknown>;
+    errorUri?: string;
+    cause?: Error;
+}
+/**
+ * Authrim SDK Error class
+ */
+declare class AuthrimError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: AuthrimErrorCode;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    /** OAuth error_uri if provided */
+    readonly errorUri?: string;
+    /** Underlying cause */
+    readonly cause?: Error;
+    constructor(code: AuthrimErrorCode, message: string, options?: AuthrimErrorOptions);
+    /**
+     * Create an AuthrimError from an OAuth error response
+     */
+    static fromOAuthError(error: {
+        error: string;
+        error_description?: string;
+        error_uri?: string;
+    }): AuthrimError;
+    /**
+     * Check if an error is retryable (e.g., network errors)
+     */
+    isRetryable(): boolean;
+    /**
+     * Get error metadata for recovery guidance
+     */
+    get meta(): AuthrimErrorMeta;
+}
+/**
+ * Get error metadata for a given error code
+ */
+declare function getErrorMeta(code: AuthrimErrorCode): AuthrimErrorMeta;
+
+/**
+ * Event Types
+ */
+
+/**
+ * Token refresh event data
+ */
+interface TokenRefreshedEvent {
+    tokens: TokenSet;
+}
+/**
+ * Token expired event data
+ */
+interface TokenExpiredEvent {
+    accessToken: string;
+}
+/**
+ * Token error event data
+ */
+interface TokenErrorEvent {
+    error: AuthrimError;
+}
+/**
+ * Token exchanged event data (RFC 8693)
+ */
+interface TokenExchangedEvent {
+    tokens: TokenSet;
+    issuedTokenType: string;
+}
+/**
+ * Session started event data
+ */
+interface SessionStartedEvent {
+    user: UserInfo;
+}
+/**
+ * Session ended event data
+ */
+interface SessionEndedEvent {
+    reason: 'logout' | 'expired' | 'revoked';
+}
+/**
+ * Auth redirecting event data
+ */
+interface AuthRedirectingEvent {
+    url: string;
+}
+/**
+ * Auth callback event data
+ */
+interface AuthCallbackEvent {
+    code: string;
+    state: string;
+}
+/**
+ * Error event data
+ */
+interface ErrorEvent {
+    error: AuthrimError;
+    context: string;
+}
+/**
+ * All Authrim events
+ */
+interface AuthrimEvents {
+    'token:refreshed': TokenRefreshedEvent;
+    'token:expired': TokenExpiredEvent;
+    'token:error': TokenErrorEvent;
+    'token:exchanged': TokenExchangedEvent;
+    'session:started': SessionStartedEvent;
+    'session:ended': SessionEndedEvent;
+    'auth:redirecting': AuthRedirectingEvent;
+    'auth:callback': AuthCallbackEvent;
+    error: ErrorEvent;
+}
+/**
+ * Event names
+ */
+type AuthrimEventName = keyof AuthrimEvents;
+/**
+ * Event handler type
+ */
+type AuthrimEventHandler<T extends AuthrimEventName> = (event: AuthrimEvents[T]) => void;
+
+/**
+ * State/Nonce Manager
+ *
+ * Manages CSRF protection (state) and replay attack prevention (nonce)
+ * for Authorization Code Flow.
+ */
+
+/**
+ * Auth state stored in storage
+ */
+interface AuthState {
+    /** State parameter (CSRF protection) */
+    state: string;
+    /** Nonce parameter (replay attack prevention) */
+    nonce: string;
+    /** PKCE code verifier */
+    codeVerifier: string;
+    /** Redirect URI used for this auth request */
+    redirectUri: string;
+    /** Timestamp when state was created */
+    createdAt: number;
+    /** Timestamp when state expires */
+    expiresAt: number;
+}
+/**
+ * Options for generating auth state
+ */
+interface GenerateAuthStateOptions {
+    /** Redirect URI for this auth request */
+    redirectUri: string;
+    /** Code verifier for PKCE */
+    codeVerifier: string;
+    /** TTL in seconds (default: 600 = 10 minutes) */
+    ttlSeconds?: number;
+}
+/**
+ * Storage keys factory
+ */
+declare const STORAGE_KEYS: {
+    /**
+     * Auth state key (state-specific)
+     */
+    readonly authState: (issuerHash: string, clientIdHash: string, state: string) => string;
+    /**
+     * Token storage key
+     */
+    readonly tokens: (issuerHash: string, clientIdHash: string) => string;
+    /**
+     * ID token storage key
+     */
+    readonly idToken: (issuerHash: string, clientIdHash: string) => string;
+    /**
+     * Auth state prefix for cleanup
+     */
+    readonly authStatePrefix: (issuerHash: string, clientIdHash: string) => string;
+};
+/**
+ * State Manager
+ */
+declare class StateManager {
+    private readonly crypto;
+    private readonly storage;
+    private readonly issuerHash;
+    private readonly clientIdHash;
+    /** Default TTL: 10 minutes */
+    private static readonly DEFAULT_TTL_SECONDS;
+    constructor(crypto: CryptoProvider, storage: AuthrimStorage, issuerHash: string, clientIdHash: string);
+    /**
+     * Generate and store auth state
+     *
+     * Creates state, nonce, stores them with the code verifier.
+     *
+     * @param options - Generation options
+     * @returns Generated state string
+     */
+    generateAuthState(options: GenerateAuthStateOptions): Promise<AuthState>;
+    /**
+     * Validate and consume state
+     *
+     * Retrieves, validates, and ALWAYS deletes the state (success or failure).
+     * This ensures replay attack prevention and GC.
+     *
+     * @param state - State parameter from callback
+     * @returns Auth state if valid
+     * @throws AuthrimError if state is invalid or expired
+     */
+    validateAndConsumeState(state: string): Promise<AuthState>;
+    /**
+     * Clean up expired states
+     *
+     * This is a best-effort cleanup. Only works if storage.getAll() is available.
+     * The primary GC mechanism is validateAndConsumeState()'s finally delete.
+     *
+     * Safe to call at startup or periodically.
+     */
+    cleanupExpiredStates(): Promise<void>;
+}
+
+/**
+ * PKCE (Proof Key for Code Exchange) Helper
+ *
+ * Implements RFC 7636 for Authorization Code Flow security.
+ * https://tools.ietf.org/html/rfc7636
+ */
+
+/**
+ * PKCE challenge method
+ */
+type CodeChallengeMethod = 'S256' | 'plain';
+/**
+ * PKCE pair (verifier and challenge)
+ */
+interface PKCEPair {
+    /** Code verifier (high-entropy random string) */
+    codeVerifier: string;
+    /** Code challenge (derived from verifier) */
+    codeChallenge: string;
+    /** Challenge method used */
+    codeChallengeMethod: CodeChallengeMethod;
+}
+/**
+ * PKCE Helper class
+ */
+declare class PKCEHelper {
+    private readonly crypto;
+    constructor(crypto: CryptoProvider);
+    /**
+     * Generate a PKCE pair (verifier + challenge)
+     *
+     * Uses S256 method (SHA-256 hash, base64url-encoded).
+     *
+     * @returns PKCE pair
+     */
+    generatePKCE(): Promise<PKCEPair>;
+    /**
+     * Generate only the code verifier
+     *
+     * @returns Code verifier string
+     */
+    generateCodeVerifier(): Promise<string>;
+    /**
+     * Generate a code challenge from a verifier
+     *
+     * @param verifier - Code verifier
+     * @returns Code challenge (base64url-encoded SHA-256 hash)
+     */
+    generateCodeChallenge(verifier: string): Promise<string>;
+}
+
+/**
+ * Authorization Code Flow
+ *
+ * Implements OAuth 2.0 Authorization Code Flow with PKCE.
+ * Uses 2-step pattern: buildAuthorizationUrl() + handleCallback()
+ */
+
+/**
+ * Options for building authorization URL
+ */
+interface BuildAuthorizationUrlOptions {
+    /** Redirect URI (required) */
+    redirectUri: string;
+    /** Scopes to request (default: 'openid profile') */
+    scope?: string;
+    /** Prompt behavior */
+    prompt?: 'none' | 'login' | 'consent' | 'select_account';
+    /** Hint about the login identifier */
+    loginHint?: string;
+    /** Requested Authentication Context Class Reference values */
+    acrValues?: string;
+    /** Additional custom parameters */
+    extraParams?: Record<string, string>;
+    /**
+     * Expose state/nonce in result (for SSR/external storage)
+     *
+     * Default: false (security: state/nonce stay internal)
+     * Set to true only when you need to store state externally
+     * (e.g., cookie, server-side session)
+     */
+    exposeState?: boolean;
+}
+/**
+ * Result of buildAuthorizationUrl
+ */
+interface AuthorizationUrlResult {
+    /** Authorization URL to redirect to */
+    url: string;
+    /** State parameter (only if exposeState: true) */
+    state?: string;
+    /** Nonce parameter (only if exposeState: true) */
+    nonce?: string;
+}
+/**
+ * Internal authorization context (stored by StateManager)
+ */
+interface AuthorizationContext {
+    /** Auth state object */
+    authState: AuthState;
+    /** PKCE pair */
+    pkce: PKCEPair;
+}
+/**
+ * Options for exchanging authorization code
+ */
+interface ExchangeCodeOptions {
+    /** Authorization code */
+    code: string;
+    /** State parameter (for validation) */
+    state: string;
+    /** Redirect URI used in authorization request */
+    redirectUri: string;
+    /** Code verifier for PKCE */
+    codeVerifier: string;
+    /** Nonce to validate in ID token */
+    nonce: string;
+}
+/**
+ * Authorization Code Flow helper
+ */
+declare class AuthorizationCodeFlow {
+    private readonly http;
+    private readonly clientId;
+    constructor(http: HttpClient, clientId: string);
+    /**
+     * Build authorization URL
+     *
+     * @param discovery - OIDC discovery document
+     * @param authState - Auth state from StateManager
+     * @param pkce - PKCE pair
+     * @param options - Authorization options
+     * @returns Authorization URL result
+     */
+    buildAuthorizationUrl(discovery: OIDCDiscoveryDocument, authState: AuthState, pkce: PKCEPair, options: BuildAuthorizationUrlOptions): AuthorizationUrlResult;
+    /**
+     * Parse callback URL and extract code/state
+     *
+     * @param callbackUrl - Callback URL or query string
+     * @returns Parsed code and state
+     * @throws AuthrimError if code or state is missing, or if error is present
+     */
+    parseCallback(callbackUrl: string): {
+        code: string;
+        state: string;
+    };
+    /**
+     * Exchange authorization code for tokens
+     *
+     * @param discovery - OIDC discovery document
+     * @param options - Exchange options
+     * @returns Token set
+     * @throws AuthrimError if exchange fails or nonce validation fails
+     */
+    exchangeCode(discovery: OIDCDiscoveryDocument, options: ExchangeCodeOptions): Promise<TokenSet>;
+}
+
+/**
+ * Token Introspection (RFC 7662)
+ *
+ * Implements OAuth 2.0 Token Introspection to validate tokens server-side.
+ * https://datatracker.ietf.org/doc/html/rfc7662
+ */
+
+/**
+ * Token type hint for introspection
+ */
+type IntrospectionTokenTypeHint = 'access_token' | 'refresh_token';
+/**
+ * Token introspection response (RFC 7662)
+ */
+interface IntrospectionResponse {
+    /** Whether the token is active */
+    active: boolean;
+    /** Space-separated list of scopes (if active) */
+    scope?: string;
+    /** Client identifier (if active) */
+    client_id?: string;
+    /** Human-readable username (if active) */
+    username?: string;
+    /** Token type (e.g., "Bearer") */
+    token_type?: string;
+    /** Expiration time (Unix timestamp) */
+    exp?: number;
+    /** Issued at time (Unix timestamp) */
+    iat?: number;
+    /** Not before time (Unix timestamp) */
+    nbf?: number;
+    /** Subject identifier */
+    sub?: string;
+    /** Audience (single string or array) */
+    aud?: string | string[];
+    /** Issuer identifier */
+    iss?: string;
+    /** JWT ID */
+    jti?: string;
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Token introspection options
+ */
+interface IntrospectTokenOptions {
+    /** Token to introspect */
+    token: string;
+    /** Hint about the token type (optional, helps server optimize lookup) */
+    tokenTypeHint?: IntrospectionTokenTypeHint;
+}
+/**
+ * Token introspector options
+ */
+interface TokenIntrospectorOptions {
+    /** HTTP client */
+    http: HttpClient;
+    /** Client ID */
+    clientId: string;
+}
+/**
+ * Token Introspector
+ *
+ * Handles token introspection requests to the authorization server.
+ */
+declare class TokenIntrospector {
+    private readonly http;
+    private readonly clientId;
+    constructor(options: TokenIntrospectorOptions);
+    /**
+     * Introspect a token
+     *
+     * Per RFC 7662, the introspection endpoint returns:
+     * - { active: true, ... } for valid tokens with additional metadata
+     * - { active: false } for invalid, expired, or revoked tokens
+     *
+     * @param discovery - OIDC discovery document
+     * @param options - Introspection options
+     * @returns Introspection response
+     * @throws AuthrimError if introspection endpoint is not available or request fails
+     */
+    introspect(discovery: OIDCDiscoveryDocument, options: IntrospectTokenOptions): Promise<IntrospectionResponse>;
+    /**
+     * Introspect a token directly using the endpoint URL
+     *
+     * Use this when you have the endpoint URL but not the full discovery document.
+     *
+     * @param endpoint - Introspection endpoint URL
+     * @param options - Introspection options
+     * @returns Introspection response
+     * @throws AuthrimError if request fails
+     */
+    introspectWithEndpoint(endpoint: string, options: IntrospectTokenOptions): Promise<IntrospectionResponse>;
+    /**
+     * Check if a token is active
+     *
+     * Convenience method that returns only the active status.
+     *
+     * @param discovery - OIDC discovery document
+     * @param token - Token to check
+     * @returns True if token is active
+     */
+    isActive(discovery: OIDCDiscoveryDocument, token: string): Promise<boolean>;
+}
+
+/**
+ * Token Revocation (RFC 7009)
+ *
+ * Implements OAuth 2.0 Token Revocation to explicitly invalidate tokens.
+ * https://datatracker.ietf.org/doc/html/rfc7009
+ */
+
+/**
+ * Token type hint for revocation
+ */
+type TokenTypeHint = 'access_token' | 'refresh_token';
+/**
+ * Token revocation options
+ */
+interface RevokeTokenOptions {
+    /** Token to revoke */
+    token: string;
+    /** Hint about the token type (optional, helps server optimize lookup) */
+    tokenTypeHint?: TokenTypeHint;
+}
+/**
+ * Token revoker options
+ */
+interface TokenRevokerOptions {
+    /** HTTP client */
+    http: HttpClient;
+    /** Client ID */
+    clientId: string;
+}
+/**
+ * Token Revoker
+ *
+ * Handles token revocation requests to the authorization server.
+ */
+declare class TokenRevoker {
+    private readonly http;
+    private readonly clientId;
+    constructor(options: TokenRevokerOptions);
+    /**
+     * Revoke a token
+     *
+     * Per RFC 7009, the revocation endpoint:
+     * - Returns 200 OK on success (even if token was already invalid)
+     * - Returns 400 for invalid requests
+     * - Returns 503 if temporarily unavailable
+     *
+     * @param discovery - OIDC discovery document
+     * @param options - Revocation options
+     * @throws AuthrimError if revocation endpoint is not available or request fails
+     */
+    revoke(discovery: OIDCDiscoveryDocument, options: RevokeTokenOptions): Promise<void>;
+    /**
+     * Revoke a token directly using the endpoint URL
+     *
+     * Use this when you have the endpoint URL but not the full discovery document.
+     *
+     * @param endpoint - Revocation endpoint URL
+     * @param options - Revocation options
+     * @throws AuthrimError if request fails
+     */
+    revokeWithEndpoint(endpoint: string, options: RevokeTokenOptions): Promise<void>;
+}
+
+/**
+ * Event Emitter
+ *
+ * Simple typed event emitter for SDK events.
+ */
+
+/**
+ * Typed Event Emitter
+ */
+declare class EventEmitter {
+    private listeners;
+    /**
+     * Subscribe to an event
+     *
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    on<T extends AuthrimEventName>(event: T, handler: AuthrimEventHandler<T>): () => void;
+    /**
+     * Subscribe to an event (one-time)
+     *
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    once<T extends AuthrimEventName>(event: T, handler: AuthrimEventHandler<T>): () => void;
+    /**
+     * Unsubscribe from an event
+     *
+     * @param event - Event name
+     * @param handler - Event handler to remove
+     */
+    off<T extends AuthrimEventName>(event: T, handler: AuthrimEventHandler<T>): void;
+    /**
+     * Emit an event
+     *
+     * @param event - Event name
+     * @param data - Event data
+     */
+    emit<T extends AuthrimEventName>(event: T, data: AuthrimEvents[T]): void;
+    /**
+     * Remove all listeners for an event (or all events)
+     *
+     * @param event - Event name (optional, removes all if not specified)
+     */
+    removeAllListeners(event?: AuthrimEventName): void;
+    /**
+     * Get the number of listeners for an event
+     *
+     * @param event - Event name
+     * @returns Number of listeners
+     */
+    listenerCount(event: AuthrimEventName): number;
+}
+
+/**
+ * Logout Handler
+ *
+ * Implements RP-Initiated Logout (OpenID Connect RP-Initiated Logout 1.0)
+ * https://openid.net/specs/openid-connect-rpinitiated-1_0.html
+ */
+
+/**
+ * Logout options
+ */
+interface LogoutOptions {
+    /** URI to redirect to after logout */
+    postLogoutRedirectUri?: string;
+    /** ID token hint (optional, uses stored ID token if not provided) */
+    idTokenHint?: string;
+    /** State parameter for post-logout redirect */
+    state?: string;
+    /** Whether to revoke tokens before logout (requires revocation_endpoint) */
+    revokeTokens?: boolean;
+}
+/**
+ * Logout result
+ */
+interface LogoutResult {
+    /** Logout URL to redirect to (if IdP supports end_session_endpoint) */
+    logoutUrl?: string;
+    /** True if only local logout was performed (IdP doesn't support RP-Initiated Logout) */
+    localOnly: boolean;
+    /** Token revocation result (if revokeTokens was true) */
+    revocation?: {
+        /** Whether revocation was attempted */
+        attempted: boolean;
+        /** Whether access token revocation succeeded */
+        accessTokenRevoked?: boolean;
+        /** Whether refresh token revocation succeeded */
+        refreshTokenRevoked?: boolean;
+        /** Error if revocation failed (logout still proceeds) */
+        error?: Error;
+    };
+}
+/**
+ * Logout handler options
+ */
+interface LogoutHandlerOptions {
+    /** Storage provider */
+    storage: AuthrimStorage;
+    /** HTTP client (for token revocation) */
+    http: HttpClient;
+    /** Client ID */
+    clientId: string;
+    /** Issuer hash for storage keys */
+    issuerHash: string;
+    /** Client ID hash for storage keys */
+    clientIdHash: string;
+    /** Event emitter */
+    eventEmitter?: EventEmitter;
+    /** Endpoint overrides */
+    endpoints?: EndpointOverrides;
+}
+/**
+ * Logout Handler
+ */
+declare class LogoutHandler {
+    private readonly storage;
+    private readonly clientId;
+    private readonly issuerHash;
+    private readonly clientIdHash;
+    private readonly eventEmitter?;
+    private readonly endpoints?;
+    private readonly tokenRevoker;
+    constructor(options: LogoutHandlerOptions);
+    /**
+     * Perform logout
+     *
+     * 1. Optionally revokes tokens at the authorization server (if revokeTokens=true)
+     * 2. Clears local tokens (always)
+     * 3. Emits session:ended event
+     * 4. Builds logout URL if IdP supports end_session_endpoint
+     *
+     * @param discovery - OIDC discovery document
+     * @param options - Logout options
+     * @returns Logout result
+     */
+    logout(discovery: OIDCDiscoveryDocument | null, options?: LogoutOptions): Promise<LogoutResult>;
+    /**
+     * Revoke tokens at the authorization server
+     *
+     * Best-effort: if revocation fails, logout still proceeds
+     *
+     * @param discovery - OIDC discovery document
+     * @param tokens - Tokens to revoke
+     * @returns Revocation result
+     */
+    private revokeTokens;
+    /**
+     * Clear all tokens from storage
+     */
+    private clearTokens;
+    /**
+     * Get stored ID token
+     */
+    private getStoredIdToken;
+    /**
+     * Get stored tokens
+     */
+    private getStoredTokens;
+}
+
+/**
+ * Authrim Client
+ */
+declare class AuthrimClient {
+    /** Resolved configuration */
+    private readonly config;
+    /** Event emitter */
+    private readonly events;
+    /** Discovery client */
+    private readonly discoveryClient;
+    /** PKCE helper */
+    private readonly pkce;
+    /** State manager (initialized in initialize()) */
+    private stateManager;
+    /** Authorization code flow helper */
+    private readonly authCodeFlow;
+    /** Token manager (initialized in initialize()) */
+    private tokenManager;
+    /** Logout handler (initialized in initialize()) */
+    private logoutHandler;
+    /** Session manager (initialized in initialize()) */
+    private sessionManager;
+    /** Token introspector */
+    private tokenIntrospector;
+    /** Token revoker */
+    private tokenRevoker;
+    /** Issuer hash for storage keys */
+    private issuerHash;
+    /** Client ID hash for storage keys */
+    private clientIdHash;
+    /** Normalized issuer URL */
+    private readonly normalizedIssuer;
+    /** Whether the client has been initialized */
+    private initialized;
+    /**
+     * Create a new Authrim client
+     *
+     * @internal Use createAuthrimClient() instead
+     */
+    constructor(config: AuthrimClientConfig);
+    /**
+     * Initialize the client
+     *
+     * @internal Called by createAuthrimClient()
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure client is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Get OIDC discovery document
+     *
+     * @returns Discovery document
+     */
+    discover(): Promise<OIDCDiscoveryDocument>;
+    /**
+     * Build authorization URL
+     *
+     * Generates the URL to redirect the user to for authentication.
+     * Stores state, nonce, and code_verifier in storage.
+     *
+     * @param options - Authorization options
+     * @returns Authorization URL result
+     */
+    buildAuthorizationUrl(options: BuildAuthorizationUrlOptions): Promise<AuthorizationUrlResult>;
+    /**
+     * Handle authorization callback
+     *
+     * Processes the callback URL, validates state/nonce, and exchanges
+     * the authorization code for tokens.
+     *
+     * @param callbackUrl - Callback URL or query string
+     * @returns Token set
+     */
+    handleCallback(callbackUrl: string): Promise<TokenSet>;
+    /**
+     * Token API accessor
+     */
+    get token(): {
+        /**
+         * Get access token (refreshes if needed)
+         */
+        getAccessToken: () => Promise<string>;
+        /**
+         * Get current tokens
+         */
+        getTokens: () => Promise<TokenSet | null>;
+        /**
+         * Get ID token
+         */
+        getIdToken: () => Promise<string | null>;
+        /**
+         * Check if authenticated
+         */
+        isAuthenticated: () => Promise<boolean>;
+        /**
+         * Exchange token (RFC 8693)
+         *
+         * Exchanges a token for a new token with different audience, scope,
+         * or delegation. Useful for:
+         * - Cross-service token acquisition
+         * - Delegation (actor token)
+         * - Scope reduction
+         *
+         * @param request - Token exchange request parameters
+         * @returns Token exchange result
+         */
+        exchange: (request: TokenExchangeRequest) => Promise<TokenExchangeResult>;
+        /**
+         * Introspect a token (RFC 7662)
+         *
+         * Validates a token server-side and returns its metadata.
+         * Useful for resource servers to validate access tokens.
+         *
+         * @param options - Introspection options (token and optional type hint)
+         * @returns Introspection response with token metadata
+         * @throws AuthrimError if introspection endpoint not available or request fails
+         */
+        introspect: (options: IntrospectTokenOptions) => Promise<IntrospectionResponse>;
+        /**
+         * Revoke a token (RFC 7009)
+         *
+         * Explicitly invalidates a token at the authorization server.
+         * Use this when you want to ensure a token can no longer be used.
+         *
+         * @param options - Revocation options (token and optional type hint)
+         * @throws AuthrimError if revocation endpoint not available or request fails
+         */
+        revoke: (options: RevokeTokenOptions) => Promise<void>;
+    };
+    /**
+     * Session API accessor
+     */
+    get session(): {
+        /**
+         * Check if authenticated locally
+         */
+        isAuthenticated: () => Promise<boolean>;
+        /**
+         * Check session with authorization server
+         */
+        check: () => Promise<SessionCheckResult>;
+    };
+    /**
+     * Check if user is authenticated
+     *
+     * @returns True if tokens exist
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Get user information
+     *
+     * @returns User info
+     */
+    getUser(): Promise<UserInfo>;
+    /**
+     * Log out the user
+     *
+     * Clears local tokens and optionally redirects to IdP for logout.
+     *
+     * @param options - Logout options
+     * @returns Logout result
+     */
+    logout(options?: LogoutOptions): Promise<LogoutResult>;
+    /**
+     * Subscribe to an event
+     *
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    on<T extends AuthrimEventName>(event: T, handler: AuthrimEventHandler<T>): () => void;
+    /**
+     * Subscribe to an event (one-time)
+     *
+     * @param event - Event name
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    once<T extends AuthrimEventName>(event: T, handler: AuthrimEventHandler<T>): () => void;
+    /**
+     * Unsubscribe from an event
+     *
+     * @param event - Event name
+     * @param handler - Event handler
+     */
+    off<T extends AuthrimEventName>(event: T, handler: AuthrimEventHandler<T>): void;
+}
+/**
+ * Create an Authrim client
+ *
+ * This is the main entry point for creating a client.
+ * The client is fully initialized when returned.
+ *
+ * @param config - Client configuration
+ * @returns Initialized Authrim client
+ */
+declare function createAuthrimClient(config: AuthrimClientConfig): Promise<AuthrimClient>;
+
+/**
+ * OIDC Discovery Client
+ *
+ * Fetches and caches OIDC Discovery documents from the authorization server.
+ * https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+
+/**
+ * Discovery client options
+ */
+interface DiscoveryClientOptions {
+    /** HTTP client for making requests */
+    http: HttpClient;
+    /** Cache TTL in milliseconds (default: 1 hour) */
+    cacheTtlMs?: number;
+}
+/**
+ * Normalize issuer URL
+ *
+ * Removes trailing slashes to ensure consistent comparison.
+ *
+ * @param issuer - Issuer URL
+ * @returns Normalized issuer URL
+ */
+declare function normalizeIssuer(issuer: string): string;
+/**
+ * OIDC Discovery Client
+ */
+declare class DiscoveryClient {
+    private readonly http;
+    private readonly cacheTtlMs;
+    private readonly cache;
+    /** Default cache TTL: 1 hour */
+    private static readonly DEFAULT_CACHE_TTL_MS;
+    constructor(options: DiscoveryClientOptions);
+    /**
+     * Fetch the OIDC Discovery document for an issuer
+     *
+     * @param issuer - Issuer URL
+     * @returns Discovery document
+     * @throws AuthrimError if discovery fails or issuer mismatch
+     */
+    discover(issuer: string): Promise<OIDCDiscoveryDocument>;
+    /**
+     * Check if a cached document has expired
+     */
+    private isExpired;
+    /**
+     * Clear the discovery cache (useful for testing)
+     */
+    clearCache(): void;
+    /**
+     * Clear a specific issuer from the cache
+     *
+     * @param issuer - Issuer URL to clear
+     */
+    clearIssuer(issuer: string): void;
+}
+
+/**
+ * Silent Authentication (prompt=none)
+ *
+ * Foundation for silent authentication using OIDC prompt=none.
+ * This module provides the core logic for building silent auth requests
+ * and parsing responses. The actual iframe/hidden frame implementation
+ * is platform-specific and should be implemented in @authrim/web or similar.
+ *
+ * Silent authentication allows checking if a user has an active session
+ * with the authorization server without user interaction.
+ */
+
+/**
+ * Silent authentication options
+ */
+interface SilentAuthOptions {
+    /** Redirect URI for silent auth response (often an iframe callback page) */
+    redirectUri: string;
+    /** Scopes to request (default: 'openid') */
+    scope?: string;
+    /** Hint about the login identifier */
+    loginHint?: string;
+    /** ID token hint (helps IdP identify the user) */
+    idTokenHint?: string;
+    /** Additional custom parameters */
+    extraParams?: Record<string, string>;
+    /**
+     * Expose state/nonce in result (for SSR/external storage)
+     *
+     * Default: false (security: state/nonce stay internal)
+     */
+    exposeState?: boolean;
+}
+/**
+ * Result of building silent auth URL
+ */
+interface SilentAuthUrlResult {
+    /** Authorization URL with prompt=none */
+    url: string;
+    /** State parameter (only if exposeState: true) */
+    state?: string;
+    /** Nonce parameter (only if exposeState: true) */
+    nonce?: string;
+}
+/**
+ * Silent authentication result
+ */
+interface SilentAuthResult {
+    /** Whether silent auth succeeded */
+    success: boolean;
+    /** Tokens if successful */
+    tokens?: TokenSet;
+    /** Error if failed (e.g., login_required) */
+    error?: AuthrimError;
+}
+/**
+ * Silent Authentication Handler
+ *
+ * Provides core logic for silent authentication. Platform-specific
+ * implementations (iframe, hidden frame, etc.) should use this class.
+ */
+declare class SilentAuthHandler {
+    private readonly clientId;
+    constructor(clientId: string);
+    /**
+     * Build silent authentication URL
+     *
+     * Creates an authorization URL with prompt=none for silent authentication.
+     *
+     * @param discovery - OIDC discovery document
+     * @param authState - Auth state from StateManager
+     * @param pkce - PKCE pair
+     * @param options - Silent auth options
+     * @returns Silent auth URL result
+     */
+    buildSilentAuthUrl(discovery: OIDCDiscoveryDocument, authState: AuthState, pkce: PKCEPair, options: SilentAuthOptions): SilentAuthUrlResult;
+    /**
+     * Parse silent authentication response URL
+     *
+     * Parses the callback URL from silent authentication and returns
+     * either the authorization code (for token exchange) or an error.
+     *
+     * @param responseUrl - Response URL from silent auth (iframe callback)
+     * @returns Parsed result with code/state or error
+     */
+    parseSilentAuthResponse(responseUrl: string): {
+        success: true;
+        code: string;
+        state: string;
+    } | {
+        success: false;
+        error: AuthrimError;
+    };
+    /**
+     * Check if an error indicates interactive login is required
+     *
+     * @param error - Error to check
+     * @returns True if interactive login is needed
+     */
+    isInteractiveLoginRequired(error: AuthrimError): boolean;
+    /**
+     * Map OAuth error to AuthrimErrorCode
+     */
+    private mapSilentAuthError;
+    /**
+     * Get default error message for silent auth errors
+     */
+    private getDefaultErrorMessage;
+}
+
+/**
+ * Token Manager
+ *
+ * Manages token storage, retrieval, and automatic refresh.
+ * Implements in-flight request coalescing for concurrent refresh requests.
+ */
+
+/**
+ * Token manager options
+ */
+interface TokenManagerOptions {
+    /** HTTP client */
+    http: HttpClient;
+    /** Storage provider */
+    storage: AuthrimStorage;
+    /** Client ID */
+    clientId: string;
+    /** Issuer hash for storage keys */
+    issuerHash: string;
+    /** Client ID hash for storage keys */
+    clientIdHash: string;
+    /** Refresh skew in seconds (default: 30) */
+    refreshSkewSeconds?: number;
+    /** Event emitter for token events */
+    eventEmitter?: EventEmitter;
+}
+/**
+ * Token Manager
+ *
+ * Handles token storage, retrieval, and automatic refresh with
+ * concurrent request coalescing.
+ */
+declare class TokenManager {
+    private readonly http;
+    private readonly storage;
+    private readonly clientId;
+    private readonly issuerHash;
+    private readonly clientIdHash;
+    private readonly refreshSkewSeconds;
+    private readonly eventEmitter?;
+    /** In-flight refresh promise for request coalescing */
+    private refreshPromise;
+    /** Discovery document (set externally) */
+    private discovery;
+    /** Default refresh skew: 30 seconds */
+    private static readonly DEFAULT_REFRESH_SKEW_SECONDS;
+    constructor(options: TokenManagerOptions);
+    /**
+     * Set discovery document
+     */
+    setDiscovery(discovery: OIDCDiscoveryDocument): void;
+    /**
+     * Get storage key for tokens
+     */
+    private get tokenKey();
+    /**
+     * Get storage key for ID token
+     */
+    private get idTokenKey();
+    /**
+     * Get current tokens from storage
+     *
+     * @returns Token set or null if not found
+     */
+    getTokens(): Promise<TokenSet | null>;
+    /**
+     * Save tokens to storage
+     *
+     * @param tokens - Token set to save
+     */
+    saveTokens(tokens: TokenSet): Promise<void>;
+    /**
+     * Clear all tokens from storage
+     */
+    clearTokens(): Promise<void>;
+    /**
+     * Get access token, refreshing if necessary
+     *
+     * This method coalesces concurrent refresh requests - if multiple
+     * calls are made while a refresh is in-flight, they all share the
+     * same refresh operation.
+     *
+     * @returns Access token
+     * @throws AuthrimError if no tokens available or refresh fails
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Get ID token
+     *
+     * @returns ID token or null
+     */
+    getIdToken(): Promise<string | null>;
+    /**
+     * Check if token needs refresh
+     *
+     * @param tokens - Token set to check
+     * @returns True if token should be refreshed
+     */
+    private shouldRefresh;
+    /**
+     * Refresh token with in-flight request coalescing
+     *
+     * If a refresh is already in progress, wait for it instead of
+     * starting a new one.
+     *
+     * @param refreshToken - Refresh token to use
+     * @returns Access token from new token set
+     */
+    private refreshWithLock;
+    /**
+     * Perform refresh with single retry for network errors
+     *
+     * @param refreshToken - Refresh token to use
+     * @param attemptedRetry - Whether retry has been attempted (stack-local)
+     * @returns New token set
+     */
+    private doRefreshWithRetry;
+    /**
+     * Perform the actual token refresh
+     *
+     * @param refreshToken - Refresh token to use
+     * @returns New token set
+     */
+    private doRefresh;
+    /**
+     * Check if error is retryable (network errors only)
+     */
+    private isRetryableError;
+    /**
+     * Check if user is authenticated
+     *
+     * @returns True if valid tokens exist
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Exchange a token using RFC 8693 Token Exchange
+     *
+     * This allows exchanging tokens for different audiences or scopes,
+     * delegation scenarios, and cross-service token acquisition.
+     *
+     * @param request - Token exchange request parameters
+     * @returns Token exchange result with new tokens and issued token type
+     * @throws AuthrimError if exchange fails
+     */
+    exchangeToken(request: TokenExchangeRequest): Promise<TokenExchangeResult>;
+    /**
+     * Map short token type to URI (RFC 8693)
+     */
+    private mapTokenTypeToUri;
+}
+
+/**
+ * Token API Client
+ *
+ * Provides session verification against the authorization server.
+ * Uses the UserInfo endpoint or custom session check endpoint.
+ */
+
+/**
+ * Session check result
+ */
+interface SessionCheckResult {
+    /** Whether session is valid */
+    valid: boolean;
+    /** User info if session is valid */
+    user?: UserInfo;
+    /** Error if session is invalid */
+    error?: AuthrimError;
+}
+/**
+ * Token API client options
+ */
+interface TokenApiClientOptions {
+    /** HTTP client */
+    http: HttpClient;
+}
+/**
+ * Token API Client
+ *
+ * Verifies session status with the authorization server.
+ */
+declare class TokenApiClient {
+    private readonly http;
+    constructor(options: TokenApiClientOptions);
+    /**
+     * Check session validity by calling UserInfo endpoint
+     *
+     * @param discovery - OIDC discovery document
+     * @param accessToken - Access token to verify
+     * @returns Session check result
+     */
+    checkSession(discovery: OIDCDiscoveryDocument, accessToken: string): Promise<SessionCheckResult>;
+    /**
+     * Get user info from the authorization server
+     *
+     * @param discovery - OIDC discovery document
+     * @param accessToken - Access token
+     * @returns User info
+     * @throws AuthrimError if request fails
+     */
+    getUserInfo(discovery: OIDCDiscoveryDocument, accessToken: string): Promise<UserInfo>;
+}
+
+/**
+ * Session Manager
+ *
+ * Coordinates session-related operations including checking
+ * session status and retrieving user information.
+ */
+
+/**
+ * Session manager options
+ */
+interface SessionManagerOptions {
+    /** Token manager */
+    tokenManager: TokenManager;
+    /** Token API client */
+    tokenApiClient: TokenApiClient;
+}
+/**
+ * Session Manager
+ */
+declare class SessionManager {
+    private readonly tokenManager;
+    private readonly tokenApiClient;
+    /** Discovery document */
+    private discovery;
+    constructor(options: SessionManagerOptions);
+    /**
+     * Set discovery document
+     */
+    setDiscovery(discovery: OIDCDiscoveryDocument): void;
+    /**
+     * Check if user is authenticated locally
+     *
+     * This checks if valid tokens exist in storage.
+     * Does not verify with the authorization server.
+     *
+     * @returns True if tokens exist
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Check session validity with authorization server
+     *
+     * Calls the UserInfo endpoint to verify the session is still valid.
+     *
+     * @returns Session check result
+     */
+    checkSession(): Promise<SessionCheckResult>;
+    /**
+     * Get user information
+     *
+     * Fetches user info from the UserInfo endpoint.
+     *
+     * @returns User info
+     * @throws AuthrimError if not authenticated or request fails
+     */
+    getUser(): Promise<UserInfo>;
+}
+
+/**
+ * Base64URL Encoding/Decoding Utilities
+ *
+ * Implements RFC 4648 Section 5 (Base64 URL and Filename Safe Alphabet)
+ */
+/**
+ * Encode a Uint8Array to base64url string
+ *
+ * @param data - Bytes to encode
+ * @returns Base64URL encoded string (no padding)
+ */
+declare function base64urlEncode(data: Uint8Array): string;
+/**
+ * Decode a base64url string to Uint8Array
+ *
+ * @param str - Base64URL encoded string
+ * @returns Decoded bytes
+ */
+declare function base64urlDecode(str: string): Uint8Array;
+/**
+ * Encode a string to base64url
+ *
+ * @param str - String to encode (UTF-8)
+ * @returns Base64URL encoded string
+ */
+declare function stringToBase64url(str: string): string;
+/**
+ * Decode a base64url string to string
+ *
+ * @param base64url - Base64URL encoded string
+ * @returns Decoded string (UTF-8)
+ */
+declare function base64urlToString(base64url: string): string;
+
+/**
+ * JWT Utilities
+ *
+ * Note: This module only provides decoding (parsing) functionality.
+ * JWT signature verification MUST be performed by the server.
+ * Never trust decoded JWT claims without server-side verification.
+ */
+
+/**
+ * JWT Header
+ */
+interface JwtHeader {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [key: string]: unknown;
+}
+/**
+ * Decoded JWT structure
+ */
+interface DecodedJwt<T = Record<string, unknown>> {
+    header: JwtHeader;
+    payload: T;
+    signature: string;
+}
+/**
+ * Decode a JWT without verifying the signature
+ *
+ * WARNING: This function does NOT verify the JWT signature.
+ * Use this only for reading claims after the token has been
+ * validated by the authorization server.
+ *
+ * @param jwt - JWT string to decode
+ * @returns Decoded JWT parts
+ * @throws Error if the JWT format is invalid
+ */
+declare function decodeJwt<T = Record<string, unknown>>(jwt: string): DecodedJwt<T>;
+/**
+ * Decode an ID token and extract claims
+ *
+ * WARNING: This function does NOT verify the ID token.
+ * The token MUST be verified by the authorization server before use.
+ *
+ * @param idToken - ID token string
+ * @returns ID token claims
+ */
+declare function decodeIdToken(idToken: string): IdTokenClaims;
+/**
+ * Check if a JWT is expired
+ *
+ * @param jwt - Decoded JWT payload with exp claim
+ * @param skewSeconds - Clock skew tolerance in seconds (default: 0)
+ * @returns true if expired
+ */
+declare function isJwtExpired(payload: {
+    exp?: number;
+}, skewSeconds?: number): boolean;
+/**
+ * Get the nonce claim from an ID token
+ *
+ * @param idToken - ID token string
+ * @returns nonce value or undefined
+ */
+declare function getIdTokenNonce(idToken: string): string | undefined;
+
+/**
+ * Hash Utilities
+ *
+ * Provides hash calculation utilities for OIDC specifications.
+ */
+
+/**
+ * Calculate ds_hash for Native SSO device_secret verification
+ *
+ * Algorithm: BASE64URL(left half of SHA-256(device_secret))
+ * Reference: OIDC Native SSO 1.0 specification
+ *
+ * This is the same algorithm used for at_hash and c_hash in OIDC Core,
+ * applied to the device_secret value.
+ *
+ * @param deviceSecret - The device_secret value to hash
+ * @param crypto - Platform-specific crypto provider
+ * @returns ds_hash value (BASE64URL encoded)
+ *
+ * @example
+ * ```typescript
+ * const dsHash = await calculateDsHash(deviceSecret, cryptoProvider);
+ * // Compare with id_token.ds_hash claim
+ * if (idToken.ds_hash === dsHash) {
+ *   // device_secret is valid
+ * }
+ * ```
+ */
+declare function calculateDsHash(deviceSecret: string, crypto: CryptoProvider): Promise<string>;
+
+export { type AddressClaim, type AuthCallbackEvent, type AuthRedirectingEvent, type AuthState, AuthorizationCodeFlow, type AuthorizationContext, type AuthorizationUrlResult, AuthrimClient, type AuthrimClientConfig, AuthrimError, type AuthrimErrorCode, type AuthrimErrorMeta, type AuthrimErrorOptions, type AuthrimErrorSeverity, type AuthrimErrorUserAction, type AuthrimEventHandler, type AuthrimEventName, type AuthrimEvents, type AuthrimStorage, type BuildAuthorizationUrlOptions, type CodeChallengeMethod, type CryptoProvider, type DecodedJwt, DiscoveryClient, type EndpointOverrides, type ErrorEvent, EventEmitter, type ExchangeCodeOptions, type GenerateAuthStateOptions, type HashOptions, type HttpClient, type HttpOptions, type HttpResponse, type IntrospectTokenOptions, type IntrospectionResponse, type IntrospectionTokenTypeHint, type JwtHeader, LogoutHandler, type LogoutHandlerOptions, type LogoutOptions, type LogoutResult, type OIDCDiscoveryDocument, PKCEHelper, type PKCEPair, type ResolvedConfig, type RevokeTokenOptions, STORAGE_KEYS, type SessionCheckResult, type SessionEndedEvent, SessionManager, type SessionManagerOptions, type SessionStartedEvent, SilentAuthHandler, type SilentAuthOptions, type SilentAuthResult, type SilentAuthUrlResult, type StandardClaims, StateManager, TOKEN_TYPE_URIS, TokenApiClient, type TokenApiClientOptions, type TokenErrorEvent, type TokenExchangeRequest, type TokenExchangeResponse, type TokenExchangeResult, type TokenExchangedEvent, type TokenExpiredEvent, TokenIntrospector, type TokenIntrospectorOptions, TokenManager, type TokenManagerOptions, type TokenRefreshedEvent, type TokenResponse, TokenRevoker, type TokenRevokerOptions, type TokenSet, type TokenTypeHint, type TokenTypeUri, type UserInfo, base64urlDecode, base64urlEncode, base64urlToString, calculateDsHash, createAuthrimClient, decodeIdToken, decodeJwt, getErrorMeta, getIdTokenNonce, isJwtExpired, normalizeIssuer, resolveConfig, stringToBase64url };