@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/apps/widgets/eligibility.ts

@@ -1,10 +1,10 @@
 /**
- * Widget eligibility — PrivateApps epic, D5 (Chunk C). Mirrors
+ * Widget eligibility. Mirrors
  * `webhooks/emit.ts`'s `isEligibleTarget` discipline: an install is eligible
  * to render its widget at `slot` only while it is LIVE — `active`, scoped for
  * `widgets:launch`, and carrying a validated placement for that slot. This
  * live check is what makes suspending an install actually stop it rendering
- * on the very next page load — the D8 "suspension kills widgets"
+ * on the very next page load — the "suspension kills widgets"
  * enforcement — with no separate revoke step; it's just this gate re-run on
  * every request.
  */

package/apps/storefront/src/lib/apps/widgets/frameProps.ts

@@ -1,7 +1,7 @@
 /**
- * Pure prop-building for `<AppWidgetFrame>` — PrivateApps epic, D5 (Chunk D).
- * Split out of the `.astro` component so the query-param handoff and the
- * sandbox attrs are unit-testable: `vitest.config.ts` deliberately does NOT
+ * Pure prop-building for `<AppWidgetFrame>`. The query-param handoff and the
+ * sandbox attrs live here (not in the `.astro` component) so they are
+ * unit-testable: `vitest.config.ts` deliberately does NOT
  * render `.astro` components (Astro Container API breaks under vitest@2 +
  * astro@7 — see that file's docstring), so render *logic* lives here and
  * rendered output is verified on a live preview instead.

package/apps/storefront/src/lib/apps/widgets/launchToken.ts

@@ -1,7 +1,7 @@
 /**
- * Widget launch-token minting — PrivateApps epic, D5 Chunk B. Mints the
+ * Widget launch-token minting. Mints the
  * short-lived RS256 JWT a platform-managed sandboxed widget iframe carries at
- * SSR render time: Chunk D calls `mintWidgetLaunchToken` while rendering the
+ * SSR render time: the page-render path calls `mintWidgetLaunchToken` while rendering the
  * page for each declared placement, and the resulting token is what the
  * widget's own endpoint receives as proof it was launched by THIS platform,
  * for THIS install, at THIS placement — never a merchant-forged or replayed
@@ -31,10 +31,10 @@ import {
 export interface MintWidgetLaunchTokenInput {
   /**
    * Only `installId`/`tenantId`/`env` are read. Narrowed from `AppInstall` to
-   * this `Pick` so Chunk D's render path — which has `placements.ts`'s
+   * this `Pick` so the render path — which has `placements.ts`'s
    * `ResolvedPlacement` (installId/appOrigin/endpoint), not the full
    * `AppInstall` — can build the minimal object itself instead of re-fetching
-   * the install; a full `AppInstall` still satisfies this shape unchanged.
+   * the install; a full `AppInstall` still satisfies this shape.
    */
   install: Pick<AppInstall, "installId" | "tenantId" | "env">;
   slot: WidgetPlacement;

package/apps/storefront/src/lib/apps/widgets/placements.ts

@@ -1,6 +1,6 @@
 /**
- * Widget placement resolution — PrivateApps epic, D5 (Chunk C). Turns "which
- * apps have a live widget at this slot" into the concrete list Chunk D needs
+ * Widget placement resolution. Turns "which
+ * apps have a live widget at this slot" into the concrete list the render path needs
  * to render sandboxed iframes and mint launch tokens: reads
  * `registry.listByTenant`, filters to the requested `env` and
  * {@link isWidgetEligible}, then reads each eligible install's `endpoint`

package/apps/storefront/src/lib/apps/widgets/renderSlot.ts

@@ -1,5 +1,5 @@
 /**
- * Widget slot render composition — PrivateApps epic, D5 (Chunk D). The one
+ * Widget slot render composition. The one
  * call a page/layout makes to turn "render slot X for this request" into the
  * concrete, launch-token-bearing list `AppWidgetFrame` needs: resolves live
  * placements (`placements.ts`), mints each one a launch token

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

@@ -1,10 +1,10 @@
 /**
- * Admin session-entry resolution (unit dg6) — the SERVER-SIDE decision that puts
+ * Admin session-entry resolution — 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
+ * NARROW to auth/session ENTRY: it CONSUMES the admin tab UX
+ * (`pages/admin.astro` + `components/admin/AdminPublishTab.astro`) and the
  * 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
@@ -14,15 +14,15 @@
  *   - `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} +
+ *   - `isOwnerViewer` / `shipCapabilities` — {@link decideIsOwner} +
  *     {@link resolveShipCapabilities} over that host-bound capability. This is the
- *     OWNER VIEWER identity (decision `owner-identity-narrow-viewer-not-bearer-console`):
+ *     OWNER VIEWER identity:
  *     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`
+ * The distinguishing logic: `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
@@ -56,9 +56,9 @@ export interface AdminEntryDecision {
   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). */
+  /** 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. */
+  /** The two derived ship-gate capabilities for this viewer entry. */
   shipCapabilities: ShipCapabilities;
   /** Which of the four entry cases this is. */
   principal: AdminEntryPrincipal;
@@ -90,7 +90,7 @@ export function resolveAdminEntry(input: {
   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
+  // 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,

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

@@ -1,6 +1,6 @@
 /**
  * Offline verification of tot's identity assertion (`id_token`) — the consuming
- * half of the decoupled-authZ architecture (Phase 3).
+ * half of the decoupled-authZ architecture.
  *
  * 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
@@ -10,20 +10,12 @@
  * 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`.
+ * SCOPE: this does ONLY the JWKS offline-verify + a coarse claims→session
+ * derivation. Do NOT vendor the Cedar-wasm PDP into the Worker; it is
+ * unnecessary for the current coarse gate.
  *
- * 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
+ * Contract points as-built: ES256 + jose, the claim set, the consumer verify
+ * algorithm, field name `id_token`, and JWKS host is per-env app config (jose
  * cross-version 4↔6 is wire-compatible by construction).
  */
 import {

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

@@ -1,9 +1,9 @@
 /**
  * Login-gate decision (pure) — the "Sign in with ToT" enforcement mode for a
- * gated demo host, the eventual replacement for the interim Basic-Auth password
- * (see `@/lib/demoGate`). Same `DEMO_GATE_HOSTS` list, switched by `DEMO_GATE_MODE`:
+ * gated demo host (see `@/lib/demoGate`). Same `DEMO_GATE_HOSTS` list, switched
+ * by `DEMO_GATE_MODE`:
  *
- *   DEMO_GATE_MODE = "password"  → interim Basic-Auth gate (evaluateDemoGate)
+ *   DEMO_GATE_MODE = "password"  → Basic-Auth gate (evaluateDemoGate)
  *   DEMO_GATE_MODE = "login"     → this: redirect to /auth/login unless a valid,
  *                                  resource-bound tot_session cookie is present.
  *
@@ -29,7 +29,7 @@ export const PUBLIC_HOME_TENANT_ID = "home";
 
 /**
  * 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.
+ * — these readers tolerate a partial record and are deny-closed on absence.
  */
 type HostAdmissionRecord = Partial<
   Pick<SessionRecord, "tenants" | "staffSelection" | "staff" | "resource" | "capability">
@@ -144,6 +144,18 @@ export function isPublicPath(pathname: string): boolean {
   return pathname === "/api/cli/policy";
 }
 
+/**
+ * The authenticated static-bundle staging upload (`/api/publish/stage-bundle`).
+ * Like the candidate-preview control plane, it governs its OWN, stricter auth (a
+ * CI `private_key_jwt` assertion — see `@/lib/publish/stageBundleUpload`), so it
+ * must reach its handler server-to-server rather than being masked behind the
+ * demo login gate's "Coming soon" holding page. Gate-exemption does NOT weaken
+ * it: an unauthenticated request still gets a 401 from the route's own check.
+ */
+export function isStaticBundleUploadPath(pathname: string): boolean {
+  return pathname === "/api/publish/stage-bundle";
+}
+
 /**
  * The candidate-preview CONTROL-PLANE routes — the per-change hosted review
  * surfaces that carry their OWN, stricter auth (the cockpit gate: signed-in +
@@ -158,20 +170,56 @@ export function isPublicPath(pathname: string): boolean {
  * 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)
+ * Matched (prefix, so sub-paths are covered). The PR/rev aliases are tenant-first
+ * (`/<tenant>/preview/...`, the leading segment middleware-selects the tenant),
+ * matched here on the pre-strip request path:
+ *   /preview/render/<tenant>/<changeId>/...   the candidate content renderer
+ *   /preview/change/<changeId>                the per-change review dashboard
+ *   /<tenant>/preview/pr/<n>                  the friendly PR-number alias
+ *   /<tenant>/preview/rev/<sha>/...           the immutable per-revision renderer
  */
 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
+  // /<tenant>/preview/pr and /<tenant>/preview/pr/<n> — the PR-number alias.
+  if (/^\/[^/]+\/preview\/pr(?:\/|$)/.test(pathname)) return true;
+  // /<tenant>/preview/rev/<sha> and /<tenant>/preview/rev/<sha>/<path...> — the
   // immutable per-revision alias.
-  return /^\/preview\/[^/]+\/rev(?:\/|$)/.test(pathname);
+  return /^\/[^/]+\/preview\/rev(?:\/|$)/.test(pathname);
+}
+
+/**
+ * Admin surfaces, in BOTH the bare host-routed form (`/admin`, `/admin/...`) and
+ * the tenant-first path form (`/<tenant>/admin`, `/<tenant>/admin/...`, where the
+ * leading segment middleware-selects the tenant). Admin reuses the same
+ * loginGate/sessionAdmitsHost mechanism as public content — there is no separate
+ * password layer — so this predicate is what keeps the QA content bypass from ever
+ * reaching admin: /admin ALWAYS requires a real, valid session.
+ */
+export function isAdminPath(pathname: string): boolean {
+  if (pathname === "/admin" || pathname.startsWith("/admin/")) return true;
+  return /^\/[^/]+\/admin(?:\/|$)/.test(pathname);
+}
+
+/**
+ * Paths the QA content bypass must NEVER cover — everything privileged or
+ * state-mutating. The bypass is a convenience for browsing public tenant content
+ * (product/marketing pages) only; these fail toward requiring a real session:
+ *   - admin ({@link isAdminPath}) — the hard security requirement.
+ *   - the cockpit control-plane (`/cockpit`, `/<tenant>/cockpit`) and its `/dev`
+ *     redirect alias.
+ *   - every `/api/` route (tenant-state mutation). Genuinely-public API endpoints
+ *     are already gate-exempt via {@link isPublicPath}/{@link isAuthPath}, so
+ *     excluding all of `/api/` here costs nothing and fails safe.
+ */
+export function isBypassPrivilegedPath(pathname: string): boolean {
+  if (isAdminPath(pathname)) return true;
+  if (pathname === "/cockpit" || pathname.startsWith("/cockpit/")) return true;
+  if (/^\/[^/]+\/cockpit(?:\/|$)/.test(pathname)) return true;
+  if (pathname === "/dev" || pathname.startsWith("/dev/")) return true;
+  if (/^\/[^/]+\/dev(?:\/|$)/.test(pathname)) return true;
+  if (pathname === "/api" || pathname.startsWith("/api/")) return true;
+  return false;
 }
 
 export type LoginGateDecision =
@@ -192,6 +240,14 @@ export interface LoginGateInput {
    * exempt from the gate so it renders publicly. See {@link PUBLIC_HOME_TENANT_ID}.
    */
   tenantExempt?: boolean;
+  /**
+   * True when the request presented the server-configured QA bypass token (see
+   * `DEMO_GATE_BYPASS_TOKEN` in middleware). Only ever set in a QA/test deploy — an
+   * unset server token leaves it false, so this is fully inert by default. Passes
+   * the gate for PUBLIC CONTENT paths only; {@link isBypassPrivilegedPath} paths
+   * (admin, cockpit, /api) are never bypassed regardless of this flag.
+   */
+  qaBypass?: boolean;
 }
 
 /**
@@ -208,6 +264,12 @@ export function evaluateLoginGate(input: LoginGateInput): LoginGateDecision {
   // 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" };
+  // The static-bundle staging upload carries its own private_key_jwt auth.
+  if (isStaticBundleUploadPath(input.pathname)) return { action: "pass" };
+  // QA content-bypass: a request presenting the server-configured token passes for
+  // public content only. NEVER for admin/cockpit/api — that guard lives here (not
+  // just in middleware) so /admin stays gated even if the flag is set upstream.
+  if (input.qaBypass && !isBypassPrivilegedPath(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

@@ -1,7 +1,6 @@
 /**
  * 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`).
+ * "MCP machine identity" contract.
  *
  * 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
@@ -10,8 +9,7 @@
  * 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`).
+ * `.well-known/mcp-client-jwks.json` route).
  *
  * 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
@@ -30,6 +28,10 @@
  * 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.
+ * This same rule applies ACROSS EXECUTION ENVIRONMENTS, not just within this Worker:
+ * a different runtime (e.g. a CI pipeline) needing MCP machine identity gets its OWN
+ * confidential-client registration + keypair, never a copy of this one — see tot-mcp
+ * `devbook/app-binding.md` Recipe A ("multiple execution environments").
  */
 import { importPKCS8, exportJWK, SignJWT, type CryptoKey, type JWK, type JSONWebKeySet } from "jose";
 import { readEnv } from "@/lib/env";

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

@@ -0,0 +1,113 @@
+/**
+ * Shared machinery for storefront's two-path operator-session resolvers: a
+ * signed-in host-bound tenant viewer (path 1), else a Bearer operator secret
+ * (path 2), fail-closed if neither validates. The grants owner session
+ * (`../grants/session.ts`) and the Private Apps admin session
+ * (`../apps/adminSession.ts`) are both configured from these primitives, so the
+ * fail-closed ordering and the host-bound tenant derivation live in ONE audited
+ * place. Each resolver supplies only what genuinely differs — the result shape,
+ * the Bearer secret/env sourcing, the operator-capability set, and how a present
+ * viewer that lacks that capability is treated.
+ */
+import type { APIContext } from "astro";
+
+/** The host-bound viewer chrome the middleware sets on `locals.viewer`. */
+type Viewer = NonNullable<APIContext["locals"]["viewer"]>;
+
+/** The fail-closed shape both resolvers share for a refused session. */
+export type SessionFailure = { ok: false; status: number; message: string };
+
+/** Pure inputs to the Bearer-fallback authorization decision (env + request, no I/O). */
+export interface BearerOperatorInput {
+  /** The request `Authorization` header, if any. */
+  authHeader: string | null;
+  /** The configured operator gate secret (or undefined if unconfigured). */
+  gateSecret: string | undefined;
+  /** Server-configured principal for this deployment, preferred over the header. */
+  configuredPrincipal: string | undefined;
+  /** Requested-principal header — honoured ONLY once the Bearer authenticates. */
+  requestedPrincipal: string | null;
+  /** 503 message when the gate secret is unconfigured. */
+  unconfiguredMessage: string;
+  /** 400 message when no principal can be resolved. */
+  unresolvedMessage: string;
+}
+
+export type BearerOperatorResult = { ok: true; principal: string } | SessionFailure;
+
+/**
+ * The fail-closed Bearer-operator core, with NO I/O — unit-testable. The
+ * ordering is the security contract: unconfigured gate → 503, bad/absent Bearer
+ * → 401 (BEFORE any principal is read, so a bare caller cannot target another
+ * tenant by naming it in the requested-principal header), no resolvable
+ * principal → 400. The server-configured principal is preferred over the
+ * request header so a single-principal deploy cannot be redirected cross-tenant.
+ */
+export function authorizeBearerOperator(
+  input: BearerOperatorInput,
+): BearerOperatorResult {
+  if (!input.gateSecret) {
+    return { ok: false, status: 503, message: input.unconfiguredMessage };
+  }
+  if (input.authHeader !== `Bearer ${input.gateSecret}`) {
+    return { ok: false, status: 401, message: "Unauthorized" };
+  }
+  const principal = (
+    input.configuredPrincipal ??
+    input.requestedPrincipal ??
+    ""
+  ).trim();
+  if (!principal) {
+    return { ok: false, status: 400, message: input.unresolvedMessage };
+  }
+  return { ok: true, principal };
+}
+
+/**
+ * How to treat a signed-in viewer that IS present on the resolved host but lacks
+ * an operator capability. The two resolvers deliberately differ here:
+ *   - `fallThrough` — continue to the Bearer gate (grants' owner session), so a
+ *     lower-capability viewer that also presents a valid operator secret is
+ *     admitted via path 2 exactly as an unauthenticated headless caller is.
+ *   - `failClosed` — return the supplied 403 and do NOT consult the Bearer gate
+ *     (apps admin session), so an authenticated-but-insufficient viewer is never
+ *     silently admitted by a secret it happens to also present.
+ */
+export type InsufficientCapabilityPolicy =
+  | { mode: "fallThrough" }
+  | { mode: "failClosed"; failure: SessionFailure };
+
+export interface HostBoundSessionConfig<T> {
+  /** Capabilities that make a host-bound viewer an operator for their tenant. */
+  capabilities: ReadonlySet<string>;
+  /** How to treat a present-but-insufficient viewer (see the type). */
+  onInsufficientCapability: InsufficientCapabilityPolicy;
+  /** Build the success result from the authorized viewer + resolved host appDomain. */
+  resolveViewer: (viewer: Viewer, tenant: string) => Promise<T> | T;
+  /** The Bearer path (path 2), consulted whenever path 1 does not resolve. */
+  resolveBearer: (context: APIContext) => Promise<T | SessionFailure>;
+}
+
+/**
+ * Two-path host-bound operator session: a signed-in `locals.viewer` on the
+ * middleware-resolved `locals.tenant` (path 1), else the Bearer gate (path 2).
+ * The tenant is ALWAYS the resolved host `appDomain` — never the request body.
+ * When no viewer/tenant pair is present, or a present viewer is insufficient
+ * under a `fallThrough` policy, path 2 decides.
+ */
+export async function resolveHostBoundSession<T>(
+  context: APIContext,
+  config: HostBoundSessionConfig<T>,
+): Promise<T | SessionFailure> {
+  const viewer = context.locals?.viewer;
+  const tenant = context.locals?.tenant?.appDomain;
+  if (viewer && tenant) {
+    if (config.capabilities.has(viewer.capability)) {
+      return config.resolveViewer(viewer, tenant);
+    }
+    if (config.onInsufficientCapability.mode === "failClosed") {
+      return config.onInsufficientCapability.failure;
+    }
+  }
+  return config.resolveBearer(context);
+}

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

@@ -120,14 +120,54 @@ export function clearSessionCookie(context: APIContext): void {
   context.cookies.delete(SESSION_COOKIE, { path: "/" });
 }
 
+/** True if `s` contains any C0 control char (0x00–0x1F) or DEL (0x7F) — CR/LF
+ *  included, so a `next` value can never smuggle a header break or NUL. Written as
+ *  a charCode scan (not a control-char regex literal) so the source stays printable. */
+function hasControlChar(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c <= 0x1f || c === 0x7f) return true;
+  }
+  return false;
+}
+
 /**
- * Sanitize a `next` redirect target to a same-origin PATH only (starts with a
- * single "/", not "//" or a scheme) — closes the open-redirect hole. Falls back
- * to "/".
+ * Sanitize a post-sign-in `next`/returnTo redirect target to a same-origin,
+ * path-only reference — the single open-redirect chokepoint for the whole sign-in
+ * surface (the login gate, verify, and the shared `pr/<N>` reviewer link all funnel
+ * through here). Anything that could resolve off-origin falls back to "/".
+ *
+ * Rejected, because a browser would treat each as an ABSOLUTE/off-origin URL:
+ *   - a scheme or bare host      ("https://evil.com", "evil.com")
+ *   - protocol-relative          ("//evil.com")
+ *   - backslash-smuggled         ("/\evil.com", "\\evil.com") — browsers normalize
+ *     "\" → "/", so "/\evil.com" resolves as "//evil.com"
+ *   - encoded slash/backslash    ("/%2F%2Fevil.com", "/%5Cevil.com") that DECODES
+ *     to a protocol-relative form
+ *   - control chars / newlines   (header-injection belt-and-suspenders)
+ *   - malformed percent-encoding  (refuse rather than guess)
+ *
+ * The ORIGINAL (still-encoded) value is returned on success — decoding is only for
+ * the safety check, never for the redirect target.
  */
 export function safeNext(next: string | null | undefined): string {
   if (!next) return "/";
-  if (!next.startsWith("/") || next.startsWith("//")) return "/";
+  if (!next.startsWith("/")) return "/";
+  // No control chars / CR / LF anywhere (header-injection belt-and-suspenders).
+  if (hasControlChar(next)) return "/";
+  // Normalize backslashes to slashes the way a browser would, then reject any
+  // protocol-relative ("//host") form — raw or backslash-smuggled.
+  if (next.replace(/\\/g, "/").startsWith("//")) return "/";
+  // Defeat encoded slash/backslash smuggling: decode once and re-check that it is
+  // still a single-slash, same-origin path. Malformed encoding → refuse.
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(next);
+  } catch {
+    return "/";
+  }
+  const decodedNormalized = decoded.replace(/\\/g, "/");
+  if (!decodedNormalized.startsWith("/") || decodedNormalized.startsWith("//")) return "/";
   return next;
 }
 

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

@@ -20,7 +20,7 @@ export const SESSION_COOKIE = "tot_session";
 
 /**
  * A ToT-staff viewer's ACTIVE vendor selection — the two-phase-admission marker
- * (#8425 staff cross-vendor access). This is a DISTINCT access path from
+ * for staff cross-vendor access. This is a DISTINCT access path from
  * `tenants[]`: a staff user isn't a member of a bounded set of vendors, so we
  * NEVER synthesize a `tenants[]` entry for them. Instead, after the staff viewer
  * explicitly searches + enters a vendor and tot20's `staffVendorAccess` writes
@@ -43,25 +43,24 @@ export const DEFAULT_SESSION_TTL_SECONDS = 7 * 24 * 3600;
 /**
  * What we know about a signed-in viewer.
  *
- * Phase 3: `email`/`resource`/`roles`/`capability` are now derived from tot's
+ * `email`/`resource`/`roles`/`capability` are derived from tot's
  * OFFLINE-VERIFIED `id_token` claims (see `@/lib/auth/identityToken`
  * `sessionFromClaims`), not from trusting tot's flat `/verify` JSON. `capability`
  * is the coarse standing on `resource` (owner|admin|member). `tenants`/`staff`
- * are the multi-tenant claims carried in the verified token (present when the
- * session was minted via the Phase-3 path; optional for backward compatibility).
+ * are the multi-tenant claims carried in the verified token.
  */
 export interface SessionRecord {
   /** Verified email (lowercased) — the principal that passed the grant check. */
   email: string;
   /** The resource (appDomain/tenant, e.g. "sample-store.example") this session authorizes. */
   resource: string;
-  /** Display roles for `resource` (Phase 3: the coarse role from verified claims). */
+  /** Display roles for `resource` (the coarse role from verified claims). */
   roles: string[];
-  /** Coarse capability on `resource` (owner|admin|member; legacy: developer|inviter|staff|none). */
+  /** Coarse capability on `resource` (owner|admin|member). */
   capability: string;
-  /** All tenant memberships from the verified assertion (policy input). Phase-3 path only. */
+  /** All tenant memberships from the verified assertion (policy input). */
   tenants?: { resource: string; role: string }[];
-  /** ToT-staff scope from the verified assertion (sandboxed; grants nothing today). Phase-3 path only. */
+  /** ToT-staff scope from the verified assertion (sandboxed; grants nothing). */
   staff?: string[];
   /**
    * A staff viewer's active, explicitly-entered vendor selection (the two-phase

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

@@ -28,6 +28,7 @@
  */
 import { readEnv } from "@/lib/env";
 import { diagEmail } from "@/lib/diag/redact";
+import { FetchHttpTransport, type HttpResponseLike, type HttpTransport } from "@/lib/http/fetchTransport";
 import { classifyStepUp, type StepUpChallenge, type StepUpObligation } from "./stepUpChallenge.js";
 
 /** `send` is deliberately opaque — it never reveals whether the email was eligible. */
@@ -150,24 +151,13 @@ export type SmsVerifyResult =
 
 // --- HTTP transport seam (injected by tests) --------------------------------
 
-export interface HttpResponseLike {
-  status: number;
-  json(): Promise<unknown>;
-}
-export interface HttpTransport {
-  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
-}
+export type { HttpResponseLike, HttpTransport };
 
-/** Default transport: a JSON `fetch` POST. */
-export class FetchHttpTransport implements HttpTransport {
-  async post(url: string, headers: Record<string, string>, body: unknown) {
-    return fetch(url, {
-      method: "POST",
-      headers: { "content-type": "application/json", accept: "application/json", ...headers },
-      body: JSON.stringify(body),
-    });
-  }
-}
+/** Default transport: a JSON `fetch` POST that also sends `accept: application/json`. */
+const defaultTransport = () =>
+  new FetchHttpTransport({
+    defaultHeaders: { "content-type": "application/json", accept: "application/json" },
+  });
 
 export interface HttpTotAccessClientConfig {
   /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
@@ -193,7 +183,7 @@ export class HttpTotAccessClient implements TotAccessClient {
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
     this.apiKey = config.apiKey;
     this.secretKey = config.secretKey;
-    this.transport = config.transport ?? new FetchHttpTransport();
+    this.transport = config.transport ?? defaultTransport();
   }
 
   /**

package/apps/storefront/src/lib/basePath.ts

@@ -13,13 +13,20 @@
  *
  * It is idempotent and conservative: only root-absolute single-slash paths are
  * prefixed. Protocol-relative URLs ("//cdn…"), absolute URLs ("https://…"),
- * fragments/queries ("#x", "?x"), and already-prefixed paths pass through. This
- * mirrors the defense-in-depth client script in Layout.astro.
+ * fragments/queries ("#x", "?x"), and already-prefixed paths pass through. The
+ * GLOBAL static-asset namespaces are also left untouched — they are served at root
+ * under both routing modes and must NOT carry a tenant prefix:
+ *   - `/tenants/…` — per-tenant static assets (logo, favicon, theme/mkt css);
+ *   - `/shared/…`  — platform-shipped shared assets (shared commerce-chrome css).
+ * This mirrors both `prefixTenantLinks` (lib/rawMarketingHtml.ts) and the
+ * defense-in-depth client script in Layout.astro.
  */
 export function withBase(basePath: string, href: string): string {
   if (!basePath || !href) return href;
   // Only same-origin root-absolute paths; skip protocol-relative "//".
   if (href.charAt(0) !== "/" || href.charAt(1) === "/") return href;
+  // Global asset namespaces are root-served under every tenant; never prefix them.
+  if (href.startsWith("/tenants/") || href.startsWith("/shared/")) return href;
   // Already inside the prefix.
   if (href === basePath || href.startsWith(`${basePath}/`)) return href;
   return `${basePath}${href}`;

package/apps/storefront/src/lib/blog/access.ts

@@ -0,0 +1,29 @@
+import type { SessionRecord } from "@/lib/auth/session.js";
+import type { BlogAccess } from "./types.js";
+
+/**
+ * Whether a signed-in viewer counts as a paid member. v1: authenticated ⇒ member,
+ * because there is no consumer entitlement source yet. This is the single seam a
+ * future billing/entitlement integration plugs into — keep it a named export so
+ * routes and predicates never re-implement the "is a member" decision inline.
+ */
+export function isConsumerMember(_viewer: SessionRecord): boolean {
+  return true;
+}
+
+/**
+ * Entitlement chokepoint: may this viewer read the post's body? Orthogonal to
+ * visibility (`isVisibleOnLive`) — a gated post is still published/listed; this
+ * only decides full body vs teaser. Every reader path calls this one function.
+ */
+export function viewerHasBlogAccess(
+  viewer: SessionRecord | null,
+  post: { access?: BlogAccess },
+): boolean {
+  const need = post.access ?? "public";
+  if (need === "public") return true;
+  if (!viewer) return false;
+  if (need === "authenticated") return true;
+  if (need === "members") return isConsumerMember(viewer);
+  return false;
+}