@veloxts/auth 0.6.84 → 0.6.85

package/dist/adapters/auth0.js

@@ -0,0 +1,539 @@
+/**
+ * Auth0 Adapter for @veloxts/auth
+ *
+ * Integrates Auth0 (https://auth0.com) with VeloxTS's pluggable
+ * authentication system. Auth0 is an identity platform providing
+ * authentication and authorization services.
+ *
+ * This adapter uses JWKS (JSON Web Key Sets) for JWT verification,
+ * allowing secure token validation without sharing secrets.
+ *
+ * @module auth/adapters/auth0
+ *
+ * @example
+ * ```typescript
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ * import { createAuth0Adapter } from '@veloxts/auth/adapters/auth0';
+ *
+ * const adapter = createAuth0Adapter({
+ *   domain: process.env.AUTH0_DOMAIN!,
+ *   audience: process.env.AUTH0_AUDIENCE!,
+ *   clientId: process.env.AUTH0_CLIENT_ID,
+ * });
+ *
+ * // Simplified API - just pass the adapter
+ * const authPlugin = createAuthAdapterPlugin(adapter);
+ *
+ * app.use(authPlugin);
+ * ```
+ */
+import { AuthAdapterError, BaseAuthAdapter } from '../adapter.js';
+import { extractBearerToken, validateNonEmptyString } from './utils.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Default clock tolerance in seconds for JWT validation */
+const DEFAULT_CLOCK_TOLERANCE_SECONDS = 5;
+/** Default JWKS cache TTL in milliseconds (1 hour) */
+const DEFAULT_JWKS_CACHE_TTL_MS = 3600000;
+/** Minimum interval between JWKS refresh attempts in milliseconds (5 seconds) */
+const MIN_JWKS_REFRESH_INTERVAL_MS = 5000;
+class JWKSCache {
+    keys = new Map();
+    lastFetch = 0;
+    lastRefreshAttempt = 0;
+    refreshPromise = null;
+    ttl;
+    jwksUrl;
+    logger;
+    constructor(jwksUrl, ttl = DEFAULT_JWKS_CACHE_TTL_MS, logger) {
+        this.jwksUrl = jwksUrl;
+        this.ttl = ttl;
+        this.logger = logger;
+    }
+    async getKey(kid) {
+        const now = Date.now();
+        // Refresh cache if expired, but rate limit refresh attempts
+        const needsRefresh = now - this.lastFetch > this.ttl || this.keys.size === 0;
+        const canRefresh = now - this.lastRefreshAttempt > MIN_JWKS_REFRESH_INTERVAL_MS;
+        if (needsRefresh && canRefresh) {
+            // Use promise-based locking to prevent concurrent refreshes
+            if (!this.refreshPromise) {
+                this.lastRefreshAttempt = now;
+                this.refreshPromise = this.refresh().finally(() => {
+                    this.refreshPromise = null;
+                });
+            }
+            await this.refreshPromise;
+        }
+        return this.keys.get(kid) ?? null;
+    }
+    async refresh() {
+        try {
+            const response = await fetch(this.jwksUrl);
+            if (!response.ok) {
+                throw new Error(`JWKS fetch failed: ${response.status}`);
+            }
+            const data = (await response.json());
+            this.keys.clear();
+            for (const key of data.keys) {
+                if (key.kid) {
+                    this.keys.set(key.kid, key);
+                }
+            }
+            this.lastFetch = Date.now();
+        }
+        catch (error) {
+            // If we have cached keys, don't fail completely
+            if (this.keys.size > 0) {
+                this.logger?.('JWKS refresh failed, using cached keys');
+                return;
+            }
+            throw error;
+        }
+    }
+}
+// ============================================================================
+// Default JWT Verifier
+// ============================================================================
+/**
+ * Create a default JWT verifier using JWKS
+ *
+ * This implementation uses Web Crypto API for JWT verification
+ * to avoid external dependencies like 'jose'.
+ *
+ * @internal
+ */
+function createDefaultVerifier(domain, audience, issuer, clockTolerance, cacheTtl, logger) {
+    const jwksUrl = `https://${domain}/.well-known/jwks.json`;
+    const cache = new JWKSCache(jwksUrl, cacheTtl, logger);
+    return {
+        async verify(token) {
+            // Parse the JWT
+            const parts = token.split('.');
+            if (parts.length !== 3) {
+                throw new Error('Invalid JWT format');
+            }
+            // Decode and validate header structure
+            const headerJson = base64UrlDecode(parts[0]);
+            const header = parseAndValidateHeader(headerJson);
+            if (header.alg !== 'RS256') {
+                throw new Error(`Unsupported algorithm: ${header.alg}`);
+            }
+            if (!header.kid) {
+                throw new Error('Missing kid in token header');
+            }
+            // Get the signing key from JWKS
+            const key = await cache.getKey(header.kid);
+            if (!key) {
+                throw new Error(`Unknown signing key: ${header.kid}`);
+            }
+            // Verify signature using Web Crypto
+            const isValid = await verifyRS256Signature(token, key);
+            if (!isValid) {
+                throw new Error('Invalid token signature');
+            }
+            // Decode and validate claims structure
+            const payloadJson = base64UrlDecode(parts[1]);
+            const claims = parseAndValidateClaims(payloadJson);
+            const now = Math.floor(Date.now() / 1000);
+            // Validate expiration
+            if (claims.exp && claims.exp + clockTolerance < now) {
+                throw new Error('Token has expired');
+            }
+            // Validate not before
+            if (claims.nbf && claims.nbf - clockTolerance > now) {
+                throw new Error('Token not yet valid');
+            }
+            // Validate issuer
+            if (claims.iss !== issuer) {
+                throw new Error(`Invalid issuer: expected ${issuer}, got ${claims.iss}`);
+            }
+            // Validate audience
+            const audiences = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
+            if (!audiences.includes(audience)) {
+                throw new Error(`Invalid audience: expected ${audience}`);
+            }
+            return claims;
+        },
+    };
+}
+/**
+ * Base64URL decode
+ *
+ * @internal
+ */
+function base64UrlDecode(str) {
+    // Replace URL-safe characters
+    const base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+    // Pad if necessary
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+    // Decode
+    return Buffer.from(padded, 'base64').toString('utf-8');
+}
+/**
+ * Parse and validate JWT header structure
+ *
+ * @param headerJson - JSON string of the JWT header
+ * @returns Validated JWT header
+ * @throws Error if header is malformed or missing required fields
+ *
+ * @internal
+ */
+function parseAndValidateHeader(headerJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(headerJson);
+    }
+    catch {
+        throw new Error('Invalid JWT format - malformed header JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('Invalid JWT format - header must be an object');
+    }
+    const header = parsed;
+    if (typeof header.alg !== 'string') {
+        throw new Error('Invalid JWT format - missing or invalid alg in header');
+    }
+    if (typeof header.kid !== 'string') {
+        throw new Error('Invalid JWT format - missing or invalid kid in header');
+    }
+    return {
+        alg: header.alg,
+        kid: header.kid,
+        typ: typeof header.typ === 'string' ? header.typ : undefined,
+    };
+}
+/**
+ * Parse and validate JWT claims structure
+ *
+ * Validates that required Auth0 JWT claims are present and have correct types.
+ *
+ * @param payloadJson - JSON string of the JWT payload
+ * @returns Validated Auth0 claims
+ * @throws Error if payload is malformed or missing required fields
+ *
+ * @internal
+ */
+function parseAndValidateClaims(payloadJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(payloadJson);
+    }
+    catch {
+        throw new Error('Invalid JWT format - malformed payload JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('Invalid JWT format - payload must be an object');
+    }
+    const payload = parsed;
+    // Validate required claims
+    if (typeof payload.sub !== 'string') {
+        throw new Error('Invalid JWT claims - missing or invalid sub');
+    }
+    if (typeof payload.iat !== 'number') {
+        throw new Error('Invalid JWT claims - missing or invalid iat');
+    }
+    if (typeof payload.exp !== 'number') {
+        throw new Error('Invalid JWT claims - missing or invalid exp');
+    }
+    if (typeof payload.iss !== 'string') {
+        throw new Error('Invalid JWT claims - missing or invalid iss');
+    }
+    if (payload.aud !== undefined && typeof payload.aud !== 'string' && !Array.isArray(payload.aud)) {
+        throw new Error('Invalid JWT claims - invalid aud format');
+    }
+    // Build validated claims object
+    const claims = {
+        sub: payload.sub,
+        iat: payload.iat,
+        exp: payload.exp,
+        iss: payload.iss,
+        aud: payload.aud,
+    };
+    // Add optional claims if present and valid
+    if (typeof payload.nbf === 'number') {
+        claims.nbf = payload.nbf;
+    }
+    if (typeof payload.azp === 'string') {
+        claims.azp = payload.azp;
+    }
+    if (typeof payload.scope === 'string') {
+        claims.scope = payload.scope;
+    }
+    if (Array.isArray(payload.permissions)) {
+        claims.permissions = payload.permissions;
+    }
+    if (typeof payload.org_id === 'string') {
+        claims.org_id = payload.org_id;
+    }
+    if (typeof payload.org_name === 'string') {
+        claims.org_name = payload.org_name;
+    }
+    if (typeof payload.email === 'string') {
+        claims.email = payload.email;
+    }
+    if (typeof payload.email_verified === 'boolean') {
+        claims.email_verified = payload.email_verified;
+    }
+    if (typeof payload.name === 'string') {
+        claims.name = payload.name;
+    }
+    if (typeof payload.nickname === 'string') {
+        claims.nickname = payload.nickname;
+    }
+    if (typeof payload.picture === 'string') {
+        claims.picture = payload.picture;
+    }
+    if (typeof payload.updated_at === 'string') {
+        claims.updated_at = payload.updated_at;
+    }
+    return claims;
+}
+/**
+ * Verify RS256 signature using Web Crypto API
+ *
+ * @internal
+ */
+async function verifyRS256Signature(token, jwk) {
+    const parts = token.split('.');
+    const signatureInput = `${parts[0]}.${parts[1]}`;
+    const signature = base64UrlToArrayBuffer(parts[2]);
+    // Import the public key
+    const cryptoKey = await crypto.subtle.importKey('jwk', {
+        kty: jwk.kty,
+        n: jwk.n,
+        e: jwk.e,
+        alg: 'RS256',
+        use: 'sig',
+    }, {
+        name: 'RSASSA-PKCS1-v1_5',
+        hash: 'SHA-256',
+    }, false, ['verify']);
+    // Verify the signature
+    const encoder = new TextEncoder();
+    return crypto.subtle.verify('RSASSA-PKCS1-v1_5', cryptoKey, signature, encoder.encode(signatureInput));
+}
+/**
+ * Convert base64url string to ArrayBuffer
+ *
+ * @internal
+ */
+function base64UrlToArrayBuffer(str) {
+    const base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+    const binary = Buffer.from(padded, 'base64');
+    return binary.buffer.slice(binary.byteOffset, binary.byteOffset + binary.byteLength);
+}
+// ============================================================================
+// Auth0 Adapter Implementation
+// ============================================================================
+/**
+ * Auth0 Adapter
+ *
+ * Integrates Auth0 with VeloxTS by:
+ * - Verifying Auth0 JWTs using JWKS
+ * - Extracting user data from token claims
+ * - Supporting Auth0 Organizations and RBAC
+ *
+ * @example
+ * ```typescript
+ * const adapter = new Auth0Adapter();
+ * const plugin = createAuthAdapterPlugin({
+ *   adapter,
+ *   config: {
+ *     name: 'auth0',
+ *     domain: 'your-tenant.auth0.com',
+ *     audience: 'https://your-api.example.com',
+ *   },
+ * });
+ * ```
+ */
+export class Auth0Adapter extends BaseAuthAdapter {
+    verifier = null;
+    domain = '';
+    clientId;
+    authHeader = 'authorization';
+    constructor() {
+        super('auth0', '1.0.0');
+    }
+    /**
+     * Initialize the adapter with Auth0 configuration
+     */
+    async initialize(fastify, config) {
+        await super.initialize(fastify, config);
+        // Validate required configuration using shared utility
+        try {
+            this.domain = validateNonEmptyString(config.domain, 'Auth0 domain');
+        }
+        catch {
+            throw new AuthAdapterError('Auth0 domain is required and cannot be empty', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        let audience;
+        try {
+            audience = validateNonEmptyString(config.audience, 'Auth0 audience');
+        }
+        catch {
+            throw new AuthAdapterError('Auth0 audience is required and cannot be empty', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        this.clientId = config.clientId;
+        this.authHeader = config.authHeader ?? 'authorization';
+        // Construct issuer URL
+        const issuer = config.issuer ?? `https://${this.domain}/`;
+        // Use custom verifier or create default
+        // Pass bound debug method directly to avoid closure overhead
+        this.verifier =
+            config.jwtVerifier ??
+                createDefaultVerifier(this.domain, audience, issuer, config.clockTolerance ?? DEFAULT_CLOCK_TOLERANCE_SECONDS, config.jwksCacheTtl ?? DEFAULT_JWKS_CACHE_TTL_MS, this.debug.bind(this));
+        this.debug(`Initialized with domain: ${this.domain}`);
+    }
+    /**
+     * Get session from Auth0 JWT
+     *
+     * Extracts the Bearer token from the Authorization header
+     * and verifies it using JWKS.
+     */
+    async getSession(request) {
+        if (!this.verifier) {
+            throw new AuthAdapterError('Auth0 adapter not initialized', 500, 'ADAPTER_NOT_CONFIGURED');
+        }
+        // Extract token from Authorization header
+        const authHeaderValue = request.headers[this.authHeader];
+        if (!authHeaderValue || typeof authHeaderValue !== 'string') {
+            this.debug('No authorization header found');
+            return null;
+        }
+        // Extract Bearer token
+        const token = extractBearerToken(authHeaderValue);
+        if (!token) {
+            this.debug('No Bearer token found in authorization header');
+            return null;
+        }
+        try {
+            // Verify the token
+            const claims = await this.verifier.verify(token);
+            this.debug(`Token verified for user: ${claims.sub}`);
+            // Validate azp if clientId is configured
+            if (this.clientId && claims.azp && claims.azp !== this.clientId) {
+                this.debug(`Invalid authorized party: expected ${this.clientId}, got ${claims.azp}`);
+                return null;
+            }
+            // Transform to VeloxTS format
+            return transformAuth0Session(claims);
+        }
+        catch (error) {
+            // Token verification failed
+            if (error instanceof Error) {
+                this.debug(`Token verification failed: ${error.message}`);
+            }
+            return null;
+        }
+    }
+    /**
+     * Get routes for Auth0
+     *
+     * Auth0 handles auth on the client side via their SDK.
+     * Server only needs to verify tokens, not handle auth routes.
+     *
+     * If you need to handle Auth0 webhooks or Actions callbacks,
+     * override this method.
+     */
+    getRoutes() {
+        return [];
+    }
+    /**
+     * Clean up adapter resources
+     */
+    async cleanup() {
+        await super.cleanup();
+        this.verifier = null;
+        this.debug('Adapter cleaned up');
+    }
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Transform Auth0 claims to VeloxTS format
+ *
+ * @param claims - Verified JWT claims
+ * @returns VeloxTS adapter session result
+ *
+ * @internal
+ */
+function transformAuth0Session(claims) {
+    // Generate a synthetic session ID from sub and iat
+    const sessionId = `${claims.sub}:${claims.iat}`;
+    return {
+        user: {
+            id: claims.sub,
+            email: claims.email ?? 'unknown',
+            name: claims.name ?? claims.nickname,
+            emailVerified: claims.email_verified,
+            image: claims.picture,
+            providerData: {
+                // Include permissions (RBAC)
+                ...(claims.permissions && { permissions: claims.permissions }),
+                // Include scopes
+                ...(claims.scope && { scope: claims.scope.split(' ') }),
+                // Include organization data if present
+                ...(claims.org_id && { organizationId: claims.org_id }),
+                ...(claims.org_name && { organizationName: claims.org_name }),
+                // Include other useful claims
+                ...(claims.nickname && { nickname: claims.nickname }),
+                ...(claims.updated_at && { updatedAt: claims.updated_at }),
+            },
+        },
+        session: {
+            sessionId,
+            userId: claims.sub,
+            expiresAt: claims.exp * 1000, // Convert to Unix ms
+            isActive: true,
+            providerData: {
+                issuedAt: claims.iat * 1000,
+                issuer: claims.iss,
+                ...(claims.azp && { authorizedParty: claims.azp }),
+                ...(claims.aud && { audience: claims.aud }),
+            },
+        },
+    };
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create an Auth0 adapter
+ *
+ * This is the recommended way to create an Auth0 adapter.
+ * It returns an adapter instance with the configuration attached.
+ *
+ * @param config - Adapter configuration
+ * @returns Auth0 adapter with configuration
+ *
+ * @example
+ * ```typescript
+ * import { createAuth0Adapter } from '@veloxts/auth/adapters/auth0';
+ * import { createAuthAdapterPlugin } from '@veloxts/auth';
+ *
+ * const adapter = createAuth0Adapter({
+ *   domain: process.env.AUTH0_DOMAIN!,
+ *   audience: process.env.AUTH0_AUDIENCE!,
+ *   clientId: process.env.AUTH0_CLIENT_ID, // Optional
+ *   debug: process.env.NODE_ENV === 'development',
+ * });
+ *
+ * // Simplified API - just pass the adapter
+ * const authPlugin = createAuthAdapterPlugin(adapter);
+ *
+ * app.use(authPlugin);
+ * ```
+ */
+export function createAuth0Adapter(config) {
+    const adapter = new Auth0Adapter();
+    // Attach config for easy access when creating plugin
+    return Object.assign(adapter, { config });
+}
+// ============================================================================
+// Re-exports
+// ============================================================================
+export { AuthAdapterError } from '../adapter.js';