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

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

@@ -0,0 +1,369 @@
+/**
+ * Core type definitions for OAuth 2.1 authentication.
+ *
+ * @module types
+ */
+/**
+ * Supported OAuth/OIDC provider identifiers for user identity.
+ *
+ * Note: OpenAI and Anthropic are NOT public OAuth IdPs for third-party login.
+ * They use API keys instead. See ModelProviderId and model-credentials module.
+ *
+ * Requirements: 7.1, 7a.1
+ */
+export type AuthProviderId = 'google' | 'azure' | 'cognito' | 'github' | 'oidc';
+/**
+ * Model API providers that use API keys (NOT OAuth).
+ *
+ * These providers do not offer public OAuth IdP for third-party login.
+ * Use API key authentication instead.
+ *
+ * Requirements: 7b.1, 7b.2
+ */
+export type ModelProviderId = 'openai' | 'anthropic';
+/**
+ * Storage backend types.
+ */
+export type StorageBackendType = 'keychain' | 'encrypted-file' | 'memory';
+/**
+ * Token status for a provider.
+ */
+export type TokenStatus = 'authenticated' | 'expired' | 'refresh-failed' | 'not-configured';
+/**
+ * Authentication error codes.
+ */
+export type AuthErrorCode = 'INVALID_STATE' | 'TIMEOUT' | 'NETWORK_ERROR' | 'INVALID_CREDENTIALS' | 'STORAGE_ERROR' | 'PROVIDER_ERROR' | 'UNSUPPORTED_PROVIDER' | 'CALLBACK_ERROR' | 'TOKEN_REFRESH_FAILED' | 'HEADLESS_ENVIRONMENT';
+/**
+ * OAuth token response from provider.
+ */
+export interface TokenResponse {
+    accessToken: string;
+    tokenType: string;
+    expiresIn?: number;
+    refreshToken?: string;
+    scope?: string;
+    idToken?: string;
+}
+/**
+ * Token injection method for agent requests.
+ */
+export interface TokenInjectionMethod {
+    type: 'header' | 'query' | 'body';
+    key: string;
+    format?: string;
+}
+/**
+ * Custom provider endpoints (for Cognito/Azure).
+ */
+export interface ProviderEndpoints {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    userInfoEndpoint?: string;
+}
+/**
+ * Stored credentials in credential store.
+ */
+export interface StoredCredentials {
+    providerId: AuthProviderId;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+    clientId?: string;
+    clientSecret?: string;
+    customEndpoints?: ProviderEndpoints;
+    storedAt: number;
+}
+/**
+ * Authorization parameters for building auth URL.
+ */
+export interface AuthorizationParams {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    state: string;
+    codeChallenge: string;
+    codeChallengeMethod: 'S256';
+    responseType: 'code';
+    additionalParams?: Record<string, string>;
+}
+/**
+ * Successful callback result from OAuth redirect.
+ */
+export interface CallbackSuccess {
+    success: true;
+    code: string;
+    state: string;
+}
+/**
+ * Error callback result from OAuth redirect.
+ */
+export interface CallbackErrorResult {
+    success: false;
+    error: string;
+    errorDescription?: string;
+    state?: string;
+}
+/**
+ * Callback result from OAuth redirect (discriminated union).
+ * OAuth error redirects may not include 'code', only 'error'.
+ */
+export type CallbackResult = CallbackSuccess | CallbackErrorResult;
+/**
+ * Agent auth flow options.
+ */
+export interface AgentAuthOptions {
+    timeoutMs?: number;
+    scopes?: string[];
+    clientId?: string;
+}
+/**
+ * Authentication error with details.
+ */
+export interface AuthError {
+    code: AuthErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Successful authentication result.
+ */
+export interface AuthResultSuccess {
+    success: true;
+    providerId: AuthProviderId;
+}
+/**
+ * Failed authentication result.
+ */
+export interface AuthResultFailure {
+    success: false;
+    providerId: AuthProviderId;
+    error: AuthError;
+}
+/**
+ * Authentication result (discriminated union).
+ */
+export type AuthResult = AuthResultSuccess | AuthResultFailure;
+/**
+ * Auth status for display.
+ */
+export interface AuthStatusEntry {
+    providerId: AuthProviderId;
+    status: TokenStatus;
+    expiresAt?: number;
+    scope?: string;
+    lastRefresh?: number;
+}
+/**
+ * Map of provider IDs to their auth status.
+ */
+export type AuthStatusMap = Map<AuthProviderId, AuthStatusEntry>;
+/**
+ * Provider configuration.
+ */
+export interface ProviderConfig {
+    clientId: string;
+    clientSecret?: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    defaultScopes: string[];
+    tokenInjection: TokenInjectionMethod;
+}
+/**
+ * Authentication method types.
+ * Used for method precedence selection.
+ */
+export type AuthMethodType = 'oauth2' | 'api-key';
+/**
+ * Valid authentication method types for runtime validation.
+ */
+export declare const VALID_AUTH_METHOD_TYPES: readonly AuthMethodType[];
+/**
+ * Type guard to check if a value is a valid AuthMethodType.
+ * @param value - The value to check
+ * @returns True if the value is a valid AuthMethodType
+ */
+export declare function isValidAuthMethodType(value: unknown): value is AuthMethodType;
+/**
+ * Configuration for authentication method precedence.
+ *
+ * Defines the order in which authentication methods are attempted.
+ * Default precedence: oauth2 > api-key (OAuth preferred when available)
+ *
+ * Requirements: 3.1, 10.3
+ */
+export interface AuthMethodPrecedenceConfig {
+    /**
+     * Ordered list of authentication methods by preference.
+     * First method in the list has highest priority.
+     * Default: ['oauth2', 'api-key']
+     */
+    methodPrecedence: AuthMethodType[];
+    /**
+     * Whether to fail fast when an unsupported method is encountered.
+     * If true, throws an error immediately.
+     * If false, skips the unsupported method and tries the next one.
+     * Default: true
+     */
+    failFastOnUnsupported: boolean;
+    /**
+     * Whether to fail fast when provider ID is ambiguous.
+     * Ambiguity occurs when multiple providers could match an agent.
+     * If true, throws an error immediately.
+     * If false, uses the first matching provider.
+     * Default: true
+     */
+    failFastOnAmbiguous: boolean;
+}
+/**
+ * Default authentication method precedence configuration.
+ *
+ * OAuth2 is preferred over API keys when both are available.
+ * This aligns with Requirement 10.3: prefer OAuth credentials.
+ */
+export declare const DEFAULT_AUTH_METHOD_PRECEDENCE: AuthMethodPrecedenceConfig;
+/**
+ * Extended launcher config with auth settings.
+ */
+export interface AuthConfig {
+    /** Default auth timeout in seconds */
+    authTimeoutSec: number;
+    /** Proactive token refresh threshold in seconds */
+    tokenRefreshThresholdSec: number;
+    /** Preferred storage backend */
+    preferredStorageBackend?: StorageBackendType;
+    /**
+     * Authentication method precedence configuration.
+     * Controls which auth method is preferred when multiple are available.
+     * Default: oauth2 > api-key
+     */
+    methodPrecedence?: Partial<AuthMethodPrecedenceConfig>;
+}
+/**
+ * ACP protocol auth method advertisement.
+ */
+export interface AcpAuthMethod {
+    id: string;
+    type: 'oauth2' | 'api-key';
+    providerId?: AuthProviderId;
+}
+/**
+ * Valid provider IDs for runtime validation.
+ *
+ * Note: OpenAI and Anthropic are NOT included - they use API keys, not OAuth.
+ * See model-credentials module for API key handling.
+ */
+export declare const VALID_PROVIDER_IDS: readonly AuthProviderId[];
+/**
+ * Valid storage backend types for runtime validation.
+ */
+export declare const VALID_STORAGE_BACKENDS: readonly StorageBackendType[];
+/**
+ * Valid token status values for runtime validation.
+ */
+export declare const VALID_TOKEN_STATUSES: readonly TokenStatus[];
+/**
+ * Valid auth error codes for runtime validation.
+ */
+export declare const VALID_ERROR_CODES: readonly AuthErrorCode[];
+/**
+ * Type guard to check if a value is a valid AuthProviderId.
+ * @param value - The value to check
+ * @returns True if the value is a valid AuthProviderId
+ */
+export declare function isValidProviderId(value: unknown): value is AuthProviderId;
+/**
+ * Type guard to check if a value is a valid StorageBackendType.
+ * @param value - The value to check
+ * @returns True if the value is a valid StorageBackendType
+ */
+export declare function isValidStorageBackend(value: unknown): value is StorageBackendType;
+/**
+ * Type guard to check if a value is a valid TokenStatus.
+ * @param value - The value to check
+ * @returns True if the value is a valid TokenStatus
+ */
+export declare function isValidTokenStatus(value: unknown): value is TokenStatus;
+/**
+ * Type guard to check if a value is a valid AuthErrorCode.
+ * @param value - The value to check
+ * @returns True if the value is a valid AuthErrorCode
+ */
+export declare function isValidErrorCode(value: unknown): value is AuthErrorCode;
+/**
+ * Explicit mapping from authMethod.id to AuthProviderId.
+ *
+ * This mapping table provides a secure, explicit translation from
+ * ACP authMethod identifiers to internal provider IDs.
+ *
+ * SECURITY: No substring or heuristic matching is used.
+ * Only exact matches in this table are accepted.
+ *
+ * Note: OpenAI and Anthropic are NOT included - they use API keys, not OAuth.
+ * See model-credentials module for API key handling.
+ *
+ * Requirements: 7.1, 13.4
+ */
+export declare const AUTH_METHOD_ID_TO_PROVIDER_ID: Readonly<Record<string, AuthProviderId>>;
+/**
+ * Valid authMethod.id values for runtime validation.
+ */
+export declare const VALID_AUTH_METHOD_IDS: readonly string[];
+/**
+ * Error thrown when an unknown authMethod.id is encountered.
+ *
+ * Requirements: 13.4
+ */
+export declare class UnknownAuthMethodIdError extends Error {
+    readonly code: "UNSUPPORTED_PROVIDER";
+    readonly unknownMethodId: string;
+    readonly supportedMethodIds: readonly string[];
+    readonly supportedProviders: readonly AuthProviderId[];
+    constructor(unknownMethodId: string);
+}
+/**
+ * Type guard to check if a value is a valid authMethod.id.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a valid authMethod.id
+ */
+export declare function isValidAuthMethodId(value: unknown): value is string;
+/**
+ * Resolves an authMethod.id to its corresponding AuthProviderId.
+ *
+ * This function uses explicit mapping only - no substring matching,
+ * no heuristics, no fuzzy matching. This is a security requirement
+ * to prevent provider confusion attacks.
+ *
+ * @param authMethodId - The authMethod.id to resolve
+ * @returns The corresponding AuthProviderId
+ * @throws UnknownAuthMethodIdError if the authMethod.id is not recognized
+ *
+ * Requirements: 7.1, 13.4
+ *
+ * @example
+ * ```typescript
+ * // Valid mappings
+ * resolveAuthMethodIdToProviderId('oauth2-openai'); // returns 'openai'
+ * resolveAuthMethodIdToProviderId('oauth2-github'); // returns 'github'
+ * resolveAuthMethodIdToProviderId('github');        // returns 'github' (direct)
+ *
+ * // Invalid - throws UnknownAuthMethodIdError
+ * resolveAuthMethodIdToProviderId('oauth2-unknown');
+ * resolveAuthMethodIdToProviderId('openai-oauth2'); // wrong format
+ * resolveAuthMethodIdToProviderId('OPENAI');        // case sensitive
+ * ```
+ */
+export declare function resolveAuthMethodIdToProviderId(authMethodId: string): AuthProviderId;
+/**
+ * Safely resolves an authMethod.id to its corresponding AuthProviderId.
+ *
+ * Unlike `resolveAuthMethodIdToProviderId`, this function returns null
+ * instead of throwing an error for unknown method IDs.
+ *
+ * @param authMethodId - The authMethod.id to resolve
+ * @returns The corresponding AuthProviderId, or null if not recognized
+ *
+ * Requirements: 7.1, 13.4
+ */
+export declare function tryResolveAuthMethodIdToProviderId(authMethodId: string): AuthProviderId | null;

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

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

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

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

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

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

package/out/tsc/workers-registry/{acp-worker/src/registry-launcher → registry-launcher/src}/registry/index.d.ts

@@ -6,8 +6,8 @@
  *
  * @module registry/index
  */
-import { Registry, RegistryAgent, SpawnCommand } from './types.js';
-export type { Platform, BinaryDistribution, BinaryTarget, NpxDistribution, UvxDistribution, Distribution, RegistryAgent, Registry, SpawnCommand, McpServerConfig, } from './types.js';
+import { AgentAuthMethod, Registry, RegistryAgent, SpawnCommand } from './types.js';
+export type { Platform, BinaryDistribution, BinaryTarget, NpxDistribution, UvxDistribution, Distribution, RegistryAgent, Registry, SpawnCommand, McpServerConfig, AgentAuthMethod, } from './types.js';
 export { PlatformNotSupportedError, NoDistributionError, getCurrentPlatform, resolve } from './resolver.js';
 /**
  * Error thrown when registry fetch fails.
@@ -30,6 +30,19 @@ export declare class AgentNotFoundError extends Error {
     readonly agentId: string;
     constructor(agentId: string);
 }
+/**
+ * Cached auth requirements for an agent.
+ *
+ * Requirements: 11.2, 11.3
+ */
+export interface AgentAuthRequirements {
+    /** Whether authentication is required */
+    authRequired: boolean;
+    /** Authentication methods supported/required by the agent */
+    authMethods: AgentAuthMethod[];
+    /** Primary OAuth provider ID (first oauth2 method's providerId) */
+    primaryOAuthProviderId?: string;
+}
 /**
  * Interface for the RegistryIndex.
  */
@@ -51,6 +64,18 @@ export interface IRegistryIndex {
      * @throws PlatformNotSupportedError if binary distribution doesn't support current platform
      */
     resolve(agentId: string): SpawnCommand;
+    /**
+     * Get auth requirements for an agent.
+     *
+     * Checks the agent definition in the registry for `authRequired` or `authMethods` fields.
+     * Results are cached per agent for efficient repeated lookups.
+     *
+     * Requirements: 11.2, 11.3
+     *
+     * @param agentId - Agent ID to query
+     * @returns Auth requirements or undefined if agent not found
+     */
+    getAuthRequirements(agentId: string): AgentAuthRequirements | undefined;
 }
 /**
  * Parse and validate registry JSON data.
@@ -72,6 +97,12 @@ export declare class RegistryIndex implements IRegistryIndex {
     private registry;
     /** Map of agent ID to agent entry for fast lookup */
     private agentMap;
+    /**
+     * Cache of auth requirements per agent.
+     *
+     * Requirements: 11.2, 11.3
+     */
+    private authRequirementsCache;
     /**
      * Create a new RegistryIndex.
      *
@@ -106,6 +137,24 @@ export declare class RegistryIndex implements IRegistryIndex {
      * @returns The parsed registry or null if not yet fetched
      */
     getRegistry(): Registry | null;
+    /**
+     * Get auth requirements for an agent.
+     *
+     * Checks the agent definition in the registry for `authRequired` or `authMethods` fields.
+     * Results are cached per agent for efficient repeated lookups.
+     *
+     * Requirements: 11.2, 11.3
+     *
+     * @param agentId - Agent ID to query
+     * @returns Auth requirements or undefined if agent not found
+     */
+    getAuthRequirements(agentId: string): AgentAuthRequirements | undefined;
+    /**
+     * Clear the auth requirements cache for a specific agent or all agents.
+     *
+     * @param agentId - Optional agent ID to clear. If not provided, clears all cached requirements.
+     */
+    clearAuthRequirementsCache(agentId?: string): void;
     /**
      * Merge custom agents into the registry.
      *

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

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

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

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

package/out/tsc/workers-registry/{acp-worker/src/registry-launcher → registry-launcher/src}/registry/types.d.ts

@@ -74,6 +74,18 @@ export interface McpServerConfig {
     /** Optional environment variables */
     env?: Record<string, string>;
 }
+/**
+ * Authentication method configuration for an agent.
+ * Specifies how the agent requires authentication.
+ */
+export interface AgentAuthMethod {
+    /** Authentication method identifier (e.g., 'oauth2-openai', 'api-key') */
+    id: string;
+    /** Authentication type: 'oauth2' for OAuth 2.1, 'api-key' for API key */
+    type: 'oauth2' | 'api-key';
+    /** OAuth provider identifier (required for oauth2 type) */
+    providerId?: string;
+}
 /**
  * Agent entry in the ACP Registry.
  */
@@ -98,6 +110,18 @@ export interface RegistryAgent {
     distribution: Distribution;
     /** MCP servers to connect when creating a session */
     mcpServers?: McpServerConfig[];
+    /**
+     * Whether authentication is required for this agent.
+     * If true, the agent requires authentication before use.
+     * Requirements: 11.2, 11.3
+     */
+    authRequired?: boolean;
+    /**
+     * Authentication methods supported/required by this agent.
+     * Specifies OAuth providers or API key requirements.
+     * Requirements: 11.2, 11.3
+     */
+    authMethods?: AgentAuthMethod[];
 }
 /**
  * Parsed ACP Registry structure.