@tokenoftrust/storefront-runner 4.8.1 → 4.9.1

package/apps/storefront/src/lib/access/rate/kvWindow.ts

@@ -1,16 +1,23 @@
 /**
- * Fixed-window KV rate limiter — the storefront's first throttle, built small
- * and generic so any public POST can share it (reactions today; blog comments
- * and other reader writes next).
+ * Fixed-window KV rate limiter for public POSTs.
  *
  * A request is counted into the bucket for the current fixed window
  * (`floor(now / windowSeconds)`), keyed `<key>:<bucket>`. The counter TTLs out a
  * window after it is first written, so old buckets self-expire — no sweep.
  *
- * Best-effort by construction: a KV read/write hiccup FAILS OPEN (returns
- * `allowed: true`) and never throws. A rate limiter must never turn a KV blip
- * into a rejected legitimate request; the abuse it guards against is low-stakes
- * (mirrors the "never throws" discipline of `blog/viewCounts.ts`).
+ * Two entry points, and the difference is the decision a caller makes:
+ *   - {@link checkRateLimit} FAILS CLOSED. No KV binding, or a KV read/write error,
+ *     refuses with `reason: "unavailable"`. This is the default for every public
+ *     write whose abuse is not trivial (a stored message, a subscriber row, a mail).
+ *   - {@link checkRateLimitFailOpen} admits when KV is missing or erroring. Only for
+ *     a write whose abuse blast radius is a counter and where refusing a legitimate
+ *     request on a KV blip is the worse outcome; the call site names that choice.
+ *
+ * Keys carry a hashed client identifier, never a raw IP: build one with
+ * `requestClientIp` + `hashConsentIp`.
+ *
+ * Increment is a read-modify-write, so under concurrency a few increments can be
+ * lost to KV's last-write-wins — acceptable for a soft abuse throttle, not a hard quota.
  */
 
 export interface RateLimitOptions {
@@ -20,54 +27,26 @@ export interface RateLimitOptions {
   maxRequests: number;
 }
 
+export type RateLimitVerdict =
+  | { allowed: true }
+  | { allowed: false; reason: "limited" | "unavailable" };
+
 /** The current fixed-window bucket index for `now` (ms epoch). */
 function windowBucket(windowSeconds: number, nowMs: number): number {
   return Math.floor(nowMs / 1000 / windowSeconds);
 }
 
 /**
- * Count one request against `key` and report whether it is within the cap for
- * the current window. Increment is a read-modify-write, so under concurrency a
- * few increments can be lost to KV's last-write-wins — acceptable for a soft
- * abuse throttle, not a hard quota. Fails OPEN on any KV error.
+ * Count one request against `key` and report whether it is within the cap for the
+ * current window. FAIL-CLOSED: no KV binding, or a KV read/write error, refuses
+ * with `reason: "unavailable"` instead of admitting.
  */
 export async function checkRateLimit(
   kv: KVNamespace | undefined,
   key: string,
   opts: RateLimitOptions,
   nowMs: number = Date.now(),
-): Promise<{ allowed: boolean }> {
-  if (!kv) return { allowed: true };
-  try {
-    const bucket = windowBucket(opts.windowSeconds, nowMs);
-    const bucketKey = `${key}:${bucket}`;
-    const raw = await kv.get(bucketKey);
-    const current = raw == null ? 0 : Number.parseInt(raw, 10);
-    const count = Number.isFinite(current) && current >= 0 ? current : 0;
-    if (count >= opts.maxRequests) return { allowed: false };
-    await kv.put(bucketKey, String(count + 1), { expirationTtl: opts.windowSeconds });
-    return { allowed: true };
-  } catch {
-    return { allowed: true };
-  }
-}
-
-export type ClosedRateLimitVerdict =
-  | { allowed: true }
-  | { allowed: false; reason: "limited" | "unavailable" };
-
-/**
- * The same fixed window, FAIL-CLOSED: no KV binding, or a KV read/write error,
- * refuses with `reason: "unavailable"` instead of admitting. For public writes
- * whose abuse is not low-stakes (a stored visitor message), where an unthrottled
- * window is worse than a refused request.
- */
-export async function checkRateLimitClosed(
-  kv: KVNamespace | undefined,
-  key: string,
-  opts: RateLimitOptions,
-  nowMs: number = Date.now(),
-): Promise<ClosedRateLimitVerdict> {
+): Promise<RateLimitVerdict> {
   if (!kv) return { allowed: false, reason: "unavailable" };
   let count: number;
   const bucketKey = `${key}:${windowBucket(opts.windowSeconds, nowMs)}`;
@@ -86,3 +65,18 @@ export async function checkRateLimitClosed(
   }
   return { allowed: true };
 }
+
+/**
+ * The same fixed window, FAIL-OPEN: no KV binding, or a KV error, returns
+ * `allowed: true` and never throws. A call site uses this only for a write whose
+ * abuse is low-stakes (a reaction counter), and says so where it calls.
+ */
+export async function checkRateLimitFailOpen(
+  kv: KVNamespace | undefined,
+  key: string,
+  opts: RateLimitOptions,
+  nowMs: number = Date.now(),
+): Promise<{ allowed: boolean }> {
+  const verdict = await checkRateLimit(kv, key, opts, nowMs);
+  return { allowed: verdict.allowed || verdict.reason === "unavailable" };
+}

package/apps/storefront/src/pages/api/blog/[collection]/[slug]/react.ts

@@ -5,21 +5,23 @@
  *
  * Discipline (mirrors the other public POSTs, `newsletter.ts` / `rum/vitals.ts`):
  *   - Tenant is resolved from `locals.tenant`, NEVER the request body.
- *   - A soft per-IP KV rate limit stops trivial scripted inflation; over-cap
+ *   - A soft per-visitor KV rate limit (hashed client IP, fail-open) stops trivial scripted inflation; over-cap
  *     returns the current tallies (429) without counting — abuse blast-radius is
  *     ~0 (a counter), so the cap is lenient.
  *   - Never 500. Every path returns a clean JSON response; `recordReaction` is
  *     itself best-effort and never throws.
  */
 import type { APIRoute } from "astro";
-import { readKv } from "@/lib/publication/shared/env";
+import { readEnv, readKv } from "@/lib/publication/shared/env";
+import { requestClientIp } from "@/lib/publication/shared/cdnForward";
+import { hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import {
   getReactionCounts,
   isReaction,
   recordReaction,
   type Reaction,
 } from "@/lib/content/blog/reactions";
-import { checkRateLimit } from "@/lib/access/rate/kvWindow";
+import { checkRateLimitFailOpen } from "@/lib/access/rate/kvWindow";
 
 export const prerender = false;
 
@@ -33,15 +35,6 @@ function json(body: unknown, status = 200): Response {
   });
 }
 
-/** Best-effort client IP for rate-limit keying — Cloudflare's header, else XFF. */
-function clientIp(request: Request): string {
-  const cf = request.headers.get("cf-connecting-ip");
-  if (cf) return cf;
-  const xff = request.headers.get("x-forwarded-for");
-  if (xff) return xff.split(",")[0]!.trim();
-  return "unknown";
-}
-
 /** Pull the reaction from a JSON or form-encoded body. */
 async function readReaction(request: Request): Promise<string | null> {
   try {
@@ -80,7 +73,11 @@ export const POST: APIRoute = async (context) => {
     );
   }
 
-  const { allowed } = await checkRateLimit(kv, `react:${tenantId}:${clientIp(context.request)}`, {
+  // Deliberately fail-open: a reaction is a counter, so a KV blip must not refuse a reader.
+  const cdnSecret = await readEnv("CDN_ORIGIN_SECRET");
+  const ip = await requestClientIp(context.request.headers, cdnSecret);
+  const ipKey = await hashConsentIp(ip, `react-rate:${cdnSecret ?? tenantId}`);
+  const { allowed } = await checkRateLimitFailOpen(kv, `react:${tenantId}:${ipKey}`, {
     windowSeconds: RATE_WINDOW_SECONDS,
     maxRequests: RATE_MAX_PER_WINDOW,
   });

package/apps/storefront/src/pages/api/contact.ts

@@ -13,7 +13,7 @@
 import type { APIContext } from "astro";
 import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
 import { fromD1 } from "@/lib/catalog/d1/catalog";
-import { checkRateLimitClosed } from "@/lib/access/rate/kvWindow";
+import { checkRateLimit } from "@/lib/access/rate/kvWindow";
 import { hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import { ContactMessagesStore } from "@/lib/engagement/contact/contactMessages";
 import { verifyContactToken } from "@/lib/engagement/contact/submitToken";
@@ -107,7 +107,7 @@ export async function POST(context: APIContext): Promise<Response> {
   const kv = await readKv("TENANT_CACHE");
   const ip = await requestClientIp(request.headers, await readEnv("CDN_ORIGIN_SECRET"));
   const ipKey = await hashConsentIp(ip, `contact-rate:${secret}`);
-  const limit = await checkRateLimitClosed(kv, `contact:${tenantId}:${ipKey}`, {
+  const limit = await checkRateLimit(kv, `contact:${tenantId}:${ipKey}`, {
     windowSeconds: CONTACT_RATE_WINDOW_SECONDS,
     maxRequests: CONTACT_RATE_MAX_PER_WINDOW,
   });

package/apps/storefront/src/pages/api/newsletter/[collection]/subscribe.ts

@@ -5,19 +5,22 @@
  * Discipline (mirrors the other public POSTs, `blog/.../react.ts` / `newsletter.ts`):
  *   - `tenant_id` is resolved from `locals.tenant`, `collection` from the ROUTE —
  *     NEVER the request body (tenant is the isolation boundary).
- *   - A soft per-IP KV rate limit (`kvWindow`) stops trivial scripted signups.
+ *   - A per-visitor KV rate limit (`kvWindow`, keyed on the hashed client IP,
+ *     fail-closed) stops scripted signups; a missing or failing KV refuses (503).
  *   - `INSERT OR IGNORE` a `pending` row with a fresh opaque token + consent
  *     record (`consent_source` = referrer, `consent_ip_hash` = sha256(ip+salt) —
  *     NEVER a raw IP). A repeat subscribe is idempotent.
- *   - Confirmation email is STUBBED (no ESP in-repo yet — N4 wires it); a stub
- *     failure never fails the subscribe.
+ *   - A confirmation email that cannot be sent, a missing apps DB and a failed
+ *     write are errors (502/503 JSON), never a success: the visitor is not told to
+ *     check an inbox that will stay empty. A retry re-sends while the row is pending.
  *   - Never 500. A `fetch`/JSON caller gets a clean JSON body; a plain form POST
- *     is redirected back to the referrer so the page can show its own thanks.
+ *     that succeeded is redirected back to the referrer so the page can show its own thanks.
  */
 import type { APIRoute } from "astro";
 import { readD1, readKv, readEnv } from "@/lib/publication/shared/env";
 import { fromD1 } from "@/lib/catalog/d1/catalog";
 import { checkRateLimit } from "@/lib/access/rate/kvWindow";
+import { requestClientIp } from "@/lib/publication/shared/cdnForward";
 import { NewsletterSubscribersStore } from "@/lib/engagement/newsletter/subscribers";
 import { randomToken, hashConsentIp } from "@/lib/engagement/newsletter/consent";
 import { sendConfirmationEmail } from "@/lib/engagement/newsletter/confirmationEmail";
@@ -38,15 +41,6 @@ function json(body: unknown, status = 200): Response {
   });
 }
 
-/** Best-effort client IP for rate-limit keying + consent record — CF header, else XFF. */
-function clientIp(request: Request): string {
-  const cf = request.headers.get("cf-connecting-ip");
-  if (cf) return cf;
-  const xff = request.headers.get("x-forwarded-for");
-  if (xff) return xff.split(",")[0]!.trim();
-  return "unknown";
-}
-
 /** Read `email` from a JSON or form-encoded body; null if unparseable. */
 async function readEmail(request: Request): Promise<string | null> {
   try {
@@ -98,26 +92,31 @@ export const POST: APIRoute = async (context) => {
       return json({ ok: false, error: "invalid_email" }, 400);
     }
 
+    const salt = (await readEnv("NEWSLETTER_CONSENT_SALT")) ?? DEV_CONSENT_SALT;
+    const ip = await requestClientIp(context.request.headers, await readEnv("CDN_ORIGIN_SECRET"));
+    const consentIpHash = await hashConsentIp(ip, salt);
+    const rateKey = await hashConsentIp(ip, `newsletter-rate:${salt}`);
+
     const kv = await readKv("TENANT_CACHE");
-    const { allowed } = await checkRateLimit(
+    const limit = await checkRateLimit(
       kv,
-      `newsletter-subscribe:${tenantId}:${clientIp(context.request)}`,
+      `newsletter-subscribe:${tenantId}:${rateKey}`,
       { windowSeconds: RATE_WINDOW_SECONDS, maxRequests: RATE_MAX_PER_WINDOW },
     );
-    if (!allowed) return json({ ok: false, error: "rate_limited" }, 429);
+    if (!limit.allowed) {
+      return limit.reason === "limited"
+        ? json({ ok: false, error: "rate_limited" }, 429)
+        : json({ ok: false, error: "unavailable" }, 503);
+    }
 
     const d1 = await readD1("STOREFRONT_APPS_DB");
     if (!d1) {
-      // No apps DB binding (local/dev without D1): can't persist. Don't fail the
-      // visitor — log and acknowledge so the flow is exercisable in dev.
-      console.log(`[newsletter] subscribe not persisted (no D1) → ${tenantId}/${collection}`);
-      return ok(context.request);
+      console.error(`[newsletter] subscribe refused: no apps DB binding tenant=${tenantId} collection=${collection}`);
+      return json({ ok: false, error: "unavailable" }, 503);
     }
 
     const referer = context.request.headers.get("referer");
     const consentSource = referer ? new URL(referer).pathname : null;
-    const salt = (await readEnv("NEWSLETTER_CONSENT_SALT")) ?? DEV_CONSENT_SALT;
-    const consentIpHash = await hashConsentIp(clientIp(context.request), salt);
 
     const store = new NewsletterSubscribersStore(fromD1(d1));
     const result = await store.subscribe({
@@ -130,25 +129,29 @@ export const POST: APIRoute = async (context) => {
     });
 
     // Only (re)send confirmation while still pending — never re-mail a confirmed
-    // or unsubscribed address. Best-effort; a stub failure must not fail signup.
+    // or unsubscribed address. A failed send is an error: the row stays pending, so
+    // the visitor's retry re-sends.
     if (result.status === "pending") {
       const origin = new URL(context.request.url).origin;
       // The tenant's real routed prefix: a pinned preview's basePath has no API mirror.
       const apiBasePath = context.locals?.apiBasePath ?? context.locals?.basePath ?? "";
       const confirmUrl = `${origin}${apiBasePath}/api/newsletter/confirm?token=${result.token}`;
-      await sendConfirmationEmail({ email, collection, confirmUrl }).catch((err: unknown) => {
+      try {
+        await sendConfirmationEmail({ email, collection, confirmUrl });
+      } catch (err) {
         console.error(
           `[newsletter] confirmation email failed tenant=${tenantId} collection=${collection}: ${err instanceof Error ? err.name : "unknown"}`,
         );
-      });
+        return json({ ok: false, error: "confirmation_not_sent" }, 502);
+      }
     }
 
     return ok(context.request);
   } catch (err) {
-    // Never 500 on a signup — acknowledge, but never swallow the failure silently.
+    // Never 500 on a signup, and never report a success that did not happen.
     console.error(
       `[newsletter] subscribe failed collection=${collection}: ${err instanceof Error ? err.name : "unknown"}`,
     );
-    return ok(context.request);
+    return json({ ok: false, error: "unavailable" }, 503);
   }
 };

package/apps/storefront/src/pages/api/newsletter.ts

@@ -12,7 +12,8 @@
  *
  * Every outcome is a confirmation page with a link back to where the visitor was;
  * a script that asks for JSON gets `{ ok, status }`. Robustness: a signup must NEVER
- * 500. All failures degrade to a friendly thank-you.
+ * 500, and a signup that was not recorded (no KV binding, a failed write) answers
+ * `failed` with a 503 rather than a thank-you.
  */
 import type { APIContext } from "astro";
 import { readKv } from "@/lib/publication/shared/env";
@@ -22,7 +23,7 @@ import { withBase } from "@/lib/publication/shared/basePath";
 // deliverability; the ESP validates properly downstream.
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
-export type NewsletterStatus = "subscribed" | "preview" | "invalid";
+export type NewsletterStatus = "subscribed" | "preview" | "invalid" | "failed";
 
 const COPY: Record<NewsletterStatus, { heading: string; message: string }> = {
   subscribed: {
@@ -38,8 +39,15 @@ const COPY: Record<NewsletterStatus, { heading: string; message: string }> = {
     heading: "That didn't go through.",
     message: "That address didn't look quite right — head back and try again.",
   },
+  failed: {
+    heading: "That didn't go through.",
+    message: "We couldn't record your signup just now — head back and try again in a moment.",
+  },
 };
 
+/** A failed recording is a 503; every other outcome is a 200 page or body. */
+const HTTP_STATUS: Record<NewsletterStatus, number> = { subscribed: 200, preview: 200, invalid: 200, failed: 503 };
+
 function escapeHtml(value: string): string {
   return value.replace(/[&<>"']/g, (ch) => `&#${ch.charCodeAt(0)};`);
 }
@@ -65,8 +73,8 @@ function wantsJson(request: Request): boolean {
 
 function respond(context: APIContext, status: NewsletterStatus): Response {
   if (wantsJson(context.request)) {
-    return new Response(JSON.stringify({ ok: status !== "invalid", status }), {
-      status: 200,
+    return new Response(JSON.stringify({ ok: status !== "invalid" && status !== "failed", status }), {
+      status: HTTP_STATUS[status],
       headers: { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" },
     });
   }
@@ -98,7 +106,7 @@ function respond(context: APIContext, status: NewsletterStatus): Response {
   </body>
 </html>`;
   return new Response(html, {
-    status: 200,
+    status: HTTP_STATUS[status],
     headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
   });
 }
@@ -125,16 +133,16 @@ export async function POST(context: APIContext): Promise<Response> {
         JSON.stringify({ email, source, at: new Date().toISOString() }),
       );
     } else {
-      // No KV binding (local/dev): nothing to persist to.
-      console.log(`[newsletter] signup not persisted (no TENANT_CACHE) tenant=${tenantId} source=${source}`);
+      console.error(`[newsletter] signup not recorded: no TENANT_CACHE binding tenant=${tenantId}`);
+      return respond(context, "failed");
     }
     return respond(context, "subscribed");
   } catch (err) {
-    // Never 500 on a signup, but never swallow the failure silently either.
+    // Never 500 on a signup, and never report a success that did not happen.
     console.error(
       `[newsletter] signup failed tenant=${context.locals.tenant?.tenant_id ?? "?"}: ${err instanceof Error ? err.name : "unknown"}`,
     );
-    return respond(context, "subscribed");
+    return respond(context, "failed");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.8.1",
+  "version": "4.9.1",
   "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/image-dependencies.ts

@@ -83,6 +83,12 @@ export interface ImageDependency {
   surface: ImageReferenceSurface;
   disposition: ImageDependencyDisposition;
   reason?: ImageDependencyReason;
+  /**
+   * Set when the reference is an absolute URL on one of the tenant's own origins: the path of the
+   * artifact that holds it. Such a URL is served by the tenant's origin or by nothing, so a gate can
+   * name the file and ask whether a repo file backs it (`tenant-origin-images.ts`).
+   */
+  tenantOriginIn?: string;
 }
 
 export interface ImageDependencyFinding {
@@ -1214,11 +1220,15 @@ export function classifyImageDependency(
     tenantOrigins?: readonly string[];
   },
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
-  return classifyImageDependencyWithPrepared(
+  const { tenantOrigin: _tenantOrigin, ...classified } = classifyImageDependencyWithPrepared(
     locator, context, preparePlatformHostedConfig(context.platformHosted), prepareTenantOrigins(context.tenantOrigins ?? []),
   );
+  return classified;
 }
 
+/** A classification, and whether it came from an absolute URL on one of the tenant's own origins. */
+type Classified = Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> & { tenantOrigin?: true };
+
 function prepareTenantOrigins(tenantOrigins: readonly string[]): ReadonlySet<string> {
   return new Set(tenantOrigins.map(normalizedOrigin).filter((origin): origin is string => origin != null));
 }
@@ -1228,7 +1238,7 @@ function classifyParsedHttpUrl(
   context: { tenantId: string; artifactPath: string },
   platformHosted: PreparedPlatformHostedImageConfig,
   tenantOrigins: ReadonlySet<string>,
-): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
+): Classified {
   if (!absolute.hostname || absolute.username || absolute.password) {
     return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
   }
@@ -1240,7 +1250,7 @@ function classifyParsedHttpUrl(
     // instead of the third-party fallback below. The pathname.startsWith("//") exclusion
     // guards a URL like https://tenant.example//evil.example/x.png, whose pathname would
     // otherwise re-parse as scheme-relative to a DIFFERENT origin on the recursive call.
-    return classifyImageDependencyWithPrepared(`${absolute.pathname}${absolute.search}`, context, platformHosted, tenantOrigins);
+    return { ...classifyImageDependencyWithPrepared(`${absolute.pathname}${absolute.search}`, context, platformHosted, tenantOrigins), tenantOrigin: true };
   }
   absolute.hash = "";
   const canonical = absolute.toString();
@@ -1259,7 +1269,7 @@ function classifyImageDependencyWithPrepared(
   context: { tenantId: string; artifactPath: string },
   platformHosted: PreparedPlatformHostedImageConfig,
   tenantOrigins: ReadonlySet<string>,
-): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
+): Classified {
   const raw = normalizeUrlInput(locator);
   if (!raw || CONTROL_RE.test(raw)) {
     return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
@@ -1485,7 +1495,7 @@ export function scanImageDependencies(
         });
         continue;
       }
-      const classified = classifyImageDependencyWithPrepared(ref.classificationLocator ?? ref.locator, {
+      const { tenantOrigin, ...classified } = classifyImageDependencyWithPrepared(ref.classificationLocator ?? ref.locator, {
         tenantId: options.tenantId,
         artifactPath: artifact.path,
       }, platformHosted, tenantOrigins);
@@ -1495,6 +1505,7 @@ export function scanImageDependencies(
         occurrence,
         surface: ref.surface,
         ...classified,
+        ...(tenantOrigin ? { tenantOriginIn: artifact.path } : {}),
       });
     }
   }

package/packages/public-runtime/src/image-release-gate.ts

@@ -31,15 +31,45 @@ import type { ImageDependency, ImageDependencyArtifact } from "./image-dependenc
 /**
  * `unregistered` and `unsupported-format` are integrity: nothing may publish through them.
  * `unresolved` and `mutable` judge the tenant's own references: an owner may accept them exactly.
+ * `tenant-origin-missing` is not acceptable: an absolute URL on the tenant's own domain that no
+ * file in the release backs is served by nothing once that domain points at the platform, and
+ * capture has no source to fetch it from (see {@link tenantOriginImageGaps}).
  */
-export type ReleaseImageFindingCode = "unregistered" | "unsupported-format" | "unresolved" | "mutable";
+export type ReleaseImageFindingCode = "unregistered" | "unsupported-format" | "unresolved" | "mutable" | "tenant-origin-missing";
 
-export const BLOCKING_RELEASE_IMAGE_CODES: readonly ReleaseImageFindingCode[] = Object.freeze(["unregistered", "unsupported-format"]);
+export const BLOCKING_RELEASE_IMAGE_CODES: readonly ReleaseImageFindingCode[] = Object.freeze(["unregistered", "unsupported-format", "tenant-origin-missing"]);
 
 export interface ReleaseImageFinding {
   code: ReleaseImageFindingCode;
   /** The reference as rendered, query and fragment stripped. */
   ref: string;
+  /** `tenant-origin-missing` only: the files that hold the reference, sorted. */
+  files?: string[];
+}
+
+/**
+ * The tenant-origin image references no file backs. A reference is an absolute URL on one of the
+ * tenant's own origins (`ImageDependency.tenantOriginIn`) that scanning classified as a repo-local
+ * path to capture; `backed` says whether a file at that path exists where the caller looks (the
+ * revision's repo files before capture, the release's files at publish). One entry per reference,
+ * naming the files that hold it.
+ */
+export function tenantOriginImageGaps(
+  dependencies: readonly ImageDependency[],
+  backed: (path: string) => boolean,
+): Array<{ ref: string; files: string[] }> {
+  const holders = new Map<string, Set<string>>();
+  for (const dependency of dependencies) {
+    if (dependency.tenantOriginIn === undefined || dependency.disposition !== "capture-required" || dependency.reason !== "local") continue;
+    const ref = refOf(dependency);
+    if (!ref.startsWith("/") || ref.startsWith("//")) continue;
+    if (backed(ref)) continue;
+    if (!holders.has(ref)) holders.set(ref, new Set());
+    holders.get(ref)!.add(dependency.tenantOriginIn);
+  }
+  return [...holders.entries()]
+    .map(([ref, files]) => ({ ref, files: [...files].sort() }))
+    .sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
 }
 
 export type BundlePathResolution =
@@ -71,7 +101,7 @@ export interface ReleaseImageFacts {
 export interface LegacyImageAllowance {
   tenant: string;
   ref: string;
-  code: Exclude<ReleaseImageFindingCode, "unsupported-format">;
+  code: Exclude<ReleaseImageFindingCode, "unsupported-format" | "tenant-origin-missing">;
   /** Who answers for this entry and removes it by its exit date. */
   owner: string;
   reason: string;
@@ -171,8 +201,16 @@ export function judgeReleaseImages(input: {
     ...input.dependencies.map((dependency) => ({ dependency, structured: false })),
     ...(input.structuredDependencies ?? []).map((dependency) => ({ dependency, structured: true })),
   ];
+  // A tenant-origin reference no release file backs is its own finding, whichever surface renders it.
+  const gaps = tenantOriginImageGaps(tagged.map(({ dependency }) => dependency), (path) => {
+    const rel = bundleRelPath(path);
+    return rel !== null && input.facts.bundlePath(rel).kind !== "absent";
+  });
+  const gapRefs = new Set(gaps.map((gap) => gap.ref));
+  for (const gap of gaps) raw.set(`tenant-origin-missing\0${gap.ref}`, { code: "tenant-origin-missing", ref: gap.ref, files: gap.files });
   for (const { dependency, structured } of tagged) {
     const ref = refOf(dependency);
+    if (dependency.tenantOriginIn !== undefined && gapRefs.has(ref)) continue;
     const key = `${structured}\0${dependency.disposition}\0${dependency.reason ?? ""}\0${ref}`;
     if (seen.has(key)) continue;
     seen.add(key);
@@ -195,7 +233,7 @@ export function judgeReleaseImages(input: {
   const allowed: ReleaseImageFinding[] = [];
   const expired: LegacyImageAllowance[] = [];
   for (const finding of [...raw.values()].sort(compareFindings)) {
-    const allowance = finding.code === "unsupported-format" ? undefined : allowanceFor(input.allowances ?? [], input.tenantId, finding);
+    const allowance = finding.code === "unsupported-format" || finding.code === "tenant-origin-missing" ? undefined : allowanceFor(input.allowances ?? [], input.tenantId, finding);
     if (allowance && Date.parse(allowance.exit) > now) allowed.push(finding);
     else {
       if (allowance) expired.push(allowance);
@@ -215,6 +253,7 @@ export const RELEASE_IMAGE_FINDING_PREFIX: Readonly<Record<ReleaseImageFindingCo
   "unsupported-format": "IMAGE_FORMAT",
   unresolved: "IMAGE_UNRESOLVED",
   mutable: "IMAGE_MUTABLE",
+  "tenant-origin-missing": "IMAGE_TENANT_ORIGIN",
 });
 
 /**
@@ -237,9 +276,28 @@ export function releaseImageFindingText(finding: ReleaseImageFinding): string {
     case "mutable":
       return `${prefix}: ${finding.ref} is a release-local path whose bytes are not pinned to a pool version, so the image ` +
         "it serves can change under the same name — add it with `tot image add <file>` and reference the URL it prints.";
+    case "tenant-origin-missing":
+      return tenantOriginImageText(finding.ref, finding.files ?? [], prefix);
   }
 }
 
+const NAMED_FILES = 5;
+
+/**
+ * The text for a tenant-origin image no file backs: where it is referenced, what path it names, why
+ * that breaks, and the two remedies. Shared by the publish gates and the preview capture pass, so the
+ * remedy reads the same wherever the owner meets it.
+ */
+export function tenantOriginImageText(ref: string, files: readonly string[], prefix = "IMAGE_TENANT_ORIGIN"): string {
+  const shown = files.slice(0, NAMED_FILES).join(", ");
+  const more = files.length > NAMED_FILES ? ` and ${files.length - NAMED_FILES} more` : "";
+  return `${prefix}: ${ref} is referenced as a URL on this store's own domain${shown ? ` in ${shown}${more}` : ""}, but no file in the ` +
+    "repository serves that path, so the image breaks when the domain points at the platform and capture has no source to fetch it from — " +
+    "reference the image at a source URL that is not this store's domain (a Shopify store: " +
+    "`node agency-kit/tools/normalize-shopify-image-urls.mjs --store <checkout>` rewrites /cdn/shop/ references to the shop CDN URL), " +
+    "or add the image with `tot image add <file>` and reference the URL it prints.";
+}
+
 const ALLOWANCE_CODES = new Set(["unregistered", "unresolved", "mutable"]);
 const DATE = /^\d{4}-\d{2}-\d{2}$/;