@tokenoftrust/storefront-runner 3.2.0 → 3.3.1

package/agency-kit/tools/lib/catalog-model/model.mjs

@@ -168,6 +168,7 @@ export const CATALOG_MODEL = {
       created_at: "string",
       updated_at: "string",
       migrated_at: "string",
+      "source_created_at?": "string",
       source_checksum: "string",
       "catalog_overrides?": "CatalogOverrideField[]",
     },

package/apps/storefront/src/config/tenants.ts

@@ -98,7 +98,7 @@ export class StaticTenantResolver implements TenantResolver {
 
 export const tenantResolver: TenantResolver = new StaticTenantResolver();
 
-const COMPOSED_PLATFORM_FIELDS = ["access", "pathPrefixTenants"] as const;
+const COMPOSED_PLATFORM_FIELDS = ["access", "pathPrefixTenants", "capabilities"] as const;
 
 /** Same contract as the real registry's withPlatformPolicy — kept in sync by hand. */
 export function withPlatformPolicy(record: TenantConfig): TenantConfig {

package/apps/storefront/src/lib/assets/assetRegistryR2.ts

@@ -0,0 +1,67 @@
+/**
+ * The R2 asset registry document (`registry/assets.json` in `STATIC_BUNDLES`, ADR 0038 §11) for
+ * Worker writers: hosted capture seals and author uploads register the originals they prove a
+ * tenant holds. The record model and its upsert rules are `@tot/public-runtime/asset-registry`, the
+ * same ones the CI publisher applies.
+ *
+ * Each upsert is a compare-and-set on the document's ETag, retried a few times, so two Worker
+ * writers never overwrite each other. A writer that keeps losing gives up (`lost`): its facts are
+ * dropped, which only weakens the record, and the next publish re-registers what the tenant holds.
+ * A document that exists but does not parse is never overwritten from here.
+ */
+import {
+  ASSET_REGISTRY_KEY,
+  MAX_ASSET_REGISTRY_BYTES,
+  applyAssetWrites,
+  emptyAssetRegistry,
+  parseAssetRegistry,
+  serializeAssetRegistry,
+  type AssetRegistry,
+  type AssetRegistryStore,
+  type AssetWrite,
+} from "@tot/public-runtime/asset-registry";
+
+/** The registry's store name in R2; the CI publisher writes the same document under this name. */
+export const R2_ASSET_REGISTRY_STORE = "r2";
+const ATTEMPTS = 4;
+
+export interface AssetRegistryBucket {
+  get(key: string): Promise<{ etag: string; size: number; arrayBuffer(): Promise<ArrayBuffer> } | null>;
+  put(key: string, body: Uint8Array, options: {
+    httpMetadata: { contentType: string; cacheControl: string };
+    onlyIf: { etagMatches: string } | { etagDoesNotMatch: string };
+  }): Promise<unknown>;
+}
+
+async function readDocument(bucket: AssetRegistryBucket): Promise<{ registry: AssetRegistry | null; etag: string | null }> {
+  const object = await bucket.get(ASSET_REGISTRY_KEY);
+  if (!object) return { registry: emptyAssetRegistry(R2_ASSET_REGISTRY_STORE), etag: null };
+  if (object.size > MAX_ASSET_REGISTRY_BYTES) return { registry: null, etag: object.etag };
+  return { registry: parseAssetRegistry(new Uint8Array(await object.arrayBuffer()), R2_ASSET_REGISTRY_STORE), etag: object.etag };
+}
+
+export function createR2AssetRegistry(bucket: AssetRegistryBucket): AssetRegistryStore {
+  return {
+    async read() {
+      return (await readDocument(bucket)).registry;
+    },
+    async upsert(writes: readonly AssetWrite[]) {
+      if (writes.length === 0) return "unchanged";
+      for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+        const { registry, etag } = await readDocument(bucket);
+        if (!registry) return "lost";
+        const next = applyAssetWrites(registry, writes);
+        if (!next.changed) return "unchanged";
+        const body = serializeAssetRegistry(next.registry);
+        if (body.byteLength > MAX_ASSET_REGISTRY_BYTES) return "lost";
+        // R2 answers a failed precondition with null rather than an error.
+        const put = await bucket.put(ASSET_REGISTRY_KEY, body, {
+          httpMetadata: { contentType: "application/json", cacheControl: "no-store" },
+          onlyIf: etag === null ? { etagDoesNotMatch: "*" } : { etagMatches: etag },
+        });
+        if (put) return "written";
+      }
+      return "lost";
+    },
+  };
+}

package/apps/storefront/src/lib/assets/captured-original-serve.ts

@@ -5,10 +5,12 @@
  * when the sealed revision manifest names the address.
  */
 import { sha256Hex } from "@tot/public-runtime";
-import { CAPTURABLE_RASTER_MEDIA_TYPES, PINNED_ASSET_EXTENSION_BY_MEDIA_TYPE } from "@tot/public-runtime/hosted-image-media-types";
+import {
+  PINNED_ASSET_EXTENSION_BY_MEDIA_TYPE, PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION, sealedMediaTypeAllowed,
+} from "@tot/public-runtime/hosted-image-media-types";
 import { durableAssetsStatusKey, durableCaptureRevisionId, durableRequiredStores, parseDurableAssetsStatus } from "@tot/public-runtime/durable-assets";
+import { POOL_ASSET_SECURITY_HEADERS } from "@tot/public-runtime/pool-asset-headers";
 
-const CAPTURE_TYPES = new Set<string>(CAPTURABLE_RASTER_MEDIA_TYPES);
 const ADDRESS_RE = /^[0-9a-f]{64}$/;
 /** Hostname-like tenant ids (no scheme, no path separators). */
 const TENANT_ID_RE = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/i;
@@ -27,14 +29,8 @@ function originalImageManifestObjectKey(tenantId: string, revisionId: string): s
   return `original-images/${tenantId}/revisions/${revisionId}/manifest.json`;
 }
 
-const EXT_TYPE: Record<string, string> = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".avif": "image/avif",
-};
+/** The shared pinned table, plus the `.jpeg` spelling a hand-written reference may use. */
+const EXT_TYPE: Record<string, string> = { ...PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION, ".jpeg": "image/jpeg" };
 
 export type CapturedOriginalBucket = {
   get(key: string): Promise<unknown>;
@@ -84,7 +80,7 @@ async function readManifestEntries(
       const entry = raw as Partial<ManifestEntry>;
       if (typeof entry.address !== "string" || !ADDRESS_RE.test(entry.address)) return null;
       if (!Number.isSafeInteger(entry.byteLength) || entry.byteLength! < 1 || entry.byteLength! > 8 * 1024 * 1024 ||
-          typeof entry.mediaType !== "string" || !CAPTURE_TYPES.has(entry.mediaType)) return null;
+          !sealedMediaTypeAllowed(entry.provenance?.kind, entry.mediaType)) return null;
       entries.push({
         address: entry.address,
         byteLength: entry.byteLength!,
@@ -184,6 +180,7 @@ export async function tryServeCapturedOriginal(input: {
       "cache-control": durable ? "no-store" : "public, max-age=31536000, immutable",
       "x-tot-original-image": durable ? "durable" : "revision-bound",
       "content-length": String(bytes.byteLength),
+      ...POOL_ASSET_SECURITY_HEADERS,
     };
     const method = (input.method ?? "GET").toUpperCase();
     return new Response(method === "HEAD" ? null : bytes, { status: 200, headers });

package/apps/storefront/src/lib/assets/durableR2.ts

@@ -8,7 +8,7 @@
  * bundle-GC sweep holds its lease, then stage and verify every object those references name.
  */
 import { sha256Hex } from "@tot/public-runtime";
-import { PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION } from "@tot/public-runtime/hosted-image-media-types";
+import { PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION, sealedMediaTypeAllowed } from "@tot/public-runtime/hosted-image-media-types";
 import {
   durableAssetsStatusKey,
   durableCaptureRevisionId,
@@ -19,6 +19,7 @@ import {
   type DurableAssetRecord,
 } from "@tot/public-runtime/durable-assets";
 import { GC_LEASE_KEY, awaitGcQuiescence } from "@tot/public-runtime/retention-holds";
+import { authorizeAssetReference, type AssetRegistryStore, type AssetWrite } from "@tot/public-runtime/asset-registry";
 
 const MAX_IMAGE = 8 * 1024 * 1024;
 const MAX_MANIFEST = 1024 * 1024;
@@ -143,20 +144,45 @@ async function capturedBytes(captureBucket: R2BucketLike, tenant: string, entry:
  * Stage every captured original a version manifest records (`capturedOriginals`) into the public
  * pool. The caller has already established the reference (the version manifest in this bucket) and
  * waited at the fence.
+ *
+ * The pool is shared by every tenant, so an object being there says nothing about who may reference
+ * it (ADR 0038 §11). Each entry must be registered to this tenant in the asset registry, or be in the
+ * tenant's own capture store (which registers it); otherwise nothing is staged and the go-live
+ * refuses `asset-unauthorized`.
  */
 export async function stageCapturedOriginalsR2(input: {
   tenant: string;
   entries: readonly string[];
   captureBucket: R2BucketLike;
   publicBucket: R2BucketLike;
+  registry?: AssetRegistryStore;
 }): Promise<number> {
+  const registry = input.registry ? await input.registry.read().catch(() => null) : null;
+  const owned = new Map<string, Uint8Array>();
+  const unauthorized: string[] = [];
+  for (const entry of input.entries) {
+    if (authorizeAssetReference([registry], input.tenant, entry).ok) continue;
+    const own = await capturedBytes(input.captureBucket, input.tenant, entry).catch((error: unknown) => {
+      if (error instanceof R2StagingError) return null;
+      throw error;
+    });
+    if (own) owned.set(entry, own);
+    else unauthorized.push(entry);
+  }
+  if (input.registry && owned.size > 0) {
+    const writes: AssetWrite[] = [...owned].map(([entry, bytes]) => ({
+      entry, tenant: input.tenant, mediaType: mediaTypeOf(entry), size: bytes.byteLength,
+    }));
+    await input.registry.upsert(writes).catch(() => "lost");
+  }
+  if (unauthorized.length > 0) throw new R2StagingError("asset-unauthorized");
   let staged = 0;
   for (const entry of input.entries) {
     const key = `assets/${entry}`;
     const present = await readBounded(input.publicBucket, key, MAX_IMAGE);
     const address = POOL_ENTRY_RE.exec(entry)?.[1];
     if (present && address && await sha256Hex(present) === address) continue;
-    await ensurePoolObject(input.publicBucket, key, await capturedBytes(input.captureBucket, input.tenant, entry), mediaTypeOf(entry));
+    await ensurePoolObject(input.publicBucket, key, owned.get(entry) ?? await capturedBytes(input.captureBucket, input.tenant, entry), mediaTypeOf(entry));
     staged++;
   }
   return staged;
@@ -203,6 +229,8 @@ export async function designateDurableR2(input: {
   kv: StatusKvLike;
   now?: () => Date;
   awaitQuiescence?: QuiescenceWaiter;
+  /** The pool's asset registry: each verified designation is recorded as a transition to `durable`. */
+  registry?: AssetRegistryStore;
 }): Promise<DurableDesignationResult> {
   if (input.images.length === 0) return { ok: true, designated: [] };
   const revision = durableCaptureRevisionId(input.revision);
@@ -211,7 +239,7 @@ export async function designateDurableR2(input: {
   if (manifestBytes) {
     const manifest = JSON.parse(new TextDecoder().decode(manifestBytes)) as {
       version?: unknown; revisionId?: unknown;
-      entries?: Array<{ address?: unknown; byteLength?: unknown; mediaType?: unknown; provenance?: { locator?: unknown } }>;
+      entries?: Array<{ address?: unknown; byteLength?: unknown; mediaType?: unknown; provenance?: { kind?: unknown; locator?: unknown } }>;
     };
     if (manifest.version !== 1 || manifest.revisionId !== revision || !Array.isArray(manifest.entries)) {
       throw new R2StagingError("manifest-invalid");
@@ -219,6 +247,7 @@ export async function designateDurableR2(input: {
     for (const entry of manifest.entries) {
       if (typeof entry?.address !== "string" || !/^[0-9a-f]{64}$/.test(entry.address) ||
         typeof entry.byteLength !== "number" || typeof entry.mediaType !== "string" ||
+        !sealedMediaTypeAllowed(entry.provenance?.kind, entry.mediaType) ||
         typeof entry.provenance?.locator !== "string") throw new R2StagingError("manifest-invalid");
       byLocator.set(entry.provenance.locator, { address: entry.address, byteLength: entry.byteLength, mediaType: entry.mediaType });
     }
@@ -249,6 +278,11 @@ export async function designateDurableR2(input: {
   }
   await recordDurableStatusKv(input.kv, input.tenant, { revision: input.revision, at: now().toISOString(), declared,
     designated: prepared.map((item) => ({ entry: item.entry, name: item.image.name, source: item.image.source, verifiedStores: ["r2"] })) });
+  // A record, not the retention mechanism: the hold above is what the bundle GC honours.
+  await input.registry?.upsert(prepared.map((item) => ({
+    entry: item.entry, tenant: input.tenant, mediaType: item.mediaType,
+    retention: { to: "durable" as const, at, how: "designation" },
+  }))).catch(() => "lost");
   return { ok: true, designated: declared };
 }
 
@@ -263,6 +297,8 @@ export function makeWorkerR2PinnedOriginalStager(deps: {
   publicBucket: R2BucketLike;
   captureBucket: R2BucketLike;
   kv: StatusKvLike;
+  /** The pool's asset registry (`STATIC_BUNDLES` `registry/assets.json`). */
+  registry?: AssetRegistryStore;
   now?: () => Date;
   awaitQuiescence?: QuiescenceWaiter;
 }) {
@@ -281,12 +317,13 @@ export function makeWorkerR2PinnedOriginalStager(deps: {
     }
     await awaitR2Quiescence(deps.publicBucket, deps.awaitQuiescence);
     await stageCapturedOriginalsR2({ tenant: tenantId, entries: entries as string[],
-      captureBucket: deps.captureBucket, publicBucket: deps.publicBucket });
+      captureBucket: deps.captureBucket, publicBucket: deps.publicBucket, ...(deps.registry ? { registry: deps.registry } : {}) });
     const images = manifest.durableAssets?.images ?? [];
     if (images.length > 0) {
       if (typeof manifest.sourceSha !== "string") throw new R2StagingError("manifest-invalid");
       const result = await designateDurableR2({ tenant: tenantId, revision: manifest.sourceSha, images,
         captureBucket: deps.captureBucket, publicBucket: deps.publicBucket, kv: deps.kv,
+        ...(deps.registry ? { registry: deps.registry } : {}),
         ...(deps.now ? { now: deps.now } : {}), ...(deps.awaitQuiescence ? { awaitQuiescence: deps.awaitQuiescence } : {}) });
       if (!result.ok) throw new R2StagingError(result.reason);
     }

package/apps/storefront/src/lib/assets/durableR2Bindings.ts

@@ -6,6 +6,7 @@
  */
 import { readKv, readR2 } from "@/lib/publication/shared/env";
 import { makeWorkerR2PinnedOriginalStager, R2StagingError, type R2BucketLike, type StatusKvLike } from "./durableR2.js";
+import { createR2AssetRegistry, type AssetRegistryBucket } from "./assetRegistryR2.js";
 
 export async function workerR2PinnedOriginalStagerFromEnv(): Promise<
   (args: { tenantId: string; versionId: string; treeDigest?: string | null }) => Promise<void>
@@ -27,5 +28,6 @@ export async function workerR2PinnedOriginalStagerFromEnv(): Promise<
     publicBucket: publicBucket as unknown as R2BucketLike,
     captureBucket: captureBucket as unknown as R2BucketLike,
     kv: kv as unknown as StatusKvLike,
+    registry: createR2AssetRegistry(publicBucket as unknown as AssetRegistryBucket),
   });
 }

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

@@ -29,16 +29,15 @@ export function isAvailable(p: CatalogProduct): boolean {
 
 /**
  * "New" is the product's real age. The `new` tag is the merchant's explicit call. Otherwise a
- * product is new only when it has a known creation date inside the window: a record with no
- * creation date, or whose `created_at` is no earlier than its `migrated_at` (the import stamped
- * it, so it says when the record arrived, not when the product was created), is not new.
+ * product is new only when its `source_created_at` (the creation date the source system
+ * reported) is inside the window. `created_at` and `migrated_at` say when a record arrived, never
+ * how old the product is, so they do not age the badge; a record with no readable
+ * `source_created_at` is not new.
  */
 export function isNew(p: CatalogProduct, days = 60): boolean {
   if (p.tags.includes("new")) return true;
-  const created = Date.parse(p.created_at);
+  const created = Date.parse(p.source_created_at ?? "");
   if (Number.isNaN(created)) return false;
-  const migrated = Date.parse(p.migrated_at);
-  if (!Number.isNaN(migrated) && created >= migrated) return false;
   return Date.now() - created < days * 24 * 60 * 60 * 1000;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "3.2.0",
+  "version": "3.3.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

@@ -19,6 +19,9 @@
     "./extension-contract-values": "./src/extension-contract-values.mjs",
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
+    "./asset-registry": "./src/asset-registry.ts",
+    "./svg-sanitize": "./src/svg-sanitize.ts",
+    "./pool-asset-headers": "./src/pool-asset-headers.ts",
     "./catalog-files": "./src/catalog-files.ts",
     "./embed-catalog": "./src/embed-catalog.mjs",
     "./retention-holds": "./src/retention-holds.ts",

package/packages/public-runtime/src/asset-registry.ts

@@ -0,0 +1,403 @@
+/**
+ * The asset registry record model (ADR 0038 §11): one address-keyed record per content-addressed
+ * pool object (`assets/<sha256><ext>`), held in one document per store (`registry/assets.json`, in
+ * the S3 tenant bucket and in R2 `STATIC_BUNDLES`). Every writer — capture seal, upload ingest,
+ * durable designation, publish verification — upserts the same record through
+ * {@link applyAssetWrite}; every reader parses it through {@link parseAssetRegistry}. The I/O and the
+ * byte audit live in `scripts/publish/lib/asset-registry.mjs` (CI) and
+ * `apps/storefront/src/lib/assets/assetRegistryR2.ts` (Worker).
+ *
+ * A record's facets are independent. Each is validated on its own; an invalid facet is dropped, never
+ * repaired, so a damaged document can only lose facts. Writers read the document, apply their writes
+ * and put it back: a writer that loses a race loses its writes, which only removes facts (a tenant's
+ * authorization, a verification, a retention transition). No facet is ever added except by a writer
+ * that observed it, so no interleaving can fabricate one.
+ *
+ * Import-free on purpose: plain node runs it without a workspace install (the retention job).
+ */
+
+export const ASSET_REGISTRY_KEY = "registry/assets.json";
+export const ASSET_REGISTRY_VERSION = 1;
+/** Bounds the document a reader will parse. */
+export const MAX_ASSET_REGISTRY_BYTES = 32 * 1024 * 1024;
+
+export type VerificationMethod = "byte-read" | "create-readback" | "audit";
+export interface VerifiedFacet { size: number; etag: string; at: string; how: VerificationMethod }
+
+export type AssetProvenanceKind = "capture" | "upload" | "repo" | "variant";
+export interface AssetProvenance {
+  kind: AssetProvenanceKind;
+  /** Where the bytes first came from: a query-stripped source URL, a repo path, or the pool URL. */
+  locator?: string;
+  /** The first tenant revision the address was sealed or built in. */
+  firstRevision?: string;
+  at: string;
+}
+
+export type AssetRecipe =
+  | { kind: "original" }
+  | { kind: "sanitized"; sanitizer: string; source: string }
+  | { kind: "variant"; parent: string; width: number; format: string; encoder: string };
+
+export type RetentionClass = "release" | "durable" | "external-use" | "removal-requested";
+export interface RetentionTransition {
+  from: RetentionClass;
+  to: RetentionClass;
+  at: string;
+  /** What made the change: a designation, a declaration drop, an owner operation. */
+  how: string;
+  /** Opaque actor id of the owner who made it, when an owner did. */
+  actor?: string;
+}
+export interface RetentionFacet { class: RetentionClass; transitions: RetentionTransition[] }
+
+export interface AssetRecord {
+  address: string;
+  mediaType?: string;
+  size?: number;
+  provenance?: AssetProvenance;
+  /** Tenants authorized to reference this address: each one proved it holds the bytes. */
+  tenants?: string[];
+  /** Opaque actor id of the first owner who brought the bytes in. */
+  owner?: string;
+  recipe?: AssetRecipe;
+  /** Entries (`<sha256><ext>`) derived from this one. */
+  renditions?: string[];
+  verified?: VerifiedFacet;
+  retention?: RetentionFacet;
+}
+
+export interface AssetRegistry {
+  version: 1;
+  kind: "asset-registry";
+  store: string;
+  assets: Record<string, AssetRecord>;
+}
+
+/** One writer's facts about one entry. Absent fields leave the record as it is. */
+export interface AssetWrite {
+  entry: string;
+  mediaType?: string;
+  size?: number;
+  provenance?: AssetProvenance;
+  tenant?: string;
+  owner?: string;
+  recipe?: AssetRecipe;
+  rendition?: string;
+  verified?: VerifiedFacet;
+  retention?: { to: RetentionClass; at: string; how: string; actor?: string };
+}
+
+const ENTRY_RE = /^([0-9a-f]{64})(\.[A-Za-z0-9]+)?$/;
+const POOL_KEY_RE = /^assets\/([0-9a-f]{64})(\.[A-Za-z0-9]+)?$/;
+const ETAG_RE = /^[A-Za-z0-9-]{1,128}$/;
+const TENANT_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const ACTOR_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const REVISION_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const MEDIA_TYPE_RE = /^[a-z]+\/[a-z0-9.+-]{1,64}$/;
+const TOKEN_RE = /^[A-Za-z0-9._:-]{1,64}$/;
+const HOW = new Set<string>(["byte-read", "create-readback", "audit"]);
+const PROVENANCE_KINDS = new Set<string>(["capture", "upload", "repo", "variant"]);
+const RETENTION_CLASSES = new Set<string>(["release", "durable", "external-use", "removal-requested"]);
+const MAX_TENANTS = 256;
+const MAX_RENDITIONS = 64;
+const MAX_TRANSITIONS = 32;
+const MAX_LOCATOR = 2048;
+
+/**
+ * The retention transitions an owner or a designation may make. A record with no retention facet is
+ * `release`. The pool GCs still decide deletion from the create-only holds and removal records
+ * (ADR 0038 §4–§6), so a lost write of this facet never shortens what is kept.
+ */
+export const RETENTION_TRANSITIONS: Readonly<Record<RetentionClass, readonly RetentionClass[]>> = Object.freeze({
+  release: ["durable", "external-use"],
+  "external-use": ["durable", "removal-requested"],
+  durable: ["removal-requested"],
+  "removal-requested": ["durable", "external-use", "release"],
+});
+
+/** The pool key's registry entry name (`<sha256><ext>`) and address, or null for any other key. */
+export function poolEntry(key: string): { entry: string; address: string } | null {
+  const match = POOL_KEY_RE.exec(key);
+  return match ? { entry: key.slice("assets/".length), address: match[1]! } : null;
+}
+
+/** The address of an entry name (`<sha256><ext>`), or null. */
+export function entryAddress(entry: string): string | null {
+  return ENTRY_RE.exec(entry)?.[1] ?? null;
+}
+
+/** An ETag without its quotes, as both S3 and R2 listings and GETs report it. */
+export function normalizeEtag(etag: unknown): string {
+  return typeof etag === "string" ? etag.replace(/"/g, "") : "";
+}
+
+export function emptyAssetRegistry(store: string): AssetRegistry {
+  return { version: ASSET_REGISTRY_VERSION, kind: "asset-registry", store, assets: {} };
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function validTime(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 64 && !Number.isNaN(Date.parse(value));
+}
+
+function validLocator(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= MAX_LOCATOR && !/[?#\u0000-\u001f]/.test(value);
+}
+
+function normalizeVerified(raw: unknown): VerifiedFacet | null {
+  if (!isObject(raw) || !Number.isSafeInteger(raw.size) || (raw.size as number) < 1 ||
+      typeof raw.etag !== "string" || !ETAG_RE.test(raw.etag) || typeof raw.at !== "string" ||
+      typeof raw.how !== "string" || !HOW.has(raw.how)) return null;
+  return { size: raw.size as number, etag: raw.etag, at: raw.at, how: raw.how as VerificationMethod };
+}
+
+function normalizeProvenance(raw: unknown): AssetProvenance | null {
+  if (!isObject(raw) || typeof raw.kind !== "string" || !PROVENANCE_KINDS.has(raw.kind) || !validTime(raw.at)) return null;
+  if (raw.locator !== undefined && !validLocator(raw.locator)) return null;
+  if (raw.firstRevision !== undefined && (typeof raw.firstRevision !== "string" || !REVISION_RE.test(raw.firstRevision))) return null;
+  return {
+    kind: raw.kind as AssetProvenanceKind, at: raw.at,
+    ...(raw.locator !== undefined ? { locator: raw.locator as string } : {}),
+    ...(raw.firstRevision !== undefined ? { firstRevision: raw.firstRevision as string } : {}),
+  };
+}
+
+function normalizeRecipe(raw: unknown): AssetRecipe | null {
+  if (!isObject(raw)) return null;
+  if (raw.kind === "original") return { kind: "original" };
+  if (raw.kind === "sanitized" && typeof raw.sanitizer === "string" && TOKEN_RE.test(raw.sanitizer) &&
+      typeof raw.source === "string" && entryAddress(raw.source) !== null) {
+    return { kind: "sanitized", sanitizer: raw.sanitizer, source: raw.source };
+  }
+  if (raw.kind === "variant" && typeof raw.parent === "string" && entryAddress(raw.parent) !== null &&
+      Number.isSafeInteger(raw.width) && (raw.width as number) > 0 && (raw.width as number) <= 16384 &&
+      typeof raw.format === "string" && TOKEN_RE.test(raw.format) &&
+      typeof raw.encoder === "string" && TOKEN_RE.test(raw.encoder)) {
+    return { kind: "variant", parent: raw.parent, width: raw.width as number, format: raw.format, encoder: raw.encoder };
+  }
+  return null;
+}
+
+function normalizeTransition(raw: unknown): RetentionTransition | null {
+  if (!isObject(raw) || typeof raw.from !== "string" || typeof raw.to !== "string" ||
+      !RETENTION_CLASSES.has(raw.from) || !RETENTION_CLASSES.has(raw.to) || !validTime(raw.at) ||
+      typeof raw.how !== "string" || !TOKEN_RE.test(raw.how)) return null;
+  if (raw.actor !== undefined && (typeof raw.actor !== "string" || !ACTOR_RE.test(raw.actor))) return null;
+  return {
+    from: raw.from as RetentionClass, to: raw.to as RetentionClass, at: raw.at, how: raw.how,
+    ...(raw.actor !== undefined ? { actor: raw.actor as string } : {}),
+  };
+}
+
+/**
+ * The retention facet, or null. Its class must be where its own transition log ends: a facet whose
+ * log does not chain, or whose class contradicts the log, is dropped as a whole.
+ */
+function normalizeRetention(raw: unknown): RetentionFacet | null {
+  if (!isObject(raw) || typeof raw.class !== "string" || !RETENTION_CLASSES.has(raw.class) ||
+      !Array.isArray(raw.transitions) || raw.transitions.length > MAX_TRANSITIONS) return null;
+  const transitions: RetentionTransition[] = [];
+  for (const item of raw.transitions) {
+    const transition = normalizeTransition(item);
+    if (!transition || !RETENTION_TRANSITIONS[transition.from].includes(transition.to)) return null;
+    const previous = transitions[transitions.length - 1];
+    if (previous && previous.to !== transition.from) return null;
+    transitions.push(transition);
+  }
+  const last = transitions[transitions.length - 1];
+  if ((last ? last.to : "release") !== raw.class) return null;
+  return { class: raw.class as RetentionClass, transitions };
+}
+
+function sortedUnique(values: readonly string[], limit: number): string[] {
+  return [...new Set(values)].sort().slice(0, limit);
+}
+
+/**
+ * One stored record, facet by facet. Null when the entry or its address is not a pool address: then
+ * nothing about it can be trusted. Any other invalid facet is dropped and the rest kept.
+ */
+export function normalizeAssetRecord(entry: string, raw: unknown): AssetRecord | null {
+  const address = entryAddress(entry);
+  if (!address || !isObject(raw) || raw.address !== address) return null;
+  const record: AssetRecord = { address };
+  if (typeof raw.mediaType === "string" && MEDIA_TYPE_RE.test(raw.mediaType)) record.mediaType = raw.mediaType;
+  if (Number.isSafeInteger(raw.size) && (raw.size as number) > 0) record.size = raw.size as number;
+  const provenance = normalizeProvenance(raw.provenance);
+  if (provenance) record.provenance = provenance;
+  if (Array.isArray(raw.tenants)) {
+    const tenants = raw.tenants.filter((tenant): tenant is string => typeof tenant === "string" && TENANT_RE.test(tenant));
+    if (tenants.length > 0) record.tenants = sortedUnique(tenants, MAX_TENANTS);
+  }
+  if (typeof raw.owner === "string" && ACTOR_RE.test(raw.owner)) record.owner = raw.owner;
+  const recipe = normalizeRecipe(raw.recipe);
+  if (recipe) record.recipe = recipe;
+  if (Array.isArray(raw.renditions)) {
+    const renditions = raw.renditions.filter((item): item is string => typeof item === "string" && entryAddress(item) !== null);
+    if (renditions.length > 0) record.renditions = sortedUnique(renditions, MAX_RENDITIONS);
+  }
+  const verified = normalizeVerified(raw.verified);
+  if (verified) record.verified = verified;
+  const retention = normalizeRetention(raw.retention);
+  if (retention) record.retention = retention;
+  return record;
+}
+
+/**
+ * Parse a stored document. Null when it is not a registry for `store`: the caller then trusts no
+ * record and leaves the document alone.
+ */
+export function parseAssetRegistry(raw: Uint8Array | string, store: string): AssetRegistry | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(typeof raw === "string" ? raw : new TextDecoder("utf-8", { fatal: true }).decode(raw));
+  } catch { return null; }
+  if (!isObject(parsed) || parsed.version !== ASSET_REGISTRY_VERSION || parsed.kind !== "asset-registry" ||
+      parsed.store !== store || !isObject(parsed.assets)) return null;
+  const registry = emptyAssetRegistry(store);
+  for (const [entry, value] of Object.entries(parsed.assets)) {
+    const record = normalizeAssetRecord(entry, value);
+    if (record && !isEmptyAssetRecord(record)) registry.assets[entry] = record;
+  }
+  return registry;
+}
+
+export function serializeAssetRegistry(registry: AssetRegistry): Uint8Array {
+  return new TextEncoder().encode(JSON.stringify(registry));
+}
+
+/** True when the record carries nothing but its address. */
+export function isEmptyAssetRecord(record: AssetRecord): boolean {
+  return Object.keys(record).length === 1;
+}
+
+/**
+ * Apply one writer's facts to a record and return the result (`existing` is not mutated).
+ *
+ * - `mediaType`, `size`, `provenance`, `owner`, `recipe`: the first writer's value stands. These
+ *   describe immutable bytes, so a later writer has nothing to add.
+ * - `tenants`, `renditions`: a union.
+ * - `verified`: the latest verification replaces the earlier one.
+ * - `retention`: a transition is applied only when the current class allows it
+ *   ({@link RETENTION_TRANSITIONS}); a write naming the current class is a no-op. `rejected` reports
+ *   a transition that was not allowed.
+ *
+ * An invalid fact is ignored, never coerced.
+ */
+export function applyAssetWrite(existing: AssetRecord | undefined, write: AssetWrite): { record: AssetRecord | null; rejected?: string } {
+  const address = entryAddress(write.entry);
+  if (!address || (existing && existing.address !== address)) return { record: existing ?? null };
+  const record: AssetRecord = existing ? structuredCloneRecord(existing) : { address };
+  if (record.mediaType === undefined && write.mediaType !== undefined && MEDIA_TYPE_RE.test(write.mediaType)) record.mediaType = write.mediaType;
+  if (record.size === undefined && Number.isSafeInteger(write.size) && (write.size as number) > 0) record.size = write.size as number;
+  if (record.provenance === undefined && write.provenance) {
+    const provenance = normalizeProvenance(write.provenance);
+    if (provenance) record.provenance = provenance;
+  }
+  if (write.tenant !== undefined && TENANT_RE.test(write.tenant)) {
+    record.tenants = sortedUnique([...(record.tenants ?? []), write.tenant], MAX_TENANTS);
+  }
+  if (record.owner === undefined && write.owner !== undefined && ACTOR_RE.test(write.owner)) record.owner = write.owner;
+  if (record.recipe === undefined && write.recipe) {
+    const recipe = normalizeRecipe(write.recipe);
+    if (recipe) record.recipe = recipe;
+  }
+  if (write.rendition !== undefined && entryAddress(write.rendition) !== null) {
+    record.renditions = sortedUnique([...(record.renditions ?? []), write.rendition], MAX_RENDITIONS);
+  }
+  if (write.verified) {
+    const verified = normalizeVerified(write.verified);
+    if (verified) record.verified = verified;
+  }
+  let rejected: string | undefined;
+  if (write.retention) {
+    const from = record.retention?.class ?? "release";
+    const transition = normalizeTransition({ from, ...write.retention });
+    if (!transition) rejected = "retention-invalid";
+    else if (transition.to !== from) {
+      if (!RETENTION_TRANSITIONS[from].includes(transition.to)) rejected = `retention ${from} -> ${transition.to} is not allowed`;
+      else {
+        record.retention = {
+          class: transition.to,
+          transitions: [...(record.retention?.transitions ?? []), transition].slice(-MAX_TRANSITIONS),
+        };
+      }
+    }
+  }
+  return rejected ? { record, rejected } : { record };
+}
+
+function structuredCloneRecord(record: AssetRecord): AssetRecord {
+  return JSON.parse(JSON.stringify(record)) as AssetRecord;
+}
+
+/** Apply a batch of writes to a registry, returning a new registry and whether anything changed. */
+export function applyAssetWrites(registry: AssetRegistry, writes: Iterable<AssetWrite>): { registry: AssetRegistry; changed: boolean; rejected: string[] } {
+  const next: AssetRegistry = { ...registry, assets: { ...registry.assets } };
+  let changed = false;
+  const rejected: string[] = [];
+  for (const write of writes) {
+    const before = next.assets[write.entry];
+    const result = applyAssetWrite(before, write);
+    if (result.rejected) rejected.push(`${write.entry}: ${result.rejected}`);
+    if (!result.record || isEmptyAssetRecord(result.record)) continue;
+    if (!before || JSON.stringify(before) !== JSON.stringify(result.record)) {
+      next.assets[write.entry] = result.record;
+      changed = true;
+    }
+  }
+  return { registry: next, changed, rejected };
+}
+
+/**
+ * One store's registry document, for a writer outside CI (the Worker's R2 store). `upsert` applies
+ * the writes to the current document and puts it back; `lost` means a concurrent writer won and
+ * these facts were dropped, which callers treat as the weakening the model allows.
+ */
+export interface AssetRegistryStore {
+  read(): Promise<AssetRegistry | null>;
+  upsert(writes: readonly AssetWrite[]): Promise<"written" | "unchanged" | "lost">;
+}
+
+export type AssetAuthorization =
+  | { ok: true }
+  | { ok: false; code: "asset-unauthorized"; entry: string; message: string };
+
+/**
+ * May `tenantId` reference the pool object `entry`? Only when a record for it lists the tenant.
+ * Content addressing deduplicates bytes across tenants; it never shares authorization: a tenant is
+ * listed only by a writer that saw that tenant hold the bytes (its own upload, its own sealed
+ * capture, its own built bundle). Pass every registry the caller can read; any one listing the
+ * tenant authorizes.
+ */
+export function authorizeAssetReference(
+  registries: readonly (AssetRegistry | null | undefined)[], tenantId: string, entry: string,
+): AssetAuthorization {
+  if (TENANT_RE.test(tenantId) && entryAddress(entry) !== null &&
+      registries.some((registry) => registry?.assets[entry]?.tenants?.includes(tenantId))) return { ok: true };
+  return {
+    ok: false, code: "asset-unauthorized", entry,
+    message: `/_a/${entry} is not registered to this store: it was not uploaded, captured or built by this tenant. ` +
+      "Upload the image with `tot image add <file>` (or reference its original source) and use the URL it prints.",
+  };
+}
+
+/**
+ * The tenants a record lists other than `tenantId`, without naming them: true when the address is
+ * registered and this tenant is not among its tenants. Capture uses it to refuse a reference to
+ * another tenant's image while leaving unregistered legacy references to the publisher.
+ */
+export function registeredToOthers(registries: readonly (AssetRegistry | null | undefined)[], tenantId: string, entry: string): boolean {
+  let listed = false;
+  for (const registry of registries) {
+    const tenants = registry?.assets[entry]?.tenants;
+    if (!tenants) continue;
+    if (tenants.includes(tenantId)) return false;
+    listed = true;
+  }
+  return listed;
+}

package/packages/public-runtime/src/hosted-image-media-types.ts

@@ -43,3 +43,18 @@ export type CapturableRasterMediaType = (typeof CAPTURABLE_RASTER_MEDIA_TYPES)[n
 
 /** Comma-joined for an HTTP `Accept` header -- derived, never a second literal. */
 export const CAPTURABLE_RASTER_ACCEPT_HEADER = CAPTURABLE_RASTER_MEDIA_TYPES.join(",");
+
+/**
+ * An author upload may also be an SVG: the upload path is the one ingest that sanitizes it
+ * (`svg-sanitize.ts`) before it enters the pool, so a sealed `upload` entry may carry it while a
+ * captured (`local`/`remote`) entry never does.
+ */
+export const UPLOADABLE_MEDIA_TYPES = Object.freeze([...CAPTURABLE_RASTER_MEDIA_TYPES, "image/svg+xml"] as const);
+
+export type UploadableMediaType = (typeof UPLOADABLE_MEDIA_TYPES)[number];
+
+/** May a sealed original of provenance `kind` carry `mediaType`? Every reader of a manifest asks this. */
+export function sealedMediaTypeAllowed(kind: unknown, mediaType: unknown): boolean {
+  const types: readonly string[] = kind === "upload" ? UPLOADABLE_MEDIA_TYPES : CAPTURABLE_RASTER_MEDIA_TYPES;
+  return typeof mediaType === "string" && types.includes(mediaType);
+}

package/packages/public-runtime/src/page-csp.d.mts

@@ -0,0 +1,5 @@
+/** Types for the shared (S3 publish + Cloudflare serve) per-page CSP resolution. */
+export declare function pageCspFor(
+  manifest: { csp?: unknown; perRouteCsp?: Record<string, unknown> | null } | null | undefined,
+  relPath: string,
+): { headerName: string; value: string } | null;

package/packages/public-runtime/src/page-csp.mjs

@@ -0,0 +1,27 @@
+import { NATIVE_GA4_SANDBOX_ASSET_PATH } from "./integration/native-ga4-sandbox-asset.mjs";
+
+/** @param {unknown} value */
+function captureOrNull(value) {
+  const capture = /** @type {{headerName?: unknown, value?: unknown} | null | undefined} */ (value);
+  return capture && typeof capture.headerName === "string" && typeof capture.value === "string"
+    ? /** @type {{headerName: string, value: string}} */ (capture)
+    : null;
+}
+
+/**
+ * The tenant CSP one HTML document carries, shared by every plane that applies it: the S3 version
+ * upload stamps it as object metadata (`planVersionUpload`) and the Cloudflare static-bundle serve
+ * emits it as a response header (`serveStaticBundle`), so the two cannot answer differently.
+ *
+ * A page's own captured policy (`manifest.perRouteCsp[<bundlePath>]`) wins; the home-route
+ * `manifest.csp` is only the fallback for a document with no entry of its own. The platform-owned
+ * GA4 sandbox document enforces its own hash-pinned meta CSP and takes none.
+ * @param {{csp?: unknown, perRouteCsp?: Record<string, unknown> | null} | null | undefined} manifest
+ * @param {string} relPath the bundle-relative path of the document
+ * @returns {{headerName: string, value: string} | null}
+ */
+export function pageCspFor(manifest, relPath) {
+  if (relPath === NATIVE_GA4_SANDBOX_ASSET_PATH) return null;
+  const own = manifest?.perRouteCsp ? captureOrNull(manifest.perRouteCsp[relPath]) : null;
+  return own ?? captureOrNull(manifest?.csp);
+}

package/packages/public-runtime/src/pool-asset-headers.ts

@@ -0,0 +1,19 @@
+/**
+ * Response headers every content-addressed pool image (`/_a/<sha256><ext>`) is served with, on both
+ * serving paths (ADR 0038 §12): the Worker sets them on its R2 responses, and each S3 pool image
+ * carries the policy as stamped `content-security-policy` metadata that the CloudFront
+ * viewer-response function (`scripts/publish/cloudfront/csp-meta-emit.mjs`) emits as the header.
+ *
+ * A raster loaded by `<img>` ignores the policy. A document opened directly — an SVG navigated to —
+ * runs sandboxed: no script, no plugins, no network, an opaque origin. That holds even for bytes a
+ * sanitizer would have missed, which is why it is sent for every pool image, not only sanitized
+ * ones. Only images carry it: a script a page runs as a worker takes its policy from its own response.
+ * Import-free, so plain node reads it.
+ */
+export const POOL_ASSET_CONTENT_SECURITY_POLICY =
+  "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; sandbox";
+
+export const POOL_ASSET_SECURITY_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  "content-security-policy": POOL_ASSET_CONTENT_SECURITY_POLICY,
+  "x-content-type-options": "nosniff",
+});

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

@@ -275,6 +275,12 @@ export interface CatalogProduct {
   created_at: string; // ISO 8601
   updated_at: string; // ISO 8601
   migrated_at: string; // ISO 8601
+  /**
+   * When the product was created at its source system (ISO 8601). Written only by an importer
+   * that read the date from the source; an import time never goes here. It is the only date the
+   * "New" badge ages: absent or unreadable means no age-based "New".
+   */
+  source_created_at?: string;
   /** Content hash for incremental sync / change detection. */
   source_checksum: string;
   /**

package/packages/public-runtime/src/static-bundle.ts

@@ -42,9 +42,10 @@
  */
 import { assetContentType } from "./tenant-assets.js";
 import { formatHtmlCacheControl } from "./html-cache-policy.js";
-import { NATIVE_GA4_SANDBOX_ASSET_PATH } from "./integration/native-ga4-sandbox-asset.mjs";
 import { CONTENT_NAMED_ASSET_PREFIXES } from "./content-named-asset-prefixes.mjs";
 import { resolveRedirect } from "./publication-redirects.mjs";
+import { pageCspFor } from "./page-csp.mjs";
+import { POOL_ASSET_SECURITY_HEADERS } from "./pool-asset-headers.js";
 
 // ---------------------------------------------------------------------------
 // R2 seam — same structural subset tenant-assets.ts uses (no workers-types dep)
@@ -160,6 +161,8 @@ export interface StaticBundleManifest {
   treeDigest: string;
   pinnedNonce: string;
   csp: { headerName: string; value: string } | null;
+  /** Each HTML document's OWN captured CSP, keyed by bundle path; `csp` is the fallback (see `pageCspFor`). */
+  perRouteCsp?: Record<string, { headerName: string; value: string }>;
   /**
    * The route-document `Cache-Control` this bundle's tenant declared (ADR 0013
    * `serving.htmlCachePolicy`, formatted by `formatHtmlCacheControl` at materialize).
@@ -221,6 +224,16 @@ function parseManifest(raw: string): StaticBundleManifest | null {
       typeof (m.csp as { value?: unknown }).value === "string"
         ? (m.csp as { headerName: string; value: string })
         : null;
+    let perRouteCsp: StaticBundleManifest["perRouteCsp"];
+    if (m.perRouteCsp && typeof m.perRouteCsp === "object") {
+      perRouteCsp = {};
+      for (const [rel, value] of Object.entries(m.perRouteCsp as Record<string, unknown>)) {
+        const capture = value as { headerName?: unknown; value?: unknown } | null;
+        if (capture && typeof capture.headerName === "string" && typeof capture.value === "string") {
+          perRouteCsp[rel] = { headerName: capture.headerName, value: capture.value };
+        }
+      }
+    }
     let files: StaticBundleManifest["files"];
     if (m.files && typeof m.files === "object") {
       files = {};
@@ -252,7 +265,7 @@ function parseManifest(raw: string): StaticBundleManifest | null {
       }
     }
     const htmlCacheControl = typeof m.htmlCacheControl === "string" ? m.htmlCacheControl : undefined;
-    return { treeDigest: m.treeDigest, pinnedNonce: m.pinnedNonce, csp, htmlCacheControl, files, redirects };
+    return { treeDigest: m.treeDigest, pinnedNonce: m.pinnedNonce, csp, perRouteCsp, htmlCacheControl, files, redirects };
   } catch {
     return null;
   }
@@ -366,7 +379,9 @@ export function versionIndependentAssetKey(pathname: string): string | null {
  * Serve a version-independent asset straight from R2, or return null when `pathname` is not one
  * (or, for `/_astro/`, when the named store does not hold it — the Worker's own build also serves
  * that prefix, so a miss belongs to the caller). A missing `/_a/` object is a 404: the address is
- * exact, so there is nothing else it could mean.
+ * exact, so there is nothing else it could mean. A pool image is sent with the sandboxing pool
+ * headers (`pool-asset-headers.ts`): the pool is shared, so an SVG opened directly on any tenant's
+ * host runs with no script and no network.
  */
 export async function serveVersionIndependentAsset(
   bucket: StaticBundleR2BucketLike,
@@ -383,10 +398,12 @@ export async function serveVersionIndependentAsset(
       headers: { "cache-control": "no-store", "x-tot-static-bundle": "pinned-miss" },
     });
   }
+  const contentType = assetContentType(key);
   const headers: Record<string, string> = {
-    "content-type": assetContentType(key),
+    "content-type": contentType,
     "cache-control": IMMUTABLE_CACHE_CONTROL,
     "x-tot-static-bundle": "pinned",
+    ...(pathname.startsWith(PINNED_ASSET_URL_PREFIX) && contentType.startsWith("image/") ? POOL_ASSET_SECURITY_HEADERS : {}),
   };
   if (typeof object.size === "number") headers["content-length"] = String(object.size);
   const body: BodyInit | null = method.toUpperCase() === "HEAD"
@@ -499,9 +516,8 @@ export async function serveStaticBundle(
   // The reviewed GA4 transport frame is a platform-owned security boundary with
   // its own generated, hash-pinned meta CSP. Applying the tenant page CSP as a
   // second policy would intersect the two and block the reviewed gtag.js origin.
-  if (isHtml && rel !== NATIVE_GA4_SANDBOX_ASSET_PATH && manifest.csp) {
-    headers[manifest.csp.headerName] = manifest.csp.value;
-  }
+  const pageCsp = isHtml ? pageCspFor(manifest, rel) : null;
+  if (pageCsp) headers[pageCsp.headerName] = pageCsp.value;
 
   if (typeof object.size === "number") {
     headers["content-length"] = String(object.size);

package/packages/public-runtime/src/svg-sanitize.ts

@@ -0,0 +1,331 @@
+/**
+ * The pool's SVG sanitizer (ADR 0038 §12). An SVG is a document that can run script, so the pool
+ * accepts one only after this allowlist pass, and serves every pool object with the sandboxing
+ * policy in `pool-asset-headers.ts`, which contains whatever a sanitizer could miss.
+ *
+ * The pass is a strict XML reader, not an HTML parser: the browser reads `image/svg+xml` as XML, so
+ * the sanitizer reads it the same way and refuses anything it cannot read exactly (a custom entity,
+ * a DOCTYPE internal subset, a processing instruction, an unbalanced tag). What it reads, it keeps
+ * only when allowlisted:
+ *
+ * - elements: static SVG drawing, text, paint servers, clipping, masking and filters. Any other
+ *   element — `script`, `foreignObject`, animation (`set`/`animate*` can rewrite an `href`),
+ *   `iframe`, editor metadata, anything namespaced — is removed with its whole subtree;
+ * - attributes: event handlers (`on*`) and every namespaced attribute except `xlink:href`,
+ *   `xml:space` and `xml:lang` are removed;
+ * - references (`href`, `xlink:href`, every `url()`): only a same-document fragment (`#id`), a pool
+ *   object (`/_a/<sha256><ext>`) or an inline raster `data:` image. Any other reference is removed;
+ * - `<style>` text with an escape, `@import`, a non-pool `url()` or a script-capable construct
+ *   refuses the image rather than being half-cleaned.
+ *
+ * Output is the input with the removed spans cut out, byte for byte otherwise, so an already-clean
+ * SVG keeps its bytes and therefore its address. Import-free.
+ */
+
+export const SVG_SANITIZER_ID = "svg-allowlist-1";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const XLINK_NS = "http://www.w3.org/1999/xlink";
+
+const ALLOWED_ELEMENTS = new Set([
+  "svg", "g", "defs", "symbol", "use", "title", "desc", "switch", "a", "view",
+  "path", "rect", "circle", "ellipse", "line", "polyline", "polygon",
+  "text", "tspan", "textPath", "image", "style",
+  "linearGradient", "radialGradient", "stop", "pattern", "clipPath", "mask", "marker",
+  "filter", "feBlend", "feColorMatrix", "feComponentTransfer", "feComposite", "feConvolveMatrix",
+  "feDiffuseLighting", "feDisplacementMap", "feDistantLight", "feDropShadow", "feFlood", "feFuncA",
+  "feFuncB", "feFuncG", "feFuncR", "feGaussianBlur", "feImage", "feMerge", "feMergeNode",
+  "feMorphology", "feOffset", "fePointLight", "feSpecularLighting", "feSpotLight", "feTile",
+  "feTurbulence",
+]);
+const ALLOWED_PREFIXED_ATTRIBUTES = new Set(["xlink:href", "xml:space", "xml:lang"]);
+
+export type SvgRefusalReason = "too-large" | "not-utf8" | "not-svg" | "malformed" | "entity" | "unsafe-style" | "too-complex";
+
+export type SvgSanitizeResult =
+  | { ok: true; bytes: Uint8Array; changed: boolean; removedElements: number; removedAttributes: number }
+  | { ok: false; reason: SvgRefusalReason; message: string };
+
+export interface SvgSanitizeLimits { maxBytes: number; maxElements: number; maxDepth: number }
+const DEFAULT_LIMITS: SvgSanitizeLimits = { maxBytes: 8 * 1024 * 1024, maxElements: 100_000, maxDepth: 256 };
+
+class Refusal extends Error {
+  readonly reason: SvgRefusalReason;
+  readonly detail: string;
+  constructor(reason: SvgRefusalReason, detail: string) {
+    super(detail);
+    this.reason = reason;
+    this.detail = detail;
+  }
+}
+
+const NAME = /[A-Za-z_][A-Za-z0-9._:-]*/y;
+const SPACE = /[ \t\r\n]*/y;
+const ATTRIBUTE = /[ \t\r\n]+([A-Za-z_][A-Za-z0-9._:-]*)[ \t\r\n]*=[ \t\r\n]*("[^"]*"|'[^']*')/y;
+const TAG_END = /[ \t\r\n]*(\/?)>/y;
+const CLOSE_TAG = /<\/([A-Za-z_][A-Za-z0-9._:-]*)[ \t\r\n]*>/y;
+const XML_DECLARATION = /^<\?xml[ \t\r\n]+version[ \t\r\n]*=[ \t\r\n]*(["'])1\.[0-9]\1(?:[ \t\r\n]+encoding[ \t\r\n]*=[ \t\r\n]*(["'])([A-Za-z][A-Za-z0-9._-]*)\2)?(?:[ \t\r\n]+standalone[ \t\r\n]*=[ \t\r\n]*(["'])(?:yes|no)\4)?[ \t\r\n]*\?>/;
+
+const FRAGMENT = /^#[A-Za-z_][A-Za-z0-9._:-]*$/;
+const POOL_URL = /^\/_a\/[0-9a-f]{64}\.(?:png|jpg|gif|webp|avif|svg)$/;
+const RASTER_DATA = /^data:image\/(?:png|jpeg|gif|webp|avif);base64,[A-Za-z0-9+/]+={0,2}$/;
+
+/** Is `value` a reference the pool allows: a fragment, a pool object, or an inline raster? */
+export function isPoolSafeReference(value: string): boolean {
+  const trimmed = value.trim();
+  if (FRAGMENT.test(trimmed) || POOL_URL.test(trimmed)) return true;
+  return /^data:/i.test(trimmed) && RASTER_DATA.test(trimmed.replace(/[ \t\r\n]+/g, ""));
+}
+
+/** Decode XML's five predefined entities and character references; null on any other `&`. */
+function decodeEntities(text: string): string | null {
+  if (/&(?!(?:#x[0-9A-Fa-f]{1,6}|#[0-9]{1,7}|amp|lt|gt|quot|apos);)/.test(text)) return null;
+  let invalid = false;
+  const decoded = text.replace(/&(?:#x([0-9A-Fa-f]{1,6})|#([0-9]{1,7})|(amp|lt|gt|quot|apos));/g, (_all, hex, dec, named) => {
+    if (named) return ({ amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" } as Record<string, string>)[named]!;
+    const code = hex ? parseInt(hex, 16) : parseInt(dec, 10);
+    if (code === 0 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) { invalid = true; return ""; }
+    return String.fromCodePoint(code);
+  });
+  return invalid ? null : decoded;
+}
+
+/** Every `url(...)` target in `css`, or null when one cannot be read exactly. */
+function urlTargets(css: string): string[] | null {
+  const targets: string[] = [];
+  const lower = css.toLowerCase();
+  let from = 0;
+  for (;;) {
+    const at = lower.indexOf("url(", from);
+    if (at === -1) return targets;
+    let i = at + 4;
+    while (i < css.length && /[ \t\r\n\f]/.test(css[i]!)) i++;
+    let target: string;
+    const quote = css[i];
+    if (quote === '"' || quote === "'") {
+      const end = css.indexOf(quote, i + 1);
+      if (end === -1) return null;
+      target = css.slice(i + 1, end);
+      i = end + 1;
+    } else {
+      const end = css.indexOf(")", i);
+      if (end === -1) return null;
+      target = css.slice(i, end).replace(/[ \t\r\n\f]+$/, "");
+      if (/[\s"'(]/.test(target)) return null;
+      i = end;
+    }
+    while (i < css.length && /[ \t\r\n\f]/.test(css[i]!)) i++;
+    if (css[i] !== ")") return null;
+    targets.push(target);
+    from = i + 1;
+  }
+}
+
+const UNSAFE_CSS = ["@import", "@font-face", "@namespace", "expression(", "javascript:", "vbscript:", "-moz-binding",
+  "behavior", "image-set(", "cross-fade(", "element(", "src("];
+
+/** Why `css` is unsafe, or null when it is safe to keep. */
+function unsafeCss(css: string): string | null {
+  if (css.includes("\\")) return "it uses a CSS escape sequence";
+  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  if (stripped.includes("/*")) return "it has an unterminated CSS comment";
+  const lower = stripped.toLowerCase();
+  const construct = UNSAFE_CSS.find((item) => lower.includes(item));
+  if (construct) return `it uses \`${construct}\``;
+  const targets = urlTargets(stripped);
+  if (!targets) return "it has a url() that cannot be read exactly";
+  if (targets.some((target) => !isPoolSafeReference(target))) return "it references a url() outside this image or the pool";
+  return null;
+}
+
+interface Open { name: string; dropped: boolean; style: { css: string } | null }
+
+/**
+ * Sanitize one SVG. Refuses (never rasterizes, never guesses) when the document cannot be read
+ * exactly; otherwise returns the allowlisted document and how much was removed.
+ */
+export function sanitizeSvg(bytes: Uint8Array, limits: Partial<SvgSanitizeLimits> = {}): SvgSanitizeResult {
+  const bound = { ...DEFAULT_LIMITS, ...limits };
+  const refuse = (reason: SvgRefusalReason, detail: string): SvgSanitizeResult => ({
+    ok: false, reason,
+    message: `The SVG was refused: ${detail}. Export it again as plain SVG (no scripts, entities or external references), or as PNG or WebP.`,
+  });
+  if (bytes.byteLength > bound.maxBytes) return refuse("too-large", `it is larger than ${bound.maxBytes} bytes`);
+  let source: string;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(bytes);
+  } catch {
+    return refuse("not-utf8", "it is not UTF-8 text");
+  }
+  try {
+    return sanitizeText(source, bound);
+  } catch (error) {
+    if (error instanceof Refusal) return refuse(error.reason, error.detail);
+    throw error;
+  }
+}
+
+function sanitizeText(source: string, limits: SvgSanitizeLimits): SvgSanitizeResult {
+  const out: string[] = [];
+  const stack: Open[] = [];
+  let i = 0;
+  let rootSeen = false;
+  let rootClosed = false;
+  let elements = 0;
+  let removedElements = 0;
+  let removedAttributes = 0;
+  const malformed = (detail: string) => new Refusal("malformed", detail);
+
+  const declaration = XML_DECLARATION.exec(source);
+  if (declaration) {
+    const encoding = declaration[3];
+    if (encoding && !/^utf-?8$/i.test(encoding)) throw new Refusal("not-utf8", `it declares the ${encoding} encoding`);
+    out.push(declaration[0]);
+    i = declaration[0].length;
+  }
+
+  while (i < source.length) {
+    const open = stack[stack.length - 1];
+    const dropped = open?.dropped ?? false;
+    if (source.startsWith("<!--", i)) {
+      const end = source.indexOf("-->", i + 4);
+      if (end === -1) throw malformed("a comment is not closed");
+      const body = source.slice(i + 4, end);
+      if (body.includes("--") || body.endsWith("-")) throw malformed("a comment contains `--`");
+      i = end + 3;
+      continue;
+    }
+    if (source.startsWith("<![CDATA[", i)) {
+      const end = source.indexOf("]]>", i + 9);
+      if (end === -1) throw malformed("a CDATA section is not closed");
+      if (!dropped) {
+        if (!open?.style) throw malformed("a CDATA section appears outside <style>");
+        open.style.css += source.slice(i + 9, end);
+        out.push(source.slice(i, end + 3));
+      }
+      i = end + 3;
+      continue;
+    }
+    if (source.startsWith("<!DOCTYPE", i)) {
+      if (rootSeen) throw malformed("a DOCTYPE appears inside the document");
+      const end = source.indexOf(">", i);
+      if (end === -1) throw malformed("the DOCTYPE is not closed");
+      if (source.slice(i, end).includes("[")) throw new Refusal("entity", "it declares entities in a DOCTYPE internal subset");
+      i = end + 1;
+      continue;
+    }
+    if (source.startsWith("<!", i)) throw malformed("it contains a markup declaration");
+    if (source.startsWith("<?", i)) throw malformed("it contains a processing instruction");
+    if (source.startsWith("</", i)) {
+      CLOSE_TAG.lastIndex = i;
+      const match = CLOSE_TAG.exec(source);
+      if (!match) throw malformed("a closing tag cannot be read");
+      const top = stack.pop();
+      if (!top || top.name !== match[1]) throw malformed(`</${match[1]}> does not close the open element`);
+      if (top.style) {
+        const decoded = decodeEntities(top.style.css);
+        if (decoded === null) throw new Refusal("entity", "a <style> uses an undefined entity");
+        const unsafe = unsafeCss(decoded);
+        if (unsafe) throw new Refusal("unsafe-style", `a <style> element is unsafe: ${unsafe}`);
+      }
+      if (!top.dropped) out.push(match[0]);
+      if (stack.length === 0) rootClosed = true;
+      i = CLOSE_TAG.lastIndex;
+      continue;
+    }
+    if (source[i] === "<") {
+      NAME.lastIndex = i + 1;
+      const nameMatch = NAME.exec(source);
+      if (!nameMatch) throw malformed("a tag cannot be read");
+      const name = nameMatch[0];
+      let cursor = NAME.lastIndex;
+      const attributes: { name: string; raw: string; value: string }[] = [];
+      const seen = new Set<string>();
+      for (;;) {
+        ATTRIBUTE.lastIndex = cursor;
+        const attribute = ATTRIBUTE.exec(source);
+        if (!attribute) break;
+        const quoted = attribute[2]!;
+        const value = quoted.slice(1, -1);
+        if (value.includes("<")) throw malformed(`attribute ${attribute[1]} contains \`<\``);
+        if (seen.has(attribute[1]!)) throw malformed(`attribute ${attribute[1]} appears twice`);
+        seen.add(attribute[1]!);
+        attributes.push({ name: attribute[1]!, raw: attribute[0], value });
+        cursor = ATTRIBUTE.lastIndex;
+      }
+      TAG_END.lastIndex = cursor;
+      const end = TAG_END.exec(source);
+      if (!end) throw malformed(`<${name}> cannot be read`);
+      const selfClosing = end[1] === "/";
+      i = TAG_END.lastIndex;
+
+      if (++elements > limits.maxElements) throw new Refusal("too-complex", `it has more than ${limits.maxElements} elements`);
+      if (stack.length >= limits.maxDepth) throw new Refusal("too-complex", `it nests deeper than ${limits.maxDepth} elements`);
+      const isRoot = stack.length === 0;
+      if (isRoot) {
+        if (rootClosed) throw malformed("it has more than one root element");
+        rootSeen = true;
+        const xmlns = attributes.find((attribute) => attribute.name === "xmlns");
+        if (name !== "svg" || !xmlns || decodeEntities(xmlns.value) !== SVG_NS) {
+          throw new Refusal("not-svg", "its root element is not an <svg> in the SVG namespace");
+        }
+      }
+      // Every attribute value must read exactly, kept element or not.
+      const decoded = attributes.map((attribute) => {
+        const value = decodeEntities(attribute.value);
+        if (value === null) throw new Refusal("entity", `attribute ${attribute.name} uses an undefined entity`);
+        return value;
+      });
+      const keep = !dropped && ALLOWED_ELEMENTS.has(name);
+      if (!dropped && !keep) removedElements++;
+      if (keep) {
+        let tag = `<${name}`;
+        attributes.forEach((attribute, index) => {
+          if (keepAttribute(attribute.name, decoded[index]!, isRoot)) tag += attribute.raw;
+          else removedAttributes++;
+        });
+        out.push(tag + end[0]);
+      }
+      if (!selfClosing) stack.push({ name, dropped: !keep, style: keep && name === "style" ? { css: "" } : null });
+      else if (isRoot) rootClosed = true;
+      continue;
+    }
+    const next = source.indexOf("<", i);
+    const text = source.slice(i, next === -1 ? source.length : next);
+    if (stack.length === 0) {
+      if (text.trim() !== "") throw malformed("it has text outside the root element");
+      out.push(text);
+    } else {
+      if (text.includes("]]>")) throw malformed("text contains `]]>`");
+      if (decodeEntities(text) === null) throw new Refusal("entity", "its text uses an undefined entity");
+      if (!dropped) {
+        if (open?.style) open.style.css += text;
+        out.push(text);
+      }
+    }
+    i = next === -1 ? source.length : next;
+  }
+  if (!rootSeen) throw new Refusal("not-svg", "it has no root element");
+  if (stack.length > 0) throw malformed(`<${stack[stack.length - 1]!.name}> is not closed`);
+  const output = out.join("");
+  return {
+    ok: true, bytes: new TextEncoder().encode(output), changed: output !== source,
+    removedElements, removedAttributes,
+  };
+}
+
+/** Whether a kept element keeps this attribute (its decoded value). */
+function keepAttribute(name: string, value: string, isRoot: boolean): boolean {
+  if (/^on/i.test(name)) return false;
+  if (name === "xmlns") return isRoot || value === SVG_NS;
+  if (name.startsWith("xmlns:")) return name === "xmlns:xlink" && value === XLINK_NS;
+  if (name.includes(":") && !ALLOWED_PREFIXED_ATTRIBUTES.has(name)) return false;
+  if (name === "href" || name === "xlink:href") return isPoolSafeReference(value);
+  if (/javascript:|vbscript:/i.test(value.replace(/[\s\u0000-\u001f]+/g, ""))) return false;
+  if (name === "style") return unsafeCss(value) === null;
+  if (/url[ \t\r\n\f]*\(/i.test(value)) {
+    const targets = urlTargets(value);
+    return !!targets && targets.every(isPoolSafeReference) && !/url[ \t\r\n\f]+\(/i.test(value);
+  }
+  return true;
+}