@stdiobus/workers-registry 1.4.14 → 1.5.0-beta.2

package/out/tsc/workers-registry/registry-launcher/src/auth/providers/oidc-provider.d.ts

@@ -0,0 +1,413 @@
+import { BaseAuthProvider } from './base-provider.js';
+import type { TokenResponse } from '../types.js';
+/**
+ * JSON Web Key (JWK) structure for RSA keys.
+ */
+export interface JWK {
+    /** Key type (e.g., 'RSA') */
+    kty: string;
+    /** Key ID - used to match keys in JWKS */
+    kid?: string;
+    /** Algorithm (e.g., 'RS256') */
+    alg?: string;
+    /** Key use (e.g., 'sig' for signature) */
+    use?: string;
+    /** RSA modulus (base64url encoded) */
+    n?: string;
+    /** RSA exponent (base64url encoded) */
+    e?: string;
+    /** X.509 certificate chain */
+    x5c?: string[];
+}
+/**
+ * JSON Web Key Set (JWKS) structure.
+ */
+export interface JWKS {
+    /** Array of JSON Web Keys */
+    keys: JWK[];
+}
+/**
+ * Cached JWKS with metadata.
+ */
+export interface CachedJWKS {
+    /** The JWKS data */
+    jwks: JWKS;
+    /** Timestamp when the JWKS was fetched */
+    fetchedAt: number;
+    /** TTL in milliseconds */
+    ttlMs: number;
+}
+/**
+ * Decoded JWT header.
+ */
+export interface JWTHeader {
+    /** Algorithm used for signing */
+    alg: string;
+    /** Token type (usually 'JWT') */
+    typ?: string;
+    /** Key ID - used to find the signing key in JWKS */
+    kid?: string;
+}
+/**
+ * ID Token claims structure.
+ * Requirements: 7a.5
+ */
+export interface IDTokenClaims {
+    /** Issuer - must match the configured issuer */
+    iss: string;
+    /** Subject - unique identifier for the user */
+    sub: string;
+    /** Audience - must contain the client_id */
+    aud: string | string[];
+    /** Expiration time (Unix timestamp) */
+    exp: number;
+    /** Issued at time (Unix timestamp) */
+    iat: number;
+    /** Nonce - if provided in auth request, must match */
+    nonce?: string;
+    /** Authentication time */
+    auth_time?: number;
+    /** Access token hash */
+    at_hash?: string;
+    /** Additional claims */
+    [key: string]: unknown;
+}
+/**
+ * Result of ID token validation.
+ */
+export interface IDTokenValidationResult {
+    /** Whether validation was successful */
+    valid: boolean;
+    /** The decoded claims if valid */
+    claims?: IDTokenClaims;
+    /** Error message if validation failed */
+    error?: string;
+}
+/**
+ * Options for ID token validation.
+ */
+export interface IDTokenValidationOptions {
+    /** Expected audience (client_id) */
+    audience: string;
+    /** Expected nonce (if used in auth request) */
+    nonce?: string;
+    /** Clock skew tolerance in seconds (default: 60) */
+    clockSkewSeconds?: number;
+}
+/**
+ * OIDC Discovery document structure.
+ * Contains the endpoints and capabilities advertised by the OIDC provider.
+ */
+export interface OIDCDiscoveryDocument {
+    /** The issuer identifier (must match the issuer URL) */
+    issuer: string;
+    /** URL of the authorization endpoint */
+    authorization_endpoint: string;
+    /** URL of the token endpoint */
+    token_endpoint: string;
+    /** URL of the JWKS endpoint for token validation */
+    jwks_uri?: string;
+    /** URL of the userinfo endpoint */
+    userinfo_endpoint?: string;
+    /** Supported response types */
+    response_types_supported?: string[];
+    /** Supported grant types */
+    grant_types_supported?: string[];
+    /** Supported scopes */
+    scopes_supported?: string[];
+    /** Supported token endpoint authentication methods */
+    token_endpoint_auth_methods_supported?: string[];
+    /** Supported code challenge methods for PKCE */
+    code_challenge_methods_supported?: string[];
+}
+/**
+ * Configuration options for OIDC provider.
+ */
+export interface OIDCProviderConfig {
+    /**
+     * The OIDC issuer URL (e.g., 'https://auth.example.com').
+     * Used for discovery via {issuer}/.well-known/openid-configuration.
+     */
+    issuer: string;
+    /**
+     * Manual override for authorization endpoint.
+     * Used when discovery is unavailable.
+     * Requirements: 7a.2
+     */
+    authorizationEndpoint?: string;
+    /**
+     * Manual override for token endpoint.
+     * Used when discovery is unavailable.
+     * Requirements: 7a.2
+     */
+    tokenEndpoint?: string;
+    /**
+     * Manual override for JWKS URI.
+     * Used for token validation when discovery is unavailable.
+     */
+    jwksUri?: string;
+    /** OAuth client ID */
+    clientId?: string;
+    /** OAuth client secret (optional, for confidential clients) */
+    clientSecret?: string;
+    /**
+     * Token endpoint authentication method.
+     * Supported: 'client_secret_post', 'client_secret_basic'
+     * Default: 'client_secret_post'
+     * Requirements: 7a.7
+     */
+    tokenEndpointAuthMethod?: 'client_secret_post' | 'client_secret_basic';
+    /**
+     * Custom scopes to use instead of defaults.
+     * Default: ['openid', 'profile']
+     */
+    scopes?: string[];
+    /**
+     * Whether to skip discovery and use manual endpoints only.
+     * Default: false (discovery is attempted first)
+     */
+    skipDiscovery?: boolean;
+    /**
+     * Timeout for discovery request in milliseconds.
+     * Default: 10000 (10 seconds)
+     */
+    discoveryTimeoutMs?: number;
+}
+/**
+ * Result of OIDC discovery operation.
+ */
+export interface OIDCDiscoveryResult {
+    /** Whether discovery was successful */
+    success: boolean;
+    /** The discovery document if successful */
+    document?: OIDCDiscoveryDocument;
+    /** Error message if discovery failed */
+    error?: string;
+}
+/**
+ * Generic OIDC Discovery provider.
+ *
+ * Supports any OIDC-compliant provider (Auth0, Okta, Keycloak, etc.)
+ * via issuer-based discovery with manual endpoint override fallback.
+ *
+ * Features:
+ * - Automatic discovery via .well-known/openid-configuration
+ * - Manual endpoint override when discovery unavailable
+ * - PKCE S256 enforcement (per Requirement 7a.3)
+ * - Cached discovery document
+ * - Support for client_secret_post and client_secret_basic auth methods
+ *
+ * Default scopes: openid, profile
+ * Token injection: Bearer header
+ *
+ * Requirements: 7a.1, 7a.2, 7a.3, 7a.7
+ */
+export declare class OIDCProvider extends BaseAuthProvider {
+    private readonly issuer;
+    private readonly tokenEndpointAuthMethod;
+    private readonly discoveryTimeoutMs;
+    private readonly skipDiscovery;
+    private readonly manualJwksUri?;
+    /** Discovered authorization endpoint (overrides base class endpoint after discovery) */
+    private discoveredAuthorizationEndpoint?;
+    /** Discovered token endpoint (overrides base class endpoint after discovery) */
+    private discoveredTokenEndpoint?;
+    /** Cached discovery document */
+    private discoveryDocument?;
+    /** Whether discovery has been attempted */
+    private discoveryAttempted;
+    /** Cached JWKS for token validation */
+    private cachedJWKS?;
+    /** Default timeout for discovery requests (10 seconds) */
+    private static readonly DEFAULT_DISCOVERY_TIMEOUT_MS;
+    /** Default JWKS cache TTL (1 hour) */
+    private static readonly DEFAULT_JWKS_CACHE_TTL_MS;
+    /** Default clock skew tolerance for token validation (60 seconds) */
+    private static readonly DEFAULT_CLOCK_SKEW_SECONDS;
+    constructor(config: OIDCProviderConfig);
+    /**
+     * Validate the issuer URL.
+     * @param issuer - The issuer URL to validate
+     * @throws Error if issuer is invalid
+     */
+    private static validateIssuer;
+    /**
+     * Validate an endpoint URL.
+     * @param endpoint - The endpoint URL to validate
+     * @param name - The name of the endpoint for error messages
+     * @throws Error if endpoint is invalid
+     */
+    private static validateEndpoint;
+    /**
+     * Get the issuer URL.
+     * @returns The issuer URL
+     */
+    getIssuer(): string;
+    /**
+     * Get the JWKS URI for token validation.
+     * Returns the discovered or manually configured JWKS URI.
+     * @returns The JWKS URI or undefined if not available
+     */
+    getJwksUri(): string | undefined;
+    /**
+     * Get the cached discovery document.
+     * @returns The discovery document or undefined if not discovered
+     */
+    getDiscoveryDocument(): OIDCDiscoveryDocument | undefined;
+    /**
+     * Check if discovery has been performed.
+     * @returns True if discovery was attempted
+     */
+    isDiscoveryAttempted(): boolean;
+    /**
+     * Get the effective authorization endpoint.
+     * Returns discovered endpoint if available, otherwise the initial endpoint.
+     * @returns The authorization endpoint URL
+     */
+    getAuthorizationEndpoint(): string;
+    /**
+     * Get the effective token endpoint.
+     * Returns discovered endpoint if available, otherwise the initial endpoint.
+     * @returns The token endpoint URL
+     */
+    getTokenEndpoint(): string;
+    /**
+     * Perform OIDC discovery by fetching the .well-known/openid-configuration.
+     *
+     * This method fetches and parses the discovery document, updating the
+     * provider's endpoints if successful.
+     *
+     * Requirements: 7a.1
+     *
+     * @returns The discovery result
+     */
+    discover(): Promise<OIDCDiscoveryResult>;
+    /**
+     * Validate the discovery document.
+     * @param document - The discovery document to validate
+     * @returns Error message if invalid, undefined if valid
+     */
+    private validateDiscoveryDocument;
+    /**
+     * Ensure discovery has been performed before operations that need endpoints.
+     * If discovery hasn't been attempted and manual endpoints weren't provided,
+     * this will perform discovery.
+     */
+    ensureDiscovered(): Promise<void>;
+    /**
+     * Exchange authorization code for tokens.
+     *
+     * Overrides base implementation to support different token endpoint
+     * authentication methods (client_secret_post, client_secret_basic).
+     *
+     * Requirements: 7a.7
+     *
+     * @param code - The authorization code from the callback
+     * @param codeVerifier - The PKCE code verifier
+     * @param redirectUri - The redirect URI used in the authorization request
+     * @returns The token response
+     */
+    exchangeCode(code: string, codeVerifier: string, redirectUri: string): Promise<TokenResponse>;
+    /**
+     * Refresh an access token using a refresh token.
+     *
+     * Overrides base implementation to support different token endpoint
+     * authentication methods.
+     *
+     * @param refreshToken - The refresh token
+     * @returns The new token response
+     */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /**
+     * Fetch JWKS from the jwks_uri endpoint.
+     *
+     * Requirements: 7a.6
+     *
+     * @param forceRefresh - If true, bypasses cache and fetches fresh JWKS
+     * @returns The JWKS or null if unavailable
+     */
+    fetchJWKS(forceRefresh?: boolean): Promise<JWKS | null>;
+    /**
+     * Find a key in the JWKS by key ID (kid).
+     *
+     * If the key is not found in the cache, attempts to refresh the JWKS
+     * to handle key rotation.
+     *
+     * Requirements: 7a.6 (key rotation handling)
+     *
+     * @param kid - The key ID to find
+     * @returns The JWK or null if not found
+     */
+    findKey(kid: string): Promise<JWK | null>;
+    /**
+     * Clear the JWKS cache.
+     * Useful for testing or when key rotation is detected.
+     */
+    clearJWKSCache(): void;
+    /**
+     * Get the cached JWKS if available.
+     * @returns The cached JWKS or undefined
+     */
+    getCachedJWKS(): CachedJWKS | undefined;
+    /**
+     * Validate an ID token.
+     *
+     * Validates the following claims per OIDC Core spec:
+     * - iss: Must match the configured issuer
+     * - aud: Must contain the client_id
+     * - exp: Must not be expired
+     * - iat: Must be present and reasonable
+     *
+     * Also validates the JWT signature using JWKS.
+     *
+     * Requirements: 7a.5, 7a.6
+     *
+     * @param idToken - The ID token to validate
+     * @param options - Validation options
+     * @returns The validation result
+     */
+    validateIdToken(idToken: string, options: IDTokenValidationOptions): Promise<IDTokenValidationResult>;
+    /**
+     * Validate the JWT signature using JWKS.
+     *
+     * Requirements: 7a.6
+     *
+     * @param headerB64 - Base64url encoded header
+     * @param payloadB64 - Base64url encoded payload
+     * @param signatureB64 - Base64url encoded signature
+     * @param header - Decoded JWT header
+     * @returns True if signature is valid
+     */
+    private validateJWTSignature;
+    /**
+     * Validate ID token claims.
+     *
+     * Requirements: 7a.5
+     *
+     * @param claims - The decoded claims
+     * @param options - Validation options
+     * @returns The validation result
+     */
+    private validateIDTokenClaims;
+    /**
+     * Decode a base64url encoded string to UTF-8.
+     *
+     * @param input - Base64url encoded string
+     * @returns Decoded UTF-8 string
+     */
+    private static base64UrlDecode;
+    /**
+     * Convert a base64url encoded string to a Buffer.
+     *
+     * @param input - Base64url encoded string
+     * @returns Buffer
+     */
+    private static base64UrlToBuffer;
+    /**
+     * Convert a JWK RSA public key to PEM format.
+     *
+     * @param jwk - The JWK to convert
+     * @returns PEM formatted public key
+     */
+    private static jwkToPem;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/providers/oidc-provider.property.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/providers/oidc-provider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/providers/providers.property.test.d.ts

@@ -0,0 +1 @@
+export {};

package/out/tsc/workers-registry/registry-launcher/src/auth/providers/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Provider interface definitions.
+ *
+ * @module providers/types
+ */
+import type { AuthProviderId, AuthorizationParams, TokenResponse, TokenInjectionMethod } from '../types.js';
+/**
+ * OAuth 2.1 provider interface.
+ * Each provider implements this interface with provider-specific configuration.
+ */
+export interface IAuthProvider {
+    /** Unique provider identifier */
+    readonly id: AuthProviderId;
+    /** Human-readable provider name */
+    readonly name: string;
+    /** Provider-specific default scopes */
+    readonly defaultScopes: readonly string[];
+    /** Build the authorization URL for the OAuth flow */
+    buildAuthorizationUrl(params: AuthorizationParams): string;
+    /** Exchange authorization code for tokens */
+    exchangeCode(code: string, codeVerifier: string, redirectUri: string): Promise<TokenResponse>;
+    /** Refresh an access token using a refresh token */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /** Validate provider configuration */
+    validateConfig(): void;
+    /** Get token injection method for agent requests */
+    getTokenInjection(): TokenInjectionMethod;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/session.d.ts

@@ -0,0 +1,251 @@
+import type { AuthProviderId } from './types.js';
+/**
+ * Represents an in-progress OAuth authorization flow.
+ */
+export interface IAuthSession {
+    /** Unique session identifier */
+    readonly sessionId: string;
+    /** Provider being authenticated */
+    readonly providerId: AuthProviderId;
+    /** PKCE code verifier (kept secret) */
+    readonly codeVerifier: string;
+    /** PKCE code challenge (sent to provider) */
+    readonly codeChallenge: string;
+    /** State parameter for CSRF protection */
+    readonly state: string;
+    /** Session start timestamp */
+    readonly startedAt: number;
+    /** Session timeout in milliseconds */
+    readonly timeoutMs: number;
+    /** Check if session has expired */
+    isExpired(): boolean;
+    /** Get remaining time in milliseconds */
+    remainingTime(): number;
+    /** Validate returned state parameter */
+    validateState(returnedState: string): boolean;
+}
+/**
+ * Default session timeout in milliseconds (5 minutes).
+ */
+export declare const DEFAULT_SESSION_TIMEOUT_MS: number;
+/**
+ * Maximum allowed session timeout in milliseconds (1 hour).
+ */
+export declare const MAX_SESSION_TIMEOUT_MS: number;
+/**
+ * Validate and normalize a timeout value.
+ *
+ * Ensures the timeout is a finite positive number within allowed bounds.
+ * Returns the default timeout for invalid values (NaN, Infinity, negative, zero).
+ *
+ * @param timeoutMs - The timeout value to validate
+ * @returns A valid timeout value within bounds
+ */
+export declare function validateTimeout(timeoutMs: number): number;
+/**
+ * Represents an in-progress OAuth authorization flow.
+ *
+ * Implements the IAuthSession interface from the design document.
+ * Tracks all PKCE and state parameters needed for a secure OAuth 2.1 flow.
+ */
+export declare class AuthSession implements IAuthSession {
+    /** Unique session identifier */
+    readonly sessionId: string;
+    /** Provider being authenticated */
+    readonly providerId: AuthProviderId;
+    /** PKCE code verifier (kept secret) */
+    readonly codeVerifier: string;
+    /** PKCE code challenge (sent to provider) */
+    readonly codeChallenge: string;
+    /** State parameter for CSRF protection */
+    readonly state: string;
+    /** Session start timestamp (Unix milliseconds) */
+    readonly startedAt: number;
+    /** Session timeout in milliseconds */
+    readonly timeoutMs: number;
+    /**
+     * Create a new auth session.
+     *
+     * @param providerId - The OAuth provider being authenticated
+     * @param codeVerifier - PKCE code verifier (kept secret)
+     * @param codeChallenge - PKCE code challenge (sent to provider)
+     * @param state - State parameter for CSRF protection
+     * @param timeoutMs - Session timeout in milliseconds (default: 5 minutes)
+     */
+    constructor(providerId: AuthProviderId, codeVerifier: string, codeChallenge: string, state: string, timeoutMs?: number);
+    /**
+     * Check if the session has expired.
+     *
+     * A session is expired if the current time exceeds startedAt + timeoutMs.
+     *
+     * @returns True if the session has expired, false otherwise
+     */
+    isExpired(): boolean;
+    /**
+     * Get the remaining time until session expiration.
+     *
+     * Returns the number of milliseconds until the session expires.
+     * Returns 0 if the session has already expired.
+     *
+     * @returns Remaining time in milliseconds (0 if expired)
+     */
+    remainingTime(): number;
+    /**
+     * Validate a returned state parameter against this session's state.
+     *
+     * Uses constant-time comparison via the validateState function
+     * to prevent timing attacks.
+     *
+     * @param returnedState - The state parameter from the OAuth callback
+     * @returns True if the state matches, false otherwise
+     */
+    validateState(returnedState: string): boolean;
+}
+/**
+ * Factory function to create a new auth session.
+ *
+ * Generates PKCE parameters and state, then creates a new AuthSession.
+ * This is a convenience function that handles all the cryptographic
+ * parameter generation.
+ *
+ * @param providerId - The OAuth provider to authenticate with
+ * @param timeoutMs - Session timeout in milliseconds (default: 5 minutes)
+ * @returns A new AuthSession with generated PKCE and state parameters
+ */
+export declare function createSession(providerId: AuthProviderId, timeoutMs?: number): AuthSession;
+/**
+ * Session manager for tracking and cleaning up OAuth authorization sessions.
+ *
+ * Provides centralized management of active auth sessions including:
+ * - Session storage and retrieval by session ID or state parameter
+ * - Automatic cleanup of expired sessions
+ * - Session lifecycle management (create, get, remove, list)
+ *
+ * The manager uses a configurable cleanup interval to periodically remove
+ * expired sessions, preventing memory leaks in long-running processes.
+ */
+export declare class SessionManager {
+    private readonly cleanupIntervalMs;
+    /** Map of session ID to AuthSession */
+    private readonly sessions;
+    /** Map of state parameter to session ID for quick lookup */
+    private readonly stateToSessionId;
+    /** Cleanup interval timer reference */
+    private cleanupTimer;
+    /** Default cleanup interval in milliseconds (1 minute) */
+    static readonly DEFAULT_CLEANUP_INTERVAL_MS: number;
+    /**
+     * Create a new SessionManager.
+     *
+     * @param cleanupIntervalMs - Interval for automatic cleanup (default: 1 minute)
+     * @param autoStartCleanup - Whether to start automatic cleanup immediately (default: true)
+     */
+    constructor(cleanupIntervalMs?: number, autoStartCleanup?: boolean);
+    /**
+     * Create and register a new auth session.
+     *
+     * Generates PKCE parameters and state, creates a new AuthSession,
+     * and registers it with the manager for tracking.
+     *
+     * @param providerId - The OAuth provider to authenticate with
+     * @param timeoutMs - Session timeout in milliseconds (default: 5 minutes)
+     * @returns The newly created and registered AuthSession
+     */
+    create(providerId: AuthProviderId, timeoutMs?: number): AuthSession;
+    /**
+     * Get a session by its session ID.
+     *
+     * @param sessionId - The unique session identifier
+     * @returns The session if found and not expired, undefined otherwise
+     */
+    get(sessionId: string): AuthSession | undefined;
+    /**
+     * Get a session by its state parameter.
+     *
+     * Useful for looking up sessions during OAuth callback handling.
+     *
+     * @param state - The state parameter from the OAuth callback
+     * @returns The session if found and not expired, undefined otherwise
+     */
+    getByState(state: string): AuthSession | undefined;
+    /**
+     * Remove a session by its session ID.
+     *
+     * Cleans up both the session and its state parameter mapping.
+     *
+     * @param sessionId - The unique session identifier
+     * @returns True if the session was removed, false if it didn't exist
+     */
+    remove(sessionId: string): boolean;
+    /**
+     * Remove a session by its state parameter.
+     *
+     * @param state - The state parameter
+     * @returns True if the session was removed, false if it didn't exist
+     */
+    removeByState(state: string): boolean;
+    /**
+     * List all active (non-expired) sessions.
+     *
+     * This method also performs cleanup of any expired sessions found.
+     *
+     * @returns Array of active AuthSession objects
+     */
+    list(): AuthSession[];
+    /**
+     * Get the count of active sessions.
+     *
+     * Note: This may include sessions that have expired but not yet been cleaned up.
+     * Use list().length for an accurate count of non-expired sessions.
+     *
+     * @returns The number of tracked sessions
+     */
+    size(): number;
+    /**
+     * Check if a session exists by session ID.
+     *
+     * @param sessionId - The unique session identifier
+     * @returns True if the session exists and is not expired
+     */
+    has(sessionId: string): boolean;
+    /**
+     * Check if a session exists by state parameter.
+     *
+     * @param state - The state parameter
+     * @returns True if a session with this state exists and is not expired
+     */
+    hasByState(state: string): boolean;
+    /**
+     * Remove all expired sessions.
+     *
+     * This is called automatically by the cleanup timer, but can also
+     * be called manually to force immediate cleanup.
+     *
+     * @returns The number of expired sessions that were removed
+     */
+    cleanup(): number;
+    /**
+     * Start the automatic cleanup timer.
+     *
+     * If cleanup is already running, this method does nothing.
+     */
+    startCleanup(): void;
+    /**
+     * Stop the automatic cleanup timer.
+     *
+     * Call this method when shutting down to clean up resources.
+     */
+    stopCleanup(): void;
+    /**
+     * Clear all sessions and stop cleanup.
+     *
+     * Use this for cleanup during shutdown or testing.
+     */
+    clear(): void;
+    /**
+     * Check if automatic cleanup is running.
+     *
+     * @returns True if the cleanup timer is active
+     */
+    isCleanupRunning(): boolean;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/session.property.test.d.ts

@@ -0,0 +1 @@
+export {};