@payez/next-mvp 4.8.1 → 4.8.2

package/src/auth/safe-callback.ts

@@ -1,199 +1,199 @@
-/**
- * ONE definition of "is this callback target safe to navigate to", for the
- * whole package (375656).
- *
- * *** THIS DELEGATES PARSING TO THE URL PARSER. DO NOT REPLACE IT WITH
- * *** startsWith() CHECKS. THAT APPROACH FAILED FOUR TIMES.
- *
- * WHY THIS FILE EXISTS: `@payez/next-mvp` shipped THREE bodies named
- * `makeAuthDecision`, each carrying its own `callbackUrl.startsWith('/account-auth/')`
- * test. That test is a REDIRECT-LOOP guard sitting in the seat where an ORIGIN
- * check belongs - its own comment says "prevents infinite loop" - so
- * `https://evil.example.com` does not start with `/account-auth/`, passes
- * through untouched, and becomes the redirect target. The exported copy
- * (`auth/auth-decision.ts`, re-exported from `index.ts` and `edge/middleware.ts`)
- * is public API, so that is a published open redirect independent of who calls it.
- *
- * HISTORY, because it is the whole argument for the current shape (267097 /
- * 267174 / 267448), carried over verbatim from the portal's `src/lib/safe-callback.ts`
- * where this guard was proven (0 leaks / 21 hostile inputs):
- *
- *   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
- * to forward slashes and STRIPS all ASCII tab, LF and CR before resolving. So a
- * prefix check can always be defeated by a character that is not there yet when
- * it runs. Each fix bought one character. The list was never provably complete.
- *
- * SO: stop re-implementing the parser and ask it instead. Resolve the input
- * against a synthetic base and compare ORIGINS. Anything that escapes the
- * origin - however it is spelled, including spellings nobody has found yet -
- * fails one comparison. The returned value is the parser's own NORMALISED
- * output, so an accepted path cannot smuggle a control character onward either.
- *
- * A synthetic base is used deliberately so this works identically in a server
- * component (no window), on the client, and in the edge runtime.
- */
-
-/** Where we send anyone whose requested target we will not honour. */
-export const DEFAULT_CALLBACK = '/';
-
-/** The auth surface. A callback pointing back into it causes a redirect cycle. */
-const AUTH_PREFIX = '/account-auth/';
-
-/**
- * PAY-2315 (4.7.1): the middleware now treats the public /login page like /account-auth/login (a signed-in user is sent
- * on), so a callback or a resolved path that is /login itself must be refused here too - otherwise /login with no
- * callbackUrl would resolve its own pathname as the destination and redirect to itself forever.
- */
-function isAuthSurface(pathname: string): boolean {
-  return pathname.startsWith(AUTH_PREFIX) || pathname === '/login' || pathname.startsWith('/login/');
-}
-
-/**
- * Synthetic, unreachable base. Only ever used as the resolution origin for the
- * comparison below - never emitted, never navigated to. `.invalid` is reserved
- * by RFC 2606 and can never resolve.
- */
-const BASE = 'http://safe-callback.invalid';
-
-/**
- * The value to navigate to: a same-origin relative path, NORMALISED by the URL
- * parser, or `fallback` for anything that escapes the origin or loops back into
- * the auth surface. Never throws.
- */
-export function safeCallbackPath(raw: unknown, fallback: string = DEFAULT_CALLBACK): string {
-  if (typeof raw !== 'string' || raw.length === 0) return fallback;
-
-  let url: URL;
-  try {
-    url = new URL(raw, BASE);
-  } catch {
-    return fallback;
-  }
-
-  // Anything that resolved to a different origin escaped, however it was spelled:
-  // absolute, protocol-relative //host, backslash /\host, tab/LF/CR variants, or
-  // a scheme like javascript: (whose origin is opaque and never equals BASE).
-  if (url.origin !== BASE) return fallback;
-
-  // Loopbacks into the auth surface cause redirect cycles.
-  if (isAuthSurface(url.pathname)) return fallback;
-
-  // PAY-2218: `_rsc` is Next's flight cache-buster. Once skipProxyUrlNormalize lets it reach middleware it leaks
-  // into return targets (`callbackUrl=/overview?_rsc=abc12`, NightHawk 72013); it is never a meaningful part of a
-  // destination. Only touched when present, so every other query keeps its exact spelling.
-  if (url.searchParams.has('_rsc')) url.searchParams.delete('_rsc');
-
-  // The parser's normalised output - control characters already stripped.
-  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: URL;
-  try {
-    echo = new URL(candidate, BASE);
-  } catch {
-    return fallback;
-  }
-  if (echo.origin !== BASE) return fallback;
-  if (isAuthSurface(echo.pathname)) 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;
-}
-
-/**
- * Pick the post-login destination: an explicit `?callbackUrl=` when it is one we
- * will honour, otherwise the current path, otherwise `/`.
- *
- * This replaces the package's three hand-rolled `getSafeCallbackUrl` /
- * `getCallbackUrl` bodies. Note the ARGUMENT ORDER DEPENDENCY those had: they
- * tested `pathname` FIRST and returned early, so a caller on the login page
- * never reached the attacker-controlled parameter at all - safe, but only
- * because that caller happened to pass a value that tripped the function's own
- * first guard. Nothing in the code named that dependency, and an argument
- * reorder would have opened it. Here BOTH inputs are validated, so the
- * protection no longer depends on which one is passed.
- */
-export function resolveCallbackDestination(
-  pathname: string,
-  searchParams?: URLSearchParams | null,
-  fallback: string = DEFAULT_CALLBACK
-): string {
-  const requested = searchParams?.get('callbackUrl');
-  if (isSafeCallbackPath(requested)) return safeCallbackPath(requested, fallback);
-  return safeCallbackPath(pathname, fallback);
-}
+/**
+ * ONE definition of "is this callback target safe to navigate to", for the
+ * whole package (375656).
+ *
+ * *** THIS DELEGATES PARSING TO THE URL PARSER. DO NOT REPLACE IT WITH
+ * *** startsWith() CHECKS. THAT APPROACH FAILED FOUR TIMES.
+ *
+ * WHY THIS FILE EXISTS: `@payez/next-mvp` shipped THREE bodies named
+ * `makeAuthDecision`, each carrying its own `callbackUrl.startsWith('/account-auth/')`
+ * test. That test is a REDIRECT-LOOP guard sitting in the seat where an ORIGIN
+ * check belongs - its own comment says "prevents infinite loop" - so
+ * `https://evil.example.com` does not start with `/account-auth/`, passes
+ * through untouched, and becomes the redirect target. The exported copy
+ * (`auth/auth-decision.ts`, re-exported from `index.ts` and `edge/middleware.ts`)
+ * is public API, so that is a published open redirect independent of who calls it.
+ *
+ * HISTORY, because it is the whole argument for the current shape (267097 /
+ * 267174 / 267448), carried over verbatim from the portal's `src/lib/safe-callback.ts`
+ * where this guard was proven (0 leaks / 21 hostile inputs):
+ *
+ *   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
+ * to forward slashes and STRIPS all ASCII tab, LF and CR before resolving. So a
+ * prefix check can always be defeated by a character that is not there yet when
+ * it runs. Each fix bought one character. The list was never provably complete.
+ *
+ * SO: stop re-implementing the parser and ask it instead. Resolve the input
+ * against a synthetic base and compare ORIGINS. Anything that escapes the
+ * origin - however it is spelled, including spellings nobody has found yet -
+ * fails one comparison. The returned value is the parser's own NORMALISED
+ * output, so an accepted path cannot smuggle a control character onward either.
+ *
+ * A synthetic base is used deliberately so this works identically in a server
+ * component (no window), on the client, and in the edge runtime.
+ */
+
+/** Where we send anyone whose requested target we will not honour. */
+export const DEFAULT_CALLBACK = '/';
+
+/** The auth surface. A callback pointing back into it causes a redirect cycle. */
+const AUTH_PREFIX = '/account-auth/';
+
+/**
+ * PAY-2315 (4.7.1): the middleware now treats the public /login page like /account-auth/login (a signed-in user is sent
+ * on), so a callback or a resolved path that is /login itself must be refused here too - otherwise /login with no
+ * callbackUrl would resolve its own pathname as the destination and redirect to itself forever.
+ */
+function isAuthSurface(pathname: string): boolean {
+  return pathname.startsWith(AUTH_PREFIX) || pathname === '/login' || pathname.startsWith('/login/');
+}
+
+/**
+ * Synthetic, unreachable base. Only ever used as the resolution origin for the
+ * comparison below - never emitted, never navigated to. `.invalid` is reserved
+ * by RFC 2606 and can never resolve.
+ */
+const BASE = 'http://safe-callback.invalid';
+
+/**
+ * The value to navigate to: a same-origin relative path, NORMALISED by the URL
+ * parser, or `fallback` for anything that escapes the origin or loops back into
+ * the auth surface. Never throws.
+ */
+export function safeCallbackPath(raw: unknown, fallback: string = DEFAULT_CALLBACK): string {
+  if (typeof raw !== 'string' || raw.length === 0) return fallback;
+
+  let url: URL;
+  try {
+    url = new URL(raw, BASE);
+  } catch {
+    return fallback;
+  }
+
+  // Anything that resolved to a different origin escaped, however it was spelled:
+  // absolute, protocol-relative //host, backslash /\host, tab/LF/CR variants, or
+  // a scheme like javascript: (whose origin is opaque and never equals BASE).
+  if (url.origin !== BASE) return fallback;
+
+  // Loopbacks into the auth surface cause redirect cycles.
+  if (isAuthSurface(url.pathname)) return fallback;
+
+  // PAY-2218: `_rsc` is Next's flight cache-buster. Once skipProxyUrlNormalize lets it reach middleware it leaks
+  // into return targets (`callbackUrl=/overview?_rsc=abc12`, NightHawk 72013); it is never a meaningful part of a
+  // destination. Only touched when present, so every other query keeps its exact spelling.
+  if (url.searchParams.has('_rsc')) url.searchParams.delete('_rsc');
+
+  // The parser's normalised output - control characters already stripped.
+  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: URL;
+  try {
+    echo = new URL(candidate, BASE);
+  } catch {
+    return fallback;
+  }
+  if (echo.origin !== BASE) return fallback;
+  if (isAuthSurface(echo.pathname)) 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;
+}
+
+/**
+ * Pick the post-login destination: an explicit `?callbackUrl=` when it is one we
+ * will honour, otherwise the current path, otherwise `/`.
+ *
+ * This replaces the package's three hand-rolled `getSafeCallbackUrl` /
+ * `getCallbackUrl` bodies. Note the ARGUMENT ORDER DEPENDENCY those had: they
+ * tested `pathname` FIRST and returned early, so a caller on the login page
+ * never reached the attacker-controlled parameter at all - safe, but only
+ * because that caller happened to pass a value that tripped the function's own
+ * first guard. Nothing in the code named that dependency, and an argument
+ * reorder would have opened it. Here BOTH inputs are validated, so the
+ * protection no longer depends on which one is passed.
+ */
+export function resolveCallbackDestination(
+  pathname: string,
+  searchParams?: URLSearchParams | null,
+  fallback: string = DEFAULT_CALLBACK
+): string {
+  const requested = searchParams?.get('callbackUrl');
+  if (isSafeCallbackPath(requested)) return safeCallbackPath(requested, fallback);
+  return safeCallbackPath(pathname, fallback);
+}

package/src/auth/session-cookie-clear.ts

@@ -1,30 +1,30 @@
-/**
- * The ONE body that writes the session-cookie expiry Set-Cookie headers. Shared by the middleware
- * (create-middleware.ts clearSessionCookies, behind its prefetch guard) and the PAY-2218 session-reset route, so
- * the two clearing sites cannot drift apart on which cookies they expire or with which attributes.
- */
-import type { NextResponse } from 'next/server';
-import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
-
-export function expireSessionCookies(response: NextResponse, requestCookieNames: Iterable<string>): void {
-  const sessionCookie = getSessionCookieName();
-  const secureCookie = getSecureSessionCookieName();
-
-  // Clear main cookies
-  response.cookies.set(sessionCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax' });
-  response.cookies.set(secureCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax', secure: true });
-
-  // Clear any chunked cookies (NextAuth chunks large cookies)
-  for (const name of requestCookieNames) {
-    if (name.startsWith(`${sessionCookie}.`) || name.startsWith(`${secureCookie}.`)) {
-      const isSecure = name.startsWith('__Secure-');
-      response.cookies.set(name, '', {
-        path: '/',
-        expires: new Date(0),
-        httpOnly: true,
-        sameSite: 'lax',
-        ...(isSecure && { secure: true })
-      });
-    }
-  }
-}
+/**
+ * The ONE body that writes the session-cookie expiry Set-Cookie headers. Shared by the middleware
+ * (create-middleware.ts clearSessionCookies, behind its prefetch guard) and the PAY-2218 session-reset route, so
+ * the two clearing sites cannot drift apart on which cookies they expire or with which attributes.
+ */
+import type { NextResponse } from 'next/server';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+
+export function expireSessionCookies(response: NextResponse, requestCookieNames: Iterable<string>): void {
+  const sessionCookie = getSessionCookieName();
+  const secureCookie = getSecureSessionCookieName();
+
+  // Clear main cookies
+  response.cookies.set(sessionCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax' });
+  response.cookies.set(secureCookie, '', { path: '/', expires: new Date(0), httpOnly: true, sameSite: 'lax', secure: true });
+
+  // Clear any chunked cookies (NextAuth chunks large cookies)
+  for (const name of requestCookieNames) {
+    if (name.startsWith(`${sessionCookie}.`) || name.startsWith(`${secureCookie}.`)) {
+      const isSecure = name.startsWith('__Secure-');
+      response.cookies.set(name, '', {
+        path: '/',
+        expires: new Date(0),
+        httpOnly: true,
+        sameSite: 'lax',
+        ...(isSecure && { secure: true })
+      });
+    }
+  }
+}