agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2a/auth/routes.d.ts

@@ -0,0 +1,244 @@
+/**
+ * A2A OAuth 2.0 Endpoint Routes
+ *
+ * Implements OAuth 2.0 authorization server endpoints for A2A authentication.
+ * Supports authorization_code, client_credentials, and refresh_token grants.
+ *
+ * Endpoints:
+ * - POST /oauth/token - Token exchange
+ * - GET /oauth/authorize - Authorization redirect (for authorization_code flow)
+ * - POST /oauth/revoke - Token revocation
+ * - GET /oauth/.well-known/openid-configuration - OpenID Connect discovery
+ *
+ * @module adapters/a2a/auth/routes
+ * @see https://datatracker.ietf.org/doc/html/rfc6749
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html
+ */
+import type { HttpRequest, HttpResponse, NextFunction } from '../discovery/routes.js';
+/**
+ * Supported OAuth 2.0 grant types
+ */
+export type GrantType = 'authorization_code' | 'refresh_token' | 'client_credentials';
+/**
+ * Token request body
+ */
+export interface TokenRequest {
+    /** OAuth 2.0 grant type */
+    readonly grant_type: GrantType;
+    /** Authorization code (for authorization_code grant) */
+    readonly code?: string;
+    /** Refresh token (for refresh_token grant) */
+    readonly refresh_token?: string;
+    /** Client ID */
+    readonly client_id: string;
+    /** Client secret (optional for public clients) */
+    readonly client_secret?: string;
+    /** Requested scope (space-separated) */
+    readonly scope?: string;
+    /** Redirect URI (for authorization_code grant) */
+    readonly redirect_uri?: string;
+    /** PKCE code verifier */
+    readonly code_verifier?: string;
+}
+/**
+ * Token response
+ */
+export interface TokenResponse {
+    /** Access token */
+    readonly access_token: string;
+    /** Token type (always "Bearer") */
+    readonly token_type: 'Bearer';
+    /** Token expiration in seconds */
+    readonly expires_in: number;
+    /** Refresh token (if issued) */
+    readonly refresh_token?: string;
+    /** Granted scope (space-separated) */
+    readonly scope?: string;
+    /** ID token (if OpenID Connect) */
+    readonly id_token?: string;
+}
+/**
+ * Authorization request query parameters
+ */
+export interface AuthorizationRequest {
+    /** Response type (code, token, or id_token) */
+    readonly response_type: 'code' | 'token' | 'id_token' | 'code id_token' | 'code token' | 'token id_token' | 'code token id_token';
+    /** Client ID */
+    readonly client_id: string;
+    /** Redirect URI */
+    readonly redirect_uri: string;
+    /** Requested scope (space-separated) */
+    readonly scope?: string;
+    /** State parameter (CSRF protection) */
+    readonly state?: string;
+    /** Nonce (for OpenID Connect) */
+    readonly nonce?: string;
+    /** PKCE code challenge */
+    readonly code_challenge?: string;
+    /** PKCE code challenge method */
+    readonly code_challenge_method?: 'plain' | 'S256';
+    /** Login hint */
+    readonly login_hint?: string;
+    /** Prompt behavior */
+    readonly prompt?: 'none' | 'login' | 'consent' | 'select_account';
+}
+/**
+ * Token revocation request
+ */
+export interface RevokeRequest {
+    /** Token to revoke */
+    readonly token: string;
+    /** Token type hint (access_token or refresh_token) */
+    readonly token_type_hint?: 'access_token' | 'refresh_token';
+    /** Client ID */
+    readonly client_id?: string;
+    /** Client secret */
+    readonly client_secret?: string;
+}
+/**
+ * OpenID Connect discovery document
+ */
+export interface OpenIDConfiguration {
+    readonly issuer: string;
+    readonly authorization_endpoint: string;
+    readonly token_endpoint: string;
+    readonly revocation_endpoint: string;
+    readonly jwks_uri: string;
+    readonly response_types_supported: string[];
+    readonly grant_types_supported: string[];
+    readonly subject_types_supported: string[];
+    readonly id_token_signing_alg_values_supported: string[];
+    readonly scopes_supported: string[];
+    readonly token_endpoint_auth_methods_supported: string[];
+    readonly claims_supported: string[];
+    readonly code_challenge_methods_supported: string[];
+}
+/**
+ * OAuth 2.0 provider interface
+ * Implement this to integrate with your authentication system
+ */
+export interface OAuth2Provider {
+    /** Validate client credentials */
+    validateClient(clientId: string, clientSecret?: string): Promise<boolean>;
+    /** Exchange authorization code for tokens */
+    exchangeAuthorizationCode(code: string, clientId: string, redirectUri: string, codeVerifier?: string): Promise<TokenResponse>;
+    /** Exchange client credentials for tokens */
+    exchangeClientCredentials(clientId: string, clientSecret: string, scope?: string): Promise<TokenResponse>;
+    /** Refresh an access token */
+    refreshToken(refreshToken: string, clientId: string): Promise<TokenResponse>;
+    /** Revoke a token */
+    revokeToken(token: string, tokenTypeHint?: 'access_token' | 'refresh_token'): Promise<void>;
+    /** Generate authorization code (for authorization endpoint) */
+    generateAuthorizationCode?(clientId: string, redirectUri: string, scope: string, state?: string, codeChallenge?: string, codeChallengeMethod?: 'plain' | 'S256'): Promise<{
+        code: string;
+        expiresIn: number;
+    }>;
+    /** Get OpenID configuration */
+    getOpenIDConfiguration(): OpenIDConfiguration;
+}
+/**
+ * Route definition for router setup
+ */
+export interface OAuthRouteDefinition {
+    readonly method: 'get' | 'post' | 'options';
+    readonly path: string;
+    readonly handler: (req: HttpRequest, res: HttpResponse, next?: NextFunction) => Promise<void>;
+}
+/**
+ * OAuth routes configuration
+ */
+export interface OAuthRoutesConfig {
+    /** OAuth 2.0 provider implementation */
+    readonly provider: OAuth2Provider;
+    /** Base path for routes (default: /oauth) */
+    readonly basePath?: string;
+    /** Enable CORS headers */
+    readonly enableCors?: boolean;
+    /** Login page URL for authorization redirect */
+    readonly loginPageUrl?: string;
+}
+/**
+ * Default OAuth routes configuration
+ */
+export declare const DEFAULT_OAUTH_ROUTES_CONFIG: {
+    readonly basePath: "/oauth";
+    readonly enableCors: true;
+    readonly loginPageUrl: "/login";
+};
+/**
+ * Get OAuth route definitions
+ *
+ * Returns an array of route definitions that can be used to setup routes
+ * in Express or any compatible HTTP framework.
+ *
+ * @param config OAuth routes configuration
+ * @returns Array of route definitions
+ *
+ * @example
+ * ```typescript
+ * const routeDefs = getOAuthRouteDefinitions({
+ *   provider: myOAuthProvider,
+ * });
+ *
+ * // Setup in custom router
+ * for (const route of routeDefs) {
+ *   router.add(route.method, route.path, route.handler);
+ * }
+ * ```
+ */
+export declare function getOAuthRouteDefinitions(config: OAuthRoutesConfig): OAuthRouteDefinition[];
+/**
+ * Create OAuth routes for Express
+ *
+ * NOTE: This function requires Express to be installed separately.
+ * If Express is not available, use getOAuthRouteDefinitions() instead.
+ *
+ * @param config OAuth routes configuration
+ * @returns Express router
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createOAuthRoutes } from '@agentic-qe/v3';
+ *
+ * const app = express();
+ * const oauthRouter = createOAuthRoutes({
+ *   provider: myOAuthProvider,
+ * });
+ *
+ * app.use(oauthRouter);
+ * ```
+ */
+export declare function createOAuthRoutes(config: OAuthRoutesConfig): {
+    stack: Array<{
+        route?: {
+            path?: string;
+        };
+    }>;
+} & Record<string, unknown>;
+/**
+ * Validate redirect URI against allowed URIs
+ *
+ * @param uri URI to validate
+ * @param allowedUris List of allowed URIs (supports wildcards)
+ * @returns True if URI is allowed
+ */
+export declare function validateRedirectUri(uri: string, allowedUris: string[]): boolean;
+/**
+ * Generate PKCE code challenge from verifier
+ *
+ * @param verifier Code verifier string
+ * @param method Challenge method (plain or S256)
+ * @returns Code challenge
+ */
+export declare function generateCodeChallenge(verifier: string, method?: 'plain' | 'S256'): Promise<string>;
+/**
+ * Verify PKCE code challenge
+ *
+ * @param verifier Code verifier from token request
+ * @param challenge Original code challenge from authorization
+ * @param method Challenge method
+ * @returns True if verification passes
+ */
+export declare function verifyCodeChallenge(verifier: string, challenge: string, method?: 'plain' | 'S256'): Promise<boolean>;
+//# sourceMappingURL=routes.d.ts.map

package/v3/dist/adapters/a2a/auth/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2a/auth/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAOtF;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,oBAAoB,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEtF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,gBAAgB;IAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,eAAe,GAAG,YAAY,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;IAClI,gBAAgB;IAChB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mBAAmB;IACnB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,iCAAiC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClD,iBAAiB;IACjB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,gBAAgB,CAAC;CACnE;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,eAAe,CAAC,EAAE,cAAc,GAAG,eAAe,CAAC;IAC5D,gBAAgB;IAChB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,qBAAqB,EAAE,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,qCAAqC,EAAE,MAAM,EAAE,CAAC;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,qCAAqC,EAAE,MAAM,EAAE,CAAC;IACzD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,gCAAgC,EAAE,MAAM,EAAE,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1E,6CAA6C;IAC7C,yBAAyB,CACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B,6CAA6C;IAC7C,yBAAyB,CACvB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B,8BAA8B;IAC9B,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7E,qBAAqB;IACrB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5F,+DAA+D;IAC/D,yBAAyB,CAAC,CACxB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,mBAAmB,CAAC,EAAE,OAAO,GAAG,MAAM,GACrC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEhD,+BAA+B;IAC/B,sBAAsB,IAAI,mBAAmB,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/F;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAMD;;GAEG;AACH,eAAO,MAAM,2BAA2B;;;;CAI9B,CAAC;AAoVX;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,EAAE,CA4D1F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,GACxB;IAAE,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiB3E;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAwC/E;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,OAAO,GAAG,MAAe,GAChC,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,OAAO,GAAG,MAAe,GAChC,OAAO,CAAC,OAAO,CAAC,CAGlB"}