agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/auth/oauth-provider.d.ts

@@ -0,0 +1,308 @@
+/**
+ * A2A OAuth 2.0 Provider
+ *
+ * Implements OAuth 2.0 authorization server functionality including:
+ * - Authorization Code Flow (with PKCE support)
+ * - Client Credentials Flow
+ * - Token refresh
+ * - Token revocation
+ *
+ * @module adapters/a2a/auth/oauth-provider
+ * @see https://datatracker.ietf.org/doc/html/rfc6749
+ * @see https://datatracker.ietf.org/doc/html/rfc7636 (PKCE)
+ */
+import { TokenStore, type TokenStoreConfig } from './token-store.js';
+import { type JWTPayload } from './jwt-utils.js';
+/**
+ * Client credentials for OAuth 2.0 clients
+ */
+export interface ClientCredentials {
+    /** Client secret (hashed) */
+    readonly clientSecret: string;
+    /** Whether secret is hashed */
+    readonly secretHashed?: boolean;
+    /** Client name for display */
+    readonly name?: string;
+    /** Allowed scopes for this client */
+    readonly allowedScopes: string[];
+    /** Redirect URIs for authorization code flow */
+    readonly redirectUris?: string[];
+    /** Whether this client is a confidential client */
+    readonly confidential?: boolean;
+    /** Whether this client is active */
+    readonly active?: boolean;
+    /** Client metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * OAuth 2.0 provider configuration
+ */
+export interface OAuth2Config {
+    /** Issuer identifier (used in JWT 'iss' claim) */
+    readonly issuer: string;
+    /** Token endpoint URL */
+    readonly tokenEndpoint: string;
+    /** Authorization endpoint URL */
+    readonly authorizationEndpoint: string;
+    /** Registered client credentials */
+    readonly clientCredentials: Map<string, ClientCredentials>;
+    /** Access token TTL in seconds (default: 3600 = 1 hour) */
+    readonly tokenTTL?: number;
+    /** Refresh token TTL in seconds (default: 2592000 = 30 days) */
+    readonly refreshTokenTTL?: number;
+    /** Authorization code TTL in seconds (default: 600 = 10 minutes) */
+    readonly authorizationCodeTTL?: number;
+    /** JWT signing secret */
+    readonly signingSecret: string;
+    /** Token store configuration */
+    readonly tokenStoreConfig?: TokenStoreConfig;
+    /** Require PKCE for authorization code flow */
+    readonly requirePKCE?: boolean;
+    /** Allow refresh tokens */
+    readonly allowRefreshTokens?: boolean;
+}
+/**
+ * Default OAuth 2.0 configuration values
+ */
+export declare const DEFAULT_OAUTH2_CONFIG: {
+    readonly tokenTTL: 3600;
+    readonly refreshTokenTTL: 2592000;
+    readonly authorizationCodeTTL: 600;
+    readonly requirePKCE: false;
+    readonly allowRefreshTokens: true;
+};
+/**
+ * Authorization code with metadata
+ */
+export interface AuthorizationCode {
+    /** The authorization code */
+    readonly code: string;
+    /** Client ID */
+    readonly clientId: string;
+    /** Redirect URI */
+    readonly redirectUri: string;
+    /** Requested scopes */
+    readonly scopes: string[];
+    /** State parameter */
+    readonly state?: string;
+    /** When the code expires */
+    readonly expiresAt: Date;
+    /** Code challenge for PKCE */
+    readonly codeChallenge?: string;
+    /** Code challenge method */
+    readonly codeChallengeMethod?: 'S256' | 'plain';
+}
+/**
+ * Token pair (access + refresh)
+ */
+export interface TokenPair {
+    /** Access token (JWT) */
+    readonly accessToken: string;
+    /** Refresh token (opaque) */
+    readonly refreshToken?: string;
+    /** Token type (always 'Bearer') */
+    readonly tokenType: 'Bearer';
+    /** Access token expires in (seconds) */
+    readonly expiresIn: number;
+    /** Refresh token expires in (seconds) */
+    readonly refreshExpiresIn?: number;
+    /** Granted scopes */
+    readonly scope: string;
+}
+/**
+ * OAuth 2.0 error response
+ */
+export interface OAuth2Error {
+    /** Error code */
+    readonly error: OAuth2ErrorCode;
+    /** Human-readable description */
+    readonly error_description?: string;
+    /** Error URI */
+    readonly error_uri?: string;
+}
+/**
+ * OAuth 2.0 error codes
+ */
+export type OAuth2ErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unauthorized_client' | 'unsupported_grant_type' | 'invalid_scope' | 'access_denied' | 'server_error';
+/**
+ * OAuth 2.0 grant types
+ */
+export type GrantType = 'authorization_code' | 'client_credentials' | 'refresh_token';
+/**
+ * OAuth 2.0 error
+ */
+export declare class OAuth2ProviderError extends Error {
+    readonly error: OAuth2ErrorCode;
+    readonly errorDescription?: string;
+    readonly httpStatus: number;
+    constructor(error: OAuth2ErrorCode, description?: string);
+    private getHttpStatus;
+    /**
+     * Convert to OAuth 2.0 error response format
+     */
+    toResponse(): OAuth2Error;
+}
+/**
+ * OAuth 2.0 Authorization Server Provider
+ *
+ * Implements OAuth 2.0 token issuance and validation for the A2A protocol.
+ */
+export declare class OAuth2Provider {
+    private readonly config;
+    private readonly tokenStore;
+    constructor(config: OAuth2Config);
+    /**
+     * Register a new client
+     *
+     * @param clientId - The client ID
+     * @param credentials - The client credentials
+     */
+    registerClient(clientId: string, credentials: ClientCredentials): void;
+    /**
+     * Remove a client
+     *
+     * @param clientId - The client ID
+     * @returns True if the client was removed
+     */
+    removeClient(clientId: string): boolean;
+    /**
+     * Validate client credentials
+     *
+     * @param clientId - The client ID
+     * @param clientSecret - The client secret (optional for public clients)
+     * @returns True if the credentials are valid
+     */
+    validateClient(clientId: string, clientSecret?: string): boolean;
+    /**
+     * Get client credentials
+     *
+     * @param clientId - The client ID
+     * @returns The client credentials or undefined
+     */
+    getClient(clientId: string): ClientCredentials | undefined;
+    /**
+     * Generate an authorization code
+     *
+     * @param clientId - The client ID
+     * @param redirectUri - The redirect URI
+     * @param scope - Requested scopes
+     * @param state - Optional state parameter
+     * @param codeChallenge - PKCE code challenge
+     * @param codeChallengeMethod - PKCE method (S256 or plain)
+     * @returns The authorization code
+     */
+    generateAuthorizationCode(clientId: string, redirectUri: string, scope: string[], state?: string, codeChallenge?: string, codeChallengeMethod?: 'S256' | 'plain'): AuthorizationCode;
+    /**
+     * Exchange an authorization code for tokens
+     *
+     * @param code - The authorization code
+     * @param clientId - The client ID
+     * @param clientSecret - The client secret
+     * @param redirectUri - The redirect URI (must match original)
+     * @param codeVerifier - PKCE code verifier
+     * @returns Token pair
+     */
+    exchangeCodeForTokens(code: string, clientId: string, clientSecret: string, redirectUri: string, codeVerifier?: string): Promise<TokenPair>;
+    /**
+     * Issue tokens using client credentials grant
+     *
+     * @param clientId - The client ID
+     * @param clientSecret - The client secret
+     * @param scope - Requested scopes
+     * @returns Token pair
+     */
+    clientCredentialsGrant(clientId: string, clientSecret: string, scope?: string[]): Promise<TokenPair>;
+    /**
+     * Refresh an access token
+     *
+     * @param refreshToken - The refresh token
+     * @param scope - Optional new scope (must be subset of original)
+     * @returns New token pair
+     */
+    refreshAccessToken(refreshToken: string, scope?: string[]): Promise<TokenPair>;
+    /**
+     * Revoke a token
+     *
+     * @param token - The token to revoke
+     * @param tokenTypeHint - Optional hint about token type
+     */
+    revokeToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): void;
+    /**
+     * Revoke all tokens for a client
+     *
+     * @param clientId - The client ID
+     * @returns Number of tokens revoked
+     */
+    revokeClientTokens(clientId: string): number;
+    /**
+     * Validate an access token
+     *
+     * @param token - The access token
+     * @param requiredScopes - Required scopes (optional)
+     * @returns The token payload if valid
+     */
+    validateAccessToken(token: string, requiredScopes?: string[]): Promise<JWTPayload>;
+    /**
+     * Introspect a token
+     *
+     * @param token - The token to introspect
+     * @returns Token introspection response
+     */
+    introspectToken(token: string): Promise<{
+        active: boolean;
+        scope?: string;
+        client_id?: string;
+        exp?: number;
+        iat?: number;
+        sub?: string;
+        token_type?: string;
+    }>;
+    /**
+     * Generate a token pair
+     */
+    private generateTokenPair;
+    /**
+     * Generate a secure random code
+     */
+    private generateSecureCode;
+    /**
+     * Verify PKCE code challenge
+     */
+    private verifyCodeChallenge;
+    /**
+     * Get OAuth 2.0 authorization server metadata
+     *
+     * @returns OpenID Connect Discovery metadata
+     */
+    getMetadata(): Record<string, unknown>;
+    /**
+     * Get provider statistics
+     */
+    getStats(): {
+        tokenStats: ReturnType<TokenStore['getStats']>;
+        clientCount: number;
+    };
+    /**
+     * Clean up expired tokens
+     */
+    cleanup(): number;
+    /**
+     * Destroy the provider
+     */
+    destroy(): void;
+}
+/**
+ * Create a new OAuth2Provider instance
+ *
+ * @param config - Provider configuration
+ * @returns A new OAuth2Provider
+ */
+export declare function createOAuth2Provider(config: OAuth2Config): OAuth2Provider;
+/**
+ * Create a simple OAuth2Provider for testing
+ *
+ * @param signingSecret - The JWT signing secret
+ * @returns A configured OAuth2Provider
+ */
+export declare function createTestOAuth2Provider(signingSecret?: string): OAuth2Provider;
+//# sourceMappingURL=oauth-provider.d.ts.map

package/v3/dist/adapters/a2a/auth/oauth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/auth/oauth-provider.ts"],"names":[],"mappings":"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"}