fraim 2.0.177 → 2.0.180

package/dist/src/routes/app-routes.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAppRoutes = registerAppRoutes;
+const path_1 = __importDefault(require("path"));
+/**
+ * Serve the unified tabs experience at the root path.
+ *
+ * Authenticated users see the tabbed interface with Analytics, Brain, and Account.
+ * Unauthenticated users are redirected to sign-in.
+ */
+function registerAppRoutes(app, deps) {
+    const { dbService } = deps;
+    /**
+     * GET / - Main authenticated app (unified tabs)
+     *
+     * Serves the unified tabs page. Client-side JavaScript checks session via
+     * /api/auth/session and redirects to sign-in if not authenticated.
+     */
+    app.get('/', (req, res) => {
+        try {
+            const indexPath = path_1.default.join(process.cwd(), 'public', 'index.html');
+            return res.sendFile(indexPath);
+        }
+        catch (err) {
+            console.error('Error serving root page:', err);
+            return res.status(500).send('Internal server error');
+        }
+    });
+}

package/dist/src/routes/auth-routes.js

@@ -0,0 +1,505 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPublicAuthRoutes = registerPublicAuthRoutes;
+exports.registerProtectedAuthRoutes = registerProtectedAuthRoutes;
+exports.__resetAuthRouteRateLimitsForTests = __resetAuthRouteRateLimitsForTests;
+const crypto_1 = require("crypto");
+const email_service_1 = require("../services/email-service");
+const cookie_service_1 = require("../services/cookie-service");
+const oauth_helpers_1 = require("../services/oauth-helpers");
+const audit_log_1 = require("../services/audit-log");
+const email_code_1 = require("../services/email-code");
+const MAX_EMAIL_REQUESTS_PER_EMAIL_PER_10MIN = 5;
+const MAX_EMAIL_REQUESTS_PER_IP_PER_10MIN = 20;
+const recentEmailRequests = new Map();
+// ─── mobile exchange code store ─────────────────────────────────────────────
+// Short-lived one-time codes bridging web OAuth/email-code sign-in to the mobile app.
+// Key: 12-char hex code   Value: { apiKey, expiresAt }
+const MOBILE_CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const mobileCodeStore = new Map();
+function pruneMobileCodes() {
+    const now = Date.now();
+    for (const [code, entry] of mobileCodeStore.entries()) {
+        if (entry.expiresAt < now)
+            mobileCodeStore.delete(code);
+    }
+}
+function issueMobileExchangeCode(apiKey) {
+    pruneMobileCodes();
+    const code = (0, crypto_1.randomBytes)(12).toString('hex'); // 24 chars
+    mobileCodeStore.set(code, { apiKey, expiresAt: Date.now() + MOBILE_CODE_TTL_MS });
+    return code;
+}
+function serializeApiKeyLifecycle(apiKeyData) {
+    const rawExpiresAt = apiKeyData?.expiresAt ?? null;
+    const parsedExpiresAt = rawExpiresAt ? new Date(rawExpiresAt) : null;
+    return {
+        status: apiKeyData?.status ?? 'active',
+        expiresAt: parsedExpiresAt && !Number.isNaN(parsedExpiresAt.getTime())
+            ? parsedExpiresAt.toISOString()
+            : null,
+    };
+}
+const recentIpRequests = new Map();
+function pruneOlder(arr, cutoff) {
+    return arr.filter(t => t >= cutoff);
+}
+function recordAndCheckRate(map, key, max) {
+    const now = Date.now();
+    const cutoff = now - 10 * 60 * 1000;
+    const existing = map.get(key) ?? [];
+    const recent = pruneOlder(existing, cutoff);
+    recent.push(now);
+    map.set(key, recent);
+    return recent.length <= max;
+}
+const PENDING_VERIFICATION_TTL_MS = 15 * 60 * 1000;
+/**
+ * Build the base URL used in email-code sign-in emails.
+ *
+ * Preference order:
+ *  1. FRAIM_PUBLIC_BASE_URL env var (explicit canonical override)
+ *  2. X-Forwarded-Proto + X-Forwarded-Host from the request
+ *
+ * Azure App Service sets X-Forwarded-Host to the hostname the user actually
+ * navigated to (validated against configured custom domains / the default
+ * azurewebsites.net hostname), so the derived URL is always a legitimate
+ * origin — no Host-header injection risk in this deployment topology.
+ * Using the request-derived host means sign-in CTA links work correctly regardless
+ * of which of the app's configured hostnames the user accessed.
+ */
+function getCanonicalBaseUrl(req) {
+    const fromEnv = process.env.FRAIM_PUBLIC_BASE_URL;
+    if (fromEnv && /^https?:\/\//i.test(fromEnv)) {
+        return fromEnv.replace(/\/+$/, '');
+    }
+    const proto = req.headers['x-forwarded-proto'] || req.protocol || 'https';
+    const host = req.headers['x-forwarded-host'] || req.get('host') || 'localhost';
+    return `${proto}://${host}`;
+}
+function defaultSignInUrl(req) {
+    const base = getCanonicalBaseUrl(req);
+    return `${base}/auth/sign-in.html`;
+}
+/**
+ * Issue #359 — wire OAuth-first login + email-code recovery + logout endpoints.
+ *
+ * Public routes (no auth middleware required):
+ *   POST /api/auth/email/request     — send a one-time sign-in code
+ *   POST /api/auth/email/verify-code — consume sign-in code, create session
+ *
+ * Authenticated routes (run after auth middleware):
+ *   POST /api/auth/logout            — revoke current session
+ *   POST /api/auth/logout-all        — revoke every session for current user
+ *   GET  /api/auth/session           — return basic identity for current session
+ */
+function registerPublicAuthRoutes(app, deps) {
+    const { dbService } = deps;
+    let cachedEmailService = deps.emailService;
+    const getEmailService = () => {
+        if (!cachedEmailService)
+            cachedEmailService = new email_service_1.EmailService();
+        return cachedEmailService;
+    };
+    // Startup diagnostics.
+    console.log('[FRAIM Auth] startup config check:', {
+        FRAIM_PUBLIC_BASE_URL: process.env.FRAIM_PUBLIC_BASE_URL
+            ? `(set: ${process.env.FRAIM_PUBLIC_BASE_URL})`
+            : '(not set — will derive URL from X-Forwarded-Host at request time)',
+        RESEND_API_KEY: process.env.RESEND_API_KEY ? '(set)' : '(NOT SET — email codes will not send)',
+        RESEND_FROM_EMAIL: process.env.RESEND_FROM_EMAIL || '(not set — using Resend default sender onboarding@resend.dev)',
+        NODE_ENV: process.env.NODE_ENV || '(not set)',
+    });
+    app.post('/api/auth/email/request', async (req, res) => {
+        try {
+            const email = (req.body && (req.body.email ?? req.body.userEmail));
+            const surface = (0, oauth_helpers_1.pickSurfaceOrDefault)(req.body?.surface);
+            if (!(0, oauth_helpers_1.isLikelyValidEmail)(email)) {
+                return res.status(200).json({ ok: true });
+            }
+            const lower = email.toLowerCase();
+            const ip = (0, oauth_helpers_1.clientIpFromReq)(req);
+            const ipOk = recordAndCheckRate(recentIpRequests, ip, MAX_EMAIL_REQUESTS_PER_IP_PER_10MIN);
+            if (!ipOk) {
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_RATE_LIMITED', { ip, reason: 'per_ip', outcome: 'failure' });
+                return res.status(429).json({ ok: false, error: 'rate_limited' });
+            }
+            const emailOk = recordAndCheckRate(recentEmailRequests, lower, MAX_EMAIL_REQUESTS_PER_EMAIL_PER_10MIN);
+            if (!emailOk) {
+                // Always 200 to keep the response enumeration-resistant; just don't send the email.
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_RATE_LIMITED', { userId: lower, ip, reason: 'per_email', outcome: 'failure' });
+                return res.status(200).json({ ok: true });
+            }
+            const token = (0, crypto_1.randomBytes)(32).toString('hex');
+            const signInCode = (0, email_code_1.generateEmailCode)();
+            const now = new Date();
+            try {
+                await dbService.createPendingVerification({
+                    token,
+                    codeHash: (0, email_code_1.hashEmailCode)(lower, signInCode),
+                    email: lower,
+                    verified: false,
+                    expiresAt: new Date(now.getTime() + PENDING_VERIFICATION_TTL_MS),
+                    createdAt: now,
+                    usedAt: null,
+                });
+                const url = defaultSignInUrl(req);
+                await getEmailService().sendEmailCode(lower, url, signInCode, { purpose: 'sign-in' });
+            }
+            catch (innerErr) {
+                // Fires when RESEND_API_KEY is missing/invalid, the sender domain (RESEND_FROM_EMAIL) is not
+                // verified in Resend, or the token/DB write fails. Returns 200 to prevent email enumeration.
+                console.error('[FRAIM AUTH] email-code send failed — check RESEND_API_KEY and verify the sender domain in Resend dashboard (RESEND_FROM_EMAIL):', innerErr instanceof Error ? innerErr.message : String(innerErr));
+            }
+            await (0, audit_log_1.auditLog)('EMAIL_CODE_REQUESTED', { userId: lower, ip, surface, outcome: 'success' });
+            return res.status(200).json({ ok: true });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/email/request error:', err instanceof Error ? err.message : String(err));
+            return res.status(200).json({ ok: true });
+        }
+    });
+    app.post('/api/auth/email/verify-code', async (req, res) => {
+        try {
+            const emailInput = req.body?.email;
+            const codeInput = (0, email_code_1.normalizeEmailCode)(req.body?.code);
+            const surface = (0, oauth_helpers_1.pickSurfaceOrDefault)(req.body?.surface);
+            const requestedRedirect = (0, oauth_helpers_1.safeRedirectPath)(req.body?.redirect_to, (0, oauth_helpers_1.defaultRedirectForSurface)(surface));
+            if (!(0, oauth_helpers_1.isLikelyValidEmail)(emailInput) || codeInput.length < 6) {
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_CONSUMED', { reason: 'invalid_input', outcome: 'failure' });
+                return res.status(400).json({ ok: false, error: 'invalid_code' });
+            }
+            const lower = String(emailInput).toLowerCase();
+            const ip = (0, oauth_helpers_1.clientIpFromReq)(req);
+            const ipOk = recordAndCheckRate(recentIpRequests, `code:${ip}`, MAX_EMAIL_REQUESTS_PER_IP_PER_10MIN);
+            if (!ipOk) {
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_RATE_LIMITED', { userId: lower, ip, reason: 'code_per_ip', outcome: 'failure' });
+                return res.status(429).json({ ok: false, error: 'rate_limited' });
+            }
+            const emailOk = recordAndCheckRate(recentEmailRequests, `code:${lower}`, MAX_EMAIL_REQUESTS_PER_EMAIL_PER_10MIN);
+            if (!emailOk) {
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_RATE_LIMITED', { userId: lower, ip, reason: 'code_per_email', outcome: 'failure' });
+                return res.status(429).json({ ok: false, error: 'rate_limited' });
+            }
+            const pending = await dbService.consumePendingVerificationByCode(lower, (0, email_code_1.hashEmailCode)(lower, codeInput)).catch(() => null);
+            if (!pending) {
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_CONSUMED', { userId: lower, ip, outcome: 'failure', reason: 'invalid_or_expired' });
+                return res.status(401).json({ ok: false, error: 'invalid_or_expired_code' });
+            }
+            const apiKeyData = await dbService.getApiKeyByUserId(lower, false);
+            if (!apiKeyData) {
+                await (0, audit_log_1.auditLog)('EMAIL_CODE_CONSUMED', { userId: lower, ip, outcome: 'failure', reason: 'no_account' });
+                return res.status(404).json({ ok: false, error: 'no_account' });
+            }
+            const sessionId = (0, oauth_helpers_1.generateSessionId)();
+            await dbService.createAuthSession({
+                sessionId,
+                userId: lower,
+                authMethod: 'email-code',
+                userAgent: typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : undefined,
+                ip,
+            });
+            await (0, audit_log_1.auditLog)('EMAIL_CODE_CONSUMED', { userId: lower, ip, outcome: 'success' });
+            await (0, audit_log_1.auditLog)('SESSION_CREATED', { userId: lower, sessionId, surface, outcome: 'success' });
+            (0, cookie_service_1.setSessionCookie)(res, sessionId);
+            if (surface === 'mobile') {
+                return res.status(200).json({ ok: true, mobileCode: issueMobileExchangeCode(apiKeyData.key) });
+            }
+            return res.status(200).json({ ok: true, redirectTo: requestedRedirect });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/email/verify-code error:', err instanceof Error ? err.message : String(err));
+            return res.status(400).json({ ok: false, error: 'invalid_code' });
+        }
+    });
+    // Mobile exchange: trade a short-lived code (created by /api/auth/mobile/claim) for an API key.
+    // Public — the code itself is the proof of authorization.
+    app.post('/api/auth/mobile/exchange', async (req, res) => {
+        try {
+            pruneMobileCodes();
+            const code = String(req.body?.code ?? '').trim();
+            if (!code)
+                return res.status(400).json({ ok: false, error: 'missing_code' });
+            const entry = mobileCodeStore.get(code);
+            if (!entry || entry.expiresAt < Date.now()) {
+                mobileCodeStore.delete(code);
+                return res.status(401).json({ ok: false, error: 'invalid_or_expired_code' });
+            }
+            mobileCodeStore.delete(code); // one-time use
+            return res.status(200).json({ ok: true, apiKey: entry.apiKey });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/mobile/exchange error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+}
+function registerProtectedAuthRoutes(app, deps) {
+    const { dbService } = deps;
+    app.post('/api/auth/logout', async (req, res) => {
+        try {
+            const sessionToken = (0, cookie_service_1.readSessionCookie)(req) || (0, cookie_service_1.readBearerToken)(req);
+            const userId = req.apiKeyData?.userId || null;
+            if (sessionToken) {
+                await dbService.revokeAuthSession(sessionToken);
+                await (0, audit_log_1.auditLog)('LOGOUT', { userId, sessionId: sessionToken, outcome: 'success' });
+            }
+            (0, cookie_service_1.clearSessionCookie)(res);
+            return res.status(200).json({ ok: true });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/logout error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.post('/api/auth/logout-all', async (req, res) => {
+        try {
+            const userId = req.apiKeyData?.userId;
+            if (!userId)
+                return res.status(401).json({ ok: false });
+            const currentSessionId = (0, cookie_service_1.readSessionCookie)(req) || (0, cookie_service_1.readBearerToken)(req) || undefined;
+            const revokedCount = await dbService.revokeAllAuthSessionsForUser(userId, currentSessionId);
+            await (0, audit_log_1.auditLog)('SESSIONS_REVOKED_ALL_OTHERS', { userId, sessionId: currentSessionId, outcome: 'success', revokedCount });
+            return res.status(200).json({ ok: true, revokedCount });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/logout-all error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.get('/api/account/api-key', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            await (0, audit_log_1.auditLog)('KEY_REVEALED', {
+                userId: apiKeyData.userId,
+                sessionId: req.authSession?.sessionId ?? null,
+                outcome: 'success',
+            });
+            return res.status(200).json({
+                ok: true,
+                apiKey: apiKeyData.key,
+                ...serializeApiKeyLifecycle(apiKeyData),
+            });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/api-key error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.post('/api/account/api-key/rotate', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const { randomBytes } = await Promise.resolve().then(() => __importStar(require('crypto')));
+            const newKey = `fraim_${randomBytes(24).toString('hex')}`;
+            const ok = await dbService.rotateApiKey(apiKeyData.key, newKey);
+            if (!ok)
+                return res.status(500).json({ ok: false });
+            await (0, audit_log_1.auditLog)('KEY_ROTATED', {
+                userId: apiKeyData.userId,
+                sessionId: req.authSession?.sessionId ?? null,
+                outcome: 'success',
+            });
+            return res.status(200).json({ ok: true, apiKey: newKey });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/api-key/rotate error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.get('/api/account/sessions', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const sessions = await dbService.listActiveAuthSessionsForUser(apiKeyData.userId);
+            const currentSessionId = req.authSession?.sessionId ?? null;
+            return res.status(200).json({
+                ok: true,
+                currentSessionId,
+                sessions: sessions.map(s => ({
+                    sessionId: s.sessionId,
+                    authMethod: s.authMethod,
+                    createdAt: s.createdAt,
+                    lastSeenAt: s.lastSeenAt,
+                    expiresAt: s.expiresAt,
+                    userAgent: s.userAgent,
+                    ip: s.ip,
+                })),
+            });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/sessions error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.post('/api/account/sessions/:id/revoke', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const targetId = String(req.params.id || '');
+            const target = await dbService.getAuthSession(targetId);
+            if (!target || target.userId !== apiKeyData.userId) {
+                return res.status(404).json({ ok: false });
+            }
+            await dbService.revokeAuthSession(targetId);
+            await (0, audit_log_1.auditLog)('SESSION_REVOKED', {
+                userId: apiKeyData.userId,
+                sessionId: targetId,
+                outcome: 'success',
+                reason: 'user_revoke',
+            });
+            return res.status(200).json({ ok: true });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/sessions/:id/revoke error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.post('/api/account/sessions/revoke-all-others', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const currentSessionId = (0, cookie_service_1.readSessionCookie)(req) || (0, cookie_service_1.readBearerToken)(req) || undefined;
+            const revokedCount = await dbService.revokeAllAuthSessionsForUser(apiKeyData.userId, currentSessionId);
+            await (0, audit_log_1.auditLog)('SESSIONS_REVOKED_ALL_OTHERS', {
+                userId: apiKeyData.userId,
+                sessionId: currentSessionId,
+                outcome: 'success',
+                revokedCount,
+            });
+            return res.status(200).json({ ok: true, revokedCount });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/sessions/revoke-all-others error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.get('/api/account/activity', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const days = Math.min(Math.max(parseInt(String(req.query.days ?? '30'), 10) || 30, 1), 90);
+            const sinceMs = days * 24 * 60 * 60 * 1000;
+            const records = await dbService.listAuditRecordsForUser(apiKeyData.userId, sinceMs, 200);
+            return res.status(200).json({
+                ok: true,
+                days,
+                records: records.map(r => ({
+                    sequence: r.sequence,
+                    ts: r.ts,
+                    event: r.event,
+                    provider: r.provider ?? null,
+                    surface: r.surface ?? null,
+                    ip: r.ip ?? null,
+                    outcome: r.outcome ?? null,
+                })),
+            });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/account/activity error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    app.get('/api/auth/session', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            const authSession = req.authSession;
+            if (!apiKeyData)
+                return res.status(401).json({ ok: false });
+            const rawMethod = authSession?.authMethod ?? 'api-key';
+            // Normalise 'oauth:google' → 'google', 'oauth:github' → 'github', etc.
+            const signInMethod = rawMethod.startsWith('oauth:') ? rawMethod.slice(6) : rawMethod;
+            // count <= 1 means this is the user's first-ever sign-in (the current session is
+            // already persisted when this endpoint is called, so count is 1, not 0).
+            let isFirstSignIn = false;
+            if (authSession?.userId) {
+                const total = await dbService.countTotalAuthSessionsForUser(authSession.userId);
+                isFirstSignIn = total <= 1;
+            }
+            return res.status(200).json({
+                ok: true,
+                // Flat fields consumed by auth-bootstrap.js in embedded pages
+                email: apiKeyData.userId,
+                authMethod: signInMethod,
+                source: req.authSource ?? 'api-key',
+                isFirstSignIn,
+                ...serializeApiKeyLifecycle(apiKeyData),
+                // Nested user object consumed by public/index.html
+                user: {
+                    email: apiKeyData.userId,
+                    signInMethod,
+                    apiKey: apiKeyData.key,
+                    ...serializeApiKeyLifecycle(apiKeyData),
+                },
+            });
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/session error:', err instanceof Error ? err.message : String(err));
+            return res.status(500).json({ ok: false });
+        }
+    });
+    // Mobile claim: authenticated endpoint that generates a short-lived code the mobile app
+    // can exchange for its API key. Called as the redirect_to target after OAuth
+    // so the browser is already authenticated (session cookie set) when it lands here.
+    app.get('/api/auth/mobile/claim', async (req, res) => {
+        try {
+            const apiKeyData = req.apiKeyData;
+            if (!apiKeyData)
+                return res.redirect('/auth/error.html?reason=invalid');
+            const code = issueMobileExchangeCode(apiKeyData.key);
+            // Deep-link back to the app. Express can redirect to non-http schemes.
+            return res.redirect(`fraim://auth/callback?code=${encodeURIComponent(code)}`);
+        }
+        catch (err) {
+            console.error('[FRAIM AUTH] /api/auth/mobile/claim error:', err instanceof Error ? err.message : String(err));
+            return res.redirect('/auth/error.html?reason=invalid');
+        }
+    });
+}
+/**
+ * Test-only helper to reset the in-memory rate-limit state between tests.
+ */
+function __resetAuthRouteRateLimitsForTests() {
+    recentEmailRequests.clear();
+    recentIpRequests.clear();
+}