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

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

@@ -0,0 +1,186 @@
+/**
+ * Type definitions for model API credentials.
+ *
+ * This module defines types for upstream model provider credentials (API keys).
+ * These providers (OpenAI, Anthropic) do NOT offer public OAuth IdP for
+ * third-party login - they use API keys instead.
+ *
+ * This separation clearly distinguishes:
+ * - User identity (OAuth/OIDC): Google, Microsoft Entra ID, AWS Cognito, GitHub, Generic OIDC
+ * - Model API access (API Keys): OpenAI, Anthropic
+ *
+ * Requirements: 7b.1, 7b.3
+ *
+ * @module model-credentials/types
+ */
+/**
+ * Model API provider identifiers.
+ *
+ * These providers use API keys for authentication, NOT OAuth.
+ * They do not offer public OAuth IdP for third-party login.
+ *
+ * Requirements: 7b.1, 7b.2
+ */
+export type ModelProviderId = 'openai' | 'anthropic';
+/**
+ * Valid model provider IDs for runtime validation.
+ */
+export declare const VALID_MODEL_PROVIDER_IDS: readonly ModelProviderId[];
+/**
+ * Type guard to check if a value is a valid ModelProviderId.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid ModelProviderId
+ */
+export declare function isValidModelProviderId(value: unknown): value is ModelProviderId;
+/**
+ * Model credential for storing API keys.
+ *
+ * Represents an API key credential for a model provider.
+ * These credentials are stored securely in the Credential_Store.
+ *
+ * Requirements: 7b.1, 7b.4
+ */
+export interface ModelCredential {
+    /**
+     * The model provider this credential is for.
+     */
+    providerId: ModelProviderId;
+    /**
+     * The API key value.
+     * This is stored encrypted in the Credential_Store.
+     */
+    apiKey: string;
+    /**
+     * Optional human-readable label for this credential.
+     * Useful when multiple keys are stored for the same provider.
+     */
+    label?: string;
+    /**
+     * Unix timestamp when this credential was stored.
+     */
+    storedAt: number;
+    /**
+     * Optional Unix timestamp when this credential expires.
+     * Most API keys don't expire, but some providers may issue
+     * time-limited keys.
+     */
+    expiresAt?: number;
+}
+/**
+ * Header injection type for model credentials.
+ */
+export interface HeaderInjection {
+    type: 'header';
+    /**
+     * The header name to use.
+     * e.g., 'Authorization' for OpenAI, 'x-api-key' for Anthropic
+     */
+    headerName: string;
+    /**
+     * Optional format string for the header value.
+     * Use '{key}' as placeholder for the API key.
+     * e.g., 'Bearer {key}' for OpenAI
+     * If not provided, the API key is used directly.
+     */
+    format?: string;
+}
+/**
+ * Model credential injection configuration.
+ *
+ * Defines how API keys should be injected into requests
+ * for each model provider.
+ *
+ * Requirements: 7b.5
+ */
+export type ModelCredentialInjection = HeaderInjection;
+/**
+ * Provider-specific injection configurations.
+ *
+ * OpenAI: Authorization header with Bearer token
+ * Anthropic: x-api-key header with raw key
+ *
+ * Requirements: 7b.5
+ */
+export declare const MODEL_CREDENTIAL_INJECTION_CONFIG: Readonly<Record<ModelProviderId, ModelCredentialInjection>>;
+/**
+ * Stored model credentials in the credential store.
+ *
+ * This is the format used when persisting model credentials
+ * to the Credential_Store.
+ *
+ * Requirements: 7b.4
+ */
+export interface StoredModelCredential {
+    /**
+     * The model provider this credential is for.
+     */
+    providerId: ModelProviderId;
+    /**
+     * The encrypted API key value.
+     * Encryption is handled by the storage backend.
+     */
+    apiKey: string;
+    /**
+     * Optional human-readable label.
+     */
+    label?: string;
+    /**
+     * Unix timestamp when this credential was stored.
+     */
+    storedAt: number;
+    /**
+     * Optional Unix timestamp when this credential expires.
+     */
+    expiresAt?: number;
+}
+/**
+ * Result of a model credential retrieval operation.
+ */
+export interface ModelCredentialResult {
+    /**
+     * Whether the credential was found.
+     */
+    found: boolean;
+    /**
+     * The credential, if found.
+     */
+    credential?: ModelCredential;
+    /**
+     * Error message if retrieval failed.
+     */
+    error?: string;
+}
+/**
+ * Status of a model credential.
+ */
+export type ModelCredentialStatus = 'configured' | 'not-configured' | 'expired';
+/**
+ * Model credential status entry for display.
+ */
+export interface ModelCredentialStatusEntry {
+    /**
+     * The model provider.
+     */
+    providerId: ModelProviderId;
+    /**
+     * Current status of the credential.
+     */
+    status: ModelCredentialStatus;
+    /**
+     * Optional label for the credential.
+     */
+    label?: string;
+    /**
+     * Unix timestamp when the credential was stored.
+     */
+    storedAt?: number;
+    /**
+     * Unix timestamp when the credential expires.
+     */
+    expiresAt?: number;
+}
+/**
+ * Map of model provider IDs to their credential status.
+ */
+export type ModelCredentialStatusMap = Map<ModelProviderId, ModelCredentialStatusEntry>;

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

@@ -0,0 +1,61 @@
+/**
+ * Minimum length for PKCE code verifier per RFC 7636.
+ */
+export declare const PKCE_VERIFIER_MIN_LENGTH = 43;
+/**
+ * Maximum length for PKCE code verifier per RFC 7636.
+ */
+export declare const PKCE_VERIFIER_MAX_LENGTH = 128;
+/**
+ * PKCE code challenge method.
+ * OAuth 2.1 requires S256 (SHA-256) method.
+ */
+export declare const PKCE_CODE_CHALLENGE_METHOD: "S256";
+/**
+ * Generate a cryptographically secure PKCE code verifier.
+ *
+ * The verifier is generated using crypto.randomBytes for cryptographic randomness,
+ * then encoded using only unreserved URI characters as specified in RFC 7636.
+ * Uses rejection sampling to avoid modulo bias.
+ *
+ * @param length - Optional length of the verifier (default: 64, must be 43-128)
+ * @returns A random string between 43-128 characters using unreserved URI characters
+ * @throws Error if length is outside the valid range (43-128) or not a valid integer
+ */
+export declare function generateCodeVerifier(length?: number): string;
+/**
+ * Validate a PKCE code verifier format.
+ *
+ * Checks that the verifier meets RFC 7636 requirements:
+ * - Length between 43 and 128 characters
+ * - Contains only unreserved URI characters
+ *
+ * @param verifier - The code verifier to validate
+ * @returns True if the verifier is valid, false otherwise
+ */
+export declare function validateCodeVerifier(verifier: string): boolean;
+/**
+ * Generate a PKCE code challenge from a code verifier.
+ *
+ * Computes the SHA-256 hash of the verifier and encodes it as base64url
+ * without padding, as required by RFC 7636 S256 method.
+ *
+ * @param verifier - The code verifier to hash
+ * @param strict - If true, validates verifier format (default: false for backward compatibility)
+ * @returns Base64url-encoded SHA-256 hash of the verifier (without padding)
+ * @throws Error if strict mode is enabled and verifier format is invalid
+ */
+export declare function generateCodeChallenge(verifier: string, strict?: boolean): string;
+/**
+ * Generate a PKCE pair (verifier and challenge).
+ *
+ * Creates a cryptographically secure code verifier and computes
+ * the corresponding S256 code challenge.
+ *
+ * @param length - Optional length of the verifier (default: 64, must be 43-128)
+ * @returns Object containing both the verifier and challenge
+ */
+export declare function generatePKCEPair(length?: number): {
+    verifier: string;
+    challenge: string;
+};

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

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

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

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

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

@@ -0,0 +1,138 @@
+/**
+ * Base OAuth 2.1 provider implementation.
+ *
+ * Provides common OAuth 2.1 URL building logic and HTTPS endpoint validation.
+ *
+ * @module providers/base-provider
+ */
+import type { AuthProviderId, AuthorizationParams, TokenResponse, TokenInjectionMethod, ProviderEndpoints } from '../types.js';
+import type { IAuthProvider } from './types.js';
+/**
+ * Configuration for a base auth provider.
+ */
+export interface BaseProviderConfig {
+    /** Unique provider identifier */
+    id: AuthProviderId;
+    /** Human-readable provider name */
+    name: string;
+    /** OAuth authorization endpoint URL */
+    authorizationEndpoint: string;
+    /** OAuth token endpoint URL */
+    tokenEndpoint: string;
+    /** Default scopes for this provider */
+    defaultScopes: string[];
+    /** Token injection method for agent requests */
+    tokenInjection: TokenInjectionMethod;
+    /** Client ID for OAuth flow */
+    clientId?: string;
+    /** Client secret for OAuth flow (optional, for confidential clients) */
+    clientSecret?: string;
+}
+/**
+ * Abstract base class for OAuth 2.1 providers.
+ *
+ * Implements common OAuth 2.1 functionality:
+ * - Authorization URL building with required parameters
+ * - HTTPS endpoint validation
+ * - Token exchange and refresh
+ *
+ * Requirements: 3.2, 3.6, 7.5
+ */
+export declare abstract class BaseAuthProvider implements IAuthProvider {
+    readonly id: AuthProviderId;
+    readonly name: string;
+    readonly defaultScopes: readonly string[];
+    protected readonly authorizationEndpoint: string;
+    protected readonly tokenEndpoint: string;
+    protected readonly tokenInjection: TokenInjectionMethod;
+    protected clientId?: string;
+    protected clientSecret?: string;
+    /** Default timeout for HTTP requests in milliseconds (30 seconds) */
+    protected static readonly DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+    /**
+     * Security-critical OAuth parameters that cannot be overridden by additionalParams.
+     * These parameters are set by the OAuth flow and must not be tampered with.
+     */
+    private static readonly PROTECTED_PARAMS;
+    /**
+     * Create a new base auth provider.
+     * @param config - Provider configuration
+     * @throws Error if endpoints are not HTTPS or contain embedded credentials
+     */
+    constructor(config: BaseProviderConfig);
+    /**
+     * Build the authorization URL for the OAuth flow.
+     *
+     * Includes all required OAuth 2.1 parameters:
+     * - client_id
+     * - redirect_uri
+     * - response_type=code
+     * - scope
+     * - state
+     * - code_challenge
+     * - code_challenge_method=S256
+     *
+     * @param params - Authorization parameters
+     * @returns The complete authorization URL
+     * @throws Error if additionalParams attempts to override protected parameters
+     */
+    buildAuthorizationUrl(params: AuthorizationParams): string;
+    /**
+     * Exchange authorization code for tokens.
+     *
+     * @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.
+     *
+     * @param refreshToken - The refresh token
+     * @returns The new token response
+     */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /**
+     * Validate provider configuration.
+     *
+     * Ensures all endpoints use HTTPS (required for OAuth 2.1).
+     *
+     * @throws Error if configuration is invalid
+     */
+    validateConfig(): void;
+    /**
+     * Get token injection method for agent requests.
+     *
+     * @returns The token injection configuration
+     */
+    getTokenInjection(): TokenInjectionMethod;
+    /**
+     * Get the provider endpoints.
+     *
+     * @returns The provider endpoint URLs
+     */
+    getEndpoints(): ProviderEndpoints;
+    /**
+     * Set the client credentials.
+     *
+     * @param clientId - The OAuth client ID
+     * @param clientSecret - The OAuth client secret (optional)
+     */
+    setClientCredentials(clientId: string, clientSecret?: string): void;
+    /**
+     * Validate that an endpoint uses HTTPS and has no embedded credentials.
+     *
+     * @param endpoint - The endpoint URL to validate
+     * @param name - The name of the endpoint (for error messages)
+     * @throws Error if the endpoint does not use HTTPS or contains embedded credentials
+     */
+    protected validateHttpsEndpoint(endpoint: string, name: string): void;
+    /**
+     * Parse a token response from the provider.
+     *
+     * @param data - The raw response data
+     * @returns The parsed token response
+     */
+    protected parseTokenResponse(data: Record<string, unknown>): TokenResponse;
+}

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

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

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

@@ -0,0 +1,44 @@
+/**
+ * AWS Cognito OAuth 2.1 provider implementation.
+ *
+ * @module providers/cognito-provider
+ */
+import { BaseAuthProvider } from './base-provider.js';
+/**
+ * Configuration options for Cognito provider.
+ */
+export interface CognitoProviderConfig {
+    /** Cognito user pool domain (e.g., 'my-app' for my-app.auth.us-east-1.amazoncognito.com) */
+    userPoolDomain: string;
+    /** AWS region (e.g., 'us-east-1') */
+    region: string;
+    /** OAuth client ID */
+    clientId?: string;
+    /** OAuth client secret (optional) */
+    clientSecret?: string;
+}
+/**
+ * AWS Cognito OAuth provider.
+ *
+ * Endpoints are dynamically constructed based on user pool domain and region:
+ * - Authorization: https://{domain}.auth.{region}.amazoncognito.com/oauth2/authorize
+ * - Token: https://{domain}.auth.{region}.amazoncognito.com/oauth2/token
+ *
+ * Default scopes: openid, profile
+ * Token injection: Bearer header
+ */
+export declare class CognitoProvider extends BaseAuthProvider {
+    constructor(config: CognitoProviderConfig);
+    /**
+     * Validate Cognito user pool domain name.
+     * @param domain - The user pool domain to validate
+     * @throws Error if domain is invalid or contains injection characters
+     */
+    private static validateUserPoolDomain;
+    /**
+     * Validate AWS region name.
+     * @param region - The AWS region to validate
+     * @throws Error if region is invalid or contains injection characters
+     */
+    private static validateRegion;
+}

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * Microsoft Entra ID (formerly Azure AD) OAuth 2.1 provider implementation.
+ *
+ * @module providers/entra-provider
+ */
+import { BaseAuthProvider } from './base-provider.js';
+/**
+ * Configuration options for Microsoft Entra ID provider.
+ *
+ * @remarks
+ * Microsoft renamed Azure AD to Microsoft Entra ID in 2023.
+ * This provider supports both single-tenant and multi-tenant configurations.
+ */
+export interface EntraProviderConfig {
+    /** Microsoft Entra ID tenant ID or 'common' for multi-tenant */
+    tenantId: string;
+    /** OAuth client ID */
+    clientId?: string;
+    /** OAuth client secret (optional) */
+    clientSecret?: string;
+}
+/**
+ * @deprecated Use EntraProviderConfig instead. Kept for backward compatibility.
+ */
+export type AzureProviderConfig = EntraProviderConfig;
+/**
+ * Microsoft Entra ID (formerly Azure AD) OAuth provider.
+ *
+ * Endpoints are dynamically constructed based on tenant ID:
+ * - Authorization: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
+ * - Token: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
+ *
+ * Use 'common' for multi-tenant applications.
+ *
+ * Default scopes: openid, profile
+ * Token injection: Bearer header
+ *
+ * @remarks
+ * The provider ID remains 'azure' for backward compatibility with existing
+ * configurations and the ACP Registry.
+ */
+export declare class EntraIdProvider extends BaseAuthProvider {
+    constructor(config: EntraProviderConfig);
+    /**
+     * Validate Microsoft Entra ID tenant ID.
+     * @param tenantId - The tenant ID to validate
+     * @throws Error if tenantId is invalid or contains injection characters
+     */
+    private static validateTenantId;
+}
+/**
+ * @deprecated Use EntraIdProvider instead. Kept for backward compatibility.
+ */
+export declare const AzureProvider: typeof EntraIdProvider;

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

@@ -0,0 +1,19 @@
+/**
+ * GitHub OAuth 2.1 provider implementation.
+ *
+ * @module providers/github-provider
+ */
+import { BaseAuthProvider } from './base-provider.js';
+/**
+ * GitHub OAuth provider.
+ *
+ * Endpoints:
+ * - Authorization: https://github.com/login/oauth/authorize
+ * - Token: https://github.com/login/oauth/access_token
+ *
+ * Default scopes: read:user
+ * Token injection: Bearer header
+ */
+export declare class GitHubProvider extends BaseAuthProvider {
+    constructor(clientId?: string, clientSecret?: string);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Google OAuth 2.1 provider implementation.
+ *
+ * @module providers/google-provider
+ */
+import { BaseAuthProvider } from './base-provider.js';
+/**
+ * Google OAuth provider.
+ *
+ * Endpoints:
+ * - Authorization: https://accounts.google.com/o/oauth2/v2/auth
+ * - Token: https://oauth2.googleapis.com/token
+ *
+ * Default scopes: openid, profile, email
+ * Token injection: Bearer header
+ */
+export declare class GoogleProvider extends BaseAuthProvider {
+    constructor(clientId?: string, clientSecret?: string);
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Provider registry and factory.
+ *
+ * Provides access to OAuth provider implementations.
+ *
+ * @module providers
+ */
+import type { AuthProviderId } from '../types.js';
+import type { IAuthProvider } from './types.js';
+/**
+ * Provider factory function type.
+ */
+export type ProviderFactory = () => IAuthProvider;
+/**
+ * List of supported OAuth provider IDs.
+ *
+ * Note: OpenAI and Anthropic are NOT included - they use API keys, not OAuth.
+ * See model-credentials module for API key handling.
+ */
+export declare const SUPPORTED_PROVIDERS: readonly AuthProviderId[];
+/**
+ * Register a provider factory.
+ *
+ * @param providerId - The provider identifier
+ * @param factory - Factory function that creates the provider
+ * @throws Error if providerId is not a valid supported provider ID
+ */
+export declare function registerProvider(providerId: AuthProviderId, factory: ProviderFactory): void;
+/**
+ * Unregister a provider.
+ *
+ * @param providerId - The provider identifier to unregister
+ * @returns True if the provider was unregistered
+ */
+export declare function unregisterProvider(providerId: AuthProviderId): boolean;
+/**
+ * Clear all registered providers.
+ * Useful for testing.
+ */
+export declare function clearProviders(): void;
+/**
+ * Get a provider implementation by ID.
+ *
+ * @param providerId - The provider identifier
+ * @returns The provider implementation
+ * @throws Error if provider is not registered
+ */
+export declare function getProvider(providerId: AuthProviderId): IAuthProvider;
+/**
+ * Check if a provider is registered.
+ *
+ * @param providerId - The provider identifier
+ * @returns True if the provider is registered
+ */
+export declare function hasProvider(providerId: AuthProviderId): boolean;
+/**
+ * Get the list of registered provider IDs.
+ *
+ * @returns Array of registered provider identifiers
+ */
+export declare function getRegisteredProviders(): AuthProviderId[];
+/**
+ * Get the list of supported provider IDs.
+ *
+ * @returns Array of supported provider identifiers
+ */
+export declare function getSupportedProviders(): readonly AuthProviderId[];
+/**
+ * Check if a provider ID is valid (supported).
+ * Re-exports the centralized type guard from types.ts.
+ *
+ * @param providerId - The provider identifier to check
+ * @returns True if the provider is supported
+ */
+export declare function isValidProviderId(providerId: unknown): providerId is AuthProviderId;
+/**
+ * Check if a provider ID is registered and available.
+ *
+ * @param providerId - The provider identifier to check
+ * @returns True if the provider is registered
+ */
+export declare function isProviderAvailable(providerId: string): boolean;
+export type { IAuthProvider } from './types.js';
+export { BaseAuthProvider } from './base-provider.js';
+export type { BaseProviderConfig } from './base-provider.js';
+export { GitHubProvider } from './github-provider.js';
+export { GoogleProvider } from './google-provider.js';
+export { CognitoProvider } from './cognito-provider.js';
+export type { CognitoProviderConfig } from './cognito-provider.js';
+export { EntraIdProvider, AzureProvider } from './entra-provider.js';
+export type { EntraProviderConfig, AzureProviderConfig } from './entra-provider.js';
+export { OIDCProvider } from './oidc-provider.js';
+export type { OIDCProviderConfig, OIDCDiscoveryDocument, OIDCDiscoveryResult } from './oidc-provider.js';
+/**
+ * Initialize all OAuth providers.
+ * Must be called before using AuthManager.
+ *
+ * This registers all supported OAuth provider implementations
+ * in the provider registry.
+ *
+ * Note: OpenAI and Anthropic are NOT registered here - they use API keys, not OAuth.
+ * See model-credentials module for API key handling.
+ *
+ * Note: Cognito, Azure, and OIDC require environment-specific configuration
+ * and are only registered if their config is available via env vars.
+ */
+export declare function initializeProviders(): void;

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

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