@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

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

@@ -0,0 +1,119 @@
+/**
+ * Admin session-entry resolution (unit dg6) — the SERVER-SIDE decision that puts
+ * an authenticated owner/team member into the CORRECT tenant admin context, and
+ * keeps a non-member / unauthenticated visitor on the legitimate sign-in gate.
+ *
+ * NARROW to auth/session ENTRY: it CONSUMES the go-live admin tab UX
+ * (`pages/admin.astro` + `components/admin/AdminPublishTab.astro`) and u10's
+ * ship-capability model (`change/shipCapabilities` + `change/route` decideIsOwner)
+ * rather than reimplementing either. Everything it resolves is bound to the
+ * RESOLVED tenant, never taken from client input, and never requires a
+ * bearer/operator secret.
+ *
+ * Two things are resolved, both host-bound:
+ *   - `hostCapability` — the viewer's owner/admin/member standing FOR THIS host,
+ *     from {@link sessionHostCapability} (tenants[] membership → resource-scoped
+ *     session → live staff selection). null ⇒ not a member of this tenant.
+ *   - `isOwnerViewer` / `shipCapabilities` — u10's {@link decideIsOwner} +
+ *     {@link resolveShipCapabilities} over that host-bound capability. This is the
+ *     OWNER VIEWER identity (decision `owner-identity-narrow-viewer-not-bearer-console`):
+ *     a signed-in owner/admin viewer over the resolved tenant, NOT the bearer
+ *     operator console. The ship-axis `capability` is the fail-closed
+ *     `preview-access` — a viewer session carries no operator ship grant, so the
+ *     owner is the ONLY source of `shipOnBehalf`/`apexCutover` here.
+ *
+ * The distinguishing logic the go-live "definition of done" demands: `admitted`
+ * separates an authenticated OWNER/member (a host-bound capability, or ToT-staff
+ * scope) — who must NEVER see the "Coming soon" holding page at their own admin —
+ * from an authenticated NON-member and an anonymous visitor, who legitimately do
+ * not enter. `principal` labels which of those four cases this is.
+ */
+import type { SessionRecord } from "./session.js";
+import { sessionHostCapability } from "./loginGate.js";
+import { decideIsOwner } from "@/lib/change/route";
+import {
+  resolveShipCapabilities,
+  type ShipCapabilities,
+} from "@/lib/change/shipCapabilities";
+import type { Capability } from "@/lib/change/types";
+import { OWNER_CAPABILITIES } from "@/lib/grants/session";
+
+/** Which entry case a viewer is in, for chrome + the DoD test matrix. */
+export type AdminEntryPrincipal =
+  | "owner"
+  | "admin"
+  | "member"
+  | "staff"
+  | "authenticated-non-member"
+  | "anonymous";
+
+export interface AdminEntryDecision {
+  /**
+   * True when the viewer is an owner/member of this tenant (host-bound capability)
+   * or a ToT-staff viewer — i.e. reaches the admin context, never the gate. False
+   * for an authenticated non-member and an anonymous visitor (the legit gate).
+   */
+  admitted: boolean;
+  /** The owner/admin/member standing bound to this host, or null. */
+  hostCapability: string | null;
+  /** u10: the acting viewer IS the tenant owner/admin (superset of ship-on-behalf). */
+  isOwnerViewer: boolean;
+  /** u10: the two derived ship-gate capabilities for this viewer entry. */
+  shipCapabilities: ShipCapabilities;
+  /** Which of the four entry cases this is. */
+  principal: AdminEntryPrincipal;
+}
+
+/**
+ * Resolve the admin session-entry decision for a viewer over the resolved tenant.
+ * PURE (no I/O, no Astro) so the four-way distinction is unit-testable in
+ * isolation and stays identical across every admin route.
+ *
+ * @param record       the viewer's full session (from `readViewerSession`), or null
+ * @param hostResource the resolved tenant's appDomain (server-derived, never input)
+ * @param nowSeconds   epoch seconds, for the staff-selection expiry check
+ * @param shipGrant    OPTIONAL: the signed-in developer's REAL, LIVE, owner-revocable
+ *   ship grant over this tenant, resolved server-side from the MCP subject-capability
+ *   store (`resolveViewerShipCapability`). Feeds the ship AXIS so a ship-granted
+ *   developer (not owner/admin) gets `shipOnBehalf: true` — but NEVER apex-cutover
+ *   (owner-only). Absent ⇒ the fail-closed `preview-access` (no ship). NEVER derive
+ *   this from the coarse role or a client header.
+ */
+export function resolveAdminEntry(input: {
+  record: SessionRecord | null | undefined;
+  hostResource: string;
+  nowSeconds: number;
+  shipGrant?: Capability;
+}): AdminEntryDecision {
+  const { record, hostResource, nowSeconds, shipGrant } = input;
+  const hostCapability = sessionHostCapability(record ?? null, hostResource, nowSeconds);
+  const staffScope = Array.isArray(record?.staff) && record!.staff.length > 0;
+  const admitted = hostCapability !== null || staffScope;
+
+  // u10 owner resolution — the OWNER VIEWER, not the bearer console: authorized
+  // (a member/staff viewer of THIS tenant) AND holding an owner/admin capability.
+  const isOwnerViewer = decideIsOwner({
+    authorized: admitted,
+    viewerCapability: hostCapability ?? undefined,
+  });
+  // The ship axis: a viewer entry carries no operator ship grant EXCEPT an explicit,
+  // LIVE ship-on-behalf grant a developer may hold (passed in as `shipGrant`).
+  // Fail-closed default is `preview-access`. Only an admitted viewer's grant counts —
+  // a non-member's resolved grant never leaks ship into this host's entry.
+  const shipCapabilities = resolveShipCapabilities({
+    isOwner: isOwnerViewer,
+    capability: admitted ? (shipGrant ?? "preview-access") : "preview-access",
+  });
+
+  const principal: AdminEntryPrincipal = !record
+    ? "anonymous"
+    : hostCapability
+      ? OWNER_CAPABILITIES.has(hostCapability)
+        ? (hostCapability as "owner" | "admin")
+        : "member"
+      : staffScope
+        ? "staff"
+        : "authenticated-non-member";
+
+  return { admitted, hostCapability, isOwnerViewer, shipCapabilities, principal };
+}

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

@@ -85,6 +85,15 @@ export interface IdentityClaims {
    * app privileges (enforced by the Phase-4 PDP staff sandbox).
    */
   staff: string[];
+  /**
+   * RFC 9470 Authentication Context Class Reference tot stamped on this
+   * assertion (e.g. `tot:aal:sms` for a step-up-satisfied credential). Optional:
+   * only present on tokens minted through an assurance-aware path (step-up
+   * completion); a plain federated-verify token may omit it.
+   */
+  acr?: string;
+  /** Epoch seconds the underlying authentication event occurred, when tot sends it. */
+  auth_time?: number;
 }
 
 /** Coarse-role collapse guard: anything tot didn't send as owner/admin → member. */
@@ -115,7 +124,7 @@ export function toIdentityClaims(payload: Record<string, unknown>): IdentityClai
     ? payload.staff.filter((s): s is string => typeof s === "string")
     : [];
 
-  return {
+  const claims: IdentityClaims = {
     iss: String(payload.iss ?? ""),
     sub: String(payload.sub ?? email),
     aud: String(payload.aud ?? ""),
@@ -127,6 +136,9 @@ export function toIdentityClaims(payload: Record<string, unknown>): IdentityClai
     tenants,
     staff,
   };
+  if (typeof payload.acr === "string") claims.acr = payload.acr;
+  if (typeof payload.auth_time === "number") claims.auth_time = payload.auth_time;
+  return claims;
 }
 
 /** Derive tot's JWKS URL from the configured tot API base (§6b: path fixed, host app-config). */
@@ -321,6 +333,10 @@ export interface FederatedSessionFields {
   tenants: TenantMembership[];
   /** ToT-staff scope carried in the token (sandboxed; grants nothing here). */
   staff: string[];
+  /** RFC 9470 ACR the assertion carried (e.g. `tot:aal:sms`), when tot sent one. */
+  acr?: string;
+  /** Epoch seconds of the underlying authentication event, when tot sent one. */
+  authTime?: number;
 }
 
 /**
@@ -332,10 +348,13 @@ export interface FederatedSessionFields {
  * `tenants[]`, and the tenant-scoped preview gate never matches it.
  */
 export function sessionFromFederatedClaims(claims: IdentityClaims): FederatedSessionFields {
-  return {
+  const fields: FederatedSessionFields = {
     email: claims.email,
     resource: claims.aud,
     tenants: claims.tenants,
     staff: claims.staff,
   };
+  if (claims.acr) fields.acr = claims.acr;
+  if (typeof claims.auth_time === "number") fields.authTime = claims.auth_time;
+  return fields;
 }

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

@@ -14,7 +14,7 @@
  * so a visitor can actually sign in.
  */
 import { hostInGateList } from "@/lib/demoGate";
-import { viewerCanAccess } from "@/lib/dashboard/tenantSelection";
+import { normalizeMemberships, staffAdmits } from "@/lib/dashboard/tenantSelection";
 import type { SessionRecord } from "./session.js";
 
 export type GateMode = "password" | "login";
@@ -28,18 +28,72 @@ export type GateMode = "password" | "login";
 export const PUBLIC_HOME_TENANT_ID = "home";
 
 /**
- * Whether a (federated) viewer session admits the gated HOST — i.e. the signed-in
- * user holds a membership for the host's tenant (`hostResource`, the host's
- * appDomain). This UNIFIES the preview-host gate onto the single federated session:
- * federated sign-in mints a multi-tenant session whose `aud`/`resource` is the
- * storefront app (not a tenant), so the old resource-scoped session match never
- * fit; membership in `tenants[]` is the right test. Deny-closed: no session, or a
- * session without a membership for `hostResource`, is not admitted. (Backward-
- * compatible with a legacy resource-scoped session, whose `tenants[]` still lists
- * its own resource.)
+ * The record fields the host-admission + host-capability checks read. All optional
+ * — these readers tolerate a partial/legacy record and are deny-closed on absence.
+ */
+type HostAdmissionRecord = Partial<
+  Pick<SessionRecord, "tenants" | "staffSelection" | "staff" | "resource" | "capability">
+>;
+
+/**
+ * The owner/admin/member standing a session holds FOR THIS EXACT HOST tenant, or
+ * null when it is not a member of the host. Resolved SERVER-SIDE and BOUND to
+ * `hostResource` — it never returns a capability the session holds for some OTHER
+ * tenant, so the caller can surface it as the viewer's per-host capability without
+ * an over-grant. Resolution order (all host-bound):
+ *
+ *   1. A `tenants[]` membership for `hostResource` (the federated multi-tenant
+ *      signal) → its role.
+ *   2. A session minted SCOPED to this host (`sessionFromClaims`): its primary
+ *      `resource` IS this tenant and its `capability` is the owner/admin/member
+ *      standing verified for it. This is the near-side signal that admits the
+ *      authenticated OWNER of their own tenant even when the multi-tenant
+ *      `tenants[]` projection is absent — the fix for an authenticated owner
+ *      wrongly served the "Coming soon" gate at their own `/admin`. A federated
+ *      console session's `resource` is the storefront app `aud` (never a tenant
+ *      host), so it never matches here — deny-closed for cross-tenant.
+ *   3. A LIVE ToT-staff vendor selection for this exact host (the distinct
+ *      staff-admission path — never a synthesized `tenants[]` member).
+ *
+ * Deny-closed: no session, or none of the above binds to `hostResource`, → null.
+ */
+export function sessionHostCapability(
+  record: HostAdmissionRecord | null | undefined,
+  hostResource: string,
+  nowSeconds: number = Math.floor(Date.now() / 1000),
+): string | null {
+  if (!record) return null;
+  const target = (hostResource ?? "").trim();
+  if (!target) return null;
+
+  const membership = normalizeMemberships(record.tenants).find((t) => t.resource === target);
+  if (membership) return membership.role;
+
+  if (record.resource === target) {
+    const cap = (record.capability ?? "").trim();
+    if (cap && cap !== "none") return cap;
+  }
+
+  if (staffAdmits({ selection: record.staffSelection, nowSeconds }, target)) {
+    return record.staffSelection!.capability;
+  }
+
+  return null;
+}
+
+/**
+ * Whether a viewer session admits the gated HOST — i.e. the signed-in user is a
+ * member/owner of the host's tenant (`hostResource`, the host's appDomain), or a
+ * ToT-staff viewer. This UNIFIES the preview-host gate onto the single federated
+ * session: federated sign-in mints a multi-tenant session whose `aud`/`resource`
+ * is the storefront app (not a tenant), so a `tenants[]` membership is the primary
+ * test; a session minted SCOPED to this host (its own primary `resource` +
+ * `capability`) is admitted too, so an authenticated OWNER of their own tenant is
+ * never mistaken for an anonymous visitor. Deny-closed: no session, or one with no
+ * standing for `hostResource`, is not admitted.
  */
 export function sessionAdmitsHost(
-  record: Pick<SessionRecord, "tenants" | "staffSelection" | "staff"> | null,
+  record: HostAdmissionRecord | null,
   hostResource: string,
   nowSeconds: number = Math.floor(Date.now() / 1000),
 ): boolean {
@@ -47,14 +101,11 @@ export function sessionAdmitsHost(
   // ToT STAFF get in everywhere: any session carrying a verified `staff` scope is
   // admitted to EVERY gated demo host with just a login — no per-vendor selection
   // needed. This is a GATE-level admission for demo BROWSING only; dashboard-action
-  // authorization (viewerCanAccess) stays membership/selection-bound + audited.
+  // authorization stays membership/selection-bound + audited.
   if (Array.isArray(record.staff) && record.staff.length > 0) return true;
-  // Otherwise: a membership OR a live ToT-staff selection for this exact host admits
-  // — the staff-selection path is distinct from tenants[] (never a synthesized member).
-  return viewerCanAccess(record.tenants, hostResource, {
-    selection: record.staffSelection,
-    nowSeconds,
-  });
+  // Otherwise a host-bound standing (membership, resource-scoped session, or a live
+  // staff selection for this exact host) admits — see sessionHostCapability.
+  return sessionHostCapability(record, hostResource, nowSeconds) !== null;
 }
 
 /** Parse `DEMO_GATE_MODE` (default "password"). */
@@ -93,6 +144,36 @@ export function isPublicPath(pathname: string): boolean {
   return pathname === "/api/cli/policy";
 }
 
+/**
+ * The candidate-preview CONTROL-PLANE routes — the per-change hosted review
+ * surfaces that carry their OWN, stricter auth (the cockpit gate: signed-in +
+ * developer capability + a SESSION-derived tenant — see
+ * `@/lib/preview/candidateRender` and `@/lib/preview/reviewDashboard`). They MUST be
+ * exempt from the demo login gate's "Coming soon" holding page: a REAL candidate
+ * that exists must never be masked behind a generic holding page — that false-
+ * negative is exactly `dogfood-definition-of-done`'s NOT-DONE bar ("a preview that
+ * renders 'Coming soon'"). Exempting them here does NOT open them up: the route's
+ * own cockpit gate still withholds a candidate from an unauthenticated / wrong-
+ * tenant viewer, but HONESTLY (a real 401/403, or an honest "not renderable"
+ * blocker naming the head SHA), never a misleading "Coming soon". A demo BROWSE of
+ * the tenant's own pages stays gated as before.
+ *
+ * Matched (prefix, so sub-paths are covered):
+ *   /preview/render/<tenant>/<changeId>/...   the candidate content renderer (s4)
+ *   /preview/change/<changeId>                the per-change review dashboard (s5)
+ *   /preview/<tenant>/pr/<n>                  the friendly PR-number alias (u4)
+ *   /preview/<tenant>/rev/<sha>/...           the immutable per-revision renderer (u4)
+ */
+export function isCandidatePreviewPath(pathname: string): boolean {
+  if (pathname.startsWith("/preview/render/")) return true;
+  if (pathname === "/preview/change" || pathname.startsWith("/preview/change/")) return true;
+  // /preview/<tenant>/pr and /preview/<tenant>/pr/<n> — the PR-number alias.
+  if (/^\/preview\/[^/]+\/pr(?:\/|$)/.test(pathname)) return true;
+  // /preview/<tenant>/rev/<sha> and /preview/<tenant>/rev/<sha>/<path...> — the
+  // immutable per-revision alias.
+  return /^\/preview\/[^/]+\/rev(?:\/|$)/.test(pathname);
+}
+
 export type LoginGateDecision =
   | { action: "pass" }
   | { action: "redirect"; location: string };
@@ -124,6 +205,9 @@ export function evaluateLoginGate(input: LoginGateInput): LoginGateDecision {
   if (input.tenantExempt) return { action: "pass" };
   if (isAuthPath(input.pathname)) return { action: "pass" };
   if (isPublicPath(input.pathname)) return { action: "pass" };
+  // Candidate-preview control-plane routes govern their OWN (stricter, honest) auth
+  // and must never fall to the "Coming soon" holding page for a real candidate.
+  if (isCandidatePreviewPath(input.pathname)) return { action: "pass" };
   if (input.hasValidSession) return { action: "pass" };
   const next = input.pathname + (input.search ?? "");
   return { action: "redirect", location: `/auth/login?next=${encodeURIComponent(next)}` };

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

@@ -0,0 +1,215 @@
+/**
+ * MCP client-assertion MINTER + signing-key loader — the storefront half of the
+ * "MCP machine identity" contract (workstream `mcp-machine-identity`, unit B1
+ * `sf-client-assertion`).
+ *
+ * The deployed storefront Worker is a browserless, multi-tenant service with no
+ * human in the loop. It authenticates to the MCP's `client_credentials` grant
+ * (RFC 6749 §4.4) using `private_key_jwt` client authentication (OIDC Core §9,
+ * RFC 7523 §2.2/§3): it MINTS a short-lived RS256 `client_assertion` JWT proving
+ * it holds `MCP_CLIENT_ASSERTION_PRIVATE_KEY_B64`, and the MCP verifies the
+ * signature against storefront's PUBLISHED public key (fetched by `kid` from the
+ * JWKS this module derives — see `loadMcpClientAssertionJwks` + the sibling
+ * `.well-known/mcp-client-jwks.json` route, binding decision
+ * `c0-client-key-resolution`).
+ *
+ * Claims (RFC 7523 §3): `iss = sub = client_id`, `aud = <mcp token endpoint>`,
+ * `exp ~= iat + 60s`, a fresh `jti` every call (one-time-use, verified server-side
+ * by the MCP's replay store). Header: `{ alg: RS256, kid, typ: JWT }`.
+ *
+ * SERVER-SIDE ONLY. Mirrors `./brokerAssertion.ts`'s `mintBrokerAssertion()` shape
+ * (short-lived RS256 assertion signed with a private key that never leaves the
+ * Worker/server env) and `../apps/gatewayKeys.ts`'s signing-key-loader +
+ * JWKS-derivation shape (public JWKS derived from the same RSA key, every private
+ * field stripped before publish).
+ *
+ * KEY CONVENTION: this is a NEW, DEDICATED key — `MCP_CLIENT_ASSERTION_PRIVATE_KEY_B64`
+ * — never the broker key (`STOREFRONT_BROKER_PRIVATE_KEY_B64`) or the app-gateway
+ * key (`JWT_APP_GATEWAY_PRIVATE_KEY_B64`). Each trust direction gets its own key so a
+ * compromise or rotation of one never implicates another (see gatewayKeys.ts's
+ * header comment for the same rule stated from the gateway side). The key is a
+ * PROVIDED secret (generated + synced via SSM/`.secrets[]`, see B3), never
+ * autogenerated at runtime; tests/local-dev generate a throwaway keypair instead.
+ */
+import { importPKCS8, exportJWK, SignJWT, type CryptoKey, type JWK, type JSONWebKeySet } from "jose";
+import { readEnv } from "@/lib/env";
+
+/** The only algorithm this assertion is signed with (the MCP verifier rejects anything else). */
+export const MCP_CLIENT_ASSERTION_ALG = "RS256";
+
+/** Default key id (overridable via `MCP_CLIENT_ASSERTION_KID`). Matches the C0 golden fixture's `kid`. */
+export const DEFAULT_MCP_CLIENT_ASSERTION_KID = "storefront-mcp-client-1";
+
+/**
+ * Default issuer — this doubles as the OAuth `client_id`: RFC 7523 §3 requires
+ * `iss == sub == client_id`, so one env value covers both claims. Overridable via
+ * `MCP_CLIENT_ASSERTION_ISSUER`. Matches the C0 golden fixture's `clientId`.
+ */
+export const DEFAULT_MCP_CLIENT_ASSERTION_ISSUER = "storefront.tokenoftrust.com";
+
+/** Assertion lifetime — RFC 7523 §3 wants this short; the contract pins `exp = iat + 60`. */
+export const MCP_CLIENT_ASSERTION_TTL_SECONDS = 60;
+
+/** Env keys the minter/loader reads (server-only). */
+export const MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV = "MCP_CLIENT_ASSERTION_PRIVATE_KEY_B64";
+export const MCP_CLIENT_ASSERTION_KID_ENV = "MCP_CLIENT_ASSERTION_KID";
+export const MCP_CLIENT_ASSERTION_ISSUER_ENV = "MCP_CLIENT_ASSERTION_ISSUER";
+
+/**
+ * Thrown when the assertion can't be minted or the JWKS can't be derived — the
+ * private key env is absent/malformed, or (for minting) no audience/token-endpoint
+ * was supplied. Routes/callers map this to "integration not configured" and FAIL
+ * CLOSED: with no key, no assertion goes out and no JWKS is published.
+ */
+export class McpClientAssertionError extends Error {}
+
+/** Optional test/DI overrides (avoids touching process env in unit tests). */
+export interface McpClientAssertionOverrides {
+  /** base64 of the PKCS8 PEM private key (defaults to the env value). */
+  privateKeyB64?: string;
+  kid?: string;
+  /** Also used as the OAuth `client_id` (both `iss` and `sub`). */
+  issuer?: string;
+}
+
+export interface McpClientAssertionSigningConfig {
+  key: CryptoKey;
+  kid: string;
+  issuer: string;
+}
+
+// Import the signing key once per distinct PEM (importPKCS8 is not free), same
+// cache shape as brokerAssertion.ts / gatewayKeys.ts. Keyed on the base64 string
+// so a rotated key (new env value) transparently re-imports and re-derives.
+const signingKeyCache = new Map<string, CryptoKey>();
+const publicJwkCache = new Map<string, JWK>();
+
+async function importPrivateKey(privateKeyB64: string): Promise<CryptoKey> {
+  const cached = signingKeyCache.get(privateKeyB64);
+  if (cached) return cached;
+  let pem: string;
+  try {
+    pem = Buffer.from(privateKeyB64, "base64").toString("utf8");
+  } catch (cause) {
+    throw new McpClientAssertionError(
+      `mcp client assertion: ${MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV} is not valid base64 ` +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  if (!/-----BEGIN (RSA )?PRIVATE KEY-----/.test(pem)) {
+    throw new McpClientAssertionError(
+      `mcp client assertion: decoded ${MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV} is not a PEM private key`,
+    );
+  }
+  let key: CryptoKey;
+  try {
+    // extractable: true — required so `loadMcpClientAssertionJwks` below can
+    // derive the public JWK from this same key. The private key itself is
+    // still never exported anywhere outside this module.
+    key = (await importPKCS8(pem, MCP_CLIENT_ASSERTION_ALG, { extractable: true })) as CryptoKey;
+  } catch (cause) {
+    throw new McpClientAssertionError(
+      `mcp client assertion: failed to import the RS256 private key ` +
+        (cause instanceof Error ? cause.message : String(cause)),
+    );
+  }
+  signingKeyCache.set(privateKeyB64, key);
+  return key;
+}
+
+/**
+ * Resolve the active signing config (key + kid + issuer/client_id) from env, or
+ * `overrides` in tests. FAILS CLOSED: throws {@link McpClientAssertionError} when
+ * the private key env is absent/malformed.
+ */
+export async function loadMcpClientAssertionSigningConfig(
+  overrides: McpClientAssertionOverrides = {},
+): Promise<McpClientAssertionSigningConfig> {
+  const privateKeyB64 =
+    overrides.privateKeyB64 ?? (await readEnv(MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV));
+  if (!privateKeyB64) {
+    throw new McpClientAssertionError(
+      `mcp client assertion: ${MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV} is not configured (fail closed)`,
+    );
+  }
+  const kid =
+    overrides.kid ?? (await readEnv(MCP_CLIENT_ASSERTION_KID_ENV)) ?? DEFAULT_MCP_CLIENT_ASSERTION_KID;
+  const issuer =
+    overrides.issuer ??
+    (await readEnv(MCP_CLIENT_ASSERTION_ISSUER_ENV)) ??
+    DEFAULT_MCP_CLIENT_ASSERTION_ISSUER;
+  const key = await importPrivateKey(privateKeyB64);
+  return { key, kid, issuer };
+}
+
+/**
+ * Derive the PUBLIC JWKS for the active key — sanitized (every private RSA field
+ * stripped) and cached by the source private-key base64 (so a rotated key
+ * transparently re-derives). This is what the `.well-known/mcp-client-jwks.json`
+ * route publishes, and what the MCP fetches by `kid` (binding decision
+ * `c0-client-key-resolution`) to verify assertions minted by
+ * {@link mintMcpClientAssertion}. V1 always returns exactly one key; the envelope
+ * (`{ keys: [] }`) is forward-compatible with more (rotation-with-overlap).
+ */
+export async function loadMcpClientAssertionJwks(
+  overrides: McpClientAssertionOverrides = {},
+): Promise<JSONWebKeySet> {
+  const privateKeyB64 =
+    overrides.privateKeyB64 ?? (await readEnv(MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV));
+  if (!privateKeyB64) {
+    throw new McpClientAssertionError(
+      `mcp client assertion: ${MCP_CLIENT_ASSERTION_PRIVATE_KEY_ENV} is not configured (fail closed)`,
+    );
+  }
+  const { key, kid } = await loadMcpClientAssertionSigningConfig(overrides);
+  let jwk = publicJwkCache.get(privateKeyB64);
+  if (!jwk) {
+    const full = (await exportJWK(key)) as Record<string, unknown>;
+    // Strip every private RSA field (RFC 7518 §6.3.2) — only the public parts
+    // (kty, n, e) are ever published. This line is the one place that matters.
+    const { d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, oth: _oth, ...publicOnly } = full;
+    jwk = { ...publicOnly, kid, alg: MCP_CLIENT_ASSERTION_ALG, use: "sig" };
+    publicJwkCache.set(privateKeyB64, jwk);
+  }
+  return { keys: [jwk] };
+}
+
+/**
+ * Mint a fresh private_key_jwt `client_assertion` PROVING this Worker holds the
+ * dedicated MCP signing key. `audience` is the MCP's OAuth token endpoint
+ * (`<mcpBase>/oauth/token`) — callers (B2's forge/change service-auth transport)
+ * supply it from their own resolved `MCP_BASE_URL` config, since it can differ
+ * per deploy target (qa vs prod).
+ *
+ * Claims: `{ iss:<client_id>, sub:<client_id>, aud:<audience>, iat, exp:iat+60,
+ * jti:<uuid> }`. Header: `{ alg:'RS256', kid, typ:'JWT' }`. Claim/header field
+ * order mirrors the C0 golden fixture (`iss,sub,aud,iat,exp,jti` /
+ * `alg,kid,typ`) so a structural diff against the fixture is a no-op modulo
+ * `iat`/`exp`/`jti`.
+ *
+ * FAILS CLOSED: throws {@link McpClientAssertionError} when the private key env
+ * is absent/malformed or no audience is supplied — the caller must NOT fall back
+ * to an unsigned/unproven call.
+ */
+export async function mintMcpClientAssertion(
+  audience: string,
+  overrides: McpClientAssertionOverrides = {},
+): Promise<string> {
+  const aud = (audience ?? "").trim();
+  if (!aud) {
+    throw new McpClientAssertionError(
+      "mcp client assertion: an audience (the MCP token endpoint) is required",
+    );
+  }
+  const signing = await loadMcpClientAssertionSigningConfig(overrides);
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  return new SignJWT({})
+    .setProtectedHeader({ alg: MCP_CLIENT_ASSERTION_ALG, kid: signing.kid, typ: "JWT" })
+    .setIssuer(signing.issuer)
+    .setSubject(signing.issuer)
+    .setAudience(aud)
+    .setIssuedAt(nowSeconds)
+    .setExpirationTime(nowSeconds + MCP_CLIENT_ASSERTION_TTL_SECONDS)
+    .setJti(crypto.randomUUID())
+    .sign(signing.key);
+}

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

@@ -134,12 +134,27 @@ export function safeNext(next: string | null | undefined): string {
 /** Redirect back to the login page carrying step-2 state (email/error), no-JS-safe. */
 export function loginRedirect(
   context: APIContext,
-  params: { sent?: boolean; email?: string; error?: string; next?: string },
+  params: {
+    sent?: boolean;
+    email?: string;
+    error?: string;
+    next?: string;
+    /**
+     * Step-up state distinct from a plain `error`: `step-up-required` (the login
+     * page should offer the SMS step-up completion card) or `success-pending`
+     * (identity is bound; sign-in awaits step-up). See `@/lib/auth/stepUpChallenge`.
+     */
+    reason?: "step-up-required" | "success-pending";
+    /** The RFC 9470 `requiredAcr` from the step-up obligation, when known. */
+    requiredAcr?: string;
+  },
 ): Response {
   const q = new URLSearchParams();
   if (params.sent) q.set("sent", "1");
   if (params.email) q.set("email", params.email);
   if (params.error) q.set("error", params.error);
+  if (params.reason) q.set("reason", params.reason);
+  if (params.requiredAcr) q.set("requiredAcr", params.requiredAcr);
   if (params.next && params.next !== "/") q.set("next", params.next);
   const qs = q.toString();
   return context.redirect(`/auth/login${qs ? `?${qs}` : ""}`, 303);

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

@@ -69,6 +69,14 @@ export interface SessionRecord {
    * DISTINCT from `tenants[]` — never a synthesized membership. See {@link StaffSelection}.
    */
   staffSelection?: StaffSelection;
+  /**
+   * RFC 9470 Authentication Context Class Reference the session was established
+   * at (e.g. `tot:aal:sms` after a step-up completion). Absent for a session
+   * minted from a plain federated verify that carried no `acr` claim.
+   */
+  acr?: string;
+  /** Epoch seconds of the underlying authentication event, when known (step-up path). */
+  authTime?: number;
   /** Issued-at, epoch seconds. */
   createdAt: number;
   /** Expiry, epoch seconds. The store TTL mirrors this; we re-check on read. */