@payez/next-mvp 4.8.0 → 4.8.2

package/src/server/decode-session.ts

@@ -1,309 +1,309 @@
-/**
- * Server-Side Session Decoder
- *
- * Uses Better Auth's server-side session API to get the current session.
- * Falls back to legacy JWT + Redis path if Better Auth session not found.
- */
-
-import 'server-only';
-import { cookies } from 'next/headers';
-import { type JWTPayload } from 'jose';
-import { getSession, type SessionData } from '../lib/session-store';
-import { getIDPClientConfig } from '../lib/idp-client-config';
-import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
-import { ensureInitialized } from '../lib/startup-init';
-import { extractSessionTokenFromCookieValue } from '../lib/session-cookie-shape';
-import { resolveVerifiedSessionCookie } from './verified-session-token';
-import { tokenLogId } from '../lib/token-log-id';
-
-export interface DecodedSession {
-  sessionData: SessionData;
-  jwtPayload: JWTPayload & { sessionToken?: string; redisSessionId?: string };
-}
-
-/**
- * Try Better Auth's server-side session API.
- * Returns a DecodedSession if Better Auth has an active session, null otherwise.
- */
-async function tryBetterAuthSession(
-  requestCookies?: { get: (name: string) => { value: string } | undefined }
-): Promise<DecodedSession | null> {
-  try {
-    const { getBetterAuthInstance } = await import('../auth/better-auth');
-
-    let auth: any = null;
-    try {
-      auth = await getBetterAuthInstance();
-    } catch {
-      return null;
-    }
-
-    if (!auth?.api?.getSession) {
-      return null;
-    }
-
-    // Build headers from cookies for Better Auth to read
-    const cookieStore = requestCookies || (await cookies());
-    const headerObj = new Headers();
-
-    // Collect all cookies into a Cookie header
-    if ('getAll' in cookieStore && typeof cookieStore.getAll === 'function') {
-      const allCookies = (cookieStore as any).getAll();
-      const cookieStr = allCookies.map((c: any) => `${c.name}=${c.value}`).join('; ');
-      headerObj.set('cookie', cookieStr);
-    } else {
-      // Fallback: read known cookie names
-      const sessionCookieName = getSessionCookieName();
-      const secureCookieName = getSecureSessionCookieName();
-      const parts: string[] = [];
-      const sc = cookieStore.get(secureCookieName);
-      if (sc?.value) parts.push(`${secureCookieName}=${sc.value}`);
-      const nc = cookieStore.get(sessionCookieName);
-      if (nc?.value) parts.push(`${sessionCookieName}=${nc.value}`);
-      if (parts.length > 0) headerObj.set('cookie', parts.join('; '));
-    }
-
-    const result = await auth.api.getSession({ headers: headerObj });
-
-    if (!result?.session || !result?.user) {
-      return null;
-    }
-
-    // Read IDP tokens from BA Redis session (stored by callback route after OAuth)
-    let idpTokens: any = null;
-    try {
-      const { getRedis } = await import('../lib/redis');
-      const { getAppSlug } = await import('../lib/app-slug');
-      // KEY-COMPOSER MISMATCH FIX (2026-08-02).
-      // better-auth writes this key as `ba:${idpConfig.clientSlug || getAppSlug()}:...`
-      // (better-auth.ts:99). This reader used getAppSlug() ALONE, so on any
-      // deployment where the IDP returns a clientSlug that differs from
-      // APP_SLUG the lookup missed entirely: idpTokens stayed null, and every
-      // caller looked unauthenticated regardless of their real session.
-      // Observed live: writer produced ba:idp_admin_ui_graft:<token> while this
-      // reader asked for ba:payez_idp_admin_web:<token>.
-      //
-      // Try the writer's composition FIRST, then the original as a fallback.
-      // Additive on purpose: it can only ever find MORE sessions than before,
-      // so no consumer whose keys already resolved can regress.
-      let baRaw: string | null = null;
-      try {
-        const idpCfg = await getIDPClientConfig();
-        const writerSlug = (idpCfg as { clientSlug?: string } | null)?.clientSlug;
-        if (writerSlug) {
-          baRaw = await getRedis().get(`ba:${writerSlug}:${result.session.token}`);
-        }
-      } catch { /* config unavailable — fall through to the legacy key */ }
-      if (!baRaw) {
-        baRaw = await getRedis().get(`ba:${getAppSlug()}:${result.session.token}`);
-      }
-      if (baRaw) {
-        const baData = JSON.parse(baRaw);
-        idpTokens = baData.idpTokens;
-      }
-    } catch { /* Redis unavailable */ }
-
-    // LEG-1 FAIL-CLOSED ON UNUSABLE ROLES (card 340015, BAPert R412, 2026-09-03).
-    //
-    // `idpTokens.roles` is the ONLY source of roles for every role-gated route
-    // (see :109 below). When it is empty this leg used to return a perfectly
-    // valid-LOOKING session carrying `roles: []` — so the caller was
-    // authenticated but authorised for nothing. Every admin screen 403s and
-    // renders its chrome with no data and NO ERROR TEXT: it does not look
-    // broken, it looks empty.
-    //
-    // Three independent causes produce that state, so the test is on the
-    // CONDITION THAT ACTUALLY HARMS — "no usable roles" — rather than on any
-    // one route to it. A fourth cause is then covered for free:
-    //   A  MINT        the password / admin-login lane never writes the block
-    //                  (it never calls storeIdpTokensInSession), so it is
-    //                  absent from birth.
-    //   B  CLOBBER     better-auth's own 24h session refresh rebuilds the
-    //                  `ba:` record as `{session, user}` and drops the
-    //                  `idpTokens` SIBLING structurally, not conditionally
-    //                  (better-auth internal-adapter.mjs:287). This hits the
-    //                  OAuth and passkey lanes too — they are safe for 24
-    //                  hours and then stop being safe.
-    //   C  DERIVATION  the block is PRESENT and fully populated with only
-    //                  `roles` empty (card 339748). `!idpTokens` is FALSE
-    //                  here and cannot see it — which is exactly why the
-    //                  predicate is `!idpTokens?.roles?.length` and not an
-    //                  absence check.
-    //
-    // Declining here hands the request to the legacy `{slug}:sess:` leg below,
-    // which carries the same roles. *** IF THAT RECORD IS ALSO ABSENT THE USER
-    // IS SIGNED OUT. THAT IS DELIBERATE AND ACCEPTED, NOT A REGRESSION *** —
-    // an honest, visible sign-out in place of a silently half-authorised
-    // session. Read the commit message before treating a sign-out here as a
-    // bug introduced by this fix.
-    if (!idpTokens?.roles?.length) {
-      console.warn(
-        '[DECODE-SESSION] Leg 1 declining: idpTokens unusable (no roles) for session',
-        tokenLogId(result.session.token),
-        '— falling through to the sess: leg'
-      );
-      return null;
-    }
-
-    // Map Better Auth session + IDP tokens to SessionData
-    const sessionData: SessionData = {
-      userId: idpTokens?.userId || result.user.id || '',
-      email: idpTokens?.email || result.user.email || '',
-      name: idpTokens?.name || result.user.name || undefined,
-      roles: idpTokens?.roles || [],
-      idpAccessToken: idpTokens?.idpAccessToken,
-      idpRefreshToken: idpTokens?.idpRefreshToken,
-      idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
-        || (result.session.expiresAt ? new Date(result.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
-      mfaVerified: idpTokens?.mfaVerified ?? false,
-      // R807 (362550): fail-closed collapse above stays; this preserves the bit it
-      // destroys. Explicit `false` counts as a signal - hence `!== undefined`.
-      mfaSignalPresent: idpTokens?.mfaVerified !== undefined,
-      /**
-       * ⚠ WAS HARDCODED `'google'` — third site of QAPert finding #3 (card
-       * 167892), found by sweeping rather than by report.
-       *
-       * Note the line ABOVE is already honest: mfaVerified derives from what
-       * was stored. This one asserted the provider anyway, so a passkey
-       * sign-in decoded here was relabelled a Google OAuth sign-in — the
-       * provenance the sign-in path deliberately records, overwritten on read.
-       *
-       * The IDP emits NO provider claim (DotNetPert), so when it was not
-       * stored the honest answer is UNSET, not a guess.
-       */
-      oauthProvider: idpTokens?.oauthProvider ?? undefined,
-      idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId,
-      merchantId: idpTokens?.merchantId,
-    };
-
-    // Backwards compat: session.user.email works alongside session.email
-    (sessionData as any).user = {
-      id: sessionData.userId,
-      email: sessionData.email,
-      name: sessionData.name,
-      roles: sessionData.roles,
-      image: result.user.image,
-      oauthProvider: sessionData.oauthProvider,
-    };
-
-    const jwtPayload: DecodedSession['jwtPayload'] = {
-      sub: result.user.id,
-      email: result.user.email,
-      name: result.user.name,
-      iat: Math.floor(Date.now() / 1000),
-      exp: sessionData.idpAccessTokenExpires / 1000,
-      sessionToken: result.session.token,
-    };
-
-    return { sessionData, jwtPayload };
-  } catch (error) {
-    console.warn('[DECODE-SESSION] Better Auth session check failed:', error instanceof Error ? error.message : String(error));
-    return null;
-  }
-}
-
-/**
- * Decode the session from cookies.
- * Tries Better Auth first, falls back to legacy JWT + Redis.
- *
- * @param requestCookies Optional cookie getter for API route context (NextRequest.cookies).
- *                       If omitted, uses next/headers cookies() for server components.
- */
-export async function decodeSession(
-  requestCookies?: { get: (name: string) => { value: string } | undefined }
-): Promise<DecodedSession | null> {
-  try {
-    await ensureInitialized();
-
-    // Try Better Auth session first
-    const betterAuthSession = await tryBetterAuthSession(requestCookies);
-    if (betterAuthSession) {
-      return betterAuthSession;
-    }
-
-    // Fall back to legacy JWT + Redis path
-    const cookieStore = requestCookies || (await cookies());
-    const sessionCookieName = getSessionCookieName();
-    const secureCookieName = getSecureSessionCookieName();
-
-    const cookieValue =
-      cookieStore.get(secureCookieName)?.value ||
-      cookieStore.get(sessionCookieName)?.value;
-
-    if (!cookieValue) {
-      return null;
-    }
-
-    const config = await getIDPClientConfig();
-    const secret = config.authSecret;
-    if (!secret) {
-      console.error('[DECODE-SESSION] No authSecret available from IDP config');
-      return null;
-    }
-
-    // BA-SHAPE-AWARE FALLBACK LEG (183047, 2026-08-08).
-    //
-    // Better Auth mints session cookies as `{token}.{base64(hmac)}` — TWO
-    // segments, one dot. jose's `jwtVerify()` below requires a genuine
-    // compact JWS — THREE segments — and throws "Invalid Compact JWS" on a
-    // BA-shaped cookie unconditionally, before it ever looks at the secret.
-    // Since Better Auth is the only minter in production, that meant this
-    // fallback could never succeed for the cookies it actually receives: any
-    // single Better-Auth-primary miss (secondary-storage eviction, disabled
-    // cookie cache, in-flight secret divergence) read as total session
-    // death, because the ONLY fallback was structurally blind to the only
-    // shape it would ever be handed.
-    //
-    // PAY-1476: the shape still decides HOW to verify, but BOTH shapes are now
-    // verified, by the shared resolver. This branch used to take a BA-hmac
-    // cookie's token with no signature check ("Redis presence is the
-    // authority"), so `{leaked token}.{anything}` authenticated here - including
-    // behind the portal's admin API gate. The resolver checks the HMAC with
-    // timingSafeEqual (ba-hmac) or runs jwtVerify (jws) against the same
-    // env-first auth secret, and returns null on any failure.
-    const shaped = extractSessionTokenFromCookieValue(cookieValue);
-    const verified = await resolveVerifiedSessionCookie(cookieValue);
-    const sessionToken = verified?.token;
-    const payload: JWTPayload | undefined = verified?.payload;
-
-    if (!sessionToken) {
-      console.warn('[DECODE-SESSION] Session cookie did not verify (shape:', shaped?.shape ?? 'unrecognized', ')');
-      return null;
-    }
-
-    const sessionData = await getSession(sessionToken);
-    if (!sessionData) {
-      // The OTHER half of R412(ii). There are two ways decodeSession returns
-      // null and they mean different things, so they must not both be silent:
-      // Leg 1 declining is routine and recoverable (this leg normally holds
-      // the roles), whereas reaching HERE means there is no fallback record
-      // either and the caller is about to be signed out. Different meanings,
-      // different remediations — do not ship a second silent path while
-      // fixing a silent path.
-      console.warn(
-        '[DECODE-SESSION] No sess: record for token',
-        tokenLogId(sessionToken),
-        '— no fallback available, session will be signed out'
-      );
-      return null;
-    }
-
-    // Backwards compat: session.user.email works alongside session.email
-    if (!(sessionData as any).user) {
-      (sessionData as any).user = {
-        id: sessionData.userId,
-        email: sessionData.email,
-        name: sessionData.name,
-        roles: sessionData.roles,
-      };
-    }
-
-    return {
-      sessionData,
-      jwtPayload: (payload ?? { sessionToken }) as DecodedSession['jwtPayload'],
-    };
-  } catch (error) {
-    console.error('[DECODE-SESSION] Error:', error instanceof Error ? error.message : String(error));
-    return null;
-  }
-}
+/**
+ * Server-Side Session Decoder
+ *
+ * Uses Better Auth's server-side session API to get the current session.
+ * Falls back to legacy JWT + Redis path if Better Auth session not found.
+ */
+
+import 'server-only';
+import { cookies } from 'next/headers';
+import { type JWTPayload } from 'jose';
+import { getSession, type SessionData } from '../lib/session-store';
+import { getIDPClientConfig } from '../lib/idp-client-config';
+import { getSessionCookieName, getSecureSessionCookieName } from '../lib/app-slug';
+import { ensureInitialized } from '../lib/startup-init';
+import { extractSessionTokenFromCookieValue } from '../lib/session-cookie-shape';
+import { resolveVerifiedSessionCookie } from './verified-session-token';
+import { tokenLogId } from '../lib/token-log-id';
+
+export interface DecodedSession {
+  sessionData: SessionData;
+  jwtPayload: JWTPayload & { sessionToken?: string; redisSessionId?: string };
+}
+
+/**
+ * Try Better Auth's server-side session API.
+ * Returns a DecodedSession if Better Auth has an active session, null otherwise.
+ */
+async function tryBetterAuthSession(
+  requestCookies?: { get: (name: string) => { value: string } | undefined }
+): Promise<DecodedSession | null> {
+  try {
+    const { getBetterAuthInstance } = await import('../auth/better-auth');
+
+    let auth: any = null;
+    try {
+      auth = await getBetterAuthInstance();
+    } catch {
+      return null;
+    }
+
+    if (!auth?.api?.getSession) {
+      return null;
+    }
+
+    // Build headers from cookies for Better Auth to read
+    const cookieStore = requestCookies || (await cookies());
+    const headerObj = new Headers();
+
+    // Collect all cookies into a Cookie header
+    if ('getAll' in cookieStore && typeof cookieStore.getAll === 'function') {
+      const allCookies = (cookieStore as any).getAll();
+      const cookieStr = allCookies.map((c: any) => `${c.name}=${c.value}`).join('; ');
+      headerObj.set('cookie', cookieStr);
+    } else {
+      // Fallback: read known cookie names
+      const sessionCookieName = getSessionCookieName();
+      const secureCookieName = getSecureSessionCookieName();
+      const parts: string[] = [];
+      const sc = cookieStore.get(secureCookieName);
+      if (sc?.value) parts.push(`${secureCookieName}=${sc.value}`);
+      const nc = cookieStore.get(sessionCookieName);
+      if (nc?.value) parts.push(`${sessionCookieName}=${nc.value}`);
+      if (parts.length > 0) headerObj.set('cookie', parts.join('; '));
+    }
+
+    const result = await auth.api.getSession({ headers: headerObj });
+
+    if (!result?.session || !result?.user) {
+      return null;
+    }
+
+    // Read IDP tokens from BA Redis session (stored by callback route after OAuth)
+    let idpTokens: any = null;
+    try {
+      const { getRedis } = await import('../lib/redis');
+      const { getAppSlug } = await import('../lib/app-slug');
+      // KEY-COMPOSER MISMATCH FIX (2026-08-02).
+      // better-auth writes this key as `ba:${idpConfig.clientSlug || getAppSlug()}:...`
+      // (better-auth.ts:99). This reader used getAppSlug() ALONE, so on any
+      // deployment where the IDP returns a clientSlug that differs from
+      // APP_SLUG the lookup missed entirely: idpTokens stayed null, and every
+      // caller looked unauthenticated regardless of their real session.
+      // Observed live: writer produced ba:idp_admin_ui_graft:<token> while this
+      // reader asked for ba:payez_idp_admin_web:<token>.
+      //
+      // Try the writer's composition FIRST, then the original as a fallback.
+      // Additive on purpose: it can only ever find MORE sessions than before,
+      // so no consumer whose keys already resolved can regress.
+      let baRaw: string | null = null;
+      try {
+        const idpCfg = await getIDPClientConfig();
+        const writerSlug = (idpCfg as { clientSlug?: string } | null)?.clientSlug;
+        if (writerSlug) {
+          baRaw = await getRedis().get(`ba:${writerSlug}:${result.session.token}`);
+        }
+      } catch { /* config unavailable — fall through to the legacy key */ }
+      if (!baRaw) {
+        baRaw = await getRedis().get(`ba:${getAppSlug()}:${result.session.token}`);
+      }
+      if (baRaw) {
+        const baData = JSON.parse(baRaw);
+        idpTokens = baData.idpTokens;
+      }
+    } catch { /* Redis unavailable */ }
+
+    // LEG-1 FAIL-CLOSED ON UNUSABLE ROLES (card 340015, BAPert R412, 2026-09-03).
+    //
+    // `idpTokens.roles` is the ONLY source of roles for every role-gated route
+    // (see :109 below). When it is empty this leg used to return a perfectly
+    // valid-LOOKING session carrying `roles: []` — so the caller was
+    // authenticated but authorised for nothing. Every admin screen 403s and
+    // renders its chrome with no data and NO ERROR TEXT: it does not look
+    // broken, it looks empty.
+    //
+    // Three independent causes produce that state, so the test is on the
+    // CONDITION THAT ACTUALLY HARMS — "no usable roles" — rather than on any
+    // one route to it. A fourth cause is then covered for free:
+    //   A  MINT        the password / admin-login lane never writes the block
+    //                  (it never calls storeIdpTokensInSession), so it is
+    //                  absent from birth.
+    //   B  CLOBBER     better-auth's own 24h session refresh rebuilds the
+    //                  `ba:` record as `{session, user}` and drops the
+    //                  `idpTokens` SIBLING structurally, not conditionally
+    //                  (better-auth internal-adapter.mjs:287). This hits the
+    //                  OAuth and passkey lanes too — they are safe for 24
+    //                  hours and then stop being safe.
+    //   C  DERIVATION  the block is PRESENT and fully populated with only
+    //                  `roles` empty (card 339748). `!idpTokens` is FALSE
+    //                  here and cannot see it — which is exactly why the
+    //                  predicate is `!idpTokens?.roles?.length` and not an
+    //                  absence check.
+    //
+    // Declining here hands the request to the legacy `{slug}:sess:` leg below,
+    // which carries the same roles. *** IF THAT RECORD IS ALSO ABSENT THE USER
+    // IS SIGNED OUT. THAT IS DELIBERATE AND ACCEPTED, NOT A REGRESSION *** —
+    // an honest, visible sign-out in place of a silently half-authorised
+    // session. Read the commit message before treating a sign-out here as a
+    // bug introduced by this fix.
+    if (!idpTokens?.roles?.length) {
+      console.warn(
+        '[DECODE-SESSION] Leg 1 declining: idpTokens unusable (no roles) for session',
+        tokenLogId(result.session.token),
+        '— falling through to the sess: leg'
+      );
+      return null;
+    }
+
+    // Map Better Auth session + IDP tokens to SessionData
+    const sessionData: SessionData = {
+      userId: idpTokens?.userId || result.user.id || '',
+      email: idpTokens?.email || result.user.email || '',
+      name: idpTokens?.name || result.user.name || undefined,
+      roles: idpTokens?.roles || [],
+      idpAccessToken: idpTokens?.idpAccessToken,
+      idpRefreshToken: idpTokens?.idpRefreshToken,
+      idpAccessTokenExpires: idpTokens?.idpAccessTokenExpires
+        || (result.session.expiresAt ? new Date(result.session.expiresAt).getTime() : Date.now() + 24 * 60 * 60 * 1000),
+      mfaVerified: idpTokens?.mfaVerified ?? false,
+      // R807 (362550): fail-closed collapse above stays; this preserves the bit it
+      // destroys. Explicit `false` counts as a signal - hence `!== undefined`.
+      mfaSignalPresent: idpTokens?.mfaVerified !== undefined,
+      /**
+       * ⚠ WAS HARDCODED `'google'` — third site of QAPert finding #3 (card
+       * 167892), found by sweeping rather than by report.
+       *
+       * Note the line ABOVE is already honest: mfaVerified derives from what
+       * was stored. This one asserted the provider anyway, so a passkey
+       * sign-in decoded here was relabelled a Google OAuth sign-in — the
+       * provenance the sign-in path deliberately records, overwritten on read.
+       *
+       * The IDP emits NO provider claim (DotNetPert), so when it was not
+       * stored the honest answer is UNSET, not a guess.
+       */
+      oauthProvider: idpTokens?.oauthProvider ?? undefined,
+      idpClientId: idpTokens?.idpClientId ?? idpTokens?.clientId,
+      merchantId: idpTokens?.merchantId,
+    };
+
+    // Backwards compat: session.user.email works alongside session.email
+    (sessionData as any).user = {
+      id: sessionData.userId,
+      email: sessionData.email,
+      name: sessionData.name,
+      roles: sessionData.roles,
+      image: result.user.image,
+      oauthProvider: sessionData.oauthProvider,
+    };
+
+    const jwtPayload: DecodedSession['jwtPayload'] = {
+      sub: result.user.id,
+      email: result.user.email,
+      name: result.user.name,
+      iat: Math.floor(Date.now() / 1000),
+      exp: sessionData.idpAccessTokenExpires / 1000,
+      sessionToken: result.session.token,
+    };
+
+    return { sessionData, jwtPayload };
+  } catch (error) {
+    console.warn('[DECODE-SESSION] Better Auth session check failed:', error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}
+
+/**
+ * Decode the session from cookies.
+ * Tries Better Auth first, falls back to legacy JWT + Redis.
+ *
+ * @param requestCookies Optional cookie getter for API route context (NextRequest.cookies).
+ *                       If omitted, uses next/headers cookies() for server components.
+ */
+export async function decodeSession(
+  requestCookies?: { get: (name: string) => { value: string } | undefined }
+): Promise<DecodedSession | null> {
+  try {
+    await ensureInitialized();
+
+    // Try Better Auth session first
+    const betterAuthSession = await tryBetterAuthSession(requestCookies);
+    if (betterAuthSession) {
+      return betterAuthSession;
+    }
+
+    // Fall back to legacy JWT + Redis path
+    const cookieStore = requestCookies || (await cookies());
+    const sessionCookieName = getSessionCookieName();
+    const secureCookieName = getSecureSessionCookieName();
+
+    const cookieValue =
+      cookieStore.get(secureCookieName)?.value ||
+      cookieStore.get(sessionCookieName)?.value;
+
+    if (!cookieValue) {
+      return null;
+    }
+
+    const config = await getIDPClientConfig();
+    const secret = config.authSecret;
+    if (!secret) {
+      console.error('[DECODE-SESSION] No authSecret available from IDP config');
+      return null;
+    }
+
+    // BA-SHAPE-AWARE FALLBACK LEG (183047, 2026-08-08).
+    //
+    // Better Auth mints session cookies as `{token}.{base64(hmac)}` — TWO
+    // segments, one dot. jose's `jwtVerify()` below requires a genuine
+    // compact JWS — THREE segments — and throws "Invalid Compact JWS" on a
+    // BA-shaped cookie unconditionally, before it ever looks at the secret.
+    // Since Better Auth is the only minter in production, that meant this
+    // fallback could never succeed for the cookies it actually receives: any
+    // single Better-Auth-primary miss (secondary-storage eviction, disabled
+    // cookie cache, in-flight secret divergence) read as total session
+    // death, because the ONLY fallback was structurally blind to the only
+    // shape it would ever be handed.
+    //
+    // PAY-1476: the shape still decides HOW to verify, but BOTH shapes are now
+    // verified, by the shared resolver. This branch used to take a BA-hmac
+    // cookie's token with no signature check ("Redis presence is the
+    // authority"), so `{leaked token}.{anything}` authenticated here - including
+    // behind the portal's admin API gate. The resolver checks the HMAC with
+    // timingSafeEqual (ba-hmac) or runs jwtVerify (jws) against the same
+    // env-first auth secret, and returns null on any failure.
+    const shaped = extractSessionTokenFromCookieValue(cookieValue);
+    const verified = await resolveVerifiedSessionCookie(cookieValue);
+    const sessionToken = verified?.token;
+    const payload: JWTPayload | undefined = verified?.payload;
+
+    if (!sessionToken) {
+      console.warn('[DECODE-SESSION] Session cookie did not verify (shape:', shaped?.shape ?? 'unrecognized', ')');
+      return null;
+    }
+
+    const sessionData = await getSession(sessionToken);
+    if (!sessionData) {
+      // The OTHER half of R412(ii). There are two ways decodeSession returns
+      // null and they mean different things, so they must not both be silent:
+      // Leg 1 declining is routine and recoverable (this leg normally holds
+      // the roles), whereas reaching HERE means there is no fallback record
+      // either and the caller is about to be signed out. Different meanings,
+      // different remediations — do not ship a second silent path while
+      // fixing a silent path.
+      console.warn(
+        '[DECODE-SESSION] No sess: record for token',
+        tokenLogId(sessionToken),
+        '— no fallback available, session will be signed out'
+      );
+      return null;
+    }
+
+    // Backwards compat: session.user.email works alongside session.email
+    if (!(sessionData as any).user) {
+      (sessionData as any).user = {
+        id: sessionData.userId,
+        email: sessionData.email,
+        name: sessionData.name,
+        roles: sessionData.roles,
+      };
+    }
+
+    return {
+      sessionData,
+      jwtPayload: (payload ?? { sessionToken }) as DecodedSession['jwtPayload'],
+    };
+  } catch (error) {
+    console.error('[DECODE-SESSION] Error:', error instanceof Error ? error.message : String(error));
+    return null;
+  }
+}