qa360 2.3.0 → 2.3.1

package/dist/core/auth/oauth2-provider.js

@@ -0,0 +1,227 @@
+/**
+ * OAuth2 Authentication Provider
+ *
+ * Handles OAuth2 authentication with support for:
+ * - Client credentials grant
+ * - Password grant (resource owner)
+ * - Authorization code grant (requires pre-issued code)
+ *
+ * P0: Refresh token support for automatic token renewal
+ */
+import { authCache, createCacheKey } from './index.js';
+export class OAuth2Provider {
+    type = 'oauth2';
+    async authenticate(config) {
+        const cacheKey = this.getCacheKey(config);
+        // Check cache first
+        if (config.cache?.enabled !== false) {
+            const cached = authCache.get(cacheKey);
+            if (cached) {
+                // P0: Check if token is expired and auto_refresh is enabled
+                if (config.auto_refresh && cached.expiresAt && cached.expiresAt < Date.now()) {
+                    // Token expired, try to refresh
+                    if (cached.refreshToken || config.refresh_token) {
+                        const refreshResult = await this.refresh(config);
+                        if (refreshResult.success) {
+                            return refreshResult;
+                        }
+                    }
+                }
+                return { success: true, credentials: cached };
+            }
+        }
+        // If we have a refresh_token in config, use refresh flow
+        if (config.refresh_token && config.grant_type !== 'refresh_token') {
+            return this.performRefresh(config);
+        }
+        // Prepare token request based on grant type
+        const grantType = config.grant_type || 'client_credentials';
+        const body = {
+            grant_type: grantType,
+            client_id: config.client_id,
+        };
+        // Add client secret for most grants (except some implicit flows)
+        if (config.client_secret) {
+            body.client_secret = config.client_secret;
+        }
+        // Grant-specific parameters
+        if (grantType === 'password') {
+            if (!config.username || !config.password) {
+                return {
+                    success: false,
+                    error: 'Username and password required for password grant'
+                };
+            }
+            body.username = config.username;
+            body.password = config.password;
+        }
+        if (config.scopes && config.scopes.length > 0) {
+            body.scope = config.scopes.join(' ');
+        }
+        try {
+            const response = await fetch(config.token_url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: new URLSearchParams(body).toString(),
+            });
+            if (!response.ok) {
+                const error = await response.text().catch(() => 'Unknown error');
+                return {
+                    success: false,
+                    error: `OAuth2 token request failed: ${response.status} ${error}`
+                };
+            }
+            const data = await response.json();
+            const token = data.access_token;
+            if (!token) {
+                return {
+                    success: false,
+                    error: 'No access_token in OAuth2 response'
+                };
+            }
+            // Calculate expiration
+            let expiresAt;
+            if (data.expires_in) {
+                expiresAt = Date.now() + data.expires_in * 1000;
+            }
+            const credentials = {
+                type: 'oauth2',
+                headers: {
+                    'Authorization': `Bearer ${token}`
+                },
+                // P0: Store refresh token for later use
+                refreshToken: data.refresh_token,
+                expiresAt,
+            };
+            // Cache if enabled
+            if (config.cache?.enabled !== false) {
+                const ttl = config.cache?.ttl || data.expires_in || 3600;
+                authCache.set(cacheKey, credentials, ttl);
+            }
+            return {
+                success: true,
+                credentials,
+                expiresAt
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `OAuth2 request failed: ${error.message}`
+            };
+        }
+    }
+    /**
+     * P0: Refresh OAuth2 access token using refresh token
+     */
+    async refresh(config) {
+        return this.performRefresh(config);
+    }
+    /**
+     * P0: Perform refresh token flow
+     */
+    async performRefresh(config) {
+        const cacheKey = this.getCacheKey(config);
+        // Get refresh token from config or cached credentials
+        let refreshToken = config.refresh_token;
+        if (!refreshToken && config.cache?.enabled !== false) {
+            const cached = authCache.get(cacheKey);
+            if (cached?.refreshToken) {
+                refreshToken = cached.refreshToken;
+            }
+        }
+        if (!refreshToken) {
+            // No refresh token available, fall back to full authentication
+            return this.authenticate({ ...config, refresh_token: undefined });
+        }
+        // Prepare refresh token request
+        const body = {
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            client_id: config.client_id,
+        };
+        if (config.client_secret) {
+            body.client_secret = config.client_secret;
+        }
+        if (config.scopes && config.scopes.length > 0) {
+            body.scope = config.scopes.join(' ');
+        }
+        const tokenUrl = config.refresh_url || config.token_url;
+        try {
+            const response = await fetch(tokenUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: new URLSearchParams(body).toString(),
+            });
+            if (!response.ok) {
+                const error = await response.text().catch(() => 'Unknown error');
+                // Refresh token failed - might be expired, try full auth
+                const fullAuthResult = await this.authenticate({ ...config, refresh_token: undefined });
+                return fullAuthResult;
+            }
+            const data = await response.json();
+            const token = data.access_token;
+            if (!token) {
+                return {
+                    success: false,
+                    error: 'No access_token in OAuth2 refresh response'
+                };
+            }
+            // Calculate expiration
+            let expiresAt;
+            if (data.expires_in) {
+                expiresAt = Date.now() + data.expires_in * 1000;
+            }
+            // Use new refresh token if provided (rotation), otherwise keep existing
+            const newRefreshToken = data.refresh_token || refreshToken;
+            const credentials = {
+                type: 'oauth2',
+                headers: {
+                    'Authorization': `Bearer ${token}`
+                },
+                refreshToken: newRefreshToken,
+                expiresAt,
+            };
+            // Update cache
+            if (config.cache?.enabled !== false) {
+                const ttl = config.cache?.ttl || data.expires_in || 3600;
+                authCache.set(cacheKey, credentials, ttl);
+            }
+            return {
+                success: true,
+                credentials,
+                expiresAt
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `OAuth2 refresh failed: ${error.message}`
+            };
+        }
+    }
+    clear(config) {
+        const key = this.getCacheKey(config);
+        authCache.clear(key);
+        return Promise.resolve();
+    }
+    async validate(config) {
+        const key = this.getCacheKey(config);
+        const cached = authCache.get(key);
+        if (!cached) {
+            return false;
+        }
+        // Check if token is expired
+        if (cached.expiresAt && cached.expiresAt < Date.now()) {
+            return false;
+        }
+        return true;
+    }
+    getCacheKey(config) {
+        return createCacheKey('oauth2', config.client_id);
+    }
+}

package/dist/core/auth/otp-provider.d.ts

@@ -0,0 +1,93 @@
+/**
+ * OTP (One-Time Password) Authentication Provider
+ *
+ * Handles OTP-based authentication including:
+ * - SMS OTP: One-time passwords sent via SMS
+ * - Email OTP: One-time passwords sent via email
+ * - Magic Links: Login links sent via email
+ *
+ * P1 Feature: OTP-based authentication is widely used for 2FA and passwordless flows
+ */
+import type { AuthProvider, AuthResult } from './index.js';
+import { type OTPAuthConfig } from './index.js';
+/**
+ * OTP delivery method
+ */
+export type OTPDeliveryMethod = 'sms' | 'email' | 'magic_link';
+/**
+ * Generates a random OTP code
+ * @param digits Number of digits (default 6)
+ */
+export declare function generateOTP(digits?: number): string;
+/**
+ * Validates OTP format
+ * @param code OTP code to validate
+ * @param digits Expected number of digits
+ */
+export declare function validateOTPFormat(code: string, digits?: number): boolean;
+/**
+ * Generates a magic link URL
+ * @param baseUrl Base URL of the application
+ * @param token Authentication token
+ * @param email User email
+ */
+export declare function generateMagicLink(baseUrl: string, token: string, email: string): string;
+/**
+ * Extracts token from magic link URL
+ * @param url Magic link URL
+ */
+export declare function extractTokenFromMagicLink(url: string): string | null;
+/**
+ * OTP Authentication Provider
+ */
+export declare class OTPProvider implements AuthProvider<OTPAuthConfig> {
+    readonly type: "otp";
+    private otpStates;
+    private maxAttempts;
+    authenticate(config: OTPAuthConfig): Promise<AuthResult>;
+    /**
+     * Requests a new OTP to be sent
+     */
+    requestOTP(config: OTPAuthConfig): Promise<AuthResult>;
+    /**
+     * Verifies an OTP code
+     */
+    verifyOTP(config: OTPAuthConfig): Promise<AuthResult>;
+    /**
+     * Verifies a magic link
+     */
+    verifyMagicLink(config: OTPAuthConfig): Promise<AuthResult>;
+    /**
+     * Generates a session token
+     */
+    private generateSessionToken;
+    /**
+     * Validates OTP configuration
+     */
+    validate(config: OTPAuthConfig): Promise<boolean>;
+    /**
+     * Clears cached OTP state
+     */
+    clear(config: OTPAuthConfig): Promise<void>;
+    /**
+     * Gets remaining time for OTP expiration
+     */
+    getOTPTimeRemaining(destination: string): number | null;
+    /**
+     * Gets remaining attempts for OTP verification
+     */
+    getRemainingAttempts(destination: string): number;
+    /**
+     * Sets maximum verification attempts
+     */
+    setMaxAttempts(max: number): void;
+    /**
+     * Clears all OTP states
+     */
+    clearAllStates(): void;
+    private getCacheKey;
+}
+/**
+ * Creates an OTP auth provider instance
+ */
+export declare function createOTPProvider(): OTPProvider;

package/dist/core/auth/otp-provider.js

@@ -0,0 +1,288 @@
+/**
+ * OTP (One-Time Password) Authentication Provider
+ *
+ * Handles OTP-based authentication including:
+ * - SMS OTP: One-time passwords sent via SMS
+ * - Email OTP: One-time passwords sent via email
+ * - Magic Links: Login links sent via email
+ *
+ * P1 Feature: OTP-based authentication is widely used for 2FA and passwordless flows
+ */
+import { createCacheKey, authCache } from './index.js';
+/**
+ * Generates a random OTP code
+ * @param digits Number of digits (default 6)
+ */
+export function generateOTP(digits = 6) {
+    const min = Math.pow(10, digits - 1);
+    const max = Math.pow(10, digits) - 1;
+    return Math.floor(min + Math.random() * (max - min + 1)).toString().padStart(digits, '0');
+}
+/**
+ * Validates OTP format
+ * @param code OTP code to validate
+ * @param digits Expected number of digits
+ */
+export function validateOTPFormat(code, digits = 6) {
+    const regex = new RegExp(`^\\d{${digits}}$`);
+    return regex.test(code);
+}
+/**
+ * Generates a magic link URL
+ * @param baseUrl Base URL of the application
+ * @param token Authentication token
+ * @param email User email
+ */
+export function generateMagicLink(baseUrl, token, email) {
+    const url = new URL(baseUrl);
+    url.searchParams.set('token', token);
+    url.searchParams.set('email', email);
+    return url.toString();
+}
+/**
+ * Extracts token from magic link URL
+ * @param url Magic link URL
+ */
+export function extractTokenFromMagicLink(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.searchParams.get('token');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * OTP Authentication Provider
+ */
+export class OTPProvider {
+    type = 'otp';
+    otpStates = new Map();
+    maxAttempts = 3;
+    async authenticate(config) {
+        const { method, destination, code, magicLinkUrl, verifyEndpoint, headers } = config;
+        if (!destination) {
+            return {
+                success: false,
+                error: `${method} destination is required`
+            };
+        }
+        const cacheKey = this.getCacheKey(config);
+        // If code is provided, verify it
+        if (code) {
+            return this.verifyOTP(config);
+        }
+        // If magic link URL is provided, extract token
+        if (magicLinkUrl && method === 'magic_link') {
+            return this.verifyMagicLink(config);
+        }
+        // Otherwise, request a new OTP
+        return this.requestOTP(config);
+    }
+    /**
+     * Requests a new OTP to be sent
+     */
+    async requestOTP(config) {
+        const { method, destination, requestEndpoint, headers: customHeaders } = config;
+        // In a real implementation, this would call an API to send the OTP
+        // For now, we simulate the OTP generation
+        const otp = generateOTP(6);
+        const expiresAt = Date.now() + 5 * 60 * 1000; // 5 minutes
+        // Store OTP state (in production, this would be on the server)
+        this.otpStates.set(destination, {
+            code: otp,
+            expiresAt,
+            attempts: 0,
+        });
+        // Simulate API call if endpoint provided
+        if (requestEndpoint) {
+            // In real implementation, would make HTTP request
+            console.log(`[OTP Mock] Sending ${method} to ${destination}: ${otp}`);
+        }
+        return {
+            success: true,
+            credentials: {
+                type: 'otp',
+                headers: {
+                    'X-OTP-Destination': destination,
+                    'X-OTP-Method': method,
+                },
+            },
+        };
+    }
+    /**
+     * Verifies an OTP code
+     */
+    async verifyOTP(config) {
+        const { destination, code, verifyEndpoint } = config;
+        if (!code) {
+            return {
+                success: false,
+                error: 'OTP code is required for verification'
+            };
+        }
+        // Check local state
+        const state = this.otpStates.get(destination);
+        if (!state) {
+            return {
+                success: false,
+                error: 'No OTP requested for this destination'
+            };
+        }
+        // Check expiration
+        if (Date.now() > state.expiresAt) {
+            this.otpStates.delete(destination);
+            return {
+                success: false,
+                error: 'OTP has expired'
+            };
+        }
+        // Check attempts
+        if (state.attempts >= this.maxAttempts) {
+            this.otpStates.delete(destination);
+            return {
+                success: false,
+                error: 'Maximum verification attempts exceeded'
+            };
+        }
+        // Increment attempts
+        state.attempts++;
+        // Verify code
+        if (code !== state.code) {
+            return {
+                success: false,
+                error: 'Invalid OTP code',
+            };
+        }
+        // Success - clean up state
+        this.otpStates.delete(destination);
+        // Generate a session token
+        const token = this.generateSessionToken();
+        return {
+            success: true,
+            credentials: {
+                type: 'otp',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                },
+            },
+            expiresAt: Date.now() + 24 * 60 * 60 * 1000, // 24 hours
+        };
+    }
+    /**
+     * Verifies a magic link
+     */
+    async verifyMagicLink(config) {
+        const { magicLinkUrl, destination } = config;
+        if (!magicLinkUrl) {
+            return {
+                success: false,
+                error: 'Magic link URL is required'
+            };
+        }
+        const token = extractTokenFromMagicLink(magicLinkUrl);
+        if (!token) {
+            return {
+                success: false,
+                error: 'Invalid magic link URL'
+            };
+        }
+        // In a real implementation, verify token with server
+        // For now, accept any valid-looking token
+        if (token.length < 10) {
+            return {
+                success: false,
+                error: 'Invalid magic link token'
+            };
+        }
+        return {
+            success: true,
+            credentials: {
+                type: 'otp',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                },
+            },
+            expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+        };
+    }
+    /**
+     * Generates a session token
+     */
+    generateSessionToken() {
+        const crypto = require('node:crypto');
+        return crypto.randomBytes(32).toString('hex');
+    }
+    /**
+     * Validates OTP configuration
+     */
+    async validate(config) {
+        if (!config.destination) {
+            return false;
+        }
+        if (config.method === 'sms') {
+            // Validate phone number format (basic)
+            return /^[\d\s+()-]{10,}$/.test(config.destination);
+        }
+        if (config.method === 'email' || config.method === 'magic_link') {
+            // Validate email format
+            return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(config.destination);
+        }
+        return false;
+    }
+    /**
+     * Clears cached OTP state
+     */
+    async clear(config) {
+        const key = this.getCacheKey(config);
+        authCache.clear(key);
+        this.otpStates.delete(config.destination);
+    }
+    /**
+     * Gets remaining time for OTP expiration
+     */
+    getOTPTimeRemaining(destination) {
+        const state = this.otpStates.get(destination);
+        if (!state)
+            return null;
+        const remaining = state.expiresAt - Date.now();
+        return remaining > 0 ? remaining : 0;
+    }
+    /**
+     * Gets remaining attempts for OTP verification
+     */
+    getRemainingAttempts(destination) {
+        const state = this.otpStates.get(destination);
+        if (!state)
+            return this.maxAttempts;
+        return this.maxAttempts - state.attempts;
+    }
+    /**
+     * Sets maximum verification attempts
+     */
+    setMaxAttempts(max) {
+        this.maxAttempts = max;
+    }
+    /**
+     * Clears all OTP states
+     */
+    clearAllStates() {
+        this.otpStates.clear();
+    }
+    getCacheKey(config) {
+        const crypto = require('node:crypto');
+        const hash = crypto
+            .createHash('sha256')
+            .update(`${config.method}:${config.destination}`)
+            .digest('hex')
+            .substring(0, 16);
+        return createCacheKey('otp', hash);
+    }
+}
+/**
+ * Creates an OTP auth provider instance
+ */
+export function createOTPProvider() {
+    return new OTPProvider();
+}
+// Types are exported from index.ts