@tokenoftrust/storefront-runner 2.0.9 → 2.0.11

package/apps/storefront/integrations/materialize-guard.mjs

@@ -34,7 +34,13 @@ export function materializeGuard() {
         const onlyTenants = scoped.length > 0 ? scoped : null;
         const frameworkOnly = onlyTenants === null || process.env.TOT_FRAMEWORK_ONLY_BUILD === "1";
         if (frameworkOnly) {
-          const { problems } = checkPinned(undefined, { expectRef, allowUnpinned, onlyTenants });
+          // Framework mode never treats tenant content as a build input (it's
+          // resolved from KV/R2 per request), so the guard checks ZERO
+          // tenants here — onlyTenants=[] scopes checkPinned to an empty
+          // set (not "all tenants", which `null` would mean), so a sibling
+          // tenant that is present-but-stale can never block this build.
+          const frameworkOnlyTenants = [];
+          const { problems } = checkPinned(undefined, { expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
           const absent = problems.filter((p) => p.reason === "absent");
           const real = problems.filter((p) => p.reason !== "absent");
           if (absent.length) {
@@ -43,7 +49,7 @@ export function materializeGuard() {
             else console.log(msg);
           }
           if (real.length) {
-            assertPinnedMaterialized({ expectRef, allowUnpinned, onlyTenants });
+            assertPinnedMaterialized({ expectRef, allowUnpinned, onlyTenants: frameworkOnlyTenants });
           }
           return;
         }

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

@@ -28,6 +28,13 @@ import { readEnv } from "@/lib/env";
 /** The audience tot20's broker verifier pins. */
 export const BROKER_AUDIENCE = "tot20-broker";
 
+/**
+ * The ONLY place an assertion may travel — a header, never a query string, so the
+ * subject never lands in access logs, proxy logs or browser history. tot20 reads
+ * it case-insensitively (`readAssertion`, `operatorGrants-api.routes.node.js`).
+ */
+export const BROKER_ASSERTION_HEADER = "X-ToT-Broker-Assertion";
+
 /** The only algorithm the storefront broker signs with (tot20 rejects anything else). */
 export const BROKER_ALG = "RS256";
 
@@ -52,8 +59,20 @@ export const BROKER_ISSUER_ENV = "STOREFRONT_BROKER_ISSUER";
  */
 export class BrokerAssertionError extends Error {}
 
-/** Optional test/DI overrides (avoids touching process env in unit tests). */
+/** Mint options: the optional `tenant` claim, plus test/DI overrides. */
 export interface MintBrokerAssertionOverrides {
+  /**
+   * Binds this one assertion to a single target tenant (appDomain), signed. tot20
+   * reads it as `assertionTenant` and requires it to match the tenant named on the
+   * request EXACTLY — an unnormalized string compare, so pass the same value the
+   * request carries. It names the tenant the broker was asked to act on; it is
+   * NOT evidence the subject owns it (tot20 resolves ownership from its own state).
+   *
+   * Omit for the surfaces that act on the caller's own store or on ToT-staff
+   * authority alone (the invite/vendor-search flows) — tot20 leaves
+   * `assertionTenant` undefined there and those routes never consult it.
+   */
+  tenant?: string;
   /** base64 of the PKCS8 PEM private key (defaults to the env value). */
   privateKeyB64?: string;
   kid?: string;
@@ -95,12 +114,17 @@ async function loadSigningKey(privateKeyB64: string): Promise<CryptoKey> {
 }
 
 /**
- * Mint a fresh, storefront-signed broker assertion PROVING `subjectEmail` is the
- * staff actor. Returns the compact RS256 JWT to place in `X-ToT-Broker-Assertion`.
+ * Mint a fresh, storefront-signed broker assertion PROVING the storefront asserts
+ * `subjectEmail` as the actor. Returns the compact RS256 JWT to place in
+ * {@link BROKER_ASSERTION_HEADER}.
  *
- * Claims: `{ iss, sub:<subjectEmail>, aud:'tot20-broker', jti:<uuid>, iat, exp:iat+300 }`.
+ * Claims: `{ iss, sub:<subjectEmail>, aud:'tot20-broker', jti:<uuid>, iat, exp:iat+300 }`,
+ * plus `tenant` when `overrides.tenant` is given.
  * Header: `{ alg:'RS256', kid, typ:'JWT' }`.
  *
+ * MINT ONE PER CALL. tot20's verifier BURNS the `jti` on first verify (single-use
+ * replay protection), so an assertion must never be reused across two requests.
+ *
  * FAILS CLOSED: throws {@link BrokerAssertionError} when the private key env is
  * absent/malformed or no subject is supplied — the caller must NOT fall back to an
  * unproven call.
@@ -122,9 +146,11 @@ export async function mintBrokerAssertion(
   const kid = overrides.kid ?? (await readEnv(BROKER_KID_ENV)) ?? DEFAULT_BROKER_KID;
   const issuer = overrides.issuer ?? (await readEnv(BROKER_ISSUER_ENV)) ?? DEFAULT_BROKER_ISSUER;
 
+  const tenant = (overrides.tenant ?? "").trim();
+
   const key = await loadSigningKey(privateKeyB64);
   const nowSeconds = Math.floor(Date.now() / 1000);
-  return new SignJWT({})
+  return new SignJWT(tenant ? { tenant } : {})
     .setProtectedHeader({ alg: BROKER_ALG, kid, typ: "JWT" })
     .setIssuer(issuer)
     .setSubject(sub)

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

@@ -144,6 +144,39 @@ export function isPublicPath(pathname: string): boolean {
   return pathname === "/api/cli/policy";
 }
 
+/**
+ * The CLI viewer-session mint (`/api/dev/cli-session`) — how an invited developer
+ * turns their own `tot login` MCP token into a storefront session so `tot accept`
+ * can reach the ship surface. Like the static-bundle upload it governs its OWN,
+ * stricter auth and must reach its handler rather than being masked behind the
+ * "Coming soon" holding page.
+ *
+ * Gate-exemption does NOT weaken it, on three independent grounds:
+ *   - It authenticates ITSELF: no `Authorization: Bearer <token>` → 401
+ *     `missing_bearer`. It reads no cookie, so it carries zero ambient authority.
+ *   - It resolves WHO that opaque token is only by asking the MCP over the
+ *     service-secret seam, fail-closed (unconfigured seam, transport fault, non-2xx,
+ *     unparseable body, or absent email all → 401).
+ *   - The session it mints is capability `member`, roles `[]` — byte-for-byte the
+ *     one `/api/auth/magic-exchange` produces from the same `reissueSubjectToken` →
+ *     verify → `createSession` path, and that route is ALREADY exempt via
+ *     {@link isAuthPath}. So this exposes no reachable surface that is not.
+ *
+ * It also grants no admission: a developer holding no membership for this host gets
+ * a session that STILL fails `sessionAdmitsHost`, so the gate stays closed to them.
+ *
+ * Matched in BOTH addressing forms, like {@link isCandidatePreviewPath} — the gate
+ * sees the PRE-STRIP request path, so a tenant reached by path prefix arrives as
+ * `/<tenant>/api/dev/cli-session`. The CLI addresses tenants exactly that way (the
+ * shared storefront origin serves every tenant under a path prefix, which is the only
+ * form that works for a tenant whose apex has not cut over), so an exact-match-only
+ * exemption would never fire for the one caller this route exists to serve.
+ */
+export function isDevCliSessionPath(pathname: string): boolean {
+  if (pathname === "/api/dev/cli-session") return true;
+  return /^\/[^/]+\/api\/dev\/cli-session$/.test(pathname);
+}
+
 /**
  * The authenticated static-bundle staging upload (`/api/publish/stage-bundle`).
  * Like the candidate-preview control plane, it governs its OWN, stricter auth (a
@@ -266,6 +299,8 @@ export function evaluateLoginGate(input: LoginGateInput): LoginGateDecision {
   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" };
+  // The CLI viewer-session mint carries its own bearer auth — see isDevCliSessionPath.
+  if (isDevCliSessionPath(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.

package/apps/storefront/src/lib/shared/principalGrants.ts

@@ -9,57 +9,64 @@
  * which only ever emits `preview-access`/`blog-contribute` sign-in eligibility) —
  * the two revoke independently and must never be merged.
  *
- *   POST   /api/clients/principalGrants                { principal:{type:'user',email}, capability, expiresAt }
+ *   POST   /api/clients/principalGrants                   { tenant, principal:{type:'user',email}, capability, expiresAt }
  *     → 200 { code:'operatorGrants:principalGrantCreated', tenant, principal, ref, capability, expiresAt }
  *     → 422 operatorGrants:{expiresAtRequired|unknownCapability|invalidPrincipal|principalTypeNotSupported}
- *     → 403 operatorGrants:notAuthenticated (bad/absent owner credential)
- *   GET    /api/clients/principalGrants                 → 200 { code:'operatorGrants:principalGrantsOk', grants:[...] }
- *   DELETE /api/clients/principalGrants/{ref}            → 200 { code:'operatorGrants:principalGrantRevoked', tenant }
+ *   GET    /api/clients/principalGrants?tenant=<t>        → 200 { code:'operatorGrants:principalGrantsOk', grants:[...] }
+ *   DELETE /api/clients/principalGrants/{ref}?tenant=<t>  → 200 { code:'operatorGrants:principalGrantRevoked', tenant }
  *
  * `expiresAt` (epoch-ms) is REQUIRED for a human grantee — tot20 fails closed
  * with `expiresAtRequired` if omitted (ADR-0003 D4: no standing authority for a
  * human/service principal). `ref` is opaque (never the raw email) and is what
  * `revoke`/list rows key on.
  *
- * ⚠ KNOWN GAP (2026-09-03, see handoff 2026-09-03-storefront-owner-grants-a-developer,
- * Part 1): unlike every other tot20 seam in this repo, this route is
- * OWNER-authenticated — `req.getApiClient()` must resolve to the TARGET TENANT's
- * own credential, not storefront's own operator identity. Storefront holds NO
- * per-tenant owner secret key anywhere (confirmed: no such credential exists in
- * this codebase — every other tot20 call here, `developerInvites`/`teamGrants`,
- * authenticates as storefront ITSELF via `TOT_API_KEY`/`TOT_SECRET_KEY`, which
- * resolves to storefront's OWN app domain, not a hosted tenant's). Presenting
- * storefront's operator credential here would not grant on behalf of the target
- * tenant — it would either self-grant on storefront's own domain or be rejected.
- * `createPrincipalGrantClient` therefore FAILS CLOSED (throws
- * {@link PrincipalGrantClientError}) until one of the following lands:
- *   (a) tot20 accepts the signed-in owner's verified id_token as bearer auth on
- *       this route, or
- *   (b) tot20 adds a storefront-proxy grantor mode (operator credential + a
- *       verified owner id_token/session claim, scoped to storefront's own hosted
- *       tenants) — the same shape as the ToT-staff-broker-assertion widening
- *       requested separately for this same route.
- * The client/route/UI below are otherwise complete and ready to light up the
- * moment a real credential resolver exists — see {@link OwnerCredentialResolver}.
+ * GRANTOR MODE: OWNER-BROKERED SESSION. Merchants hold no ToT API keys — they sign
+ * into storefront's dashboard. tot20's `resolveGrantorContext` accepts three grantor
+ * provenances, and this client drives exactly one of them:
+ *
+ *   - Naming a `tenant` on the request switches tot20 OFF the owner-key path (where
+ *     the grantor is the CALLER's own store — i.e. storefront itself) and onto the
+ *     brokered path.
+ *   - The brokered path requires a VERIFIED broker assertion whose signed `tenant`
+ *     claim matches the request's tenant EXACTLY (an unnormalized string compare, so
+ *     both are built from the same value here) and whose SUBJECT is the signed-in
+ *     owner. tot20 then resolves ownership from its OWN state (`ownsTenant` →
+ *     `AccessCodeService.resolveEligibility`, strictly `capability === 'owner'`) —
+ *     the assertion proves WHO the subject is, never WHAT they own.
+ *   - Transport auth stays storefront's OWN operator credential (`TOT_API_KEY` /
+ *     `TOT_SECRET_KEY`; the route is `requireSecretKey`), the same credential every
+ *     sibling client here presents. It authenticates the BROKER; it does not choose
+ *     the grantor. tot20 audits the result as `authorityPath:'owner-brokered-session'`
+ *     with actor `owner:<hash>` — distinct from the owner-key `self-service-direct`.
+ *
+ * The assertion is minted PER CALL by the route (the only layer holding the verified
+ * session) and injected as {@link OwnerAssertionMinter}; this module never sees a
+ * session and so cannot mint on a client-supplied email. tot20's verifier BURNS the
+ * `jti` on first verify, so a minter that memoized would fail the second call as a
+ * replay.
  *
  * AUTH WIRE: tot20's swagger `normalizeSecureUserRequest` accepts machine creds
  * three ways — request BODY fields `totApiKey`/`totSecretKey`, the same fields as
  * QUERY params, or an `Authorization` header carrying a base64 "license key"
  * (`base64("<apiKey>;<secretKey>")`, expanded by tot20's `expandLicenseKey`,
- * which takes PRECEDENCE over the body/query values). Custom `x-tot-*` headers
- * are NOT read. This is the only integration-sensitive spot
- * ({@link OwnerCredentialResolver}, {@link credentialAuthHeader}).
+ * which takes PRECEDENCE over the body/query values). The broker assertion rides the
+ * separate `X-ToT-Broker-Assertion` header ({@link BROKER_ASSERTION_HEADER}) — the
+ * only place tot20's `readAssertion` looks. These are the integration-sensitive spots
+ * ({@link credentialAuthHeader}, {@link HttpPrincipalGrantClient.brokeredHeaders}).
  *
- * ⚠ CREDENTIALS NEVER GO IN A URL. `POST` carries them in the body; `GET`/`DELETE`
- * have no body, so they use the `Authorization` license-key header — NOT the query
- * string, even though tot20 would accept it there. A query string lands in access
- * logs, proxy logs, browser history and error-tracking payloads, so a credential
- * there is a disclosure with a long tail. tot20 holds this same line deliberately
- * (its staff broker assertions are header-only "so the staff subject never lands
- * in URLs/access logs", and its revoke addresses a grant by an opaque `ref`
- * precisely so an email never becomes a path segment); this client must not be the
- * thing that breaks it. `principalGrants.test.ts` asserts no credential value ever
- * appears in a request URL, for any method — keep that guard.
+ * ⚠ CREDENTIALS AND ASSERTIONS NEVER GO IN A URL. `POST` carries the credential in the
+ * body; `GET`/`DELETE` have no body, so they use the `Authorization` license-key
+ * header — NOT the query string, even though tot20 would accept it there. A query
+ * string lands in access logs, proxy logs, browser history and error-tracking
+ * payloads, so a credential there is a disclosure with a long tail. tot20 holds this
+ * same line deliberately (its broker assertions are header-only "so the staff subject
+ * never lands in URLs/access logs", and its revoke addresses a grant by an opaque
+ * `ref` precisely so an email never becomes a path segment); this client must not be
+ * the thing that breaks it. `?tenant=` on GET/DELETE is the ONE permitted query param
+ * — an appDomain is public routing data, not a credential, and tot20 reads the tenant
+ * from `req.query` on exactly those two verbs. `principalGrants.test.ts` asserts that
+ * `tenant` is the only param present and that no credential or assertion value ever
+ * reaches a URL, for any method — keep that guard.
  *
  * TIER: host + credentials are per-DEPLOY env, same `TOT_CORE_URL` the sibling
  * developerInvites/forge clients read (qa tier is what's live today for this route).
@@ -70,6 +77,7 @@
  */
 import { readEnv } from "@/lib/env";
 import { diagEmail } from "@/lib/diag/redact";
+import { BROKER_ASSERTION_HEADER, BROKER_PRIVATE_KEY_ENV } from "@/lib/auth/brokerAssertion";
 
 /** A human grantee — the only principal type this HTTP surface accepts. */
 export interface UserPrincipal {
@@ -103,12 +111,18 @@ export interface PrincipalGrantCreated {
 }
 
 export type PrincipalGrantFailureReason =
-  | "notAuthenticated" // 403/422 — owner credential missing/rejected
+  | "notAuthenticated" // 403/422 — storefront's own operator credential missing/rejected
   | "expiresAtRequired" // 422 — ADR-0003 D4
   | "unknownCapability" // 422
   | "invalidPrincipal" // 422
   | "principalTypeNotSupported" // 422 — non-'user' principal at this HTTP layer
-  | "ownerCredentialNotConfigured" // LOCAL: no owner-credential resolver wired yet (see file header)
+  // --- owner-brokered grantor path (tot20 `resolveGrantorContext`) ---
+  | "brokerAssertionRequired" // 422 — named a tenant with no assertion (client bug)
+  | "brokerAssertionInvalid" // 401 — bad signature / expired / replayed jti
+  | "assertionTenantMismatch" // 422 — assertion names a different tenant than the request
+  | "tenantNotRegistered" // 422 — the named appDomain is not a ToT client
+  | "subjectNotTenantOwner" // 403 — the signed-in subject does not OWN this tenant
+  | "brokerNotConfigured" // LOCAL 503 — this deploy holds no broker signing key
   | "error"; // transport / unexpected upstream fault
 
 export interface PrincipalGrantFailed {
@@ -173,14 +187,18 @@ export class FetchHttpTransport implements HttpTransport {
 export class PrincipalGrantClientError extends Error {}
 
 /**
- * Resolves the tot20 credential fields to merge into a request body FOR A GIVEN
- * TENANT — the seam the known gap above is about. Returns `null` when no owner
- * credential can be resolved for that tenant (fails closed; never falls back to
- * storefront's own operator credential, which would silently misdirect the grant).
+ * Mints a FRESH broker assertion naming `tenant`, whose subject is the signed-in
+ * OWNER. Supplied by the route, which is the only layer holding a verified session
+ * — keeping this an injected function is what makes it structurally impossible for
+ * this module to assert an email that came off a request.
+ *
+ * Returns `null` when this deploy cannot sign at all (no broker key) — the caller
+ * fails closed with `brokerNotConfigured` rather than sending an unbrokered request
+ * that tot20 would silently resolve to storefront's OWN store as grantor.
+ *
+ * Called once per request: tot20 burns the `jti`, so a cached assertion replays.
  */
-export type OwnerCredentialResolver = (
-  tenant: string,
-) => Promise<{ totApiKey: string; totSecretKey?: string } | null>;
+export type OwnerAssertionMinter = (tenant: string) => Promise<string | null>;
 
 /**
  * Build the `Authorization` header tot20 accepts for a body-less request (GET /
@@ -204,34 +222,63 @@ export function credentialAuthHeader(cred: {
 export interface HttpPrincipalGrantClientConfig {
   /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
   baseUrl: string;
-  resolveOwnerCredential: OwnerCredentialResolver;
+  /** Storefront's OWN operator credential — authenticates the broker, not the grantor. */
+  apiKey: string;
+  secretKey?: string;
+  mintOwnerAssertion: OwnerAssertionMinter;
   transport?: HttpTransport;
 }
 
 export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   private readonly baseUrl: string;
-  private readonly resolveOwnerCredential: OwnerCredentialResolver;
+  private readonly apiKey: string;
+  private readonly secretKey: string | undefined;
+  private readonly mintOwnerAssertion: OwnerAssertionMinter;
   private readonly transport: HttpTransport;
 
   constructor(config: HttpPrincipalGrantClientConfig) {
     if (!config.baseUrl) {
       throw new PrincipalGrantClientError("principalGrants: TOT_CORE_URL is not configured");
     }
+    if (!config.apiKey) {
+      throw new PrincipalGrantClientError("principalGrants: TOT_API_KEY is not configured");
+    }
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
-    this.resolveOwnerCredential = config.resolveOwnerCredential;
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.mintOwnerAssertion = config.mintOwnerAssertion;
     this.transport = config.transport ?? new FetchHttpTransport();
   }
 
+  /** Storefront's own operator credential, as tot20's documented body fields. */
+  private credential(): { totApiKey: string; totSecretKey?: string } {
+    return { totApiKey: this.apiKey, ...(this.secretKey ? { totSecretKey: this.secretKey } : {}) };
+  }
+
+  /**
+   * Headers for a brokered call. `assertion` is header-only; the license-key
+   * `Authorization` is added for the body-less verbs, which have nowhere else to
+   * carry the credential that isn't the URL.
+   */
+  private brokeredHeaders(assertion: string, withCredential: boolean): Record<string, string> {
+    return {
+      [BROKER_ASSERTION_HEADER]: assertion,
+      ...(withCredential ? credentialAuthHeader(this.credential()) : {}),
+    };
+  }
+
   async createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult> {
-    const cred = await this.resolveOwnerCredential(input.tenant);
-    if (!cred) return notConfigured();
+    const assertion = await this.mintOwnerAssertion(input.tenant);
+    if (!assertion) return brokerNotConfigured();
 
+    // `tenant` in the BODY is what puts tot20 on the owner-brokered branch for POST
+    // (createPrincipalGrant reads `body.tenant`); GET/DELETE read `req.query.tenant`.
     const body: Record<string, unknown> = {
+      tenant: input.tenant,
       principal: { type: "user", email: input.principal.email.toLowerCase() },
       capability: input.capability,
       expiresAt: input.expiresAt,
-      totApiKey: cred.totApiKey,
-      ...(cred.totSecretKey ? { totSecretKey: cred.totSecretKey } : {}),
+      ...this.credential(),
     };
     if (input.scope) body.scope = input.scope;
     if (input.purpose) body.purpose = input.purpose;
@@ -246,7 +293,11 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
 
     let res: HttpResponseLike;
     try {
-      res = await this.transport.post(`${this.baseUrl}/api/clients/principalGrants`, {}, body);
+      res = await this.transport.post(
+        `${this.baseUrl}/api/clients/principalGrants`,
+        this.brokeredHeaders(assertion, false),
+        body,
+      );
     } catch (cause) {
       return transportFailure("creating principal grant", cause);
     }
@@ -263,14 +314,15 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   }
 
   async listGrants(tenant: string): Promise<PrincipalGrantListResult> {
-    const cred = await this.resolveOwnerCredential(tenant);
-    if (!cred) return notConfigured();
+    const assertion = await this.mintOwnerAssertion(tenant);
+    if (!assertion) return brokerNotConfigured();
     let res: HttpResponseLike;
     try {
-      // Credential travels in the Authorization header, never the query string.
+      // `tenant` is the ONLY query param — public routing data, and the only place
+      // tot20's listPrincipalGrants reads it. The credential stays in a header.
       res = await this.transport.get(
-        `${this.baseUrl}/api/clients/principalGrants`,
-        credentialAuthHeader(cred),
+        `${this.baseUrl}/api/clients/principalGrants?tenant=${encodeURIComponent(tenant)}`,
+        this.brokeredHeaders(assertion, true),
       );
     } catch (cause) {
       return transportFailure("listing principal grants", cause);
@@ -281,16 +333,17 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   }
 
   async revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult> {
-    const cred = await this.resolveOwnerCredential(tenant);
-    if (!cred) return notConfigured();
+    const assertion = await this.mintOwnerAssertion(tenant);
+    if (!assertion) return brokerNotConfigured();
     let res: HttpResponseLike;
     try {
-      // Credential travels in the Authorization header, never the query string.
-      // `ref` is tot20's opaque grant handle (never a raw email), so it is safe
-      // as a path segment — that is exactly why tot20 addresses revoke by ref.
+      // `ref` is tot20's opaque grant handle (never a raw email), so it is safe as a
+      // path segment — that is exactly why tot20 addresses revoke by ref. `tenant` is
+      // the only query param; the credential stays in the Authorization header.
       res = await this.transport.delete(
-        `${this.baseUrl}/api/clients/principalGrants/${encodeURIComponent(ref)}`,
-        credentialAuthHeader(cred),
+        `${this.baseUrl}/api/clients/principalGrants/${encodeURIComponent(ref)}` +
+          `?tenant=${encodeURIComponent(tenant)}`,
+        this.brokeredHeaders(assertion, true),
       );
     } catch (cause) {
       return transportFailure("revoking principal grant", cause);
@@ -301,14 +354,14 @@ export class HttpPrincipalGrantClient implements PrincipalGrantClient {
   }
 }
 
-function notConfigured(): PrincipalGrantFailed {
+function brokerNotConfigured(): PrincipalGrantFailed {
   return {
     ok: false,
     status: 503,
-    reason: "ownerCredentialNotConfigured",
+    reason: "brokerNotConfigured",
     message:
-      "storefront has no owner credential to present to tot20 for this tenant yet " +
-      "(see the KNOWN GAP note in lib/shared/principalGrants.ts)",
+      "this storefront deploy cannot sign an owner assertion " +
+      `(${BROKER_PRIVATE_KEY_ENV} is not configured), so the request was not sent`,
   };
 }
 
@@ -366,12 +419,49 @@ function reasonFor(code: string | undefined, status: number): PrincipalGrantFail
       return "invalidPrincipal";
     case "operatorGrants:principalTypeNotSupported":
       return "principalTypeNotSupported";
+    // --- owner-brokered grantor path ---
+    case "operatorGrants:brokerAssertionRequired":
+      return "brokerAssertionRequired";
+    case "operatorGrants:brokerAssertionInvalid":
+      return "brokerAssertionInvalid";
+    // All three are the same class of storefront bug: the signed `tenant` claim and
+    // the tenant on the request did not line up. Collapsed so the UI has one story.
+    case "operatorGrants:assertionTenantRequired":
+    case "operatorGrants:tenantAssertionMismatch":
+    case "operatorGrants:tenantRequired":
+      return "assertionTenantMismatch";
+    case "operatorGrants:tenantNotRegistered":
+      return "tenantNotRegistered";
+    case "operatorGrants:subjectNotTenantOwner":
+    // Storefront never drives the staff-consent-capture branch, so a staff-scope
+    // refusal here can only mean the subject reached tot20 as staff rather than as
+    // the owner — the same operator-facing story as "you don't own this store".
+    case "operatorGrants:staffScopeInsufficient":
+      return "subjectNotTenantOwner";
     default:
       if (status === 403 || status === 401) return "notAuthenticated";
       return "error";
   }
 }
 
+/**
+ * Turn a tot20 refusal into a typed failure. When we RECOGNISE the code we prefer
+ * our own operator-facing wording over tot20's — tot20's messages are written for
+ * an API integrator ("The broker assertion names a different tenant than the
+ * request."), which is noise to a merchant clicking Delegate. An unrecognised code
+ * keeps tot20's message, since that is the only signal we have.
+ */
+function failureFrom(
+  status: number,
+  c: Record<string, unknown>,
+): { status: number; reason: PrincipalGrantFailureReason; message: string; code?: string } {
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const reason = reasonFor(code, status);
+  const upstream = typeof c.message === "string" ? c.message : undefined;
+  const message = reason === "error" && upstream ? upstream : defaultMessage(reason, status);
+  return { status, reason, message, ...(code ? { code } : {}) };
+}
+
 function defaultMessage(reason: PrincipalGrantFailureReason, status: number): string {
   switch (reason) {
     case "notAuthenticated":
@@ -384,8 +474,17 @@ function defaultMessage(reason: PrincipalGrantFailureReason, status: number): st
       return "a valid grantee email is required";
     case "principalTypeNotSupported":
       return "this endpoint grants a human (email) principal only";
-    case "ownerCredentialNotConfigured":
-      return "storefront has no owner credential configured for this tenant";
+    case "subjectNotTenantOwner":
+      return "only an owner of this store can delegate ship-on-behalf";
+    case "tenantNotRegistered":
+      return "this store isn't registered with Token of Trust";
+    case "brokerAssertionInvalid":
+      return "your session proof was rejected — sign in again and retry";
+    case "brokerAssertionRequired":
+    case "assertionTenantMismatch":
+      return "storefront sent a malformed delegation request — please report this";
+    case "brokerNotConfigured":
+      return "delegation isn't available on this deployment";
     default:
       return `principalGrants: tot20 returned status ${status}`;
   }
@@ -405,9 +504,7 @@ export function normalizeCreateResponse(status: number, body: unknown): Principa
       expiresAt: Number(c.expiresAt ?? 0),
     };
   }
-  const reason = reasonFor(code, status);
-  const message = typeof c.message === "string" ? c.message : defaultMessage(reason, status);
-  return { ok: false, status, reason, message, ...(code ? { code } : {}) };
+  return { ok: false, ...failureFrom(status, c) };
 }
 
 export function normalizeListResponse(status: number, tenant: string, body: unknown): PrincipalGrantListResult {
@@ -426,9 +523,7 @@ export function normalizeListResponse(status: number, tenant: string, body: unkn
     });
     return { ok: true, tenant, grants };
   }
-  const reason = reasonFor(code, status);
-  const message = typeof c.message === "string" ? c.message : defaultMessage(reason, status);
-  return { ok: false, status, reason, message, ...(code ? { code } : {}) };
+  return { ok: false, ...failureFrom(status, c) };
 }
 
 export function normalizeRevokeResponse(status: number, tenant: string, body: unknown): PrincipalGrantRevokeResult {
@@ -438,9 +533,7 @@ export function normalizeRevokeResponse(status: number, tenant: string, body: un
   if (isOk) {
     return { ok: true, tenant: String(c.tenant ?? tenant), ref: "" };
   }
-  const reason = reasonFor(code, status);
-  const message = typeof c.message === "string" ? c.message : defaultMessage(reason, status);
-  return { ok: false, status, reason, message, ...(code ? { code } : {}) };
+  return { ok: false, ...failureFrom(status, c) };
 }
 
 /** Map a typed failure onto the HTTP status a storefront route should return. */
@@ -452,8 +545,15 @@ export function principalGrantHttpStatus(reason: PrincipalGrantFailureReason, up
     case "unknownCapability":
     case "invalidPrincipal":
     case "principalTypeNotSupported":
+    case "brokerAssertionRequired":
+    case "assertionTenantMismatch":
+    case "tenantNotRegistered":
       return 422;
-    case "ownerCredentialNotConfigured":
+    case "brokerAssertionInvalid":
+      return 401;
+    case "subjectNotTenantOwner":
+      return 403;
+    case "brokerNotConfigured":
       return 503;
     default:
       return upstreamStatus >= 400 ? upstreamStatus : 502;
@@ -466,16 +566,26 @@ export function principalGrantHttpStatus(reason: PrincipalGrantFailureReason, up
 export class MockPrincipalGrantClient implements PrincipalGrantClient {
   private grants = new Map<string, { principal: UserPrincipal; capability: string; expiresAt: number }>();
   private seq = 0;
-  /** Tenants with NO owner credential configured (simulates the known gap). */
-  private readonly unconfigured: Set<string>;
+  /** Tenants the signed-in subject does NOT own (tot20's `subjectNotTenantOwner`). */
+  private readonly notOwned: Set<string>;
 
-  constructor(unconfiguredTenants: string[] = []) {
-    this.unconfigured = new Set(unconfiguredTenants.map((t) => t.toLowerCase()));
+  constructor(notOwnedTenants: string[] = []) {
+    this.notOwned = new Set(notOwnedTenants.map((t) => t.toLowerCase()));
+  }
+
+  private refuseNotOwner(): PrincipalGrantFailed {
+    return {
+      ok: false,
+      status: 403,
+      reason: "subjectNotTenantOwner",
+      message: defaultMessage("subjectNotTenantOwner", 403),
+      code: "operatorGrants:subjectNotTenantOwner",
+    };
   }
 
   async createGrant(input: CreatePrincipalGrantInput): Promise<PrincipalGrantResult> {
     const tenant = input.tenant.toLowerCase();
-    if (this.unconfigured.has(tenant)) return notConfigured();
+    if (this.notOwned.has(tenant)) return this.refuseNotOwner();
     if (!input.expiresAt || input.expiresAt <= Date.now()) {
       return { ok: false, status: 422, reason: "expiresAtRequired", message: "a future expiresAt is required", code: "operatorGrants:expiresAtRequired" };
     }
@@ -490,7 +600,7 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
 
   async listGrants(tenant: string): Promise<PrincipalGrantListResult> {
     const t = tenant.toLowerCase();
-    if (this.unconfigured.has(t)) return notConfigured();
+    if (this.notOwned.has(t)) return this.refuseNotOwner();
     const grants = [...this.grants.entries()]
       .filter(([ref]) => ref.startsWith(`mock-ref-${t}-`))
       .map(([ref, g]) => ({ ...g, ref }));
@@ -499,7 +609,7 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
 
   async revokeGrant(tenant: string, ref: string): Promise<PrincipalGrantRevokeResult> {
     const t = tenant.toLowerCase();
-    if (this.unconfigured.has(t)) return notConfigured();
+    if (this.notOwned.has(t)) return this.refuseNotOwner();
     if (!ref.startsWith(`mock-ref-${t}-`) || !this.grants.has(ref)) {
       return { ok: false, status: 404, reason: "error", message: "no such grant" };
     }
@@ -511,17 +621,28 @@ export class MockPrincipalGrantClient implements PrincipalGrantClient {
 // --- Factory ----------------------------------------------------------------
 
 /**
- * Build the env-configured client. `resolveOwnerCredential` defaults to a
- * fail-closed stub (see the KNOWN GAP note at the top of this file) — pass an
- * override once a real owner-credential resolver exists.
+ * Build the env-configured client:
+ *   - `TOT_CORE_URL` — tot20 core API base (tier-matching per deploy).
+ *   - `TOT_API_KEY` (+ optional `TOT_SECRET_KEY`) — storefront's own operator creds.
+ *
+ * `mintOwnerAssertion` is a REQUIRED positional argument, not an override with a
+ * default: there is no safe default. A client built without it would send an
+ * unbrokered request that tot20 resolves to storefront's OWN store as grantor —
+ * silently granting on the wrong tenant. Making it structural means the caller must
+ * hold a verified owner session to build a client at all.
  */
 export async function createPrincipalGrantClient(
-  overrides: Partial<HttpPrincipalGrantClientConfig> = {},
+  mintOwnerAssertion: OwnerAssertionMinter,
+  overrides: Partial<Omit<HttpPrincipalGrantClientConfig, "mintOwnerAssertion">> = {},
 ): Promise<HttpPrincipalGrantClient> {
   const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv("TOT_API_KEY")) ?? "";
+  const secretKey = overrides.secretKey ?? (await readEnv("TOT_SECRET_KEY"));
   return new HttpPrincipalGrantClient({
     baseUrl,
-    resolveOwnerCredential: overrides.resolveOwnerCredential ?? (async () => null),
+    apiKey,
+    mintOwnerAssertion,
+    ...(secretKey ? { secretKey } : {}),
     ...(overrides.transport ? { transport: overrides.transport } : {}),
   });
 }

package/apps/storefront/src/lib/tot/syncState.ts

@@ -0,0 +1,111 @@
+/**
+ * Worker-side reader for the durable per-tenant catalog sync state (hsby-B1).
+ * The migration CLI writes one JSON document per tenant scope at
+ * out/catalog/<scope>/sync-state.json (packages/migration/src/load/sync-state.ts,
+ * `SyncStateStore`/`nextSyncState`) — this module is the Worker's read side of
+ * that same file, via the same Vite glob mechanism `ToTClient.ts` uses for
+ * products.json/collections.json/reviews.json. OPTIONAL: a tenant with no
+ * recorded sync (or one migrated before hsby-B1 landed) just gets `null`.
+ *
+ * This is intentionally a thin, standalone read — not wired into `ToTClient`,
+ * since not every caller needs sync provenance. hsby-B3's readiness projection
+ * is the expected first consumer.
+ */
+
+/** Mirrors packages/migration/src/load/sync-state.ts's `SourcePlatform`. */
+export type SyncStateSourcePlatform =
+  | "shopify-admin"
+  | "shopify-public"
+  | "fixtures"
+  | "existing";
+
+/** Mirrors packages/migration/src/load/sync-state.ts's `FidelityLevel`. */
+export type SyncStateFidelityLevel = "full" | "reduced" | "unknown";
+
+export interface SyncStateFidelity {
+  level: SyncStateFidelityLevel;
+  note: string;
+  missing: string[];
+}
+
+export interface SyncStateSourceMode {
+  platform: SyncStateSourcePlatform;
+  mode: "full" | "incremental";
+  fullSweepOnly: boolean;
+}
+
+export interface SyncStateEntity {
+  checksums: Record<string, string>;
+  lastUpdatedAt: string | null;
+}
+
+/** Mirrors packages/migration/src/load/sync-state.ts's `EntityChangeSet`. */
+export interface SyncStateEntityChangeSet {
+  added: string[];
+  updated: string[];
+  removed: string[];
+  unchanged: number;
+}
+
+/** Mirrors packages/migration/src/load/sync-state.ts's `SweepChanges`. */
+export interface SyncStateSweepChanges {
+  computedAt: string;
+  mode: "full" | "incremental";
+  removalsAssessed: boolean;
+  fullSweepOnly: boolean;
+  products: SyncStateEntityChangeSet;
+  collections: SyncStateEntityChangeSet;
+}
+
+/** The on-disk shape written by the migration CLI (schema "tot.sync-state/1"). */
+export interface CatalogSyncState {
+  schema: string;
+  tenantId: string;
+  scope: string;
+  source: SyncStateSourceMode;
+  fidelity: SyncStateFidelity;
+  lastSyncAt: string | null;
+  /** True when the most recent sync loaded with record errors; absent on a pre-hsby-B3 catalog. */
+  lastSyncHadErrors?: boolean;
+  products: SyncStateEntity;
+  collections: SyncStateEntity;
+  /**
+   * The content-hash delta of the most recent sweep. Optional: a catalog
+   * migrated before hsby-B2 (change detection) has no `lastChanges`.
+   */
+  lastChanges?: SyncStateSweepChanges;
+}
+
+// Vite resolves this glob at build time and bundles every tenant's sync-state
+// document, so the Worker has no runtime filesystem dependency — same pattern
+// as productGlobs/collectionGlobs/reviewGlobs in ToTClient.ts.
+const syncStateGlobs = import.meta.glob<CatalogSyncState>(
+  "../../../../../packages/migration/out/catalog/*/sync-state.json",
+  { import: "default" },
+);
+
+const syncStateCacheByScope = new Map<string, CatalogSyncState | null>();
+
+/** Pick the glob entry for a tenant scope (matches .../catalog/<scope>/file). */
+function pickByScope(scope: string): (() => Promise<CatalogSyncState>) | null {
+  const suffix = `/catalog/${scope}/`;
+  const key = Object.keys(syncStateGlobs).find((k) => k.includes(suffix));
+  return (key ? syncStateGlobs[key] : null) ?? null;
+}
+
+/**
+ * The tenant's durable sync state, or null when none was ever recorded (no
+ * migration run yet, or a pre-hsby-B1 catalog). Never throws.
+ */
+export async function getSyncState(scope: string): Promise<CatalogSyncState | null> {
+  if (syncStateCacheByScope.has(scope)) return syncStateCacheByScope.get(scope)!;
+  const loader = pickByScope(scope);
+  const state = loader ? await loader() : null;
+  syncStateCacheByScope.set(scope, state);
+  return state;
+}
+
+/** Test seam: drop the per-isolate cache. */
+export function clearSyncStateCache(): void {
+  syncStateCacheByScope.clear();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

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

@@ -90,7 +90,21 @@ export interface PreviewState {
    * post-hoc merge sets it, after `reportPreviewEvidence` computes it. Absent and
    * `null` both mean "no verdict yet"; callers should treat them the same.
    */
-  evidence?: { checks: PreviewStateEvidenceCheck[]; promotable: boolean; generatedAt: string } | null;
+  evidence?: {
+    checks: PreviewStateEvidenceCheck[];
+    promotable: boolean;
+    generatedAt: string;
+    /**
+     * Set when the MCP `change_report_evidence` push for this verdict failed —
+     * `promotable` above is already forced `false` in that case (fail-closed: MCP
+     * has no evidence for this commit, so the local record must not claim
+     * shippability the other source of truth doesn't share). Mirrors
+     * `ReviewEnvironmentEvidence.pushFailed` (candidate-index.ts).
+     */
+    pushFailed?: boolean;
+    /** The push failure's error message, when `pushFailed` is true. */
+    pushError?: string;
+  } | null;
 }
 
 export function previewStateKey(tenantId: string): string {

package/packages/public-runtime/src/evidence.ts

@@ -9,16 +9,16 @@
  * See `epics/dev-loop.md` (D4 + the MCP-foundations block).
  */
 
-// NOTE (2026-08): a v2 `assets_materialized` check was briefly added here and REVERTED —
-// the deployed tot-mcp evidence validator pins `contract_version:1` + a 7-id enum and
-// REJECTED every v2 report (".contract_version should be equal to constant; .checks[7].id
-// should be equal to one of the allowed values"), silently dropping the evidence push so
-// `preview_status` hung `pending` on every reconcile. The reconcile STILL fetch-verifies
-// the served asset subtree (verify-assets.ts) and surfaces the result in the reconcile
-// trace ("assets-verified" marker) — that regression guard is intact. Re-add the
-// `assets_materialized` check id here + bump to 2 ONLY in lockstep with tot-mcp accepting
-// contract_version 2 (and mirroring the evidence-url CRC). Until then this stays v1.
-export const EVIDENCE_CONTRACT_VERSION = 1;
+// v2 (2026-08): added the `assets_materialized` check — reconcile now fetch-verifies
+// that a version's public/app asset subtree actually SERVES (the pagination-truncation
+// class of silent drop, fb-1787794734109-hjru1k, reported success + promotable while
+// the newest asset subtree 404'd). GRANDFATHER: a consumer must treat an
+// already-passed v1 report as still valid — the new check is version-gated, so a v1
+// report (which cannot carry it) is never retroactively failed for its absence. The
+// promote-gate addition (`assets_materialized` → REQUIRED_FOR_PROMOTE) is
+// version-gated to v2 on the CONSUMER (tot-mcp); this producer emits the check but
+// leaves REQUIRED_FOR_PROMOTE unchanged so a v1-shaped promote rule still holds.
+export const EVIDENCE_CONTRACT_VERSION = 2;
 
 /** The per-check verdicts. `skip` = not applicable / not yet measured. */
 export const EVIDENCE_STATUSES = ["pass", "warn", "fail", "skip"] as const;
@@ -37,7 +37,10 @@ export const EVIDENCE_CHECK_IDS = [
   "json_ld",
   "sitemap",
   "cutover_crawl",
-  // (v2 `assets_materialized` intentionally omitted — see EVIDENCE_CONTRACT_VERSION note.)
+  // v2: did this version's public/app asset subtree actually materialize + serve
+  // (fetch-verified against R2 at the published versionId). Fail-closed — a silent
+  // drop (pagination truncation, a failed ingest) reads `fail`, never a vacuous pass.
+  "assets_materialized",
 ] as const;
 export type EvidenceCheckId = (typeof EVIDENCE_CHECK_IDS)[number];
 

package/scripts/tenant/materialize-tenant-content.mjs

@@ -38,6 +38,12 @@
  *   node scripts/tenant/materialize-tenant-content.mjs --check-pinned [--expect-ref <sha>] [--allow-unpinned]
  *       # stricter deploy gate: verify populated AND materialized from Gitea at a
  *       # PINNED ref (.materialized.json present, pinned, on the expected ref); no network
+ *   node scripts/tenant/materialize-tenant-content.mjs --check-pinned --verify-fresh
+ *       # opt-in NETWORK addition to --check-pinned: for any stamp pinned to a
+ *       # MOVABLE ref (a branch name, or an unpinned default-branch materialize),
+ *       # resolve that ref's CURRENT tip on Gitea and refuse if the stamped sha no
+ *       # longer matches it (`git ls-remote`, no clone). A stamp pinned to an exact
+ *       # commit SHA is frozen by design and can never be "stale" under this check.
  *
  * Auth (never logged; tokens are redacted from every error):
  *   TENANT_GIT_BASE   clone base. Default https://git.tokenoftrust.com/storefront
@@ -71,6 +77,7 @@ const repoRoot = resolve(here, "..", "..");
 
 export const MANIFEST_PATH = "tenants/.gitea-tenants.json";
 const TENANT_ID_RE = /^[a-z0-9][a-z0-9.-]{1,60}[a-z0-9]$/;
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
 const DEFAULT_GIT_BASE = "https://git.tokenoftrust.com/storefront";
 
 /** Load the Gitea-tenant manifest. Returns { tenants: { <id>: { repo } } }. */
@@ -380,9 +387,87 @@ export function checkPinned(
   return { ok: problems.length === 0, problems };
 }
 
-/** Human-readable refusal for a failed `checkPinned` (shared by the CLI + the
- * build-time guard). `problems` is checkPinned().problems; `expectRef` is echoed
- * into the off-ref explanation when set. */
+/**
+ * `--verify-fresh` (opt-in, NETWORK): the one thing `checkPinned` deliberately cannot tell you —
+ * whether a pinned stamp is still current. `checkPinned` only proves the stamp is pinned to SOME
+ * ref (and, with `expectRef`, that it matches a caller-supplied value); it never talks to Gitea,
+ * so a stamp pinned to a MOVABLE ref (a branch name, or an unpinned default-branch materialize)
+ * can silently drift arbitrarily far behind that ref's current tip and keep passing forever.
+ *
+ * A stamp pinned to an exact commit SHA is excluded on purpose: that's a deliberate promotion to
+ * an immutable commit, frozen by design, and is never "stale" — re-promoting to a newer commit is
+ * a separate, explicit act (a fresh `--ref <sha>` materialize), not something this check should
+ * flag as a problem.
+ *
+ * For each in-scope tenant with a stamp, resolves the stamped ref's CURRENT tip via
+ * `git ls-remote` (no clone) and compares it to the stamped sha. Requires read access to Gitea —
+ * same TENANT_GIT_USER/TENANT_GIT_TOKEN as materializeTenant. Tenants that already fail
+ * `checkPinned` (absent/missing/unpinned-without-allowUnpinned/off-ref) are left to those
+ * existing reasons and skipped here to avoid double-reporting the same tenant.
+ *
+ * Returns { ok, problems: [{ tenant, reason }] } where reason ∈ "unreachable" | "stale":
+ *   unreachable   the live tip could not be resolved (network/auth failure, deleted ref, etc.) —
+ *                 never treated as fresh; an unreachable Gitea must not silently pass this gate.
+ *   stale         the stamped sha no longer matches the ref's live tip.
+ *
+ * @param {string} [root]
+ * @param {object} [opts]
+ * @param {string} [opts.gitBase]
+ * @param {string} [opts.user]
+ * @param {string} [opts.token]
+ * @param {string[]|null} [opts.onlyTenants]
+ */
+export function checkFresh(
+  root = repoRoot,
+  {
+    gitBase = DEFAULT_GIT_BASE,
+    user = process.env.TENANT_GIT_USER,
+    token = process.env.TENANT_GIT_TOKEN,
+    onlyTenants = null,
+  } = {},
+) {
+  const manifest = loadManifest(root);
+  const problems = [];
+  const scope = onlyTenants ? new Set(onlyTenants) : null;
+  for (const tenant of Object.keys(manifest.tenants)) {
+    if (scope && !scope.has(tenant)) continue;
+    const stampPath = join(root, "tenants", tenant, ".materialized.json");
+    if (!existsSync(stampPath)) continue; // checkPinned already reports absent/missing
+    let stamp;
+    try {
+      stamp = JSON.parse(readFileSync(stampPath, "utf8"));
+    } catch {
+      continue; // checkPinned already reports this as "missing"
+    }
+    const sha = typeof stamp.sha === "string" ? stamp.sha : "";
+    const rawRef = typeof stamp.ref === "string" ? stamp.ref : "";
+    if (!sha || !FULL_SHA_RE.test(sha)) continue; // no usable sha to compare — leave to checkPinned
+    if (FULL_SHA_RE.test(rawRef)) continue; // pinned to an exact commit — frozen by design
+    const movableRef = rawRef === "" || rawRef === "(default branch)" ? "HEAD" : rawRef;
+    const repo = manifest.tenants[tenant]?.repo ?? tenant;
+    const cloneUrl = buildCloneUrl({ base: gitBase, repo, user, token });
+    let liveSha = "";
+    try {
+      const out = execFileSync("git", ["ls-remote", cloneUrl, movableRef], {
+        stdio: ["ignore", "pipe", "pipe"],
+      }).toString();
+      liveSha = (out.split(/\s+/)[0] || "").trim();
+    } catch {
+      problems.push({ tenant, reason: "unreachable" });
+      continue;
+    }
+    if (!FULL_SHA_RE.test(liveSha)) {
+      problems.push({ tenant, reason: "unreachable" });
+      continue;
+    }
+    if (liveSha !== sha) problems.push({ tenant, reason: "stale" });
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+/** Human-readable refusal for a failed `checkPinned` (+ optional `checkFresh`) run (shared by
+ * the CLI + the build-time guard). `problems` is checkPinned().problems, optionally concatenated
+ * with checkFresh().problems; `expectRef` is echoed into the off-ref explanation when set. */
 export function describePinnedProblems(problems, /** @type {string|null} */ expectRef = null) {
   const how = {
     absent: "not materialized (no tenant content on disk at all)",
@@ -390,6 +475,8 @@ export function describePinnedProblems(problems, /** @type {string|null} */ expe
     unpinned:
       "materialized from the tenant repo's DEFAULT branch (no pinned ref) — may be stale",
     "off-ref": `materialized at a different ref than expected (${expectRef})`,
+    stale: "pinned ref's live Gitea tip has moved past the materialized sha — re-materialize",
+    unreachable: "could not resolve the tenant repo's live tip (network/auth failure)",
   };
   return (
     "REFUSING: tenant content is not materialized from Gitea at a pinned ref.\n" +
@@ -438,6 +525,7 @@ function parseArgs(argv) {
     checkPinned: false,
     expectRef: null,
     allowUnpinned: false,
+    verifyFresh: false,
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -449,11 +537,15 @@ function parseArgs(argv) {
     else if (t === "--check-pinned") a.checkPinned = true;
     else if (t === "--expect-ref") a.expectRef = argv[++i];
     else if (t === "--allow-unpinned") a.allowUnpinned = true;
+    else if (t === "--verify-fresh") a.verifyFresh = true;
     else if (t === "--help" || t === "-h") a.help = true;
     else if (!t.startsWith("--") && !a.tenant) a.tenant = t;
     else throw new Error(`unknown argument: ${t}`);
   }
   if (a.remote && a.all) throw new Error("--remote targets ONE tenant; not valid with --all");
+  if (a.verifyFresh && !a.checkPinned) {
+    throw new Error("--verify-fresh is only valid with --check-pinned");
+  }
   return a;
 }
 
@@ -463,6 +555,8 @@ const USAGE = `materialize-tenant-content — populate tenants/<id>/ from its Gi
   node scripts/tenant/materialize-tenant-content.mjs --all
   node scripts/tenant/materialize-tenant-content.mjs --check
   node scripts/tenant/materialize-tenant-content.mjs --check-pinned [--expect-ref <sha>] [--allow-unpinned]
+  node scripts/tenant/materialize-tenant-content.mjs --check-pinned --verify-fresh
+      # opt-in NETWORK addition: refuse if a movable-ref stamp's sha is behind Gitea's live tip
 
   env: TENANT_GIT_BASE (default ${DEFAULT_GIT_BASE}), TENANT_GIT_USER, TENANT_GIT_TOKEN`;
 
@@ -486,15 +580,21 @@ function main() {
     return;
   }
   if (args.checkPinned) {
-    const { ok, problems } = checkPinned(repoRoot, {
+    const { problems } = checkPinned(repoRoot, {
       expectRef: args.expectRef,
       allowUnpinned: args.allowUnpinned,
     });
-    if (!ok) {
-      console.error(describePinnedProblems(problems, args.expectRef));
+    const freshProblems = args.verifyFresh ? checkFresh(repoRoot, { gitBase }).problems : [];
+    const allProblems = [...problems, ...freshProblems];
+    if (allProblems.length > 0) {
+      console.error(describePinnedProblems(allProblems, args.expectRef));
       process.exit(1);
     }
-    console.log("All Gitea-classified tenants materialized from Gitea at a pinned ref.");
+    console.log(
+      args.verifyFresh
+        ? "All Gitea-classified tenants materialized from Gitea at a pinned ref, verified fresh against the live tip."
+        : "All Gitea-classified tenants materialized from Gitea at a pinned ref.",
+    );
     return;
   }
   const manifest = loadManifest();