@tokenoftrust/storefront-runner 4.8.1 → 4.9.0

package/package.json

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

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

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

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