@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -1,33 +1,32 @@
 /**
- * Ship operations workspace (unit dg7) — the PURE composer behind the admin
+ * Ship operations workspace — the PURE composer behind the admin
  * Publish tab's operations surface that sits ALONGSIDE the go-live core
  * (AdminPublishTab.astro's change queue + accept/reject + dispatch status).
  *
- * dg7 is DELTA-scoped: the go-live session already delivered the Publish-tab
- * core (the change queue from GET /api/changes, Go-live/Reject, the live-version
- * + dispatch-status panel, and the owner-only Domain section). This module adds
- * the operations workspace BEYOND that core — the three read/act surfaces woven
- * into the same tab:
+ * This module composes the operations workspace ALONGSIDE the Publish-tab core
+ * (the change queue from GET /api/changes, Go-live/Reject, the live-version +
+ * dispatch-status panel, and the owner-only Domain section) — the three read/act
+ * surfaces woven into the same tab:
  *
  *   1. DIFF VIEW  — for one pending candidate, the artifact-level diff of what
  *      changed (its rendered immutable version vs the current live version),
- *      tied to the exact tenant Gitea head SHA, with the u5 immutable
- *      `/preview/<tenant>/rev/<sha>/` link and the dg3 evidence AUTHORITY
+ *      tied to the exact tenant Gitea head SHA, with the immutable
+ *      `/<tenant>/preview/rev/<sha>/` link and the evidence AUTHORITY
  *      (authoritative / stale / missing) — never a diff a reviewer would mistake
  *      for the head when a last-good version actually renders.
  *   2. VERSIONS  — the tenant's published-version / promotion history
- *      (`listPromotions`, u2/u3 promotion_status), each row carrying the tenant
- *      Gitea SHA (`gitea-only-tenant-content-authority`), its promotion time, a
+ *      (`listPromotions`, promotion_status), each row carrying the tenant
+ *      Gitea SHA, its promotion time, a
  *      `/rev/<sha>/` link, and — marking the current live one.
  *   3. ROLLBACK  — pick a prior version and roll back THROUGH the one orchestrator
- *      (`/api/changes/rollback` → `rollbackCandidateAtomic` / u8's
+ *      (`/api/changes/rollback` → `rollbackCandidateAtomic` /
  *      `staticRollbackOrchestrator`), rendering only the HONEST terminal state
  *      (`rolled_back` when VERIFIED; `publish_pending` in flight; `publish_failed`
  *      / `blocked` fail-closed) — never a false "rolled back".
  *
  * COMPOSES, never rebuilds:
- *   - the u5 immutable link is `reviewDashboardRevisionHref` verbatim;
- *   - the dg3 authority is `candidateEvidenceAuthority` /
+ *   - the immutable link is `reviewDashboardRevisionHref` verbatim;
+ *   - the authority is `candidateEvidenceAuthority` /
  *     `classifyCandidateForRender` verbatim;
  *   - the versions come from the SAME `KVVersionStore.listPromotions` the
  *     "one step back" rollback resolution reads;
@@ -38,22 +37,16 @@
  * decision is unit-tested without a Worker/KV — mirroring the reviewDashboard.ts /
  * candidatePreviewState.ts split.
  *
- * HONEST BOUNDARY (surfaced, never faked): a FULLY-STATIC tenant serves its public
- * site from an external `versions/<digest>/` archive whose per-version treeDigests
- * 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. 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.
+ * `rollbackMode` names the path a rollback is honestly driven by: a `control-plane`
+ * (hosted) tenant and a `pointer` (static-publish) tenant BOTH roll back one-click
+ * via the instant KV `live` pointer flip — the Worker serves whatever bundle the
+ * pointer's digest names (from R2, for a static tenant), so restoring the pointer IS
+ * the rollback. The `publish_pending`/`publish_failed`/`blocked` honesty model from
+ * `interpretRollbackResponse` below applies identically in both modes — only the
+ * digest column (surfaced for a static tenant) differs.
  */
 import { reviewDashboardRevisionHref } from "@/lib/preview/reviewDashboard";
+import { assignVersionNumbers } from "@/lib/publish/versionNumber";
 import {
   candidateEvidenceAuthority,
   classifyCandidateForRender,
@@ -64,11 +57,45 @@ import type { ReviewEnvironment, PromotionEvent } from "@tot/public-runtime";
 
 // ── Versions / promotion history ───────────────────────────────────────────
 
-/** One published version in the tenant's promotion history (u2/u3 promotion_status). */
+/** The plain-language "what shipped in this version" model (same shape the staged
+ *  release summary uses — a name + a lead sentence + one highlight per included change). */
+export interface VersionReleaseSummary {
+  /** The human-readable release name (see `deriveReleaseName`), or null. */
+  name: string | null;
+  lead: string;
+  highlights: { title: string; detail: string }[];
+}
+
+/** One change that shipped in a published version — its PR summary, for the
+ *  version's openable "what shipped" list. Fields degrade to null/`PR #N` when
+ *  candidate_summary didn't cover the PR (best-effort enrichment). */
+export interface WorkspaceVersionChange {
+  changeId: string;
+  prNumber: number | null;
+  headSha: string;
+  title: string | null;
+  description: string | null;
+  fileCount: number | null;
+  linesAdded: number | null;
+  linesRemoved: number | null;
+}
+
+/** Per-version release enrichment, keyed by versionId (== the promoted aggregate sha). */
+export interface VersionReleaseInfo {
+  releaseSummary: VersionReleaseSummary | null;
+  changes: WorkspaceVersionChange[];
+}
+
+/** One published version in the tenant's promotion history (promotion_status). */
 export interface WorkspaceVersion {
-  /** The tenant Gitea SHA the version serves — the content identity
-   *  (`gitea-only-tenant-content-authority`). */
+  /** The tenant Gitea SHA the version serves — the content identity. */
   versionId: string;
+  /**
+   * The merchant-facing monotonic version number ("v42") — derived from first
+   * promotion order (see `versionNumber.ts`), shared with the "Live version"
+   * metric. The human label; the SHA is demoted to a technical disclosure.
+   */
+  number: number | null;
   /** How the version was published (a Gitea commit, or a content hash). */
   source: "commit" | "hash" | null;
   /** ISO time the version was PROMOTED onto `live` (the promotion event). */
@@ -84,30 +111,46 @@ export interface WorkspaceVersion {
    * digest lives only in the S3 archive the Worker can't enumerate. Never fabricated.
    */
   digest: string | null;
-  /** The u5 immutable `/preview/<tenant>/rev/<sha>/` deep-link, or `null` without a SHA. */
+  /** The immutable `/<tenant>/preview/rev/<sha>/` deep-link, or `null` without a SHA. */
   revHref: string | null;
   /** The version currently serving live (the one you never roll back TO). */
   isCurrent: boolean;
+  /**
+   * The plain-language "what shipped in this version" summary, composed from the
+   * release receipt's included PRs + their candidate_summary. `null` when no
+   * receipt links this version to a PR set, or none carried summary prose.
+   */
+  releaseSummary: VersionReleaseSummary | null;
+  /**
+   * The PRs that shipped in this version (from its release receipt), each with its
+   * human summary — the version's openable "what shipped" list. Empty when no
+   * receipt links this version to a PR set.
+   */
+  changes: WorkspaceVersionChange[];
+  /** How many changes shipped in this version, or `null` when unknown (no receipt). */
+  changeCount: number | null;
 }
 
-/** How a rollback is honestly driven for this tenant (see the module HONEST BOUNDARY note). */
-export type RollbackMode = "control-plane" | "static-archive";
+/**
+ * How a rollback is honestly driven for this tenant. `control-plane` (hosted) and
+ * `pointer` (static-publish) both roll back one-click via the instant KV `live`
+ * pointer flip; they render identical instant "Roll back" copy, differing only in
+ * whether the static digest column is shown.
+ */
+export type RollbackMode = "control-plane" | "pointer";
 
 /** The versions-panel view model. */
 export interface VersionsView {
   /** The current live version + (static) the digest `live/` actually serves. */
-  current: { versionId: string | null; digest: string | null };
+  current: { versionId: string | null; number: number | null; digest: string | null };
   /** Promotion history, newest first, current marked. */
   versions: WorkspaceVersion[];
   /** 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`
-   * (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.
+   * `control-plane` (hosted) and `pointer` (static-publish) both roll back
+   * one-click via `targetVersionId` (instant KV pointer flip) and render identical
+   * instant "Roll back" copy.
    */
   rollbackMode: RollbackMode;
 }
@@ -129,6 +172,12 @@ export interface BuildVersionsViewInput {
   currentDigest: string | null;
   /** Per-version manifest facts, keyed by versionId (absent ⇒ unknown facts). */
   manifests: Map<string, VersionManifestFacts>;
+  /**
+   * Per-version release enrichment, keyed by versionId (== the promoted aggregate
+   * sha on the release receipt). Absent ⇒ a version with no linked PR set (an
+   * honest empty release summary + no changes list — never fabricated).
+   */
+  releases?: Map<string, VersionReleaseInfo>;
   staticPublish: boolean;
 }
 
@@ -136,16 +185,31 @@ export interface BuildVersionsViewInput {
  * Assemble the versions panel from the promotion history + per-version manifest
  * facts + the current-live pointer. Pure. The current live row is marked; the
  * digest is populated ONLY for the current live of a static tenant (never faked
- * for priors). `revHref` is the u5 immutable link.
+ * for priors). `revHref` is the immutable link.
  */
 export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
-  const { tenantId, promotions, currentVersionId, currentDigest, manifests, staticPublish } = input;
+  const {
+    tenantId,
+    promotions,
+    currentVersionId,
+    currentDigest,
+    manifests,
+    releases,
+    staticPublish,
+  } = input;
+
+  // The merchant-facing "v42" counter, derived from first-promotion order — the
+  // SAME derivation `resolveLiveVersion` feeds the "Live version" metric, so the
+  // panel and the metric always agree on a version's number.
+  const numbers = assignVersionNumbers(promotions);
 
   const versions: WorkspaceVersion[] = promotions.map((p) => {
     const facts = manifests.get(p.versionId);
+    const release = releases?.get(p.versionId);
     const isCurrent = currentVersionId != null && p.versionId === currentVersionId;
     return {
       versionId: p.versionId,
+      number: numbers.get(p.versionId) ?? null,
       source: facts?.source ?? null,
       promotedAt: p.at,
       createdAt: facts?.createdAt ?? null,
@@ -154,14 +218,21 @@ export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
       digest: isCurrent && staticPublish ? currentDigest : null,
       revHref: reviewDashboardRevisionHref(tenantId, p.versionId),
       isCurrent,
+      releaseSummary: release?.releaseSummary ?? null,
+      changes: release?.changes ?? [],
+      changeCount: release ? release.changes.length : null,
     };
   });
 
   return {
-    current: { versionId: currentVersionId, digest: staticPublish ? currentDigest : null },
+    current: {
+      versionId: currentVersionId,
+      number: currentVersionId != null ? numbers.get(currentVersionId) ?? null : null,
+      digest: staticPublish ? currentDigest : null,
+    },
     versions,
     staticPublish,
-    rollbackMode: staticPublish ? "static-archive" : "control-plane",
+    rollbackMode: staticPublish ? "pointer" : "control-plane",
   };
 }
 
@@ -182,13 +253,13 @@ export interface CandidateDiffView {
   headSha: string | null;
   /** The immutable version actually rendered + diffed — the reconcile ACTUAL. */
   versionId: string | null;
-  /** The u5 immutable link to the exact reviewed SHA, or `null` without a head SHA. */
+  /** The immutable link to the exact reviewed SHA, or `null` without a head SHA. */
   revHref: string | null;
-  /** dg3 evidence authority: authoritative (tied to head) / stale (last-good) / missing. */
+  /** Evidence authority: authoritative (tied to head) / stale (last-good) / missing. */
   authority: CandidateEvidenceAuthority;
   /** The artifact-level diff (candidate rendered version vs current live), sorted by path. */
   files: DiffEntry[];
-  /** True when the candidate has a renderable version to diff (dg3 `ready`). */
+  /** True when the candidate has a renderable version to diff (the `ready` classification). */
   renderable: boolean;
   /** When NOT renderable, the honest reason (names why) — never a fake empty diff. */
   blockedReason: string | null;
@@ -206,7 +277,7 @@ export interface BuildCandidateDiffInput {
 /**
  * Diff a candidate's rendered version against the current live version, at the
  * artifact level (each path carries a content hash in its site-version manifest).
- * Composes dg3's `classifyCandidateForRender` (only a `ready` candidate has a
+ * Composes `classifyCandidateForRender` (only a `ready` candidate has a
  * version to diff — a blocked/queued one yields an HONEST `blockedReason`, never a
  * fabricated empty diff) and `candidateEvidenceAuthority` (so a diff of a last-good
  * version that LAGS the head is flagged `stale`, not passed off as the head).
@@ -289,10 +360,9 @@ export interface RollbackOutcome {
  * for BOTH planes without the surface having to know which it hit:
  *   - a HOSTED (control-plane) rollback returns `{ rolledBack: true, toVersionId }`
  *     on success (the pointer flip IS the rollback) or `{ error, reason }` on refusal;
- *   - a STATIC rollback returns the orchestrator's honest `{ state, ... }` (u8).
+ *   - a STATIC rollback returns the orchestrator's honest `{ state, ... }`.
  * The rule the surface depends on: `rolledBack` is true ONLY for a verified
- * `rolled_back` — a `publish_pending` is NEVER rendered as rolled back
- * (`storefront-atomic-accept-is-ship-orchestrator` / `static-publish-fails-closed`).
+ * `rolled_back` — a `publish_pending` is NEVER rendered as rolled back.
  * Pure.
  */
 export function interpretRollbackResponse(

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

@@ -0,0 +1,119 @@
+/**
+ * The shared "buffer-or-stream on `Accept`" plumbing for a long-running admin
+ * route. ONE emit-driven work function serves BOTH transports:
+ *
+ *   - a non-streaming caller (the CLI, any `Accept: application/json` client) gets
+ *     the buffered terminal JSON body + status the work resolved — `emit` is a no-op;
+ *   - a streaming caller (`Accept: text/event-stream`, the admin Publish tab) gets
+ *     each `emit(event, data)` as an SSE frame AS IT HAPPENS, then a terminal
+ *     `result` event carrying the SAME payload the JSON body would have, then close.
+ *
+ * The work runs ONCE either way; the terminal payload + status are IDENTICAL. Only
+ * the delivery differs. This is the generalized form of the pattern
+ * `POST /api/preview/build` first shipped inline — extracted here so every
+ * long-running route (build / integrate / rebuild / ship) streams the same way
+ * without re-implementing the ReadableStream/encoder/close dance.
+ */
+
+/**
+ * A buffered JSON Response — the non-streaming terminal body. Inlined (not imported
+ * from the change/grants controlplane) so this generic transport helper stays in the
+ * `lib/publish` render layer, respecting the renderer-no-controlplane boundary.
+ */
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/** Emit one SSE event. A no-op in buffered (JSON) mode. */
+export type SseEmit = (event: string, data: Record<string, unknown>) => void;
+
+/** The terminal outcome of the work: the HTTP status + the JSON/`result` payload. */
+export interface StreamWorkResult {
+  status: number;
+  payload: Record<string, unknown>;
+}
+
+/** True when the caller asked for an SSE stream (`Accept: text/event-stream`). */
+export function wantsEventStream(request: Request): boolean {
+  return (request.headers.get("accept") || "").includes("text/event-stream");
+}
+
+/**
+ * Run `work` and deliver its terminal payload as either a buffered JSON Response
+ * (default) or a streamed SSE Response (when the caller sent
+ * `Accept: text/event-stream`). In stream mode each `emit` becomes an
+ * `event: <name>\ndata: <json>\n\n` frame; the terminal payload is sent as a
+ * `result` event and the stream closes. `onError` maps an UNEXPECTED throw (the
+ * work is expected to be fail-safe and return its own error payload) to a terminal
+ * result — in JSON mode it becomes the response body+status, in SSE mode the
+ * `result` event.
+ */
+export async function respondBufferedOrStreamed(
+  request: Request,
+  work: (emit: SseEmit) => Promise<StreamWorkResult>,
+  opts?: { onError?: (error: unknown) => StreamWorkResult },
+): Promise<Response> {
+  const onError =
+    opts?.onError ??
+    ((error: unknown): StreamWorkResult => ({
+      status: 500,
+      payload: {
+        ok: false,
+        outcome: "failed",
+        errors: [`operation failed: ${error instanceof Error ? error.message : String(error)}`],
+      },
+    }));
+
+  // Buffered JSON mode — the CLI / any non-streaming caller. `emit` is a no-op; the
+  // work's own status + payload are returned verbatim (same contract as before).
+  if (!wantsEventStream(request)) {
+    try {
+      const { status, payload } = await work(() => {});
+      return jsonResponse(payload, status);
+    } catch (error) {
+      const { status, payload } = onError(error);
+      return jsonResponse(payload, status);
+    }
+  }
+
+  // SSE mode — stream each phase as it happens, then a terminal `result` event
+  // carrying the SAME payload the JSON body would have, then close. Workers stream a
+  // ReadableStream body natively — no infra.
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const send: SseEmit = (event, data) => {
+        try {
+          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+        } catch {
+          /* controller already closed (client disconnected) — nothing to do */
+        }
+      };
+      void (async () => {
+        try {
+          const { payload } = await work(send);
+          send("result", payload);
+        } catch (error) {
+          send("result", onError(error).payload);
+        } finally {
+          try {
+            controller.close();
+          } catch {
+            /* already closed */
+          }
+        }
+      })();
+    },
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      "x-accel-buffering": "no",
+    },
+  });
+}

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

@@ -0,0 +1,215 @@
+/**
+ * Authenticated static-bundle STAGING upload — the Worker-side write surface that
+ * lets CI stage a materialized bundle's objects into the `STATIC_BUNDLES` R2
+ * binding WITHOUT a static R2 S3-compatible key pair (`R2_ACCESS_KEY_ID`/
+ * `R2_SECRET_ACCESS_KEY`). CI proves identity with the SAME OIDC→AWS→SSM→
+ * `private_key_jwt` chain it already uses to authenticate to MCP
+ * (`scripts/publish/ci-mcp-read-remote.mjs`): it mints a short-lived RS256
+ * `client_assertion` under its dedicated confidential client
+ * (`storefront-ci.tokenoftrust.com` / kid `storefront-ci-publish-1`, the key held
+ * only in SSM), audience-bound to THIS upload endpoint, and the Worker verifies
+ * the signature against that client's PUBLISHED public JWKS.
+ *
+ * This is a WRITE path to a production-serving bucket, so the auth boundary is
+ * deliberately as strong as the MCP leg:
+ *   - RS256 signature over the CI client's JWKS (no shared static secret).
+ *   - `iss == sub == <expected CI client id>` (RFC 7523 §3).
+ *   - `aud == <this exact upload endpoint>` (RFC 8707 resource binding) — an
+ *     assertion minted for MCP's token endpoint can never be replayed here, and
+ *     vice versa.
+ *   - `exp`/`iat` freshness (jose enforces `exp`; assertions live ~60s).
+ *   - `jti` one-time-use replay rejection (KV-backed), mirroring MCP's replay
+ *     store — so a captured assertion can't be replayed inside its TTL window.
+ *   - Object key confined to `versions/<digest>/…`: a valid CI credential can
+ *     only write immutable version archives, never the `live/` pointer or any
+ *     other bucket key.
+ *
+ * The KEY SCHEME (`versions/<digest>/<rel>`) MUST byte-match the read side
+ * (`@tot/public-runtime` `staticBundleObjectKey`/`staticBundleManifestKey`) and
+ * the CI writer (`scripts/publish/lib/r2-publish.mjs` `r2ObjectKey`) — the same
+ * lockstep those two already keep. MANIFEST-LAST ordering (the manifest is the
+ * "fully staged" signal) is the CALLER's responsibility (CI writes it last, the
+ * same as `writeBundleToR2`); this surface writes exactly the one object it is
+ * handed per request.
+ */
+import { createLocalJWKSet, jwtVerify, type JSONWebKeySet, type JWTPayload } from "jose";
+
+/** The only signature algorithm accepted (matches the CI minter). */
+export const STAGE_BUNDLE_UPLOAD_ALG = "RS256";
+
+/** The route this surface is mounted at — the canonical `aud`/resource identifier. */
+export const STAGE_BUNDLE_UPLOAD_PATH = "/api/publish/stage-bundle";
+
+/** Default CI confidential-client id (`iss == sub`), overridable per env. */
+export const DEFAULT_STAGE_BUNDLE_UPLOAD_ISSUER = "storefront-ci.tokenoftrust.com";
+
+/** How long a used `jti` is remembered — the assertion TTL (~60s) plus clock skew. */
+export const STAGE_BUNDLE_JTI_TTL_SECONDS = 120;
+
+/** Clock skew tolerated on `exp`/`iat`, in seconds. */
+const CLOCK_TOLERANCE_SECONDS = 5;
+
+/**
+ * The `versions/<digest>/<rel>` keys a CI credential is allowed to write. The
+ * digest is a lowercase hex tree digest; `rel` is a bundle-relative POSIX path
+ * with no traversal. Anything else (a bare key, `live/…`, an absolute path, a
+ * `..` segment) is refused with 400 — the write authority is bounded to
+ * immutable version archives regardless of a valid signature.
+ */
+const VERSION_KEY_RE = /^versions\/[a-f0-9]{8,}\/.+$/;
+
+/** Minimal R2 surface this module needs — structural, so tests pass a fake. */
+export interface StageBundleUploadBucket {
+  head(key: string): Promise<{ key: string } | null>;
+  put(
+    key: string,
+    value: ArrayBuffer | ArrayBufferView,
+    options?: { httpMetadata?: { contentType?: string } },
+  ): Promise<unknown>;
+}
+
+/**
+ * One-time-use `jti` store. `checkAndRemember` returns `true` when the `jti` was
+ * unseen (and records it), `false` when it was already used (a replay). Backed by
+ * KV in the deployed Worker; omitted in dev/tests where no KV is bound (replay
+ * protection then relies on the ~60s `aud`-bound `exp` window alone).
+ */
+export interface JtiReplayStore {
+  checkAndRemember(jti: string, ttlSeconds: number): Promise<boolean>;
+}
+
+export interface StageBundleUploadConfig {
+  /** The CI client's published PUBLIC JWKS (verifies the assertion signature). */
+  jwks: JSONWebKeySet;
+  /** Expected `iss == sub` (the CI confidential-client id). */
+  issuer: string;
+  /** Expected `aud` — this exact upload endpoint URL (RFC 8707 resource). */
+  audience: string;
+}
+
+/** A KV-namespace-shaped store (`get`/`put`) — the deployed jti replay backing. */
+export interface JtiKvLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+}
+
+/** Build a KV-backed {@link JtiReplayStore}. Keyed under a dedicated prefix. */
+export function kvJtiReplayStore(kv: JtiKvLike): JtiReplayStore {
+  return {
+    async checkAndRemember(jti, ttlSeconds) {
+      const key = `stage-bundle-jti:${jti}`;
+      if (await kv.get(key)) return false;
+      // KV's minimum expirationTtl is 60s; the TTL default already exceeds it.
+      await kv.put(key, "1", { expirationTtl: Math.max(60, ttlSeconds) });
+      return true;
+    },
+  };
+}
+
+function json(status: number, body: Record<string, unknown>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/** Extract the bearer assertion from the Authorization header, or null. */
+function bearer(request: Request): string | null {
+  const h = request.headers.get("authorization");
+  if (!h) return null;
+  const m = /^Bearer (.+)$/.exec(h.trim());
+  return m ? m[1]!.trim() : null;
+}
+
+/**
+ * Verify the CI `client_assertion`: RS256 signature over the configured JWKS,
+ * `iss`/`sub`/`aud` exact match, `exp` freshness, and one-time `jti`. Returns the
+ * verified payload, or a `Response` (401) to return verbatim on any failure — no
+ * failure detail beyond a stable machine reason is leaked.
+ */
+export async function verifyUploadAssertion(
+  token: string,
+  config: StageBundleUploadConfig,
+  jtiStore?: JtiReplayStore,
+): Promise<{ payload: JWTPayload } | { reject: Response }> {
+  let payload: JWTPayload;
+  try {
+    const keys = createLocalJWKSet(config.jwks);
+    ({ payload } = await jwtVerify(token, keys, {
+      algorithms: [STAGE_BUNDLE_UPLOAD_ALG],
+      issuer: config.issuer,
+      audience: config.audience,
+      clockTolerance: CLOCK_TOLERANCE_SECONDS,
+    }));
+  } catch {
+    // Signature, iss/aud mismatch, or expiry — one opaque 401 (never which).
+    return { reject: json(401, { error: "invalid_assertion" }) };
+  }
+  // RFC 7523 §3: sub must equal the client id (iss). jose verifies iss but not
+  // that sub matches it, so assert it explicitly.
+  if (payload.sub !== config.issuer) {
+    return { reject: json(401, { error: "invalid_assertion" }) };
+  }
+  const jti = typeof payload.jti === "string" ? payload.jti : "";
+  if (!jti) {
+    return { reject: json(401, { error: "invalid_assertion" }) };
+  }
+  if (jtiStore) {
+    const fresh = await jtiStore.checkAndRemember(jti, STAGE_BUNDLE_JTI_TTL_SECONDS);
+    if (!fresh) return { reject: json(401, { error: "assertion_replayed" }) };
+  }
+  return { payload };
+}
+
+/** True iff `key` is a well-formed, traversal-free `versions/<digest>/<rel>` key. */
+export function isSafeVersionKey(key: string): boolean {
+  if (!VERSION_KEY_RE.test(key)) return false;
+  return !key.split("/").some((seg) => seg === ".." || seg === "." || seg === "");
+}
+
+/**
+ * Handle one authenticated staging request against `bucket`:
+ *   - `PUT  ?key=versions/<digest>/<rel>` — write the request body as that object.
+ *   - `HEAD ?key=versions/<digest>/<rel>` — 200 if present, 404 if not (the CI
+ *     idempotency probe, mirroring `r2ObjectExists`).
+ * Both require a valid CI assertion; the key is confined to `versions/<digest>/`.
+ */
+export async function handleStageBundleUpload(opts: {
+  request: Request;
+  bucket: StageBundleUploadBucket;
+  config: StageBundleUploadConfig;
+  jtiStore?: JtiReplayStore;
+}): Promise<Response> {
+  const { request, bucket, config, jtiStore } = opts;
+  const method = request.method.toUpperCase();
+  if (method !== "PUT" && method !== "HEAD") {
+    return json(405, { error: "method_not_allowed" });
+  }
+
+  const token = bearer(request);
+  if (!token) return json(401, { error: "missing_bearer" });
+
+  // HEAD is a read/probe and must NOT consume the one-time jti (a PUT retry after
+  // a probe would then falsely 401 as a replay). Only PUT records the jti.
+  const verified = await verifyUploadAssertion(
+    token,
+    config,
+    method === "PUT" ? jtiStore : undefined,
+  );
+  if ("reject" in verified) return verified.reject;
+
+  const key = new URL(request.url).searchParams.get("key") ?? "";
+  if (!isSafeVersionKey(key)) {
+    return json(400, { error: "invalid_key" });
+  }
+
+  if (method === "HEAD") {
+    const obj = await bucket.head(key);
+    return new Response(null, { status: obj ? 200 : 404 });
+  }
+
+  const body = await request.arrayBuffer();
+  const contentType = request.headers.get("content-type") ?? undefined;
+  await bucket.put(key, body, contentType ? { httpMetadata: { contentType } } : undefined);
+  return json(200, { key, staged: true });
+}