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

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

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/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;
+}