@payez/next-mvp 4.4.4 → 4.4.6

package/scripts/verify-release-provenance.mjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+/**
+ * RELEASE PROVENANCE VERIFIER — 340024 / BAPert R1037 s2.
+ *
+ * WHY THIS EXISTS. Published 4.4.5 ships source that EXISTS IN NO COMMIT. Measured
+ * three ways; the decisive instrument was `git cat-file -e`, which resolves loose AND
+ * packed objects regardless of reachability — and 4.4.5's `src/auth/better-auth.ts`
+ * blob DOES NOT EXIST in the object store. Not a dangling object a reflog walk could
+ * recover: the bytes were never committed. The only shape consistent with that is a
+ * PUBLISH FROM A WORKING TREE WITH UNCOMMITTED EDITS.
+ *
+ * You cannot fix that after the fact — the source is gone. So R1037 s2 replaced the
+ * unanswerable question ("where did 4.4.5 come from?") with a pass/fail check on the
+ * artefact you are ABOUT to ship, which is this script:
+ *
+ *     Every shipped file that is supposed to come from the repo must hash-match the
+ *     blob recorded at the release commit FOR THAT PATH. Anything else = do not ship.
+ *
+ * ---------------------------------------------------------------------------------
+ * DESIGN NOTES (deliberate; do not "helpfully" soften these)
+ *
+ * 1. IT IS PATH-ANCHORED, NOT EXISTENCE-BASED. The gate was specified as "confirm the
+ *    blob hash RESOLVES IN THE STORE". That is too weak for a pre-ship gate: a file
+ *    from a DIFFERENT commit resolves perfectly and is still the wrong bytes. We
+ *    compare against `<commit>:<path>` — the blob recorded at that path at that
+ *    commit. Store existence is still computed, but only as a DIAGNOSIS on failures,
+ *    because it separates two faults with different remediations:
+ *
+ *        mismatch + hash EXISTS in store  -> packed from the WRONG REVISION (re-checkout)
+ *        mismatch + hash ABSENT from store -> UNCOMMITTED EDITS  (this is the 4.4.5 disease)
+ *
+ * 2. IT CLASSIFIES, BECAUSE THE TARBALL IS NOT ALL SOURCE. Measured on real 4.4.5:
+ *    744 entries = 488 dist/ + 246 src/ + 7 scripts/ + package.json + 2 docs. `dist/`
+ *    is GITIGNORED BUILD OUTPUT and can never hash-match a commit. A gate that failed
+ *    on every unmatched file would report 488 failures on a PERFECTLY CLEAN publish,
+ *    and a control that always fires is a control that gets switched off. So each
+ *    shipped path is assigned to a declared class and checked accordingly.
+ *
+ * 3. UNKNOWN PATHS FAIL. If someone adds an entry to package.json "files", it lands in
+ *    no class and this EXITS 1 rather than ignoring it. A verifier that silently skips
+ *    what it does not recognise cannot be trusted to have checked anything. Fail closed.
+ *
+ * 4. MISSING FILES FAIL TOO. A file committed under a verified prefix but ABSENT from
+ *    the tarball is a truncated publish — the same class of defect, opposite sign.
+ *    Checked in both directions.
+ *
+ * 5. LINE ENDINGS ARE NORMALISED CRLF->LF BEFORE HASHING, and this is load-bearing:
+ *    tarballs packed on Windows ship CRLF (measured: 1416 CRLF in the 4.4.5 tarball)
+ *    while the repo blobs are LF (measured: 0). Comparing raw bytes reports every text
+ *    file as a mismatch. Binary files (NUL byte present) are NEVER normalised.
+ *
+ * 6. `dist/` IS NOT PROVENANCE-VERIFIED AND THIS SCRIPT SAYS SO OUT LOUD. It is
+ *    ENTAILED — built by prepack from sources this script proved clean — not verified.
+ *    Anyone who wants dist verified needs a reproducible-build comparison, which is a
+ *    different and more expensive control. Stating the limit is the point: a gate that
+ *    overstates its coverage is worse than one that admits a gap, because the gap then
+ *    goes unstaffed.
+ *
+ * 7. NO NETWORK, NO DEPENDENCIES. Reads a local .tgz and a local git object store.
+ *    Same reasoning as check-publish-health.mjs's refusal to enter prepack: a release
+ *    control that needs the network trades one outage for another.
+ *
+ * ---------------------------------------------------------------------------------
+ * Usage:
+ *   npm run check:provenance -- --tarball <file.tgz> --commit <sha>
+ *   node scripts/verify-release-provenance.mjs --tarball <file.tgz> --commit <sha>
+ *        [--repo <path>] [--pkg-dir packages/next-mvp] [--json] [--quiet]
+ *
+ *   Runs correctly from ANY cwd (repo root, package dir, or outside the repo):
+ *   --repo/--pkg-dir default to this script's own location, not process.cwd().
+ *
+ * Exit: 0 = PASS       every verifiable shipped file matches the commit
+ *       1 = FAIL       mismatch / missing / unclassified  -> RE-RUN, DO NOT SHIP
+ *       2 = INCONCLUSIVE  could not read tarball or git    -> NOT a pass
+ */
+
+import { createHash } from 'node:crypto';
+import { gunzipSync } from 'node:zlib';
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const EXIT_INCONCLUSIVE = 2;
+
+/* ------------------------------------------------------------------ classification */
+
+/**
+ * Paths are relative to the tarball's "package/" root.
+ * Order matters: first match wins, so put specific paths before prefixes.
+ */
+const CLASSES = [
+  // Rewritten by npm at pack time (_id, dist, gitHead, field normalisation).
+  // Never byte-matches its committed blob. Checked semantically instead.
+  { cls: 'MANIFEST', test: (p) => p === 'package.json' },
+
+  // Gitignored build output. See design note 6.
+  { cls: 'DERIVED', test: (p) => p.startsWith('dist/') },
+
+  // Committed source — the class this gate exists to protect.
+  { cls: 'VERIFIED', test: (p) => p.startsWith('src/') },
+  { cls: 'VERIFIED', test: (p) => p.startsWith('scripts/') },
+  { cls: 'VERIFIED', test: (p) => p === 'POST-INSTALL.md' },
+  // npm always ships README regardless of "files"; it is committed, so verify it.
+  { cls: 'VERIFIED', test: (p) => p === 'README.md' },
+  { cls: 'VERIFIED', test: (p) => p === 'LICENSE' || p === 'LICENCE' },
+];
+
+function classify(path) {
+  for (const c of CLASSES) if (c.test(path)) return c.cls;
+  return 'UNCLASSIFIED'; // design note 3 — fail closed
+}
+
+/* ------------------------------------------------------------------------ tar read */
+
+/**
+ * Minimal USTAR/GNU reader. We parse rather than shell out to `tar` so the check
+ * never writes a temp tree it might then read back differently (and so it behaves
+ * identically on the Windows seat and the Linux agent).
+ */
+function readTar(buf) {
+  const entries = new Map();
+  let off = 0;
+  let longName = null;
+
+  const str = (b, s, n) => {
+    const slice = b.subarray(s, s + n);
+    const z = slice.indexOf(0);
+    return slice.subarray(0, z === -1 ? slice.length : z).toString('utf8');
+  };
+
+  while (off + 512 <= buf.length) {
+    const hdr = buf.subarray(off, off + 512);
+    if (hdr.every((b) => b === 0)) break; // end-of-archive
+
+    const name = str(hdr, 0, 100);
+    const sizeField = str(hdr, 124, 12).trim();
+    const size = parseInt(sizeField, 8) || 0;
+    const type = String.fromCharCode(hdr[156]);
+    const prefix = str(hdr, 345, 155);
+
+    off += 512;
+    const data = buf.subarray(off, off + size);
+    off += Math.ceil(size / 512) * 512;
+
+    if (type === 'L') {
+      // GNU long name: applies to the NEXT header.
+      longName = data.toString('utf8').replace(/\0+$/, '');
+      continue;
+    }
+
+    let full = longName ?? (prefix ? `${prefix}/${name}` : name);
+    longName = null;
+
+    if (type === '0' || type === '\0' || type === '') {
+      entries.set(full.replace(/\\/g, '/'), Buffer.from(data));
+    }
+    // directories (5), links, pax headers: not content, ignored deliberately
+  }
+  return entries;
+}
+
+/* ------------------------------------------------------------------------- hashing */
+
+const isBinary = (buf) => buf.includes(0);
+
+/** CRLF -> LF, text only. See design note 5. */
+function normalise(buf) {
+  if (isBinary(buf)) return buf;
+  return Buffer.from(buf.toString('binary').replace(/\r\n/g, '\n'), 'binary');
+}
+
+/** git blob id = sha1("blob <bytelen>\0" + content) */
+function gitBlobId(buf) {
+  return createHash('sha1')
+    .update(`blob ${buf.length}\0`, 'binary')
+    .update(buf)
+    .digest('hex');
+}
+
+/* ----------------------------------------------------------------------------- git */
+
+function git(repo, args) {
+  return execFileSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/** path (relative to pkgDir) -> blob sha, for one commit. ONE git call. */
+function treeAtCommit(repo, commit, pkgDir) {
+  const out = git(repo, ['ls-tree', '-r', commit, '--', pkgDir]);
+  const map = new Map();
+  for (const line of out.split('\n')) {
+    if (!line.trim()) continue;
+    const m = line.match(/^(\d+) (\w+) ([0-9a-f]+)\t(.*)$/);
+    if (!m) continue;
+    const [, , objType, sha, fullPath] = m;
+    if (objType !== 'blob') continue;
+    const rel = fullPath.startsWith(pkgDir + '/') ? fullPath.slice(pkgDir.length + 1) : null;
+    if (rel) map.set(rel, sha);
+  }
+  return map;
+}
+
+function existsInStore(repo, sha) {
+  try {
+    git(repo, ['cat-file', '-e', `${sha}^{object}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/* ---------------------------------------------------------------------------- main */
+
+/**
+ * Defaults must NOT come from process.cwd().
+ *
+ * MEASURED 2026-09-14: with repo defaulting to cwd, running this from the package
+ * directory -- which is exactly what an `npm run` script does -- makes git resolve
+ * `ls-tree -- packages/next-mvp` against packages/next-mvp itself, matching nothing.
+ * Result: "INCONCLUSIVE: no blobs under packages/next-mvp", exit 2, on a tarball that
+ * is in fact clean. A gate whose most natural invoker always answers INCONCLUSIVE is
+ * a gate that gets switched off.
+ *
+ * So anchor both defaults to THIS FILE's location: the repo is whatever toplevel the
+ * script lives in, and the package prefix is the script's parent relative to that
+ * toplevel. Correct from any cwd, and still correct if the package is ever moved.
+ * Both remain overridable by --repo / --pkg-dir.
+ */
+function locateSelf() {
+  const fallback = { repo: process.cwd(), pkgDir: 'packages/next-mvp' };
+  try {
+    const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+    const pkgRoot = path.resolve(scriptDir, '..');
+    const toplevel = execFileSync('git', ['-C', pkgRoot, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+    if (!toplevel) return fallback;
+    const rel = path.relative(toplevel, pkgRoot).split(path.sep).join('/');
+    // rel === '' would mean the package IS the repo root; keep the explicit default.
+    return { repo: toplevel, pkgDir: rel || fallback.pkgDir };
+  } catch {
+    return fallback;
+  }
+}
+
+function parseArgs(argv) {
+  const self = locateSelf();
+  const a = { repo: self.repo, pkgDir: self.pkgDir, json: false, quiet: false };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--tarball') a.tarball = argv[++i];
+    else if (k === '--commit') a.commit = argv[++i];
+    else if (k === '--repo') a.repo = argv[++i];
+    else if (k === '--pkg-dir') a.pkgDir = argv[++i];
+    else if (k === '--json') a.json = true;
+    else if (k === '--quiet') a.quiet = true;
+    else if (k === '--help' || k === '-h') a.help = true;
+    else throw new Error(`unknown argument: ${k}`);
+  }
+  return a;
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    console.error(`[provenance] ${e.message}`);
+    return EXIT_INCONCLUSIVE;
+  }
+
+  if (args.help || !args.tarball || !args.commit) {
+    console.error(
+      'usage: node scripts/verify-release-provenance.mjs --tarball <file.tgz> --commit <sha>\n' +
+        '                 [--repo <path>] [--pkg-dir packages/next-mvp] [--json] [--quiet]'
+    );
+    return EXIT_INCONCLUSIVE;
+  }
+
+  // --- read inputs. Any failure here is INCONCLUSIVE, never a pass.
+  let entries, committed, resolvedCommit;
+  try {
+    entries = readTar(gunzipSync(readFileSync(args.tarball)));
+  } catch (e) {
+    console.error(`[provenance] INCONCLUSIVE: cannot read tarball ${args.tarball}: ${e.message}`);
+    return EXIT_INCONCLUSIVE;
+  }
+  try {
+    resolvedCommit = git(args.repo, ['rev-parse', `${args.commit}^{commit}`]).trim();
+    committed = treeAtCommit(args.repo, resolvedCommit, args.pkgDir);
+  } catch (e) {
+    console.error(`[provenance] INCONCLUSIVE: cannot read git at ${args.repo}: ${e.message}`);
+    return EXIT_INCONCLUSIVE;
+  }
+  if (entries.size === 0) {
+    console.error('[provenance] INCONCLUSIVE: tarball contained zero file entries');
+    return EXIT_INCONCLUSIVE;
+  }
+  if (committed.size === 0) {
+    console.error(`[provenance] INCONCLUSIVE: no blobs under ${args.pkgDir} at ${args.commit}`);
+    return EXIT_INCONCLUSIVE;
+  }
+
+  // --- classify + check
+  const res = { matched: [], mismatched: [], unclassified: [], derived: [], manifest: [], missing: [] };
+  let normalisedCount = 0;
+
+  for (const [tarPath, raw] of entries) {
+    if (!tarPath.startsWith('package/')) {
+      res.unclassified.push({ path: tarPath, why: 'outside package/ root' });
+      continue;
+    }
+    const p = tarPath.slice('package/'.length);
+    const cls = classify(p);
+
+    if (cls === 'DERIVED') { res.derived.push(p); continue; }
+    if (cls === 'MANIFEST') { res.manifest.push(p); continue; }
+    if (cls === 'UNCLASSIFIED') {
+      res.unclassified.push({ path: p, why: 'shipped but in no declared class' });
+      continue;
+    }
+
+    const norm = normalise(raw);
+    if (norm.length !== raw.length) normalisedCount++;
+    const actual = gitBlobId(norm);
+    const expected = committed.get(p);
+
+    if (!expected) {
+      res.mismatched.push({ path: p, actual, expected: null, diagnosis: 'SHIPPED BUT NOT COMMITTED AT THIS COMMIT' });
+    } else if (actual === expected) {
+      res.matched.push(p);
+    } else {
+      res.mismatched.push({
+        path: p,
+        actual,
+        expected,
+        diagnosis: existsInStore(args.repo, actual)
+          ? 'WRONG REVISION (bytes exist in store, but not at this path/commit)'
+          : 'DIRTY TREE (bytes exist in NO commit — uncommitted edit)',
+      });
+    }
+  }
+
+  // --- reverse direction: committed under a verified prefix but not shipped
+  for (const [p] of committed) {
+    if (classify(p) !== 'VERIFIED') continue;
+    if (!entries.has(`package/${p}`)) res.missing.push(p);
+  }
+
+  const verifiable = res.matched.length + res.mismatched.length;
+  const failed = res.mismatched.length + res.unclassified.length + res.missing.length;
+  const pass = failed === 0;
+
+  if (args.json) {
+    console.log(JSON.stringify({ pass, commit: resolvedCommit, tarball: args.tarball, ...res }, null, 2));
+    return pass ? EXIT_PASS : EXIT_FAIL;
+  }
+
+  const log = args.quiet ? () => {} : (...a) => console.log(...a);
+  log('');
+  log('  RELEASE PROVENANCE — tarball vs commit');
+  log(`  tarball : ${args.tarball}`);
+  log(`  commit  : ${resolvedCommit}`);
+  log(`  pkg dir : ${args.pkgDir}`);
+  log('  ' + '-'.repeat(70));
+  log(`  VERIFIED    ${String(res.matched.length).padStart(4)} / ${verifiable} shipped source files match the commit`);
+  log(`  DERIVED     ${String(res.derived.length).padStart(4)}   dist/ build output — NOT provenance-verified (see note 6)`);
+  log(`  MANIFEST    ${String(res.manifest.length).padStart(4)}   package.json — rewritten by npm, not byte-comparable`);
+  log(`  normalised  ${String(normalisedCount).padStart(4)}   text files had CRLF stripped before hashing`);
+
+  if (res.mismatched.length) {
+    log('');
+    log(`  *** ${res.mismatched.length} FILE(S) DO NOT MATCH THE COMMIT ***`);
+    for (const m of res.mismatched.slice(0, 40)) {
+      log(`    ${m.path}`);
+      log(`      shipped  ${m.actual}`);
+      log(`      commit   ${m.expected ?? '(no blob at this path)'}`);
+      log(`      -> ${m.diagnosis}`);
+    }
+    if (res.mismatched.length > 40) log(`    ... and ${res.mismatched.length - 40} more`);
+  }
+  if (res.missing.length) {
+    log('');
+    log(`  *** ${res.missing.length} COMMITTED FILE(S) MISSING FROM TARBALL (truncated publish) ***`);
+    for (const p of res.missing.slice(0, 20)) log(`    ${p}`);
+    if (res.missing.length > 20) log(`    ... and ${res.missing.length - 20} more`);
+  }
+  if (res.unclassified.length) {
+    log('');
+    log(`  *** ${res.unclassified.length} SHIPPED FILE(S) IN NO DECLARED CLASS ***`);
+    log('      (fail closed — add them to CLASSES or remove them from "files")');
+    for (const u of res.unclassified.slice(0, 20)) log(`    ${u.path}  — ${u.why}`);
+    if (res.unclassified.length > 20) log(`    ... and ${res.unclassified.length - 20} more`);
+  }
+
+  log('');
+  log(pass ? '  PASS — every verifiable shipped file traces to this commit.'
+           : '  FAIL — RE-RUN THE PUBLISH FROM A CLEAN CHECKOUT. DO NOT SHIP.');
+  log('');
+  return pass ? EXIT_PASS : EXIT_FAIL;
+}
+
+process.exit(main());

package/src/api/auth-handler.ts

@@ -24,6 +24,7 @@ import {
   checkRefreshLock,
   type SessionData
 } from '../lib/session-store';
+import { tokenLogId } from '../lib/token-log-id';
 
 
 export interface AuthContext {
@@ -268,7 +269,7 @@ export function createAuthHandler(options: AuthHandlerOptions = {}) {
       }
 
       console.info('[AUTH_HANDLER] Executing refresh against IDP', {
-        sessionToken: sessionToken.substring(0, 8) + '...',
+        sessionToken: tokenLogId(sessionToken),
         hasRefreshToken: true
       });
 
@@ -283,7 +284,8 @@ export function createAuthHandler(options: AuthHandlerOptions = {}) {
 
       if (!response.ok) {
         const errorText = await response.text().catch(() => 'Unknown error');
-        console.error('[AUTH_HANDLER] Refresh failed:', response.status, errorText);
+        // PAY-1427: never the raw upstream body (the refresh.ts:528 twin PR 139 fixed). Status + length only.
+        console.error('[AUTH_HANDLER] Refresh failed:', { status: response.status, bodyLength: errorText.length });
         return { success: false, error: `Refresh failed: ${response.status}` };
       }
 
@@ -441,7 +443,7 @@ export function createAuthHandler(options: AuthHandlerOptions = {}) {
           const requestId = generateRequestId();
           console.info('[AUTH_HANDLER] Token near expiry, initiating coordinated refresh', {
             requestId,
-            sessionToken: authContext.sessionToken.substring(0, 8) + '...'
+            sessionToken: tokenLogId(authContext.sessionToken)
           });
 
           const refreshResult = await performCoordinatedRefresh(

package/src/api-handlers/account/change-password.ts

@@ -9,6 +9,7 @@ interface ChangePasswordRequest {
 }
 
 import { nanoid } from 'nanoid';
+import { projectPasswordPolicyDetails } from '../../lib/safe-error-response';
 
 // ...
 
@@ -115,7 +116,8 @@ export async function POST(req: NextRequest) {
           message: errorMessage,
           error_code: responseData.error_code || 'CHANGE_PASSWORD_FAILED',
           request_id: requestId,
-          details: responseData.details,
+          // PAY-1438: only the password-policy messages the security pages display, never the raw envelope.
+          details: projectPasswordPolicyDetails(responseData.details),
         },
         { status: idpResponse.status }
       );
@@ -127,12 +129,13 @@ export async function POST(req: NextRequest) {
       request_id: requestId,
     });
   } catch (error) {
-    console.error('[CHANGE_PASSWORD] Error:', error);
     const requestId = req.headers.get('x-request-id') ?? crypto.randomUUID();
+    // PAY-1438: the exception text stays in the log, keyed by the request_id the caller receives.
+    console.error('[CHANGE_PASSWORD] Error:', { request_id: requestId, error });
     return NextResponse.json(
       {
         success: false,
-        message: error instanceof Error ? error.message : 'Failed to change password',
+        message: 'Failed to change password',
         error_code: 'INTERNAL_ERROR',
         request_id: requestId,
       },

package/src/api-handlers/account/masked-info.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { idpFetchJSON } from '../../lib/idp-fetch';
 import { ENV_CONFIG } from '../../config/env';
+import { projectIdpError } from '../../lib/safe-error-response';
 
 // IDP masked-info is POST and uses capital 'A' in /api/Account
 export async function POST(req: NextRequest) {
@@ -24,7 +25,7 @@ export async function POST(req: NextRequest) {
       {
         success: false,
         message: 'Upstream error',
-        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: result.json },
+        error: { code: 'UPSTREAM_SERVICE_ERROR', status: result.status, details: projectIdpError(result.json) },
         meta: { attemptedRefresh: result.attemptedRefresh },
       },
       { status: result.status }

package/src/api-handlers/account/recovery/forward.ts

@@ -0,0 +1,117 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { ENV_CONFIG } from '../../../config/env';
+import { getIDPClientConfig } from '../../../lib/idp-client-config';
+import { resolveClientKey } from '../../../lib/client-key';
+import { idpErrorEnvelope } from '../../../lib/safe-error-response';
+
+/**
+ * Account recovery - the ONE forwarder behind /recovery/send-code and /recovery/verify-code (PAY-1588).
+ *
+ * THE DEFECT (QAPert, W1 walk on :4797 -> dev-93 IdP 90f766bd0, 2026-09-19): portal /account-auth/recovery,
+ * initiate -> 200, send-code -> 401 "Upstream error". The browser sends `Authorization: Bearer <recovery session
+ * token>` (the token `initiate` minted); these handlers went through idpFetchJSON, which sets Authorization ONLY from
+ * the server-side SESSION and never forwards the inbound header, so the IdP got no Bearer at all
+ * (AccountController.cs:872-885 = 401 MISSING_TOKEN). Positive control direct to the IdP: without Authorization 401,
+ * with it 200 and the email is sent.
+ *
+ * WHY THE 2026-08-02 REWRITE GOT IT WRONG. It reasoned "browsers send a session COOKIE and no Authorization header"
+ * and moved both handlers onto idpFetchJSON. That is true of every OTHER authenticated route. It is false of this
+ * flow: the caller is LOCKED OUT, so there is no session to resolve - the recovery session token IS the credential,
+ * and the browser is the only party that holds it. Resolving a token from a session that does not exist is why the
+ * entire recovery path, both halves, has been dead: it fails exactly when it is the only thing left that could help.
+ *
+ * WHAT THIS DOES INSTEAD
+ *   - Forwards the inbound `Authorization: Bearer <token>` to the IdP and nothing else from the caller's headers.
+ *   - Uses a direct fetch, NOT idpFetchJSON: a stray session belonging to someone else on the same browser must not
+ *     be able to override the recovery credential with its own bearer (idpFetchJSON's session bearer wins over any
+ *     caller-supplied Authorization).
+ *   - FAILS LOUD when there is no usable bearer: 401 `missing_recovery_token`, without calling upstream. The old
+ *     behaviour returned the IdP's opaque rejection, so the user saw recovery "not working" and the log showed an
+ *     upstream error rather than the auth fault it was.
+ *   - Shape-checks the token (a bearer scheme, one opaque token, sane length) before forwarding, so the header cannot
+ *     be used to smuggle anything but a credential to the IdP. It is never logged.
+ *   - Anonymous route (PAY-1438): on failure only the whitelisted envelope, never the IdP body.
+ *
+ * SERVER VALUE WINS for client_id (cards 268012 / 268410): applied AFTER the caller's payload spread, because these are
+ * unauthenticated endpoints and a browser-supplied client_id would be a tenant-targeting lever on a password-reset path.
+ *
+ * @package @payez/next-mvp
+ */
+
+/** One opaque token: JWT / base64url / opaque-hex alphabet, no whitespace or control characters, bounded length. */
+const TOKEN_SHAPE = /^[A-Za-z0-9\-._~+/]+=*$/;
+
+/** The recovery bearer from the inbound request, or null when absent / malformed. Never throws. */
+export function inboundRecoveryBearer(req: Pick<NextRequest, 'headers'>): string | null {
+  const raw = req.headers.get('authorization');
+  if (!raw) return null;
+  const m = /^Bearer[ ]+(\S+)$/i.exec(raw.trim());
+  if (!m) return null;
+  const token = m[1];
+  if (token.length < 16 || token.length > 4096) return null;
+  return TOKEN_SHAPE.test(token) ? token : null;
+}
+
+async function recoveryClientKey(where: string): Promise<string | null> {
+  try {
+    const config = await getIDPClientConfig();
+    return resolveClientKey(config, where).key;
+  } catch (e) {
+    console.error(`[${where}] could not resolve IDP client config for client_id:`, e);
+    return null;
+  }
+}
+
+export interface RecoveryForward {
+  /** IdP path after the host, e.g. /api/Account/recovery/send-code */
+  upstreamPath: string;
+  /** log/route label used for the client-key resolver */
+  where: string;
+  /** stable `error` code for an upstream that could not be reached */
+  failureCode: string;
+  /** user-facing fallback when the IdP gave no message */
+  fallbackMessage: string;
+}
+
+export async function forwardRecoveryCall(req: NextRequest, spec: RecoveryForward): Promise<NextResponse> {
+  let payload: unknown = {};
+  try {
+    payload = await req.json();
+  } catch {
+    return NextResponse.json({ success: false, error: 'invalid_request', message: 'A JSON body is required' }, { status: 400 });
+  }
+
+  const bearer = inboundRecoveryBearer(req);
+  if (!bearer) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: 'missing_recovery_token',
+        message: 'Your recovery session could not be found. Start the recovery again from the beginning.',
+      },
+      { status: 401 },
+    );
+  }
+
+  const clientKey = await recoveryClientKey(spec.where);
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(`${ENV_CONFIG.IDP_URL}${spec.upstreamPath}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        Authorization: `Bearer ${bearer}`,
+        ...(clientKey ? { 'X-Client-Id': clientKey } : {}),
+      },
+      body: JSON.stringify({ ...(payload as Record<string, unknown>), ...(clientKey ? { client_id: clientKey } : {}) }),
+    });
+  } catch {
+    return NextResponse.json({ success: false, error: spec.failureCode }, { status: 502 });
+  }
+
+  const data = await upstream.json().catch(() => ({}));
+  if (!upstream.ok) return NextResponse.json(idpErrorEnvelope(data, spec.fallbackMessage), { status: upstream.status });
+  return NextResponse.json(data, { status: 200 });
+}

package/src/api-handlers/account/recovery/initiate.ts

@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getIDPClientConfig } from '../../../lib/idp-client-config';
 import { resolveClientKey } from '../../../lib/client-key';
+import { idpErrorEnvelope } from '../../../lib/safe-error-response';
 
 function getIdpUrl(): string {
   const url = process.env.IDP_URL;
@@ -49,6 +50,8 @@ export async function POST(req: NextRequest) {
       body: JSON.stringify({ email, ...(clientKey ? { client_id: clientKey } : {}) }),
     });
     const data = await upstream.json().catch(() => ({}));
+    // PAY-1438: anonymous route - on failure only the whitelisted envelope, never the IDP body.
+    if (!upstream.ok) return NextResponse.json(idpErrorEnvelope(data, 'Failed to initiate recovery'), { status: upstream.status });
     return NextResponse.json(data, { status: upstream.status });
   } catch (e) {
     return NextResponse.json({ success: false, error: 'initiate_failed' }, { status: 500 });