@dotdo/oauth 0.1.5 → 0.1.7

package/dist/server.js

@@ -4,9 +4,11 @@
  * Creates a Hono app that implements OAuth 2.1 authorization server endpoints:
  * - /.well-known/oauth-authorization-server (RFC 8414)
  * - /.well-known/oauth-protected-resource (draft-ietf-oauth-resource-metadata)
+ * - /.well-known/jwks.json (JWKS endpoint)
  * - /authorize (authorization endpoint)
  * - /callback (upstream OAuth callback)
  * - /token (token endpoint)
+ * - /introspect (token introspection - RFC 7662)
  * - /register (dynamic client registration - RFC 7591)
  * - /revoke (token revocation - RFC 7009)
  *
@@ -16,8 +18,9 @@
  */
 import { Hono } from 'hono';
 import { cors } from 'hono/cors';
-import { generateAuthorizationCode, generateToken, generateState, verifyCodeChallenge, hashClientSecret, } from './pkce.js';
+import { generateAuthorizationCode, generateToken, generateState, verifyCodeChallenge, hashClientSecret, verifyClientSecret, } from './pkce.js';
 import { createTestHelpers, generateLoginFormHtml, } from './dev.js';
+import { decodeJWT } from './jwt.js';
 /**
  * Create an OAuth 2.1 server as a Hono app
  *
@@ -58,12 +61,72 @@ import { createTestHelpers, generateLoginFormHtml, } from './dev.js';
  * ```
  */
 export function createOAuth21Server(config) {
-    const { issuer, storage, upstream, devMode, scopes = ['openid', 'profile', 'email', 'offline_access'], accessTokenTtl = 3600, refreshTokenTtl = 2592000, authCodeTtl = 600, enableDynamicRegistration = true, onUserAuthenticated, debug = false, } = config;
+    const { issuer: defaultIssuer, storage, upstream, devMode, scopes = ['openid', 'profile', 'email', 'offline_access'], accessTokenTtl = 3600, refreshTokenTtl = 2592000, authCodeTtl = 600, enableDynamicRegistration = true, onUserAuthenticated, debug = false, allowedOrigins, signingKeyManager: providedSigningKeyManager, useJwtAccessTokens = false, } = config;
+    /**
+     * Get the effective issuer for a request.
+     * Supports dynamic issuers via X-Issuer header for multi-tenant scenarios.
+     * This allows services like collections.do to proxy OAuth and have tokens
+     * issued with their own domain as the issuer.
+     */
+    function getEffectiveIssuer(c) {
+        const xIssuer = c.req.header('X-Issuer');
+        if (xIssuer) {
+            // Validate it's a proper URL
+            try {
+                new URL(xIssuer);
+                return xIssuer.replace(/\/$/, ''); // Remove trailing slash
+            }
+            catch {
+                if (debug) {
+                    console.warn('[OAuth] Invalid X-Issuer header:', xIssuer);
+                }
+            }
+        }
+        return defaultIssuer;
+    }
     // Validate configuration
     if (!devMode?.enabled && !upstream) {
         throw new Error('Either upstream configuration or devMode must be provided');
     }
+    // Security warning: devMode should never be used in production
+    // Use globalThis to access process in a way that works in all environments (Node, Deno, browsers)
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    if (devMode?.enabled && nodeEnv === 'production') {
+        console.warn('[OAuth] WARNING: devMode is enabled in a production environment!\n' +
+            'This bypasses upstream OAuth security and allows simple password authentication.\n' +
+            'This is a critical security risk. Set devMode.enabled = false for production.');
+    }
     const app = new Hono();
+    // Signing key manager for JWT access tokens
+    // If useJwtAccessTokens is enabled but no manager provided, we'll create keys lazily
+    let signingKeyManager = providedSigningKeyManager;
+    // Helper to get or create signing key
+    async function ensureSigningKey() {
+        if (!signingKeyManager) {
+            // Create an in-memory key manager lazily
+            const { SigningKeyManager: SKM } = await import('./jwt-signing.js');
+            signingKeyManager = new SKM();
+            app.signingKeyManager = signingKeyManager;
+        }
+        return signingKeyManager.getCurrentKey();
+    }
+    // Helper to generate JWT access token for simple login flow
+    // Accepts optional issuer override for multi-tenant scenarios
+    async function generateAccessToken(user, clientId, scope, issuerOverride) {
+        const { signAccessToken } = await import('./jwt-signing.js');
+        const key = await ensureSigningKey();
+        return signAccessToken(key, {
+            sub: user.id,
+            client_id: clientId,
+            scope,
+            email: user.email,
+            name: user.name,
+        }, {
+            issuer: issuerOverride || defaultIssuer,
+            audience: clientId,
+            expiresIn: accessTokenTtl,
+        });
+    }
     // Dev mode user storage
     const devUsers = new Map();
     // Initialize dev users
@@ -78,12 +141,30 @@ export function createOAuth21Server(config) {
             accessTokenTtl,
             refreshTokenTtl,
             authCodeTtl,
-            allowAnyCredentials: devMode.allowAnyCredentials,
+            ...(devMode.allowAnyCredentials !== undefined && { allowAnyCredentials: devMode.allowAnyCredentials }),
         });
     }
-    // CORS for all endpoints
+    // Attach signing key manager if provided
+    if (providedSigningKeyManager) {
+        app.signingKeyManager = providedSigningKeyManager;
+    }
+    // CORS for all endpoints - restrictive by default
+    // In production, only allow issuer origin unless explicitly configured
+    // In dev mode, allow all origins if not specified
+    const corsOrigins = allowedOrigins ?? (devMode?.enabled ? ['*'] : [new URL(defaultIssuer).origin]);
     app.use('*', cors({
-        origin: '*',
+        origin: (origin) => {
+            // If '*' is in the list, allow all origins
+            if (corsOrigins.includes('*')) {
+                return origin || '*';
+            }
+            // Otherwise, check if the origin is in the allowed list
+            if (origin && corsOrigins.includes(origin)) {
+                return origin;
+            }
+            // Return null to deny the request
+            return null;
+        },
         allowMethods: ['GET', 'POST', 'OPTIONS'],
         allowHeaders: ['Content-Type', 'Authorization'],
         exposeHeaders: ['WWW-Authenticate'],
@@ -95,12 +176,16 @@ export function createOAuth21Server(config) {
      * OAuth 2.1 Authorization Server Metadata (RFC 8414)
      */
     app.get('/.well-known/oauth-authorization-server', (c) => {
+        const issuer = getEffectiveIssuer(c);
         const metadata = {
             issuer,
             authorization_endpoint: `${issuer}/authorize`,
             token_endpoint: `${issuer}/token`,
-            registration_endpoint: enableDynamicRegistration ? `${issuer}/register` : undefined,
+            ...(enableDynamicRegistration && { registration_endpoint: `${issuer}/register` }),
             revocation_endpoint: `${issuer}/revoke`,
+            // JWKS and introspection endpoints (always advertised, but JWKS only works if signing keys available)
+            jwks_uri: `${issuer}/.well-known/jwks.json`,
+            introspection_endpoint: `${issuer}/introspect`,
             scopes_supported: scopes,
             response_types_supported: ['code'],
             grant_types_supported: ['authorization_code', 'refresh_token'],
@@ -113,6 +198,7 @@ export function createOAuth21Server(config) {
      * OAuth 2.1 Protected Resource Metadata
      */
     app.get('/.well-known/oauth-protected-resource', (c) => {
+        const issuer = getEffectiveIssuer(c);
         const metadata = {
             resource: issuer,
             authorization_servers: [issuer],
@@ -121,6 +207,102 @@ export function createOAuth21Server(config) {
         };
         return c.json(metadata);
     });
+    /**
+     * JWKS endpoint - exposes public signing keys
+     */
+    app.get('/.well-known/jwks.json', async (c) => {
+        try {
+            if (!signingKeyManager && !useJwtAccessTokens) {
+                // No signing keys configured - return empty JWKS
+                return c.json({ keys: [] });
+            }
+            const key = await ensureSigningKey();
+            const jwk = await crypto.subtle.exportKey('jwk', key.publicKey);
+            return c.json({
+                keys: [{
+                        kty: 'RSA',
+                        kid: key.kid,
+                        use: 'sig',
+                        alg: 'RS256',
+                        n: jwk.n,
+                        e: jwk.e,
+                    }]
+            });
+        }
+        catch (err) {
+            if (debug) {
+                console.error('[OAuth] JWKS error:', err);
+            }
+            return c.json({ keys: [] });
+        }
+    });
+    /**
+     * Token Introspection endpoint (RFC 7662)
+     * Allows resource servers to validate tokens
+     */
+    app.post('/introspect', async (c) => {
+        const contentType = c.req.header('content-type');
+        let token;
+        if (contentType?.includes('application/json')) {
+            const body = await c.req.json();
+            token = body.token;
+        }
+        else {
+            const formData = await c.req.parseBody();
+            token = String(formData['token'] || '');
+        }
+        if (!token) {
+            return c.json({ active: false });
+        }
+        // Try to decode as JWT first
+        const decoded = decodeJWT(token);
+        if (decoded) {
+            // It's a JWT - verify claims
+            const now = Math.floor(Date.now() / 1000);
+            // Check expiration
+            if (decoded.payload.exp && decoded.payload.exp < now) {
+                return c.json({ active: false });
+            }
+            // Check issuer - accept tokens from any issuer we could have issued
+            // Since we use the same signing keys, tokens with any valid issuer are acceptable
+            // The X-Issuer header can specify which issuer to accept, or we accept the default
+            const effectiveIssuer = getEffectiveIssuer(c);
+            if (decoded.payload.iss && decoded.payload.iss !== effectiveIssuer && decoded.payload.iss !== defaultIssuer) {
+                // Token's issuer doesn't match either the requested issuer or our default
+                return c.json({ active: false });
+            }
+            // Note: In production, you should also verify the signature using the JWKS
+            // For now, we trust the JWT structure and claims
+            return c.json({
+                active: true,
+                sub: decoded.payload.sub,
+                client_id: decoded.payload['client_id'],
+                scope: decoded.payload['scope'],
+                exp: decoded.payload.exp,
+                iat: decoded.payload.iat,
+                iss: decoded.payload.iss,
+                token_type: 'Bearer',
+            });
+        }
+        // Not a JWT - check opaque token storage
+        const storedToken = await storage.getAccessToken(token);
+        if (!storedToken) {
+            return c.json({ active: false });
+        }
+        // Check expiration
+        if (Date.now() > storedToken.expiresAt) {
+            return c.json({ active: false });
+        }
+        return c.json({
+            active: true,
+            sub: storedToken.userId,
+            client_id: storedToken.clientId,
+            scope: storedToken.scope,
+            exp: Math.floor(storedToken.expiresAt / 1000),
+            iat: Math.floor(storedToken.issuedAt / 1000),
+            token_type: storedToken.tokenType,
+        });
+    });
     // ═══════════════════════════════════════════════════════════════════════════
     // Authorization Endpoint
     // ═══════════════════════════════════════════════════════════════════════════
@@ -140,14 +322,14 @@ export function createOAuth21Server(config) {
      */
     app.get('/authorize', async (c) => {
         const params = c.req.query();
-        // Validate required parameters
-        const clientId = params.client_id;
-        const redirectUri = params.redirect_uri;
-        const responseType = params.response_type;
-        const codeChallenge = params.code_challenge;
-        const codeChallengeMethod = params.code_challenge_method;
-        const scope = params.scope;
-        const state = params.state;
+        // Validate required parameters (bracket notation for index signature access)
+        const clientId = params['client_id'];
+        const redirectUri = params['redirect_uri'];
+        const responseType = params['response_type'];
+        const codeChallenge = params['code_challenge'];
+        const codeChallengeMethod = params['code_challenge_method'];
+        const scope = params['scope'];
+        const state = params['state'];
         if (debug) {
             console.log('[OAuth] Authorize request:', { clientId, redirectUri, responseType, scope });
         }
@@ -167,6 +349,13 @@ export function createOAuth21Server(config) {
         if (!redirectUri) {
             return c.json({ error: 'invalid_request', error_description: 'redirect_uri is required' }, 400);
         }
+        // Validate redirect_uri is a valid URL
+        try {
+            new URL(redirectUri);
+        }
+        catch {
+            return c.json({ error: 'invalid_request', error_description: 'redirect_uri must be a valid URL' }, 400);
+        }
         if (!client.redirectUris.includes(redirectUri)) {
             return c.json({ error: 'invalid_request', error_description: 'redirect_uri not registered for this client' }, 400);
         }
@@ -179,12 +368,13 @@ export function createOAuth21Server(config) {
         }
         // Dev mode: show login form instead of redirecting to upstream
         if (devMode?.enabled) {
+            const effectiveIssuer = getEffectiveIssuer(c);
             const html = devMode.customLoginPage || generateLoginFormHtml({
-                issuer,
+                issuer: effectiveIssuer,
                 clientId,
                 redirectUri,
-                scope,
-                state,
+                ...(scope !== undefined && { scope }),
+                ...(state !== undefined && { state }),
                 codeChallenge,
                 codeChallengeMethod,
             });
@@ -194,24 +384,33 @@ export function createOAuth21Server(config) {
         if (!upstream) {
             return c.json({ error: 'server_error', error_description: 'No upstream provider configured' }, 500);
         }
+        // Get effective issuer for multi-tenant support
+        const effectiveIssuer = getEffectiveIssuer(c);
         // Store the authorization request and redirect to upstream
+        // Generate a cryptographically secure state for CSRF protection with upstream provider
         const upstreamState = generateState(64);
         // Store pending auth as a temporary authorization code that will be replaced
+        // The upstreamState is stored both in the code key (for lookup) and as a separate field (for explicit validation)
+        // This provides defense-in-depth for CSRF protection
         await storage.saveAuthorizationCode({
             code: `pending:${upstreamState}`,
             clientId,
             userId: '', // Will be filled after upstream auth
             redirectUri,
-            scope,
+            ...(scope !== undefined && { scope }),
             codeChallenge,
             codeChallengeMethod: 'S256',
-            state,
+            ...(state !== undefined && { state }), // Client's state (will be passed back to client)
+            upstreamState, // Server's state for explicit validation in callback
+            effectiveIssuer, // Store for multi-tenant token generation
             issuedAt: Date.now(),
             expiresAt: Date.now() + authCodeTtl * 1000,
         });
         // Build upstream authorization URL
+        // Note: The callback URL uses defaultIssuer (oauth.do) since that's what's registered with upstream providers
+        // The effectiveIssuer is stored in the auth code and used when generating tokens
         const upstreamAuthUrl = buildUpstreamAuthUrl(upstream, {
-            redirectUri: `${issuer}/callback`,
+            redirectUri: `${defaultIssuer}/callback`,
             state: upstreamState,
             scope: scope || 'openid profile email',
         });
@@ -221,6 +420,110 @@ export function createOAuth21Server(config) {
         return c.redirect(upstreamAuthUrl);
     });
     // ═══════════════════════════════════════════════════════════════════════════
+    // Simple Login Endpoint (for first-party apps)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Simple login redirect for first-party apps
+     *
+     * This is a simplified flow that doesn't require the full OAuth ceremony.
+     * It redirects to the upstream provider and returns a JWT to the return_to URL.
+     *
+     * Usage: GET /login?returnTo=https://myapp.com/callback
+     * After auth, redirects to: https://myapp.com/callback?_token=<jwt>
+     *
+     * If returnTo is not provided, defaults to:
+     * - Referer URL (if origin is in allowedOrigins)
+     * - Issuer root otherwise
+     */
+    app.get('/login', async (c) => {
+        // Support both camelCase (preferred) and snake_case for compatibility
+        let returnTo = c.req.query('returnTo') || c.req.query('return_to');
+        // Default to referer if it's an allowed origin
+        if (!returnTo) {
+            const referer = c.req.header('Referer');
+            if (referer) {
+                try {
+                    const refererUrl = new URL(referer);
+                    // Check if referer's origin is allowed (or if we allow all origins)
+                    const isAllowed = corsOrigins.includes('*') || corsOrigins.includes(refererUrl.origin);
+                    if (isAllowed) {
+                        returnTo = referer;
+                    }
+                }
+                catch {
+                    // Invalid referer, ignore
+                }
+            }
+            // Default to effective issuer root
+            const effectiveIssuer = getEffectiveIssuer(c);
+            if (!returnTo) {
+                returnTo = effectiveIssuer;
+            }
+        }
+        // Validate return_to is a valid URL
+        try {
+            new URL(returnTo);
+        }
+        catch {
+            return c.json({ error: 'invalid_request', error_description: 'return_to must be a valid URL' }, 400);
+        }
+        // Get effective issuer for token generation
+        const effectiveIssuer = getEffectiveIssuer(c);
+        // Dev mode: show a simple form or auto-login
+        if (devMode?.enabled && devMode.users?.length) {
+            // In dev mode, auto-login as the first user and redirect
+            const devUser = devMode.users[0];
+            let user = await storage.getUserByEmail(devUser.email);
+            if (!user) {
+                user = {
+                    id: devUser.id,
+                    email: devUser.email,
+                    ...(devUser.name !== undefined && { name: devUser.name }),
+                    createdAt: Date.now(),
+                    updatedAt: Date.now(),
+                    lastLoginAt: Date.now(),
+                };
+                await storage.saveUser(user);
+            }
+            // Generate JWT access token with effective issuer
+            const accessToken = await generateAccessToken(user, 'first-party', 'openid profile email', effectiveIssuer);
+            // Redirect with token
+            const url = new URL(returnTo);
+            url.searchParams.set('_token', accessToken);
+            return c.redirect(url.toString());
+        }
+        // Production mode: redirect to upstream
+        if (!upstream) {
+            return c.json({ error: 'server_error', error_description: 'No upstream provider configured' }, 500);
+        }
+        // Generate state to track this login request
+        const loginState = generateState(64);
+        // Store the return_to URL in the auth code table (reusing the structure)
+        // Also store effective issuer for use when generating tokens in callback
+        await storage.saveAuthorizationCode({
+            code: `login:${loginState}`,
+            clientId: 'first-party',
+            userId: '',
+            redirectUri: returnTo,
+            codeChallenge: 'none', // Not used for simple login
+            codeChallengeMethod: 'S256',
+            effectiveIssuer, // Store for use in callback
+            issuedAt: Date.now(),
+            expiresAt: Date.now() + authCodeTtl * 1000,
+        });
+        // Build upstream authorization URL
+        // Note: Callback URL uses defaultIssuer (oauth.do) since that's registered with upstream providers
+        const upstreamAuthUrl = buildUpstreamAuthUrl(upstream, {
+            redirectUri: `${defaultIssuer}/callback`,
+            state: loginState,
+            scope: 'openid profile email',
+        });
+        if (debug) {
+            console.log('[OAuth] Simple login redirect to upstream:', upstreamAuthUrl);
+        }
+        return c.redirect(upstreamAuthUrl);
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
     // Dev Mode Login Endpoint
     // ═══════════════════════════════════════════════════════════════════════════
     /**
@@ -231,22 +534,27 @@ export function createOAuth21Server(config) {
             return c.json({ error: 'invalid_request', error_description: 'Dev mode is not enabled' }, 400);
         }
         const formData = await c.req.parseBody();
-        const email = String(formData.email || '');
-        const password = String(formData.password || '');
-        const clientId = String(formData.client_id || '');
-        const redirectUri = String(formData.redirect_uri || '');
-        const scope = String(formData.scope || '');
-        const state = String(formData.state || '');
-        const codeChallenge = String(formData.code_challenge || '');
-        const codeChallengeMethod = String(formData.code_challenge_method || 'S256');
+        const email = String(formData['email'] || '');
+        const password = String(formData['password'] || '');
+        const clientId = String(formData['client_id'] || '');
+        const redirectUri = String(formData['redirect_uri'] || '');
+        const scope = String(formData['scope'] || '');
+        const state = String(formData['state'] || '');
+        const codeChallenge = String(formData['code_challenge'] || '');
+        const codeChallengeMethod = String(formData['code_challenge_method'] || 'S256');
+        // Get effective issuer for multi-tenant support
+        const effectiveIssuer = getEffectiveIssuer(c);
         if (debug) {
             console.log('[OAuth] Dev login attempt:', { email, clientId });
         }
         // Validate credentials
+        if (!app.testHelpers) {
+            return c.json({ error: 'server_error', error_description: 'Test helpers not available' }, 500);
+        }
         const devUser = await app.testHelpers.validateCredentials(email, password);
         if (!devUser) {
             const html = generateLoginFormHtml({
-                issuer,
+                issuer: effectiveIssuer,
                 clientId,
                 redirectUri,
                 scope,
@@ -263,9 +571,9 @@ export function createOAuth21Server(config) {
             user = {
                 id: devUser.id,
                 email: devUser.email,
-                name: devUser.name,
-                organizationId: devUser.organizationId,
-                roles: devUser.roles,
+                ...(devUser.name !== undefined && { name: devUser.name }),
+                ...(devUser.organizationId !== undefined && { organizationId: devUser.organizationId }),
+                ...(devUser.roles !== undefined && { roles: devUser.roles }),
                 createdAt: Date.now(),
                 updatedAt: Date.now(),
                 lastLoginAt: Date.now(),
@@ -277,7 +585,9 @@ export function createOAuth21Server(config) {
             user.updatedAt = Date.now();
             await storage.saveUser(user);
         }
-        await onUserAuthenticated?.(user);
+        if (onUserAuthenticated) {
+            await onUserAuthenticated(user);
+        }
         // Generate authorization code
         const authCode = generateAuthorizationCode();
         await storage.saveAuthorizationCode({
@@ -285,10 +595,10 @@ export function createOAuth21Server(config) {
             clientId,
             userId: user.id,
             redirectUri,
-            scope,
+            ...(scope && { scope }),
             codeChallenge,
             codeChallengeMethod: 'S256',
-            state,
+            ...(state && { state }),
             issuedAt: Date.now(),
             expiresAt: Date.now() + authCodeTtl * 1000,
         });
@@ -317,6 +627,70 @@ export function createOAuth21Server(config) {
         if (debug) {
             console.log('[OAuth] Callback received:', { code: !!code, state: upstreamState, error });
         }
+        if (!code || !upstreamState) {
+            return c.json({ error: 'invalid_request', error_description: 'Missing code or state' }, 400);
+        }
+        // In dev mode, callback shouldn't be used (login handles it directly)
+        if (!upstream) {
+            return c.json({ error: 'server_error', error_description: 'No upstream provider configured' }, 500);
+        }
+        // Check if this is a simple login flow (login: prefix) or OAuth flow (pending: prefix)
+        const loginAuth = await storage.consumeAuthorizationCode(`login:${upstreamState}`);
+        if (loginAuth) {
+            // Simple login flow - use one-time code exchange (not JWT in URL)
+            if (error) {
+                const redirectUrl = new URL(loginAuth.redirectUri);
+                redirectUrl.searchParams.set('error', error);
+                if (errorDescription) {
+                    redirectUrl.searchParams.set('error_description', errorDescription);
+                }
+                return c.redirect(redirectUrl.toString());
+            }
+            try {
+                // Exchange code with upstream provider
+                // Use defaultIssuer for callback URL (registered with upstream provider)
+                const upstreamTokens = await exchangeUpstreamCode(upstream, code, `${defaultIssuer}/callback`);
+                if (debug) {
+                    console.log('[OAuth] Simple login - upstream tokens received');
+                }
+                // Get or create user
+                const user = await getOrCreateUser(storage, upstreamTokens.user, onUserAuthenticated);
+                // Generate JWT access token with stored effective issuer (for multi-tenant support)
+                const tokenIssuer = loginAuth.effectiveIssuer || defaultIssuer;
+                const accessToken = await generateAccessToken(user, 'first-party', 'openid profile email', tokenIssuer);
+                // Generate a one-time code and store the JWT (60 second TTL)
+                const oneTimeCode = generateAuthorizationCode();
+                await storage.saveAuthorizationCode({
+                    code: `exchange:${oneTimeCode}`,
+                    clientId: 'first-party',
+                    userId: user.id,
+                    redirectUri: loginAuth.redirectUri,
+                    codeChallenge: accessToken, // Store the JWT in codeChallenge field (reusing structure)
+                    codeChallengeMethod: 'S256',
+                    issuedAt: Date.now(),
+                    expiresAt: Date.now() + 60 * 1000, // 60 second TTL
+                });
+                // Redirect to origin's /callback with one-time code
+                const originalUrl = new URL(loginAuth.redirectUri);
+                const callbackUrl = new URL('/callback', originalUrl.origin);
+                callbackUrl.searchParams.set('code', oneTimeCode);
+                callbackUrl.searchParams.set('returnTo', originalUrl.pathname + originalUrl.search);
+                if (debug) {
+                    console.log('[OAuth] Platform login redirect:', callbackUrl.toString());
+                }
+                return c.redirect(callbackUrl.toString());
+            }
+            catch (err) {
+                if (debug) {
+                    console.error('[OAuth] Simple login callback error:', err);
+                }
+                const redirectUrl = new URL(loginAuth.redirectUri);
+                redirectUrl.searchParams.set('error', 'server_error');
+                redirectUrl.searchParams.set('error_description', err instanceof Error ? err.message : 'Authentication failed');
+                return c.redirect(redirectUrl.toString());
+            }
+        }
+        // OAuth flow - look for pending: prefix
         if (error) {
             // Retrieve pending auth to get redirect_uri
             const pendingAuth = await storage.consumeAuthorizationCode(`pending:${upstreamState}`);
@@ -325,21 +699,24 @@ export function createOAuth21Server(config) {
             }
             return c.json({ error, error_description: errorDescription }, 400);
         }
-        if (!code || !upstreamState) {
-            return c.json({ error: 'invalid_request', error_description: 'Missing code or state' }, 400);
-        }
         // Retrieve pending authorization
         const pendingAuth = await storage.consumeAuthorizationCode(`pending:${upstreamState}`);
         if (!pendingAuth) {
             return c.json({ error: 'invalid_request', error_description: 'Invalid or expired state' }, 400);
         }
-        // In dev mode, callback shouldn't be used (login handles it directly)
-        if (!upstream) {
-            return c.json({ error: 'server_error', error_description: 'No upstream provider configured' }, 500);
+        // CSRF Protection: Explicitly validate the upstream state matches what was stored
+        // This is defense-in-depth - the lookup by state already provides implicit validation,
+        // but explicit comparison ensures the state wasn't somehow tampered with
+        if (pendingAuth.upstreamState && pendingAuth.upstreamState !== upstreamState) {
+            if (debug) {
+                console.log('[OAuth] State mismatch - potential CSRF attack detected');
+            }
+            return redirectWithError(pendingAuth.redirectUri, 'access_denied', 'State parameter validation failed - possible CSRF attack', pendingAuth.state);
         }
         try {
             // Exchange code with upstream provider
-            const upstreamTokens = await exchangeUpstreamCode(upstream, code, `${issuer}/callback`);
+            // Use defaultIssuer for callback URL (registered with upstream provider)
+            const upstreamTokens = await exchangeUpstreamCode(upstream, code, `${defaultIssuer}/callback`);
             if (debug) {
                 console.log('[OAuth] Upstream tokens received:', { hasAccessToken: !!upstreamTokens.access_token });
             }
@@ -352,10 +729,11 @@ export function createOAuth21Server(config) {
                 clientId: pendingAuth.clientId,
                 userId: user.id,
                 redirectUri: pendingAuth.redirectUri,
-                scope: pendingAuth.scope,
-                codeChallenge: pendingAuth.codeChallenge,
+                ...(pendingAuth.scope !== undefined && { scope: pendingAuth.scope }),
+                ...(pendingAuth.codeChallenge !== undefined && { codeChallenge: pendingAuth.codeChallenge }),
                 codeChallengeMethod: 'S256',
-                state: pendingAuth.state,
+                ...(pendingAuth.state !== undefined && { state: pendingAuth.state }),
+                ...(pendingAuth.effectiveIssuer !== undefined && { effectiveIssuer: pendingAuth.effectiveIssuer }),
                 issuedAt: Date.now(),
                 expiresAt: Date.now() + authCodeTtl * 1000,
             });
@@ -393,21 +771,61 @@ export function createOAuth21Server(config) {
             const formData = await c.req.parseBody();
             params = Object.fromEntries(Object.entries(formData).map(([k, v]) => [k, String(v)]));
         }
-        const grantType = params.grant_type;
+        const grantType = params['grant_type'];
         if (debug) {
-            console.log('[OAuth] Token request:', { grantType, clientId: params.client_id });
+            console.log('[OAuth] Token request:', { grantType, clientId: params['client_id'] });
         }
+        // JWT signing options
+        // Note: issuer is set to defaultIssuer but can be overridden per-token by effectiveIssuer in auth code
+        const jwtSigningOptions = useJwtAccessTokens ? {
+            issuer: defaultIssuer,
+            getSigningKey: ensureSigningKey,
+        } : undefined;
         if (grantType === 'authorization_code') {
-            return handleAuthorizationCodeGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug);
+            return handleAuthorizationCodeGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug, jwtSigningOptions);
         }
         else if (grantType === 'refresh_token') {
-            return handleRefreshTokenGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug);
+            return handleRefreshTokenGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug, jwtSigningOptions);
         }
         else {
             return c.json({ error: 'unsupported_grant_type', error_description: 'Only authorization_code and refresh_token grants are supported' }, 400);
         }
     });
     // ═══════════════════════════════════════════════════════════════════════════
+    // Platform Token Exchange (for first-party domains)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Exchange a one-time code for a JWT (platform domains only)
+     *
+     * This is used by platform domains after the OAuth callback.
+     * The one-time code is exchanged server-side for the JWT,
+     * which is then set as an httpOnly cookie.
+     *
+     * POST /exchange { code: "one-time-code" }
+     * Returns: { token: "jwt", expiresIn: 3600 }
+     */
+    app.post('/exchange', async (c) => {
+        const body = await c.req.json();
+        const code = body.code;
+        if (!code) {
+            return c.json({ error: 'invalid_request', error_description: 'code is required' }, 400);
+        }
+        // Look up the one-time code
+        const exchangeData = await storage.consumeAuthorizationCode(`exchange:${code}`);
+        if (!exchangeData) {
+            return c.json({ error: 'invalid_grant', error_description: 'Invalid or expired code' }, 400);
+        }
+        // The JWT was stored in codeChallenge field
+        const token = exchangeData.codeChallenge;
+        if (debug) {
+            console.log('[OAuth] Platform exchange successful for user:', exchangeData.userId);
+        }
+        return c.json({
+            token,
+            expiresIn: accessTokenTtl,
+        });
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
     // Dynamic Client Registration
     // ═══════════════════════════════════════════════════════════════════════════
     if (enableDynamicRegistration) {
@@ -437,7 +855,7 @@ export function createOAuth21Server(config) {
                 grantTypes: body.grant_types || ['authorization_code', 'refresh_token'],
                 responseTypes: body.response_types || ['code'],
                 tokenEndpointAuthMethod: body.token_endpoint_auth_method || 'client_secret_basic',
-                scope: body.scope,
+                ...(body.scope !== undefined && { scope: body.scope }),
                 createdAt: Date.now(),
             };
             await storage.saveClient(client);
@@ -464,8 +882,8 @@ export function createOAuth21Server(config) {
      */
     app.post('/revoke', async (c) => {
         const formData = await c.req.parseBody();
-        const token = String(formData.token || '');
-        const tokenTypeHint = String(formData.token_type_hint || '');
+        const token = String(formData['token'] || '');
+        const tokenTypeHint = String(formData['token_type_hint'] || '');
         if (!token) {
             return c.json({ error: 'invalid_request', error_description: 'token is required' }, 400);
         }
@@ -482,19 +900,125 @@ export function createOAuth21Server(config) {
     });
     return app;
 }
-// ═══════════════════════════════════════════════════════════════════════════
-// Helper Functions
-// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Authenticate a client at the token endpoint
+ *
+ * Supports:
+ * - client_secret_basic: Authorization: Basic base64(client_id:client_secret)
+ * - client_secret_post: client_id and client_secret in request body
+ * - none: public clients (no secret required)
+ */
+async function authenticateClient(c, params, storage, debug) {
+    let clientId;
+    let clientSecret;
+    // Check for client_secret_basic (Authorization header)
+    const authHeader = c.req.header('authorization');
+    if (authHeader?.startsWith('Basic ')) {
+        try {
+            const base64Credentials = authHeader.slice(6);
+            const credentials = atob(base64Credentials);
+            const colonIndex = credentials.indexOf(':');
+            if (colonIndex !== -1) {
+                clientId = decodeURIComponent(credentials.slice(0, colonIndex));
+                clientSecret = decodeURIComponent(credentials.slice(colonIndex + 1));
+            }
+        }
+        catch {
+            return {
+                success: false,
+                error: 'invalid_client',
+                errorDescription: 'Invalid Authorization header',
+                statusCode: 401,
+            };
+        }
+    }
+    // Fall back to client_secret_post (body parameters)
+    if (!clientId) {
+        clientId = params['client_id'];
+        clientSecret = params['client_secret'];
+    }
+    if (!clientId) {
+        return {
+            success: false,
+            error: 'invalid_request',
+            errorDescription: 'client_id is required',
+            statusCode: 400,
+        };
+    }
+    // Fetch the client
+    const client = await storage.getClient(clientId);
+    if (!client) {
+        return {
+            success: false,
+            error: 'invalid_client',
+            errorDescription: 'Client not found',
+            statusCode: 401,
+        };
+    }
+    // Check if client requires authentication
+    if (client.tokenEndpointAuthMethod !== 'none') {
+        // Client requires secret verification
+        if (!client.clientSecretHash) {
+            // Client is configured to require auth but has no secret stored
+            return {
+                success: false,
+                error: 'invalid_client',
+                errorDescription: 'Client authentication failed',
+                statusCode: 401,
+            };
+        }
+        if (!clientSecret) {
+            return {
+                success: false,
+                error: 'invalid_client',
+                errorDescription: 'Client secret is required',
+                statusCode: 401,
+            };
+        }
+        // Verify the secret using constant-time comparison
+        const secretValid = await verifyClientSecret(clientSecret, client.clientSecretHash);
+        if (!secretValid) {
+            if (debug) {
+                console.log('[OAuth] Client authentication failed for:', clientId);
+            }
+            return {
+                success: false,
+                error: 'invalid_client',
+                errorDescription: 'Client authentication failed',
+                statusCode: 401,
+            };
+        }
+    }
+    if (debug) {
+        console.log('[OAuth] Client authenticated:', clientId);
+    }
+    return {
+        success: true,
+        client,
+    };
+}
 function redirectWithError(redirectUri, error, description, state) {
-    const url = new URL(redirectUri);
-    url.searchParams.set('error', error);
-    if (description) {
-        url.searchParams.set('error_description', description);
+    try {
+        const url = new URL(redirectUri);
+        url.searchParams.set('error', error);
+        if (description) {
+            url.searchParams.set('error_description', description);
+        }
+        if (state) {
+            url.searchParams.set('state', state);
+        }
+        return Response.redirect(url.toString(), 302);
     }
-    if (state) {
-        url.searchParams.set('state', state);
+    catch {
+        // If redirect_uri is malformed, return a JSON error response instead of redirecting
+        return new Response(JSON.stringify({
+            error,
+            error_description: description || 'Invalid redirect_uri',
+        }), {
+            status: 400,
+            headers: { 'Content-Type': 'application/json' },
+        });
     }
-    return Response.redirect(url.toString(), 302);
 }
 function buildUpstreamAuthUrl(upstream, params) {
     if (upstream.provider === 'workos') {
@@ -524,13 +1048,12 @@ async function exchangeUpstreamCode(upstream, code, redirectUri) {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',
-                'Authorization': `Bearer ${upstream.apiKey}`,
             },
             body: new URLSearchParams({
                 grant_type: 'authorization_code',
                 client_id: upstream.clientId,
+                client_secret: upstream.apiKey,
                 code,
-                redirect_uri: redirectUri,
             }).toString(),
         });
         if (!response.ok) {
@@ -567,11 +1090,12 @@ async function getOrCreateUser(storage, upstreamUser, onUserAuthenticated) {
     let user = await storage.getUserByEmail(upstreamUser.email);
     if (!user) {
         // Create new user
+        const fullName = [upstreamUser.first_name, upstreamUser.last_name].filter(Boolean).join(' ');
         user = {
             id: upstreamUser.id,
             email: upstreamUser.email,
-            name: [upstreamUser.first_name, upstreamUser.last_name].filter(Boolean).join(' ') || undefined,
-            organizationId: upstreamUser.organization_id,
+            ...(fullName && { name: fullName }),
+            ...(upstreamUser.organization_id !== undefined && { organizationId: upstreamUser.organization_id }),
             createdAt: Date.now(),
             updatedAt: Date.now(),
             lastLoginAt: Date.now(),
@@ -584,91 +1108,138 @@ async function getOrCreateUser(storage, upstreamUser, onUserAuthenticated) {
         user.updatedAt = Date.now();
         await storage.saveUser(user);
     }
-    await onUserAuthenticated?.(user);
+    if (onUserAuthenticated) {
+        await onUserAuthenticated(user);
+    }
     return user;
 }
-async function handleAuthorizationCodeGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug) {
-    const { code, client_id, redirect_uri, code_verifier } = params;
+/**
+ * Sign a JWT access token
+ */
+async function signJWTAccessToken(claims, options, expiresIn) {
+    const { signAccessToken } = await import('./jwt-signing.js');
+    const key = await options.getSigningKey();
+    return signAccessToken(key, claims, {
+        issuer: options.issuer,
+        audience: claims.client_id,
+        expiresIn,
+    });
+}
+async function handleAuthorizationCodeGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug, jwtOptions) {
+    const code = params['code'];
+    const redirect_uri = params['redirect_uri'];
+    const code_verifier = params['code_verifier'];
     if (!code) {
         return c.json({ error: 'invalid_request', error_description: 'code is required' }, 400);
     }
-    if (!client_id) {
-        return c.json({ error: 'invalid_request', error_description: 'client_id is required' }, 400);
+    // Authenticate client (supports client_secret_basic and client_secret_post)
+    const authResult = await authenticateClient(c, params, storage, debug);
+    if (!authResult.success) {
+        const statusCode = (authResult.statusCode || 401);
+        return c.json({ error: authResult.error, error_description: authResult.errorDescription }, statusCode);
     }
+    const client = authResult.client;
     // Consume authorization code (one-time use)
     const authCode = await storage.consumeAuthorizationCode(code);
     if (!authCode) {
         return c.json({ error: 'invalid_grant', error_description: 'Invalid or expired authorization code' }, 400);
     }
-    // Verify client
-    if (authCode.clientId !== client_id) {
+    // Verify client matches the code
+    if (authCode.clientId !== client.clientId) {
         return c.json({ error: 'invalid_grant', error_description: 'Client mismatch' }, 400);
     }
     // Verify redirect_uri
     if (redirect_uri && authCode.redirectUri !== redirect_uri) {
         return c.json({ error: 'invalid_grant', error_description: 'redirect_uri mismatch' }, 400);
     }
-    // Verify PKCE
-    if (authCode.codeChallenge) {
-        if (!code_verifier) {
-            return c.json({ error: 'invalid_request', error_description: 'code_verifier is required' }, 400);
-        }
-        const valid = await verifyCodeChallenge(code_verifier, authCode.codeChallenge, authCode.codeChallengeMethod || 'S256');
-        if (!valid) {
-            return c.json({ error: 'invalid_grant', error_description: 'Invalid code_verifier' }, 400);
-        }
+    // Verify PKCE (required in OAuth 2.1)
+    // Per OAuth 2.1 spec, PKCE is REQUIRED for authorization_code flow
+    if (!authCode.codeChallenge) {
+        // This should never happen if the authorize endpoint is working correctly
+        return c.json({ error: 'server_error', error_description: 'Authorization code missing code_challenge' }, 500);
+    }
+    if (!code_verifier) {
+        return c.json({ error: 'invalid_request', error_description: 'code_verifier is required' }, 400);
+    }
+    const valid = await verifyCodeChallenge(code_verifier, authCode.codeChallenge, authCode.codeChallengeMethod || 'S256');
+    if (!valid) {
+        return c.json({ error: 'invalid_grant', error_description: 'Invalid code_verifier' }, 400);
     }
     // Check expiration
     if (Date.now() > authCode.expiresAt) {
         return c.json({ error: 'invalid_grant', error_description: 'Authorization code expired' }, 400);
     }
     // Generate tokens
-    const accessToken = generateToken(48);
     const refreshToken = generateToken(64);
     const now = Date.now();
-    await storage.saveAccessToken({
-        token: accessToken,
-        tokenType: 'Bearer',
-        clientId: authCode.clientId,
-        userId: authCode.userId,
-        scope: authCode.scope,
-        issuedAt: now,
-        expiresAt: now + accessTokenTtl * 1000,
-    });
+    // Generate access token (JWT if configured, otherwise opaque)
+    let accessToken;
+    if (jwtOptions) {
+        // Use effectiveIssuer from auth code if set (for multi-tenant support)
+        const tokenJwtOptions = authCode.effectiveIssuer
+            ? { ...jwtOptions, issuer: authCode.effectiveIssuer }
+            : jwtOptions;
+        accessToken = await signJWTAccessToken({
+            sub: authCode.userId,
+            client_id: authCode.clientId,
+            ...(authCode.scope && { scope: authCode.scope }),
+        }, tokenJwtOptions, accessTokenTtl);
+        // Note: JWT access tokens are stateless, so we don't store them
+        // But we can optionally store metadata for tracking/revocation
+    }
+    else {
+        accessToken = generateToken(48);
+        await storage.saveAccessToken({
+            token: accessToken,
+            tokenType: 'Bearer',
+            clientId: authCode.clientId,
+            userId: authCode.userId,
+            ...(authCode.scope !== undefined && { scope: authCode.scope }),
+            issuedAt: now,
+            expiresAt: now + accessTokenTtl * 1000,
+        });
+    }
     await storage.saveRefreshToken({
         token: refreshToken,
         clientId: authCode.clientId,
         userId: authCode.userId,
-        scope: authCode.scope,
+        ...(authCode.scope !== undefined && { scope: authCode.scope }),
         issuedAt: now,
-        expiresAt: refreshTokenTtl > 0 ? now + refreshTokenTtl * 1000 : undefined,
+        ...(refreshTokenTtl > 0 && { expiresAt: now + refreshTokenTtl * 1000 }),
     });
     // Save grant
     await storage.saveGrant({
         id: `${authCode.userId}:${authCode.clientId}`,
         userId: authCode.userId,
         clientId: authCode.clientId,
-        scope: authCode.scope,
+        ...(authCode.scope !== undefined && { scope: authCode.scope }),
         createdAt: now,
         lastUsedAt: now,
     });
     if (debug) {
-        console.log('[OAuth] Tokens issued for user:', authCode.userId);
+        console.log('[OAuth] Tokens issued for user:', authCode.userId, jwtOptions ? '(JWT)' : '(opaque)');
     }
     const response = {
         access_token: accessToken,
         token_type: 'Bearer',
         expires_in: accessTokenTtl,
         refresh_token: refreshToken,
-        scope: authCode.scope,
+        ...(authCode.scope !== undefined && { scope: authCode.scope }),
     };
     return c.json(response);
 }
-async function handleRefreshTokenGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug) {
-    const { refresh_token, client_id } = params;
+async function handleRefreshTokenGrant(c, params, storage, accessTokenTtl, refreshTokenTtl, debug, jwtOptions) {
+    const refresh_token = params['refresh_token'];
     if (!refresh_token) {
         return c.json({ error: 'invalid_request', error_description: 'refresh_token is required' }, 400);
     }
+    // Authenticate client (supports client_secret_basic and client_secret_post)
+    const authResult = await authenticateClient(c, params, storage, debug);
+    if (!authResult.success) {
+        const statusCode = (authResult.statusCode || 401);
+        return c.json({ error: authResult.error, error_description: authResult.errorDescription }, statusCode);
+    }
+    const client = authResult.client;
     const storedRefresh = await storage.getRefreshToken(refresh_token);
     if (!storedRefresh) {
         return c.json({ error: 'invalid_grant', error_description: 'Invalid refresh token' }, 400);
@@ -679,31 +1250,43 @@ async function handleRefreshTokenGrant(c, params, storage, accessTokenTtl, refre
     if (storedRefresh.expiresAt && Date.now() > storedRefresh.expiresAt) {
         return c.json({ error: 'invalid_grant', error_description: 'Refresh token expired' }, 400);
     }
-    if (client_id && storedRefresh.clientId !== client_id) {
+    // Verify the refresh token belongs to the authenticated client
+    if (storedRefresh.clientId !== client.clientId) {
         return c.json({ error: 'invalid_grant', error_description: 'Client mismatch' }, 400);
     }
     // Generate new tokens
-    const accessToken = generateToken(48);
     const newRefreshToken = generateToken(64);
     const now = Date.now();
-    await storage.saveAccessToken({
-        token: accessToken,
-        tokenType: 'Bearer',
-        clientId: storedRefresh.clientId,
-        userId: storedRefresh.userId,
-        scope: storedRefresh.scope,
-        issuedAt: now,
-        expiresAt: now + accessTokenTtl * 1000,
-    });
+    // Generate access token (JWT if configured, otherwise opaque)
+    let accessToken;
+    if (jwtOptions) {
+        accessToken = await signJWTAccessToken({
+            sub: storedRefresh.userId,
+            client_id: storedRefresh.clientId,
+            ...(storedRefresh.scope && { scope: storedRefresh.scope }),
+        }, jwtOptions, accessTokenTtl);
+    }
+    else {
+        accessToken = generateToken(48);
+        await storage.saveAccessToken({
+            token: accessToken,
+            tokenType: 'Bearer',
+            clientId: storedRefresh.clientId,
+            userId: storedRefresh.userId,
+            ...(storedRefresh.scope !== undefined && { scope: storedRefresh.scope }),
+            issuedAt: now,
+            expiresAt: now + accessTokenTtl * 1000,
+        });
+    }
     // Rotate refresh token
     await storage.revokeRefreshToken(refresh_token);
     await storage.saveRefreshToken({
         token: newRefreshToken,
         clientId: storedRefresh.clientId,
         userId: storedRefresh.userId,
-        scope: storedRefresh.scope,
+        ...(storedRefresh.scope !== undefined && { scope: storedRefresh.scope }),
         issuedAt: now,
-        expiresAt: refreshTokenTtl > 0 ? now + refreshTokenTtl * 1000 : undefined,
+        ...(refreshTokenTtl > 0 && { expiresAt: now + refreshTokenTtl * 1000 }),
     });
     // Update grant last used
     const grant = await storage.getGrant(storedRefresh.userId, storedRefresh.clientId);
@@ -712,14 +1295,14 @@ async function handleRefreshTokenGrant(c, params, storage, accessTokenTtl, refre
         await storage.saveGrant(grant);
     }
     if (debug) {
-        console.log('[OAuth] Tokens refreshed for user:', storedRefresh.userId);
+        console.log('[OAuth] Tokens refreshed for user:', storedRefresh.userId, jwtOptions ? '(JWT)' : '(opaque)');
     }
     const response = {
         access_token: accessToken,
         token_type: 'Bearer',
         expires_in: accessTokenTtl,
         refresh_token: newRefreshToken,
-        scope: storedRefresh.scope,
+        ...(storedRefresh.scope !== undefined && { scope: storedRefresh.scope }),
     };
     return c.json(response);
 }