@payez/next-mvp 4.4.9 → 4.5.1

package/src/index.ts

@@ -27,7 +27,7 @@ export { isUnauthenticatedRoute, configurePublicRoutes, getRouteConfig } from '.
 // 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.
 export { safeCallbackPath, isSafeCallbackPath, resolveCallbackDestination, DEFAULT_CALLBACK } from './auth/safe-callback';
-export { createMvpMiddleware } from './middleware/create-middleware';
+export { createMvpMiddleware, isPrefetchRequest } from './middleware/create-middleware';
 
 // Account Components
 export { UserAvatarMenu, MobileNavDrawer } from './components/account';

package/src/lib/onboarding-proxy.ts

@@ -0,0 +1,57 @@
+/**
+ * PAY-2121: shared anonymous IDP proxy for the /api/onboarding/* handlers.
+ *
+ * The onboarding flow is TOKEN-DRIVEN: the invitee has no account or session
+ * yet, and the onboard_token IS the credential. So these calls must NOT go
+ * through idpFetchJSON (which injects a Bearer from a Redis session) - there is
+ * no session. They are plain server-to-server POSTs to the IdP, exactly as the
+ * VibeID portal's hand-built /api/onboarding/* routes do (card 182611).
+ *
+ * WHY A SERVER ROUTE AT ALL, AND NOT A BROWSER CALL: the IdP URL is not exposed
+ * to the browser, and the route is the one place that owns that. The token is
+ * forwarded, never the IdP's host.
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../config/env';
+import { assertAbsoluteIdpUrl } from './idp-url-guard';
+
+/** A typed refusal in the kit's error envelope - used for a missing field, BEFORE any IdP call. */
+export function onboardingBadRequest(code: string, message: string) {
+  return NextResponse.json({ success: false, message, error: { code } }, { status: 400 });
+}
+
+/**
+ * POST a JSON body to `{IDP_URL}{idpPath}` with no credentials, and relay the
+ * IdP's status and body verbatim (the page acts on what the IdP actually
+ * returns, not on a shape this layer guesses). Never relays the IdP error TEXT
+ * for a non-2xx is NOT done here: the onboarding endpoints answer structured
+ * envelopes the page reads; the page owns the copy.
+ */
+export async function onboardingProxy(req: NextRequest, idpPath: string): Promise<NextResponse> {
+  const idpBase = ENV_CONFIG.IDP_URL;
+  if (!idpBase) {
+    return NextResponse.json({ success: false, message: 'IDP_URL is not configured', error: { code: 'NO_IDP_URL' } }, { status: 500 });
+  }
+  const url = `${idpBase}${idpPath}`;
+  assertAbsoluteIdpUrl(url);
+  let bodyText = '{}';
+  try {
+    const raw = await req.text();
+    if (raw && raw.trim().length > 0) bodyText = raw;
+  } catch { /* empty body is fine */ }
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
+  const xfwd = req.headers.get('x-forwarded-for') || req.headers.get('x-real-ip');
+  if (xfwd) headers['X-Forwarded-For'] = xfwd;
+  const ua = req.headers.get('user-agent');
+  if (ua) headers['User-Agent'] = ua;
+
+  let res: Response;
+  try {
+    res = await fetch(url, { method: 'POST', headers, body: bodyText, cache: 'no-store' });
+  } catch {
+    return NextResponse.json({ success: false, message: 'The identity service is unreachable.', error: { code: 'UPSTREAM_UNREACHABLE' } }, { status: 502 });
+  }
+  const json = await res.json().catch(() => null);
+  return NextResponse.json(json ?? { success: res.ok }, { status: res.status });
+}

package/src/lib/session-store.ts

@@ -1048,3 +1048,45 @@ export async function cleanupRefreshLocks(): Promise<number> {
   console.warn('[SESSION-STORE] cleanupRefreshLocks called - scanning for expired locks');
   return 0;
 }
+
+/**
+ * PAY-2136 DIAGNOSTIC (BAPert 70873): which of the session keys EXIST for a token, right now.
+ *
+ * Names/presence only - this returns booleans and the key PREFIX (an app slug, not a secret), never a value and
+ * never any part of the token. It exists so a NO_SESSION can be read for what it was: canonical row gone with the
+ * ba: record alive (the :330 asymmetry), both gone (expired/deleted), or the store could not be asked ('error').
+ *
+ * EXISTS, not GET: it cannot parse, cannot throw on a malformed blob, and cannot return a credential. Each key is
+ * asked separately so one timeout does not hide the other two. Never throws.
+ */
+export type KeyPresence = boolean | 'error';
+export async function describeSessionKeyPresence(
+  sessionToken: string
+): Promise<{ prefix: string; canonical: KeyPresence; ba: KeyPresence; ver: KeyPresence }> {
+  const ask = async (key: string): Promise<KeyPresence> => {
+    try {
+      return (await redis.exists(key)) > 0;
+    } catch {
+      return 'error';
+    }
+  };
+  let prefix = '';
+  try {
+    prefix = getSessionPrefix();
+  } catch {
+    prefix = '';
+  }
+  if (!sessionToken) return { prefix, canonical: false, ba: false, ver: false };
+  let canonicalKey = '';
+  let baKey = '';
+  let verKey = '';
+  try {
+    canonicalKey = getSessionKey(sessionToken);
+    baKey = getBetterAuthSessionKey(sessionToken, getAppSlug());
+    verKey = getSessionVersionKey(sessionToken);
+  } catch {
+    return { prefix, canonical: 'error', ba: 'error', ver: 'error' };
+  }
+  const [canonical, ba, ver] = await Promise.all([ask(canonicalKey), ask(baKey), ask(verKey)]);
+  return { prefix, canonical, ba, ver };
+}

package/src/middleware/create-middleware.ts

@@ -197,8 +197,30 @@ function getSafeCallbackUrl(pathname: string, searchParams?: URLSearchParams): s
   return resolveCallbackDestination(pathname, searchParams);
 }
 
-/** Clear all session cookies on a response */
+/**
+ * PAY-2136 Rule A: a speculative request (router prefetch) must NEVER mutate cookies.
+ * A prefetch of /account/security was answered 307 + Set-Cookie (session cookies expired), the browser
+ * applied it, and the user's next real request (e.g. Approve) was signed out. Detected by any of:
+ * `Next-Router-Prefetch: 1|2` (Next sets it on EVERY Link prefetch; 2 = runtime prefetch) or `Sec-Purpose`/`Purpose`
+ * containing "prefetch".
+ * NOT `RSC: 1` + `_rsc`: a real client-side navigation carries both too (Nextpert-Scout 70976), so that shape
+ * would swallow in-app navigations and stop the middleware refreshing/clearing for them.
+ */
+export function isPrefetchRequest(request: NextRequest): boolean {
+  const h = request.headers;
+  const nrp = h.get('next-router-prefetch');
+  if (nrp === '1' || nrp === '2') return true;
+  if (/prefetch/i.test(h.get('sec-purpose') ?? '') || /prefetch/i.test(h.get('purpose') ?? '')) return true;
+  return false;
+}
+
+/**
+ * Clear all session cookies on a response. The ONE site that writes the expiry Set-Cookie for the middleware,
+ * so the prefetch guard lives here: on a prefetch the redirect is still returned (routing unchanged) but
+ * carries no Set-Cookie; the next real navigation reaches the same decision and clears then.
+ */
 function clearSessionCookies(response: NextResponse, request: NextRequest): void {
+  if (isPrefetchRequest(request)) return;
   const sessionCookie = getSessionCookieName();
   const secureCookie = getSecureSessionCookieName();
 
@@ -736,6 +758,9 @@ async function executeDecision(
       return NextResponse.redirect(new URL('/service-unavailable', request.url));
 
     case 'refresh_needed':
+      // PAY-2136: a speculative request must not spend (rotate) a single-use refresh token or, on a 401/403,
+      // clear the session. Let it through; the real navigation refreshes.
+      if (isPrefetchRequest(request)) return NextResponse.next();
       return handleRefresh(request, safeCallback, opts);
   }
 }

package/src/pages/login/page.tsx

@@ -311,13 +311,10 @@ function LoginForm({ altAuthSlot }: { altAuthSlot?: React.ReactNode }) {
           </div>
         </div>
 
-        {/* Additional Info */}
-        <p className={`mt-4 text-center text-sm ${colors.muted}`}>
-          Don't have an account?{' '}
-          <a href="/account-auth/register" className="themed-link font-medium hover:underline">
-            Sign up
-          </a>
-        </p>
+        {/* PAY-2121: the kit ships no sign-up PAGE (registration is the owner-initiated
+            invite/onboarding flow, not a self-serve screen), so the old "Sign up" link to
+            the register path was a dead end - it 404'd at the developer's site. Removed;
+            the README says how registration is reached. */}
       </div>
     </div>
     </>

package/src/pages/onboarding/index.ts

@@ -0,0 +1,11 @@
+/**
+ * PAY-2121: the onboarding surface.
+ *
+ *   default     - the /account-auth/onboarding page (mount from the scaffold at
+ *                 app/account-auth/onboarding/page.tsx).
+ *   PasswordResetBridge - mount once on `/` to honour the IdP's post-verify
+ *                 `#password_reset_required=true` fragment.
+ */
+export { default } from './page';
+export { default as OnboardingPage } from './page';
+export { PasswordResetBridge } from '../../components/auth/PasswordResetBridge';

package/src/pages/onboarding/page.tsx

@@ -0,0 +1,212 @@
+'use client';
+
+import React, { Suspense, useEffect, useState } from 'react';
+import { useSearchParams } from 'next/navigation';
+
+/**
+ * PAY-2121: the /account-auth/onboarding landing page.
+ *
+ * The IdP's welcome/invite email links to
+ *   {site}/account-auth/onboarding?client_id=<numeric>&onboard_token=<token>
+ * (OnboardingLinkService.BuildOnboardingLink, PayEz-Core). A fresh
+ * @payez/next-mvp app had NO page at that path, so the invitee 404'd at the
+ * developer's own site. This page mounts it.
+ *
+ * It is TOKEN-DRIVEN: the invitee has no account or session; the onboard_token
+ * IS the credential. The page forwards { onboard_token } to the kit's onboarding
+ * API (the /api/onboarding/* handlers), which proxy the IdP. Two steps:
+ *   1. verify-welcome-email -> the masked contact info the invitee recognises;
+ *   2. verify-code -> reset_token + email; then set-password -> onboarding done.
+ *
+ * MOUNTING (what README section 5 asks a consumer to write; the CLI scaffold
+ * writes it too):
+ *   app/account-auth/onboarding/page.tsx:
+ *     export { default } from '@payez/next-mvp/pages/onboarding';
+ *
+ * A missing onboard_token is a typed state, never a crash: it renders a plain
+ * "this link is missing its token" with a way back to sign-in.
+ */
+
+type Step = 'code' | 'password' | 'done';
+
+const H = { primary: 'var(--text-primary)', secondary: 'var(--text-secondary)', muted: 'var(--text-muted)' } as const;
+
+function OnboardingContent() {
+  const params = useSearchParams();
+  const onboardToken = params?.get('onboard_token') ?? '';
+
+  const [step, setStep] = useState<Step>('code');
+  const [maskedEmail, setMaskedEmail] = useState<string | null>(null);
+  const [digits, setDigits] = useState('');
+  const [password, setPassword] = useState('');
+  const [confirm, setConfirm] = useState('');
+  const [resetToken, setResetToken] = useState('');
+  const [email, setEmail] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Step 1: tell the invitee which address the code went to (masked). Best
+  // effort - a failure here does not block entering a code they were emailed.
+  useEffect(() => {
+    if (!onboardToken) return;
+    let alive = true;
+    (async () => {
+      try {
+        const res = await fetch('/api/onboarding/verify-welcome-email', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ onboard_token: onboardToken }),
+        });
+        const body = await res.json().catch(() => null);
+        const data = body?.data?.data || body?.data || {};
+        const masked = data?.masked_user_info?.masked_email || data?.masked_email;
+        if (alive && typeof masked === 'string' && masked) setMaskedEmail(masked);
+      } catch { /* non-fatal */ }
+    })();
+    return () => { alive = false; };
+  }, [onboardToken]);
+
+  if (!onboardToken) {
+    return (
+      <Shell>
+        <h1 style={titleStyle}>This invitation link is missing its token.</h1>
+        <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>
+          The link may have been truncated or copied incompletely. Ask for a new invitation, or sign in if you already have an
+          account.
+        </p>
+        <p style={{ marginTop: 16 }}>
+          <a href="/account-auth/login" style={linkStyle}>Go to sign in</a>
+        </p>
+      </Shell>
+    );
+  }
+
+  async function submitCode(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await fetch('/api/onboarding/verify-code', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ onboard_token: onboardToken, code: digits }),
+      });
+      const body = await res.json().catch(() => null);
+      const data = body?.data?.data || body?.data || body;
+      if (!res.ok || !data?.reset_token || !data?.email) throw new Error();
+      setResetToken(data.reset_token);
+      setEmail(data.email);
+      setStep('password');
+    } catch {
+      setError('That code was not accepted. Check it and try again.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function submitPassword(e: React.FormEvent) {
+    e.preventDefault();
+    if (password !== confirm) { setError('The two passwords do not match.'); return; }
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await fetch('/api/onboarding/set-password', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ onboard_token: onboardToken, email, reset_token: resetToken, new_password: password }),
+      });
+      const body = await res.json().catch(() => null);
+      if (!res.ok || (body && body.success === false)) throw new Error(body?.message || '');
+      setStep('done');
+    } catch (err) {
+      setError(err instanceof Error && err.message ? err.message : 'We could not set that password. Try again.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <Shell>
+      {step === 'code' && (
+        <>
+          <h1 style={titleStyle}>Finish setting up your account</h1>
+          <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>
+            {maskedEmail
+              ? `We emailed a 6-digit code to ${maskedEmail}. Enter it below.`
+              : 'Enter the 6-digit code from your invitation email.'}
+          </p>
+          <form onSubmit={submitCode} noValidate style={{ marginTop: 16 }}>
+            <input
+              value={digits}
+              onChange={(e) => setDigits(e.target.value.replace(/\D/g, '').slice(0, 6))}
+              inputMode="numeric"
+              autoComplete="one-time-code"
+              aria-label="6-digit code"
+              placeholder="000000"
+              style={{ ...inputStyle, letterSpacing: 6, textAlign: 'center', fontFamily: 'monospace', fontSize: 20 }}
+            />
+            <button type="submit" disabled={busy || digits.length < 6} style={ctaStyle(busy || digits.length < 6)}>
+              {busy ? 'Verifying…' : 'Verify'}
+            </button>
+          </form>
+        </>
+      )}
+
+      {step === 'password' && (
+        <>
+          <h1 style={titleStyle}>Choose a password</h1>
+          <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>Set the password you will sign in with.</p>
+          <form onSubmit={submitPassword} noValidate style={{ marginTop: 16 }}>
+            <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} aria-label="New password" placeholder="New password" style={inputStyle} />
+            <input type="password" value={confirm} onChange={(e) => setConfirm(e.target.value)} aria-label="Confirm password" placeholder="Confirm password" style={{ ...inputStyle, marginTop: 10 }} />
+            <button type="submit" disabled={busy || !password || !confirm} style={ctaStyle(busy || !password || !confirm)}>
+              {busy ? 'Saving…' : 'Set password'}
+            </button>
+          </form>
+        </>
+      )}
+
+      {step === 'done' && (
+        <>
+          <h1 style={titleStyle}>You&apos;re all set.</h1>
+          <p style={{ color: H.secondary, fontSize: 14, marginTop: 8 }}>Your account is ready. You can sign in now.</p>
+          <p style={{ marginTop: 16 }}>
+            <a href="/account-auth/login" style={linkStyle}>Go to sign in</a>
+          </p>
+        </>
+      )}
+
+      {error && <p style={{ color: '#b00020', fontSize: 13, marginTop: 12 }}>{error}</p>}
+    </Shell>
+  );
+}
+
+const titleStyle: React.CSSProperties = { color: H.primary, fontSize: 20, fontWeight: 600, margin: 0 };
+const linkStyle: React.CSSProperties = { color: H.primary, fontWeight: 600, textDecoration: 'underline' };
+const inputStyle: React.CSSProperties = {
+  width: '100%', padding: '10px 12px', border: '1px solid var(--border-default, #d1d5db)',
+  borderRadius: 10, color: H.primary, fontSize: 15, background: 'var(--bg-card, #fff)',
+};
+const ctaStyle = (disabled: boolean): React.CSSProperties => ({
+  marginTop: 14, width: '100%', padding: '10px 12px', borderRadius: 10, border: 'none',
+  background: H.primary, color: '#fff', fontWeight: 600, fontSize: 15, cursor: disabled ? 'default' : 'pointer',
+  opacity: disabled ? 0.5 : 1,
+});
+
+function Shell({ children }: { children: React.ReactNode }) {
+  return (
+    <div style={{ minHeight: '100vh', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16, background: 'var(--bg-default, #f9fafb)' }}>
+      <div style={{ width: '100%', maxWidth: 420, background: 'var(--bg-card, #fff)', border: '1px solid var(--border-default, #e5e7eb)', borderRadius: 16, padding: 28 }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export default function OnboardingPage() {
+  return (
+    <Suspense fallback={<div style={{ minHeight: '100vh' }} />}>
+      <OnboardingContent />
+    </Suspense>
+  );
+}

package/src/pages/recovery/page.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect, Suspense } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation';
 import { RecoveryStep, RecoverySession, PasswordResetToken } from '../../types/recovery';
 import { accountApi } from '../../utils/api';
+import { recoveryEntry, resetSubmitTarget } from '../../auth/password-reset-bridge';
 import { InitiateRecoveryStep } from '../../components/recovery/InitiateRecoveryStep';
 import { SelectMethodStep } from '../../components/recovery/SelectMethodStep';
 import { VerifyCodeStep } from '../../components/recovery/VerifyCodeStep';
@@ -15,15 +16,21 @@ import { useColors } from '../../theme/useTheme';
 function RecoveryContent() {
   const router = useRouter();
   const searchParams = useSearchParams();
-  const prefilledEmail = searchParams?.get('email') || '';
+  // PAY-2121 (BAPert 70576): a VERIFIED passwordless user arrives here with a real
+  // reset token (?token=) from the IdP's post-verify fragment, via the bridge. In
+  // that case skip the request-a-code step and go straight to set-password - the
+  // token is the credential; asking for a code would throw it away.
+  const entry = recoveryEntry(searchParams?.get('token'), searchParams?.get('email'));
   const colors = useColors();
 
-  const [currentStep, setCurrentStep] = useState<RecoveryStep>('initiate');
-  const [email, setEmail] = useState(prefilledEmail);
+  const [currentStep, setCurrentStep] = useState<RecoveryStep>(entry.step);
+  const [email, setEmail] = useState(entry.email);
   const [recoverySession, setRecoverySession] = useState<RecoverySession | null>(null);
   const [selectedMethod, setSelectedMethod] = useState<'email' | 'sms' | 'authenticator' | null>(null);
   const [verificationCode, setVerificationCode] = useState('');
-  const [passwordResetToken, setPasswordResetToken] = useState<PasswordResetToken | null>(null);
+  const [passwordResetToken, setPasswordResetToken] = useState<PasswordResetToken | null>(
+    entry.resetToken ? { token: entry.resetToken, expiresAt: '' } : null,
+  );
   const [error, setError] = useState<string | null>(null);
   // PAY-1591: true when the reset failed because the recovery itself is dead; the error box then offers a way back.
   const [recoveryExpired, setRecoveryExpired] = useState(false);
@@ -113,7 +120,14 @@ function RecoveryContent() {
   };
 
   const handleResetPassword = async (password: string, confirmPassword: string) => {
-    if (!passwordResetToken || !recoverySession) return;
+    // PAY-2121 (BAPert 70582): the ONE place that decides whether a submit may proceed.
+    // No token (or no email anywhere) -> refuse BEFORE any request; a guard-less submit
+    // would otherwise call the API with an empty token.
+    const target = resetSubmitTarget(passwordResetToken?.token, recoverySession?.email, email);
+    if (!target) {
+      setError(passwordResetToken ? 'We could not tell which account to reset. Start recovery again.' : 'This reset link is missing its token. Start recovery again.');
+      return;
+    }
 
     setLoading(true);
     setError(null);
@@ -121,8 +135,8 @@ function RecoveryContent() {
 
     try {
       const response = await accountApi.resetPasswordWithToken(
-        recoverySession.email,
-        passwordResetToken.token,
+        target.email,
+        target.token,
         password,
         confirmPassword
       );
@@ -144,7 +158,9 @@ function RecoveryContent() {
   const handleGoBack = () => {
     if (currentStep === 'select-method') setCurrentStep('initiate');
     else if (currentStep === 'verify-code') setCurrentStep('select-method');
-    else if (currentStep === 'set-password') setCurrentStep('verify-code');
+    // PAY-2121: a deep-linked set-password has no verify-code to go back to; return to
+    // the request-code step so a bad token still leaves a way forward.
+    else if (currentStep === 'set-password') setCurrentStep(recoverySession ? 'verify-code' : 'initiate');
   };
 
   return (

package/src/routes/onboarding/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Ready-to-use onboarding route handlers (PAY-2121).
+ *
+ * Import directly into your app's API routes with zero configuration:
+ *
+ * @example
+ * ```typescript
+ * // app/api/onboarding/verify-code/route.ts
+ * export { POST } from '@payez/next-mvp/routes/onboarding/verify-code';
+ * ```
+ */
+export { POST as verifyCodePOST } from '../../api-handlers/onboarding/verify-code';
+export { POST as sendEmailCodePOST } from '../../api-handlers/onboarding/send-email-code';
+export { POST as verifyWelcomeEmailPOST } from '../../api-handlers/onboarding/verify-welcome-email';
+export { POST as setPasswordPOST } from '../../api-handlers/onboarding/set-password';

package/src/routes/onboarding/send-email-code.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/send-email-code -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/send-email-code';

package/src/routes/onboarding/set-password.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/set-password -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/set-password';

package/src/routes/onboarding/verify-code.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/verify-code -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/verify-code';

package/src/routes/onboarding/verify-welcome-email.ts

@@ -0,0 +1,2 @@
+/** POST /api/onboarding/verify-welcome-email -> IdP (PAY-2121). */
+export { POST } from '../../api-handlers/onboarding/verify-welcome-email';

package/src/server/auth.ts

@@ -10,8 +10,10 @@ import { getBetterAuthInstance } from '../auth/better-auth';
 import {
   getSession as getRedisSession,
   getBetterAuthSession as getBetterAuthRedisSession,
+  describeSessionKeyPresence,
   type SessionData,
 } from '../lib/session-store';
+import { tokenLogId } from '../lib/token-log-id';
 import { resolveVerifiedSessionTokenFromRequest } from './verified-session-token';
 
 export type IdpTokenResult =
@@ -125,6 +127,82 @@ export async function getAuthInstance() {
 }
 
 
+/* ----------------------------------------------------------------------------------------------------------------
+ * PAY-2136 DIAGNOSTICS (BAPert 70873, Nextpert-Scout 70872/70875) - LOG ONLY, NO BEHAVIOUR CHANGE.
+ *
+ * A getFreshIdpToken NO_SESSION used to carry no origin: three different returns produced the same
+ * `{error:'NO_SESSION'}`, and getSession() swallowed every Redis error into a bare `catch {}`. These helpers name
+ * the origin and make a swallowed read audible. Hard rules: every helper is wrapped so it can NEVER throw or change
+ * a return value; nothing here ever logs a token, a cookie VALUE or a Redis value - only a tokenLogId() fingerprint,
+ * cookie NAMES, booleans, and an error name/message with any long opaque run redacted.
+ * -------------------------------------------------------------------------------------------------------------- */
+
+/** An error name/message, first 80 chars, with any 24+ char opaque run (a token, a key) replaced. */
+function scrubForLog(v: unknown): string {
+  const raw = v instanceof Error ? v.message : String(v ?? '');
+  return raw.replace(/[A-Za-z0-9_\-.+/=]{24,}/g, '[redacted]').slice(0, 80);
+}
+
+/** `catch {}` sites on the session read path: still swallowed, now audible. */
+function logSessionReadSwallowed(path: 'primary' | 'A' | 'B', err: unknown): void {
+  try {
+    const name = scrubForLog(err instanceof Error ? err.name : typeof err);
+    console.warn(`[server-auth] SESSION_READ_SWALLOWED path=${path} err=${name} msg=${scrubForLog(err)}`);
+  } catch {
+    /* a diagnostic must never change the outcome */
+  }
+}
+
+/** Origin a: getSession(request) produced no token. Cookie NAMES only, never a value. */
+function logNoSessionOriginA(request: Request | undefined): void {
+  try {
+    const header = request?.headers?.get('cookie') ?? '';
+    // Only segments of the form name=value contribute a NAME. A segment with no '=' is not a cookie pair, and
+    // logging it whole could emit a bare token (Nextpert-Scout 70901 finding 1).
+    const cookieNames = header
+      .split(';')
+      // Structural, alphabet-independent (Nextpert-Scout 70945): base64 padding can only sit at the END of a bare
+      // value, so a bare padded token splits as name=<token>, value='' or '='. A real pair has a non-empty value that
+      // is not only '=' characters. (The old includes('=') let 74% of base64url tokens through as a "name".)
+      .filter((c) => {
+        const i = c.indexOf('=');
+        if (i < 0) return false;
+        const v = c.slice(i + 1);
+        return v !== '' && !/^=+$/.test(v);
+      })
+      .map((c) => c.split('=')[0].trim())
+      .filter((n) => n !== '')
+      // A bare token that merely ENDS in base64 padding ('=') still passes the filter above and its "name" would be
+      // the token itself (Nextpert-Scout 70913). Real cookie names carry a separator ('.', '-', '_'); a long name with
+      // none is opaque, so it is logged as a placeholder, never as itself.
+      .map((n) => (n.length >= 24 && !/[._-]/.test(n) ? '[opaque-name]' : n))
+      .slice(0, 20);
+    console.warn('[server-auth] NO_SESSION origin=a', { hasCookieHeader: header !== '', cookieNames });
+  } catch {
+    /* a diagnostic must never change the outcome */
+  }
+}
+
+/** Origins b and c: a token WAS resolved. Log which of its three keys exist (presence only), fire-and-forget. */
+function logNoSessionWithKeys(origin: 'b' | 'c', sessionToken: string): void {
+  try {
+    void describeSessionKeyPresence(sessionToken).then(
+      (keys) => {
+        try {
+          console.warn(`[server-auth] NO_SESSION origin=${origin}`, { token: tokenLogId(sessionToken), ...keys });
+        } catch {
+          /* never throws */
+        }
+      },
+      () => {
+        /* never throws */
+      }
+    );
+  } catch {
+    /* a diagnostic must never change the outcome */
+  }
+}
+
 /**
  * Get the current session from a request.
  *
@@ -153,7 +231,9 @@ export async function getSession(request?: Request): Promise<any> {
   let betterAuthSession: any = null;
   try {
     betterAuthSession = await auth.api.getSession({ headers: request.headers });
-  } catch { /* fall through to canonical Redis path */ }
+  } catch (err) {
+    logSessionReadSwallowed('primary', err); // fall through to canonical Redis path
+  }
 
   if (betterAuthSession?.session?.token && betterAuthSession?.user) {
     const sessionToken = betterAuthSession.session.token as string;
@@ -161,7 +241,9 @@ export async function getSession(request?: Request): Promise<any> {
     try {
       sessionData = await getRedisSession(sessionToken);
       if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
-    } catch { /* Redis unavailable */ }
+    } catch (err) {
+      logSessionReadSwallowed('A', err); // Redis unavailable
+    }
     if (!sessionData) sessionData = buildSessionDataFromAuthSession(betterAuthSession);
     return attachSessionData(betterAuthSession, sessionData, sessionToken);
   }
@@ -184,7 +266,9 @@ export async function getSession(request?: Request): Promise<any> {
   try {
     sessionData = await getRedisSession(sessionToken);
     if (!sessionData) sessionData = await getBetterAuthRedisSession(sessionToken);
-  } catch { /* Redis unavailable */ }
+  } catch (err) {
+    logSessionReadSwallowed('B', err); // Redis unavailable
+  }
   if (!sessionData) return null;
 
   // Synthesize a minimal session shape compatible with downstream callers.
@@ -296,6 +380,7 @@ export async function getFreshIdpToken(
   const session = await getSession(request);
   const sessionToken = session?.session?.token as string | undefined;
   if (!sessionToken) {
+    logNoSessionOriginA(request);
     return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
   }
 
@@ -314,6 +399,7 @@ export async function getFreshIdpToken(
   );
 
   if (!result.ok) {
+    if (result.code === 'NO_SESSION') logNoSessionWithKeys('b', sessionToken);
     return {
       success: false,
       error: result.code,
@@ -327,6 +413,7 @@ export async function getFreshIdpToken(
 
   const sessionData = await getRedisSession(sessionToken);
   if (!sessionData) {
+    logNoSessionWithKeys('c', sessionToken);
     return { success: false, error: 'NO_SESSION', status: 401, terminal: true };
   }