@payez/next-mvp 4.4.6 → 4.4.8

package/dist/config/env.d.ts

@@ -19,8 +19,6 @@ export declare const API_ENDPOINTS: {
         readonly profile: "/api/account/profile";
         readonly updateProfile: "/api/account/profile";
         readonly maskedInfo: "/api/account/masked-info";
-        readonly sendResetCode: "/api/account/send-reset-code";
-        readonly verifyResetCode: "/api/account/verify-reset-code";
         readonly resetPassword: "/api/account/reset-password";
         readonly changePassword: "/api/account/change-password";
         readonly validatePassword: "/api/account/validate-password";

package/dist/config/env.js

@@ -29,8 +29,6 @@ exports.API_ENDPOINTS = {
         profile: '/api/account/profile',
         updateProfile: '/api/account/profile',
         maskedInfo: '/api/account/masked-info',
-        sendResetCode: '/api/account/send-reset-code',
-        verifyResetCode: '/api/account/verify-reset-code',
         resetPassword: '/api/account/reset-password',
         changePassword: '/api/account/change-password',
         validatePassword: '/api/account/validate-password'

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { AuthProvider, useAuthConfig, useAuthMode, useFederatedProviders, useFed
 export type { AuthConfig } from './types/auth';
 export { makeAuthDecision } from './auth/auth-decision';
 export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from './auth/route-config';
+export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
 export { createMvpMiddleware } from './middleware/create-middleware';
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';
 export type { UserAvatarMenuProps, MobileNavDrawerProps, NavItem, NavSection } from './components/account';

package/dist/index.js

@@ -8,7 +8,7 @@
 // - Better Auth: import { createBetterAuthInstance } from '@payez/next-mvp/auth/better-auth'
 // - Server auth: import { getSession } from '@payez/next-mvp/server/auth'
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.MobileNavDrawer = exports.UserAvatarMenu = exports.createMvpMiddleware = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
+exports.queryAuditLog = exports.writeAuditLog = exports.getHealthMetrics = exports.getErrorMetrics = exports.useAdminAnalytics = exports.useAuditLog = exports.useHealthMetrics = exports.useErrorMetrics = exports.AdminAnalyticsLayout = exports.AuditLogViewer = exports.HealthMetricsCard = exports.ErrorMetricsCard = exports.MobileNavDrawer = exports.UserAvatarMenu = exports.createMvpMiddleware = exports.DEFAULT_CALLBACK = exports.resolveCallbackDestination = exports.isSafeCallbackPath = exports.safeCallbackPath = exports.getRouteConfig = exports.configurePublicRoutes = exports.isUnauthenticatedRoute = exports.makeAuthDecision = exports.useTraditionalAuthEnabled = exports.useFederatedAuthEnabled = exports.useFederatedProviders = exports.useAuthMode = exports.useAuthConfig = exports.AuthProvider = exports.useAnonSession = exports.fetchWithAuth = void 0;
 // Client-safe exports only
 // Client-side utilities
 var fetch_with_auth_1 = require("./client/fetch-with-auth");
@@ -31,6 +31,13 @@ var route_config_1 = require("./auth/route-config");
 Object.defineProperty(exports, "isUnauthenticatedRoute", { enumerable: true, get: function () { return route_config_1.isUnauthenticatedRoute; } });
 Object.defineProperty(exports, "configurePublicRoutes", { enumerable: true, get: function () { return route_config_1.configurePublicRoutes; } });
 Object.defineProperty(exports, "getRouteConfig", { enumerable: true, get: function () { return route_config_1.getRouteConfig; } });
+// The ONE callback-target guard (N7 / PAY-1989): apps import this instead of
+// copying it. Exposed from the main index AND as the subpath ./auth/safe-callback.
+var safe_callback_1 = require("./auth/safe-callback");
+Object.defineProperty(exports, "safeCallbackPath", { enumerable: true, get: function () { return safe_callback_1.safeCallbackPath; } });
+Object.defineProperty(exports, "isSafeCallbackPath", { enumerable: true, get: function () { return safe_callback_1.isSafeCallbackPath; } });
+Object.defineProperty(exports, "resolveCallbackDestination", { enumerable: true, get: function () { return safe_callback_1.resolveCallbackDestination; } });
+Object.defineProperty(exports, "DEFAULT_CALLBACK", { enumerable: true, get: function () { return safe_callback_1.DEFAULT_CALLBACK; } });
 var create_middleware_1 = require("./middleware/create-middleware");
 Object.defineProperty(exports, "createMvpMiddleware", { enumerable: true, get: function () { return create_middleware_1.createMvpMiddleware; } });
 // Account Components

package/dist/lib/idp-client-config.js

@@ -81,6 +81,7 @@ exports.clearConfigRedisCache = clearConfigRedisCache;
 exports.getEnabledProviders = getEnabledProviders;
 require("server-only");
 const crypto_1 = require("crypto");
+const never_in_response_1 = require("./never-in-response");
 // REDIS IS IMPORTED LAZILY, AND THAT IS LOAD-BEARING.
 // A module-scope `import redis from './redis'` drags ioredis into EVERY bundle that
 // touches this file - including instrumentation.ts. Next compiles the instrumentation
@@ -148,6 +149,10 @@ function resolveAuthSecret(fromConfig) {
 function applyEnvSecrets(config) {
     const auth = resolveAuthSecret(config.authSecret);
     logSecretSource('authSecret', auth.source);
+    // PAY-1529: every secret this module resolves is registered as never-in-response HERE, the one place
+    // both fetch paths and the Redis read pass through, so the runtime backstop knows the value whichever
+    // handler later tries to serialize it.
+    (0, never_in_response_1.markNeverInResponse)(auth.value);
     return {
         ...config,
         authSecret: auth.value,
@@ -156,7 +161,9 @@ function applyEnvSecrets(config) {
             const fromEnv = process.env[envVar];
             const source = fromEnv ? `env:${envVar}` : p.clientSecret ? 'idp-config' : 'none';
             logSecretSource(`${p.provider} clientSecret`, source);
-            return { ...p, clientSecret: fromEnv || p.clientSecret };
+            const clientSecret = fromEnv || p.clientSecret;
+            (0, never_in_response_1.markNeverInResponse)(clientSecret);
+            return { ...p, clientSecret };
         }),
     };
 }

package/dist/lib/never-in-response.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PAY-1529 runtime backstop: the signing secret and the OAuth provider client secrets must never be
+ * serialized into an HTTP response body.
+ *
+ * The build-time guard (test/secrets-never-in-response-source-guard.test.cjs) follows values through the
+ * source it can see. This is the layer for what it cannot see — a value that crosses a module boundary,
+ * a structuredClone / Object.assign copy, a helper in a consumer app. It tracks the secret by VALUE:
+ * the loader registers every resolved secret here at the moment it resolves it (applyEnvSecrets), and a
+ * response built with `secretSafeJson` / checked with `assertNoServerSecret` FAILS CLOSED — it throws,
+ * and the route answers 500 — if any registered value appears anywhere in the serialized body, under any
+ * key, at any depth, whatever the code that built it called it.
+ *
+ * Bounds, stated rather than implied:
+ *  - Values shorter than MIN_SECRET_LENGTH are not registered. A short string matches innocent bodies and
+ *    would turn this into an outage generator; real signing and provider secrets are far longer.
+ *  - It protects responses that go through it. Adoption is per handler; the build-time guard is what
+ *    covers the handlers that do not.
+ *  - Nothing here ever logs, returns or throws a secret value.
+ */
+import { NextResponse } from 'next/server';
+export declare const MIN_SECRET_LENGTH = 16;
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+export declare function markNeverInResponse(value: unknown): void;
+export declare class SecretInResponseError extends Error {
+    constructor(where: string);
+}
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+export declare function assertNoServerSecret(body: unknown, where: string): void;
+/** NextResponse.json, refusing any body that carries a registered secret. */
+export declare function secretSafeJson<T>(body: T, init: ResponseInit | undefined, where: string): NextResponse<T>;

package/dist/lib/never-in-response.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretInResponseError = exports.MIN_SECRET_LENGTH = void 0;
+exports.markNeverInResponse = markNeverInResponse;
+exports.assertNoServerSecret = assertNoServerSecret;
+exports.secretSafeJson = secretSafeJson;
+/**
+ * PAY-1529 runtime backstop: the signing secret and the OAuth provider client secrets must never be
+ * serialized into an HTTP response body.
+ *
+ * The build-time guard (test/secrets-never-in-response-source-guard.test.cjs) follows values through the
+ * source it can see. This is the layer for what it cannot see — a value that crosses a module boundary,
+ * a structuredClone / Object.assign copy, a helper in a consumer app. It tracks the secret by VALUE:
+ * the loader registers every resolved secret here at the moment it resolves it (applyEnvSecrets), and a
+ * response built with `secretSafeJson` / checked with `assertNoServerSecret` FAILS CLOSED — it throws,
+ * and the route answers 500 — if any registered value appears anywhere in the serialized body, under any
+ * key, at any depth, whatever the code that built it called it.
+ *
+ * Bounds, stated rather than implied:
+ *  - Values shorter than MIN_SECRET_LENGTH are not registered. A short string matches innocent bodies and
+ *    would turn this into an outage generator; real signing and provider secrets are far longer.
+ *  - It protects responses that go through it. Adoption is per handler; the build-time guard is what
+ *    covers the handlers that do not.
+ *  - Nothing here ever logs, returns or throws a secret value.
+ */
+const server_1 = require("next/server");
+exports.MIN_SECRET_LENGTH = 16;
+const registered = new Set();
+/** Record a value that must never appear in a response body. Non-strings and short strings are ignored. */
+function markNeverInResponse(value) {
+    if (typeof value !== 'string' || value.length < exports.MIN_SECRET_LENGTH)
+        return;
+    registered.add(value);
+    // JSON escapes some characters, so the serialized form of a secret containing `"` or `\` differs from
+    // the raw value. Register that form too, or such a secret would pass through a JSON body unseen.
+    const escaped = JSON.stringify(value).slice(1, -1);
+    if (escaped !== value)
+        registered.add(escaped);
+}
+class SecretInResponseError extends Error {
+    constructor(where) {
+        // The message names the route, never the value.
+        super(`[PAY-1529] Refused to serialize a server secret into the response of ${where}`);
+        this.name = 'SecretInResponseError';
+    }
+}
+exports.SecretInResponseError = SecretInResponseError;
+/** Throws SecretInResponseError if any registered secret appears in `body` once serialized. */
+function assertNoServerSecret(body, where) {
+    if (registered.size === 0 || body === undefined || body === null)
+        return;
+    let text;
+    try {
+        text = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+    catch {
+        // Unserializable: NextResponse.json would throw on it anyway. Fail closed rather than guess.
+        throw new SecretInResponseError(where);
+    }
+    if (!text)
+        return;
+    for (const secret of registered) {
+        if (text.includes(secret))
+            throw new SecretInResponseError(where);
+    }
+}
+/** NextResponse.json, refusing any body that carries a registered secret. */
+function secretSafeJson(body, init, where) {
+    assertNoServerSecret(body, where);
+    return server_1.NextResponse.json(body, init);
+}

package/dist/lib/nextauth-secret.d.ts

@@ -0,0 +1,51 @@
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+import 'server-only';
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+export declare function resolveNextAuthSecret(): Promise<string>;

package/dist/lib/nextauth-secret.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveNextAuthSecret = resolveNextAuthSecret;
+/**
+ * resolveNextAuthSecret - COMPATIBILITY SHIM (restored 2026-09-30, PAY-2005 / N7).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS, AND WHY IT IS A SHIM RATHER THAN A FEATURE
+ * ---------------------------------------------------------------------------
+ * The NextAuth-era broker secret resolver was DELETED in
+ *     4d3d29e6  "feat!: Better Auth 4.0.0 — NextAuth fully removed"
+ * and it is intentionally NOT coming back as first-class API: this package is
+ * Better Auth now, and new apps must not resolve a NextAuth secret at all.
+ *
+ * It is restored here ONLY because ONE consumer is still mid-migration and cannot
+ * take the 4.4.x bump without it:
+ *
+ *   CONSUMER THAT NEEDS THIS: the customer portal
+ *   (`payez_idp_admin_web` / VibeID-Customer-Portal). It is pinned at
+ *   @payez/next-mvp 4.0.46 and still runs BOTH next-auth@4.24 and better-auth; its
+ *   `src/lib/server-session.ts` and `src/lib/session-token.ts` (and 5 route files)
+ *   import `resolveNextAuthSecret` from here. Without this export, bumping the
+ *   portal to 4.4.x breaks its build. BAPert ruled (68003) to ship this scoped
+ *   shim rather than force the portal's full NextAuth->BetterAuth migration
+ *   tonight. That migration is tracked as its own card; WHEN IT LANDS, DELETE
+ *   THIS FILE.
+ *
+ * DO NOT add new consumers. If you are starting an app, use Better Auth's own
+ * secret handling; you do not need this.
+ *
+ * ---------------------------------------------------------------------------
+ * BEHAVIOUR (faithful to the 4.0.46 implementation, with one deliberate change)
+ * ---------------------------------------------------------------------------
+ * Priority: (1) process.env.NEXTAUTH_SECRET if set; (2) fetch from the IDP via a
+ * signed client assertion; (3) cache in-memory 5 min and stamp NEXTAUTH_SECRET.
+ *
+ * DELIBERATE CHANGE, 4.0.46 -> here: 4.0.46 validated the fetched secret with
+ * `validateNextAuthSecret`, which this package's 4.4.x no longer exports (it was
+ * renamed to `validateAuthSecret` with an IDENTICAL body). The shim calls
+ * `validateAuthSecret` - same predicate, current name - so there is no second
+ * copy of the rule. The validation semantics are unchanged.
+ *
+ * SERVER-ONLY: the IDP handshake and NEXTAUTH_SECRET are server concerns.
+ */
+require("server-only");
+const node_crypto_1 = require("node:crypto");
+const secret_validation_1 = require("./secret-validation");
+let cachedSecret = null;
+let lastFetchedAt = 0;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Resolve the NextAuth secret (server-only).
+ *
+ * Priority:
+ * 1) Use process.env.NEXTAUTH_SECRET if present (allows overrides/production)
+ * 2) Fetch from the IDP broker endpoint - the IDP handles all Key Vault/signing
+ * 3) Cache result in-memory and set process.env.NEXTAUTH_SECRET for later calls
+ */
+async function resolveNextAuthSecret() {
+    // Check if already in environment
+    if (process.env.NEXTAUTH_SECRET && process.env.NEXTAUTH_SECRET.trim() !== '') {
+        return process.env.NEXTAUTH_SECRET;
+    }
+    // Check if cached and fresh (within 5 minutes)
+    if (cachedSecret && Date.now() - lastFetchedAt < CACHE_TTL_MS) {
+        return cachedSecret;
+    }
+    // Broker mode: fetch from the IDP (the IDP handles all Key Vault/signing)
+    const base = process.env.IDP_URL;
+    if (!base)
+        throw new Error('IDP_URL environment variable is required');
+    const clientIdStr = process.env.CLIENT_ID;
+    if (!clientIdStr || clientIdStr.trim() === '') {
+        throw new Error('CLIENT_ID is required (e.g., "ideal_resume_website")');
+    }
+    // Step 1: ask the IDP to sign a client assertion (the IDP holds the keys, not us)
+    const signingUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/sign-client-assertion`;
+    const signingResp = await fetch(signingUrl, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': (0, node_crypto_1.randomUUID)().replace(/-/g, ''),
+        },
+        body: JSON.stringify({
+            issuer: clientIdStr,
+            subject: clientIdStr,
+            audience: 'urn:payez:externalauth:nextauthsecret',
+            expires_in: 60,
+        }),
+        cache: 'no-store',
+    });
+    if (!signingResp.ok) {
+        const txt = await signingResp.text().catch(() => 'Unknown error');
+        throw new Error(`Failed to sign client assertion: ${signingResp.status} ${signingResp.statusText} - ${txt}`);
+    }
+    const signingBody = (await signingResp.json().catch(() => ({})));
+    const clientAssertion = signingBody?.data?.client_assertion ??
+        signingBody?.data?.clientAssertion ??
+        signingBody?.client_assertion ??
+        signingBody?.clientAssertion ??
+        signingBody?.data?.ClientAssertion ??
+        signingBody?.ClientAssertion;
+    if (!clientAssertion || typeof clientAssertion !== 'string') {
+        throw new Error('IDP did not return a valid signed client assertion');
+    }
+    // Step 2: use the signed assertion to fetch the NextAuth secret
+    const proxyUrl = `${base.replace(/\/$/, '')}/api/ExternalAuth/next-auth/secret`;
+    const proxyResp = await fetch(proxyUrl, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'X-Client-Id': clientIdStr,
+            'X-Correlation-Id': (0, node_crypto_1.randomUUID)().replace(/-/g, ''),
+        },
+        body: JSON.stringify({ client_assertion: clientAssertion }),
+        cache: 'no-store',
+    });
+    if (!proxyResp.ok) {
+        const txt = await proxyResp.text().catch(() => 'Unknown error');
+        throw new Error(`Proxy error: ${proxyResp.status} ${proxyResp.statusText} - ${txt}`);
+    }
+    const proxyBody = (await proxyResp.json().catch(() => ({})));
+    const secret = proxyBody?.data?.secret ?? proxyBody?.secret;
+    // `configuration` is available from the IDP but deliberately not logged.
+    if (!secret || typeof secret !== 'string') {
+        throw new Error('Proxy did not return a valid NextAuth secret');
+    }
+    // Same predicate as 4.0.46's validateNextAuthSecret, under its current name.
+    const validation = (0, secret_validation_1.validateAuthSecret)(secret);
+    if (!validation.valid) {
+        throw new Error(`Fetched NextAuth secret failed validation: ${validation.reason}`);
+    }
+    cachedSecret = secret;
+    lastFetchedAt = Date.now();
+    process.env.NEXTAUTH_SECRET = secret;
+    console.log('[NEXTAUTH-SECRET] Resolved from IDP (length:', secret.length + ')');
+    return secret;
+}

package/dist/lib/safe-error-response.d.ts

@@ -50,12 +50,6 @@ export declare function idpErrorEnvelope(json: unknown, fallbackMessage?: string
     };
     request_id?: string;
 };
-/**
- * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
- * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
- * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
- * (the caller must be able to tell a refused password from a dead recovery session).
- */
 /**
  * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
  * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
@@ -64,4 +58,10 @@ export declare function idpErrorEnvelope(json: unknown, fallbackMessage?: string
  * no code at all, and calling that 'link expired' loops the user.
  */
 export declare function projectResetTokenInvalid(json: unknown): boolean;
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
 export declare function projectPasswordPolicyRules(json: unknown): string[] | undefined;

package/dist/lib/safe-error-response.js

@@ -93,12 +93,6 @@ function idpErrorEnvelope(json, fallbackMessage = 'Request failed') {
         out.request_id = p.request_id;
     return out;
 }
-/**
- * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
- * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
- * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
- * (the caller must be able to tell a refused password from a dead recovery session).
- */
 /**
  * True only when the IdP EXPLICITLY says the recovery token itself is unusable: details.code token_expired / token_used, or an
  * ASP.NET Identity `InvalidToken` error in details.value (what the served IdP sends when ResetPasswordAsync refuses a used or
@@ -118,6 +112,12 @@ function projectResetTokenInvalid(json) {
         return true;
     return Array.isArray(details.value) && details.value.some((v) => !!v && typeof v === 'object' && v.code === 'InvalidToken');
 }
+/**
+ * PAY-1591: the IdP refuses a reset password with error.details = { code: 'password_policy', rules: [codes], requirements:
+ * [English] }. This route is anonymous, so only the CODES cross, and only the known ones: never `requirements`, never an
+ * unknown string. Returns undefined when this is NOT a password-policy refusal, and [] when it is one but names no rule we know
+ * (the caller must be able to tell a refused password from a dead recovery session).
+ */
 function projectPasswordPolicyRules(json) {
     if (!json || typeof json !== 'object')
         return undefined;

package/dist/lib/two-factor-verify-failure.d.ts

@@ -18,7 +18,38 @@
  */
 import { NextResponse } from 'next/server';
 export type TwoFactorVerifyMethod = 'totp' | 'sms' | 'email' | 'backup_code';
-export type TwoFactorVerifyFailureCode = 'INVALID_CODE' | 'LOCKED' | 'RATE_LIMITED' | 'SESSION_REJECTED' | 'VERIFY_UNAVAILABLE' | 'VERIFY_FAILED';
+export type TwoFactorVerifyFailureCode = 'INVALID_CODE' | 'LOCKED' | 'RATE_LIMITED' | 'SESSION_REJECTED' | 'STEP_UP_FACTOR_NOT_ALLOWED' | 'VERIFY_UNAVAILABLE' | 'VERIFY_FAILED';
+/**
+ * PAY-1611: the IdP's 403 STEP_UP_FACTOR_NOT_ALLOWED refusal (Core ExternalAuthController.DeliveredCodeStepUpRefusal).
+ * A session signed in with an emailed/texted code only cannot re-prove itself with another emailed/texted code; the
+ * IdP says which factors it WILL take and what the user can do instead. The portal can only offer those options if
+ * this BFF relays them, so on that one refusal we emit the code plus ALLOWLISTED copies of the two lists.
+ *
+ * On the wire PayEzControllerBase.OnActionExecuted re-envelopes the action's object: the code is `error.code` and the
+ * object sits under `error.details`, so the lists are `error.details.allowed_methods` / `error.details.next_steps`.
+ * The unenveloped action shape (top-level `error` string, lists at top level) is accepted too.
+ *
+ * NEVER relayed (PAY-1443 stands): `error_description` or any other IdP prose, and any IdP `endpoint` - the consumer
+ * maps each action to its OWN route from a constant table. Unknown methods/actions are dropped, not passed through;
+ * missing or malformed lists give EMPTY lists, never invented ones.
+ */
+export declare const STEP_UP_REFUSAL_CODE = "STEP_UP_FACTOR_NOT_ALLOWED";
+declare const STEP_UP_METHODS: readonly ["totp", "webauthn", "backup_code"];
+declare const STEP_UP_ACTIONS: readonly ["use_authenticator", "reset_password", "enroll_authenticator"];
+export type StepUpMethod = (typeof STEP_UP_METHODS)[number];
+export type StepUpAction = (typeof STEP_UP_ACTIONS)[number];
+export type StepUpNextStep = {
+    action: 'use_authenticator';
+    methods: StepUpMethod[];
+} | {
+    action: Exclude<StepUpAction, 'use_authenticator'>;
+};
+export type StepUpRefusal = {
+    allowed_methods: StepUpMethod[];
+    next_steps: StepUpNextStep[];
+};
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+export declare function stepUpRefusal(status: number, json: unknown): StepUpRefusal | null;
 /**
  * Every string the IDP might have put anywhere in the error envelope, unwrapped from
  * `{ message = X }` ToString form. Classification input only.
@@ -37,9 +68,11 @@ export declare function twoFactorVerifyFailure(result: {
  * so no `message` field is emitted on failure.
  */
 export type TwoFactorSendMethod = 'sms' | 'email';
-export type TwoFactorSendFailureCode = 'RATE_LIMITED' | 'SESSION_REJECTED' | 'SEND_UNAVAILABLE' | 'SEND_FAILED';
-export declare function classifyTwoFactorSendFailure(status: number): TwoFactorSendFailureCode;
+export type TwoFactorSendFailureCode = 'RATE_LIMITED' | 'SESSION_REJECTED' | 'STEP_UP_FACTOR_NOT_ALLOWED' | 'SEND_UNAVAILABLE' | 'SEND_FAILED';
+export declare function classifyTwoFactorSendFailure(status: number, json?: unknown): TwoFactorSendFailureCode;
 export declare function twoFactorSendCodeFailure(result: {
     status: number;
     attemptedRefresh: boolean;
+    json?: unknown;
 }, method: TwoFactorSendMethod): NextResponse;
+export {};

package/dist/lib/two-factor-verify-failure.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STEP_UP_REFUSAL_CODE = void 0;
+exports.stepUpRefusal = stepUpRefusal;
 exports.upstreamErrorTexts = upstreamErrorTexts;
 exports.classifyTwoFactorVerifyFailure = classifyTwoFactorVerifyFailure;
 exports.twoFactorVerifyFailure = twoFactorVerifyFailure;
@@ -61,6 +63,70 @@ const IDP_LOCKED = /^locked$|code\s*=\s*locked/i;
  */
 const IDP_UNAVAILABLE = /^(?:service_unavailable|server_error)$|code\s*=\s*(?:service_unavailable|server_error)\b/i;
 const WRONG_CODE = /\b(invalid|incorrect|wrong|expired)\b[^.]{0,40}\b(code|otp|totp|token)\b|\binvalid_code\b/i;
+/**
+ * PAY-1611: the IdP's 403 STEP_UP_FACTOR_NOT_ALLOWED refusal (Core ExternalAuthController.DeliveredCodeStepUpRefusal).
+ * A session signed in with an emailed/texted code only cannot re-prove itself with another emailed/texted code; the
+ * IdP says which factors it WILL take and what the user can do instead. The portal can only offer those options if
+ * this BFF relays them, so on that one refusal we emit the code plus ALLOWLISTED copies of the two lists.
+ *
+ * On the wire PayEzControllerBase.OnActionExecuted re-envelopes the action's object: the code is `error.code` and the
+ * object sits under `error.details`, so the lists are `error.details.allowed_methods` / `error.details.next_steps`.
+ * The unenveloped action shape (top-level `error` string, lists at top level) is accepted too.
+ *
+ * NEVER relayed (PAY-1443 stands): `error_description` or any other IdP prose, and any IdP `endpoint` - the consumer
+ * maps each action to its OWN route from a constant table. Unknown methods/actions are dropped, not passed through;
+ * missing or malformed lists give EMPTY lists, never invented ones.
+ */
+exports.STEP_UP_REFUSAL_CODE = 'STEP_UP_FACTOR_NOT_ALLOWED';
+const STEP_UP_METHODS = ['totp', 'webauthn', 'backup_code'];
+const STEP_UP_ACTIONS = ['use_authenticator', 'reset_password', 'enroll_authenticator'];
+const STEP_UP_TEXT = 'This session was signed in with an emailed or texted code only, so another emailed or texted code cannot confirm it is you.';
+function allowedMethods(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const m of v) {
+        if (STEP_UP_METHODS.includes(m) && !out.includes(m))
+            out.push(m);
+    }
+    return out;
+}
+/** The step-up refusal's allowlisted lists, or null when this is not that refusal (status 403 + the exact code only). */
+function stepUpRefusal(status, json) {
+    if (status !== 403 || !json || typeof json !== 'object')
+        return null;
+    const j = json;
+    const err = j.error;
+    let code;
+    let src = j;
+    if (err && typeof err === 'object') {
+        const e = err;
+        code = e.code;
+        src = e.details && typeof e.details === 'object' ? e.details : {};
+    }
+    else {
+        code = err;
+    }
+    if (code !== exports.STEP_UP_REFUSAL_CODE)
+        return null;
+    const next_steps = [];
+    const seen = new Set();
+    for (const step of Array.isArray(src.next_steps) ? src.next_steps : []) {
+        if (!step || typeof step !== 'object')
+            continue;
+        const action = step.action;
+        if (typeof action !== 'string' || !STEP_UP_ACTIONS.includes(action) || seen.has(action))
+            continue;
+        seen.add(action);
+        next_steps.push(action === 'use_authenticator'
+            ? { action, methods: allowedMethods(step.methods) }
+            : { action: action });
+    }
+    return { allowed_methods: allowedMethods(src.allowed_methods), next_steps };
+}
+function stepUpResponse(refusal, attemptedRefresh) {
+    return server_1.NextResponse.json({ success: false, error: STEP_UP_TEXT, code: exports.STEP_UP_REFUSAL_CODE, ...refusal, meta: { attemptedRefresh } }, { status: 403 });
+}
 /**
  * Every string the IDP might have put anywhere in the error envelope, unwrapped from
  * `{ message = X }` ToString form. Classification input only.
@@ -95,6 +161,9 @@ function upstreamErrorTexts(json) {
     return out;
 }
 function classifyTwoFactorVerifyFailure(status, json) {
+    // PAY-1611: checked FIRST - an exact code on a 403, so no prose rule below can claim it first.
+    if (stepUpRefusal(status, json))
+        return 'STEP_UP_FACTOR_NOT_ALLOWED';
     // PAY-902 (BAPert R484): the IdP's lockout CODE, not its prose. Door A is post-authentication, so stating
     // the lockout discloses nothing; telling a locked-out user "try again" sends them to spend attempts.
     //
@@ -118,12 +187,17 @@ function classifyTwoFactorVerifyFailure(status, json) {
     return 'VERIFY_FAILED';
 }
 function twoFactorVerifyFailure(result, method) {
+    const refusal = stepUpRefusal(result.status, result.json);
+    if (refusal)
+        return stepUpResponse(refusal, result.attemptedRefresh);
     const code = classifyTwoFactorVerifyFailure(result.status, result.json);
     const error = code === 'INVALID_CODE' ? INVALID_CODE_TEXT[method] : FIXED_TEXT[code];
     return server_1.NextResponse.json({ success: false, error, code, meta: { attemptedRefresh: result.attemptedRefresh } }, { status: result.status });
 }
 const SEND_LABEL = { sms: 'text message', email: 'email' };
-function classifyTwoFactorSendFailure(status) {
+function classifyTwoFactorSendFailure(status, json) {
+    if (stepUpRefusal(status, json))
+        return 'STEP_UP_FACTOR_NOT_ALLOWED'; // PAY-1611, before the 401/403 branch
     if (status === 429)
         return 'RATE_LIMITED';
     if (status === 401 || status === 403)
@@ -133,7 +207,10 @@ function classifyTwoFactorSendFailure(status) {
     return 'SEND_FAILED';
 }
 function twoFactorSendCodeFailure(result, method) {
-    const code = classifyTwoFactorSendFailure(result.status);
+    const refusal = stepUpRefusal(result.status, result.json);
+    if (refusal)
+        return stepUpResponse(refusal, result.attemptedRefresh);
+    const code = classifyTwoFactorSendFailure(result.status, result.json);
     const label = SEND_LABEL[method];
     const error = code === 'RATE_LIMITED' ? FIXED_TEXT.RATE_LIMITED
         : code === 'SESSION_REJECTED' ? `We could not send a ${label} code for this session. Please try again.`

package/dist/middleware/create-middleware.d.ts

@@ -100,4 +100,6 @@ export interface MvpMiddlewareOptions {
     /** Paths exempt from RBAC checks (auth still enforced, just no page-permission check) */
     rbacExemptPaths?: string[];
 }
+/** Login error code for a pre-2FA session that expired before the code was verified (PAY-884). */
+export declare const TWO_FACTOR_TIMEOUT_ERROR = "TwoFactorTimeout";
 export declare function createMvpMiddleware(options?: MvpMiddlewareOptions): (request: NextRequest) => Promise<NextResponse>;