@tokenoftrust/storefront-runner 4.12.2 → 4.13.0

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

@@ -2,9 +2,16 @@
  * Worker-safe serve of revision-bound captured originals.
  *
  * Does not import Node capture — R2 + Web Crypto only. Bytes are served only
- * when the sealed revision manifest names the address.
+ * when the sealed revision manifest names the address, within the tenant's image tier
+ * (`imageTier`, resolved by the caller from the server-side tenant record).
+ *
+ * Where the runtime has `crypto.DigestStream` (workerd), the R2 body is streamed to the client
+ * through a verifier that counts and hashes it and holds back the last chunk until both match, so a
+ * wrong or truncated object never reaches a client complete. Elsewhere the object is read whole,
+ * bounded by the manifest's byte length, and verified before the first byte.
  */
 import { sha256Hex } from "@tot/public-runtime";
+import { imageLimitsFor, type ImageTier } from "@tot/public-runtime/image-limits";
 import {
   PINNED_ASSET_EXTENSION_BY_MEDIA_TYPE, PINNED_ASSET_MEDIA_TYPE_BY_EXTENSION, sealedMediaTypeAllowed,
 } from "@tot/public-runtime/hosted-image-media-types";
@@ -58,7 +65,9 @@ async function readManifestEntries(
   bucket: CapturedOriginalBucket,
   tenantId: string,
   revisionId: string,
+  imageTier: ImageTier | undefined,
 ): Promise<ManifestEntry[] | null> {
+  const maxEntryBytes = imageLimitsFor(imageTier).maxEncodedBytes;
   if (!isSafeTenantId(tenantId) || !isSafeRevisionId(revisionId)) return null;
   const object = await bucket.get(originalImageManifestObjectKey(tenantId, revisionId));
   if (!object || typeof object !== "object") return null;
@@ -79,7 +88,7 @@ async function readManifestEntries(
       if (!raw || typeof raw !== "object") return null;
       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 ||
+      if (!Number.isSafeInteger(entry.byteLength) || entry.byteLength! < 1 || entry.byteLength! > maxEntryBytes ||
           !sealedMediaTypeAllowed(entry.provenance?.kind, entry.mediaType)) return null;
       entries.push({
         address: entry.address,
@@ -101,6 +110,8 @@ export async function readDurableCapturedEntry(input: {
   tenantId: string;
   provider: string | null | undefined;
   address: string;
+  /** The tenant's image tier from its server-resolved record (`resolveImageTier`); absent is standard. */
+  imageTier?: ImageTier;
 }): Promise<ManifestEntry | null> {
   if (!isSafeTenantId(input.tenantId) || !ADDRESS_RE.test(input.address)) return null;
   const required = durableRequiredStores(input.provider);
@@ -111,7 +122,7 @@ export async function readDurableCapturedEntry(input: {
     if (typeof designation.entry !== "string" || !designation.entry.startsWith(`${input.address}.`) ||
         !Array.isArray(designation.verifiedStores) || !required.every((store) => designation.verifiedStores.includes(store)) ||
         typeof designation.designatedRevision !== "string" || !isSafeRevisionId(designation.designatedRevision)) continue;
-    const entries = await readManifestEntries(input.bucket, input.tenantId, durableCaptureRevisionId(designation.designatedRevision));
+    const entries = await readManifestEntries(input.bucket, input.tenantId, durableCaptureRevisionId(designation.designatedRevision), input.imageTier);
     const entry = entries?.find((entry) => entry.address === input.address &&
       designation.entry === `${entry.address}${PINNED_ASSET_EXTENSION_BY_MEDIA_TYPE[entry.mediaType]}`);
     if (entry) return entry;
@@ -130,6 +141,8 @@ export async function tryServeCapturedOriginal(input: {
   durable?: { kv: { get(key: string): Promise<string | null> }; provider: string | null | undefined };
   pathname: string;
   method?: string;
+  /** The tenant's image tier from its server-resolved record (`resolveImageTier`); absent is standard. */
+  imageTier?: ImageTier;
 }): Promise<Response | null> {
   const parsed = parsePinnedImagePath(input.pathname);
   if (!parsed) return null;
@@ -137,18 +150,21 @@ export async function tryServeCapturedOriginal(input: {
     return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
   }
 
-  const entries = input.revisionId ? await readManifestEntries(input.bucket, input.tenantId, input.revisionId).catch(() => null) : null;
+  const entries = input.revisionId
+    ? await readManifestEntries(input.bucket, input.tenantId, input.revisionId, input.imageTier).catch(() => null)
+    : null;
   let entry = entries?.find((item) => item.address === parsed.address);
   let durable = false;
   if (!entry && input.revisionId) {
-    const declared = await readManifestEntries(input.bucket, input.tenantId, durableCaptureRevisionId(input.revisionId)).catch(() => null);
+    const declared = await readManifestEntries(input.bucket, input.tenantId, durableCaptureRevisionId(input.revisionId), input.imageTier)
+      .catch(() => null);
     entry = declared?.find((item) => item.address === parsed.address);
     durable = !!entry;
   }
   if (!entry && input.durable) {
     try {
       entry = await readDurableCapturedEntry({ bucket: input.bucket, tenantId: input.tenantId,
-        address: parsed.address, ...input.durable }) ?? undefined;
+        address: parsed.address, ...input.durable, ...(input.imageTier ? { imageTier: input.imageTier } : {}) }) ?? undefined;
       durable = !!entry;
     } catch { /* Unreadable durable authority fails closed. */ }
   }
@@ -162,29 +178,80 @@ export async function tryServeCapturedOriginal(input: {
     if (!object || typeof object !== "object") {
       return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
     }
-    const body = object as { arrayBuffer?: () => Promise<ArrayBuffer> };
-    if (typeof body.arrayBuffer !== "function") {
-      return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
-    }
-    const bytes = new Uint8Array(await body.arrayBuffer());
-    if (bytes.byteLength !== entry.byteLength) {
+    const stored = object as StoredObject;
+    const notFound = async () => {
+      await stored.body?.cancel?.().catch(() => {});
       return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
-    }
-    const digest = await sha256Hex(bytes);
-    if (digest !== parsed.address) {
-      return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
-    }
-    const contentType = EXT_TYPE[parsed.ext.toLowerCase()] ?? entry.mediaType;
+    };
+    if (typeof stored.size === "number" && stored.size !== entry.byteLength) return notFound();
+    const checksum = stored.checksums?.sha256;
+    if (checksum && hex(checksum) !== parsed.address) return notFound();
+    const method = (input.method ?? "GET").toUpperCase();
     const headers: Record<string, string> = {
-      "content-type": contentType,
+      "content-type": EXT_TYPE[parsed.ext.toLowerCase()] ?? entry.mediaType,
       "cache-control": durable ? "no-store" : "public, max-age=31536000, immutable",
       "x-tot-original-image": durable ? "durable" : "revision-bound",
-      "content-length": String(bytes.byteLength),
+      "content-length": String(entry.byteLength),
       ...POOL_ASSET_SECURITY_HEADERS,
     };
-    const method = (input.method ?? "GET").toUpperCase();
+    const Digest = digestStreamClass();
+    if (Digest && stored.body && typeof stored.size === "number") {
+      if (method === "HEAD") {
+        await stored.body.cancel?.().catch(() => {});
+        return new Response(null, { status: 200, headers });
+      }
+      return new Response(verifiedBody(stored.body, entry.byteLength, parsed.address, Digest), { status: 200, headers });
+    }
+    if (typeof stored.arrayBuffer !== "function") return notFound();
+    const bytes = new Uint8Array(await stored.arrayBuffer());
+    if (bytes.byteLength !== entry.byteLength || await sha256Hex(bytes) !== parsed.address) return notFound();
     return new Response(method === "HEAD" ? null : bytes, { status: 200, headers });
   } catch {
     return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
   }
 }
+
+type StoredObject = {
+  body?: (ReadableStream<Uint8Array> & { cancel?: () => Promise<void> }) | null;
+  size?: number;
+  arrayBuffer?: () => Promise<ArrayBuffer>;
+  /** R2 keeps the sha256 an upload declared; capture declares it when it streams an original in. */
+  checksums?: { sha256?: ArrayBuffer };
+};
+
+type DigestStreamClass = new (algorithm: string) => WritableStream<Uint8Array> & { digest: Promise<ArrayBuffer> };
+
+function digestStreamClass(): DigestStreamClass | null {
+  const found = (globalThis.crypto as unknown as { DigestStream?: DigestStreamClass } | undefined)?.DigestStream;
+  return typeof found === "function" ? found : null;
+}
+
+function hex(buffer: ArrayBuffer): string {
+  return [...new Uint8Array(buffer)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * The R2 body, passed through as it is read: counted and hashed on the way, with the last chunk held
+ * back until the whole body has matched its length and address. An overrun, a short body or a
+ * wrong hash errors the stream instead, so a client never receives a complete wrong object.
+ */
+function verifiedBody(body: ReadableStream<Uint8Array>, length: number, address: string, Digest: DigestStreamClass): ReadableStream<Uint8Array> {
+  const digest = new Digest("SHA-256");
+  const writer = digest.getWriter();
+  let seen = 0;
+  let held: Uint8Array | null = null;
+  return body.pipeThrough(new TransformStream<Uint8Array, Uint8Array>({
+    async transform(chunk, controller) {
+      seen += chunk.byteLength;
+      if (seen > length) throw new Error("captured original is longer than its manifest entry");
+      await writer.write(chunk);
+      if (held) controller.enqueue(held);
+      held = chunk;
+    },
+    async flush(controller) {
+      await writer.close();
+      if (seen !== length || hex(await digest.digest) !== address) throw new Error("captured original does not match its address");
+      if (held) controller.enqueue(held);
+    },
+  }));
+}

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

@@ -20,8 +20,8 @@ import {
 } 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";
+import { imageLimitsFor, type ImageTier } from "@tot/public-runtime/image-limits";
 
-const MAX_IMAGE = 8 * 1024 * 1024;
 const MAX_MANIFEST = 1024 * 1024;
 const POOL_ENTRY_RE = /^([0-9a-f]{64})(\.[A-Za-z0-9]+)$/;
 const IMMUTABLE = "public, max-age=31536000, immutable";
@@ -99,7 +99,8 @@ export function awaitR2Quiescence(bucket: R2BucketLike, waiter: QuiescenceWaiter
 export async function ensurePoolObject(bucket: R2BucketLike, key: string, bytes: Uint8Array, mediaType: string): Promise<void> {
   const address = POOL_ENTRY_RE.exec(key.replace(/^assets\//, ""))?.[1];
   if (!address) throw new R2StagingError("pool-key");
-  const existing = await readBounded(bucket, key, MAX_IMAGE);
+  // Bounded by the bytes being staged: an object of any other size cannot hold this address.
+  const existing = await readBounded(bucket, key, bytes.byteLength);
   if (existing && await sha256Hex(existing) !== address) throw new R2StagingError("store-mismatch");
   if (!existing) {
     if (!bucket.put) throw new R2StagingError("store-unwritable");
@@ -108,7 +109,7 @@ export async function ensurePoolObject(bucket: R2BucketLike, key: string, bytes:
       onlyIf: new Headers({ "If-None-Match": "*" }),
     });
   }
-  const readback = await readBounded(bucket, key, MAX_IMAGE);
+  const readback = await readBounded(bucket, key, bytes.byteLength);
   if (!readback || readback.byteLength !== bytes.byteLength || await sha256Hex(readback) !== address) {
     throw new R2StagingError("store-mismatch");
   }
@@ -131,11 +132,11 @@ function mediaTypeOf(entry: string): string {
   return mediaType;
 }
 
-/** The exact captured bytes for `<sha256><ext>` from the tenant's capture store. */
-async function capturedBytes(captureBucket: R2BucketLike, tenant: string, entry: string): Promise<Uint8Array> {
+/** The exact captured bytes for `<sha256><ext>` from the tenant's capture store, within its tier. */
+async function capturedBytes(captureBucket: R2BucketLike, tenant: string, entry: string, imageTier: ImageTier | undefined): Promise<Uint8Array> {
   const address = POOL_ENTRY_RE.exec(entry)?.[1];
   if (!address) throw new R2StagingError("pool-key");
-  const bytes = await readBounded(captureBucket, `original-images/${tenant}/objects/${address}`, MAX_IMAGE);
+  const bytes = await readBounded(captureBucket, `original-images/${tenant}/objects/${address}`, imageLimitsFor(imageTier).maxEncodedBytes);
   if (!bytes || bytes.byteLength < 1 || await sha256Hex(bytes) !== address) throw new R2StagingError("original-missing");
   return bytes;
 }
@@ -149,6 +150,8 @@ async function capturedBytes(captureBucket: R2BucketLike, tenant: string, entry:
  * 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`.
+ *
+ * Originals are read one at a time, within the tenant's image tier, and never held across entries.
  */
 export async function stageCapturedOriginalsR2(input: {
   tenant: string;
@@ -156,22 +159,24 @@ export async function stageCapturedOriginalsR2(input: {
   captureBucket: R2BucketLike;
   publicBucket: R2BucketLike;
   registry?: AssetRegistryStore;
+  /** The tenant's image tier from its server-resolved record (`resolveImageTier`); absent is standard. */
+  imageTier?: ImageTier;
 }): Promise<number> {
   const registry = input.registry ? await input.registry.read().catch(() => null) : null;
-  const owned = new Map<string, Uint8Array>();
+  const owned = new Map<string, number>();
   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) => {
+    const own = await capturedBytes(input.captureBucket, input.tenant, entry, input.imageTier).catch((error: unknown) => {
       if (error instanceof R2StagingError) return null;
       throw error;
     });
-    if (own) owned.set(entry, own);
+    if (own) owned.set(entry, own.byteLength);
     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,
+    const writes: AssetWrite[] = [...owned].map(([entry, size]) => ({
+      entry, tenant: input.tenant, mediaType: mediaTypeOf(entry), size,
     }));
     await input.registry.upsert(writes).catch(() => "lost");
   }
@@ -179,10 +184,10 @@ export async function stageCapturedOriginalsR2(input: {
   let staged = 0;
   for (const entry of input.entries) {
     const key = `assets/${entry}`;
-    const present = await readBounded(input.publicBucket, key, MAX_IMAGE);
+    const present = await readBounded(input.publicBucket, key, imageLimitsFor(input.imageTier).maxEncodedBytes);
     const address = POOL_ENTRY_RE.exec(entry)?.[1];
     if (present && address && await sha256Hex(present) === address) continue;
-    await ensurePoolObject(input.publicBucket, key, owned.get(entry) ?? await capturedBytes(input.captureBucket, input.tenant, entry), mediaTypeOf(entry));
+    await ensurePoolObject(input.publicBucket, key, await capturedBytes(input.captureBucket, input.tenant, entry, input.imageTier), mediaTypeOf(entry));
     staged++;
   }
   return staged;
@@ -231,6 +236,8 @@ export async function designateDurableR2(input: {
   awaitQuiescence?: QuiescenceWaiter;
   /** The pool's asset registry: each verified designation is recorded as a transition to `durable`. */
   registry?: AssetRegistryStore;
+  /** The tenant's image tier from its server-resolved record (`resolveImageTier`); absent is standard. */
+  imageTier?: ImageTier;
 }): Promise<DurableDesignationResult> {
   if (input.images.length === 0) return { ok: true, designated: [] };
   const revision = durableCaptureRevisionId(input.revision);
@@ -274,7 +281,7 @@ export async function designateDurableR2(input: {
   for (const item of prepared) {
     await createHold(input.publicBucket, item.holdKey, item.holdBody);
     await ensurePoolObject(input.publicBucket, `assets/${item.entry}`,
-      await capturedBytes(input.captureBucket, input.tenant, item.entry), item.mediaType);
+      await capturedBytes(input.captureBucket, input.tenant, item.entry, input.imageTier), item.mediaType);
   }
   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"] })) });
@@ -299,6 +306,8 @@ export function makeWorkerR2PinnedOriginalStager(deps: {
   kv: StatusKvLike;
   /** The pool's asset registry (`STATIC_BUNDLES` `registry/assets.json`). */
   registry?: AssetRegistryStore;
+  /** The tier of the tenant this Worker resolves for `tenantId`, from its server-side record. */
+  imageTier?: (tenantId: string) => Promise<ImageTier>;
   now?: () => Date;
   awaitQuiescence?: QuiescenceWaiter;
 }) {
@@ -315,15 +324,17 @@ export function makeWorkerR2PinnedOriginalStager(deps: {
     if (!Array.isArray(entries) || entries.some((entry) => typeof entry !== "string" || !POOL_ENTRY_RE.test(entry))) {
       throw new R2StagingError("manifest-invalid");
     }
+    const imageTier = deps.imageTier ? await deps.imageTier(tenantId) : undefined;
     await awaitR2Quiescence(deps.publicBucket, deps.awaitQuiescence);
     await stageCapturedOriginalsR2({ tenant: tenantId, entries: entries as string[],
-      captureBucket: deps.captureBucket, publicBucket: deps.publicBucket, ...(deps.registry ? { registry: deps.registry } : {}) });
+      captureBucket: deps.captureBucket, publicBucket: deps.publicBucket, ...(deps.registry ? { registry: deps.registry } : {}),
+      ...(imageTier ? { imageTier } : {}) });
     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.registry ? { registry: deps.registry } : {}), ...(imageTier ? { imageTier } : {}),
         ...(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

@@ -7,8 +7,10 @@
 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";
+import type { ImageTier } from "@tot/public-runtime/image-limits";
 
-export async function workerR2PinnedOriginalStagerFromEnv(): Promise<
+/** `imageTier` resolves a tenant's tier from its server-side record; the caller owns that lookup. */
+export async function workerR2PinnedOriginalStagerFromEnv(imageTier: (tenantId: string) => Promise<ImageTier>): Promise<
   (args: { tenantId: string; versionId: string; treeDigest?: string | null }) => Promise<void>
 > {
   const [publicBucket, productImages, tenantAssets, kv] = await Promise.all([
@@ -29,5 +31,6 @@ export async function workerR2PinnedOriginalStagerFromEnv(): Promise<
     captureBucket: captureBucket as unknown as R2BucketLike,
     kv: kv as unknown as StatusKvLike,
     registry: createR2AssetRegistry(publicBucket as unknown as AssetRegistryBucket),
+    imageTier,
   });
 }

package/apps/storefront/src/middleware/staticBundle.ts

@@ -16,6 +16,7 @@ import {
   versionIndependentAssetKey,
 } from "@tot/public-runtime";
 import type { StaticBundleR2BucketLike, TenantConfig } from "@tot/public-runtime";
+import { resolveImageTier } from "@tot/public-runtime/image-limits";
 
 export interface StaticBundleAttemptInput {
   request: Request;
@@ -94,6 +95,7 @@ export async function tryServeStaticBundle(
           revisionId: input.capturedOriginal.revisionId,
           pathname: assetPath,
           method,
+          imageTier: resolveImageTier(tenant),
           ...(kv ? { durable: { kv, provider: tenant.serving?.provider } } : {}),
         });
         if (captured) return captured;
@@ -107,6 +109,7 @@ export async function tryServeStaticBundle(
         revisionId: input.capturedOriginal.revisionId,
         pathname: assetPath,
         method,
+        imageTier: resolveImageTier(tenant),
         ...(kv ? { durable: { kv, provider: tenant.serving?.provider } } : {}),
       });
       if (captured) return captured;

package/package.json

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

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

package/packages/public-runtime/src/image-limits.d.mts

@@ -0,0 +1,18 @@
+export type ImageTier = "standard" | "large";
+
+export interface ImageLimits {
+  readonly maxEncodedBytes: number;
+  readonly maxPixels: number;
+  readonly maxDimension: number;
+}
+
+export declare const IMAGE_TIERS: Readonly<Record<ImageTier, ImageLimits>>;
+export declare const IMAGE_LIMITS_CEILING: ImageLimits;
+export declare const LARGE_IMAGES_ADDON_NAME: string;
+export declare function imageLimitsFor(tier: unknown): ImageLimits;
+export declare function resolveImageTier(tenant: unknown): ImageTier;
+export declare function imageLimitsForTenant(tenant: unknown): ImageLimits;
+export declare function imageLimitSummary(tier: ImageTier): string;
+export declare function withinImagePixels(
+  width: number, height: number, frames: number, limits: Pick<ImageLimits, "maxPixels" | "maxDimension">,
+): boolean;

package/packages/public-runtime/src/image-limits.mjs

@@ -0,0 +1,88 @@
+/**
+ * The one source of storefront image size limits. Every capture, upload, publication and serving
+ * path takes its byte, pixel and dimension caps from `imageLimitsFor(resolveImageTier(tenant))`;
+ * no path restates a literal (`image-limits-contract.test.mjs` scans the tree for one).
+ *
+ * Tiers are per tenant. `large` is the High Fidelity / Large Images add-on, read only from the
+ * server-resolved tenant record (`addOns.largeImages.mode === "enabled"`); every other value,
+ * including absent or malformed, is `standard` (fail closed, the same contract as
+ * `storefront.mode`).
+ *
+ * Pixels are counted as width x height x frames. No path decodes pixels inside the Worker:
+ * dimensions are read from a bounded header prefix, and display sizes are produced by the CDN.
+ *
+ * Resize paths and their input limits (measured 2026-11-03 against the tree and official docs):
+ *
+ * | path                                              | used by                                 | max input bytes | max pixels | max side  |
+ * | ------------------------------------------------- | --------------------------------------- | --------------- | ---------- | --------- |
+ * | R2 original + cdn-cgi image transform (cf.image)  | Cloudflare-served display sizes         | 100 MB          | 100 MP     | 12,000 px |
+ * | node-side sharp renditions (responsive-images.mjs)| CloudFront/S3 publication renditions    | none (stream)   | 268 MP (limitInputPixels default) | none |
+ * | Cloudflare Images stored / Images binding .input()| NOT USED (no binding or upload in tree) | 10 MB / 20 MB   | 100 MP     | 12,000 px |
+ * | Worker isolate                                    | capture and serve (streamed, no decode) | 128 MB memory   | n/a        | n/a       |
+ *
+ * Animated inputs over 50 MP pass through cf.image untransformed; the large tier's 25 MP total
+ * frame-area cap keeps every accepted image below that. If a consumer ever moves to Cloudflare
+ * Images storage or the Images binding, cap `large` at that path's byte limit.
+ */
+
+const MiB = 1024 * 1024;
+
+/** @type {Readonly<Record<"standard" | "large", Readonly<{ maxEncodedBytes: number, maxPixels: number, maxDimension: number }>>>} */
+export const IMAGE_TIERS = Object.freeze({
+  standard: Object.freeze({ maxEncodedBytes: 8 * MiB, maxPixels: 2 ** 23, maxDimension: 8192 }),
+  large: Object.freeze({ maxEncodedBytes: 30 * MiB, maxPixels: 25_000_000, maxDimension: 8192 }),
+});
+
+/** The highest limit any tenant can have: for clients that cannot know the tenant's tier. */
+export const IMAGE_LIMITS_CEILING = IMAGE_TIERS.large;
+
+export const LARGE_IMAGES_ADDON_NAME = "High Fidelity / Large Images";
+
+/** @param {unknown} tier */
+export function imageLimitsFor(tier) {
+  return tier === "large" ? IMAGE_TIERS.large : IMAGE_TIERS.standard;
+}
+
+/** @param {unknown} tenant */
+export function resolveImageTier(tenant) {
+  if (!tenant || typeof tenant !== "object") return "standard";
+  const addOns = /** @type {Record<string, unknown>} */ (tenant).addOns;
+  if (!addOns || typeof addOns !== "object") return "standard";
+  const largeImages = /** @type {Record<string, unknown>} */ (addOns).largeImages;
+  if (!largeImages || typeof largeImages !== "object") return "standard";
+  return /** @type {Record<string, unknown>} */ (largeImages).mode === "enabled" ? "large" : "standard";
+}
+
+/** @param {unknown} tenant */
+export function imageLimitsForTenant(tenant) {
+  return imageLimitsFor(resolveImageTier(tenant));
+}
+
+const mb = (bytes) => `${Math.round((bytes / MiB) * 10) / 10} MB`;
+const mp = (pixels) => `${Math.round((pixels / 1_000_000) * 10) / 10} MP`;
+
+/**
+ * The tier-aware refusal sentence for an image over its tenant's limit.
+ * @param {"standard" | "large"} tier
+ */
+export function imageLimitSummary(tier) {
+  const limits = imageLimitsFor(tier);
+  const base = `${mb(limits.maxEncodedBytes)}, ${mp(limits.maxPixels)} or ${limits.maxDimension}px on a side`;
+  if (tier === "large") return `This store's ${LARGE_IMAGES_ADDON_NAME} limit is ${base}.`;
+  const large = IMAGE_TIERS.large;
+  return `This store's image limit is ${base}; the ${LARGE_IMAGES_ADDON_NAME} add-on raises it to `
+    + `${mb(large.maxEncodedBytes)} and ${mp(large.maxPixels)}.`;
+}
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {number} frames
+ * @param {{ maxPixels: number, maxDimension: number }} limits
+ */
+export function withinImagePixels(width, height, frames, limits) {
+  if (![width, height, frames].every((n) => Number.isSafeInteger(n) && n > 0)) return false;
+  if (width > limits.maxDimension || height > limits.maxDimension) return false;
+  const pixels = width * height * frames;
+  return Number.isSafeInteger(pixels) && pixels <= limits.maxPixels;
+}

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

@@ -739,6 +739,15 @@ export interface TenantConfig {
      */
     mode?: StorefrontMode;
   };
+  /**
+   * Per-store add-ons. `largeImages` is the High Fidelity / Large Images add-on: `mode ===
+   * "enabled"` raises the store's image limits to the large tier (`image-limits.mjs`
+   * `resolveImageTier`); any other value, or absent, is the standard tier. `updatedBy` is an
+   * opaque actor id, never an email or other personal detail.
+   */
+  addOns?: {
+    largeImages?: { mode: "enabled" | "disabled"; updatedAt?: string; updatedBy?: string };
+  };
   /**
    * Internal test/e2e tenant — never a real client. A tenant carrying this
    * marker (or an `.e2e.test` appDomain) is excluded from real/prospect-facing