@tokenoftrust/storefront-runner 1.4.0 → 1.4.1

package/apps/storefront/src/lib/activity/uiActor.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared emit helper for UI-ORIGINATED operational activity (card D6).
+ *
+ * The UI cohort's entry point onto the D0 actor×action telemetry contract. It sits
+ * ON TOP of D1's server emitter ({@link recordActivity}) — every admin/cockpit action
+ * handler already runs SERVER-SIDE in the same Worker, so a UI action reaches
+ * telemetry through the same in-process `recordActivity()` call D1 uses (one
+ * structured Workers-Logs line), NOT a client-side `fetch` to the D4 ingest endpoint.
+ * There is no browser-only signal to capture: an admin/cockpit "Publish / Connect /
+ * Invite / Approve / Rollback" click is a server-rendered form/JSON POST to an API
+ * route, so the route handler that already does the work is exactly where the emit
+ * belongs (zero extra HTTP round-trip, no new auth/trust boundary). The D4 HMAC
+ * ingest path exists for emitters that CAN'T call `recordActivity()` directly (the
+ * out-of-process CLI cohort, D3) — it is not this cohort's path.
+ *
+ * WHAT THIS ADDS over calling `recordActivity()` raw: it stamps `source: "ui"` and,
+ * critically, resolves the ACTOR KIND from the authenticated session so the timeline
+ * (D5) can attribute an action to the right cohort:
+ *
+ *   • "admin"    — a ToT-STAFF viewer (the session carries `staff[]` scope). ToT
+ *                  operators acting through the admin shell / staff vendor selection.
+ *   • "merchant" — a store OWNER acting on THEIR OWN store (a signed-in viewer whose
+ *                  host-bound capability is owner/admin). The self-serve cohort.
+ *   • "dev"      — a signed-in DEVELOPER viewer who is neither staff nor owner (e.g. a
+ *                  ship-on-behalf developer invited onto someone else's store).
+ *   • "agent"    — a HEADLESS, capability-driven caller with no human viewer session
+ *                  (the Bearer/CLI operator seam) — automation acting on the surface.
+ *
+ * The classifier is a PURE function ({@link classifyActorKind}) so the cohort mapping
+ * is unit-tested without a live request. The opaque `actor.id` is the salted,
+ * non-reversible hash of the acting identity (never raw PII in the core zone) — the
+ * SAME {@link hashActorId} + `ACTIVITY_ACTOR_SALT` D1 established, so one person stays
+ * correlatable across the CLI, server, and UI cohorts.
+ *
+ * USAGE (mirrors D1's reject.ts — resolve the actor ONCE after auth, emit at each
+ * exit point, zero change to the handler's control flow):
+ *
+ *   const actor = await resolveUiActor(context, { owner: auth.owner });
+ *   // …do the work…
+ *   recordUiActivity(actor, { action: "change.ship", outcome: { status: "succeeded" }, scope });
+ */
+import type { APIContext } from "astro";
+import type {
+  ActivityActor,
+  ActorKind,
+  ActivityOutcome,
+  ActivityScope,
+  ActivityPayload,
+} from "@tot/public-runtime";
+import type { ActionKey } from "@tot/public-runtime";
+import { readViewerSession } from "@/lib/auth/route";
+import { isStaffSession } from "@/lib/dashboard/staffAdmission";
+import { readEnv } from "@/lib/env";
+import { hashActorId, recordActivity } from "./recordActivity";
+
+/** The host-bound capabilities that mark a viewer as the store OWNER (merchant). */
+const OWNER_CAPABILITIES = new Set(["owner", "admin"]);
+
+/** The minimal viewer chrome the middleware stamps on `locals.viewer`. */
+interface ViewerLike {
+  email?: string;
+  capability?: string;
+}
+
+/**
+ * Classify the acting cohort from the authenticated session — PURE so the mapping is
+ * testable without a request. Order matters and is fail-safe:
+ *
+ *   1. no signed-in viewer  → "agent" (headless Bearer/CLI operator — capability-
+ *      driven automation; there is no human identity on this request).
+ *   2. ToT-staff session    → "admin" (checked BEFORE ownership: a staff viewer who
+ *      entered a vendor via a live selection carries an owner-ish host capability, but
+ *      they are ToT staff, not the merchant).
+ *   3. owner/admin capability on this host → "merchant" (the store owner on their own store).
+ *   4. otherwise            → "dev" (a signed-in developer without ownership, e.g.
+ *      ship-on-behalf).
+ */
+export function classifyActorKind(
+  viewer: ViewerLike | null | undefined,
+  session: { staff?: string[] } | null | undefined,
+): ActorKind {
+  if (!viewer?.email) return "agent";
+  if (isStaffSession(session)) return "admin";
+  if (viewer.capability && OWNER_CAPABILITIES.has(viewer.capability)) return "merchant";
+  return "dev";
+}
+
+export interface ResolveUiActorInput {
+  /**
+   * Fallback acting identity for the HEADLESS path (no signed-in viewer) — typically
+   * the resolved tenant owner (`auth.owner`). Only used to seed the opaque id when
+   * there is no viewer email; never stored raw (always hashed).
+   */
+  owner?: string;
+}
+
+/**
+ * Resolve the {@link ActivityActor} for a UI-originated action from the request's
+ * authenticated session. Reads the full viewer session ONCE (for the staff scope the
+ * host-bound `locals.viewer` chrome doesn't carry) and computes the opaque, salted
+ * actor id. Best-effort: any read fault degrades to a coarse non-PII actor rather
+ * than throwing — telemetry must never break the action it describes. Resolve this
+ * ONCE per request (after auth) and reuse the result across every emit exit point.
+ */
+export async function resolveUiActor(
+  context: APIContext,
+  input: ResolveUiActorInput = {},
+): Promise<ActivityActor> {
+  // The host-bound `locals.viewer` chrome omits `staff[]`, so read the full session
+  // to tell a ToT-staff (admin) actor from a store owner (merchant). Best-effort.
+  const session = await readViewerSession(context).catch(() => null);
+  // Prefer the host-scoped `locals.viewer` (set by middleware for tenant-gated
+  // surfaces — the ship/grants routes); fall back to the raw session's
+  // email/capability for a route that never went through that host gate (e.g. the
+  // /dev cockpit's rendezvous-approval endpoint) but still has a real signed-in
+  // viewer. Both describe the SAME signed-in-or-not shape.
+  const viewer: ViewerLike | undefined =
+    (context.locals?.viewer as ViewerLike | undefined) ??
+    (session ? { email: session.email, capability: session.capability } : undefined);
+  const kind = classifyActorKind(viewer, session);
+  const identifier = viewer?.email ?? input.owner ?? "system";
+  const id = await hashActorId(identifier, await readEnv("ACTIVITY_ACTOR_SALT"));
+  return { kind, id };
+}
+
+/**
+ * Emit ONE UI-originated activity event with a PRE-RESOLVED actor. A thin, SYNC
+ * wrapper over D1's {@link recordActivity} that stamps `source: "ui"` — so a handler
+ * calls it at each exit point (succeeded / failed / refused) exactly as D1's server
+ * emitters do, with no control-flow change. Best-effort + never throws (inherited
+ * from `recordActivity`).
+ */
+export function recordUiActivity(
+  actor: ActivityActor,
+  input: {
+    action: ActionKey;
+    outcome: ActivityOutcome;
+    scope?: ActivityScope;
+    payload?: ActivityPayload;
+  },
+): void {
+  recordActivity({
+    action: input.action,
+    actor,
+    source: "ui",
+    outcome: input.outcome,
+    ...(input.scope ? { scope: input.scope } : {}),
+    ...(input.payload ? { payload: input.payload } : {}),
+  });
+}

package/apps/storefront/src/lib/activity/workerCommit.ts

@@ -0,0 +1,70 @@
+/**
+ * worker_commit — build provenance for the running Worker (card D2).
+ *
+ * The commit SHA THIS Worker build was cut from, made available REPO-WIDE at
+ * runtime so every server-emitted ActivityEvent can carry it (see event.ts
+ * `ActivityScope.workerCommit`) and D5 can later derive **deploy skew** — "is the
+ * build serving this request == the pushed umbrella tip, or is a stale worker
+ * still live?".
+ *
+ * HOW IT GETS HERE. Workers have no filesystem/git at runtime, so the SHA is
+ * baked in at BUILD time: astro.config.mjs's Vite `define` replaces the
+ * `__GIT_SHA__` token with a string literal of the build's commit (CI-provided
+ * `GIT_SHA`/`WORKERS_CI_COMMIT_SHA`/`GITHUB_SHA`, else local `git rev-parse`,
+ * else "unknown"). This is the SAME source /health already reports (lib/health.ts)
+ * — we read it through the identical `typeof` guard so both agree by construction,
+ * and so the value is safe under vitest (where the define isn't applied → "unknown").
+ *
+ * This is the single accessor the whole repo threads through: D1's recordActivity()
+ * spreads serverActivityScope() into every server event; D2's deploy.version_observed
+ * emitter (deployVersion.ts) reads workerCommit() directly.
+ */
+import type { ActivityScope } from "@tot/public-runtime";
+
+/** Sentinel when the build had no git context (also the vitest value). */
+export const UNKNOWN_COMMIT = "unknown";
+
+/**
+ * The commit SHA this Worker build was cut from, or "unknown". Never throws; the
+ * `typeof` guard keeps it safe under vitest (the `__GIT_SHA__` define is only
+ * applied by the Astro/Vite build). Optionally overridable for tests.
+ */
+export function workerCommit(override?: string): string {
+  if (override != null) return override;
+  return typeof __GIT_SHA__ !== "undefined" ? __GIT_SHA__ : UNKNOWN_COMMIT;
+}
+
+/** First 7 chars of the build commit for eyeballing against `git log`, or "unknown". */
+export function workerCommitShort(override?: string): string {
+  const sha = workerCommit(override);
+  return sha === UNKNOWN_COMMIT ? UNKNOWN_COMMIT : sha.slice(0, 7);
+}
+
+/**
+ * True when the build has a real git commit (not the "unknown" sentinel). D5's
+ * skew derivation only compares against the umbrella tip when this holds — an
+ * "unknown" build can't be meaningfully skew-checked.
+ */
+export function hasKnownWorkerCommit(override?: string): boolean {
+  return workerCommit(override) !== UNKNOWN_COMMIT;
+}
+
+/**
+ * Build the CORE scope for a SERVER-sourced ActivityEvent with `worker_commit`
+ * stamped in. This is the seam D1's recordActivity() spreads into every server
+ * event so provenance is present WITHOUT each call site remembering it:
+ *
+ *   createActivityEvent({ ..., source: "server", scope: serverActivityScope({ tenantId }) })
+ *
+ * Pass the event's other scope fields (tenantId/changeId/traceId) as `extra`;
+ * workerCommit always wins for the `workerCommit` slot. Omits the field entirely
+ * when the build commit is "unknown" so a downstream skew query never mistakes the
+ * sentinel for a real deployed SHA.
+ */
+export function serverActivityScope(extra?: ActivityScope): ActivityScope {
+  const sha = workerCommit();
+  return {
+    ...extra,
+    ...(sha !== UNKNOWN_COMMIT ? { workerCommit: sha } : {}),
+  };
+}

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

@@ -30,6 +30,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/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/d1/schema-apps.ts

@@ -71,6 +71,60 @@ export const appAuditLog = sqliteTable(
   }),
 );
 
+// --- Operational activity timeline (activity-telemetry epic, card D4) --------
+// The low-volume / high-value LIFECYCLE cohort of the actor×action telemetry
+// spine (DECISIONS.md §8). Only actions whose catalog `spec.sinks` include
+// "timeline" land here; the high-volume cohort goes to Cloudflare Analytics
+// Engine (binding `ACTIVITY_ANALYTICS`), and EVERY action also goes to Workers
+// Logs. Reuses the EXISTING STOREFRONT_APPS_DB (precedent: `app_audit_log`
+// above) rather than a new binding — the cohort is small (~50k rows/month at
+// 10× pilot) and the D5 query UI needs point queries + joins + arbitrary
+// retention that Analytics Engine cannot give.
+//
+// `id` is the emitter-minted event UUID and the PRIMARY KEY, so a retried/
+// replayed ingest is idempotent (INSERT OR IGNORE). `tenant_id` is written from
+// the AUTHENTICATED ingest identity, never the client-supplied `scope.tenantId`
+// (see api/activity.ts) — that is the multi-tenant isolation boundary. `payload`
+// is the SERVER-redacted JSON (default-deny allowlist + canary scan re-applied
+// at ingest, never trusting client-side redaction alone). The core columns
+// mirror the `ActivityEvent` envelope's non-payload zone (packages/public-
+// runtime/src/activity/event.ts), flattened for SQL point queries.
+export const activityEvents = sqliteTable(
+  "activity_events",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    action: text("action").notNull(),
+    actorKind: text("actor_kind").notNull(),
+    // Opaque, pseudonymized actor id — NEVER raw email/PII (emitter's contract).
+    actorId: text("actor_id").notNull(),
+    actorRef: text("actor_ref"),
+    source: text("source").notNull(),
+    status: text("status").notNull(),
+    // Low-cardinality error CLASS, never a raw exception message.
+    errorClass: text("error_class"),
+    durationMs: integer("duration_ms"),
+    changeId: text("change_id"),
+    traceId: text("trace_id"),
+    // Server-redacted payload JSON (args + rendered lanes), default "{}".
+    payload: text("payload").notNull().default("{}"),
+    // Envelope contract version (ACTIVITY_SCHEMA_VERSION) so a reader can migrate.
+    schemaVersion: integer("schema_version").notNull(),
+    // Emit-clock ISO-8601 (the event's `at`).
+    at: text("at").notNull(),
+    // Server receive-clock ISO-8601 (when ingest stored it).
+    ingestedAt: text("ingested_at").notNull(),
+  },
+  (t) => ({
+    // The D5 timeline query: a tenant's events newest-first.
+    idxActivityTenantAt: index("idx_activity_tenant_at").on(t.tenantId, t.at),
+    // Filter a tenant's timeline by action family (dashboards glob the prefix).
+    idxActivityTenantAction: index("idx_activity_tenant_action").on(t.tenantId, t.action),
+    // Join a change's whole lifecycle span across actions.
+    idxActivityChange: index("idx_activity_change").on(t.changeId),
+  }),
+);
+
 // --- Webhook event spine (PrivateApps epic, D4 Chunk A) ---------------------
 // Immutable event log. `id` is the semantic event id we mint — distinct from
 // any per-delivery wire envelope id (see `webhookDeliveries.deliveryId` below).

package/apps/storefront/src/lib/dev/vcBinding.ts

@@ -0,0 +1,80 @@
+/**
+ * Cockpit safety-net for the 08-18 vc-app-binding gap (§5): ensure the signed-in
+ * developer is bound to storefront's version-control app so their `tot start`
+ * checkout (`tenant_checkout`) and the repo tools stop 403-ing "No version-control
+ * app is bound to your session."
+ *
+ * WHY a net at all: the ROOT fix binds every entitled human at the authority seams
+ * the MCP owns — grant issuance, rendezvous `/approve`, native OAuth token issuance
+ * — plus a one-shot backfill. Those cover the terminal path. This net covers the
+ * BROWSER-FIRST developer who reached /cockpit via the storefront's own tot20
+ * sign-in (a `tot_session` cookie) WITHOUT ever crossing an MCP binding seam, so
+ * they'd otherwise land at cockpit with a `tot start` command that 403s.
+ *
+ * HOW (mirrors cli-signin-approve): there is NO per-human MCP session server-side —
+ * the cockpit reaches the MCP only as the APP (private_key_jwt). So we re-issue a
+ * FRESH tot20-signed id_token for the VERIFIED session email (via the storefront's
+ * core credential — {@link reissueSubjectToken}, the same proof `/approve` sends)
+ * and pass it as the `subject_token` the MCP binds the enrollment to. The app can't
+ * assert an arbitrary subject; the MCP verifies the proof + the subject's LIVE
+ * entitlement and authors the binding under its own forge authority (ADR-0001).
+ *
+ * ALWAYS FAIL-OPEN: any gap (proof re-issue failed, MCP cold/unreachable, the
+ * endpoint not yet deployed) returns a typed `{ ok:false }` and NEVER throws — the
+ * cockpit must render regardless, and the authority-seam binding + backfill are the
+ * real guarantees. This is strictly a best-effort accelerator.
+ */
+import { createForgeClient } from "@/lib/forge";
+import { reissueSubjectToken } from "@/lib/dev/subjectReissue";
+
+export type EnsureCockpitBindingResult =
+  | { ok: true; bound: boolean; created: boolean }
+  | { ok: false; reason: string };
+
+export interface EnsureCockpitBindingDeps {
+  /** Override the subject-proof minter (tests). */
+  reissue?: typeof reissueSubjectToken;
+  /** Override the forge-client factory (tests) — returns something with ensureVcAppBinding. */
+  makeForgeClient?: () => Promise<{
+    ensureVcAppBinding(opts: {
+      subjectToken?: string;
+    }): Promise<{ bound: boolean; created: boolean }>;
+  }>;
+}
+
+/**
+ * Ensure the developer identified by their VERIFIED session `email` is bound to the
+ * storefront VC app. Best-effort + fail-closed-to-typed-error: never throws.
+ */
+export async function ensureCockpitVcBinding(
+  email: string,
+  deps: EnsureCockpitBindingDeps = {},
+): Promise<EnsureCockpitBindingResult> {
+  if (!email) return { ok: false, reason: "missing-identity" };
+
+  const reissue = deps.reissue ?? reissueSubjectToken;
+  let subjectToken: string;
+  try {
+    const proof = await reissue(email);
+    if (!proof.ok) return { ok: false, reason: `reissue-${proof.reason}` };
+    subjectToken = proof.idToken;
+  } catch {
+    // A re-issue fault must not surface as a cockpit 500.
+    return { ok: false, reason: "reissue-threw" };
+  }
+
+  try {
+    const client = deps.makeForgeClient
+      ? await deps.makeForgeClient()
+      : await createForgeClient();
+    const res = await client.ensureVcAppBinding({ subjectToken });
+    return { ok: true, bound: res.bound, created: res.created };
+  } catch (cause) {
+    // Fail-open: the ensure endpoint may not be deployed yet, or the MCP may be
+    // cold/unreachable. The proof itself is never logged; the reason is a terse code.
+    return {
+      ok: false,
+      reason: "mcp-" + (cause instanceof Error ? cause.name : "error"),
+    };
+  }
+}

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

@@ -40,6 +40,44 @@ export async function readEnv(key: string): Promise<string | undefined> {
   return fromBuild(key);
 }
 
+/** The slice of the Workers ExecutionContext runAfterResponse needs — the
+ *  @astrojs/cloudflare adapter exposes it to routes as `locals.cfContext`. */
+export interface CfExecutionContextLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/**
+ * Run `work` PAST the response — the request's `ExecutionContext.waitUntil`
+ * when the caller passes it, else a detached floating promise (dev/Node). For
+ * webhook RECEIVERS that must ACK fast: the upstream forwarder (tot-mcp
+ * gitea-webhook proxy) aborts its forward at 15s and Gitea bounds its delivery
+ * wait too, while a real reconcile takes tens of seconds — running it inside
+ * the request meant every healthy reconcile was killed mid-flight and recorded
+ * as `forward_failed` (a layer of Trello 13075, behind the auth fix).
+ *
+ * CALLERS MUST PASS `locals.cfContext` (the @astrojs/cloudflare adapter's
+ * per-request ExecutionContext, `createLocals: { cfContext: ctx }`): in the
+ * Workers runtime a merely-floating promise is CANCELLED the moment the
+ * response returns — an earlier revision here imported `waitUntil` from
+ * `cloudflare:workers` (not exported by this adapter/runtime version), silently
+ * degraded to the floating promise, and the async reconcile died unobserved
+ * right after its 202. The floating-promise branch is a DEV-ONLY fallback.
+ * Errors are the caller's to handle inside `work` (this never throws).
+ */
+export function runAfterResponse(
+  work: Promise<unknown>,
+  cfContext?: CfExecutionContextLike | null,
+): void {
+  const swallowed = work.catch(() => {});
+  if (cfContext && typeof cfContext.waitUntil === "function") {
+    cfContext.waitUntil(swallowed);
+    return;
+  }
+  // dev/Node only — in the Workers runtime this promise would be cancelled at
+  // response end, which is exactly the bug the parameter above exists to avoid.
+  void swallowed;
+}
+
 /** KV binding for the newsletter stub / tenant cache, if present in the runtime. */
 export async function readKv(binding: string): Promise<KVNamespace | undefined> {
   const w = await getWorkerEnv();
@@ -59,6 +97,19 @@ export async function readR2(binding: string): Promise<R2Bucket | undefined> {
   return (w?.[binding] as R2Bucket | undefined) ?? undefined;
 }
 
+/**
+ * Cloudflare Analytics Engine dataset binding (e.g. ACTIVITY_ANALYTICS), if
+ * present. Untyped (`unknown`) deliberately — the caller casts to its own
+ * minimal `writeDataPoint` shape (see `activity/store.ts`'s
+ * `AnalyticsEngineLike`) rather than this module taking a types dep. Absent in
+ * dev/Node and until the binding is provisioned; callers treat undefined as
+ * "analytics sink unavailable, skip it" (never an error).
+ */
+export async function readAnalytics(binding: string): Promise<unknown | undefined> {
+  const w = await getWorkerEnv();
+  return w?.[binding] ?? undefined;
+}
+
 /**
  * Cloudflare Queue producer binding (e.g. WEBHOOK_DELIVERY_QUEUE), if present.
  * Untyped (`unknown`) deliberately — callers cast to their own minimal

package/apps/storefront/src/lib/publish/shipWorkspace.ts

@@ -43,11 +43,15 @@
  * live only in S3 — enumerable by the Node-only `listRollbackTargets`
  * (`scripts/publish/lib/static-rollback.mjs`), NOT by the Worker. So the console
  * can list a static tenant's promotion history + `/rev` links + the CURRENT live
- * digest, but it cannot resolve an ARBITRARY prior version's archive digest, which
- * `/api/changes/rollback` fail-closed requires (`targetDigest`). `rollbackMode`
- * names this: a `control-plane` tenant rolls back one-click (targetVersionId only);
- * a `static-archive` tenant's per-version rollback is honestly deferred to the ship
- * CLI / CI that enumerates the archive — never a one-click that would 400.
+ * digest, but it cannot resolve an ARBITRARY prior version's archive digest. It
+ * therefore rolls a static tenant back by an HONEST ONE-DISPATCH (rux13):
+ * `/api/changes/rollback` accepts the `targetVersionId` alone, restores the pointer,
+ * and dispatches a CI job that resolves the digest from the archive by sourceSha
+ * (`rollback-s3.mjs --source-sha`) and re-publishes — reporting `publish_pending`
+ * until the re-publish is verified live (never a false "rolled back"). `rollbackMode`
+ * names the two paths: a `control-plane` tenant rolls back one-click via the pointer
+ * flip (instant); a `static-archive` tenant's rollback DISPATCHES via CI and
+ * completes asynchronously — the surface must say so, never imply an instant flip.
  */
 import { reviewDashboardRevisionHref } from "@/lib/preview/reviewDashboard";
 import {
@@ -98,9 +102,12 @@ export interface VersionsView {
   /** Whether the tenant publishes its public site to an external static target. */
   staticPublish: boolean;
   /**
-   * `control-plane` → a prior version rolls back one-click via `targetVersionId`.
-   * `static-archive` → per-version rollback is deferred to the ship CLI / CI that
-   * enumerates the `versions/` archive (the Worker can't resolve the archive digest).
+   * `control-plane` → a prior version rolls back one-click via `targetVersionId`
+   * (instant pointer flip).
+   * `static-archive` → the console rolls back by an honest ONE-DISPATCH: it sends
+   * `targetVersionId` alone and CI resolves the archive digest + re-publishes
+   * asynchronously (`publish_pending` until verified live) — the surface must say
+   * "completes via CI", never imply an instant flip.
    */
   rollbackMode: RollbackMode;
 }

package/apps/storefront/src/middleware/index.ts

@@ -54,6 +54,8 @@ import { gatedHoldingResponse } from "@/lib/auth/gatePage";
 import { readSession, KvSessionStore, SESSION_COOKIE } from "@/lib/auth/session";
 import { isMaintenanceOn, maintenanceResponse } from "@/lib/maintenance";
 import { HEALTH_PATH, healthResponse } from "@/lib/health";
+import { observeDeployVersion } from "@/lib/activity/deployVersion";
+import { primeActivityKillSwitch } from "@/lib/activity/killSwitch";
 import type { DeepPartial, ThemeTokens } from "@tot/public-runtime";
 
 export const onRequest = defineMiddleware(async (context, next) => {
@@ -62,6 +64,21 @@ export const onRequest = defineMiddleware(async (context, next) => {
   const host =
     request.headers.get("host") ?? url.host ?? "localhost";
 
+  // ---- Activity telemetry kill switch (card D8) -----------------------------
+  // Prime the ONE `ACTIVITY_TELEMETRY_DISABLED` flag from the (async) Worker env
+  // once per isolate, BEFORE the first emit, so every telemetry chokepoint in this
+  // isolate (deploy-provenance, recordActivity, ingest) observes it. Fail-open,
+  // never throws. Off by default (unset ⇒ telemetry on).
+  await primeActivityKillSwitch();
+
+  // ---- Deploy provenance (card D2) — worker_commit / deploy.version_observed -
+  // Once per worker isolate (cold start), emit `deploy.version_observed` carrying
+  // this build's commit SHA so D5 can derive deploy skew (running build vs umbrella
+  // tip). Idempotent per isolate, best-effort, never throws — so it's safe here at
+  // the very front door, ahead of /health, and fires regardless of Host/tenant/gate.
+  // A no-op when the D8 kill switch above is set.
+  observeDeployVersion();
+
   // ---- /health — liveness + deploy-identity probe ---------------------------
   // Answered FIRST: before tenant resolution, the access gate, the maintenance
   // kill-switch, and the edge cache — so it reports the running build's commit SHA