@payez/next-mvp 4.4.9 → 4.5.1

package/dist/vibe/sessions.d.ts

@@ -210,29 +210,14 @@ export declare function warnNonNumericUserId(sessionToken: string | undefined, r
 export declare function readSessionRevocationHmac(idpUserId: number): Promise<{
     ok: boolean;
     sessions: IVibeLoginSession[];
+    failure?: string;
 }>;
-/**
- * Determine whether a session is revoked, with an explicit UNKNOWN state
- * (PAY-1882 step 4 producer half).
- *
- * States:
- *   'not_configured' - this deployment has no revocation source (IDP_URL /
- *                      VIBE_CLIENT_ID / VIBE_HMAC_KEY absent). Viable; today's
- *                      behaviour. Logged once, not per request.
- *   'unknown'        - revocation IS configured but the read FAILED (non-OK,
- *                      timeout, throw). Enforcing middleware fails this CLOSED
- *                      by default (revocationFailMode 'closed'); a Vibe-less
- *                      consumer is 'not_configured', not 'unknown', so it is not
- *                      signed out.
- *   'revoked'        - the session's own token hash matches a revoked row, or
- *                      the user has no active session at all.
- *   'active'         - read OK and the session is not revoked.
- *
- * @param idpUserId - The user's IDP ID
- * @param sessionToken - The live session token; hashed to match the stored row.
- *                       When absent, the user-wide check applies (legacy path).
- */
-export declare function getRevocationStatus(idpUserId: number, sessionToken?: string): Promise<RevocationStatus>;
+/** True only for the exact code CONCURRENT_LIMIT (nested error.code, top-level code/errorCode); a non-JSON body falls back to the literal. */
+export declare function isConcurrentLimitBody(bodyText: string): boolean;
+/** Retry-After seconds when the proxy kept it (capped at 2 s: this runs in the request path), else 200-400 ms jitter. */
+export declare function revocationRetryDelayMs(response: Response): number;
+/** Which branch of the revocation decision produced the verdict (PAY-2136 reason log; never a value). */
+export type RevocationRule = 'own_row_revoked' | 'legacy_no_active' | 'legacy_recent_2h' | 'none';
 /**
  * Get session statistics for admin dashboard.
  *
@@ -246,3 +231,6 @@ export declare function getSessionStats(accessToken: string): Promise<{
     byDevice: Record<string, number>;
     recentLogins: number;
 }>;
+/** Test/ops hook: forget every cached verdict and in-flight read. */
+export declare function resetRevocationCache(): void;
+export declare function getRevocationStatus(idpUserId: number, sessionToken?: string): Promise<RevocationStatus>;

package/dist/vibe/sessions.js

@@ -46,10 +46,14 @@ exports.hashSessionToken = hashSessionToken;
 exports.resolveNumericIdpUserId = resolveNumericIdpUserId;
 exports.warnNonNumericUserId = warnNonNumericUserId;
 exports.readSessionRevocationHmac = readSessionRevocationHmac;
-exports.getRevocationStatus = getRevocationStatus;
+exports.isConcurrentLimitBody = isConcurrentLimitBody;
+exports.revocationRetryDelayMs = revocationRetryDelayMs;
 exports.getSessionStats = getSessionStats;
+exports.resetRevocationCache = resetRevocationCache;
+exports.getRevocationStatus = getRevocationStatus;
 const crypto_1 = __importDefault(require("crypto"));
 const token_utils_1 = require("../auth/utils/token-utils");
+const token_log_id_1 = require("../lib/token-log-id");
 // -----------------------------------------------------------------------------
 // CONFIGURATION
 // -----------------------------------------------------------------------------
@@ -457,21 +461,22 @@ async function readSessionRevocationHmac(idpUserId) {
     const signingKey = getEnv('VIBE_HMAC_KEY');
     if (!idpUrl || !clientId || !signingKey) {
         // Caller distinguishes this from a read failure; report ok:false, not [].
-        return { ok: false, sessions: [] };
+        return { ok: false, sessions: [], failure: 'misconfigured' };
     }
     const endpoint = `/v1/collections/${COLLECTION}/tables/${TABLE}/query`;
     const proxyUrl = `${idpUrl}/api/vibe/proxy`;
-    const timestamp = Math.floor(Date.now() / 1000);
-    const signature = generateHmacSignature(signingKey, timestamp, 'POST', endpoint);
-    // NOTE the absence of Authorization. This is the twin's credential.
-    const headers = {
-        'Content-Type': 'application/json',
-        'X-Vibe-Client-Id': clientId,
-        'X-Vibe-Timestamp': String(timestamp),
-        'X-Vibe-Signature': signature,
-    };
-    try {
-        const response = await fetch(proxyUrl, {
+    // Signed per ATTEMPT: the retry below must not reuse a timestamp that has aged.
+    const send = () => {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = generateHmacSignature(signingKey, timestamp, 'POST', endpoint);
+        // NOTE the absence of Authorization. This is the twin's credential.
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Vibe-Client-Id': clientId,
+            'X-Vibe-Timestamp': String(timestamp),
+            'X-Vibe-Signature': signature,
+        };
+        return fetch(proxyUrl, {
             method: 'POST',
             headers,
             body: JSON.stringify({
@@ -485,10 +490,21 @@ async function readSessionRevocationHmac(idpUserId) {
                 },
             }),
         });
+    };
+    try {
+        let response = await send();
+        // PAY-2136: ONE retry, and only for the transient class. The portal's own prefetch burst exceeds the free
+        // tier's concurrency (CONCURRENT_LIMIT, HTTP 429). Keyed on the BODY code, never on Retry-After: the IdP proxy
+        // relays body and status but drops that header (PAY-2143). AUTH_BLOCKED / other 429s and every 5xx are NOT
+        // retried (a block is not transient; a retry only adds a counted failure).
+        if (response.status === 429 && isConcurrentLimitBody(await safeBodyText(response))) {
+            await new Promise((resolve) => setTimeout(resolve, revocationRetryDelayMs(response)));
+            response = await send();
+        }
         if (!response.ok) {
             // PAY-1427: never the raw proxy body - an error page can echo the request.
             console.error(`[vibe-sessions] Revocation read proxy error ${response.status}`);
-            return { ok: false, sessions: [] };
+            return { ok: false, sessions: [], failure: String(response.status) }; // PAY-2136: status only, for the reason log
         }
         const data = await response.json();
         const unwrapped = (data?.data ?? data);
@@ -496,8 +512,38 @@ async function readSessionRevocationHmac(idpUserId) {
     }
     catch (error) {
         console.error('[vibe-sessions] Revocation read failed:', error);
-        return { ok: false, sessions: [] };
+        return { ok: false, sessions: [], failure: 'exception' };
+    }
+}
+/** Body text of a response WITHOUT consuming the caller's copy; '' on any failure. */
+async function safeBodyText(response) {
+    try {
+        return await response.clone().text();
+    }
+    catch {
+        return '';
+    }
+}
+/** True only for the exact code CONCURRENT_LIMIT (nested error.code, top-level code/errorCode); a non-JSON body falls back to the literal. */
+function isConcurrentLimitBody(bodyText) {
+    try {
+        const b = JSON.parse(bodyText);
+        const nested = b?.error?.code;
+        const code = [nested, b?.code, b?.errorCode].find((c) => typeof c === 'string');
+        if (typeof code === 'string')
+            return code === 'CONCURRENT_LIMIT';
+        return false;
     }
+    catch {
+        return /CONCURRENT_LIMIT/.test(bodyText);
+    }
+}
+/** Retry-After seconds when the proxy kept it (capped at 2 s: this runs in the request path), else 200-400 ms jitter. */
+function revocationRetryDelayMs(response) {
+    const ra = Number(response.headers?.get?.('retry-after'));
+    if (Number.isFinite(ra) && ra > 0)
+        return Math.min(ra * 1000, 2000);
+    return 200 + Math.floor(Math.random() * 200);
 }
 /**
  * THE one revocation decision (PAY-2037 step 1, BAPert 69150): hash-first, per session.
@@ -509,12 +555,15 @@ async function readSessionRevocationHmac(idpUserId) {
  * rule apply: no active row -> the most recently revoked (none revoked: not revoked); else any revoked inside 2h.
  */
 function findRevokingSession(sessions, sessionTokenHash) {
+    return findRevokingSessionWithRule(sessions, sessionTokenHash).row;
+}
+function findRevokingSessionWithRule(sessions, sessionTokenHash) {
     if (sessions.length === 0)
-        return null;
+        return { row: null, rule: 'none' };
     if (sessionTokenHash) {
         const matching = sessions.find(s => s.session_token_hash === sessionTokenHash);
         if (matching)
-            return matching.status === 'revoked' ? matching : null;
+            return matching.status === 'revoked' ? { row: matching, rule: 'own_row_revoked' } : { row: null, rule: 'none' };
     }
     // Hash not found (a legacy row minted before hashing) or no hash given: idealresume's user-wide
     // rules, lib/vibe-sessions.ts:594-651 (BAPert 69189).
@@ -525,11 +574,30 @@ function findRevokingSession(sessions, sessionTokenHash) {
     if (!sessions.some(s => s.status === 'active')) {
         const revoked = sessions.filter(s => s.status === 'revoked' && s.revoked_at).sort(newestFirst);
         if (revoked.length > 0)
-            return revoked[0];
+            return { row: revoked[0], rule: 'legacy_no_active' };
     }
     // Check 2: any row revoked in the last TWO hours (idealresume's window; 5-minute polling needs the time).
     const twoHoursAgo = Date.now() - 2 * 60 * 60 * 1000;
-    return (sessions.filter(s => s.status === 'revoked' && revokedAt(s) > twoHoursAgo).sort(newestFirst)[0] ?? null);
+    const recent = sessions.filter(s => s.status === 'revoked' && revokedAt(s) > twoHoursAgo).sort(newestFirst)[0] ?? null;
+    return recent ? { row: recent, rule: 'legacy_recent_2h' } : { row: null, rule: 'none' };
+}
+/**
+ * PAY-2136: one shape-only line per NON-viable revocation verdict, naming WHICH rule fired. Never a token, userId,
+ * hash, or row content: the rule label, a read-failure status code, a row COUNT and the session's tokenLogId.
+ * Must never throw into the viability path.
+ */
+function logRevocationReason(verdict, reason, sessionToken, extra = {}) {
+    try {
+        console.warn('[REVOCATION] verdict', {
+            verdict,
+            reason,
+            sessionTokenId: sessionToken ? (0, token_log_id_1.tokenLogId)(sessionToken) : null,
+            ...extra,
+        });
+    }
+    catch {
+        /* diagnostic only */
+    }
 }
 /**
  * Determine whether a session is revoked, with an explicit UNKNOWN state
@@ -552,7 +620,7 @@ function findRevokingSession(sessions, sessionTokenHash) {
  * @param sessionToken - The live session token; hashed to match the stored row.
  *                       When absent, the user-wide check applies (legacy path).
  */
-async function getRevocationStatus(idpUserId, sessionToken) {
+async function readRevocationStatus(idpUserId, sessionToken) {
     const idpUrl = getEnv('IDP_URL');
     const clientId = getEnv('VIBE_CLIENT_ID');
     const signingKey = getEnv('VIBE_HMAC_KEY');
@@ -573,16 +641,21 @@ async function getRevocationStatus(idpUserId, sessionToken) {
     // do NOT report "no sessions". 'unknown' is the fail-closed state.
     if (!idpUrl || !signingKey) {
         console.warn('[vibe-sessions] Revocation check MISCONFIGURED (VIBE_CLIENT_ID set but IDP_URL/VIBE_HMAC_KEY missing) - reporting unknown (fail closed)');
+        logRevocationReason('unknown', 'misconfigured', sessionToken);
         return 'unknown';
     }
-    const { ok, sessions } = await readSessionRevocationHmac(idpUserId);
+    const { ok, sessions, failure } = await readSessionRevocationHmac(idpUserId);
     if (!ok) {
         console.warn('[vibe-sessions] Revocation read failed - reporting unknown');
+        logRevocationReason('unknown', `read_failed:${failure ?? 'unknown'}`, sessionToken);
         return 'unknown';
     }
-    return findRevokingSession(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined)
-        ? 'revoked'
-        : 'active';
+    const { row, rule } = findRevokingSessionWithRule(sessions, sessionToken ? hashSessionToken(sessionToken) : undefined);
+    if (row) {
+        logRevocationReason('revoked', rule, sessionToken, { rows: sessions.length });
+        return 'revoked';
+    }
+    return 'active';
 }
 // -----------------------------------------------------------------------------
 // STATISTICS
@@ -631,3 +704,65 @@ async function getSessionStats(accessToken) {
         recentLogins: stats.recentLogins,
     };
 }
+// -----------------------------------------------------------------------------
+// PAY-2136: SINGLE-FLIGHT + SHORT RESULT CACHE for the revocation read
+// -----------------------------------------------------------------------------
+// Every middleware viability check does one revocation read through the IdP proxy for the SAME Vibe client. A page
+// whose chrome prefetches ~4 links makes ~8 checks inside a second; the free tier allows 2 concurrent queries, so
+// the 3rd+ read was a 429 CONCURRENT_LIMIT and (before this change) signed the user out. Now concurrent callers for
+// ONE session share ONE in-flight read, and a CONFIRMED verdict is reused for a few seconds.
+//   - keyed by userId + the token HASH: never shared across sessions or users;
+//   - only 'active' / 'revoked' are cached: a failure ('unknown') is shared while in flight but never remembered, so
+//     the next request reads again; a revoked session is honoured at most REVOCATION_CACHE_MS late;
+//   - REVOCATION_CACHE_MS=0 disables the cache (single-flight still applies).
+const DEFAULT_REVOCATION_CACHE_MS = 5000;
+const MAX_REVOCATION_CACHE_ENTRIES = 2000;
+const revocationInflight = new Map();
+const revocationVerdicts = new Map();
+function revocationCacheMs() {
+    const raw = process.env.REVOCATION_CACHE_MS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_REVOCATION_CACHE_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.min(n, 30_000) : DEFAULT_REVOCATION_CACHE_MS;
+}
+/** Test/ops hook: forget every cached verdict and in-flight read. */
+function resetRevocationCache() {
+    revocationInflight.clear();
+    revocationVerdicts.clear();
+}
+async function getRevocationStatus(idpUserId, sessionToken) {
+    // No token = the user-wide legacy path: nothing session-specific to key on, so no sharing.
+    if (!sessionToken)
+        return readRevocationStatus(idpUserId, sessionToken);
+    const key = `${idpUserId}:${hashSessionToken(sessionToken)}`;
+    const ttl = revocationCacheMs();
+    const now = Date.now();
+    const hit = revocationVerdicts.get(key);
+    if (hit && ttl > 0 && now - hit.at < ttl)
+        return hit.status;
+    if (hit)
+        revocationVerdicts.delete(key);
+    const existing = revocationInflight.get(key);
+    if (existing)
+        return existing;
+    const read = readRevocationStatus(idpUserId, sessionToken)
+        .then((status) => {
+        if (ttl > 0 && (status === 'active' || status === 'revoked')) {
+            if (revocationVerdicts.size >= MAX_REVOCATION_CACHE_ENTRIES) {
+                for (const [k, v] of revocationVerdicts)
+                    if (now - v.at >= ttl)
+                        revocationVerdicts.delete(k);
+                if (revocationVerdicts.size >= MAX_REVOCATION_CACHE_ENTRIES)
+                    revocationVerdicts.clear();
+            }
+            revocationVerdicts.set(key, { status, at: Date.now() });
+        }
+        return status;
+    })
+        .finally(() => {
+        revocationInflight.delete(key);
+    });
+    revocationInflight.set(key, read);
+    return read;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.4.9",
+  "version": "4.5.1",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -575,6 +575,61 @@
       "require": "./dist/pages/verify-code/page.js",
       "default": "./dist/pages/verify-code/page.js"
     },
+    "./dist/pages/onboarding": {
+      "types": "./dist/pages/onboarding/index.d.ts",
+      "require": "./dist/pages/onboarding/index.js",
+      "default": "./dist/pages/onboarding/index.js"
+    },
+    "./pages/onboarding": {
+      "types": "./dist/pages/onboarding/index.d.ts",
+      "require": "./dist/pages/onboarding/index.js",
+      "default": "./dist/pages/onboarding/index.js"
+    },
+    "./components/auth/PasswordResetBridge": {
+      "types": "./dist/components/auth/PasswordResetBridge.d.ts",
+      "require": "./dist/components/auth/PasswordResetBridge.js",
+      "default": "./dist/components/auth/PasswordResetBridge.js"
+    },
+    "./api-handlers/onboarding/verify-code": {
+      "types": "./dist/api-handlers/onboarding/verify-code.d.ts",
+      "require": "./dist/api-handlers/onboarding/verify-code.js",
+      "default": "./dist/api-handlers/onboarding/verify-code.js"
+    },
+    "./api-handlers/onboarding/send-email-code": {
+      "types": "./dist/api-handlers/onboarding/send-email-code.d.ts",
+      "require": "./dist/api-handlers/onboarding/send-email-code.js",
+      "default": "./dist/api-handlers/onboarding/send-email-code.js"
+    },
+    "./api-handlers/onboarding/verify-welcome-email": {
+      "types": "./dist/api-handlers/onboarding/verify-welcome-email.d.ts",
+      "require": "./dist/api-handlers/onboarding/verify-welcome-email.js",
+      "default": "./dist/api-handlers/onboarding/verify-welcome-email.js"
+    },
+    "./api-handlers/onboarding/set-password": {
+      "types": "./dist/api-handlers/onboarding/set-password.d.ts",
+      "require": "./dist/api-handlers/onboarding/set-password.js",
+      "default": "./dist/api-handlers/onboarding/set-password.js"
+    },
+    "./routes/onboarding/verify-code": {
+      "types": "./dist/routes/onboarding/verify-code.d.ts",
+      "require": "./dist/routes/onboarding/verify-code.js",
+      "default": "./dist/routes/onboarding/verify-code.js"
+    },
+    "./routes/onboarding/send-email-code": {
+      "types": "./dist/routes/onboarding/send-email-code.d.ts",
+      "require": "./dist/routes/onboarding/send-email-code.js",
+      "default": "./dist/routes/onboarding/send-email-code.js"
+    },
+    "./routes/onboarding/verify-welcome-email": {
+      "types": "./dist/routes/onboarding/verify-welcome-email.d.ts",
+      "require": "./dist/routes/onboarding/verify-welcome-email.js",
+      "default": "./dist/routes/onboarding/verify-welcome-email.js"
+    },
+    "./routes/onboarding/set-password": {
+      "types": "./dist/routes/onboarding/set-password.d.ts",
+      "require": "./dist/routes/onboarding/set-password.js",
+      "default": "./dist/routes/onboarding/set-password.js"
+    },
     "./pages/admin-login": {
       "types": "./dist/pages/admin-login/page.d.ts",
       "require": "./dist/pages/admin-login/page.js",

package/src/api-handlers/onboarding/send-email-code.ts

@@ -0,0 +1,18 @@
+/**
+ * POST /api/onboarding/send-email-code (PAY-2121).
+ *
+ * Body: { onboard_token } - token-driven, no session. Thin proxy to the IdP's
+ * POST /api/Onboarding/send-email-code. The IdP derives the recipient from the
+ * token's BOUND email only, never from client input, so a tampered link cannot
+ * redirect the code. Also the resend leg the verify card's cooldown fires
+ * against.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const onboardToken = (body as Record<string, unknown>)?.onboard_token;
+  if (!onboardToken) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  return onboardingProxy(req, '/api/Onboarding/send-email-code');
+}

package/src/api-handlers/onboarding/set-password.ts

@@ -0,0 +1,21 @@
+/**
+ * POST /api/onboarding/set-password (PAY-2121).
+ *
+ * Body: { onboard_token, email, reset_token, new_password } - the locked
+ * contract (IdP OnboardingDtos.cs SetPasswordRequest, all four snake_case).
+ * email + reset_token come from the verify-code response; the IdP re-checks
+ * email against the token's bound user before consuming the single-use token.
+ * On success the IdP sets the password AND completes onboarding (issues tokens).
+ * Thin proxy - status and body pass through verbatim.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const b = body as Record<string, unknown>;
+  if (!b?.onboard_token) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  if (!b?.email || !b?.reset_token) return onboardingBadRequest('MISSING_RESET_CONTEXT', 'email and reset_token (from verify-code) are required');
+  if (!b?.new_password) return onboardingBadRequest('MISSING_PASSWORD', 'new_password is required');
+  return onboardingProxy(req, '/api/Onboarding/set-password');
+}

package/src/api-handlers/onboarding/verify-code.ts

@@ -0,0 +1,20 @@
+/**
+ * POST /api/onboarding/verify-code (PAY-2121).
+ *
+ * Body: { onboard_token, code } - token-driven, no session. Thin proxy to the
+ * IdP's POST /api/Onboarding/verify-code, which answers
+ * { success, reset_token, email, client_key } on success (OnboardingDtos.cs
+ * VerifyCodeResponse). reset_token + email are what the set-password step needs
+ * next. The onboard_token IS the auth; there is no session to attach.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const onboardToken = (body as Record<string, unknown>)?.onboard_token;
+  const code = (body as Record<string, unknown>)?.code;
+  if (!onboardToken) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  if (!code) return onboardingBadRequest('MISSING_CODE', 'code is required');
+  return onboardingProxy(req, '/api/Onboarding/verify-code');
+}

package/src/api-handlers/onboarding/verify-welcome-email.ts

@@ -0,0 +1,17 @@
+/**
+ * POST /api/onboarding/verify-welcome-email (PAY-2121).
+ *
+ * Body: { onboard_token } - token-driven, no session. Thin proxy to the IdP's
+ * POST /api/Onboarding/verify-welcome-email, which answers the masked contact
+ * info + expiry the verify card displays. The onboarding page calls this to
+ * render its "check your email / here is what we know" state.
+ */
+import { NextRequest } from 'next/server';
+import { onboardingBadRequest, onboardingProxy } from '../../lib/onboarding-proxy';
+
+export async function POST(req: NextRequest) {
+  const body = await req.json().catch(() => ({} as Record<string, unknown>));
+  const onboardToken = (body as Record<string, unknown>)?.onboard_token;
+  if (!onboardToken) return onboardingBadRequest('MISSING_TOKEN', 'onboard_token is required');
+  return onboardingProxy(req, '/api/Onboarding/verify-welcome-email');
+}

package/src/auth/auth-decision.ts

@@ -26,6 +26,8 @@ export interface AuthContext {
     twoFactorComplete: boolean;
   };
   circuitBreakerOpen: boolean;
+  /** PAY-2136: the request is a router prefetch. A prefetch never clears cookies (see isPrefetchRequest). */
+  isPrefetch?: boolean;
 }
 
 // Output types for the decision engine
@@ -35,9 +37,20 @@ export type AuthAction =
   | { type: 'service_error'; reason: string };
 
 /**
- * Main decision function - pure, testable, deterministic
+ * Main decision function - pure, testable, deterministic.
+ * PAY-2136: when `context.isPrefetch` is set, no redirect it returns asks for cookies to be cleared; the
+ * redirect itself is kept, and the next real navigation reaches the same decision and clears then.
  */
 export function makeAuthDecision(context: AuthContext): AuthAction {
+  const action = decide(context);
+  if (context.isPrefetch && action.type === 'redirect' && action.clearCookies) {
+    const { clearCookies: _dropped, ...rest } = action;
+    return rest;
+  }
+  return action;
+}
+
+function decide(context: AuthContext): AuthAction {
   const {
     pathname,
     isPublicRoute,

package/src/auth/password-reset-bridge.ts

@@ -0,0 +1,98 @@
+/**
+ * PAY-2121: the fragment bridge on `/`.
+ *
+ * The IdP's post-verify redirect for a passwordless account lands on
+ *   ORIGIN/#password_reset_required=true&reset_token=<token>&email=<addr>
+ * - a FRAGMENT, never a query (ProgressiveAuthController.cs:1204-1222). A fresh
+ * @payez/next-mvp app has no fragment handling at all, so the user lands on `/`
+ * and nothing happens; their reset is lost.
+ *
+ * This is the PURE half (data in, data out) so a test can execute it without a
+ * DOM. The client component (PasswordResetBridge) calls it on mount with
+ * `window.location.hash`. The kit's reset surface is the existing
+ * `/account-auth/recovery` page, which reads `?email=` and a reset token - so the
+ * bridge rewrites the fragment into that surface's OWN query shape and navigates
+ * once. It invents no new reset flow.
+ *
+ * CONTRACT:
+ *   '#password_reset_required=true&reset_token=T&email=a%40b.co' -> '/account-auth/recovery?token=T&email=a%40b.co'
+ *   any other fragment (no flag, flag != true, no token) -> null (leave `/` alone)
+ */
+
+/** The reset surface the bridge hands off to, by its existing path. */
+export const RECOVERY_PATH = '/account-auth/recovery';
+
+/**
+ * PAY-2121 (BAPert 70576): the recovery page's ENTRY decision, as a pure function.
+ *
+ * The bridge now sends a VERIFIED passwordless user to
+ *   /account-auth/recovery?token=<reset_token>&email=<addr>
+ * with a REAL reset token in hand. If the page then showed its request-a-code
+ * step, it would throw that token away and the flow would still dead-end - just
+ * one page later. So when a token is present the page must start at the
+ * set-password step and submit straight through resetPasswordWithToken.
+ *
+ *   token present      -> { step: 'set-password', resetToken: <token> }
+ *   no token           -> { step: 'initiate',    resetToken: null }   (today's behaviour)
+ */
+export function recoveryEntry(
+  token: string | null | undefined,
+  email: string | null | undefined,
+): { step: 'set-password' | 'initiate'; resetToken: string | null; email: string } {
+  const tok = (token ?? '').trim();
+  return {
+    step: tok ? 'set-password' : 'initiate',
+    resetToken: tok || null,
+    email: (email ?? '').trim(),
+  };
+}
+
+/**
+ * PAY-2121 (BAPert 70582): the set-password SUBMIT precondition, as a pure
+ * function. The old guard was `if (!passwordResetToken || !recoverySession) return;`.
+ * Removing the session half (so a deep-linked reset can submit) must NOT let a
+ * submit with NO token reach the API carrying an empty token - which is exactly
+ * what a guard-less submit would do. This decides it, in one testable place:
+ *
+ *   resetSubmitTarget(resetToken, sessionEmail, queryEmail):
+ *     - no token (after trim)          -> null   (REFUSE: never call the API with an empty token)
+ *     - token, session email present   -> { token, email: sessionEmail }
+ *     - token, only a query email      -> { token, email: queryEmail }  (the deep-link case)
+ *     - token, but NO email anywhere    -> null   (REFUSE: nothing to reset)
+ *
+ * Returns the exact { token, email } the caller must pass to
+ * accountApi.resetPasswordWithToken, or null to refuse BEFORE any request.
+ */
+export function resetSubmitTarget(
+  resetToken: string | null | undefined,
+  sessionEmail: string | null | undefined,
+  queryEmail: string | null | undefined,
+): { token: string; email: string } | null {
+  const tok = (resetToken ?? '').trim();
+  if (!tok) return null;
+  const email = ((sessionEmail ?? '').trim() || (queryEmail ?? '').trim());
+  if (!email) return null;
+  return { token: tok, email };
+}
+
+/**
+ * The redirect the fragment asks for, or null when the fragment is not a reset
+ * request. `hash` is `window.location.hash` (leading '#' optional).
+ *
+ * Returns null - leaves `/` untouched - when:
+ *   - the fragment is empty;
+ *   - `password_reset_required` is absent or not exactly 'true';
+ *   - no `reset_token` is present (nothing to reset with; not a real link).
+ */
+export function passwordResetRedirect(hash: string | null | undefined): string | null {
+  const raw = (hash ?? '').replace(/^#/, '');
+  if (!raw) return null;
+  const params = new URLSearchParams(raw);
+  if (params.get('password_reset_required') !== 'true') return null;
+  const token = params.get('reset_token') ?? '';
+  if (!token) return null;
+  const email = params.get('email') ?? '';
+  const qs = new URLSearchParams({ token });
+  if (email) qs.set('email', email);
+  return `${RECOVERY_PATH}?${qs.toString()}`;
+}

package/src/auth/route-config.ts

@@ -63,6 +63,23 @@ const defaultUnauthenticatedRoutes: UnauthenticatedRouteConfig[] = [
     allowDuringCircuitBreakerOpen: true,
     requiresRateLimit: false
   },
+  // PAY-2121: the IdP emails an invite link to /account-auth/onboarding and a
+  // post-verify reset FRAGMENT on '/'. Both must be reachable unauthenticated -
+  // the invitee has no session (the onboard_token IS the credential), and the
+  // fragment lands on the already-public root. Listed explicitly, not left to
+  // the /account-auth/* wildcard, so the two conventional paths are visible here.
+  {
+    pattern: '/account-auth/onboarding',
+    description: 'IdP invite/onboarding landing page (token-driven, no session)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: false
+  },
+  {
+    pattern: '/api/onboarding/*',
+    description: 'Onboarding API (token-driven, no session)',
+    allowDuringCircuitBreakerOpen: true,
+    requiresRateLimit: true
+  },
   {
     pattern: '/api/auth/*',
     description: 'Authentication API endpoints',

package/src/components/auth/PasswordResetBridge.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { useEffect } from 'react';
+import { passwordResetRedirect } from '../../auth/password-reset-bridge';
+
+/**
+ * PAY-2121: mount this once on your app's `/` page. When the IdP's post-verify
+ * redirect lands on `/#password_reset_required=true&reset_token=<t>&email=<e>`
+ * (a FRAGMENT), this performs ONE replace to the kit's reset surface and clears
+ * the hash. With any other fragment it renders nothing and leaves `/` alone.
+ *
+ * It renders nothing and reads no user data - it only inspects the fragment.
+ *
+ * @example
+ * // app/page.tsx
+ * import { PasswordResetBridge } from '@payez/next-mvp/components/auth/PasswordResetBridge';
+ * export default function Home() {
+ *   return (&lt;&gt;&lt;PasswordResetBridge /&gt;&lt;/&gt;);
+ * }
+ */
+export function PasswordResetBridge() {
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const target = passwordResetRedirect(window.location.hash);
+    if (target) window.location.replace(target);
+  }, []);
+  return null;
+}
+
+export default PasswordResetBridge;

package/src/edge/middleware.ts

@@ -16,7 +16,7 @@ export {
   get2FABypassConfig
 } from '../auth/route-config';
 export type { UnauthenticatedRouteConfig, ProtectedRouteConfig } from '../auth/route-config';
-export { createMvpMiddleware } from '../middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest } from '../middleware/create-middleware';
 export type {
   MvpMiddlewareOptions,
   CircuitBreakerProvider,