@payez/next-mvp 4.8.0 → 4.8.2

package/src/lib/secret-validation.ts

@@ -1,8 +1,8 @@
-export function validateAuthSecret(secret: string): { valid: boolean; reason?: string } {
-  if (!secret || typeof secret !== 'string') return { valid: false, reason: 'missing' };
-  if (secret.length < 32) return { valid: false, reason: 'too_short' };
-  const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/];
-  const score = classes.reduce((acc, re) => acc + (re.test(secret) ? 1 : 0), 0);
-  if (score < 3) return { valid: false, reason: 'weak' };
-  return { valid: true };
-}
+export function validateAuthSecret(secret: string): { valid: boolean; reason?: string } {
+  if (!secret || typeof secret !== 'string') return { valid: false, reason: 'missing' };
+  if (secret.length < 32) return { valid: false, reason: 'too_short' };
+  const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/];
+  const score = classes.reduce((acc, re) => acc + (re.test(secret) ? 1 : 0), 0);
+  if (score < 3) return { valid: false, reason: 'weak' };
+  return { valid: true };
+}

package/src/lib/session-cookie-shape.ts

@@ -1,185 +1,185 @@
-import {
-  getJwtCookieName,
-  getSecureSessionCookieName,
-  getSessionCookieName,
-} from './app-slug';
-
-/**
- * Session-cookie SHAPE detection — shared by every fallback path that must
- * recover a Redis session token from a raw session-cookie value without
- * going through Better Auth's `auth.api.getSession()`.
- *
- * WHY THIS EXISTS (183047 post-mortem, BAPert/QAPert/Scout, 2026-08-08):
- *
- * Two cookie shapes exist in this codebase's history, and until now no
- * fallback path recognized both:
- *
- *  - JWS (3 dot-separated segments): the legacy NextAuth-era format. The
- *    session token lives in the payload's `sessionToken` claim, base64-JSON
- *    encoded in the middle segment.
- *  - BA-hmac (2 segments — exactly ONE dot): Better Auth's own hand-rolled
- *    cookie, `{token}.{base64(hmac)}` (see better-auth.ts's
- *    CreateBetterAuthInstanceOptions.plugins doc comment). The token here
- *    IS the first segment verbatim — there is no claim to decode.
- *
- * Every fallback that existed before this file assumed the JWS shape
- * unconditionally:
- *  - decode-session.ts's legacy path called jose's `jwtVerify()` directly on
- *    the cookie value. `jwtVerify` requires a genuine compact JWS and throws
- *    "Invalid Compact JWS" on a 2-segment value — secret-independent, before
- *    any signature is even checked.
- *  - auth.ts's `decodeJwtBody()` required `parts.length === 3` and returned
- *    null otherwise.
- *
- * Since Better Auth is the only session minter in production, EVERY
- * BA-shaped cookie hit both fallbacks' shape gate and failed structurally.
- * That meant any single BA-primary miss (secondary-storage eviction,
- * in-flight secret divergence, cookie-cache disabled) had no working
- * fallback at all — a single cookie's failure read as total session death
- * instead of degrading to one clean Redis-canonical lookup (or a genuine
- * 401 if the record really is gone).
- *
- * No signature is verified here, and none CAN be: this module is secret-free
- * and synchronous. It only CLASSIFIES and recovers the candidate token.
- *
- * PAY-1476: the earlier claim that "Redis is the liveness authority, so a
- * forged token still has to land on a live session record" was the defect.
- * A LEAKED token lands on a live record by definition, so without a signature
- * check the token string alone was a bearer credential. The candidate token
- * returned here must NEVER be handed to the session store directly: go through
- * server/verified-session-token.ts resolveVerifiedSessionToken, which verifies
- * the HMAC (ba-hmac) or the JWS signature first.
- */
-
-export type SessionCookieShape = 'jws' | 'ba-hmac';
-
-export interface ExtractedSessionToken {
-  token: string;
-  shape: SessionCookieShape;
-}
-
-/**
- * Extract a candidate session token from a raw session-cookie value,
- * regardless of which minter produced it.
- *
- * Returns null if the value doesn't match either known shape, or (for the
- * JWS shape) if the payload segment doesn't decode to a `sessionToken`
- * claim.
- */
-export function extractSessionTokenFromCookieValue(rawValue: string | null | undefined): ExtractedSessionToken | null {
-  if (!rawValue) return null;
-
-  const segments = rawValue.split('.');
-
-  if (segments.length === 3) {
-    // JWS shape: base64-decode the payload segment (part 1), read the
-    // sessionToken claim. No signature check — see file header.
-    try {
-      const decoded = Buffer.from(segments[1], 'base64').toString('utf-8');
-      const payload = JSON.parse(decoded);
-      if (payload && typeof payload === 'object' && typeof payload.sessionToken === 'string') {
-        return { token: payload.sessionToken, shape: 'jws' };
-      }
-    } catch {
-      // fall through to null
-    }
-    return null;
-  }
-
-  if (segments.length === 2 && segments[0] && segments[1]) {
-    // BA-hmac shape: `{token}.{base64(hmac)}` — the token is the first
-    // segment verbatim, no decoding required.
-    return { token: segments[0], shape: 'ba-hmac' };
-  }
-
-  return null;
-}
-
-/** The RAW session-cookie value from a Request, WITHOUT going through Better
- *  Auth's `auth.api.getSession()`. Handles single and chunked cookies (Better
- *  Auth chunks long values across `{name}.0`, `{name}.1`, …) and every name the
- *  cookie is minted under (240654).
- *
- *  PAY-1476: this used to be `extractSessionTokenFromCookie`, which returned the
- *  TOKEN with "No signature check — Redis is the liveness gate". That turned any
- *  leaked token into a bearer credential. It now returns the raw value only, so
- *  the one way to get a token out of a request cookie is
- *  server/verified-session-token.ts resolveVerifiedSessionTokenFromRequest.
- *  Returns null if no session cookie is present. */
-export function extractSessionCookieValue(request: Request): string | null {
-  const cookieHeader = request.headers.get('cookie');
-  if (!cookieHeader) return null;
-
-  // 240654: read EVERY name this session cookie is minted under, not just the
-  // bare one.
-  //
-  // getSessionCookieName() is ALWAYS `{slug}.session-token`. But the package's
-  // own read contract is getJwtCookieName() — "the cookie name that getToken()
-  // should use to READ" — and in production that resolves to the
-  // `__Secure-`-prefixed name. The admin-login door (238225) mints the legacy
-  // JWS session under the __Secure- name in prod, exactly per that contract.
-  //
-  // So this resolver — the Path-B fallback, and the ONLY resolver for legacy
-  // JWS sessions — could not see a production session at all. Measured live on
-  // portal.keelauth.com: the session was minted and present in Redis at
-  // `idp_admin_ui_graft:sess:{token}`, yet invisible to viability and
-  // middleware, so every page bounced to /sign-in. Dev survived because in
-  // development both helpers return the SAME string, which is precisely why
-  // the dev-93 walks passed while prod died.
-  //
-  // Checking BOTH names rather than just swapping to getJwtCookieName(): the
-  // graft currently double-writes both cookie names as an app-local mitigation
-  // (graft 8a5ac21), and a rollout necessarily spans sessions minted under
-  // either name. Reading both is correct before, during and after that
-  // double-write is retired, and costs one extra map lookup.
-  const candidateNames = Array.from(
-    new Set([getJwtCookieName(), getSecureSessionCookieName(), getSessionCookieName()]),
-  );
-
-  // Parse the header ONCE, then resolve per candidate. Chunked cookies are
-  // kept per-name: Better Auth splits long values across `{name}.0/.1/.2…`,
-  // and chunks from different cookie names must never be concatenated.
-  const direct = new Map<string, string>();
-  const chunksByName = new Map<string, Array<{ idx: number; value: string }>>();
-
-  for (const part of cookieHeader.split(';')) {
-    const trimmed = part.trim();
-    const eq = trimmed.indexOf('=');
-    if (eq === -1) continue;
-    const k = trimmed.slice(0, eq);
-    const v = trimmed.slice(eq + 1);
-
-    for (const name of candidateNames) {
-      if (k === name) {
-        if (!direct.has(name)) direct.set(name, decodeURIComponent(v));
-        break;
-      }
-      if (k.startsWith(`${name}.`)) {
-        const idx = parseInt(k.split('.').pop() || '0', 10);
-        if (Number.isFinite(idx)) {
-          const list = chunksByName.get(name) ?? [];
-          list.push({ idx, value: decodeURIComponent(v) });
-          chunksByName.set(name, list);
-        }
-        break;
-      }
-    }
-  }
-
-  let rawJwt: string | null = null;
-  for (const name of candidateNames) {
-    const whole = direct.get(name);
-    if (whole) {
-      rawJwt = whole;
-      break;
-    }
-    const parts = chunksByName.get(name);
-    if (parts && parts.length > 0) {
-      parts.sort((a, b) => a.idx - b.idx);
-      rawJwt = parts.map(c => c.value).join('');
-      break;
-    }
-  }
-
-  return rawJwt || null;
-}
+import {
+  getJwtCookieName,
+  getSecureSessionCookieName,
+  getSessionCookieName,
+} from './app-slug';
+
+/**
+ * Session-cookie SHAPE detection — shared by every fallback path that must
+ * recover a Redis session token from a raw session-cookie value without
+ * going through Better Auth's `auth.api.getSession()`.
+ *
+ * WHY THIS EXISTS (183047 post-mortem, BAPert/QAPert/Scout, 2026-08-08):
+ *
+ * Two cookie shapes exist in this codebase's history, and until now no
+ * fallback path recognized both:
+ *
+ *  - JWS (3 dot-separated segments): the legacy NextAuth-era format. The
+ *    session token lives in the payload's `sessionToken` claim, base64-JSON
+ *    encoded in the middle segment.
+ *  - BA-hmac (2 segments — exactly ONE dot): Better Auth's own hand-rolled
+ *    cookie, `{token}.{base64(hmac)}` (see better-auth.ts's
+ *    CreateBetterAuthInstanceOptions.plugins doc comment). The token here
+ *    IS the first segment verbatim — there is no claim to decode.
+ *
+ * Every fallback that existed before this file assumed the JWS shape
+ * unconditionally:
+ *  - decode-session.ts's legacy path called jose's `jwtVerify()` directly on
+ *    the cookie value. `jwtVerify` requires a genuine compact JWS and throws
+ *    "Invalid Compact JWS" on a 2-segment value — secret-independent, before
+ *    any signature is even checked.
+ *  - auth.ts's `decodeJwtBody()` required `parts.length === 3` and returned
+ *    null otherwise.
+ *
+ * Since Better Auth is the only session minter in production, EVERY
+ * BA-shaped cookie hit both fallbacks' shape gate and failed structurally.
+ * That meant any single BA-primary miss (secondary-storage eviction,
+ * in-flight secret divergence, cookie-cache disabled) had no working
+ * fallback at all — a single cookie's failure read as total session death
+ * instead of degrading to one clean Redis-canonical lookup (or a genuine
+ * 401 if the record really is gone).
+ *
+ * No signature is verified here, and none CAN be: this module is secret-free
+ * and synchronous. It only CLASSIFIES and recovers the candidate token.
+ *
+ * PAY-1476: the earlier claim that "Redis is the liveness authority, so a
+ * forged token still has to land on a live session record" was the defect.
+ * A LEAKED token lands on a live record by definition, so without a signature
+ * check the token string alone was a bearer credential. The candidate token
+ * returned here must NEVER be handed to the session store directly: go through
+ * server/verified-session-token.ts resolveVerifiedSessionToken, which verifies
+ * the HMAC (ba-hmac) or the JWS signature first.
+ */
+
+export type SessionCookieShape = 'jws' | 'ba-hmac';
+
+export interface ExtractedSessionToken {
+  token: string;
+  shape: SessionCookieShape;
+}
+
+/**
+ * Extract a candidate session token from a raw session-cookie value,
+ * regardless of which minter produced it.
+ *
+ * Returns null if the value doesn't match either known shape, or (for the
+ * JWS shape) if the payload segment doesn't decode to a `sessionToken`
+ * claim.
+ */
+export function extractSessionTokenFromCookieValue(rawValue: string | null | undefined): ExtractedSessionToken | null {
+  if (!rawValue) return null;
+
+  const segments = rawValue.split('.');
+
+  if (segments.length === 3) {
+    // JWS shape: base64-decode the payload segment (part 1), read the
+    // sessionToken claim. No signature check — see file header.
+    try {
+      const decoded = Buffer.from(segments[1], 'base64').toString('utf-8');
+      const payload = JSON.parse(decoded);
+      if (payload && typeof payload === 'object' && typeof payload.sessionToken === 'string') {
+        return { token: payload.sessionToken, shape: 'jws' };
+      }
+    } catch {
+      // fall through to null
+    }
+    return null;
+  }
+
+  if (segments.length === 2 && segments[0] && segments[1]) {
+    // BA-hmac shape: `{token}.{base64(hmac)}` — the token is the first
+    // segment verbatim, no decoding required.
+    return { token: segments[0], shape: 'ba-hmac' };
+  }
+
+  return null;
+}
+
+/** The RAW session-cookie value from a Request, WITHOUT going through Better
+ *  Auth's `auth.api.getSession()`. Handles single and chunked cookies (Better
+ *  Auth chunks long values across `{name}.0`, `{name}.1`, …) and every name the
+ *  cookie is minted under (240654).
+ *
+ *  PAY-1476: this used to be `extractSessionTokenFromCookie`, which returned the
+ *  TOKEN with "No signature check — Redis is the liveness gate". That turned any
+ *  leaked token into a bearer credential. It now returns the raw value only, so
+ *  the one way to get a token out of a request cookie is
+ *  server/verified-session-token.ts resolveVerifiedSessionTokenFromRequest.
+ *  Returns null if no session cookie is present. */
+export function extractSessionCookieValue(request: Request): string | null {
+  const cookieHeader = request.headers.get('cookie');
+  if (!cookieHeader) return null;
+
+  // 240654: read EVERY name this session cookie is minted under, not just the
+  // bare one.
+  //
+  // getSessionCookieName() is ALWAYS `{slug}.session-token`. But the package's
+  // own read contract is getJwtCookieName() — "the cookie name that getToken()
+  // should use to READ" — and in production that resolves to the
+  // `__Secure-`-prefixed name. The admin-login door (238225) mints the legacy
+  // JWS session under the __Secure- name in prod, exactly per that contract.
+  //
+  // So this resolver — the Path-B fallback, and the ONLY resolver for legacy
+  // JWS sessions — could not see a production session at all. Measured live on
+  // portal.keelauth.com: the session was minted and present in Redis at
+  // `idp_admin_ui_graft:sess:{token}`, yet invisible to viability and
+  // middleware, so every page bounced to /sign-in. Dev survived because in
+  // development both helpers return the SAME string, which is precisely why
+  // the dev-93 walks passed while prod died.
+  //
+  // Checking BOTH names rather than just swapping to getJwtCookieName(): the
+  // graft currently double-writes both cookie names as an app-local mitigation
+  // (graft 8a5ac21), and a rollout necessarily spans sessions minted under
+  // either name. Reading both is correct before, during and after that
+  // double-write is retired, and costs one extra map lookup.
+  const candidateNames = Array.from(
+    new Set([getJwtCookieName(), getSecureSessionCookieName(), getSessionCookieName()]),
+  );
+
+  // Parse the header ONCE, then resolve per candidate. Chunked cookies are
+  // kept per-name: Better Auth splits long values across `{name}.0/.1/.2…`,
+  // and chunks from different cookie names must never be concatenated.
+  const direct = new Map<string, string>();
+  const chunksByName = new Map<string, Array<{ idx: number; value: string }>>();
+
+  for (const part of cookieHeader.split(';')) {
+    const trimmed = part.trim();
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const k = trimmed.slice(0, eq);
+    const v = trimmed.slice(eq + 1);
+
+    for (const name of candidateNames) {
+      if (k === name) {
+        if (!direct.has(name)) direct.set(name, decodeURIComponent(v));
+        break;
+      }
+      if (k.startsWith(`${name}.`)) {
+        const idx = parseInt(k.split('.').pop() || '0', 10);
+        if (Number.isFinite(idx)) {
+          const list = chunksByName.get(name) ?? [];
+          list.push({ idx, value: decodeURIComponent(v) });
+          chunksByName.set(name, list);
+        }
+        break;
+      }
+    }
+  }
+
+  let rawJwt: string | null = null;
+  for (const name of candidateNames) {
+    const whole = direct.get(name);
+    if (whole) {
+      rawJwt = whole;
+      break;
+    }
+    const parts = chunksByName.get(name);
+    if (parts && parts.length > 0) {
+      parts.sort((a, b) => a.idx - b.idx);
+      rawJwt = parts.map(c => c.value).join('');
+      break;
+    }
+  }
+
+  return rawJwt || null;
+}