qa360 2.2.20 → 2.3.1

package/dist/core/auth/oauth-handler.js

@@ -0,0 +1,636 @@
+/**
+ * QA360 OAuth Handler
+ *
+ * P0 Features: OAuth2/OIDC flow testing support
+ * - Authorization Code flow with PKCE
+ * - Implicit flow (legacy) - P1
+ * - Client Credentials flow
+ * - Refresh Token flow
+ * - Token storage and management
+ * - OpenID Connect support - P1
+ *
+ * Supports testing against:
+ * - Real OAuth providers (Google, GitHub, Auth0, etc.)
+ * - Mock OAuth servers for development
+ */
+import { createHash, randomBytes } from 'crypto';
+/**
+ * OAuth Handler class
+ */
+export class OAuthHandler {
+    context;
+    config;
+    accessToken = null;
+    refreshToken = null;
+    codeVerifier = null;
+    generatedState = null;
+    constructor(context, config) {
+        this.context = context;
+        this.config = config;
+    }
+    /**
+     * Generate random string for PKCE code verifier and state
+     * Uses cryptographically secure random bytes
+     */
+    generateRandomString(length = 32) {
+        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+        // Generate random bytes and map to character set
+        const randomValues = randomBytes(length);
+        let result = '';
+        for (let i = 0; i < length; i++) {
+            result += chars.charAt(randomValues[i] % chars.length);
+        }
+        return result;
+    }
+    /**
+     * Generate code challenge for PKCE
+     * Uses SHA256 to create challenge from verifier
+     */
+    generateCodeChallenge(verifier) {
+        // SHA-256 hash the verifier using Node.js crypto
+        const hash = createHash('sha256').update(verifier).digest('base64url');
+        return hash;
+    }
+    /**
+     * Build authorization URL
+     * P0: Construct the OAuth authorization URL with all required parameters
+     */
+    buildAuthorizationURL(options) {
+        const config = this.config;
+        const scope = typeof config.scope === 'string' ? config.scope : config.scope?.join(' ');
+        const state = options?.state || config.state || this.generateRandomString(32);
+        // Store state for verification
+        this.generatedState = state;
+        const params = new URLSearchParams({
+            response_type: config.responseType || 'code',
+            client_id: config.clientId,
+            redirect_uri: config.redirectUri,
+            scope: scope || '',
+            state,
+        });
+        // Add PKCE code challenge if using PKCE
+        if (config.usePKCE && options?.codeChallenge) {
+            params.append('code_challenge', options.codeChallenge);
+            params.append('code_challenge_method', 'S256');
+        }
+        return `${config.authEndpoint}?${params.toString()}`;
+    }
+    /**
+     * Start Authorization Code flow with PKCE
+     * P0: Begin OAuth login flow
+     *
+     * @returns Authorization URL to navigate user to
+     */
+    async startAuthorizationFlow() {
+        const verifier = this.generateRandomString(64);
+        this.codeVerifier = verifier;
+        const state = this.generateRandomString(32);
+        this.generatedState = state;
+        const challenge = this.generateCodeChallenge(verifier);
+        const authUrl = this.buildAuthorizationURL({ state, codeChallenge: challenge });
+        return {
+            authUrl,
+            verifier,
+            state,
+        };
+    }
+    /**
+     * Wait for OAuth callback
+     * P0: Wait for redirect to redirect_uri with code or error
+     *
+     * @returns Promise that resolves when callback is received
+     */
+    async waitForCallback(page, timeout = 60000) {
+        const redirectUri = new URL(this.config.redirectUri).pathname;
+        try {
+            // Wait for navigation to redirect URI
+            await page.waitForURL(`**${redirectUri}*`, { timeout });
+            // Get the URL parameters
+            const url = page.url();
+            const params = new URLSearchParams(url.split('?')[1] || '');
+            const code = params.get('code');
+            const error = params.get('error');
+            const errorDescription = params.get('error_description');
+            const state = params.get('state');
+            // Verify state if one was generated
+            if (this.generatedState && state !== this.generatedState) {
+                return {
+                    success: false,
+                    error: { error: 'invalid_state', error_description: 'State mismatch', state: state || undefined },
+                };
+            }
+            if (error) {
+                return {
+                    success: false,
+                    error: {
+                        error,
+                        error_description: errorDescription || undefined,
+                        state: state || undefined,
+                    },
+                };
+            }
+            return {
+                success: true,
+                code: code || undefined,
+                state: state || undefined,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: { error: 'timeout', error_description: 'Callback timeout' },
+            };
+        }
+    }
+    /**
+     * Exchange authorization code for tokens
+     * P0: Token exchange endpoint call
+     */
+    async exchangeCodeForToken(code) {
+        const config = this.config;
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: config.redirectUri,
+            client_id: config.clientId,
+        });
+        // Add client secret if provided (confidential clients)
+        if (config.clientSecret) {
+            body.append('client_secret', config.clientSecret);
+        }
+        // Add PKCE code verifier if using PKCE
+        if (config.usePKCE && this.codeVerifier) {
+            body.append('code_verifier', this.codeVerifier);
+        }
+        // Make token request
+        const response = await this.context.request.post(config.tokenEndpoint, {
+            data: body.toString(),
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+        });
+        if (!response.ok()) {
+            throw new Error(`Token request failed: ${response.status()} ${response.statusText()}`);
+        }
+        const token = await response.json();
+        // Store tokens
+        this.accessToken = token.access_token;
+        if (token.refresh_token) {
+            this.refreshToken = token.refresh_token;
+        }
+        return token;
+    }
+    /**
+     * Client Credentials flow
+     * P1: Server-to-server authentication without user interaction
+     * Used for machine-to-machine communication (service accounts, daemons, etc.)
+     *
+     * @returns OAuth token response (no refresh token in this flow)
+     */
+    async clientCredentials() {
+        const config = this.config;
+        if (!config.clientSecret) {
+            throw new Error('Client secret is required for Client Credentials flow');
+        }
+        const scope = typeof config.scope === 'string' ? config.scope : config.scope?.join(' ');
+        const body = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: config.clientId,
+            client_secret: config.clientSecret,
+        });
+        if (scope) {
+            body.append('scope', scope);
+        }
+        const response = await this.context.request.post(config.tokenEndpoint, {
+            data: body.toString(),
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+        });
+        if (!response.ok()) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new Error(`Client Credentials request failed: ${response.status()} ${response.statusText()} - ${errorText}`);
+        }
+        const token = await response.json();
+        // Store access token (no refresh token in Client Credentials flow)
+        this.accessToken = token.access_token;
+        return token;
+    }
+    /**
+     * Refresh access token
+     * P0: Use refresh token to get new access token
+     */
+    async refreshAccessToken() {
+        if (!this.refreshToken) {
+            throw new Error('No refresh token available');
+        }
+        const config = this.config;
+        const body = new URLSearchParams({
+            grant_type: 'refresh_token',
+            refresh_token: this.refreshToken,
+            client_id: config.clientId,
+        });
+        if (config.clientSecret) {
+            body.append('client_secret', config.clientSecret);
+        }
+        const response = await this.context.request.post(config.tokenEndpoint, {
+            data: body.toString(),
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+        });
+        if (!response.ok()) {
+            throw new Error(`Token refresh failed: ${response.status()} ${response.statusText()}`);
+        }
+        const token = await response.json();
+        // Update tokens
+        this.accessToken = token.access_token;
+        if (token.refresh_token) {
+            this.refreshToken = token.refresh_token;
+        }
+        return token;
+    }
+    /**
+     * Get current access token
+     */
+    getAccessToken() {
+        return this.accessToken;
+    }
+    /**
+     * Get refresh token
+     */
+    getRefreshToken() {
+        return this.refreshToken;
+    }
+    /**
+     * Set tokens manually (useful for testing)
+     */
+    setTokens(tokens) {
+        this.accessToken = tokens.accessToken;
+        this.refreshToken = tokens.refreshToken || null;
+    }
+    /**
+     * Clear all stored tokens
+     */
+    clearTokens() {
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.codeVerifier = null;
+        this.generatedState = null;
+    }
+    /**
+     * Full Authorization Code flow with PKCE
+     * P0: Complete OAuth flow from start to token exchange
+     *
+     * @param page - Playwright page instance
+     * @param userInteraction - Optional function to handle user login
+     * @returns OAuth token response
+     */
+    async completeFlow(page, userInteraction) {
+        // Start flow
+        const { authUrl, verifier, state } = await this.startAuthorizationFlow();
+        // Navigate to auth URL or call user interaction handler
+        if (userInteraction) {
+            await userInteraction(page, authUrl);
+        }
+        else {
+            await page.goto(authUrl);
+        }
+        // Wait for callback
+        const callback = await this.waitForCallback(page);
+        if (!callback.success || !callback.code) {
+            throw new Error(`OAuth flow failed: ${callback.error?.error || 'unknown'}`);
+        }
+        // Exchange code for token
+        return await this.exchangeCodeForToken(callback.code);
+    }
+    /**
+     * Set authorization header with Bearer token
+     * P0: Helper to set Authorization header for API requests
+     */
+    async setAuthHeader(page) {
+        if (!this.accessToken) {
+            throw new Error('No access token available. Call completeFlow() first.');
+        }
+        await page.setExtraHTTPHeaders({
+            Authorization: `Bearer ${this.accessToken}`,
+        });
+    }
+    /**
+     * P1: Implicit Flow (legacy OAuth2)
+     * Token is returned directly in URL fragment after redirect
+     *
+     * Note: Implicit flow is deprecated in OAuth 2.1. Use Authorization Code with PKCE instead.
+     * This method is provided for testing legacy applications.
+     *
+     * @param page - Playwright page instance
+     * @param userInteraction - Optional function to handle user login
+     * @returns Implicit flow result with access token from URL fragment
+     */
+    async implicitFlow(page, userInteraction) {
+        // Set response type to token for implicit flow
+        const originalResponseType = this.config.responseType;
+        this.config.responseType = 'token';
+        const state = this.generateRandomString(32);
+        this.generatedState = state;
+        const authUrl = this.buildAuthorizationURL({ state });
+        // Navigate to auth URL or call user interaction handler
+        if (userInteraction) {
+            await userInteraction(page, authUrl);
+        }
+        else {
+            await page.goto(authUrl);
+        }
+        // Wait for callback with token in fragment
+        const result = await this.waitForImplicitCallback(page);
+        // Restore original response type
+        this.config.responseType = originalResponseType;
+        if (result.success && result.accessToken) {
+            this.accessToken = result.accessToken;
+        }
+        return result;
+    }
+    /**
+     * P1: Wait for Implicit Flow callback
+     * Extracts token from URL fragment (hash)
+     */
+    async waitForImplicitCallback(page, timeout = 60000) {
+        const redirectUri = new URL(this.config.redirectUri).pathname;
+        try {
+            // Wait for navigation to redirect URI
+            await page.waitForURL(`**${redirectUri}*`, { timeout });
+            // Get URL fragment (hash) - tokens are in fragment for implicit flow
+            const fragment = await page.evaluate(() => window.location.hash.substring(1));
+            if (!fragment) {
+                // Also check query params for error
+                const url = page.url();
+                const params = new URLSearchParams(url.split('?')[1] || '');
+                const error = params.get('error');
+                const errorDescription = params.get('error_description');
+                const state = params.get('state');
+                return {
+                    success: false,
+                    error: {
+                        error: error || 'no_fragment',
+                        error_description: errorDescription || 'No fragment in callback URL',
+                        state: state || undefined,
+                    },
+                };
+            }
+            // Parse fragment parameters
+            const params = new URLSearchParams(fragment);
+            const accessToken = params.get('access_token');
+            const idToken = params.get('id_token');
+            const tokenType = params.get('token_type');
+            const expiresIn = params.get('expires_in');
+            const state = params.get('state');
+            const error = params.get('error');
+            const errorDescription = params.get('error_description');
+            // Verify state
+            if (this.generatedState && state !== this.generatedState) {
+                return {
+                    success: false,
+                    error: { error: 'invalid_state', error_description: 'State mismatch', state: state || undefined },
+                };
+            }
+            if (error) {
+                return {
+                    success: false,
+                    error: {
+                        error,
+                        error_description: errorDescription || undefined,
+                        state: state || undefined,
+                    },
+                };
+            }
+            return {
+                success: true,
+                accessToken: accessToken || undefined,
+                idToken: idToken || undefined,
+                tokenType: tokenType || undefined,
+                expires_in: expiresIn || undefined,
+                state: state || undefined,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: { error: 'timeout', error_description: 'Callback timeout' },
+            };
+        }
+    }
+    /**
+     * P1: OpenID Connect - Parse and validate ID token
+     *
+     * @param idToken - JWT ID token from OAuth response
+     * @returns Parsed OIDC claims
+     */
+    async parseIDToken(idToken) {
+        try {
+            // Split JWT into parts
+            const parts = idToken.split('.');
+            if (parts.length !== 3) {
+                throw new Error('Invalid ID token format');
+            }
+            // Decode payload (base64url)
+            const payload = parts[1];
+            // Add padding if needed
+            const paddedPayload = payload + '='.repeat((4 - payload.length % 4) % 4);
+            const decoded = Buffer.from(paddedPayload, 'base64url').toString('utf-8');
+            const claims = JSON.parse(decoded);
+            // Validate basic claims
+            if (!claims.iss || !claims.sub || !claims.aud || !claims.exp || !claims.iat) {
+                throw new Error('ID token missing required claims');
+            }
+            // Validate expiration
+            const now = Math.floor(Date.now() / 1000);
+            if (claims.exp < now) {
+                throw new Error('ID token has expired');
+            }
+            // Validate issuer if configured
+            const expectedIssuer = this.config.oidc?.expectedIssuer || this.config.oidc?.issuer;
+            if (expectedIssuer && claims.iss !== expectedIssuer) {
+                throw new Error(`ID token issuer mismatch: expected ${expectedIssuer}, got ${claims.iss}`);
+            }
+            // Validate audience if configured
+            const expectedAudience = this.config.oidc?.expectedAudience || this.config.clientId;
+            if (expectedAudience) {
+                const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+                if (!audiences.includes(expectedAudience) && !audiences.includes(this.config.clientId)) {
+                    throw new Error(`ID token audience mismatch: expected ${expectedAudience}, got ${claims.aud}`);
+                }
+            }
+            return claims;
+        }
+        catch (e) {
+            throw new Error(`Failed to parse ID token: ${e instanceof Error ? e.message : 'unknown error'}`);
+        }
+    }
+    /**
+     * P1: OpenID Connect - Fetch UserInfo from endpoint
+     *
+     * @param accessToken - Access token for authorization
+     * @returns UserInfo response
+     */
+    async fetchUserInfo(accessToken) {
+        const userInfoEndpoint = this.config.oidc?.userInfoEndpoint;
+        if (!userInfoEndpoint) {
+            throw new Error('UserInfo endpoint not configured');
+        }
+        const response = await this.context.request.get(userInfoEndpoint, {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+        });
+        if (!response.ok()) {
+            throw new Error(`UserInfo request failed: ${response.status()} ${response.statusText()}`);
+        }
+        return await response.json();
+    }
+    /**
+     * P1: OpenID Connect - Complete OIDC flow
+     * Performs Authorization Code flow and fetches UserInfo
+     *
+     * @param page - Playwright page instance
+     * @param userInteraction - Optional function to handle user login
+     * @returns OAuth token + parsed ID token claims + UserInfo
+     */
+    async completeOIDCFlow(page, userInteraction) {
+        // Ensure OpenID scope is included
+        const scopes = typeof this.config.scope === 'string'
+            ? this.config.scope.split(' ')
+            : this.config.scope || [];
+        if (!scopes.includes('openid')) {
+            scopes.push('openid');
+            this.config.scope = scopes.join(' ');
+        }
+        // Complete standard OAuth flow
+        const token = await this.completeFlow(page, userInteraction);
+        const result = { token };
+        // Parse ID token if present
+        if (token.id_token) {
+            try {
+                result.idTokenClaims = await this.parseIDToken(token.id_token);
+            }
+            catch (e) {
+                console.warn('Failed to parse ID token:', e);
+            }
+        }
+        // Fetch UserInfo if access token available
+        if (token.access_token && this.config.oidc?.userInfoEndpoint) {
+            try {
+                result.userInfo = await this.fetchUserInfo(token.access_token);
+            }
+            catch (e) {
+                console.warn('Failed to fetch UserInfo:', e);
+            }
+        }
+        return result;
+    }
+    /**
+     * P1: Validate ID token signature (basic validation)
+     * For full signature validation, you need the JWKS and crypto verification
+     *
+     * @param idToken - JWT ID token to validate
+     * @returns Validation result with claims if valid
+     */
+    async validateIDToken(idToken) {
+        try {
+            const claims = await this.parseIDToken(idToken);
+            // Note: Full signature validation requires JWKS and crypto verification
+            // This is a basic implementation that validates structure and timestamps
+            // For production use, implement full JWT signature verification with JWKS
+            return {
+                valid: true,
+                claims,
+            };
+        }
+        catch (e) {
+            return {
+                valid: false,
+                error: e instanceof Error ? e.message : 'Unknown validation error',
+            };
+        }
+    }
+}
+/**
+ * Mock OAuth Server for testing
+ * Simulates OAuth endpoints for development/testing
+ */
+export class MockOAuthServer {
+    baseUrl;
+    authorizedCodes = new Map();
+    constructor(baseUrl = 'http://localhost:3001') {
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * Get authorization endpoint URL
+     */
+    getAuthEndpoint() {
+        return `${this.baseUrl}/authorize`;
+    }
+    /**
+     * Get token endpoint URL
+     */
+    getTokenEndpoint() {
+        return `${this.baseUrl}/token`;
+    }
+    /**
+     * Generate a mock access token
+     */
+    generateMockToken(expiresIn = 3600) {
+        return {
+            access_token: `mock_token_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+            token_type: 'Bearer',
+            expires_in: expiresIn,
+            refresh_token: `mock_refresh_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+            scope: 'openid profile email',
+        };
+    }
+    /**
+     * Create a mock authorization code
+     * Stores code-to-token mapping for later exchange
+     */
+    createAuthorizationCode() {
+        const code = `mock_auth_code_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+        const token = this.generateMockToken();
+        this.authorizedCodes.set(code, token);
+        return { code, token };
+    }
+    /**
+     * Validate and redeem authorization code
+     */
+    redeemCode(code) {
+        const token = this.authorizedCodes.get(code);
+        if (token) {
+            this.authorizedCodes.delete(code); // One-time use
+            return token;
+        }
+        return null;
+    }
+    /**
+     * Get OAuth config for mock server
+     */
+    getOAuthConfig(clientId = 'mock-client-id', redirectUri = 'http://localhost:3000/callback') {
+        return {
+            authEndpoint: this.getAuthEndpoint(),
+            tokenEndpoint: this.getTokenEndpoint(),
+            clientId,
+            redirectUri,
+            responseType: 'code',
+            usePKCE: true,
+        };
+    }
+}
+/**
+ * Convenience function to create OAuth handler
+ */
+export function createOAuthHandler(context, config) {
+    return new OAuthHandler(context, config);
+}
+/**
+ * Convenience function to create mock OAuth server
+ */
+export function createMockOAuthServer(baseUrl) {
+    return new MockOAuthServer(baseUrl);
+}

package/{cli/dist → dist}/core/auth/oauth2-provider.d.ts

@@ -5,12 +5,21 @@
  * - Client credentials grant
  * - Password grant (resource owner)
  * - Authorization code grant (requires pre-issued code)
+ *
+ * P0: Refresh token support for automatic token renewal
  */
 import { AuthProvider, AuthResult, OAuth2AuthConfig } from './index.js';
 export declare class OAuth2Provider implements AuthProvider<OAuth2AuthConfig> {
     readonly type: "oauth2";
     authenticate(config: OAuth2AuthConfig): Promise<AuthResult>;
+    /**
+     * P0: Refresh OAuth2 access token using refresh token
+     */
     refresh(config: OAuth2AuthConfig): Promise<AuthResult>;
+    /**
+     * P0: Perform refresh token flow
+     */
+    private performRefresh;
     clear(config: OAuth2AuthConfig): Promise<void>;
     validate(config: OAuth2AuthConfig): Promise<boolean>;
     private getCacheKey;