@payez/next-mvp 4.4.2 → 4.4.3

package/dist/api/auth-handler.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAuthHandler = createAuthHandler;
 const server_1 = require("next/server");
 const auth_1 = require("../server/auth");
+const acr_1 = require("../lib/acr");
 const nanoid_1 = require("nanoid");
 const session_store_1 = require("../lib/session-store");
 /**
@@ -158,10 +159,18 @@ function createAuthHandler(options = {}) {
                 console.error('[AUTH_HANDLER] No refresh token available');
                 return { success: false, error: 'No refresh token' };
             }
-            // Extract authentication methods from session
-            const authMethods = currentSession.authMethods ||
-                (currentSession.token?.amr ? JSON.parse(currentSession.token.amr) : ['pwd', 'mfa']);
-            const authLevel = String(currentSession.authenticationLevel || currentSession.token?.acr || '2');
+            // Extract authentication methods from session.
+            //
+            // 375639: these two lines used to read
+            //     authMethods = ... : ['pwd', 'mfa']
+            //     authLevel   = String(... || ... || '2')
+            // so a session that knew NOTHING about how the user authenticated told
+            // the IDP that a second factor had happened AND named 'mfa' as the
+            // method. The two fabrications corroborated each other, so a downstream
+            // check cross-validating amr against acr would have accepted the pair.
+            // Absent is not satisfied; both now resolve fail-closed, in one place.
+            const authMethods = (0, acr_1.resolveAuthMethods)(currentSession.authMethods, currentSession.token?.amr);
+            const authLevel = (0, acr_1.resolveAcrLevel)(currentSession.authenticationLevel, currentSession.token?.acr);
             const twoFactorMethod = currentSession.twoFactorMethod || 'authenticator';
             // Build refresh request body
             const refreshRequestBody = {

package/dist/auth/safe-callback.d.ts

@@ -21,6 +21,27 @@
  *   v1  `startsWith('/') && !startsWith('//')`            -> bypassed by  /BACKSLASH host
  *   v2  + `!startsWith('/' + BACKSLASH)`                  -> bypassed by  /TAB/host
  *   ...                                                      and /LF/host, /CR/host
+ *   v3  resolve once + compare ORIGIN                     -> bypassed by  /..//host
+ *                                                            and /.//host, /%2e%2e//host
+ *   v4  + require the RESULT to be a FIXED POINT          <- current
+ *
+ * *** DRIFT, 2026-09-11 (325543). THIS FILE WAS v3 WHILE THE PORTAL'S COPY WAS
+ * *** v4, AND THE PACKAGE COPY IS THE ONE THAT SHIPPED. The portal fixed its own
+ * *** src/lib/safe-callback.ts (e1f08fea) and deployed; the served bundle STILL
+ * *** escaped 5/5 in a real browser, because `src/contexts/ThemeContext.tsx`
+ * *** imports the BARE BARREL `@payez/next-mvp`, which pulls dist/index.js ->
+ * *** auth/auth-decision -> THIS FILE into the client graph, and because the
+ * *** portal's `src/middleware.ts` imports `@payez/next-mvp/edge`, which requires
+ * *** THIS FILE server-side on every request. It was read as a stale build
+ * *** artifact of the portal's file for most of a day. It was not. It was a
+ * *** SECOND DEFINITION, and no rebuild of the portal could have removed it.
+ * *** The header below says "ONE definition ... for the whole package" and that
+ * *** was true INSIDE this package boundary the entire time. The defect lived in
+ * *** the gap BETWEEN two boundaries that each enforced one-definition correctly.
+ * *** A guard that exists in N copies is only as strong as its weakest copy, and
+ * *** a per-repo grep gate cannot see N. IF YOU CHANGE THE PREDICATE HERE, CHANGE
+ * *** IT IN THE PORTAL'S src/lib/safe-callback.ts IN THE SAME HOUR, OR DELETE ONE
+ * *** OF THEM.
  *
  * Both bypasses work the same way: the browser NORMALISES the string AFTER the
  * guard has finished looking at it. The WHATWG URL parser converts backslashes
@@ -45,7 +66,15 @@ export declare const DEFAULT_CALLBACK = "/";
  * the auth surface. Never throws.
  */
 export declare function safeCallbackPath(raw: unknown, fallback?: string): string;
-/** True when `raw` is a callback target we are willing to honour. */
+/**
+ * True when `raw` is a callback target we are willing to honour.
+ *
+ * DEFINED IN TERMS OF `safeCallbackPath` ON PURPOSE - it used to carry its own
+ * copy of the predicate, and that copy was missing the second resolution above
+ * while the two were maintained separately. This file's whole history is
+ * duplicated predicates drifting apart (see the header). One definition, one
+ * place to fix.
+ */
 export declare function isSafeCallbackPath(raw: unknown): raw is string;
 /**
  * Pick the post-login destination: an explicit `?callbackUrl=` when it is one we

package/dist/auth/safe-callback.js

@@ -22,6 +22,27 @@
  *   v1  `startsWith('/') && !startsWith('//')`            -> bypassed by  /BACKSLASH host
  *   v2  + `!startsWith('/' + BACKSLASH)`                  -> bypassed by  /TAB/host
  *   ...                                                      and /LF/host, /CR/host
+ *   v3  resolve once + compare ORIGIN                     -> bypassed by  /..//host
+ *                                                            and /.//host, /%2e%2e//host
+ *   v4  + require the RESULT to be a FIXED POINT          <- current
+ *
+ * *** DRIFT, 2026-09-11 (325543). THIS FILE WAS v3 WHILE THE PORTAL'S COPY WAS
+ * *** v4, AND THE PACKAGE COPY IS THE ONE THAT SHIPPED. The portal fixed its own
+ * *** src/lib/safe-callback.ts (e1f08fea) and deployed; the served bundle STILL
+ * *** escaped 5/5 in a real browser, because `src/contexts/ThemeContext.tsx`
+ * *** imports the BARE BARREL `@payez/next-mvp`, which pulls dist/index.js ->
+ * *** auth/auth-decision -> THIS FILE into the client graph, and because the
+ * *** portal's `src/middleware.ts` imports `@payez/next-mvp/edge`, which requires
+ * *** THIS FILE server-side on every request. It was read as a stale build
+ * *** artifact of the portal's file for most of a day. It was not. It was a
+ * *** SECOND DEFINITION, and no rebuild of the portal could have removed it.
+ * *** The header below says "ONE definition ... for the whole package" and that
+ * *** was true INSIDE this package boundary the entire time. The defect lived in
+ * *** the gap BETWEEN two boundaries that each enforced one-definition correctly.
+ * *** A guard that exists in N copies is only as strong as its weakest copy, and
+ * *** a per-repo grep gate cannot see N. IF YOU CHANGE THE PREDICATE HERE, CHANGE
+ * *** IT IN THE PORTAL'S src/lib/safe-callback.ts IN THE SAME HOUR, OR DELETE ONE
+ * *** OF THEM.
  *
  * Both bypasses work the same way: the browser NORMALISES the string AFTER the
  * guard has finished looking at it. The WHATWG URL parser converts backslashes
@@ -77,19 +98,69 @@ function safeCallbackPath(raw, fallback = exports.DEFAULT_CALLBACK) {
     if (url.pathname.startsWith(AUTH_PREFIX))
         return fallback;
     // The parser's normalised output - control characters already stripped.
-    return url.pathname + url.search + url.hash;
-}
-/** True when `raw` is a callback target we are willing to honour. */
-function isSafeCallbackPath(raw) {
-    if (typeof raw !== 'string' || raw.length === 0)
-        return false;
+    const candidate = url.pathname + url.search + url.hash;
+    // *** SECOND RESOLUTION. DO NOT DELETE THIS AS REDUNDANT - IT IS NOT. ***
+    //
+    // v3 (the origin comparison above) was bypassed too, and differently from v1/v2.
+    // The origin check constrains where `raw` RESOLVED TO. It does not constrain how
+    // the RESULT IS SPELLED - and the result is resolved a SECOND time, by whoever
+    // navigates to it. A returned path that begins with `//` is a PROTOCOL-RELATIVE
+    // URL at that second resolution, so it lands off-origin having passed every
+    // check here:
+    //
+    //     '/..//evil.example.com'     -> pathname '//evil.example.com'  -> evil.example.com
+    //     '/.//evil.example.com'      -> pathname '//evil.example.com'  -> evil.example.com
+    //     '/%2e%2e//evil.example.com' -> pathname '//evil.example.com'  -> evil.example.com
+    //
+    // The parser resolves `..` against the synthetic base and, at the root, leaves
+    // behind the EMPTY SEGMENT rather than collapsing it. Origin stayed BASE the
+    // whole time, so nothing upstream fired.
+    //
+    // MEASURED, not reasoned: in a real headless Chromium on the live origin
+    // https://portal.keelauth.com, 5 spellings resolved to https://evil.example.com
+    // (QAPert-NightHawk, 2026-09-11, card 325543), and on 2026-09-11 the SERVED
+    // BUNDLE was measured escaping 5/5 through THIS PACKAGE'S copy while the
+    // portal's own src/lib/safe-callback.ts was already fixed - the two copies had
+    // drifted. See the DRIFT note in this file's header.
+    //
+    // THE FIX FOLLOWS THIS FILE'S OWN DOCTRINE: do not pattern-match the spellings
+    // (that is the startsWith() trap that failed four times, and this would be the
+    // fifth). Ask the parser AGAIN about the exact value we are about to hand out,
+    // and require it to be a FIXED POINT. Anything whose meaning changes when it is
+    // resolved a second time is by definition not a stable same-origin path, however
+    // it is spelled - including spellings nobody has found yet.
+    let echo;
     try {
-        const url = new URL(raw, BASE);
-        return url.origin === BASE && !url.pathname.startsWith(AUTH_PREFIX);
+        echo = new URL(candidate, BASE);
     }
     catch {
-        return false;
+        return fallback;
     }
+    if (echo.origin !== BASE)
+        return fallback;
+    if (echo.pathname.startsWith(AUTH_PREFIX))
+        return fallback;
+    if (echo.pathname + echo.search + echo.hash !== candidate)
+        return fallback;
+    return candidate;
+}
+/**
+ * Sentinel that `safeCallbackPath` can never legitimately return: it is not a
+ * fixed point of the URL parser (the parser would percent-encode the space), so
+ * it cannot collide with a genuine accepted value.
+ */
+const REJECTED = '\u0000rejected';
+/**
+ * True when `raw` is a callback target we are willing to honour.
+ *
+ * DEFINED IN TERMS OF `safeCallbackPath` ON PURPOSE - it used to carry its own
+ * copy of the predicate, and that copy was missing the second resolution above
+ * while the two were maintained separately. This file's whole history is
+ * duplicated predicates drifting apart (see the header). One definition, one
+ * place to fix.
+ */
+function isSafeCallbackPath(raw) {
+    return typeof raw === 'string' && raw.length > 0 && safeCallbackPath(raw, REJECTED) !== REJECTED;
 }
 /**
  * Pick the post-login destination: an explicit `?callbackUrl=` when it is one we

package/dist/lib/acr.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CARD 375639 - the one place this package decides what an ABSENT assurance
+ * signal means.
+ *
+ * Card 375276 fixed this question inside `payez_idp_admin_web/src` (commit
+ * d9c6ac0, BAPert R980 remedy (a)) and fenced its own scope explicitly:
+ *
+ *     "fallbacks on the stored `session.authenticationLevel` (refresh lane)
+ *      are deliberately NOT covered ... That gap is 375276's remaining half."
+ *
+ * `src/api/auth-handler.ts` IS that remaining half, and it is in the shared
+ * package rather than in one app, so every consumer of the published
+ * `@payez/next-mvp/api/auth-handler` export inherits it.
+ *
+ * WHY BOTH SIGNALS LIVE IN ONE MODULE
+ * -----------------------------------
+ * `acr` (how strong the authentication was) and `amr` (which methods were
+ * used) are sent to the IDP together in a single refresh body. Defaulting one
+ * without the other produces an INCOHERENT assertion - "no second factor
+ * happened, and the method used was mfa" - so they are resolved side by side
+ * and a change to one is forced to confront the other.
+ *
+ * MEASURED CONVENTION IN THIS PACKAGE (census, 2026-09-11)
+ * -------------------------------------------------------
+ * acr absent-defaults:  '0' x1, '1' x3, '2' x1   <- the '2' was auth-handler
+ * amr absent-defaults:  []  x5, ['pwd','mfa'] x1 <- the list was auth-handler
+ *
+ * Both fail-open values were outliers at a single site, not the convention.
+ * These constants adopt the majority, fail-closed convention.
+ */
+/**
+ * The assurance level used when the session and token say NOTHING about it.
+ *
+ * '1' = a single factor. It does not assert that a second factor happened.
+ * It must never be '2' (or higher): that is the value the IDP reads as
+ * "a second factor was completed", and an absent claim is not evidence of one.
+ */
+export declare const ACR_WHEN_ABSENT = "1";
+/**
+ * The authentication-methods list used when nothing is known.
+ *
+ * Empty asserts nothing. It must never contain 'mfa' (or any second-factor
+ * method): claiming a method that was never exercised is the same fabrication
+ * as ACR '2', and because the two corroborate each other a downstream check
+ * that cross-validates amr against acr would accept the fabricated pair.
+ */
+export declare const AMR_WHEN_ABSENT: readonly string[];
+/**
+ * Resolve an assurance level from any number of candidate sources, in
+ * priority order, falling back to the level that asserts no second factor.
+ *
+ * Accepts the candidates the refresh lane actually has: the stored
+ * `session.authenticationLevel` first, then the `acr` claim on the token.
+ */
+export declare function resolveAcrLevel(...candidates: unknown[]): string;
+/**
+ * Resolve the authentication-methods list.
+ *
+ * `raw` may arrive as a JSON string (the shape stored on the token) or as an
+ * array (the shape held on the session). Anything unparseable resolves to the
+ * empty list rather than to an assumed set of methods - a malformed claim is
+ * not evidence that mfa happened.
+ */
+export declare function resolveAuthMethods(...candidates: unknown[]): string[];

package/dist/lib/acr.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * CARD 375639 - the one place this package decides what an ABSENT assurance
+ * signal means.
+ *
+ * Card 375276 fixed this question inside `payez_idp_admin_web/src` (commit
+ * d9c6ac0, BAPert R980 remedy (a)) and fenced its own scope explicitly:
+ *
+ *     "fallbacks on the stored `session.authenticationLevel` (refresh lane)
+ *      are deliberately NOT covered ... That gap is 375276's remaining half."
+ *
+ * `src/api/auth-handler.ts` IS that remaining half, and it is in the shared
+ * package rather than in one app, so every consumer of the published
+ * `@payez/next-mvp/api/auth-handler` export inherits it.
+ *
+ * WHY BOTH SIGNALS LIVE IN ONE MODULE
+ * -----------------------------------
+ * `acr` (how strong the authentication was) and `amr` (which methods were
+ * used) are sent to the IDP together in a single refresh body. Defaulting one
+ * without the other produces an INCOHERENT assertion - "no second factor
+ * happened, and the method used was mfa" - so they are resolved side by side
+ * and a change to one is forced to confront the other.
+ *
+ * MEASURED CONVENTION IN THIS PACKAGE (census, 2026-09-11)
+ * -------------------------------------------------------
+ * acr absent-defaults:  '0' x1, '1' x3, '2' x1   <- the '2' was auth-handler
+ * amr absent-defaults:  []  x5, ['pwd','mfa'] x1 <- the list was auth-handler
+ *
+ * Both fail-open values were outliers at a single site, not the convention.
+ * These constants adopt the majority, fail-closed convention.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AMR_WHEN_ABSENT = exports.ACR_WHEN_ABSENT = void 0;
+exports.resolveAcrLevel = resolveAcrLevel;
+exports.resolveAuthMethods = resolveAuthMethods;
+/**
+ * The assurance level used when the session and token say NOTHING about it.
+ *
+ * '1' = a single factor. It does not assert that a second factor happened.
+ * It must never be '2' (or higher): that is the value the IDP reads as
+ * "a second factor was completed", and an absent claim is not evidence of one.
+ */
+exports.ACR_WHEN_ABSENT = '1';
+/**
+ * The authentication-methods list used when nothing is known.
+ *
+ * Empty asserts nothing. It must never contain 'mfa' (or any second-factor
+ * method): claiming a method that was never exercised is the same fabrication
+ * as ACR '2', and because the two corroborate each other a downstream check
+ * that cross-validates amr against acr would accept the fabricated pair.
+ */
+exports.AMR_WHEN_ABSENT = [];
+/**
+ * True when an assurance signal carries no information.
+ *
+ * Deliberately NOT `!value`. The `||` idiom this replaces cannot tell
+ * "the token said nothing" from "the token said 0", and numeric 0 is a
+ * meaningful assurance level (unauthenticated) that must survive as '0'
+ * rather than being promoted to the fallback.
+ */
+function isAbsent(value) {
+    return value === undefined || value === null || value === '';
+}
+/**
+ * Resolve an assurance level from any number of candidate sources, in
+ * priority order, falling back to the level that asserts no second factor.
+ *
+ * Accepts the candidates the refresh lane actually has: the stored
+ * `session.authenticationLevel` first, then the `acr` claim on the token.
+ */
+function resolveAcrLevel(...candidates) {
+    for (const candidate of candidates) {
+        if (!isAbsent(candidate)) {
+            return String(candidate);
+        }
+    }
+    return exports.ACR_WHEN_ABSENT;
+}
+/**
+ * Resolve the authentication-methods list.
+ *
+ * `raw` may arrive as a JSON string (the shape stored on the token) or as an
+ * array (the shape held on the session). Anything unparseable resolves to the
+ * empty list rather than to an assumed set of methods - a malformed claim is
+ * not evidence that mfa happened.
+ */
+function resolveAuthMethods(...candidates) {
+    for (const candidate of candidates) {
+        if (isAbsent(candidate))
+            continue;
+        if (Array.isArray(candidate)) {
+            return candidate.map(String);
+        }
+        if (typeof candidate === 'string') {
+            try {
+                const parsed = JSON.parse(candidate);
+                if (Array.isArray(parsed)) {
+                    return parsed.map(String);
+                }
+            }
+            catch {
+                // A malformed amr claim asserts nothing. Fall through to the next
+                // candidate rather than inventing methods.
+                continue;
+            }
+        }
+    }
+    return [...exports.AMR_WHEN_ABSENT];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.4.2",
+  "version": "4.4.3",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,6 +24,7 @@
     "dev:local": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/dev-local.ps1",
     "dev:broker": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/dev-broker.ps1",
     "check:publish-health": "node scripts/check-publish-health.mjs",
+    "census:reach": "node scripts/module-reach.mjs",
     "build:incremental": "npx tsc --project tsconfig.json"
   },
   "exports": {

package/scripts/module-reach.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * module-reach.mjs - module-graph reachability census over the BUILT dist/.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Cards 372358 / 373665 rest on numbers like "40 consumer-mountable entry points can
+ * reach server/auth". Those numbers were originally produced by a script that was run
+ * inline and never committed, so nobody could reproduce them. A number nobody can
+ * re-derive is a rumour. This file is that script, made durable and self-testing.
+ *
+ * WHAT IT MEASURES
+ * ----------------
+ * Over dist/**\/*.js (the artifact a consumer actually installs, NOT src/):
+ *   - the module graph (nodes + edges)
+ *   - which modules transitively REACH a target module (reverse reachability)
+ *   - which of those are MOUNTABLE - i.e. named in package.json "exports", so a
+ *     consumer can import them directly and thereby pull the target in
+ *
+ * HOW EDGES ARE FOUND - and why this shape was chosen
+ * ---------------------------------------------------
+ * We do NOT pattern-match `require(...)`. Three real defects came from doing that:
+ *   1. QUOTE STYLE - a pattern written with "  misses '  (tsc emits either).
+ *   2. SIBLING PATHS - a pattern anchored on `./lib/` misses a plain `./auth`.
+ *   3. DYNAMIC IMPORT - `await import('x')`, and tsc's downlevel
+ *      `Promise.resolve().then(() => __importStar(require('x')))`, are not `require(` calls
+ *      in the shape a naive pattern expects.
+ * Instead: extract EVERY string literal (', ", and substitution-free `), and keep the ones
+ * that RESOLVE to a real file on disk. Keyword-agnostic and quote-agnostic by construction,
+ * so all three modes above are caught without enumerating them.
+ *
+ * THE HONESTY SIGNAL
+ * ------------------
+ * A relative specifier that does NOT resolve is counted as UNRESOLVED. Unresolved > 0 means
+ * the graph is incomplete and every count derived from it is a lower bound. The tool says so
+ * loudly rather than quietly under-reporting. Counts are reported over CALL SITES where
+ * relevant, never deduplicated to "files that mention it" - that conflation is its own defect.
+ *
+ * BOUND: this is a STATIC graph over emitted JS. It proves a module is REACHABLE, not that it
+ * is EXECUTED at runtime, and not that reaching it has any security consequence. Reachability
+ * is necessary for consequence, never sufficient. Do not quote this tool as proof of impact.
+ *
+ * USAGE
+ *   node scripts/module-reach.mjs --to server/auth
+ *   node scripts/module-reach.mjs --to server/auth --json
+ *   node scripts/module-reach.mjs --graph-only
+ *   node scripts/module-reach.mjs --to server/auth --pkg <dir>   (default: package root)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CANDIDATE_EXTS = ['', '.js', '.mjs', '.cjs', '.json'];
+const INDEX_FILES = ['index.js', 'index.mjs', 'index.cjs'];
+
+/** Extract every string literal. Handles ' " and substitution-free `. Escape-aware. */
+export function extractStringLiterals(src) {
+  const out = [];
+  const n = src.length;
+  let i = 0;
+  while (i < n) {
+    const ch = src[i];
+    // skip line comments
+    if (ch === '/' && src[i + 1] === '/') {
+      while (i < n && src[i] !== '\n') i++;
+      continue;
+    }
+    // skip block comments
+    if (ch === '/' && src[i + 1] === '*') {
+      i += 2;
+      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const quote = ch;
+      let j = i + 1;
+      let buf = '';
+      let sawSubstitution = false;
+      while (j < n) {
+        const c = src[j];
+        if (c === '\\') { buf += src[j + 1] ?? ''; j += 2; continue; }
+        if (c === quote) break;
+        if (quote === '`' && c === '$' && src[j + 1] === '{') sawSubstitution = true;
+        if (quote !== '`' && (c === '\n' || c === '\r')) break; // unterminated
+        buf += c;
+        j++;
+      }
+      // A template literal WITH ${...} is not a static specifier - we cannot resolve it,
+      // and pretending otherwise would invent an edge. Dropped, and counted by the caller.
+      if (!sawSubstitution) out.push(buf);
+      i = j + 1;
+      continue;
+    }
+    i++;
+  }
+  return out;
+}
+
+/** Resolve a relative specifier from `fromFile` to a real file, or null. */
+export function resolveSpecifier(fromFile, spec, exists) {
+  const base = path.resolve(path.dirname(fromFile), spec);
+  for (const ext of CANDIDATE_EXTS) {
+    const cand = base + ext;
+    if (exists(cand)) return cand;
+  }
+  for (const idx of INDEX_FILES) {
+    const cand = path.join(base, idx);
+    if (exists(cand)) return cand;
+  }
+  return null;
+}
+
+const isRelative = (s) => s === '.' || s === '..' || s.startsWith('./') || s.startsWith('../');
+
+function walkJs(dir, acc = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walkJs(p, acc);
+    else if (e.isFile() && /\.(js|mjs|cjs)$/.test(e.name)) acc.push(p);
+  }
+  return acc;
+}
+
+export function buildGraph(distDir, opts = {}) {
+  const readFile = opts.readFile || ((f) => fs.readFileSync(f, 'utf8'));
+  const exists = opts.exists || ((f) => { try { return fs.statSync(f).isFile(); } catch { return false; } });
+  const files = (opts.files || walkJs(distDir)).map((f) => path.resolve(f));
+
+  const rel = (f) => path.relative(distDir, f).split(path.sep).join('/');
+  const forward = new Map();   // module -> Set(module)
+  const reverse = new Map();   // module -> Set(module)
+  const unresolved = [];       // {from, spec} - CALL SITES, not deduped
+  let edgeSites = 0;
+  let externalSites = 0;
+  let dotValueSites = 0;
+
+  for (const f of files) { forward.set(rel(f), new Set()); reverse.set(rel(f), new Set()); }
+
+  for (const f of files) {
+    const from = rel(f);
+    for (const spec of extractStringLiterals(readFile(f))) {
+      if (!isRelative(spec)) {
+        // bare specifier: 'next/server', 'jose'. External to this package, not a defect.
+        if (/^[@a-zA-Z]/.test(spec) && !spec.includes(' ') && spec.length < 100) externalSites++;
+        continue;
+      }
+      const target = resolveSpecifier(f, spec, exists);
+      if (!target) {
+        // A LONE "." or ".." that does not resolve is the CHARACTER, not a specifier:
+        // verified in this dist - every occurrence is `token.split('.')`. `require('.')`
+        // is still legal, so we only discount it AFTER resolution has actually failed.
+        if (spec === '.' || spec === '..') { dotValueSites++; continue; }
+        unresolved.push({ from, spec });
+        continue;
+      }
+      const to = rel(target);
+      if (!forward.has(to)) continue; // resolved outside the scanned set
+      edgeSites++;
+      forward.get(from).add(to);
+      reverse.get(to).add(from);
+    }
+  }
+
+  let edgeCount = 0;
+  for (const s of forward.values()) edgeCount += s.size;
+
+  return { distDir, modules: [...forward.keys()].sort(), forward, reverse, unresolved, edgeCount, edgeSites, externalSites, dotValueSites };
+}
+
+/** Reverse-transitive closure: every module that can reach `target`. */
+export function reachers(graph, target) {
+  if (!graph.reverse.has(target)) return null;
+  const depth = new Map([[target, 0]]);
+  const queue = [target];
+  while (queue.length) {
+    const cur = queue.shift();
+    for (const prev of graph.reverse.get(cur) || []) {
+      if (!depth.has(prev)) { depth.set(prev, depth.get(cur) + 1); queue.push(prev); }
+    }
+  }
+  depth.delete(target);
+  return depth;
+}
+
+/** Every dist/*.js named as a target in package.json "exports". */
+export function exportTargets(pkgJson) {
+  const out = new Map(); // distRelPath -> Set(subpath)
+  const visit = (subpath, node) => {
+    if (typeof node === 'string') {
+      if (!node.endsWith('.js')) return;
+      // normalise './dist/lib/x.js' and './lib/x.js' (both appear) to 'lib/x.js'
+      let p = node.replace(/^\.\//, '');
+      p = p.replace(/^dist\//, '');
+      if (!out.has(p)) out.set(p, new Set());
+      out.get(p).add(subpath);
+      return;
+    }
+    if (node && typeof node === 'object') for (const v of Object.values(node)) visit(subpath, v);
+  };
+  for (const [subpath, node] of Object.entries(pkgJson.exports || {})) visit(subpath, node);
+  if (typeof pkgJson.main === 'string') visit('. (main)', './' + pkgJson.main);
+  return out;
+}
+
+function main(argv) {
+  const arg = (k) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : undefined; };
+  const pkgDir = path.resolve(arg('--pkg') || path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')), '..'));
+  const distDir = path.join(pkgDir, 'dist');
+  const json = argv.includes('--json');
+  const to = arg('--to');
+
+  if (!fs.existsSync(distDir)) {
+    console.error(`[module-reach] FATAL: no dist at ${distDir}. Run \`npm run build\` first.`);
+    console.error('[module-reach] Refusing to report a census over a tree that does not exist.');
+    process.exit(2);
+  }
+
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'));
+  const graph = buildGraph(distDir);
+  const exports_ = exportTargets(pkgJson);
+
+  const report = {
+    package: pkgJson.name, version: pkgJson.version, distDir,
+    modules: graph.modules.length, edges: graph.edgeCount, edgeSites: graph.edgeSites,
+    externalSites: graph.externalSites,
+    unresolvedSites: graph.unresolved.length,
+    exportSubpaths: Object.keys(pkgJson.exports || {}).length,
+    exportTargetFiles: exports_.size,
+  };
+
+  if (to) {
+    const candidates = [to, `${to}.js`, `${to}/index.js`].map((t) => t.replace(/^\.\//, ''));
+    const target = candidates.find((c) => graph.reverse.has(c));
+    if (!target) {
+      console.error(`[module-reach] FATAL: target not in dist graph: ${to}`);
+      console.error(`[module-reach] tried: ${candidates.join(', ')}`);
+      process.exit(2);
+    }
+    const depth = reachers(graph, target);
+    const all = [...depth.keys()].sort();
+    const direct = all.filter((m) => depth.get(m) === 1);
+    const mountable = all.filter((m) => exports_.has(m));
+    report.target = target;
+    report.directRequirers = direct.length;
+    report.reaching = all.length;
+    report.mountable = mountable.length;
+    report.targetIsItselfMountable = exports_.has(target);
+    report.directRequirerList = direct;
+    report.mountableList = mountable.map((m) => ({ module: m, subpaths: [...exports_.get(m)] }));
+  }
+
+  if (json) { console.log(JSON.stringify(report, null, 2)); return; }
+
+  console.log(`[module-reach] ${report.package}@${report.version}`);
+  console.log(`  dist modules ......... ${report.modules}`);
+  console.log(`  edges (unique) ....... ${report.edges}`);
+  console.log(`  edge call sites ...... ${report.edgeSites}`);
+  console.log(`  external specifiers .. ${report.externalSites}  (bare, outside this package)`);
+  console.log(`  export subpaths ...... ${report.exportSubpaths} -> ${report.exportTargetFiles} distinct dist files`);
+  if (report.unresolvedSites === 0) {
+    console.log(`  unresolved ........... 0  <- graph is complete; counts below are exact`);
+  } else {
+    console.log(`  unresolved ........... ${report.unresolvedSites}  *** GRAPH INCOMPLETE - ALL COUNTS BELOW ARE LOWER BOUNDS ***`);
+    for (const u of graph.unresolved.slice(0, 20)) console.log(`      ${u.from} -> ${u.spec}`);
+  }
+  if (report.target) {
+    console.log('');
+    console.log(`  TARGET: ${report.target}${report.targetIsItselfMountable ? '  (itself a public export)' : ''}`);
+    console.log(`  direct requirers ..... ${report.directRequirers}`);
+    console.log(`  transitively reaching  ${report.reaching}`);
+    console.log(`  ...of which MOUNTABLE  ${report.mountable}  <- consumer-reachable entry points`);
+    console.log('');
+    console.log('  BOUND: static reachability over emitted JS. Proves reachable, NOT executed,');
+    console.log('  and NOT that reaching it has any consequence. Do not quote as proof of impact.');
+  }
+}
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(path.basename(process.argv[1]));
+if (invokedDirectly) main(process.argv.slice(2));

package/src/api/auth-handler.ts

@@ -15,6 +15,7 @@
 
 import { NextRequest, NextResponse } from 'next/server';
 import { getSession as getBetterAuthSession } from '../server/auth';
+import { resolveAcrLevel, resolveAuthMethods } from '../lib/acr';
 import { nanoid } from 'nanoid';
 import {
   getSession,
@@ -244,10 +245,24 @@ export function createAuthHandler(options: AuthHandlerOptions = {}) {
         return { success: false, error: 'No refresh token' };
       }
 
-      // Extract authentication methods from session
-      const authMethods = (currentSession as any).authMethods ||
-                         ((currentSession as any).token?.amr ? JSON.parse((currentSession as any).token.amr) : ['pwd', 'mfa']);
-      const authLevel = String((currentSession as any).authenticationLevel || (currentSession as any).token?.acr || '2');
+      // Extract authentication methods from session.
+      //
+      // 375639: these two lines used to read
+      //     authMethods = ... : ['pwd', 'mfa']
+      //     authLevel   = String(... || ... || '2')
+      // so a session that knew NOTHING about how the user authenticated told
+      // the IDP that a second factor had happened AND named 'mfa' as the
+      // method. The two fabrications corroborated each other, so a downstream
+      // check cross-validating amr against acr would have accepted the pair.
+      // Absent is not satisfied; both now resolve fail-closed, in one place.
+      const authMethods = resolveAuthMethods(
+        (currentSession as any).authMethods,
+        (currentSession as any).token?.amr
+      );
+      const authLevel = resolveAcrLevel(
+        (currentSession as any).authenticationLevel,
+        (currentSession as any).token?.acr
+      );
       const twoFactorMethod = (currentSession as any).twoFactorMethod || 'authenticator';
 
       // Build refresh request body

package/src/auth/safe-callback.ts

@@ -21,6 +21,27 @@
  *   v1  `startsWith('/') && !startsWith('//')`            -> bypassed by  /BACKSLASH host
  *   v2  + `!startsWith('/' + BACKSLASH)`                  -> bypassed by  /TAB/host
  *   ...                                                      and /LF/host, /CR/host
+ *   v3  resolve once + compare ORIGIN                     -> bypassed by  /..//host
+ *                                                            and /.//host, /%2e%2e//host
+ *   v4  + require the RESULT to be a FIXED POINT          <- current
+ *
+ * *** DRIFT, 2026-09-11 (325543). THIS FILE WAS v3 WHILE THE PORTAL'S COPY WAS
+ * *** v4, AND THE PACKAGE COPY IS THE ONE THAT SHIPPED. The portal fixed its own
+ * *** src/lib/safe-callback.ts (e1f08fea) and deployed; the served bundle STILL
+ * *** escaped 5/5 in a real browser, because `src/contexts/ThemeContext.tsx`
+ * *** imports the BARE BARREL `@payez/next-mvp`, which pulls dist/index.js ->
+ * *** auth/auth-decision -> THIS FILE into the client graph, and because the
+ * *** portal's `src/middleware.ts` imports `@payez/next-mvp/edge`, which requires
+ * *** THIS FILE server-side on every request. It was read as a stale build
+ * *** artifact of the portal's file for most of a day. It was not. It was a
+ * *** SECOND DEFINITION, and no rebuild of the portal could have removed it.
+ * *** The header below says "ONE definition ... for the whole package" and that
+ * *** was true INSIDE this package boundary the entire time. The defect lived in
+ * *** the gap BETWEEN two boundaries that each enforced one-definition correctly.
+ * *** A guard that exists in N copies is only as strong as its weakest copy, and
+ * *** a per-repo grep gate cannot see N. IF YOU CHANGE THE PREDICATE HERE, CHANGE
+ * *** IT IN THE PORTAL'S src/lib/safe-callback.ts IN THE SAME HOUR, OR DELETE ONE
+ * *** OF THEM.
  *
  * Both bypasses work the same way: the browser NORMALISES the string AFTER the
  * guard has finished looking at it. The WHATWG URL parser converts backslashes
@@ -75,18 +96,69 @@ export function safeCallbackPath(raw: unknown, fallback: string = DEFAULT_CALLBA
   if (url.pathname.startsWith(AUTH_PREFIX)) return fallback;
 
   // The parser's normalised output - control characters already stripped.
-  return url.pathname + url.search + url.hash;
-}
+  const candidate = url.pathname + url.search + url.hash;
 
-/** True when `raw` is a callback target we are willing to honour. */
-export function isSafeCallbackPath(raw: unknown): raw is string {
-  if (typeof raw !== 'string' || raw.length === 0) return false;
+  // *** SECOND RESOLUTION. DO NOT DELETE THIS AS REDUNDANT - IT IS NOT. ***
+  //
+  // v3 (the origin comparison above) was bypassed too, and differently from v1/v2.
+  // The origin check constrains where `raw` RESOLVED TO. It does not constrain how
+  // the RESULT IS SPELLED - and the result is resolved a SECOND time, by whoever
+  // navigates to it. A returned path that begins with `//` is a PROTOCOL-RELATIVE
+  // URL at that second resolution, so it lands off-origin having passed every
+  // check here:
+  //
+  //     '/..//evil.example.com'     -> pathname '//evil.example.com'  -> evil.example.com
+  //     '/.//evil.example.com'      -> pathname '//evil.example.com'  -> evil.example.com
+  //     '/%2e%2e//evil.example.com' -> pathname '//evil.example.com'  -> evil.example.com
+  //
+  // The parser resolves `..` against the synthetic base and, at the root, leaves
+  // behind the EMPTY SEGMENT rather than collapsing it. Origin stayed BASE the
+  // whole time, so nothing upstream fired.
+  //
+  // MEASURED, not reasoned: in a real headless Chromium on the live origin
+  // https://portal.keelauth.com, 5 spellings resolved to https://evil.example.com
+  // (QAPert-NightHawk, 2026-09-11, card 325543), and on 2026-09-11 the SERVED
+  // BUNDLE was measured escaping 5/5 through THIS PACKAGE'S copy while the
+  // portal's own src/lib/safe-callback.ts was already fixed - the two copies had
+  // drifted. See the DRIFT note in this file's header.
+  //
+  // THE FIX FOLLOWS THIS FILE'S OWN DOCTRINE: do not pattern-match the spellings
+  // (that is the startsWith() trap that failed four times, and this would be the
+  // fifth). Ask the parser AGAIN about the exact value we are about to hand out,
+  // and require it to be a FIXED POINT. Anything whose meaning changes when it is
+  // resolved a second time is by definition not a stable same-origin path, however
+  // it is spelled - including spellings nobody has found yet.
+  let echo: URL;
   try {
-    const url = new URL(raw, BASE);
-    return url.origin === BASE && !url.pathname.startsWith(AUTH_PREFIX);
+    echo = new URL(candidate, BASE);
   } catch {
-    return false;
+    return fallback;
   }
+  if (echo.origin !== BASE) return fallback;
+  if (echo.pathname.startsWith(AUTH_PREFIX)) return fallback;
+  if (echo.pathname + echo.search + echo.hash !== candidate) return fallback;
+
+  return candidate;
+}
+
+/**
+ * Sentinel that `safeCallbackPath` can never legitimately return: it is not a
+ * fixed point of the URL parser (the parser would percent-encode the space), so
+ * it cannot collide with a genuine accepted value.
+ */
+const REJECTED = '\u0000rejected';
+
+/**
+ * True when `raw` is a callback target we are willing to honour.
+ *
+ * DEFINED IN TERMS OF `safeCallbackPath` ON PURPOSE - it used to carry its own
+ * copy of the predicate, and that copy was missing the second resolution above
+ * while the two were maintained separately. This file's whole history is
+ * duplicated predicates drifting apart (see the header). One definition, one
+ * place to fix.
+ */
+export function isSafeCallbackPath(raw: unknown): raw is string {
+  return typeof raw === 'string' && raw.length > 0 && safeCallbackPath(raw, REJECTED) !== REJECTED;
 }
 
 /**

package/src/lib/acr.ts

@@ -0,0 +1,109 @@
+/**
+ * CARD 375639 - the one place this package decides what an ABSENT assurance
+ * signal means.
+ *
+ * Card 375276 fixed this question inside `payez_idp_admin_web/src` (commit
+ * d9c6ac0, BAPert R980 remedy (a)) and fenced its own scope explicitly:
+ *
+ *     "fallbacks on the stored `session.authenticationLevel` (refresh lane)
+ *      are deliberately NOT covered ... That gap is 375276's remaining half."
+ *
+ * `src/api/auth-handler.ts` IS that remaining half, and it is in the shared
+ * package rather than in one app, so every consumer of the published
+ * `@payez/next-mvp/api/auth-handler` export inherits it.
+ *
+ * WHY BOTH SIGNALS LIVE IN ONE MODULE
+ * -----------------------------------
+ * `acr` (how strong the authentication was) and `amr` (which methods were
+ * used) are sent to the IDP together in a single refresh body. Defaulting one
+ * without the other produces an INCOHERENT assertion - "no second factor
+ * happened, and the method used was mfa" - so they are resolved side by side
+ * and a change to one is forced to confront the other.
+ *
+ * MEASURED CONVENTION IN THIS PACKAGE (census, 2026-09-11)
+ * -------------------------------------------------------
+ * acr absent-defaults:  '0' x1, '1' x3, '2' x1   <- the '2' was auth-handler
+ * amr absent-defaults:  []  x5, ['pwd','mfa'] x1 <- the list was auth-handler
+ *
+ * Both fail-open values were outliers at a single site, not the convention.
+ * These constants adopt the majority, fail-closed convention.
+ */
+
+/**
+ * The assurance level used when the session and token say NOTHING about it.
+ *
+ * '1' = a single factor. It does not assert that a second factor happened.
+ * It must never be '2' (or higher): that is the value the IDP reads as
+ * "a second factor was completed", and an absent claim is not evidence of one.
+ */
+export const ACR_WHEN_ABSENT = '1';
+
+/**
+ * The authentication-methods list used when nothing is known.
+ *
+ * Empty asserts nothing. It must never contain 'mfa' (or any second-factor
+ * method): claiming a method that was never exercised is the same fabrication
+ * as ACR '2', and because the two corroborate each other a downstream check
+ * that cross-validates amr against acr would accept the fabricated pair.
+ */
+export const AMR_WHEN_ABSENT: readonly string[] = [];
+
+/**
+ * True when an assurance signal carries no information.
+ *
+ * Deliberately NOT `!value`. The `||` idiom this replaces cannot tell
+ * "the token said nothing" from "the token said 0", and numeric 0 is a
+ * meaningful assurance level (unauthenticated) that must survive as '0'
+ * rather than being promoted to the fallback.
+ */
+function isAbsent(value: unknown): boolean {
+  return value === undefined || value === null || value === '';
+}
+
+/**
+ * Resolve an assurance level from any number of candidate sources, in
+ * priority order, falling back to the level that asserts no second factor.
+ *
+ * Accepts the candidates the refresh lane actually has: the stored
+ * `session.authenticationLevel` first, then the `acr` claim on the token.
+ */
+export function resolveAcrLevel(...candidates: unknown[]): string {
+  for (const candidate of candidates) {
+    if (!isAbsent(candidate)) {
+      return String(candidate);
+    }
+  }
+  return ACR_WHEN_ABSENT;
+}
+
+/**
+ * Resolve the authentication-methods list.
+ *
+ * `raw` may arrive as a JSON string (the shape stored on the token) or as an
+ * array (the shape held on the session). Anything unparseable resolves to the
+ * empty list rather than to an assumed set of methods - a malformed claim is
+ * not evidence that mfa happened.
+ */
+export function resolveAuthMethods(...candidates: unknown[]): string[] {
+  for (const candidate of candidates) {
+    if (isAbsent(candidate)) continue;
+
+    if (Array.isArray(candidate)) {
+      return candidate.map(String);
+    }
+
+    if (typeof candidate === 'string') {
+      try {
+        const parsed = JSON.parse(candidate);
+        if (Array.isArray(parsed)) {
+          return parsed.map(String);
+        }
+      } catch {
+        // A malformed amr claim asserts nothing. Fall through to the next
+        // candidate rather than inventing methods.
+        continue;
+      }
+    }
+  }
+  return [...AMR_WHEN_ABSENT];
+}