@tokenoftrust/storefront-runner 0.1.0

package/apps/storefront/src/lib/auth/brokerAssertion.ts

@@ -0,0 +1,136 @@
+/**
+ * Broker-assertion MINTER — the storefront half of the "staff proven by a signed
+ * assertion, not a plaintext field" contract (#8453, decision
+ * `staff-invite-proof-via-broker`).
+ *
+ * The earlier flow sent the signed-in staff email to tot20 as a PLAINTEXT
+ * `actorEmail`/`email` field and asked tot20 to trust it — a spoof: anything that
+ * can reach the operator endpoint could name any staff email. This module instead
+ * MINTS a short-lived, storefront-signed RS256 JWT (the "broker assertion") that
+ * PROVES the storefront asserts this staff actor. It is presented to tot20 in the
+ * `X-ToT-Broker-Assertion` header; tot20 verifies the signature (against the
+ * storefront's PUBLISHED public key) + replay (`jti`/`exp`) and derives the staff
+ * actor from the VERIFIED `sub` — never from an untrusted field.
+ *
+ * SERVER-SIDE ONLY. The RS256 PRIVATE key (`STOREFRONT_BROKER_PRIVATE_KEY_B64`)
+ * lives only in the Worker/server env and is used only here; it MUST NEVER reach
+ * the client bundle. Callers are the server-side API routes (they hold the
+ * verified `session.email`), which mint per call and hand the compact JWT to the
+ * tot20 client to attach as the header. The clients themselves never see the key.
+ *
+ * Mirrors the jose usage in `./identityToken.ts` (that module VERIFIES tot's
+ * ES256 assertion; this one SIGNS the storefront's RS256 assertion — the inverse
+ * direction of the same decoupled-authZ pattern).
+ */
+import { SignJWT, importPKCS8, type CryptoKey } from "jose";
+import { readEnv } from "@/lib/env";
+
+/** The audience tot20's broker verifier pins. */
+export const BROKER_AUDIENCE = "tot20-broker";
+
+/** The only algorithm the storefront broker signs with (tot20 rejects anything else). */
+export const BROKER_ALG = "RS256";
+
+/** Default key id (overridable via `STOREFRONT_BROKER_KID`). Names the published key. */
+export const DEFAULT_BROKER_KID = "storefront-qa-1";
+
+/** Default issuer (overridable via `STOREFRONT_BROKER_ISSUER`). */
+export const DEFAULT_BROKER_ISSUER = "storefront";
+
+/** Assertion lifetime — deliberately short (replay window). */
+export const BROKER_TTL_SECONDS = 300;
+
+/** Env keys the minter reads (server-only). */
+export const BROKER_PRIVATE_KEY_ENV = "STOREFRONT_BROKER_PRIVATE_KEY_B64";
+export const BROKER_KID_ENV = "STOREFRONT_BROKER_KID";
+export const BROKER_ISSUER_ENV = "STOREFRONT_BROKER_ISSUER";
+
+/**
+ * Thrown when the minter can't sign — the private key env is absent/malformed, or
+ * no subject was supplied. Routes map this to a 503 ("integration not configured")
+ * and FAIL CLOSED: with no proof of the staff actor, the staff call must not go out.
+ */
+export class BrokerAssertionError extends Error {}
+
+/** Optional test/DI overrides (avoids touching process env in unit tests). */
+export interface MintBrokerAssertionOverrides {
+  /** base64 of the PKCS8 PEM private key (defaults to the env value). */
+  privateKeyB64?: string;
+  kid?: string;
+  issuer?: string;
+}
+
+// Import the signing key once per distinct PEM (importPKCS8 is not free). Keyed on
+// the base64 string so a key rotation (new env value) transparently re-imports.
+const keyCache = new Map<string, CryptoKey>();
+
+async function loadSigningKey(privateKeyB64: string): Promise<CryptoKey> {
+  const cached = keyCache.get(privateKeyB64);
+  if (cached) return cached;
+  let pem: string;
+  try {
+    pem = Buffer.from(privateKeyB64, "base64").toString("utf8");
+  } catch (cause) {
+    throw new BrokerAssertionError(
+      "broker assertion: STOREFRONT_BROKER_PRIVATE_KEY_B64 is not valid base64 " +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  if (!/-----BEGIN (RSA )?PRIVATE KEY-----/.test(pem)) {
+    throw new BrokerAssertionError(
+      "broker assertion: decoded STOREFRONT_BROKER_PRIVATE_KEY_B64 is not a PEM private key",
+    );
+  }
+  let key: CryptoKey;
+  try {
+    key = (await importPKCS8(pem, BROKER_ALG)) as CryptoKey;
+  } catch (cause) {
+    throw new BrokerAssertionError(
+      "broker assertion: failed to import the RS256 private key " +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  keyCache.set(privateKeyB64, key);
+  return key;
+}
+
+/**
+ * Mint a fresh, storefront-signed broker assertion PROVING `subjectEmail` is the
+ * staff actor. Returns the compact RS256 JWT to place in `X-ToT-Broker-Assertion`.
+ *
+ * Claims: `{ iss, sub:<subjectEmail>, aud:'tot20-broker', jti:<uuid>, iat, exp:iat+300 }`.
+ * Header: `{ alg:'RS256', kid, typ:'JWT' }`.
+ *
+ * FAILS CLOSED: throws {@link BrokerAssertionError} when the private key env is
+ * absent/malformed or no subject is supplied — the caller must NOT fall back to an
+ * unproven call.
+ */
+export async function mintBrokerAssertion(
+  subjectEmail: string,
+  overrides: MintBrokerAssertionOverrides = {},
+): Promise<string> {
+  const sub = (subjectEmail ?? "").trim().toLowerCase();
+  if (!sub) {
+    throw new BrokerAssertionError("broker assertion: a subject email is required");
+  }
+  const privateKeyB64 = overrides.privateKeyB64 ?? (await readEnv(BROKER_PRIVATE_KEY_ENV));
+  if (!privateKeyB64) {
+    throw new BrokerAssertionError(
+      `broker assertion: ${BROKER_PRIVATE_KEY_ENV} is not configured (fail closed)`,
+    );
+  }
+  const kid = overrides.kid ?? (await readEnv(BROKER_KID_ENV)) ?? DEFAULT_BROKER_KID;
+  const issuer = overrides.issuer ?? (await readEnv(BROKER_ISSUER_ENV)) ?? DEFAULT_BROKER_ISSUER;
+
+  const key = await loadSigningKey(privateKeyB64);
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  return new SignJWT({})
+    .setProtectedHeader({ alg: BROKER_ALG, kid, typ: "JWT" })
+    .setIssuer(issuer)
+    .setSubject(sub)
+    .setAudience(BROKER_AUDIENCE)
+    .setJti(crypto.randomUUID())
+    .setIssuedAt(nowSeconds)
+    .setExpirationTime(nowSeconds + BROKER_TTL_SECONDS)
+    .sign(key);
+}

package/apps/storefront/src/lib/auth/devAuth.ts

@@ -0,0 +1,90 @@
+/**
+ * Local dev auth — the SINGLE, auditable home for the localhost sign-in bypass.
+ *
+ * On localhost tot20 isn't reachable, so real sign-in/invite emails can't be sent
+ * or verified. This module lets a developer complete sign-in locally: `/api/auth/send`
+ * prints a one-time code to the server console + stores it here; `/api/auth/verify`
+ * consumes it and mints a session WITHOUT tot20/JWKS.
+ *
+ * SECURITY — this must never exist in a deployed build:
+ *   1. EVERY call site MUST wrap use in `if (import.meta.env.DEV)`. That is a STATIC
+ *      boolean Vite/Astro evaluates at build time, so the whole branch (and this
+ *      module's imports) are dead-code-eliminated from the production bundle — the
+ *      same mechanism the middleware dev guards rely on.
+ *   2. `devAuthEnabled()` adds a runtime opt-in (`DEV_AUTH=1` in `.dev.vars`) so even
+ *      a local dev build does nothing unless the developer explicitly turned it on.
+ * Keeping the bypass in one file means "does prod contain the bypass?" is a single
+ * grep (`devAuth`), and the production path in send/verify is never weakened.
+ */
+import { readEnv } from "@/lib/env";
+import { devTenantResources } from "@/config/devTenants";
+import { createSession } from "./session.js";
+
+/** SESSION-KV key prefix for the one-time dev code (distinct from `authsession:`). */
+export const DEV_AUTH_CODE_PREFIX = "devauthcode:";
+/** Dev code lifetime (KV clamps expirationTtl to >= 60). */
+export const DEV_AUTH_CODE_TTL_SECONDS = 600;
+
+/** Minimal KV seam (the `SESSION` binding). */
+interface CodeKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+/**
+ * Runtime opt-in. Call ONLY inside `if (import.meta.env.DEV)` so the whole thing is
+ * tree-shaken from prod regardless of any env var.
+ */
+export async function devAuthEnabled(): Promise<boolean> {
+  return (await readEnv("DEV_AUTH")) === "1";
+}
+
+/** A 6-digit numeric one-time code (WebCrypto). */
+export function devAuthCode(): string {
+  const n = new Uint32Array(1);
+  crypto.getRandomValues(n);
+  return String((n[0] ?? 0) % 1_000_000).padStart(6, "0");
+}
+
+/** Store a freshly-minted code for `email`. */
+export async function storeDevCode(kv: CodeKv, email: string, code: string): Promise<void> {
+  await kv.put(`${DEV_AUTH_CODE_PREFIX}${email}`, code, {
+    expirationTtl: DEV_AUTH_CODE_TTL_SECONDS,
+  });
+}
+
+/**
+ * One-time consume: returns true iff `code` matches the stored code for `email`,
+ * deleting it on success so a code can't be replayed.
+ */
+export async function consumeDevCode(kv: CodeKv, email: string, code: string): Promise<boolean> {
+  const stored = await kv.get(`${DEV_AUTH_CODE_PREFIX}${email}`);
+  if (!stored || stored !== code) return false;
+  await kv.delete(`${DEV_AUTH_CODE_PREFIX}${email}`);
+  return true;
+}
+
+/**
+ * Session fields for a local dev sign-in (option (c)): membership on EVERY registered
+ * tenant AND a staff scope, so the dashboard picker, every tenant, and the staff
+ * (any-tenant) paths are all exercisable locally. `resource` mirrors the real path's
+ * verified `aud` (the storefront app identity, `STOREFRONT_APP_DOMAIN`).
+ */
+export async function devSessionFields(
+  email: string,
+): Promise<Parameters<typeof createSession>[1]> {
+  const resource = (await readEnv("STOREFRONT_APP_DOMAIN")) || "storefront";
+  const tenants = devTenantResources().map((resource) => ({
+    resource,
+    role: "developer",
+  }));
+  return {
+    email: email.toLowerCase(),
+    resource,
+    roles: [],
+    capability: "member",
+    tenants,
+    staff: ["staff"],
+  };
+}

package/apps/storefront/src/lib/auth/gatePage.ts

@@ -0,0 +1,81 @@
+/**
+ * "Coming soon" holding page served to UNAUTHENTICATED visitors of a login-gated
+ * tenant (every non-self tenant on a gated host — see `loginGate.ts`).
+ *
+ * Instead of hard-redirecting to /auth/login, we serve a friendly holding page
+ * that withholds the tenant's content but offers a Sign-in button. The button
+ * carries the same `?next=` destination the gate would have redirected to, so a
+ * successful sign-in lands the visitor back where they started.
+ *
+ * The platform's own home ("self") tenant is exempt and never sees this — it
+ * renders publicly so people can browse + sign up.
+ */
+
+/** Escape a string for safe interpolation into an HTML attribute value. */
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function gatedHoldingHtml(loginHref: string): string {
+  const href = escapeAttr(loginHref);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex, nofollow" />
+<title>Coming soon</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100%; padding: 2rem;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+    background: radial-gradient(1200px 800px at 50% -10%, #1e293b, #0f172a 60%, #020617);
+    color: #e2e8f0;
+  }
+  main { max-width: 34rem; text-align: center; }
+  .badge {
+    display: inline-block; letter-spacing: .18em; text-transform: uppercase;
+    font-size: .72rem; font-weight: 600; color: #94a3b8;
+    border: 1px solid rgba(148,163,184,.35); border-radius: 999px;
+    padding: .35rem .8rem; margin-bottom: 1.75rem;
+  }
+  h1 { font-size: clamp(2rem, 6vw, 3rem); line-height: 1.1; margin: 0 0 1rem; color: #f8fafc; }
+  p { font-size: 1.05rem; line-height: 1.6; color: #cbd5e1; margin: 0 auto 2rem; max-width: 28rem; }
+  a.btn {
+    display: inline-block; text-decoration: none; font-weight: 600; font-size: 1rem;
+    color: #04121f; background: #38bdf8; border-radius: 10px; padding: .8rem 1.6rem;
+    transition: background .15s ease;
+  }
+  a.btn:hover { background: #7dd3fc; }
+</style>
+</head>
+<body>
+  <main>
+    <span class="badge">Token of Trust</span>
+    <h1>Coming soon</h1>
+    <p>This storefront isn't open to the public yet. If you have access, sign in to preview it.</p>
+    <a class="btn" href="${href}">Sign in</a>
+  </main>
+</body>
+</html>`;
+}
+
+/** A `200 OK` holding page — never indexed, never cached. */
+export function gatedHoldingResponse(loginHref: string): Response {
+  return new Response(gatedHoldingHtml(loginHref), {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}

package/apps/storefront/src/lib/auth/identityToken.ts

@@ -0,0 +1,341 @@
+/**
+ * Offline verification of tot's identity assertion (`id_token`) — the consuming
+ * half of the decoupled-authZ architecture (Phase 3).
+ *
+ * tot signs a short-lived ES256 assertion ONCE at sign-in with its PRIVATE key
+ * (`/api/internal/access-code/verify` → `id_token`). This module verifies it
+ * OFFLINE using tot's published JWKS (fetched once, cached, key-selected by
+ * `kid`) and derives the storefront session from the VERIFIED claims — no shared
+ * secret, no per-request callback to tot. Removing tot's network reachability
+ * after sign-in must not break authorization; the token's own `exp` bounds
+ * staleness.
+ *
+ * This mirrors the Phase-2 launchpad kernel's lightweight offline verifier
+ * (`launchpad src/modules/authz/jwks-verifier.ts` + `identity-claims.ts`) and the
+ * tot-internal verify path proven in
+ * `tot20 services/InternalAuthService/identityTokenService.jest.js`.
+ *
+ * PROTOTYPE SCOPE: this replicates ONLY the JWKS offline-verify + a coarse
+ * claims→session derivation. The full Cedar PDP (`can()` policy engine, staff
+ * sandbox) and consuming the launchpad kernel as an installed package are
+ * Phase 4 — see branch `feat/authz-cedar-kernel`. Do NOT vendor the Cedar-wasm
+ * PDP into the Worker; it is unnecessary for the current coarse gate.
+ *
+ * Contract: /tmp/authz-token-claims-contract.md (AS-BUILT). Key points mirrored
+ * here: §2 (ES256 + jose), §3 (claim set), §5 (consumer verify algorithm),
+ * §6 (field name `id_token`), §6b (JWKS host is per-env app config; jose
+ * cross-version 4↔6 is wire-compatible by construction).
+ */
+import {
+  jwtVerify,
+  createRemoteJWKSet,
+  createLocalJWKSet,
+  decodeProtectedHeader,
+  type JWTVerifyGetKey,
+  type JSONWebKeySet,
+} from "jose";
+import { readEnv } from "@/lib/env";
+
+/** tot's issuer — consumers pin/allowlist this (`auth.jwt.issuer`). */
+export const TOT_ISSUER = "tokenoftrust-internal-ops";
+
+/** The only signing algorithm tot uses. Consumers MUST reject anything else. */
+export const TOT_ALG = "ES256";
+
+/**
+ * JWKS path (host is per-env app config — §6b). Contract also serves
+ * `/api/internal/auth/jwks`; the well-known path is the canonical one.
+ */
+export const JWKS_PATH = "/api/.well-known/jwks.json";
+
+/**
+ * Coarse tenant role, collapsed by tot from its per-tenant capability
+ * (`developer`/`inviter`/none → `member`). Org standing only; finer granularity
+ * is the storefront's own job to derive locally (Phase-4 PDP work).
+ */
+export type CoarseRole = "owner" | "admin" | "member";
+
+/** A single tenant membership carried in the assertion. */
+export interface TenantMembership {
+  resource: string;
+  role: CoarseRole;
+}
+
+/**
+ * The verified identity assertion payload (tot-authoritative + registered
+ * claims). Everything here is an INPUT to the storefront's policy, not a
+ * decision. Mirrors the launchpad kernel's `IdentityClaims`.
+ */
+export interface IdentityClaims {
+  // Registered claims
+  iss: string;
+  sub: string;
+  aud: string;
+  iat: number;
+  exp: number;
+  jti?: string;
+  // tot-authoritative claims
+  email: string;
+  /** Baseline verification signal today (email control proven at sign-in). */
+  email_verified: boolean;
+  tenants: TenantMembership[];
+  /**
+   * ToT-staff cross-domain scope (present for ToT staff). CARRIED as a principal
+   * attribute; the coarse gate grants NOTHING from it — staff must never elevate
+   * app privileges (enforced by the Phase-4 PDP staff sandbox).
+   */
+  staff: string[];
+}
+
+/** Coarse-role collapse guard: anything tot didn't send as owner/admin → member. */
+function coerceRole(role: unknown): CoarseRole {
+  return role === "owner" || role === "admin" ? role : "member";
+}
+
+/**
+ * Normalize a jose JWT payload into typed {@link IdentityClaims}, coercing the
+ * loosely-typed pieces and filling contract defaults (`staff: []`). Throws if a
+ * required tot-authoritative claim is missing or malformed. Mirrors the kernel's
+ * `toIdentityClaims`.
+ */
+export function toIdentityClaims(payload: Record<string, unknown>): IdentityClaims {
+  const email = payload.email;
+  if (typeof email !== "string" || !email) {
+    throw new Error("identity assertion missing `email` claim");
+  }
+  const tenantsRaw = Array.isArray(payload.tenants) ? payload.tenants : [];
+  const tenants: TenantMembership[] = tenantsRaw.map((t): TenantMembership => {
+    const entry = t as { resource?: unknown; role?: unknown };
+    if (typeof entry.resource !== "string") {
+      throw new Error("identity assertion `tenants[].resource` must be a string");
+    }
+    return { resource: entry.resource, role: coerceRole(entry.role) };
+  });
+  const staff = Array.isArray(payload.staff)
+    ? payload.staff.filter((s): s is string => typeof s === "string")
+    : [];
+
+  return {
+    iss: String(payload.iss ?? ""),
+    sub: String(payload.sub ?? email),
+    aud: String(payload.aud ?? ""),
+    iat: Number(payload.iat ?? 0),
+    exp: Number(payload.exp ?? 0),
+    jti: typeof payload.jti === "string" ? payload.jti : undefined,
+    email: email.toLowerCase(),
+    email_verified: payload.email_verified === true,
+    tenants,
+    staff,
+  };
+}
+
+/** Derive tot's JWKS URL from the configured tot API base (§6b: path fixed, host app-config). */
+export function deriveJwksUri(baseUrl: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}${JWKS_PATH}`;
+}
+
+export interface IdentityVerifierConfig {
+  /**
+   * This host's tenant appDomain / `resource` — enforced as the `aud` claim (tot
+   * sets `aud` per-assertion to the target app). REQUIRED: a token minted for
+   * another tenant must be rejected.
+   */
+  audience: string;
+  /** Allowlisted issuer. Defaults to tot's. */
+  issuer?: string;
+  /**
+   * tot's JWKS endpoint, e.g. `https://qa.tokenoftrust.com/api/.well-known/jwks.json`.
+   * Provide in production. jose caches the fetch, selects the key by `kid`, and
+   * re-fetches once on an unknown `kid` before failing closed.
+   */
+  jwksUri?: string;
+  /**
+   * Pre-resolved JWKS (test / air-gapped path). The storefront holds ONLY the
+   * published public material — no private key, no secret. Exactly one of
+   * {@link jwksUri} or {@link jwks} must be supplied.
+   */
+  jwks?: JSONWebKeySet;
+}
+
+/**
+ * Verifies tot identity assertions offline against the published JWKS. One
+ * instance per (audience, JWKS host); its `audience` is fixed. Never calls tot
+ * per request — the JWKS fetch is cached inside jose's key resolver, so once the
+ * key material is in-process, verification survives tot being unreachable.
+ */
+export class IdentityAssertionVerifier {
+  private readonly audience: string;
+  private readonly issuer: string;
+  private readonly keys: JWTVerifyGetKey;
+
+  constructor(config: IdentityVerifierConfig) {
+    if (!config.audience) {
+      throw new Error("IdentityAssertionVerifier requires an `audience` (this host's resource)");
+    }
+    if (!!config.jwksUri === !!config.jwks) {
+      throw new Error("IdentityAssertionVerifier requires exactly one of `jwksUri` or `jwks`");
+    }
+    this.audience = config.audience;
+    this.issuer = config.issuer ?? TOT_ISSUER;
+    this.keys = config.jwks
+      ? createLocalJWKSet(config.jwks)
+      : createRemoteJWKSet(new URL(config.jwksUri as string));
+  }
+
+  /**
+   * Verify a compact JWS and return typed claims. Rejects (throws) on: any
+   * `alg` ≠ ES256 (blocks `alg:none` and every HS*), bad signature, wrong/absent
+   * `aud`, unlisted `iss`, or expired/not-yet-valid `exp`/`iat`.
+   */
+  async verify(token: string): Promise<IdentityClaims> {
+    // Fail fast + loud on the algorithm before touching keys. jose's `algorithms`
+    // allowlist below is the authoritative guard; this makes the reason explicit.
+    const header = decodeProtectedHeader(token);
+    if (header.alg !== TOT_ALG) {
+      throw new Error(`unexpected JWT alg ${String(header.alg)}; only ${TOT_ALG} is accepted`);
+    }
+
+    const { payload } = await jwtVerify(token, this.keys, {
+      issuer: this.issuer,
+      audience: this.audience,
+      algorithms: [TOT_ALG],
+    });
+
+    return toIdentityClaims(payload as Record<string, unknown>);
+  }
+}
+
+// --- Verifier cache -----------------------------------------------------------
+//
+// In-memory, module-scoped cache keyed by (jwksUri | audience). Good enough for
+// the prototype: each Worker isolate builds its verifier once and reuses jose's
+// cached JWKS across requests. FOLLOW-UP (multi-instance): promote the JWKS cache
+// to KV or a Durable Object so isolates share fetched key material and honour a
+// single rotation signal. Tracked with the Phase-4 kernel adoption.
+const verifierCache = new Map<string, IdentityAssertionVerifier>();
+
+/**
+ * Get (or build + cache) the verifier for a resource, deriving the JWKS URL from
+ * the configured tot API base (`TOT_CORE_URL` — the same base `totAccessClient`
+ * posts the access-code endpoints to). Returns `null` when tot's base URL is not
+ * configured (routes fail closed). Pass `overrides.jwks`/`overrides.jwksUri` in
+ * tests to inject key material without a network fetch.
+ */
+export async function getIdentityVerifier(
+  resource: string,
+  overrides: { jwksUri?: string; jwks?: JSONWebKeySet; baseUrl?: string } = {},
+): Promise<IdentityAssertionVerifier | null> {
+  if (overrides.jwks) {
+    // Test / air-gapped: never cached (keys are per-test) and never networked.
+    return new IdentityAssertionVerifier({ audience: resource, jwks: overrides.jwks });
+  }
+  const jwksUri =
+    overrides.jwksUri ??
+    deriveJwksUri(overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "");
+  if (jwksUri === JWKS_PATH) return null; // empty base → unconfigured
+
+  const cacheKey = `${jwksUri}|${resource}`;
+  let v = verifierCache.get(cacheKey);
+  if (!v) {
+    v = new IdentityAssertionVerifier({ audience: resource, jwksUri });
+    verifierCache.set(cacheKey, v);
+  }
+  return v;
+}
+
+/**
+ * Get (or build + cache) the FEDERATED verifier — the one for multi-tenant
+ * sign-in. Its audience is the STOREFRONT'S OWN app identity (`STOREFRONT_APP_DOMAIN`),
+ * because tot20's federated `id_token` sets `aud` = the calling app (storefront),
+ * NOT a tenant. The token then carries ALL of the email's memberships in
+ * `tenants[]`. Returns null when the tot base URL (`TOT_CORE_URL`) or the
+ * storefront app identity (`STOREFRONT_APP_DOMAIN`) is unconfigured — the route
+ * fails closed. Pass overrides in tests to inject key material + audience.
+ */
+export async function getFederatedVerifier(
+  overrides: { jwksUri?: string; jwks?: JSONWebKeySet; baseUrl?: string; audience?: string } = {},
+): Promise<IdentityAssertionVerifier | null> {
+  const audience = overrides.audience ?? (await readEnv("STOREFRONT_APP_DOMAIN")) ?? "";
+  if (!audience) return null; // storefront's own app identity must be configured
+  if (overrides.jwks) {
+    return new IdentityAssertionVerifier({ audience, jwks: overrides.jwks });
+  }
+  const jwksUri =
+    overrides.jwksUri ??
+    deriveJwksUri(overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "");
+  if (jwksUri === JWKS_PATH) return null; // empty base → unconfigured
+  const cacheKey = `${jwksUri}|${audience}`;
+  let v = verifierCache.get(cacheKey);
+  if (!v) {
+    v = new IdentityAssertionVerifier({ audience, jwksUri });
+    verifierCache.set(cacheKey, v);
+  }
+  return v;
+}
+
+// --- Session derivation from verified claims ---------------------------------
+
+/** The session fields derived from the VERIFIED token — the Phase-3 source of truth. */
+export interface DerivedSessionFields {
+  email: string;
+  resource: string;
+  /** Coarse standing on THIS resource, surfaced as the display capability. */
+  capability: CoarseRole | "none";
+  /** Display roles derived from the coarse claim (not tot's raw app roles). */
+  roles: string[];
+  /** Full multi-tenant memberships carried in the token (policy input). */
+  tenants: TenantMembership[];
+  /** ToT-staff scope carried in the token (sandboxed; grants nothing here). */
+  staff: string[];
+}
+
+/**
+ * Derive the storefront session from VERIFIED claims for a given resource — the
+ * Phase-3 replacement for trusting tot's flat `{roles, capability}`. Picks the
+ * membership matching `resource` and collapses its coarse role to the display
+ * capability. Throws if the verified token carries no membership for `resource`
+ * (a token for another tenant must not open this gate — belt-and-braces on top
+ * of the `aud` check).
+ */
+export function sessionFromClaims(claims: IdentityClaims, resource: string): DerivedSessionFields {
+  const membership = claims.tenants.find((t) => t.resource === resource);
+  if (!membership) {
+    throw new Error(`verified assertion carries no membership for resource "${resource}"`);
+  }
+  return {
+    email: claims.email,
+    resource,
+    capability: membership.role,
+    roles: [membership.role],
+    tenants: claims.tenants,
+    staff: claims.staff,
+  };
+}
+
+/** The multi-tenant fields derived from a verified FEDERATED assertion. */
+export interface FederatedSessionFields {
+  email: string;
+  /** The verified `aud` — the storefront app identity this console session is for. */
+  resource: string;
+  /** EVERY tenant membership the token carries (the dashboard picker's input). */
+  tenants: TenantMembership[];
+  /** ToT-staff scope carried in the token (sandboxed; grants nothing here). */
+  staff: string[];
+}
+
+/**
+ * Derive the storefront CONSOLE session from a verified FEDERATED assertion. Unlike
+ * {@link sessionFromClaims}, this does NOT require (or scope to) a single tenant:
+ * it binds ALL of `claims.tenants` so a user with N memberships yields an N-vendor
+ * session. `resource` is the verified `aud` (the storefront app identity), not a
+ * tenant — it exists only to satisfy the session record shape; the dashboard reads
+ * `tenants[]`, and the tenant-scoped preview gate never matches it.
+ */
+export function sessionFromFederatedClaims(claims: IdentityClaims): FederatedSessionFields {
+  return {
+    email: claims.email,
+    resource: claims.aud,
+    tenants: claims.tenants,
+    staff: claims.staff,
+  };
+}