@portaidentity/server 1.7.0

package/dist/routes/interactions.js

@@ -0,0 +1,1074 @@
+/**
+ * Interaction route handlers for the OIDC login, consent, and logout flows.
+ *
+ * These routes handle the `/interaction/:uid` path where the UID is a
+ * node-oidc-provider interaction identifier. The provider redirects users
+ * here during the OIDC authorization flow for login and consent prompts.
+ *
+ * Route structure:
+ *   GET  /interaction/:uid              → showLogin or showConsent (based on prompt)
+ *   POST /interaction/:uid/login        → processLogin (password auth)
+ *   POST /interaction/:uid/magic-link   → sendMagicLink (passwordless auth)
+ *   GET  /interaction/:uid/consent      → showConsent
+ *   POST /interaction/:uid/confirm      → processConsent (approve/deny)
+ *   GET  /interaction/:uid/abort        → abortInteraction
+ *
+ * Security features:
+ *   - CSRF protection on all POST endpoints
+ *   - Rate limiting on login and magic link endpoints
+ *   - User enumeration prevention (generic error messages)
+ *   - Audit logging for all auth events
+ */
+import Router from '@koa/router';
+import { generateCsrfToken, verifyCsrfToken, setCsrfCookie, getCsrfFromCookie, } from '../auth/csrf.js';
+import { checkRateLimit, resetRateLimit, buildLoginRateLimitKey, buildMagicLinkRateLimitKey, loadLoginRateLimitConfig, loadMagicLinkRateLimitConfig, } from '../auth/rate-limiter.js';
+import { sendOtpCodeEmail } from '../auth/email-service.js';
+import { enqueueAccountRecovery } from '../auth/recovery-service.js';
+import { resolveLocale, getTranslationFunction } from '../auth/i18n.js';
+import { renderPage } from '../auth/template-engine.js';
+import { prepareUserForPasswordLogin, verifyLoginPassword, recordLogin, recordPasswordFailure, } from '../users/service.js';
+import { requiresTwoFactor, determineTwoFactorMethod, sendOtpCode } from '../two-factor/service.js';
+import { writeAuditLog } from '../lib/audit-log.js';
+import { logger } from '../lib/logger.js';
+import { getClientByClientId } from '../clients/service.js';
+import { getOrganizationById } from '../organizations/service.js';
+import { getRedis } from '../lib/redis.js';
+import { hasMagicLinkSession, consumeMagicLinkSession } from '../auth/magic-link-session.js';
+import { resolveLoginMethods } from '../clients/resolve-login-methods.js';
+import { purgeExpired } from '../oidc/postgres-adapter.js';
+import { observeProtocolSecurityRejection } from '../oidc/protocol-security-observer.js';
+const defaultEnumerationDependencies = {
+    getCsrfFromCookie,
+    verifyCsrfToken,
+    generateCsrfToken,
+    setCsrfCookie,
+    buildLoginRateLimitKey,
+    buildMagicLinkRateLimitKey,
+    loadLoginRateLimitConfig,
+    loadMagicLinkRateLimitConfig,
+    checkRateLimit,
+    resetRateLimit,
+    resolveLocale,
+    getTranslationFunction,
+    renderPage,
+    prepareUserForPasswordLogin,
+    verifyLoginPassword,
+    recordPasswordFailure,
+    recordLogin,
+    enqueueAccountRecovery,
+    writeAuditLog,
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a branding context object from organization data.
+ * Used to populate template context with org-specific branding.
+ *
+ * @param org - Organization with branding fields
+ * @returns Branding context for templates
+ */
+/**
+ * Resolve the effective login methods for an OIDC provider Client.
+ *
+ * Reads the raw `urn:porta:login_methods` metadata (set by {@link findForOidc}
+ * on the clients service) and applies the inheritance rule via
+ * {@link resolveLoginMethods}:
+ *   - `null` / missing / malformed  → inherit `org.defaultLoginMethods`
+ *   - explicit non-empty array       → use it verbatim
+ *
+ * Malformed metadata (e.g., from a misconfigured adapter) is treated as
+ * `null` to match the safe-fallback semantics of the raw resolver — the
+ * organization default governs in that case rather than failing closed,
+ * which would break all logins if a single client's metadata were corrupt.
+ *
+ * @param client - OIDC provider Client instance (or null/undefined — safe fallback)
+ * @param org - Organization owning the client (read for `defaultLoginMethods`)
+ * @returns Resolved `LoginMethod[]` (always non-empty, matches resolver contract)
+ */
+function resolveLoginMethodsFromOidcClient(client, org) {
+    // oidc-provider's Client objects expose metadata() → Record<string, unknown>.
+    // Missing client or missing metadata function → treat as fully inherited.
+    const metadata = client?.metadata?.();
+    const raw = metadata?.['urn:porta:login_methods'];
+    // Defensive: accept only null or string[]; treat anything else as null.
+    const normalized = Array.isArray(raw) ? raw : null;
+    return resolveLoginMethods(org, { loginMethods: normalized });
+}
+function buildBrandingFromOrg(org) {
+    return {
+        logoUrl: org.brandingLogoUrl,
+        faviconUrl: org.brandingFaviconUrl,
+        primaryColor: org.brandingPrimaryColor ?? '#3B82F6',
+        companyName: org.brandingCompanyName ?? org.name,
+        customCss: org.brandingCustomCss,
+    };
+}
+/**
+ * Build a base template context from an interaction context.
+ * Shared across all interaction route handlers to provide consistent
+ * branding, locale, and CSRF state.
+ *
+ * @param ctx - Koa context with organization state
+ * @param locale - Resolved locale string
+ * @param csrfToken - CSRF token for form protection
+ * @param orgSlug - Organization slug for template resolution
+ * @returns Base template context (without the `t` translation function)
+ */
+function buildBaseContext(ctx, locale, csrfToken, orgSlug) {
+    return {
+        branding: buildBrandingFromOrg(ctx.state.organization),
+        locale,
+        csrfToken,
+        orgSlug,
+    };
+}
+/**
+ * Render an HTML page and send it as the response.
+ * Sets Content-Type to text/html and assigns the rendered body to ctx.body.
+ *
+ * @param ctx - Koa context
+ * @param pageName - Page template name
+ * @param context - Full template context
+ * @param statusCode - HTTP status code (default: 200)
+ */
+async function renderAndRespond(ctx, pageName, context, statusCode = 200, renderer = renderPage) {
+    const html = await renderer(pageName, context);
+    ctx.status = statusCode;
+    ctx.type = 'text/html';
+    ctx.body = html;
+}
+/**
+ * Resolve the organization from the OIDC interaction's client_id.
+ *
+ * Interaction routes (`/interaction/:uid`) don't go through the tenant
+ * resolver middleware, so `ctx.state.organization` is not set automatically.
+ * This helper resolves the org by looking up the client → organization chain
+ * from the interaction's `client_id` parameter, and sets `ctx.state.organization`.
+ *
+ * Also used by two-factor routes which share the same `/interaction` prefix
+ * and likewise don't go through the tenant resolver middleware.
+ *
+ * @param ctx - Koa context to populate with organization
+ * @param clientId - OIDC client_id from the interaction params
+ * @throws Error if client or organization cannot be found
+ */
+export async function resolveOrganizationForInteraction(ctx, clientId, interactionUid) {
+    // If already resolved (e.g., by tenant resolver), skip
+    if (ctx.state.organization)
+        return;
+    // Prefer the auth-flow org stored in Redis during interaction creation.
+    // OIDC entry middleware has already proved that this organization owns the client.
+    if (interactionUid) {
+        try {
+            const storedOrgId = await getRedis().get(`interaction:org:${interactionUid}`);
+            if (storedOrgId) {
+                const org = await getOrganizationById(storedOrgId);
+                if (org) {
+                    ctx.state.organization = org;
+                    return;
+                }
+            }
+        }
+        catch {
+            // Redis error — fall through to client-based resolution
+        }
+    }
+    // Fallback: resolve from the client's organizationId
+    const client = await getClientByClientId(clientId);
+    if (!client) {
+        throw new Error(`Client not found for interaction: ${clientId}`);
+    }
+    const org = await getOrganizationById(client.organizationId);
+    if (!org) {
+        throw new Error(`Organization not found for client: ${client.organizationId}`);
+    }
+    ctx.state.organization = org;
+}
+/**
+ * Resolve continuation authority independently from the magic-link session value.
+ *
+ * The provider writes this tenant mapping when it creates the interaction. A missing, expired, or
+ * malformed mapping cannot authorize consumption and leaves the short-lived session untouched.
+ *
+ * @param interactionUid - Exact interaction selected by the public route.
+ * @returns Active interaction authority, or null when it cannot be proven.
+ */
+async function resolveMagicLinkContinuationAuthority(interactionUid) {
+    if (interactionUid.length < 1 || interactionUid.length > 128)
+        return null;
+    const organizationId = await getRedis().get(`interaction:org:${interactionUid}`);
+    if (!organizationId)
+        return null;
+    const organization = await getOrganizationById(organizationId);
+    if (!organization || organization.status !== 'active')
+        return null;
+    return { authority: { organizationId, interactionUid }, organization };
+}
+/**
+ * Derive recovery-job authority from the provider interaction and its persisted client owner.
+ *
+ * @param routeInteractionUid - Interaction selected by the route.
+ * @param interactionUid - Interaction identifier returned by oidc-provider.
+ * @param clientIdValue - Client identifier returned by oidc-provider.
+ * @param clientOrganizationIdValue - Tenant metadata returned by the admitted provider client.
+ * @param organization - Tenant resolved for the interaction.
+ * @returns Exact job authority, or null when route, provider, client, and tenant do not agree.
+ */
+function deriveMagicLinkRecoveryAuthority(routeInteractionUid, interactionUid, clientIdValue, clientOrganizationIdValue, organization) {
+    if (routeInteractionUid !== interactionUid ||
+        interactionUid.length < 1 ||
+        interactionUid.length > 128 ||
+        typeof clientIdValue !== 'string' ||
+        clientIdValue.length < 1 ||
+        clientOrganizationIdValue !== organization.id) {
+        return null;
+    }
+    return { organizationId: organization.id, interactionUid };
+}
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the interaction router with all OIDC interaction handlers.
+ *
+ * The router handles login, consent, magic link, and abort flows.
+ * Requires a Provider instance to interact with the OIDC session state.
+ *
+ * @param provider - node-oidc-provider instance for interaction management
+ * @returns Koa router with interaction routes mounted at /interaction
+ */
+export function createInteractionRouter(provider, enumerationDependencies = defaultEnumerationDependencies) {
+    const router = new Router({ prefix: '/interaction' });
+    router.use(async (ctx, next) => {
+        try {
+            await next();
+        }
+        catch (error) {
+            if (isMissingInteraction(error)) {
+                observeProtocolSecurityRejection({
+                    request: ctx.req,
+                    eventClass: 'interaction-context-rejected',
+                });
+            }
+            throw error;
+        }
+    });
+    // -------------------------------------------------------------------------
+    // GET /interaction/:uid — Show login or consent page
+    // -------------------------------------------------------------------------
+    router.get('/:uid', async (ctx) => {
+        await showLogin(ctx, provider);
+    });
+    // -------------------------------------------------------------------------
+    // POST /interaction/:uid/login — Process password login
+    // -------------------------------------------------------------------------
+    router.post('/:uid/login', async (ctx) => {
+        await processLogin(ctx, provider, enumerationDependencies);
+    });
+    // -------------------------------------------------------------------------
+    // POST /interaction/:uid/magic-link — Send magic link email
+    // -------------------------------------------------------------------------
+    router.post('/:uid/magic-link', async (ctx) => {
+        await handleSendMagicLink(ctx, provider, enumerationDependencies);
+    });
+    // -------------------------------------------------------------------------
+    // GET /interaction/:uid/consent — Show consent page
+    // -------------------------------------------------------------------------
+    router.get('/:uid/consent', async (ctx) => {
+        await showConsent(ctx, provider);
+    });
+    // -------------------------------------------------------------------------
+    // POST /interaction/:uid/confirm — Process consent (approve/deny)
+    // -------------------------------------------------------------------------
+    router.post('/:uid/confirm', async (ctx) => {
+        await processConsent(ctx, provider);
+    });
+    // -------------------------------------------------------------------------
+    // GET /interaction/:uid/abort — Abort the interaction
+    // -------------------------------------------------------------------------
+    router.get('/:uid/abort', async (ctx) => {
+        await abortInteraction(ctx, provider);
+    });
+    return router;
+}
+/** Identifies the provider's exact expired, absent, or mismatched interaction state error. */
+function isMissingInteraction(error) {
+    if (typeof error !== 'object' || error === null || Array.isArray(error))
+        return false;
+    return Reflect.get(error, 'name') === 'SessionNotFound' && Reflect.get(error, 'status') === 400;
+}
+// ---------------------------------------------------------------------------
+// Route handlers
+// ---------------------------------------------------------------------------
+/**
+ * Show the login page for an OIDC interaction.
+ *
+ * Checks for a `_ml_session` cookie first (set by the magic link handler).
+ * If present, consumes the session and either:
+ *   - Completes the OIDC flow via interactionFinished() (same browser)
+ *   - Shows a "You're signed in" success page (different browser)
+ *
+ * If no magic link session, falls through to the normal login flow:
+ * 1. Loads the interaction details from the provider
+ * 2. If the prompt is "consent", redirects to the consent page
+ * 3. Resolves the locale from OIDC params, Accept-Language, and org default
+ * 4. Generates a CSRF token for form protection
+ * 5. Renders the login page with branding, i18n, and interaction data
+ *
+ * @param ctx - Koa context with organization state
+ * @param provider - OIDC provider instance
+ */
+async function showLogin(ctx, provider) {
+    // -----------------------------------------------------------------------
+    // Opportunistic cleanup: purge expired oidc_payloads records.
+    // Fire-and-forget — no await, no error propagation. Keeps the database
+    // clean without a cron job. Proven pattern from Porta v4.
+    // -----------------------------------------------------------------------
+    purgeExpired();
+    // -----------------------------------------------------------------------
+    // Magic link session detection
+    // -----------------------------------------------------------------------
+    if (hasMagicLinkSession(ctx)) {
+        const continuationAuthority = await resolveMagicLinkContinuationAuthority(ctx.params.uid);
+        const session = continuationAuthority
+            ? await consumeMagicLinkSession(ctx, continuationAuthority.authority)
+            : null;
+        if (session && continuationAuthority) {
+            const org = continuationAuthority.organization;
+            // Try to complete the OIDC flow (same browser — interaction cookies present)
+            try {
+                const result = {
+                    login: { accountId: session.userId },
+                };
+                await provider.interactionFinished(ctx.req, ctx.res, result, {
+                    mergeWithLastSubmission: false,
+                });
+                return; // Success! Browser redirected to callback with code
+            }
+            catch {
+                // Different browser — interaction cookies not present, or interaction expired.
+                // Show the magic link success page instead.
+                logger.info({ event: 'magic_link_cross_browser_success' }, 'Magic link interaction cookies unavailable; showing success page');
+                await renderMagicLinkSuccessPage(ctx, org);
+                return;
+            }
+        }
+        // Invalid/expired session — fall through to normal login
+    }
+    // -----------------------------------------------------------------------
+    // Normal login flow
+    // -----------------------------------------------------------------------
+    try {
+        const interaction = await provider.interactionDetails(ctx.req, ctx.res);
+        const { prompt, params } = interaction;
+        // Resolve organization from the interaction's client_id.
+        // Interaction routes don't go through the tenant resolver middleware,
+        // so we resolve the org from the client → organization chain.
+        await resolveOrganizationForInteraction(ctx, params.client_id, interaction.uid);
+        // If the prompt is consent, handle it directly (no redirect).
+        // Redirecting to /consent as a separate request can lose the interaction
+        // cookie in some flows (e.g., pre-auth magic link), because the cookie
+        // was set by the provider on the redirect chain and a Koa redirect
+        // doesn't carry it forward reliably.
+        if (prompt.name === 'consent') {
+            await showConsent(ctx, provider);
+            return;
+        }
+        const org = ctx.state.organization;
+        // Resolve locale from OIDC ui_locales, Accept-Language, and org default
+        const uiLocales = params.ui_locales;
+        const acceptLanguage = ctx.get('Accept-Language') || undefined;
+        const locale = await resolveLocale(uiLocales, acceptLanguage, org.defaultLocale);
+        // Get translation function with org-specific overrides
+        const t = getTranslationFunction(locale, org.slug);
+        // Generate CSRF token for form protection
+        const csrfToken = generateCsrfToken();
+        setCsrfCookie(ctx, csrfToken);
+        // Pre-fill email from login_hint if provided.
+        //
+        // login_hint comes from the client-supplied authorization URL — OIDC spec
+        // allows any opaque identifier, not just emails, so we do NOT validate
+        // format. We DO defensively trim and length-cap at RFC 5321 max (320 chars)
+        // to avoid pathological template renders. Handlebars HTML-escapes on
+        // interpolation, which blocks XSS via the value="" attribute.
+        const rawHint = typeof params.login_hint === 'string' ? params.login_hint.trim().slice(0, 320) : '';
+        const emailHint = rawHint.length > 0 ? rawHint : undefined;
+        // Resolve human-readable client name from OIDC provider metadata.
+        // Falls back to the raw client_id if not found.
+        const oidcClient = await provider.Client.find(params.client_id);
+        const clientName = oidcClient?.metadata()?.client_name ?? params.client_id;
+        // Resolve the effective login methods from the client's OIDC metadata.
+        // When no client is found (edge case — client deleted mid-flow), fall back
+        // to the org default methods so the user sees SOMETHING actionable instead
+        // of a blank page.
+        const effectiveMethods = oidcClient
+            ? resolveLoginMethodsFromOidcClient(oidcClient, org)
+            : org.defaultLoginMethods;
+        const showPassword = effectiveMethods.includes('password');
+        const showMagicLink = effectiveMethods.includes('magic_link');
+        const context = {
+            ...buildBaseContext(ctx, locale, csrfToken, org.slug),
+            t,
+            interaction: {
+                uid: interaction.uid,
+                prompt: prompt.name,
+                params: params,
+                client: { clientName },
+            },
+            email: emailHint ?? '',
+            emailHint,
+            // Login method rendering flags — consumed by login.hbs
+            showPassword,
+            showMagicLink,
+            showDivider: showPassword && showMagicLink,
+            loginMethods: effectiveMethods,
+        };
+        // Render the login page with CSRF token in both cookie and hidden field
+        await renderAndRespond(ctx, 'login', context);
+    }
+    catch {
+        logger.error({ event: 'login-page-failed' }, 'Login page rendering failed');
+        await renderErrorPage(ctx, 'errors.interaction_expired');
+    }
+}
+/**
+ * Render the magic link success page — "You're signed in".
+ *
+ * Shown when a magic link is opened in a different browser than the one
+ * that started the OIDC authorization flow. The OIDC flow can't be
+ * completed (no interaction cookies), but the user IS authenticated.
+ *
+ * Security guard: this function is ONLY called when a valid `_ml_session`
+ * was present and successfully consumed. The `_ml_session` is single-use
+ * (Redis key deleted), so this page cannot be shown twice or by URL crafting.
+ *
+ * @param ctx - Koa context
+ * @param org - Organization for branding
+ */
+async function renderMagicLinkSuccessPage(ctx, org) {
+    const locale = await resolveLocale(undefined, ctx.get('Accept-Language') || undefined, org.defaultLocale);
+    const t = getTranslationFunction(locale, org.slug);
+    const csrfToken = generateCsrfToken();
+    const context = {
+        branding: buildBrandingFromOrg(org),
+        locale,
+        t,
+        csrfToken,
+        orgSlug: org.slug,
+    };
+    await renderAndRespond(ctx, 'magic-link-success', context);
+}
+/**
+ * Process a password-based login attempt.
+ *
+ * 1. Verifies CSRF token from form submission
+ * 2. Extracts email + password from the request body
+ * 3. Checks rate limits (per IP+email combination)
+ * 4. Looks up user by org + email
+ * 5. Verifies password and checks user status
+ * 6. On success: records login, resets rate limit, finishes interaction
+ * 7. On failure: renders login page with generic error (prevents enumeration)
+ *
+ * @param ctx - Koa context with organization state
+ * @param provider - OIDC provider instance
+ */
+async function processLogin(ctx, provider, dependencies) {
+    const body = ctx.request.body;
+    const email = (body.email ?? '').trim().toLowerCase();
+    const password = body.password ?? '';
+    const submittedCsrf = body._csrf ?? '';
+    const storedCsrf = dependencies.getCsrfFromCookie(ctx) ?? '';
+    try {
+        const interaction = await provider.interactionDetails(ctx.req, ctx.res);
+        // Resolve organization from the interaction's client_id
+        await resolveOrganizationForInteraction(ctx, interaction.params.client_id, interaction.uid);
+        const org = ctx.state.organization;
+        // Resolve locale for error messages
+        const locale = await dependencies.resolveLocale(undefined, ctx.get('Accept-Language') || undefined, org.defaultLocale);
+        const t = dependencies.getTranslationFunction(locale, org.slug);
+        // Step 1: Verify CSRF token (cookie vs form field)
+        if (!dependencies.verifyCsrfToken(storedCsrf, submittedCsrf)) {
+            logger.warn({ event: 'login-csrf-rejected' }, 'Login request CSRF validation failed');
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.csrf_invalid'), 200, dependencies);
+            return;
+        }
+        // Step 1.5: Enforce login method — 'password' must be allowed for this client.
+        //
+        // This check protects against three scenarios:
+        //   1. User submits the password form after an admin switched the client
+        //      to magic-link-only (stale form cached in the browser).
+        //   2. Adversary crafts a direct POST to bypass the UI guard (the template
+        //      hides the password form, but a raw POST from curl/Postman still
+        //      reaches this handler).
+        //   3. Browser back button resurrects the form after login method change.
+        //
+        // Rendering the login page (not a raw 403) preserves CSRF/state and gives
+        // the user a clear, actionable error message.
+        const oidcClientForLogin = await provider.Client.find(interaction.params.client_id);
+        const effectiveLoginMethods = oidcClientForLogin
+            ? resolveLoginMethodsFromOidcClient(oidcClientForLogin, org)
+            : org.defaultLoginMethods;
+        if (!effectiveLoginMethods.includes('password')) {
+            logger.warn({ event: 'password-login-method-disabled' }, 'Password login method is disabled');
+            dependencies.writeAuditLog({
+                organizationId: org.id,
+                eventType: 'security.login_method_disabled',
+                eventCategory: 'security',
+                description: 'Password login attempted where the method is disabled',
+                ipAddress: ctx.ip,
+                metadata: {
+                    clientId: interaction.params.client_id,
+                    attemptedMethod: 'password',
+                    effectiveMethods: effectiveLoginMethods,
+                },
+            });
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.login_method_disabled'), 403, dependencies);
+            return;
+        }
+        // Step 2: Check rate limit
+        const rateLimitKey = dependencies.buildLoginRateLimitKey(org.id, ctx.ip, email);
+        const rateLimitConfig = await dependencies.loadLoginRateLimitConfig();
+        const rateLimitResult = await dependencies.checkRateLimit(rateLimitKey, rateLimitConfig);
+        if (!rateLimitResult.allowed) {
+            ctx.set('Retry-After', String(rateLimitResult.retryAfter));
+            // Audit: rate limit exceeded
+            dependencies.writeAuditLog({
+                organizationId: org.id,
+                eventType: 'rate_limit.login',
+                eventCategory: 'security',
+                description: 'Login rate limit exceeded',
+                ipAddress: ctx.ip,
+            });
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.rate_limit_exceeded'), 429, dependencies);
+            return;
+        }
+        // Resolve cooldown state and verify exactly one real or dummy Argon2id hash. Only active
+        // accounts with passwords receive authentication authority; every other state follows the
+        // same verification and persistence shape.
+        const observedUser = await dependencies.prepareUserForPasswordLogin(org.id, email);
+        const eligibleUser = observedUser?.status === 'active' && observedUser.hasPassword ? observedUser : null;
+        const passwordValid = await dependencies.verifyLoginPassword(eligibleUser?.id ?? null, password);
+        if (!eligibleUser || !passwordValid) {
+            const lockResult = await dependencies.recordPasswordFailure(eligibleUser);
+            void dependencies.writeAuditLog({
+                organizationId: org.id,
+                eventType: 'user.login.password.failed',
+                eventCategory: 'security',
+                description: 'Password login rejected',
+                ipAddress: ctx.ip,
+                metadata: { failedCount: lockResult.failedCount, autoLocked: lockResult.locked },
+            });
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('login.error_invalid'), 200, dependencies);
+            return;
+        }
+        const user = eligibleUser;
+        // Step 6: Password valid — check if 2FA is required
+        await dependencies.resetRateLimit(rateLimitKey);
+        // Determine 2FA requirements based on org policy and user state
+        const twoFactorRequired = user.twoFactorEnabled || requiresTwoFactor(org, user);
+        const twoFactorMethod = determineTwoFactorMethod(org, user);
+        if (twoFactorRequired) {
+            // Store pending login in the interaction session — user must complete 2FA
+            await provider.interactionResult(ctx.req, ctx.res, {
+                twoFactor: {
+                    pendingAccountId: user.id,
+                    method: twoFactorMethod ?? 'email',
+                    email: user.email,
+                },
+            }, { mergeWithLastSubmission: true });
+            // If method is email, auto-send the first OTP code
+            if (twoFactorMethod === 'email' || (!user.twoFactorEnabled && !twoFactorMethod)) {
+                try {
+                    const otpCode = await sendOtpCode(user.id, user.email, org.id);
+                    // Send the OTP code via email (fire-and-forget)
+                    sendOtpCodeEmail({
+                        id: user.id,
+                        email: user.email,
+                        givenName: user.givenName,
+                        familyName: user.familyName,
+                    }, {
+                        id: org.id,
+                        slug: org.slug,
+                        brandingLogoUrl: org.brandingLogoUrl,
+                        brandingPrimaryColor: org.brandingPrimaryColor,
+                        brandingCompanyName: org.brandingCompanyName,
+                    }, otpCode, 10, locale);
+                }
+                catch {
+                    logger.warn({ event: 'login-otp-delivery-failed' }, 'Initial OTP delivery failed');
+                }
+            }
+            writeAuditLog({
+                organizationId: org.id,
+                userId: user.id,
+                eventType: '2fa.challenge.started',
+                eventCategory: 'authentication',
+                description: `Two-factor challenge initiated (${twoFactorMethod ?? 'setup_required'})`,
+                ipAddress: ctx.ip,
+            });
+            // Redirect to the 2FA verification page (or setup page if not enrolled)
+            if (user.twoFactorEnabled) {
+                ctx.redirect(`/interaction/${interaction.uid}/two-factor`);
+            }
+            else {
+                // User needs to set up 2FA first (org requires it but user hasn't enrolled)
+                ctx.redirect(`/interaction/${interaction.uid}/two-factor/setup`);
+            }
+            return;
+        }
+        // No 2FA required — complete login normally
+        await dependencies.recordLogin(user.id);
+        // Audit: successful login (no 2FA)
+        dependencies.writeAuditLog({
+            organizationId: org.id,
+            userId: user.id,
+            eventType: 'user.login.password',
+            eventCategory: 'authentication',
+            description: 'Password login successful',
+            ipAddress: ctx.ip,
+        });
+        // Finish the OIDC interaction with the logged-in user
+        const result = {
+            login: { accountId: user.id },
+        };
+        await provider.interactionFinished(ctx.req, ctx.res, result, {
+            mergeWithLastSubmission: false,
+        });
+    }
+    catch {
+        logger.error({ event: 'login-processing-failed' }, 'Login processing failed');
+        await renderErrorPage(ctx, 'errors.interaction_expired');
+    }
+}
+/**
+ * Send a magic link email for passwordless authentication.
+ *
+ * Always shows the "check your email" page regardless of whether the
+ * user exists — this prevents user enumeration attacks. If the user is
+ * found and active, generates a token, stores it, and sends the email.
+ *
+ * @param ctx - Koa context with organization state
+ * @param provider - OIDC provider instance
+ */
+async function handleSendMagicLink(ctx, provider, dependencies) {
+    const body = ctx.request.body;
+    const email = (body.email ?? '').trim().toLowerCase();
+    const submittedCsrf = body._csrf ?? '';
+    const storedCsrf = dependencies.getCsrfFromCookie(ctx) ?? '';
+    try {
+        const interaction = await provider.interactionDetails(ctx.req, ctx.res);
+        // Resolve organization from the interaction's client_id
+        await resolveOrganizationForInteraction(ctx, interaction.params.client_id, interaction.uid);
+        const org = ctx.state.organization;
+        // Resolve locale for page rendering
+        const locale = await dependencies.resolveLocale(undefined, ctx.get('Accept-Language') || undefined, org.defaultLocale);
+        const t = dependencies.getTranslationFunction(locale, org.slug);
+        // Verify CSRF token (cookie vs form field)
+        if (!dependencies.verifyCsrfToken(storedCsrf, submittedCsrf)) {
+            logger.warn({ event: 'magic_link_csrf_rejected' }, 'Magic link request rejected by CSRF validation');
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.csrf_invalid'), 200, dependencies);
+            return;
+        }
+        // Enforce login method — 'magic_link' must be allowed for this client.
+        // Mirror of the password-login enforcement above. Same rationale: backend
+        // is the authoritative guard; the template hiding the button is cosmetic.
+        const oidcClientForMagicLink = await provider.Client.find(interaction.params.client_id);
+        const effectiveMagicLinkMethods = oidcClientForMagicLink
+            ? resolveLoginMethodsFromOidcClient(oidcClientForMagicLink, org)
+            : org.defaultLoginMethods;
+        if (!effectiveMagicLinkMethods.includes('magic_link')) {
+            logger.warn({
+                event: 'magic_link_method_disabled',
+                organizationId: org.id,
+                clientId: interaction.params.client_id,
+            }, 'Magic link attempted for client where method is disabled');
+            dependencies.writeAuditLog({
+                organizationId: org.id,
+                eventType: 'security.login_method_disabled',
+                eventCategory: 'security',
+                description: 'Magic link attempted on client where method is disabled',
+                ipAddress: ctx.ip,
+                metadata: {
+                    clientId: interaction.params.client_id,
+                    attemptedMethod: 'magic_link',
+                    effectiveMethods: effectiveMagicLinkMethods,
+                },
+            });
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.login_method_disabled'), 403, dependencies);
+            return;
+        }
+        const recoveryAuthority = deriveMagicLinkRecoveryAuthority(ctx.params.uid, interaction.uid, interaction.params.client_id, oidcClientForMagicLink?.metadata().organizationId, org);
+        if (!recoveryAuthority) {
+            logger.warn({ event: 'magic_link_authority_rejected' }, 'Magic link authority rejected');
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.interaction_expired'), 400, dependencies);
+            return;
+        }
+        // Check rate limit for magic link requests
+        const rateLimitKey = dependencies.buildMagicLinkRateLimitKey(org.id, email);
+        const rateLimitConfig = await dependencies.loadMagicLinkRateLimitConfig();
+        const rateLimitResult = await dependencies.checkRateLimit(rateLimitKey, rateLimitConfig);
+        if (!rateLimitResult.allowed) {
+            ctx.set('Retry-After', String(rateLimitResult.retryAfter));
+            dependencies.writeAuditLog({
+                organizationId: org.id,
+                eventType: 'rate_limit.magic_link',
+                eventCategory: 'security',
+                description: 'Magic link rate limit exceeded',
+                ipAddress: ctx.ip,
+            });
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.rate_limit_exceeded'), 429, dependencies);
+            return;
+        }
+        try {
+            await dependencies.enqueueAccountRecovery({
+                jobType: 'magic_link',
+                organizationId: recoveryAuthority.organizationId,
+                email,
+                interactionUid: recoveryAuthority.interactionUid,
+                actionNonce: submittedCsrf,
+            });
+        }
+        catch {
+            logger.error({ event: 'magic_link_enqueue_failed' }, 'Failed to enqueue magic link');
+            await renderLoginWithError(ctx, provider, interaction, t, locale, email, t('errors.interaction_expired'), 503, dependencies);
+            return;
+        }
+        // Always render the "check your email" page — prevents user enumeration
+        const csrfToken = dependencies.generateCsrfToken();
+        const context = {
+            ...buildBaseContext(ctx, locale, csrfToken, org.slug),
+            t,
+            email,
+            loginUrl: `/interaction/${interaction.uid}`,
+        };
+        await renderAndRespond(ctx, 'magic-link-sent', context, 200, dependencies.renderPage);
+    }
+    catch {
+        logger.error({ event: 'magic_link_request_failed' }, 'Magic link request failed');
+        await renderErrorPage(ctx, 'errors.interaction_expired');
+    }
+}
+/**
+ * Show the consent page for an OIDC interaction.
+ *
+ * If the client belongs to the same organization (first-party app),
+ * auto-consents by immediately finishing the interaction. Otherwise,
+ * renders the consent page with requested scopes and client info.
+ *
+ * @param ctx - Koa context with organization state
+ * @param provider - OIDC provider instance
+ */
+async function showConsent(ctx, provider) {
+    try {
+        const interaction = await provider.interactionDetails(ctx.req, ctx.res);
+        const { prompt, params } = interaction;
+        // Resolve organization from the interaction's client_id
+        await resolveOrganizationForInteraction(ctx, params.client_id, interaction.uid);
+        const org = ctx.state.organization;
+        // Resolve locale for the consent page
+        const uiLocales = params.ui_locales;
+        const acceptLanguage = ctx.get('Accept-Language') || undefined;
+        const locale = await resolveLocale(uiLocales, acceptLanguage, org.defaultLocale);
+        const t = getTranslationFunction(locale, org.slug);
+        // Auto-consent for first-party apps: if the client metadata includes
+        // the org ID matching the current tenant, skip the consent screen
+        const clientId = params.client_id;
+        const client = await provider.Client.find(clientId);
+        if (client) {
+            // Check if this is a first-party client (belongs to the same org)
+            const clientOrgId = client.metadata()?.organizationId;
+            if (clientOrgId && clientOrgId === org.id) {
+                // Auto-consent: finish interaction immediately with consent grant
+                const grant = new provider.Grant({ accountId: interaction.session?.accountId, clientId });
+                // Use prompt.details to grant exactly what the provider requires
+                const details = prompt.details;
+                if (details.missingOIDCScope) {
+                    const scopes = details.missingOIDCScope;
+                    grant.addOIDCScope([...scopes].join(' '));
+                }
+                if (details.missingOIDCClaims) {
+                    const claims = details.missingOIDCClaims;
+                    grant.addOIDCClaims([...claims]);
+                }
+                if (details.missingResourceScopes) {
+                    for (const [indicator, scopes] of Object.entries(details.missingResourceScopes)) {
+                        grant.addResourceScope(indicator, [...scopes].join(' '));
+                    }
+                }
+                // Explicitly grant offline_access if requested — node-oidc-provider
+                // treats it as a consent signal and may not include it in missingOIDCScope,
+                // but the Grant must include it for a refresh_token to be issued.
+                const requestedScope = params.scope ?? '';
+                if (requestedScope.includes('offline_access')) {
+                    grant.addOIDCScope('offline_access');
+                }
+                const grantId = await grant.save();
+                const result = {
+                    consent: { grantId },
+                };
+                writeAuditLog({
+                    organizationId: org.id,
+                    userId: interaction.session?.accountId,
+                    eventType: 'user.consent.granted',
+                    eventCategory: 'authentication',
+                    description: `Auto-consent granted for first-party client ${clientId}`,
+                });
+                await provider.interactionFinished(ctx.req, ctx.res, result, {
+                    mergeWithLastSubmission: true,
+                });
+                return;
+            }
+        }
+        // Third-party client: show the consent page
+        const csrfToken = generateCsrfToken();
+        setCsrfCookie(ctx, csrfToken);
+        const requestedScopes = (params.scope ?? '').split(' ').filter(Boolean);
+        const context = {
+            ...buildBaseContext(ctx, locale, csrfToken, org.slug),
+            t,
+            interaction: {
+                uid: interaction.uid,
+                prompt: prompt.name,
+                params: params,
+                client: { clientName: client?.metadata()?.client_name ?? clientId },
+            },
+            scopes: requestedScopes,
+            clientName: client?.metadata()?.client_name ?? clientId,
+        };
+        await renderAndRespond(ctx, 'consent', context);
+    }
+    catch {
+        logger.error({ event: 'consent-page-failed' }, 'Consent page rendering failed');
+        await renderErrorPage(ctx, 'errors.interaction_expired');
+    }
+}
+/**
+ * Process a consent decision (approve or deny).
+ *
+ * Reads the decision from the form body. On approval, creates a Grant
+ * with the requested scopes. On denial, finishes the interaction with
+ * an access_denied error.
+ *
+ * @param ctx - Koa context with organization state
+ * @param provider - OIDC provider instance
+ */
+async function processConsent(ctx, provider) {
+    const body = ctx.request.body;
+    const submittedCsrf = body._csrf ?? '';
+    const storedCsrf = getCsrfFromCookie(ctx) ?? '';
+    const decision = body.decision; // 'approve' or 'deny'
+    try {
+        const interaction = await provider.interactionDetails(ctx.req, ctx.res);
+        // Resolve organization from the interaction's client_id
+        await resolveOrganizationForInteraction(ctx, interaction.params.client_id, interaction.uid);
+        const org = ctx.state.organization;
+        // Verify CSRF token
+        if (!verifyCsrfToken(storedCsrf, submittedCsrf)) {
+            logger.warn({ event: 'consent-csrf-rejected' }, 'Consent request CSRF validation failed');
+            ctx.status = 403;
+            ctx.body = 'Invalid CSRF token';
+            return;
+        }
+        if (decision === 'approve') {
+            // Create a grant for the approved scopes and claims
+            const clientId = interaction.params.client_id;
+            const grant = new provider.Grant({
+                accountId: interaction.session?.accountId,
+                clientId,
+            });
+            // Use prompt.details to grant exactly what the provider requires
+            const details = interaction.prompt.details;
+            // Grant missing OIDC scopes
+            if (details.missingOIDCScope) {
+                const scopes = details.missingOIDCScope;
+                grant.addOIDCScope([...scopes].join(' '));
+            }
+            // Grant missing OIDC claims
+            if (details.missingOIDCClaims) {
+                const claims = details.missingOIDCClaims;
+                grant.addOIDCClaims([...claims]);
+            }
+            // Grant missing resource scopes
+            if (details.missingResourceScopes) {
+                for (const [indicator, scopes] of Object.entries(details.missingResourceScopes)) {
+                    grant.addResourceScope(indicator, [...scopes].join(' '));
+                }
+            }
+            // Explicitly grant offline_access if requested (see showConsent for details)
+            const requestedScope = interaction.params.scope ?? '';
+            if (requestedScope.includes('offline_access')) {
+                grant.addOIDCScope('offline_access');
+            }
+            const grantId = await grant.save();
+            writeAuditLog({
+                organizationId: org.id,
+                userId: interaction.session?.accountId,
+                eventType: 'user.consent.granted',
+                eventCategory: 'authentication',
+                description: `Consent granted for client ${clientId}`,
+            });
+            const result = {
+                consent: { grantId },
+            };
+            await provider.interactionFinished(ctx.req, ctx.res, result, {
+                mergeWithLastSubmission: true,
+            });
+        }
+        else {
+            // Deny consent
+            writeAuditLog({
+                organizationId: org.id,
+                userId: interaction.session?.accountId,
+                eventType: 'user.consent.denied',
+                eventCategory: 'authentication',
+                description: `Consent denied for client ${interaction.params.client_id}`,
+            });
+            const result = {
+                error: 'access_denied',
+                error_description: 'User denied consent',
+            };
+            await provider.interactionFinished(ctx.req, ctx.res, result, {
+                mergeWithLastSubmission: false,
+            });
+        }
+    }
+    catch {
+        logger.error({ event: 'consent-processing-failed' }, 'Consent processing failed');
+        await renderErrorPage(ctx, 'errors.interaction_expired');
+    }
+}
+/**
+ * Abort an OIDC interaction.
+ *
+ * Finishes the interaction with an access_denied error, effectively
+ * cancelling the authorization flow and redirecting back to the client.
+ *
+ * @param ctx - Koa context with organization state
+ * @param provider - OIDC provider instance
+ */
+async function abortInteraction(ctx, provider) {
+    try {
+        const interaction = await provider.interactionDetails(ctx.req, ctx.res);
+        // Resolve organization from the interaction's client_id
+        await resolveOrganizationForInteraction(ctx, interaction.params.client_id, interaction.uid);
+        const org = ctx.state.organization;
+        writeAuditLog({
+            organizationId: org.id,
+            userId: interaction.session?.accountId,
+            eventType: 'user.consent.denied',
+            eventCategory: 'authentication',
+            description: 'Interaction aborted by user',
+        });
+        const result = {
+            error: 'access_denied',
+            error_description: 'User aborted the interaction',
+        };
+        await provider.interactionFinished(ctx.req, ctx.res, result, {
+            mergeWithLastSubmission: false,
+        });
+    }
+    catch {
+        logger.error({ event: 'interaction-abort-failed' }, 'Interaction abort failed');
+        await renderErrorPage(ctx, 'errors.interaction_expired');
+    }
+}
+// ---------------------------------------------------------------------------
+// Helper: render login page with error
+// ---------------------------------------------------------------------------
+/**
+ * Render the login page with an error flash message.
+ * Used when login fails (wrong password, rate limited, CSRF mismatch, etc.).
+ *
+ * @param ctx - Koa context
+ * @param provider - OIDC provider instance (used to resolve human-readable client name)
+ * @param interaction - OIDC interaction details
+ * @param t - Translation function
+ * @param locale - Resolved locale
+ * @param email - Pre-filled email value
+ * @param errorMessage - Error message to display
+ * @param statusCode - HTTP status code (default: 200)
+ */
+async function renderLoginWithError(ctx, provider, interaction, t, locale, email, errorMessage, statusCode = 200, dependencies = defaultEnumerationDependencies) {
+    const org = ctx.state.organization;
+    const csrfToken = dependencies.generateCsrfToken();
+    dependencies.setCsrfCookie(ctx, csrfToken);
+    // Resolve human-readable client name from provider metadata.
+    // Falls back to raw client_id if the client is not found.
+    const clientId = interaction.params.client_id ?? '';
+    const oidcClient = await provider.Client.find(clientId);
+    const clientName = oidcClient?.metadata()?.client_name ?? clientId;
+    // Resolve effective login methods so the re-rendered login page shows
+    // the correct forms (password, magic-link, or both). Without these flags,
+    // the template's no-methods fallback would incorrectly appear alongside
+    // the flash error message.
+    const effectiveMethods = oidcClient
+        ? resolveLoginMethodsFromOidcClient(oidcClient, org)
+        : org.defaultLoginMethods;
+    const showPassword = effectiveMethods.includes('password');
+    const showMagicLink = effectiveMethods.includes('magic_link');
+    const context = {
+        ...buildBaseContext(ctx, locale, csrfToken, org.slug),
+        t,
+        interaction: {
+            uid: interaction.uid,
+            prompt: interaction.prompt.name,
+            params: interaction.params,
+            client: { clientName },
+        },
+        email,
+        flash: { error: errorMessage },
+        // Login method rendering flags — must match showLogin() to avoid
+        // the "no methods configured" fallback appearing on error re-renders.
+        showPassword,
+        showMagicLink,
+        showDivider: showPassword && showMagicLink,
+        loginMethods: effectiveMethods,
+    };
+    await renderAndRespond(ctx, 'login', context, statusCode, dependencies.renderPage);
+}
+// ---------------------------------------------------------------------------
+// Helper: render error page
+// ---------------------------------------------------------------------------
+/**
+ * Render a generic error page when the interaction cannot be loaded.
+ * Used as a fallback when the interaction has expired or is invalid.
+ *
+ * @param ctx - Koa context
+ * @param errorKey - Translation key for the error message
+ */
+async function renderErrorPage(ctx, errorKey) {
+    try {
+        const org = ctx.state.organization;
+        const orgSlug = org?.slug ?? 'default';
+        const locale = org
+            ? await resolveLocale(undefined, ctx.get('Accept-Language') || undefined, org.defaultLocale)
+            : 'en';
+        const t = getTranslationFunction(locale, orgSlug);
+        const csrfToken = generateCsrfToken();
+        const context = {
+            branding: org
+                ? buildBrandingFromOrg(org)
+                : {
+                    logoUrl: null,
+                    faviconUrl: null,
+                    primaryColor: '#3B82F6',
+                    companyName: 'Porta',
+                    customCss: null,
+                },
+            locale,
+            t,
+            csrfToken,
+            orgSlug,
+            errorMessage: t(errorKey),
+        };
+        await renderAndRespond(ctx, 'error', context, 400);
+    }
+    catch {
+        // Last resort: if even the error page fails, send plain text
+        logger.error({ event: 'interaction-error-render-failed' }, 'Interaction error page failed');
+        ctx.status = 500;
+        ctx.body = 'An error occurred';
+    }
+}
+//# sourceMappingURL=interactions.js.map