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

package/packages/public-runtime/src/activity/event.ts

@@ -0,0 +1,168 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ActivityEvent — the versioned actor×action telemetry envelope (card D0).
+//
+// One event = "an ACTOR performed an ACTION, here is the OUTCOME." It is the
+// single shape every operational-activity emitter produces and every sink
+// stores, across the whole storefront platform (dev/CLI first, then merchant/
+// admin/agent). Downstream cards import this directly:
+//   D1 server recordActivity() · D2 deploy provenance · D3 CLI emitActivity
+//   D4 ingest+store · D5 query/timeline UI · D6/D7 alerts.
+//
+// TWO ZONES, and the split is load-bearing:
+//   1. CORE fields (everything except `payload`) — always safe to store. They
+//      carry NO free-text and NO third-party PII by construction: ids are
+//      opaque, error is a low-cardinality CLASS, action is an allowlisted
+//      catalog key. A core field is never redacted because it can never hold a
+//      secret.
+//   2. `payload` (args / rendered) — the extensible, ALWAYS-REDACTED zone.
+//      Whatever a call site puts here is default-DENIED: only the keys the
+//      action's allowlist names survive, and even those are canary-scanned.
+//      See redaction.ts. You cannot construct an event whose payload skipped
+//      redaction — use createActivityEvent() (redaction.ts), not a bare object.
+//
+// This package is the node-free, dependency-free edge base (see index.ts): the
+// envelope stays pure data + pure functions so server, edge, and the JS CLI
+// mirror can all consume it. ActionKey lives in catalog.ts (type-only import
+// here — no runtime cycle).
+// ─────────────────────────────────────────────────────────────────────────────
+import type { ActionKey } from "./catalog.js";
+
+/**
+ * Envelope contract version. Bump ONLY on a breaking change to a CORE field
+ * (add/remove/retype). Adding a new action key, sink, or allowlist entry is NOT
+ * breaking and does NOT bump this. Sinks store this so a reader can migrate old
+ * rows. Kept as a literal-typed const so `v` is `1`, not `number`.
+ */
+export const ACTIVITY_SCHEMA_VERSION = 1 as const;
+export type ActivitySchemaVersion = typeof ACTIVITY_SCHEMA_VERSION;
+
+/** WHO acted. Deliberately a small closed set — ingest can reject a mismatch. */
+export type ActorKind = "dev" | "merchant" | "admin" | "agent" | "system";
+
+/** WHERE the event originated. */
+export type ActivitySource = "cli" | "server" | "ui";
+
+/**
+ * Invoked/result semantics. `invoked` = the action started (fire-and-forget or
+ * the open half of an invoke/result pair); the terminal statuses close it.
+ * `refused` is distinct from `failed`: the platform DECLINED the action (a
+ * capability/authz gate said no) — it never ran — vs it ran and errored.
+ */
+export type ActivityStatus = "invoked" | "succeeded" | "failed" | "refused";
+
+/** Which store(s) an action lands in. The store decision is per-action policy,
+ * declared on each catalog entry — see catalog.ts ActionSpec.sinks and
+ * DECISIONS.md §8. `logs` is universal; `analytics` = high-volume/query-light;
+ * `timeline` = low-volume/queryable ops UI. */
+export type ActivitySink = "logs" | "analytics" | "timeline";
+
+export interface ActivityActor {
+  kind: ActorKind;
+  /**
+   * OPAQUE, stable actor id. NEVER a raw email / phone / name — the core zone is
+   * unredacted, so a raw PII id here would defeat the whole contract. Emitters
+   * pseudonymize before constructing the event (a stable hash of the email, an
+   * install id, an app-domain, "system"). The canonical pseudonymization salt is
+   * an OPEN QUESTION owned by D1/D4 (see redaction.ts header); until it lands,
+   * emitters use an already-opaque handle (install id, hashed email, app domain).
+   */
+  id: string;
+  /**
+   * Optional secondary opaque reference (e.g. a hashed email used to correlate a
+   * dev across CLI + UI). Still core, still MUST be non-reversible / non-PII.
+   */
+  ref?: string;
+}
+
+export interface ActivityScope {
+  /** Tenant / store id (tenant_id or app domain). Core, non-secret. */
+  tenantId?: string;
+  /** ShipLoop change/candidate id, when the action is change-scoped. */
+  changeId?: string;
+  /**
+   * Correlation id spanning an invite→terminal→problem span. Matches the
+   * existing `traceId` already threaded through the dev bridge + runtime record,
+   * so a CLI event and the server event it triggered share one trace.
+   */
+  traceId?: string;
+  /**
+   * BUILD PROVENANCE (card D2). The git commit SHA the running server/edge build
+   * was cut from — stamped by the emitter onto every SERVER-sourced event so the
+   * query surface (D5) can derive **deploy skew**: is the build that produced this
+   * event == the pushed umbrella tip, or is a stale worker still serving? Core,
+   * non-secret by construction (a 40-hex git sha, never PII/free-text), so it is
+   * never redacted. Absent on `cli`/`ui`-sourced events and on any build with no
+   * git context (reported as "unknown" by the stamper, see the storefront's
+   * workerCommit() accessor). This is `worker_commit` in the D2 vocabulary — the
+   * value the standalone `deploy.version_observed` action also carries in payload.
+   */
+  workerCommit?: string;
+}
+
+export interface ActivityOutcome {
+  status: ActivityStatus;
+  /**
+   * Stable, LOW-CARDINALITY error class — never a raw exception message (which
+   * can carry secrets/PII and blows up cardinality). e.g. "capability_denied",
+   * "forge_5xx", "node_too_old", "not_found". Free-text detail, if truly needed,
+   * goes through payload.rendered and its allowlist, never here.
+   */
+  errorClass?: string;
+  /** Wall-clock duration of the action in ms, when known. */
+  durationMs?: number;
+}
+
+/**
+ * The extensible, ALWAYS-REDACTED payload zone. Both lanes are default-DENY:
+ * only keys named by the action's allowlist survive redaction; every other key
+ * is DROPPED (never stored, never "logged raw then redacted later").
+ */
+export interface ActivityPayload {
+  /** Structured machine input to the action (e.g. { command, exitCode }). */
+  args?: Record<string, unknown>;
+  /** Human-readable strings for a UI timeline (e.g. { description, reason }). */
+  rendered?: Record<string, string>;
+}
+
+/**
+ * The wire + storage envelope. Field names are short because this is written at
+ * volume (Analytics Engine blobs, Workers Logs lines, D1 columns).
+ */
+export interface ActivityEvent {
+  /** Envelope contract version (see ACTIVITY_SCHEMA_VERSION). */
+  v: ActivitySchemaVersion;
+  /** Unique event id (UUID v4). Idempotency key for the ingest/store path. */
+  id: string;
+  /** ISO 8601 UTC timestamp, emit clock. */
+  at: string;
+  actor: ActivityActor;
+  /** ALLOWLISTED catalog key — never a free string. See catalog.ts. */
+  action: ActionKey;
+  source: ActivitySource;
+  scope: ActivityScope;
+  outcome: ActivityOutcome;
+  /** Post-redaction payload. Absent when the action carries no allowlisted args. */
+  payload?: ActivityPayload;
+}
+
+/** True when `at` is a parseable ISO-8601 instant. Cheap ingest guard (D4). */
+export function isIsoTimestamp(at: unknown): at is string {
+  return typeof at === "string" && !Number.isNaN(Date.parse(at));
+}
+
+/** Node-free UUID v4. Uses the platform crypto (Workers + Node ≥19 global), with
+ * a getRandomValues fallback so the edge bundle never imports `node:crypto`. */
+export function newEventId(): string {
+  const c: Crypto | undefined = (globalThis as { crypto?: Crypto }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  const b = new Uint8Array(16);
+  (c?.getRandomValues ? c.getRandomValues(b) : fillMathRandom(b));
+  b[6] = ((b[6] as number) & 0x0f) | 0x40;
+  b[8] = ((b[8] as number) & 0x3f) | 0x80;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0"));
+  return `${h[0]}${h[1]}${h[2]}${h[3]}-${h[4]}${h[5]}-${h[6]}${h[7]}-${h[8]}${h[9]}-${h[10]}${h[11]}${h[12]}${h[13]}${h[14]}${h[15]}`;
+}
+
+function fillMathRandom(b: Uint8Array): void {
+  for (let i = 0; i < b.length; i++) b[i] = Math.floor(Math.random() * 256);
+}

package/packages/public-runtime/src/activity/index.ts

@@ -0,0 +1,16 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// @tot/public-runtime/activity — the operational activity telemetry contract.
+//
+// Card D0: the actor×action ActivityEvent envelope, the allowlisted action
+// catalog, and the default-deny redaction contract. This is the FOUNDATION the
+// downstream cards import directly — nothing here does I/O or picks a store; it
+// is pure types + pure functions so server, edge, and the CLI's JS mirror can
+// all consume it. The store DECISION and cost model live in the repo-root
+// DECISIONS.md §8; the per-action routing lives on each catalog entry (sinks).
+//
+// See ./README.md for the envelope shape, catalog rules, redaction contract,
+// and the CLI-mirror keep-in-step obligation for card D3.
+// ─────────────────────────────────────────────────────────────────────────────
+export * from "./event.js";
+export * from "./catalog.js";
+export * from "./redaction.js";

package/packages/public-runtime/src/activity/redaction.ts

@@ -0,0 +1,263 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Redaction contract for the activity payload zone (card D0).
+//
+// This is the surface card D8 (adversarial PII/secret-leak review) will attack,
+// so the posture is deliberately conservative. Three layers, in order:
+//
+//   1. DEFAULT-DENY ALLOWLIST. For a given action, ONLY the top-level payload
+//      keys named in its ActionSpec (argsAllow / renderedAllow) are eligible to
+//      be stored. Every other key is DROPPED — not stored, not logged, not
+//      "kept raw and redacted later". There is no path that persists an
+//      un-allowlisted field.
+//
+//   2. PRIMITIVE-ONLY VALUES. An allowlisted value must be a string / number /
+//      boolean. Objects, arrays, functions are DROPPED — nested structures are
+//      where secrets hide, and we will not walk them. (If a future action
+//      genuinely needs structured args, it flattens them at the call site into
+//      named primitive keys and allowlists each.)
+//
+//   3. CANARY SCAN. Even an allowlisted primitive is scanned for secret/PII
+//      shapes (JWTs, bearer tokens, API keys, private keys, emails, card/phone
+//      numbers) AND secret-looking KEY NAMES. A hit replaces the value with a
+//      redaction marker and is REPORTED (the fact of the hit, never the value) so
+//      D6/D7 can alert and D8 can audit. A secret-named key is dropped outright.
+//
+// The safe constructor createActivityEvent() runs all three before an event is
+// ever returned — you cannot build an event whose payload skipped redaction.
+//
+// OPEN QUESTION (owned by D1/D4): the canonical actor-id pseudonymization salt.
+// This module scrubs PII that leaks into the PAYLOAD, but actor.id in the CORE
+// zone is the emitter's responsibility to pseudonymize. A shared, salted,
+// non-reversible hash helper (with the salt as a Worker secret) should land with
+// D1's recordActivity()/D4's ingest — do NOT bake a weak unsalted hash here.
+// ─────────────────────────────────────────────────────────────────────────────
+import {
+  ACTIVITY_SCHEMA_VERSION,
+  newEventId,
+  type ActivityEvent,
+  type ActivityActor,
+  type ActivityScope,
+  type ActivityOutcome,
+  type ActivityPayload,
+  type ActivitySource,
+} from "./event.js";
+import { getActionSpec, type ActionKey, type ActionSpec } from "./catalog.js";
+
+/** Marker stored in place of a value that tripped a canary (never the raw value). */
+export const REDACTION_MARKER = "«redacted»";
+/** Cap on a stored rendered/arg string — a stored operational value is never long;
+ * capping bounds row/blob size and shrinks the blast radius of a missed secret. */
+export const MAX_VALUE_LEN = 512;
+
+/**
+ * Secret/PII VALUE canaries — deny-by-default even inside an allowlisted field.
+ * Conservative on purpose: a false positive costs one redacted ops field; a false
+ * negative is a leaked secret. Ordered roughly most- to least-specific. Named so
+ * a report can say WHICH canary fired (the label), never the matched text.
+ */
+export const VALUE_CANARIES: readonly { label: string; re: RegExp }[] = [
+  { label: "private_key", re: /-----BEGIN(?: [A-Z]+)? PRIVATE KEY-----/ },
+  { label: "jwt", re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/ },
+  { label: "bearer", re: /\bBearer\s+[A-Za-z0-9._~+/-]{12,}=*/i },
+  { label: "aws_access_key", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { label: "gh_token", re: /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}/ },
+  { label: "slack_token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/ },
+  { label: "openai_key", re: /\bsk-[A-Za-z0-9]{20,}/ },
+  { label: "email", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/ },
+  { label: "card_number", re: /\b(?:\d[ -]?){13,19}\b/ },
+  { label: "phone", re: /\b\+?\d[\d ().-]{9,}\d\b/ },
+  // High-entropy long token: ≥28 chars of base64url with no spaces. Last resort.
+  { label: "high_entropy", re: /(?:^|[^A-Za-z0-9_-])[A-Za-z0-9_-]{28,}(?:$|[^A-Za-z0-9_-])/ },
+];
+
+/**
+ * Secret-looking KEY NAMES — dropped outright even if (mistakenly) allowlisted.
+ * Defense in depth: an allowlist edit that names one of these can never leak.
+ */
+// NB: matched as a substring of the key name, so entries must be specific enough
+// not to eat legitimate fields — e.g. a bare `code` would swallow `exitCode`.
+// Single-use codes are VALUES (caught by the value canaries + the CLI's own
+// --code redaction), not key names, so `code` is deliberately NOT here.
+export const KEY_NAME_CANARY = /(?:secret|token|passwd|password|authorization|api[_-]?key|private[_-]?key|credential|cookie|session|bearer|jwt)/i;
+
+export interface RedactionFieldHit {
+  lane: "args" | "rendered";
+  key: string;
+  /** Why the field was scrubbed/dropped. */
+  reason: "not_allowlisted" | "non_primitive" | "key_name_canary" | "value_canary" | "unknown_action";
+  /** The canary label, when reason === "value_canary". Never the matched text. */
+  canary?: string;
+}
+
+export interface RedactionReport {
+  /** Fields kept (after passing all three layers). */
+  keptArgs: string[];
+  keptRendered: string[];
+  /** Fields dropped or value-redacted, with the reason (for D8 audit / D6 alerts). */
+  hits: RedactionFieldHit[];
+  /** True if any value-canary fired — the signal an alert rule watches. */
+  canaryTripped: boolean;
+}
+
+function isPrimitive(v: unknown): v is string | number | boolean {
+  const t = typeof v;
+  return t === "string" || t === "number" || t === "boolean";
+}
+
+/** Scan a stringified value against the value canaries. Returns the first label hit. */
+export function scanValueCanary(value: string): string | undefined {
+  for (const c of VALUE_CANARIES) if (c.re.test(value)) return c.label;
+  return undefined;
+}
+
+/**
+ * CORE-zone identifier canaries — the STRUCTURED secret/PII shapes only.
+ *
+ * The core zone (actor.id / actor.ref, and the scope ids) is UNREDACTED by design and
+ * its contract is "opaque, never raw PII/secret". Unlike a payload value, a core id is
+ * SUPPOSED to be a high-entropy opaque handle (a salted hash `h_…`, a UUID install id,
+ * an app domain). So this scan deliberately EXCLUDES three VALUE_CANARIES that cannot
+ * distinguish a leak from a legitimate opaque id:
+ *   • `high_entropy` — every opaque id is high-entropy by construction;
+ *   • `card_number` / `phone` — a numeric hash / UUID segment is a bare digit run,
+ *     structurally identical to a card/phone; scanning for them would reject legitimate
+ *     numeric ids (e.g. an all-hex-digit hash, a digit-heavy UUID segment).
+ * What REMAINS are the STRUCTURED shapes that never occur in an opaque id but ARE the
+ * accidental-PII/secret an emitter most plausibly forgets to pseudonymize: an `@` email,
+ * a `eyJ…` JWT, a `Bearer …` header, `AKIA…`/`ghp_…`/`xox…`/`sk-…` cloud keys, a
+ * `-----BEGIN … PRIVATE KEY-----`. Used by D4 ingest to enforce the "core carries no
+ * PII by construction" invariant the payload contract already enforces.
+ */
+const CORE_IDENTIFIER_EXCLUDED = new Set(["high_entropy", "card_number", "phone"]);
+const CORE_IDENTIFIER_CANARIES: readonly { label: string; re: RegExp }[] = VALUE_CANARIES.filter(
+  (c) => !CORE_IDENTIFIER_EXCLUDED.has(c.label),
+);
+
+/**
+ * Scan a CORE-zone identifier (actor.id / actor.ref / scope id) for a RAW, STRUCTURED
+ * secret/PII SHAPE. Returns the canary label on a hit, else undefined. Excludes the
+ * high-entropy / card / phone canaries so a legitimate opaque id (hash / UUID / domain)
+ * is never flagged, while a raw email / JWT / bearer / cloud-key / private-key still is.
+ * Length-capped like a payload value.
+ */
+export function scanCoreIdentifier(value: string): string | undefined {
+  const s = value.slice(0, MAX_VALUE_LEN);
+  for (const c of CORE_IDENTIFIER_CANARIES) if (c.re.test(s)) return c.label;
+  return undefined;
+}
+
+function redactLane(
+  lane: "args" | "rendered",
+  raw: Record<string, unknown> | undefined,
+  allow: readonly string[],
+  hits: RedactionFieldHit[],
+): Record<string, string | number | boolean> | undefined {
+  if (!raw) return undefined;
+  const allowSet = new Set(allow);
+  const out: Record<string, string | number | boolean> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    // Layer 3b: secret-named key — drop regardless of allowlist.
+    if (KEY_NAME_CANARY.test(key)) {
+      hits.push({ lane, key, reason: "key_name_canary" });
+      continue;
+    }
+    // Layer 1: default-deny allowlist.
+    if (!allowSet.has(key)) {
+      hits.push({ lane, key, reason: "not_allowlisted" });
+      continue;
+    }
+    // Layer 2: primitives only.
+    if (!isPrimitive(value)) {
+      hits.push({ lane, key, reason: "non_primitive" });
+      continue;
+    }
+    // Layer 3a: value canary scan on the stringified, length-capped value.
+    const str = String(value).slice(0, MAX_VALUE_LEN);
+    const canary = scanValueCanary(str);
+    if (canary) {
+      hits.push({ lane, key, reason: "value_canary", canary });
+      out[key] = REDACTION_MARKER;
+      continue;
+    }
+    out[key] = typeof value === "string" ? str : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Apply the redaction contract to a raw payload for a given action. Pure. Returns
+ * the redacted payload (safe to store) plus a report of what was kept/dropped and
+ * whether a canary tripped. An unknown action yields an empty payload (deny-all).
+ */
+export function redactPayload(
+  action: string,
+  raw: ActivityPayload | undefined,
+): { payload: ActivityPayload | undefined; report: RedactionReport } {
+  const hits: RedactionFieldHit[] = [];
+  const spec: ActionSpec | undefined = getActionSpec(action);
+  if (!spec) {
+    if (raw?.args) for (const k of Object.keys(raw.args)) hits.push({ lane: "args", key: k, reason: "unknown_action" });
+    if (raw?.rendered) for (const k of Object.keys(raw.rendered)) hits.push({ lane: "rendered", key: k, reason: "unknown_action" });
+    return { payload: undefined, report: { keptArgs: [], keptRendered: [], hits, canaryTripped: false } };
+  }
+  const args = redactLane("args", raw?.args, spec.argsAllow, hits);
+  const renderedRaw = redactLane("rendered", raw?.rendered, spec.renderedAllow, hits);
+  // rendered is declared as string-valued; coerce (canary marker + capped strings
+  // are already strings, primitives stringify safely).
+  const rendered = renderedRaw
+    ? Object.fromEntries(Object.entries(renderedRaw).map(([k, v]) => [k, String(v)]))
+    : undefined;
+  const payload: ActivityPayload | undefined = args || rendered ? { ...(args ? { args } : {}), ...(rendered ? { rendered } : {}) } : undefined;
+  return {
+    payload,
+    report: {
+      keptArgs: args ? Object.keys(args) : [],
+      keptRendered: rendered ? Object.keys(rendered) : [],
+      hits,
+      canaryTripped: hits.some((h) => h.reason === "value_canary"),
+    },
+  };
+}
+
+export interface CreateActivityEventInput {
+  action: ActionKey;
+  actor: ActivityActor;
+  source: ActivitySource;
+  outcome: ActivityOutcome;
+  scope?: ActivityScope;
+  /** RAW payload — WILL be redacted before the event is returned. */
+  payload?: ActivityPayload;
+  /** Override the timestamp (tests / replaying a reported client event). */
+  at?: string;
+  /** Override the id (idempotent re-ingest). Defaults to a fresh UUID. */
+  id?: string;
+}
+
+/**
+ * The SAFE constructor — the only sanctioned way to build an ActivityEvent.
+ * Fills v/id/at, and runs the raw payload through redactPayload() so the returned
+ * event's payload is already default-denied + canary-scanned. Returns the event
+ * plus the redaction report (D4 ingest logs the report / emits
+ * `system.ingest.rejected` if a canary tripped; D1 recordActivity() can ignore it).
+ * Throws only on an out-of-catalog action (a programming error — deny by default).
+ */
+export function createActivityEvent(input: CreateActivityEventInput): {
+  event: ActivityEvent;
+  report: RedactionReport;
+} {
+  const spec = getActionSpec(input.action);
+  if (!spec) throw new Error(`activity: unknown action "${input.action}" (not in catalog)`);
+  const { payload, report } = redactPayload(input.action, input.payload);
+  const event: ActivityEvent = {
+    v: ACTIVITY_SCHEMA_VERSION,
+    id: input.id ?? newEventId(),
+    at: input.at ?? new Date().toISOString(),
+    actor: input.actor,
+    action: input.action,
+    source: input.source,
+    scope: input.scope ?? {},
+    outcome: input.outcome,
+    ...(payload ? { payload } : {}),
+  };
+  return { event, report };
+}

package/packages/public-runtime/src/candidate-index.ts

@@ -102,6 +102,19 @@ export interface ReviewEnvironment {
   lastError: string | null;
   /** ISO 8601 timestamp of the last time this projection was recomputed. */
   updatedAt: string;
+  /**
+   * ISO 8601 instant of the last `candidate-submitted` ack this record was
+   * (re)born or reset from (see `@tot/private-controlplane`'s
+   * `applyCandidateSubmittedAck` — the sync-path "ack at submit" keystone that
+   * seeds this projection BEFORE the async reconcile webhook ever fires, so a
+   * dead/unregistered webhook shows as "queued since <submittedAt>, never
+   * picked up" instead of no record at all). Additive + optional: every OTHER
+   * writer of this projection (`reconcileCandidate`, `acceptCandidateAtomic`,
+   * retire/GC) predates this field and simply carries it forward unset/
+   * untouched — only the submit-ack path ever sets it. Deliberately distinct
+   * from `updatedAt`, which every writer bumps on any recompute for any reason.
+   */
+  submittedAt?: string;
 }
 
 /** KV key for one tenant-change `ReviewEnvironment` projection. */

package/packages/public-runtime/src/catalog-d1.ts

@@ -1,6 +1,6 @@
 /**
  * D1 (edge SQLite) catalog read-model — schema + row projections (the one-store
- * target from epics/edge-read-replica.md). The storefront reads search, faceted
+ * target). The storefront reads search, faceted
  * listing, and full products from D1; the ETL emits the rows. This is the shared
  * contract both sides agree on.
  *

package/packages/public-runtime/src/customization-preview.ts

@@ -142,6 +142,8 @@ export interface EnvResolutionInput {
   /** Platform preview-signing secret (env), if configured. */
   secret?: string | null;
   nowSeconds: number;
+  /** Request pathname — used only to exempt the token dispenser itself (see {@link isPreviewDispatcherPath}). */
+  pathname?: string;
 }
 
 export interface EnvResolution {
@@ -152,16 +154,37 @@ export interface EnvResolution {
   reject?: { status: number; message: string };
 }
 
+/**
+ * The bare tenant-preview DISPATCHER path (`/<tenant>/preview` or
+ * `/<tenant>/preview/`, e.g. `pages/preview/index.astro`, tenant-first) — the page
+ * whose ENTIRE job is to mint a fresh `__preview` token and hand it to the
+ * visitor. On a preview-prefixed host this path would otherwise hit the SAME
+ * "no token -> 401" gate `resolveCustomizationEnv` enforces for every other
+ * path, deadlocking a signed-in-but-token-less visitor: they can never reach
+ * the one page that gives them a token. Distinct from `isCandidatePreviewPath`
+ * (loginGate.ts) — that exempts several preview routes from the LOGIN wall; this
+ * exempts exactly ONE route from the TOKEN wall. `<tenant>` is required to look
+ * like a real tenant id (contains a `.`) so this never accidentally matches a
+ * sibling route. Matched on the pre-strip request path.
+ */
+export function isPreviewDispatcherPath(pathname: string): boolean {
+  const m = pathname.match(/^\/([^/]+)\/preview\/?$/);
+  return m != null && m[1]!.includes(".");
+}
+
 /**
  * Decide which customization environment to serve. Production hosts always get
  * `live` and never consult a token. Preview hosts are auth-gated: a valid,
  * unexpired, tenant-matching token yields `test` (noindex); anything else is
- * rejected.
+ * rejected. The one exception is the token-dispenser path itself (see
+ * {@link isPreviewDispatcherPath}) — it renders the dispatcher's own minimal
+ * page, never tenant content, so it's let through as `live`/no-token rather
+ * than 401ing on the very request that would otherwise fetch it a token.
  */
 export async function resolveCustomizationEnv(
   input: EnvResolutionInput,
 ): Promise<EnvResolution> {
-  if (!input.isPreviewHost) {
+  if (!input.isPreviewHost || isPreviewDispatcherPath(input.pathname ?? "")) {
     return { env: "live", noindex: false };
   }
   if (!input.secret) {