@payez/next-mvp 4.4.2 → 4.4.4

package/dist/auth/better-auth.js

@@ -147,6 +147,20 @@ function isPlainObject(value) {
  * globalThis is per-process and per-runtime, which is exactly the lifetime a request-scoped
  * carrier needs to be reachable from every copy that might run inside the request.
  */
+/**
+ * THE KEY STAYS '__payezIdTokenScope' EVEN THOUGH THE SCOPE NOW CARRIES TWO
+ * THINGS. Renaming it would give a copy on the old name and a copy on the new
+ * name two DIFFERENT stores in the same process — which is precisely the
+ * double-load failure documented above, reintroduced by a cosmetic rename. The
+ * name is a wire contract between copies, not a description.
+ *
+ * accessToken is here for providers that do NOT issue an id_token. GitHub is
+ * not an OIDC provider: it has no id_token, no JWKS and no discovery document,
+ * so `id_token` can never be the field that proves a GitHub identity. The IDP
+ * re-derives that identity by calling GitHub itself with this access token
+ * (GitHubIdentityVerifier), which keeps the same rule google follows — the IDP
+ * verifies for itself and never trusts an asserted email.
+ */
 const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
 const gScope = globalThis;
 gScope[ID_TOKEN_SCOPE_KEY] ??= new node_async_hooks_1.AsyncLocalStorage();
@@ -248,9 +262,21 @@ function buildBetterAuthProviders(config) {
          * remains, so the provider emits exactly its default set.
          */
         const GOOGLE_DEFAULT_SCOPES = ['email', 'profile', 'openid'];
+        /**
+         * Same defect, same fix, different provider: github's createAuthorizationURL
+         * also seeds ['read:user','user:email'] unconditionally and then pushes ours
+         * on top (@better-auth/core social-providers/github.ts), so the stored row
+         * "read:user user:email" reached GitHub as
+         * "read:user user:email read:user user:email". Measured on :4799, not
+         * assumed. GitHub dedupes, so this is legibility rather than function — but
+         * a scope list is the first thing a security reviewer reads off that URL.
+         */
+        const GITHUB_DEFAULT_SCOPES = ['read:user', 'user:email'];
         const wireScopes = name === 'google'
             ? scopes.filter((s) => !GOOGLE_DEFAULT_SCOPES.includes(s))
-            : scopes;
+            : name === 'github'
+                ? scopes.filter((s) => !GITHUB_DEFAULT_SCOPES.includes(s))
+                : scopes;
         providers[name] = {
             clientId: oauth.clientId,
             clientSecret: oauth.clientSecret,
@@ -351,6 +377,82 @@ function buildBetterAuthProviders(config) {
                 };
             };
         }
+        /**
+         * GITHUB: THE SAME CAPTURE, A DIFFERENT TOKEN.
+         *
+         * GitHub is not an OIDC provider — it issues no id_token — so the google
+         * branch above can never fire for it and the exchange would post an
+         * assertion with nothing that proves identity. That is exactly the
+         * 401 UNVERIFIED_ASSERTION measured on :4799, whose diagnostics read
+         * `id_token_forwarded: false, id_token_length: 0` with `response_time_ms: 0`:
+         * the IDP rejected it instantly, without ever calling GitHub.
+         *
+         * getUserInfo is the ONLY provider hook that receives the token set (see the
+         * google note above), and @better-auth/core's github provider calls
+         * `options.getUserInfo(token)` BEFORE its own body — so installing this
+         * REPLACES the default rather than wrapping it, and the default's work has
+         * to be reproduced here or the sign-in loses its profile entirely.
+         *
+         * Mirrored verbatim from @better-auth/core/src/social-providers/github.ts at
+         * the version the container actually runs (better-auth 1.5.6 — the graft's
+         * node_modules says 1.6.29 and is NOT what executes). Kept deliberately
+         * dumb: it must not "improve" on upstream, because every divergence here is
+         * a behaviour change disguised as a token capture.
+         *
+         * This is NOT the identity check. The IDP re-derives the GitHub identity
+         * itself from this access token and enforces primary && verified server-side
+         * (GitHubIdentityVerifier); what we return here only shapes the local
+         * better-auth user record.
+         */
+        if (name === 'github') {
+            providers[name].getUserInfo = async (token) => {
+                const store = idTokenScope.getStore();
+                if (store) {
+                    store.accessToken = token?.accessToken;
+                }
+                else {
+                    console.warn('[BETTER_AUTH] github access_token captured but NO REQUEST SCOPE to put it in — ' +
+                        'it will NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
+                        'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.');
+                }
+                const ghHeaders = {
+                    'User-Agent': 'better-auth',
+                    Authorization: `Bearer ${token?.accessToken}`,
+                };
+                const profileRes = await fetch('https://api.github.com/user', {
+                    headers: ghHeaders,
+                });
+                // Upstream returns null on profile error, which fails the sign-in
+                // closed. Preserved rather than softened.
+                if (!profileRes.ok) {
+                    console.warn(`[BETTER_AUTH] github getUserInfo: /user returned ${profileRes.status}`);
+                    return null;
+                }
+                const profile = (await profileRes.json());
+                const emailsRes = await fetch('https://api.github.com/user/emails', {
+                    headers: ghHeaders,
+                });
+                const emails = emailsRes.ok
+                    ? (await emailsRes.json())
+                    : undefined;
+                // A GitHub account with a private email returns profile.email = null;
+                // upstream falls back to the primary address here.
+                if (!profile.email && emails) {
+                    profile.email = (emails.find((e) => e.primary) ?? emails[0])?.email;
+                }
+                const emailVerified = emails?.find((e) => e.email === profile.email)?.verified ?? false;
+                return {
+                    user: {
+                        id: profile.id,
+                        name: profile.name || profile.login || '',
+                        email: profile.email,
+                        image: profile.avatar_url,
+                        emailVerified,
+                    },
+                    data: profile,
+                };
+            };
+        }
     }
     return providers;
 }
@@ -802,6 +904,21 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
                  * distinguishable from "the provider issued none".
                  */
                 ...(idTokenScope.getStore()?.idToken ? { id_token: idTokenScope.getStore().idToken } : {}),
+                /**
+                 * The same field for providers that have no id_token to give.
+                 *
+                 * Identical doctrine to the id_token above: RAW, forwarded verbatim,
+                 * NOTHING DERIVED FROM IT, and omitted entirely rather than sent null so
+                 * "never captured" stays distinguishable from "provider issued none".
+                 * The IDP verifies for itself by calling GitHub with this token and
+                 * enforcing primary && verified; we assert nothing about the identity.
+                 *
+                 * Scoped to the provider access token captured during THIS callback, so
+                 * a google login continues to send id_token only and is unaffected.
+                 */
+                ...(idTokenScope.getStore()?.accessToken
+                    ? { access_token: idTokenScope.getStore().accessToken }
+                    : {}),
             }),
         });
         const oauthResText = await oauthRes.text();
@@ -833,9 +950,21 @@ async function exchangeOAuthForIdpTokens(sessionToken, provider = 'google') {
                     claims = { decode: 'FAILED — not a well-formed JWT' };
                 }
             }
+            const forwardedAccess = idTokenScope.getStore()?.accessToken;
             console.error('[BETTER_AUTH] exchange diagnostics:', {
                 id_token_forwarded: !!forwarded,
                 id_token_length: forwarded ? forwarded.length : 0,
+                /**
+                 * Read these two for github, and IGNORE the id_token pair above: github
+                 * issues no id_token, so `id_token_forwarded: false` is its NORMAL state
+                 * and not the fault. Presence and length only — an access token is
+                 * credential material and this log is persistent. A github failure with
+                 * access_token_forwarded:true means the IDP called GitHub and refused
+                 * the answer (unverified or non-primary email, or app not installed);
+                 * false means the capture hook never ran and the IDP never called out.
+                 */
+                access_token_forwarded: !!forwardedAccess,
+                access_token_length: forwardedAccess ? forwardedAccess.length : 0,
                 // Absent id_token => the IDP had nothing to verify. Present => compare these
                 // against the client's registered Google credentials on the IDP.
                 aud: claims.aud ?? null,

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.4.2",
+  "version": "4.4.4",
   "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": {
@@ -966,4 +967,4 @@
     "typescript": "^5.4.5",
     "zustand": "^4.5.5"
   }
-}
+}

package/scripts/module-reach.mjs

@@ -0,0 +1,286 @@
+#!/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);
+    // `__`-prefixed files in dist are TEST MUTANTS, never tsc output (measured:
+    // 0 of 245 in a clean dist). Several suites write one next to the real
+    // artifact — so its relative requires resolve — and delete it straight
+    // after, while `node --test` runs other files CONCURRENTLY. Counting one
+    // would make this census non-reproducible (the property the LIVE test
+    // asserts) and reading one after its delete lands is an ENOENT crash.
+    else if (e.isFile() && !e.name.startsWith('__') && /\.(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/auth/better-auth.ts

@@ -125,12 +125,27 @@ export interface BetterAuthSocialProvider {
  * globalThis is per-process and per-runtime, which is exactly the lifetime a request-scoped
  * carrier needs to be reachable from every copy that might run inside the request.
  */
+/**
+ * THE KEY STAYS '__payezIdTokenScope' EVEN THOUGH THE SCOPE NOW CARRIES TWO
+ * THINGS. Renaming it would give a copy on the old name and a copy on the new
+ * name two DIFFERENT stores in the same process — which is precisely the
+ * double-load failure documented above, reintroduced by a cosmetic rename. The
+ * name is a wire contract between copies, not a description.
+ *
+ * accessToken is here for providers that do NOT issue an id_token. GitHub is
+ * not an OIDC provider: it has no id_token, no JWKS and no discovery document,
+ * so `id_token` can never be the field that proves a GitHub identity. The IDP
+ * re-derives that identity by calling GitHub itself with this access token
+ * (GitHubIdentityVerifier), which keeps the same rule google follows — the IDP
+ * verifies for itself and never trusts an asserted email.
+ */
 const ID_TOKEN_SCOPE_KEY = '__payezIdTokenScope';
+type ProviderTokenScope = { idToken?: string; accessToken?: string };
 const gScope = globalThis as unknown as Record<
   string,
-  AsyncLocalStorage<{ idToken?: string }> | undefined
+  AsyncLocalStorage<ProviderTokenScope> | undefined
 >;
-gScope[ID_TOKEN_SCOPE_KEY] ??= new AsyncLocalStorage<{ idToken?: string }>();
+gScope[ID_TOKEN_SCOPE_KEY] ??= new AsyncLocalStorage<ProviderTokenScope>();
 const idTokenScope = gScope[ID_TOKEN_SCOPE_KEY]!;
 
 /**
@@ -242,10 +257,22 @@ export function buildBetterAuthProviders(
      * remains, so the provider emits exactly its default set.
      */
     const GOOGLE_DEFAULT_SCOPES = ['email', 'profile', 'openid'];
+    /**
+     * Same defect, same fix, different provider: github's createAuthorizationURL
+     * also seeds ['read:user','user:email'] unconditionally and then pushes ours
+     * on top (@better-auth/core social-providers/github.ts), so the stored row
+     * "read:user user:email" reached GitHub as
+     * "read:user user:email read:user user:email". Measured on :4799, not
+     * assumed. GitHub dedupes, so this is legibility rather than function — but
+     * a scope list is the first thing a security reviewer reads off that URL.
+     */
+    const GITHUB_DEFAULT_SCOPES = ['read:user', 'user:email'];
     const wireScopes =
       name === 'google'
         ? scopes.filter((s) => !GOOGLE_DEFAULT_SCOPES.includes(s))
-        : scopes;
+        : name === 'github'
+          ? scopes.filter((s) => !GITHUB_DEFAULT_SCOPES.includes(s))
+          : scopes;
 
     providers[name] = {
       clientId: oauth.clientId,
@@ -350,6 +377,98 @@ export function buildBetterAuthProviders(
         };
       };
     }
+
+    /**
+     * GITHUB: THE SAME CAPTURE, A DIFFERENT TOKEN.
+     *
+     * GitHub is not an OIDC provider — it issues no id_token — so the google
+     * branch above can never fire for it and the exchange would post an
+     * assertion with nothing that proves identity. That is exactly the
+     * 401 UNVERIFIED_ASSERTION measured on :4799, whose diagnostics read
+     * `id_token_forwarded: false, id_token_length: 0` with `response_time_ms: 0`:
+     * the IDP rejected it instantly, without ever calling GitHub.
+     *
+     * getUserInfo is the ONLY provider hook that receives the token set (see the
+     * google note above), and @better-auth/core's github provider calls
+     * `options.getUserInfo(token)` BEFORE its own body — so installing this
+     * REPLACES the default rather than wrapping it, and the default's work has
+     * to be reproduced here or the sign-in loses its profile entirely.
+     *
+     * Mirrored verbatim from @better-auth/core/src/social-providers/github.ts at
+     * the version the container actually runs (better-auth 1.5.6 — the graft's
+     * node_modules says 1.6.29 and is NOT what executes). Kept deliberately
+     * dumb: it must not "improve" on upstream, because every divergence here is
+     * a behaviour change disguised as a token capture.
+     *
+     * This is NOT the identity check. The IDP re-derives the GitHub identity
+     * itself from this access token and enforces primary && verified server-side
+     * (GitHubIdentityVerifier); what we return here only shapes the local
+     * better-auth user record.
+     */
+    if (name === 'github') {
+      (providers[name] as unknown as Record<string, unknown>).getUserInfo = async (token: {
+        accessToken?: string;
+      }) => {
+        const store = idTokenScope.getStore();
+        if (store) {
+          store.accessToken = token?.accessToken;
+        } else {
+          console.warn(
+            '[BETTER_AUTH] github access_token captured but NO REQUEST SCOPE to put it in — ' +
+              'it will NOT be forwarded and the IDP exchange will fail UNVERIFIED_ASSERTION. ' +
+              'Check that GET is createAuthGetHandler(), not routes/auth/nextauth.',
+          );
+        }
+
+        const ghHeaders = {
+          'User-Agent': 'better-auth',
+          Authorization: `Bearer ${token?.accessToken}`,
+        };
+
+        const profileRes = await fetch('https://api.github.com/user', {
+          headers: ghHeaders,
+        });
+        // Upstream returns null on profile error, which fails the sign-in
+        // closed. Preserved rather than softened.
+        if (!profileRes.ok) {
+          console.warn(
+            `[BETTER_AUTH] github getUserInfo: /user returned ${profileRes.status}`,
+          );
+          return null;
+        }
+        const profile = (await profileRes.json()) as Record<string, any>;
+
+        const emailsRes = await fetch('https://api.github.com/user/emails', {
+          headers: ghHeaders,
+        });
+        const emails = emailsRes.ok
+          ? ((await emailsRes.json()) as Array<{
+              email: string;
+              primary: boolean;
+              verified: boolean;
+            }>)
+          : undefined;
+
+        // A GitHub account with a private email returns profile.email = null;
+        // upstream falls back to the primary address here.
+        if (!profile.email && emails) {
+          profile.email = (emails.find((e) => e.primary) ?? emails[0])?.email;
+        }
+        const emailVerified =
+          emails?.find((e) => e.email === profile.email)?.verified ?? false;
+
+        return {
+          user: {
+            id: profile.id,
+            name: profile.name || profile.login || '',
+            email: profile.email,
+            image: profile.avatar_url,
+            emailVerified,
+          },
+          data: profile,
+        };
+      };
+    }
   }
 
   return providers;
@@ -900,6 +1019,21 @@ export async function exchangeOAuthForIdpTokens(
          * distinguishable from "the provider issued none".
          */
         ...(idTokenScope.getStore()?.idToken ? { id_token: idTokenScope.getStore()!.idToken } : {}),
+        /**
+         * The same field for providers that have no id_token to give.
+         *
+         * Identical doctrine to the id_token above: RAW, forwarded verbatim,
+         * NOTHING DERIVED FROM IT, and omitted entirely rather than sent null so
+         * "never captured" stays distinguishable from "provider issued none".
+         * The IDP verifies for itself by calling GitHub with this token and
+         * enforcing primary && verified; we assert nothing about the identity.
+         *
+         * Scoped to the provider access token captured during THIS callback, so
+         * a google login continues to send id_token only and is unaffected.
+         */
+        ...(idTokenScope.getStore()?.accessToken
+          ? { access_token: idTokenScope.getStore()!.accessToken }
+          : {}),
       }),
     });
 
@@ -933,9 +1067,21 @@ export async function exchangeOAuthForIdpTokens(
           claims = { decode: 'FAILED — not a well-formed JWT' };
         }
       }
+      const forwardedAccess = idTokenScope.getStore()?.accessToken;
       console.error('[BETTER_AUTH] exchange diagnostics:', {
         id_token_forwarded: !!forwarded,
         id_token_length: forwarded ? forwarded.length : 0,
+        /**
+         * Read these two for github, and IGNORE the id_token pair above: github
+         * issues no id_token, so `id_token_forwarded: false` is its NORMAL state
+         * and not the fault. Presence and length only — an access token is
+         * credential material and this log is persistent. A github failure with
+         * access_token_forwarded:true means the IDP called GitHub and refused
+         * the answer (unverified or non-primary email, or app not installed);
+         * false means the capture hook never ran and the IDP never called out.
+         */
+        access_token_forwarded: !!forwardedAccess,
+        access_token_length: forwardedAccess ? forwardedAccess.length : 0,
         // Absent id_token => the IDP had nothing to verify. Present => compare these
         // against the client's registered Google credentials on the IDP.
         aud: claims.aud ?? null,

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;
 }
 
 /**