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

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

@@ -0,0 +1,190 @@
+/**
+ * Error handling module for OAuth 2.1 authentication.
+ *
+ * Provides error classes for each AuthErrorCode, provider error response parsing,
+ * and error response formatting that excludes sensitive data.
+ *
+ * Requirements: 13.1, 13.2, 13.3, 13.4, 13.5
+ *
+ * @module errors
+ */
+import type { AuthErrorCode, AuthError, AuthProviderId } from './types.js';
+/**
+ * Redact sensitive data from a string.
+ *
+ * @param text - The text to redact
+ * @returns The text with sensitive data replaced with [REDACTED]
+ */
+export declare function redactSensitiveData(text: string): string;
+/**
+ * Base error class for authentication errors.
+ *
+ * Provides a structured error with code, message, and optional details.
+ * Ensures sensitive data is never included in error messages.
+ */
+export declare class AuthenticationError extends Error {
+    readonly code: AuthErrorCode;
+    readonly details?: Record<string, unknown>;
+    /**
+     * Create a new AuthenticationError.
+     *
+     * @param code - The error code
+     * @param message - The error message (will be redacted for sensitive data)
+     * @param details - Optional additional details (will be sanitized)
+     */
+    constructor(code: AuthErrorCode, message: string, details?: Record<string, unknown>);
+    /**
+     * Convert to AuthError interface.
+     */
+    toAuthError(): AuthError;
+}
+/**
+ * Error thrown when state parameter validation fails.
+ *
+ * Requirement 13.1: Parse error and return descriptive message
+ */
+export declare class InvalidStateError extends AuthenticationError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when an operation times out.
+ *
+ * Requirement 13.1: Parse error and return descriptive message
+ */
+export declare class TimeoutError extends AuthenticationError {
+    constructor(message?: string, details?: {
+        timeoutMs?: number;
+    });
+}
+/**
+ * Error thrown when a network error occurs.
+ *
+ * Requirement 13.2: Return error indicating network failure and affected endpoint
+ */
+export declare class NetworkError extends AuthenticationError {
+    constructor(message: string, endpoint?: string);
+}
+/**
+ * Error thrown when credentials are invalid.
+ *
+ * Requirement 13.1: Parse error and return descriptive message
+ */
+export declare class InvalidCredentialsError extends AuthenticationError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when credential storage fails.
+ *
+ * Requirement 13.3: Return error indicating storage backend and failure reason
+ */
+export declare class StorageError extends AuthenticationError {
+    constructor(message: string, backend?: string);
+}
+/**
+ * Error thrown when an OAuth provider returns an error.
+ *
+ * Requirement 13.1: Parse error and return descriptive message including error code and description
+ */
+export declare class ProviderError extends AuthenticationError {
+    constructor(message: string, details?: {
+        errorCode?: string;
+        errorDescription?: string;
+        providerId?: AuthProviderId;
+    });
+}
+/**
+ * Error thrown when an unsupported provider is specified.
+ *
+ * Requirement 13.4: Return error listing supported providers
+ */
+export declare class UnsupportedProviderError extends AuthenticationError {
+    constructor(providerId: string);
+}
+/**
+ * Error thrown when the callback server encounters an error.
+ *
+ * Requirement 13.1: Parse error and return descriptive message
+ */
+export declare class CallbackError extends AuthenticationError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Error thrown when token refresh fails.
+ *
+ * Requirement 13.1: Parse error and return descriptive message
+ */
+export declare class TokenRefreshError extends AuthenticationError {
+    constructor(message?: string, providerId?: AuthProviderId);
+}
+/**
+ * Standard OAuth 2.0 error response structure.
+ */
+export interface OAuthErrorResponse {
+    error: string;
+    error_description?: string;
+    error_uri?: string;
+}
+/**
+ * Check if an object is an OAuth error response.
+ *
+ * @param obj - The object to check
+ * @returns True if the object is an OAuth error response
+ */
+export declare function isOAuthErrorResponse(obj: unknown): obj is OAuthErrorResponse;
+/**
+ * Parse an OAuth provider error response into an AuthError.
+ *
+ * Requirement 13.1: Parse error and return descriptive message including error code and description
+ *
+ * @param response - The error response from the provider
+ * @param providerId - The provider that returned the error
+ * @returns A structured AuthError
+ */
+export declare function parseProviderErrorResponse(response: unknown, providerId?: AuthProviderId): AuthError;
+/**
+ * Parse an HTTP error response from a provider.
+ *
+ * @param status - The HTTP status code
+ * @param body - The response body (string or object)
+ * @param providerId - The provider that returned the error
+ * @returns A structured AuthError
+ */
+export declare function parseHttpErrorResponse(status: number, body: unknown, providerId?: AuthProviderId): AuthError;
+/**
+ * Format an error for response, ensuring no sensitive data is exposed.
+ *
+ * Requirement 13.5: Never include sensitive information in error messages
+ *
+ * @param error - The error to format
+ * @returns A formatted AuthError safe for response
+ */
+export declare function formatErrorResponse(error: unknown): AuthError;
+/**
+ * Create an error for an unsupported provider.
+ *
+ * Requirement 13.4: Return error listing supported providers
+ *
+ * @param providerId - The unsupported provider ID
+ * @returns An AuthError with supported providers listed
+ */
+export declare function createUnsupportedProviderError(providerId: string): AuthError;
+/**
+ * Create an error for a network failure.
+ *
+ * Requirement 13.2: Return error indicating network failure and affected endpoint
+ *
+ * @param message - The error message
+ * @param endpoint - The affected endpoint
+ * @returns An AuthError with endpoint information
+ */
+export declare function createNetworkError(message: string, endpoint?: string): AuthError;
+/**
+ * Create an error for storage failure.
+ *
+ * Requirement 13.3: Return error indicating storage backend and failure reason
+ *
+ * @param message - The error message
+ * @param backend - The storage backend that failed
+ * @returns An AuthError with backend information
+ */
+export declare function createStorageError(message: string, backend?: string): AuthError;

package/out/tsc/workers-registry/registry-launcher/src/auth/flows/agent-auth-flow.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Browser-based OAuth 2.1 Authorization Code flow with PKCE.
+ *
+ * Orchestrates the complete agent authentication flow:
+ * 1. Generate PKCE code verifier and challenge
+ * 2. Generate state parameter for CSRF protection
+ * 3. Start the callback server on loopback address
+ * 4. Build the authorization URL with all required parameters
+ * 5. Launch the system default browser to the authorization URL
+ * 6. Wait for the callback with the authorization code
+ * 7. Validate the state parameter
+ * 8. Exchange the authorization code for tokens
+ * 9. Return the authentication result
+ *
+ * Requirements: 3.1, 3.2, 3.3, 3.4
+ *
+ * @module flows/agent-auth-flow
+ */
+import type { AuthProviderId, AuthResult, AgentAuthOptions, TokenResponse } from '../types.js';
+import type { IAuthProvider } from '../providers/types.js';
+/**
+ * Default timeout for the agent auth flow in milliseconds (5 minutes).
+ */
+export declare const DEFAULT_AUTH_TIMEOUT_MS: number;
+/**
+ * Detect if the current environment is headless (no display/browser available).
+ *
+ * A headless environment is detected when any of the following conditions are true:
+ * 1. CI environment variables are set (CI, GITHUB_ACTIONS, GITLAB_CI, JENKINS, etc.)
+ * 2. HEADLESS environment variable is set to a truthy value
+ * 3. SSH_TTY environment variable is set (indicates SSH session without display)
+ * 4. stdout or stderr are not TTY (indicates non-interactive environment)
+ *
+ * This detection is used to prevent browser launch in environments where
+ * it would fail or be inappropriate (CI pipelines, SSH sessions, etc.).
+ *
+ * Requirements: 3.1, 4.1
+ *
+ * @returns true if running in a headless environment, false otherwise
+ */
+export declare function isHeadlessEnvironment(): boolean;
+/**
+ * Dependencies for the agent auth flow.
+ */
+export interface AgentAuthFlowDependencies {
+    /** Function to get a provider by ID */
+    getProvider: (providerId: AuthProviderId) => IAuthProvider;
+    /** Function to store tokens after successful authentication */
+    storeTokens: (providerId: AuthProviderId, tokens: TokenResponse) => Promise<void>;
+    /** Optional custom browser launcher (for testing) */
+    launchBrowser?: (url: string) => Promise<void>;
+}
+/**
+ * Agent auth flow - browser-based OAuth 2.1 Authorization Code flow with PKCE.
+ *
+ * This class orchestrates the complete OAuth 2.1 agent authentication flow,
+ * handling PKCE generation, browser launch, callback handling, and token exchange.
+ */
+export declare class AgentAuthFlow {
+    private readonly getProvider;
+    private readonly storeTokens;
+    private readonly launchBrowser;
+    /**
+     * Create a new agent auth flow.
+     *
+     * @param dependencies - Flow dependencies including provider resolver and token storage
+     */
+    constructor(dependencies: AgentAuthFlowDependencies);
+    /**
+     * Execute the agent auth flow.
+     *
+     * Performs the complete OAuth 2.1 Authorization Code flow with PKCE:
+     * 1. Checks for headless environment (fails fast if detected)
+     * 2. Creates an auth session with PKCE and state parameters
+     * 3. Starts a callback server on loopback address
+     * 4. Builds and opens the authorization URL in the system browser
+     * 5. Waits for the OAuth callback
+     * 6. Validates the state parameter
+     * 7. Exchanges the authorization code for tokens
+     * 8. Stores the tokens and returns the result
+     *
+     * @param providerId - The provider to authenticate with
+     * @param options - Optional flow configuration
+     * @returns Authentication result indicating success or failure
+     */
+    execute(providerId: AuthProviderId, options?: AgentAuthOptions): Promise<AuthResult>;
+    /**
+     * Validate provider configuration before starting OAuth flow.
+     *
+     * Checks:
+     * - Client ID is present and valid
+     * - Provider endpoints are HTTPS (via provider.validateConfig())
+     * - Provider supports PKCE with S256
+     *
+     * @param providerId - The provider identifier
+     * @param provider - The provider instance
+     * @param clientId - The client ID to validate
+     * @returns Validation result with error details if invalid
+     */
+    private validateProviderConfig;
+    /**
+     * Get the default client ID for a provider.
+     *
+     * This is a placeholder that should be overridden with actual client IDs
+     * from configuration or environment variables.
+     *
+     * @param providerId - The provider identifier
+     * @returns The default client ID for the provider
+     */
+    private getDefaultClientId;
+}
+/**
+ * Redact sensitive parameters from a URL for safe logging.
+ *
+ * @param url - The URL to redact
+ * @returns URL string with sensitive parameters replaced with [REDACTED]
+ */
+export declare function redactUrlForLogging(url: string): string;
+/**
+ * Open a URL in the system default browser.
+ *
+ * Uses platform-specific commands to launch the browser:
+ * - macOS: `open`
+ * - Windows: `start`
+ * - Linux: `xdg-open`
+ *
+ * Security measures:
+ * - Uses execFile with argument arrays to prevent command injection
+ * - Validates URL is HTTPS only (OAuth authorization URLs must use HTTPS)
+ * - Disallows userinfo (username:password) in URL
+ * - Validates no control characters in URL (checked before URL parsing)
+ * - Logs redacted URL for security
+ *
+ * Requirements: 3.6, 8.1
+ *
+ * @param url - The URL to open
+ * @throws Error if the browser cannot be launched or URL is invalid
+ */
+export declare function openSystemBrowser(url: string): Promise<void>;
+/**
+ * Create an agent auth flow with the given dependencies.
+ *
+ * @param dependencies - Flow dependencies
+ * @returns A new AgentAuthFlow instance
+ */
+export declare function createAgentAuthFlow(dependencies: AgentAuthFlowDependencies): AgentAuthFlow;

package/out/tsc/workers-registry/registry-launcher/src/auth/flows/callback-server.d.ts

@@ -0,0 +1,131 @@
+import type { CallbackResult } from '../types.js';
+/**
+ * Loopback HTTP server for OAuth callbacks.
+ */
+export interface ICallbackServer {
+    /** Start the server and return the redirect URI */
+    start(): Promise<string>;
+    /** Wait for the authorization callback */
+    waitForCallback(timeoutMs: number): Promise<CallbackResult>;
+    /** Stop the server and clean up resources */
+    stop(): Promise<void>;
+    /** Get the current server port (0 if not started) */
+    getPort(): number;
+    /** Check if server is running */
+    isRunning(): boolean;
+}
+/**
+ * Check if an address is a loopback address.
+ * Supports both IPv4 (127.x.x.x) and IPv6 (::1) loopback addresses.
+ *
+ * @param address - The IP address to check
+ * @returns True if the address is a loopback address
+ */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * Validate the Host header against allowed loopback hosts.
+ * Prevents DNS rebinding and host confusion attacks.
+ *
+ * @param hostHeader - The Host header value from the request
+ * @param expectedPort - The expected port number
+ * @returns True if the Host header is valid
+ */
+export declare function isValidHostHeader(hostHeader: string | undefined, expectedPort: number): boolean;
+/**
+ * Callback server implementation.
+ * Creates an HTTP server on a loopback address with dynamic port allocation
+ * to receive OAuth authorization callbacks.
+ *
+ * @implements {ICallbackServer}
+ */
+export declare class CallbackServer implements ICallbackServer {
+    private server;
+    private port;
+    private running;
+    private callbackPath;
+    private callbackPromise;
+    private callbackResolve;
+    private callbackReject;
+    private timeoutId;
+    private callbackHandled;
+    /** Minimum timeout in milliseconds (1 second) */
+    private static readonly MIN_TIMEOUT_MS;
+    /** Maximum timeout in milliseconds (10 minutes) */
+    private static readonly MAX_TIMEOUT_MS;
+    /**
+     * Creates a new CallbackServer instance.
+     * @param callbackPath - The path to listen for callbacks (default: '/callback')
+     */
+    constructor(callbackPath?: string);
+    /**
+     * Start the server and return the redirect URI.
+     * The server binds to a loopback address (127.0.0.1) with a dynamically allocated port.
+     *
+     * @returns The redirect URI to use for OAuth callbacks
+     * @throws Error if the server is already running or fails to start
+     */
+    start(): Promise<string>;
+    /**
+     * Wait for the authorization callback.
+     * Returns when a callback is received or the timeout is reached.
+     *
+     * @param timeoutMs - Maximum time to wait for the callback in milliseconds
+     * @returns The callback result containing the authorization code and state
+     * @throws Error if the server is not running, timeout is reached, or callback fails
+     */
+    waitForCallback(timeoutMs: number): Promise<CallbackResult>;
+    /**
+     * Stop the server and clean up resources.
+     */
+    stop(): Promise<void>;
+    /**
+     * Get the current server port.
+     * @returns The port number, or 0 if the server is not started
+     */
+    getPort(): number;
+    /**
+     * Check if the server is running.
+     * @returns True if the server is running
+     */
+    isRunning(): boolean;
+    /**
+     * Handle incoming HTTP requests.
+     * Parses the callback URL and extracts the authorization code and state.
+     * Rejects connections from non-loopback addresses for security.
+     */
+    private handleRequest;
+    /**
+     * Send an error response with security headers.
+     */
+    private sendErrorResponse;
+    /**
+     * Send an HTML response with security headers.
+     */
+    private sendHtmlResponse;
+    /**
+     * Stop accepting new connections without fully closing the server.
+     * This ensures the server stops accepting new requests after processing the callback
+     * while allowing the current response to complete.
+     *
+     * @remarks
+     * This implements Requirement 8.3: The Callback_Server SHALL immediately close
+     * after processing the single expected request.
+     */
+    private stopAcceptingConnections;
+    /**
+     * Clean up timeout and callback state.
+     */
+    private cleanup;
+    /**
+     * Build a success HTML page to display in the browser.
+     */
+    private buildSuccessPage;
+    /**
+     * Build an error HTML page to display in the browser.
+     */
+    private buildErrorPage;
+    /**
+     * Escape HTML special characters to prevent XSS.
+     */
+    private escapeHtml;
+}

package/out/tsc/workers-registry/registry-launcher/src/auth/flows/callback-server.test.d.ts

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

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

@@ -0,0 +1,11 @@
+/**
+ * Authentication flow exports.
+ *
+ * @module flows
+ */
+export type { ICallbackServer } from './callback-server.js';
+export { CallbackServer } from './callback-server.js';
+export { AgentAuthFlow, createAgentAuthFlow, openSystemBrowser, isHeadlessEnvironment, DEFAULT_AUTH_TIMEOUT_MS, } from './agent-auth-flow.js';
+export type { AgentAuthFlowDependencies } from './agent-auth-flow.js';
+export { TerminalAuthFlow, createTerminalAuthFlow, getProviderInfo, getAllProviderInfo, } from './terminal-auth-flow.js';
+export type { TerminalAuthFlowDependencies, CollectedCredentials, } from './terminal-auth-flow.js';