@tokenoftrust/storefront-runner 3.0.0 → 3.1.0

package/agency-kit/tools/lib/public-binaries.mjs

@@ -5,10 +5,13 @@
  * catalog images, and the source store is never shut down before that check passes. This decides,
  * from a listing of the store's `public/` tree, whether the repo is carrying binaries it must not.
  *
- * Three findings, each naming its remedy:
+ * Findings, each naming its remedy:
  *
- *   - `catalog-images-in-repo` — any file under `public/catalog-images/`, the directory a catalog
- *     image download writes. Decided from paths alone, so a caller without sizes still refuses it.
+ *   - one per entry of {@link FORBIDDEN_PUBLIC_DIRS}: any file under a directory a media download
+ *     writes (`public/catalog-images/` is `catalog-images-in-repo`, `public/blog/wp-content/uploads/`
+ *     is `blog-media-in-repo`). Decided from paths alone, so a caller without sizes still refuses
+ *     it. This list is the one source the validators and the reconcile read; the Gitea
+ *     pre-receive size guard names the same directories.
  *   - `public-binary-oversized` — one raster or media file over {@link PUBLIC_BINARY_LIMITS}
  *     `maxFileBytes`.
  *   - `public-tree-over-budget` — the whole `public/` tree over `maxTotalBytes`.
@@ -28,13 +31,25 @@ export const PUBLIC_BINARY_LIMITS = Object.freeze({
   maxTotalBytes: 32 * 1024 * 1024,
 });
 
-/** The directory under `public/` a catalog image download writes. */
-export const CATALOG_IMAGES_DIR = "catalog-images/";
+/**
+ * The directories under `public/` a media download writes. No file under one may be committed.
+ *
+ * @type {ReadonlyArray<Readonly<{ dir: string, code: string, noun: string }>>}
+ */
+export const FORBIDDEN_PUBLIC_DIRS = Object.freeze([
+  Object.freeze({ dir: "catalog-images/", code: "catalog-images-in-repo", noun: "catalog image" }),
+  Object.freeze({ dir: "blog/wp-content/uploads/", code: "blog-media-in-repo", noun: "blog media" }),
+]);
 
-/** The finding code for files under {@link CATALOG_IMAGES_DIR}. */
-export const CATALOG_IMAGES_FINDING_CODE = "catalog-images-in-repo";
+/** The finding codes decided from paths alone. */
+export const PATH_DECIDED_FINDING_CODES = Object.freeze(new Set(FORBIDDEN_PUBLIC_DIRS.map((d) => d.code)));
+
+/** True for a path (relative to `public/`, `/` separators) under a forbidden directory. */
+export function isForbiddenPublicPath(rel) {
+  return FORBIDDEN_PUBLIC_DIRS.some((d) => rel.startsWith(d.dir));
+}
 
-/** The kit command that moves rehosted catalog image references back to their source URLs. */
+/** The kit command that moves downloaded catalog images and blog media back to their source URLs. */
 export const UNHOST_IMAGES_COMMAND = "node agency-kit/tools/import-catalog.mjs --store <checkout> --unhost-images --write";
 
 const RASTER_OR_MEDIA = /\.(?:jpe?g|png|gif|webp|avif|bmp|tiff?|heic|heif|ico|jxl|mp4|m4v|mov|webm|mkv|avi|mpe?g|mp3|wav|ogg|oga|m4a|aac|flac|opus)$/i;
@@ -51,19 +66,20 @@ export function publicBinaryFindings(entries, limits = {}) {
   const maxFileBytes = limits.maxFileBytes ?? PUBLIC_BINARY_LIMITS.maxFileBytes;
   const maxTotalBytes = limits.maxTotalBytes ?? PUBLIC_BINARY_LIMITS.maxTotalBytes;
   const findings = [];
-  const catalogImages = entries.filter((e) => e.rel.startsWith(CATALOG_IMAGES_DIR));
-  if (catalogImages.length > 0) {
-    const bytes = catalogImages.reduce((n, e) => n + (e.bytes ?? 0), 0);
+  for (const { dir, code, noun } of FORBIDDEN_PUBLIC_DIRS) {
+    const files = entries.filter((e) => e.rel.startsWith(dir));
+    if (files.length === 0) continue;
+    const bytes = files.reduce((n, e) => n + (e.bytes ?? 0), 0);
     findings.push({
-      code: CATALOG_IMAGES_FINDING_CODE,
-      path: `public/${CATALOG_IMAGES_DIR}`,
-      message: `${catalogImages.length} catalog image file(s)${bytes ? ` (${mb(bytes)})` : ""} are committed to the store repo; ` +
+      code,
+      path: `public/${dir}`,
+      message: `${files.length} ${noun} file(s)${bytes ? ` (${mb(bytes)})` : ""} are committed to the store repo; ` +
         "images belong in the platform pool, not the repo; until platform capture owns them, keep each image at its source URL",
       remedy: UNHOST_IMAGES_COMMAND,
     });
   }
   for (const e of entries) {
-    if (e.rel.startsWith(CATALOG_IMAGES_DIR) || e.bytes === undefined) continue;
+    if (isForbiddenPublicPath(e.rel) || e.bytes === undefined) continue;
     if (e.bytes > maxFileBytes && RASTER_OR_MEDIA.test(e.rel)) {
       findings.push({
         code: "public-binary-oversized",

package/apps/storefront/src/lib/content/shared/homeVisualParity.ts

@@ -1,5 +1,5 @@
 import {
-  isSafeRehostedAssetPathForTenant,
+  isPageBlockImageReference,
   isSafeStorefrontHref,
 } from "@tot/public-runtime";
 import { withBase } from "@/lib/publication/shared/basePath";
@@ -73,7 +73,7 @@ export function promoTilesView(
       .map((tile, index) => ({
         ...tile,
         href: withBase(basePath, tile.href),
-        image: isSafeRehostedAssetPathForTenant(tile.image, tenantId) ? tile.image : undefined,
+        image: isPageBlockImageReference(tile.image, tenantId) ? tile.image : undefined,
         imageAlt: tile.imageAlt ?? tile.label,
         imageWidth: isLogoStrip ? 160 : 800,
         imageHeight: isLogoStrip ? 80 : isPortrait ? 1000 : 450,
@@ -95,12 +95,12 @@ export function promoTilesView(
 }
 
 /**
- * The editorial block's media column: the rehosted image, else generated art when
+ * The editorial block's media column: the block image, else generated art when
  * the block asks for it with `imageSeed`, else none — a text-only block.
  */
 export function editorialMediaView(block: EditorialBlock, tenantId: string) {
   if (
-    isSafeRehostedAssetPathForTenant(block.image, tenantId) &&
+    isPageBlockImageReference(block.image, tenantId) &&
     typeof block.imageAlt === "string"
   ) {
     return { kind: "image" as const, src: block.image, alt: block.imageAlt };

package/apps/storefront/src/lib/content/storyblok/content-model.ts

@@ -125,7 +125,7 @@ export interface EditorialBlock {
   body_html: string;
   /** Generated placeholder art. With neither `image` nor `imageSeed` the block is text-only. */
   imageSeed?: string;
-  /** Rehosted editorial photography; preferred over a generated placeholder. */
+  /** Editorial photography (a page-block image reference); preferred over a generated placeholder. */
   image?: string;
   imageAlt?: string;
   align?: "left" | "right";

package/apps/storefront/src/lib/content/trustStrip.ts

@@ -14,8 +14,7 @@
  */
 import {
   isFabricatedTrustProof,
-  isSafeRehostedAssetPath,
-  isSafeRehostedAssetPathForTenant,
+  isPageBlockImageReference,
 } from "@tot/public-runtime";
 
 export type TrustStripItem =
@@ -82,9 +81,7 @@ export function sanitizeTrustStrip(
         out.push({
           kind: "claim",
           label,
-          ...((tenantId
-            ? isSafeRehostedAssetPathForTenant(item.icon, tenantId)
-            : isSafeRehostedAssetPath(item.icon))
+          ...(isPageBlockImageReference(item.icon, tenantId || undefined)
             ? { icon: item.icon, iconAlt: item.iconAlt?.trim() || "" }
             : {}),
         });

package/package.json

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

@@ -16,6 +16,7 @@
     "./image-finding-acceptance": "./src/image-finding-acceptance.ts",
     "./image-preview-rewrite-overlay": "./src/image-preview-rewrite-overlay.ts",
     "./capture-rewrites": "./src/capture-rewrites.ts",
+    "./extension-contract-values": "./src/extension-contract-values.mjs",
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
     "./catalog-files": "./src/catalog-files.ts",

package/packages/public-runtime/src/extension-contract-values.d.mts

@@ -19,4 +19,14 @@ export declare const THEME_HEADING_LEVELS: readonly ["hero", "h1", "h2", "h3"];
 export declare function isThemeCssSize(value: unknown): value is string;
 export declare function isSafeRehostedAssetPath(value: unknown): value is string;
 export declare function isSafeRehostedAssetPathForTenant(value: unknown, tenantId: unknown): value is string;
+export declare function isPlatformPoolImagePath(value: unknown): value is string;
+export type ImageSourceUrlRefusal =
+  | "unsupported"
+  | "unsafe-scheme"
+  | "userinfo"
+  | "nonstandard-port"
+  | "blocked-address"
+  | "ip-literal";
+export declare function imageSourceUrlRefusal(value: unknown): ImageSourceUrlRefusal | null;
+export declare function isPageBlockImageReference(value: unknown, tenantId?: unknown): value is string;
 export declare function isSafeStorefrontHref(value: unknown): value is string;

package/packages/public-runtime/src/extension-contract-values.mjs

@@ -58,6 +58,60 @@ export function isSafeRehostedAssetPathForTenant(value, tenantId) {
   return value.startsWith("/shared/") || value.startsWith(`/tenants/${tenantId}/`);
 }
 
+/** A platform pool reference `/_a/<sha256>[.<ext>]`: content-addressed bytes the platform owns. */
+export function isPlatformPoolImagePath(value) {
+  return typeof value === "string" && /^\/_a\/[0-9a-f]{64}(?:\.[a-z0-9]{1,8})?$/.test(value);
+}
+
+const IMAGE_SOURCE_DNS_NAME = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+const IMAGE_SOURCE_BLOCKED_NAME = /(?:^|\.)(?:localhost|localdomain|local|internal|intranet|lan|home|arpa)$/i;
+const IMAGE_SOURCE_IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+
+/**
+ * The locator half of remote image capture's refusal: why capture will not fetch `value`, or null
+ * when it will try. Capture (`original-image-capture.ts`) runs exactly this before it resolves the
+ * host and pins a public address; `"ip-literal"` hands an IPv4 literal back to that caller's
+ * address blocklist. Every other surface that accepts a source URL for capture uses this function,
+ * so authoring can never accept a locator capture refuses.
+ *
+ * @returns {null | "unsupported" | "unsafe-scheme" | "userinfo" | "nonstandard-port" | "blocked-address" | "ip-literal"}
+ */
+export function imageSourceUrlRefusal(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return "unsupported";
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return "unsupported";
+  }
+  if (url.protocol !== "https:") return "unsafe-scheme";
+  if (url.username || url.password) return "userinfo";
+  if (url.port) return "nonstandard-port";
+  const hostname = url.hostname;
+  if (!hostname || hostname.includes("%")) return "blocked-address";
+  if (IMAGE_SOURCE_IPV4.test(hostname)) return "ip-literal";
+  const name = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+  if (IMAGE_SOURCE_BLOCKED_NAME.test(name) || !IMAGE_SOURCE_DNS_NAME.test(hostname)) return "blocked-address";
+  return null;
+}
+
+/**
+ * A page-block image (hero image and slides, editorial image, promo tiles, trust-strip icons):
+ * a governed `/shared/` or active-tenant `/tenants/<id>/` path, a platform pool `/_a/<sha256>`
+ * reference, or an https source URL on a public DNS name that capture fetches into the pool at
+ * hosted preview and publish. A source URL is written as authored: no whitespace, quotes, angle
+ * brackets or backslashes. Without `tenantId`, any governed tenant path is accepted.
+ */
+export function isPageBlockImageReference(value, tenantId) {
+  if (typeof value !== "string") return false;
+  if (tenantId === undefined || tenantId === null
+    ? isSafeRehostedAssetPath(value)
+    : isSafeRehostedAssetPathForTenant(value, tenantId)) return true;
+  if (isPlatformPoolImagePath(value)) return true;
+  if (!/^https:\/\//i.test(value) || /[\u0000-\u0020\u007f"'<>\\`]/.test(value)) return false;
+  return imageSourceUrlRefusal(value) === null;
+}
+
 /** Navigation authored in a commerce block stays on the current storefront. */
 export function isSafeStorefrontHref(value) {
   if (typeof value !== "string" || !value.startsWith("/") || value.startsWith("//")) return false;

package/packages/public-runtime/src/extension-contract.ts

@@ -17,11 +17,15 @@ export {
   FEATURED_PRODUCT_PRESENTATIONS,
   PROMO_TILE_PRESENTATIONS,
   THEME_HEADING_LEVELS,
+  imageSourceUrlRefusal,
+  isPageBlockImageReference,
+  isPlatformPoolImagePath,
   isSafeRehostedAssetPath,
   isSafeRehostedAssetPathForTenant,
   isSafeStorefrontHref,
   isThemeCssSize,
 } from "./extension-contract-values.mjs";
+export type { ImageSourceUrlRefusal } from "./extension-contract-values.mjs";
 
 export type PromoTilePresentation =
   (typeof PROMO_TILE_PRESENTATIONS)[number];

package/packages/public-runtime/src/image-dependencies.ts

@@ -168,6 +168,16 @@ const DEFERRED_IMAGE_MESSAGE = "A CSS image form was skipped because hosted prev
 const BUILTIN_PLATFORM_PREFIXES = ["/_astro/", "/shared/"] as const;
 const DIRECT_IMAGE_KEY_RE = /^(?:image|images|featuredimage|featured_image|thumbnail|thumbnailurl|imageurl|image_url)$/i;
 const SCALAR_IMAGE_KEY_RE = /^(?:thumbnailurl|imageurl|image_url)$/i;
+/**
+ * Identity and chrome image fields (trust-strip `icon`, chrome `head.favicon`, theme
+ * `brand.logoLight`/`logoDark`/`favicon`/`ogImage`, author `avatar`, checkout `logoUrl`). The same
+ * keys also carry inline SVG markup, icon names, emoji and booleans, so a value is a reference only
+ * when it is locator-shaped; anything else is not an image and is skipped without a finding.
+ */
+const LOCATOR_IMAGE_KEY_RE = /^(?:icon|favicon|logo|logolight|logodark|avatar|ogimage|og_image|logourl|logo_url)$/i;
+/** An object under one of these keys is an image whose `src`/`url` is the locator (chrome `brand.logo`, JSON-LD `logo`). */
+const LOCATOR_IMAGE_OBJECT_KEY_RE = /^logo$/i;
+const LOCATOR_SHAPED_RE = /^(?:\/|https?:|data:image\/)/i;
 const HTML_VALUE_KEYS = new Set(["contenthtml", "content_html", "descriptionhtml", "description_html", "html"]);
 const NON_IMAGE_ASSET_RE = /\.(?:css|m?js|woff2?|ttf|otf|eot|map|json|xml|txt|pdf|mp4|webm|mov)$/i;
 const CONTROL_RE = /[\u0000-\u001f\u007f]/;
@@ -935,6 +945,8 @@ function catalogReferences(content: string, artifactPath: string): ExtractedRefe
       else if (DIRECT_IMAGE_KEY_RE.test(key) || (imageContext && /^(?:src|url)$/i.test(key))) {
         if (trimAsciiWhitespace(value)) refs.push({ locator: value, surface: "catalog" });
         else malformed();
+      } else if (LOCATOR_IMAGE_KEY_RE.test(key) && LOCATOR_SHAPED_RE.test(trimAsciiWhitespace(value))) {
+        refs.push({ locator: value, surface: "catalog" });
       }
       continue;
     }
@@ -967,12 +979,19 @@ function catalogReferences(content: string, artifactPath: string): ExtractedRefe
     if (imageContext && !entries.some(([childKey, child]) => /^(?:src|url)$/i.test(childKey) && typeof child === "string" && trimAsciiWhitespace(child))) {
       malformed();
     }
+    const locatorImageObject = !imageContext && LOCATOR_IMAGE_OBJECT_KEY_RE.test(key);
     for (let index = entries.length - 1; index >= 0; index--) {
       const [childKey, child] = entries[index]!;
       if (imageContext && /^(?:src|url)$/i.test(childKey)) {
         if (typeof child === "string" && trimAsciiWhitespace(child)) stack.push({ kind: "reference", locator: child });
         continue;
       }
+      if (locatorImageObject && /^(?:src|url)$/i.test(childKey)) {
+        if (typeof child === "string" && LOCATOR_SHAPED_RE.test(trimAsciiWhitespace(child))) {
+          stack.push({ kind: "reference", locator: child });
+        }
+        continue;
+      }
       const nextImageContext = /^(?:image|images|featuredImage|featured_image|thumbnail)$/i.test(childKey);
       stack.push({ kind: "visit", value: child, key: childKey, imageContext: nextImageContext });
     }

package/scripts/tenant/validate.mjs

@@ -35,8 +35,7 @@ import {
   FEATURED_PRODUCT_PRESENTATIONS,
   PROMO_TILE_PRESENTATIONS,
   THEME_HEADING_LEVELS,
-  isSafeRehostedAssetPath,
-  isSafeRehostedAssetPathForTenant,
+  isPageBlockImageReference,
   isSafeStorefrontHref,
   isThemeCssSize,
 } from "../../packages/public-runtime/src/extension-contract-values.mjs";
@@ -45,7 +44,7 @@ import {
   parseMappingTarget,
   workspacePathForTenantRelative,
 } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
-import { CATALOG_IMAGES_DIR, publicBinaryFindings } from "../../agency-kit/tools/lib/public-binaries.mjs";
+import { isForbiddenPublicPath, publicBinaryFindings } from "../../agency-kit/tools/lib/public-binaries.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
 import { declaredObligations, isRegulatedCompliance, validateDeclaredConfig } from "../../packages/cli/src/declared-config.mjs";
 
@@ -443,11 +442,8 @@ function validateProductSource(value, file, at) {
 }
 
 function validateVisualAsset(value, file, at, out, tenantId) {
-  const safe = tenantId
-    ? isSafeRehostedAssetPathForTenant(value, tenantId)
-    : isSafeRehostedAssetPath(value);
-  if (!safe) {
-    out.push(mk(ERROR, "asset-path", file, `${at} must be a /shared/... asset or belong to the active tenant`));
+  if (!isPageBlockImageReference(value, tenantId || undefined)) {
+    out.push(mk(ERROR, "asset-path", file, `${at} must be a /shared/... or active-tenant asset, a /_a/<sha256> pool reference, or an https source URL on a public host (captured into the pool at preview and publish)`));
   }
 }
 
@@ -1367,8 +1363,8 @@ function checkAsset(src, file, publicDir, tenantId) {
 function findLargePublicAssets(publicDir, rel) {
   const out = [];
   for (const p of walk(publicDir, () => true)) {
-    // public/catalog-images/ is already an error (catalog-images-in-repo); one line, not thousands.
-    if (relative(publicDir, p).split("\\").join("/").startsWith(CATALOG_IMAGES_DIR)) continue;
+    // a forbidden media directory is already an error (catalog-images-in-repo, blog-media-in-repo); one line, not thousands.
+    if (isForbiddenPublicPath(relative(publicDir, p).split("\\").join("/"))) continue;
     const size = statSync(p).size;
     if (size >= LARGE_PUBLIC_ASSET_BYTES) {
       out.push(mk(WARN, "large-public-asset", rel(p), `${(size / 1024).toFixed(0)}KB`));