@tokenoftrust/storefront-runner 3.5.1 → 3.6.1

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

@@ -57,20 +57,6 @@ export interface SyncStateSweepChanges {
   collections: SyncStateEntityChangeSet;
 }
 
-/** Mirrors packages/migration/src/load/sync-state.ts's `ImageRehostRecord`. */
-export interface SyncStateImageRehost {
-  computedAt: string;
-  mode: "rehost" | "reference";
-  sink: string | null;
-  considered: number;
-  rehosted: number;
-  alreadyRehosted: number;
-  referenced: number;
-  errors: number;
-  products: string[];
-  collections: string[];
-}
-
 /** The on-disk shape written by the migration CLI (schema "tot.sync-state/1"). */
 export interface CatalogSyncState {
   schema: string;
@@ -88,13 +74,6 @@ export interface CatalogSyncState {
    * migrated before hsby-B2 (change detection) has no `lastChanges`.
    */
   lastChanges?: SyncStateSweepChanges;
-  /**
-   * What the most recent sync's image rehost moved. Absent when that run moved
-   * no imagery. Recorded separately from `lastChanges` because a rehost rewrites
-   * image urls without touching `source_checksum` — so the content-hash delta
-   * reports those records as unchanged, and this is the only account of the move.
-   */
-  lastImageRehost?: SyncStateImageRehost;
 }
 
 // Vite resolves this glob at build time and bundles every tenant's sync-state

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.5.1",
+  "version": "3.6.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/package.json

@@ -22,6 +22,7 @@
     "./asset-registry": "./src/asset-registry.ts",
     "./responsive-renditions": "./src/responsive-renditions.ts",
     "./svg-sanitize": "./src/svg-sanitize.ts",
+    "./image-release-gate": "./src/image-release-gate.ts",
     "./pool-asset-headers": "./src/pool-asset-headers.ts",
     "./catalog-files": "./src/catalog-files.ts",
     "./embed-catalog": "./src/embed-catalog.mjs",

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

@@ -0,0 +1,267 @@
+/**
+ * The release image gate (ADR 0038 §14): every image reference a release RENDERS — `src`,
+ * `srcset`, CSS `url()`, social metadata, catalog and scene registries as `scanImageDependencies`
+ * extracts them, and the JSON-LD structured data its pages carry ({@link structuredDataArtifacts})
+ * — must resolve to an exact pool version the release can prove. One pure decision shared by every gate that sees rendered output: the bundle validator
+ * (both CDNs' whole-site path), the CloudFront publisher inside the GC fence, and the Cloudflare
+ * publication-space stage. The caller supplies the facts it has proven (bytes hashed, files
+ * present); this module only decides.
+ *
+ * A reference resolves when it is:
+ * - a pool URL (`/_a/<sha256><ext>`) whose bytes the release carries (hashed to the address) or
+ *   whose sealed capture the release records, in a pool format; an SVG only as sanitizer output;
+ * - a release-local tenant path (`/tenants/<id>/...`) whose bundle bytes are pinned to such a pool
+ *   version, so the version the page names is registered and verified with the rest;
+ * - a platform build asset (`/_astro/`, `/shared/`) or an inline `data:` image.
+ * Third-party and unprefixed local references on rendered surfaces belong to the capture gate
+ * (preview captures them; a publish refuses `unaccepted-findings` until the owner accepts each),
+ * and security findings to the scanner, so neither is judged twice here. Structured data is not a
+ * capture surface, so this gate judges it whole: an unprefixed path resolves like a tenant path
+ * (the bundle file, pinned), and a third-party URL is `mutable`.
+ *
+ * Findings name the references (query and fragment stripped) and the remedy. The legacy
+ * allowlist is exact — tenant, reference and finding code — owned, and carries an exit date after
+ * which it no longer applies.
+ *
+ * Import-free (plain node runs it): the pool format table and the SVG sanitizer are passed in as
+ * `formats` (`hosted-image-media-types.ts`, `svg-sanitize.ts`).
+ */
+import type { ImageDependency, ImageDependencyArtifact } from "./image-dependencies.js";
+
+/**
+ * `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.
+ */
+export type ReleaseImageFindingCode = "unregistered" | "unsupported-format" | "unresolved" | "mutable";
+
+export const BLOCKING_RELEASE_IMAGE_CODES: readonly ReleaseImageFindingCode[] = Object.freeze(["unregistered", "unsupported-format"]);
+
+export interface ReleaseImageFinding {
+  code: ReleaseImageFindingCode;
+  /** The reference as rendered, query and fragment stripped. */
+  ref: string;
+}
+
+export type BundlePathResolution =
+  | { kind: "absent" }
+  | { kind: "unpinned" }
+  | { kind: "pinned"; entry: string };
+
+/** The pool's formats: `PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION` and `sanitizeSvg`. */
+export interface PoolImageFormats {
+  mediaTypeByExtension: Readonly<Record<string, string>>;
+  sanitizeSvg(bytes: Uint8Array): { ok: true; changed: boolean } | { ok: false };
+}
+
+/** What the caller has proven about the release it holds. */
+export interface ReleaseImageFacts {
+  /** The release's own copy of pool entry `<sha256><ext>`, already hashed to its address; else null. */
+  heldPoolBytes(entry: string): Uint8Array | null;
+  /** True when the release records `entry` as a sealed capture (`capturedOriginals`). */
+  captured(entry: string): boolean;
+  /**
+   * A bundle path (decoded, no leading slash): absent from the release, present but not pinned, or
+   * pinned to the pool entry its bytes hash to.
+   */
+  bundlePath(relPath: string): BundlePathResolution;
+}
+
+export interface LegacyImageAllowance {
+  tenant: string;
+  ref: string;
+  code: Exclude<ReleaseImageFindingCode, "unsupported-format">;
+  /** Who answers for this entry and removes it by its exit date. */
+  owner: string;
+  reason: string;
+  added: string;
+  /** ISO date after which the entry no longer applies. */
+  exit: string;
+}
+
+export interface ReleaseImageVerdict {
+  findings: ReleaseImageFinding[];
+  /** Every pool entry the rendered output resolves to, sorted: the set to register and verify. */
+  poolEntries: string[];
+  /** Findings a current allowance passed. */
+  allowed: ReleaseImageFinding[];
+  /** Allowances that matched a finding but are past their exit date (the finding stands). */
+  expired: LegacyImageAllowance[];
+}
+
+const POOL_REF = /^\/_a\/([0-9a-f]{64})(\.[A-Za-z0-9]+)?$/;
+const POOL_ENTRY = /^([0-9a-f]{64})(\.[A-Za-z0-9]+)?$/;
+
+function refOf(dependency: ImageDependency): string {
+  return dependency.canonicalLocator.replace(/[?#].*$/, "");
+}
+
+/** `/tenants/<id>/a%20b.png` -> `tenants/<id>/a b.png`, or null when it does not decode exactly. */
+export function bundleRelPath(ref: string): string | null {
+  if (!ref.startsWith("/") || ref.startsWith("//")) return null;
+  try {
+    const segments = new URL(ref, "https://release.invalid").pathname.split("/").slice(1).map(decodeURIComponent);
+    if (segments.some((segment) => !segment || segment === "." || segment === ".." || segment.includes("/"))) return null;
+    return segments.join("/");
+  } catch {
+    return null;
+  }
+}
+
+/** Is a pool entry in a pool format, and when an SVG, exactly the sanitizer's output? */
+function supportedPoolEntry(entry: string, facts: ReleaseImageFacts, formats: PoolImageFormats): boolean {
+  const ext = POOL_ENTRY.exec(entry)?.[2] ?? "";
+  if (!Object.hasOwn(formats.mediaTypeByExtension, ext)) return false;
+  if (ext !== ".svg") return true;
+  const bytes = facts.heldPoolBytes(entry);
+  // A captured SVG is a sealed upload: it entered the pool only as sanitizer output (ADR 0038 §12).
+  if (!bytes) return facts.captured(entry);
+  const result = formats.sanitizeSvg(bytes);
+  return result.ok && !result.changed;
+}
+
+function allowanceFor(allowances: readonly LegacyImageAllowance[], tenantId: string, finding: ReleaseImageFinding) {
+  return allowances.find((allowance) => allowance.tenant === tenantId && allowance.ref === finding.ref &&
+    allowance.code === finding.code);
+}
+
+const LD_JSON = /<script\b[^>]*\btype\s*=\s*["']?application\/ld\+json["']?[^>]*>([\s\S]*?)<\/script\s*>/gi;
+
+/**
+ * The JSON-LD blocks of each HTML artifact, as catalog artifacts at the page's own path (so a
+ * relative URL resolves against the page). Scan them with `scanImageDependencies` and pass the
+ * dependencies as `structuredDependencies`.
+ */
+export function structuredDataArtifacts(artifacts: readonly ImageDependencyArtifact[]): ImageDependencyArtifact[] {
+  const out: ImageDependencyArtifact[] = [];
+  for (const artifact of artifacts) {
+    if ((artifact.kind ?? "html") !== "html") continue;
+    for (const match of artifact.content.matchAll(LD_JSON)) {
+      if (match[1]?.trim()) out.push({ path: artifact.path, kind: "catalog", content: match[1] });
+    }
+  }
+  return out;
+}
+
+export function judgeReleaseImages(input: {
+  tenantId: string;
+  dependencies: readonly ImageDependency[];
+  /** Dependencies scanned from {@link structuredDataArtifacts}. */
+  structuredDependencies?: readonly ImageDependency[];
+  facts: ReleaseImageFacts;
+  formats: PoolImageFormats;
+  allowances?: readonly LegacyImageAllowance[];
+  now?: Date;
+}): ReleaseImageVerdict {
+  const raw = new Map<string, ReleaseImageFinding>();
+  const poolEntries = new Set<string>();
+  const add = (code: ReleaseImageFindingCode, ref: string) => raw.set(`${code}\0${ref}`, { code, ref });
+  // Each distinct reference is judged once, however many pages render it.
+  const seen = new Set<string>();
+  const resolveBundlePath = (ref: string) => {
+    const rel = bundleRelPath(ref);
+    const resolved = rel === null ? { kind: "absent" as const } : input.facts.bundlePath(rel);
+    if (resolved.kind === "absent") add("unresolved", ref);
+    else if (resolved.kind === "unpinned") add("mutable", ref);
+    else if (!supportedPoolEntry(resolved.entry, input.facts, input.formats)) add("unsupported-format", ref);
+    else poolEntries.add(resolved.entry);
+  };
+  const tagged = [
+    ...input.dependencies.map((dependency) => ({ dependency, structured: false })),
+    ...(input.structuredDependencies ?? []).map((dependency) => ({ dependency, structured: true })),
+  ];
+  for (const { dependency, structured } of tagged) {
+    const ref = refOf(dependency);
+    const key = `${structured}\0${dependency.disposition}\0${dependency.reason ?? ""}\0${ref}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (structured && dependency.disposition === "capture-required") {
+      if (dependency.reason === "local") resolveBundlePath(ref);
+      else add("mutable", ref);
+    } else if (dependency.disposition === "platform-hosted") {
+      const pool = POOL_REF.exec(ref);
+      if (!pool) continue;
+      const entry = `${pool[1]}${pool[2] ?? ""}`;
+      if (!input.facts.heldPoolBytes(entry) && !input.facts.captured(entry)) add("unregistered", ref);
+      else if (!supportedPoolEntry(entry, input.facts, input.formats)) add("unsupported-format", ref);
+      else poolEntries.add(entry);
+    } else if (dependency.disposition === "tenant-hosted") {
+      resolveBundlePath(ref);
+    }
+  }
+  const now = (input.now ?? new Date()).getTime();
+  const findings: ReleaseImageFinding[] = [];
+  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);
+    if (allowance && Date.parse(allowance.exit) > now) allowed.push(finding);
+    else {
+      if (allowance) expired.push(allowance);
+      findings.push(finding);
+    }
+  }
+  return { findings, poolEntries: [...poolEntries].sort(), allowed, expired };
+}
+
+function compareFindings(a: ReleaseImageFinding, b: ReleaseImageFinding): number {
+  return a.code === b.code ? (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0) : a.code < b.code ? -1 : 1;
+}
+
+/** The validator prefix for each code; the bundle validator classifies them (`finding-severity.mjs`). */
+export const RELEASE_IMAGE_FINDING_PREFIX: Readonly<Record<ReleaseImageFindingCode, string>> = Object.freeze({
+  unregistered: "IMAGE_UNREGISTERED",
+  "unsupported-format": "IMAGE_FORMAT",
+  unresolved: "IMAGE_UNRESOLVED",
+  mutable: "IMAGE_MUTABLE",
+});
+
+/**
+ * The one text of a finding, shared by every gate so an owner's exact acceptance of it in the
+ * validator is the same acceptance the publisher reads.
+ */
+export function releaseImageFindingText(finding: ReleaseImageFinding): string {
+  const prefix = RELEASE_IMAGE_FINDING_PREFIX[finding.code];
+  switch (finding.code) {
+    case "unregistered":
+      return `${prefix}: ${finding.ref} is a pool URL this release neither carries nor captured, so no version of it is ` +
+        "registered to this store — upload the image with `tot image add <file>` and use the URL it prints, or reference its " +
+        "original so preview captures it.";
+    case "unsupported-format":
+      return `${prefix}: ${finding.ref} is not a pool image format (png, jpg, gif, webp, avif, or an SVG exactly as the ` +
+        "sanitizer outputs it) — convert it, or add an SVG with `tot image add <file>`, which sanitizes it.";
+    case "unresolved":
+      return `${prefix}: ${finding.ref} resolves to no image in this release — add the image with \`tot image add <file>\` ` +
+        "and reference the URL it prints, or fix the path.";
+    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.";
+  }
+}
+
+const ALLOWANCE_CODES = new Set(["unregistered", "unresolved", "mutable"]);
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Parse the legacy allowlist document `{version: 1, owner, entries: [...]}`. Null when it is not
+ * exactly that shape: a gate then refuses rather than guessing which entries were meant.
+ */
+export function parseLegacyImageAllowlist(raw: string): { owner: string; entries: LegacyImageAllowance[] } | null {
+  let parsed: unknown;
+  try { parsed = JSON.parse(raw); } catch { return null; }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const doc = parsed as Record<string, unknown>;
+  if (doc.version !== 1 || typeof doc.owner !== "string" || !doc.owner || !Array.isArray(doc.entries)) return null;
+  const entries: LegacyImageAllowance[] = [];
+  for (const item of doc.entries) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+    const entry = item as Record<string, unknown>;
+    const strings = ["tenant", "ref", "code", "owner", "reason", "added", "exit"] as const;
+    if (strings.some((key) => typeof entry[key] !== "string" || !entry[key]) ||
+        Object.keys(entry).some((key) => !(strings as readonly string[]).includes(key)) ||
+        !ALLOWANCE_CODES.has(entry.code as string) || !DATE.test(entry.added as string) ||
+        !DATE.test(entry.exit as string) || !(entry.ref as string).startsWith("/") ||
+        /[?#]/.test(entry.ref as string) || (entry.exit as string) <= (entry.added as string)) return null;
+    entries.push(entry as unknown as LegacyImageAllowance);
+  }
+  return { owner: doc.owner, entries };
+}