@tokenoftrust/storefront-runner 2.1.10 → 2.2.0

package/apps/storefront/src/components/Seo.astro

@@ -3,7 +3,7 @@
  * <Seo> — per-page title/meta, Open Graph, Twitter card, canonical, JSON-LD.
  * (brief §8). Tenant-aware: OG image + site name come from the resolved tenant.
  */
-import { articleSeoMetaTags, type ArticleMeta } from "@/lib/seo/meta.js";
+import { articleSeoMetaTags, resolveOgImage, type ArticleMeta } from "@/lib/seo/meta.js";
 import { withXDefault, type Alternate } from "@/lib/seo/alternates.js";
 import { safeJsonScriptContent } from "@/lib/jsonScript";
 
@@ -64,23 +64,23 @@ const {
 const { tenant, canonicalBase } = Astro.locals;
 const canonical =
   canonicalOverride ?? new URL(path, canonicalBase + "/").toString();
+// Don't double-append the brand: merchant SEO titles (title_tag) often already
+// end with the store name.
+const fullTitle = title.includes(tenant.displayName)
+  ? title
+  : `${title} — ${tenant.displayName}`;
+const image = resolveOgImage({
+  ogImage, themeOgImage: tenant.theme_tokens?.brand?.ogImage ?? null, canonicalBase,
+});
 const articleMeta = articleSeoMetaTags({
   ogType,
   article,
-  imageAlt,
-  imageWidth,
-  imageHeight,
+  imageAlt: image ? imageAlt : undefined,
+  imageWidth: image ? imageWidth : undefined,
+  imageHeight: image ? imageHeight : undefined,
   twitterSite,
   twitterCreator,
 });
-// Don't double-append the brand: merchant SEO titles (title_tag) often already
-// end with the store name.
-const fullTitle = title.includes(tenant.displayName)
-  ? title
-  : `${title} — ${tenant.displayName}`;
-const image = ogImage
-  ? new URL(ogImage, canonicalBase + "/").toString()
-  : new URL(tenant.theme_tokens?.brand?.ogImage ?? "/brand/northwind-og.svg", canonicalBase + "/").toString();
 
 const graphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
 const alternateLinks = withXDefault(alternates);
@@ -108,12 +108,12 @@ const alternateLinks = withXDefault(alternates);
 <meta property="og:title" content={fullTitle} />
 {description && <meta property="og:description" content={description} />}
 <meta property="og:url" content={canonical} />
-<meta property="og:image" content={image} />
+{image && <meta property="og:image" content={image} />}
 
 <meta name="twitter:card" content="summary_large_image" />
 <meta name="twitter:title" content={fullTitle} />
 {description && <meta name="twitter:description" content={description} />}
-<meta name="twitter:image" content={image} />
+{image && <meta name="twitter:image" content={image} />}
 
 {
   articleMeta.map((t) =>

package/apps/storefront/src/lib/seo/meta.ts

@@ -34,6 +34,20 @@ export interface ArticleSeoInput {
   twitterCreator?: string;
 }
 
+/**
+ * The og:image/twitter:image URL, or `null` when neither the page nor the
+ * tenant's theme declares one. Never falls back to a platform placeholder --
+ * a shared image path that 404s live for every tenant that hasn't set one.
+ */
+export function resolveOgImage(input: {
+  ogImage?: string;
+  themeOgImage?: string | null;
+  canonicalBase: string;
+}): string | null {
+  const declared = input.ogImage ?? input.themeOgImage ?? null;
+  return declared ? new URL(declared, input.canonicalBase + "/").toString() : null;
+}
+
 /**
  * The article-only OG/Twitter meta tags. Returns `[]` for any non-article page
  * so `article:*`, `og:image:alt`, and `twitter:site`/`creator` can never leak

package/package.json

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

@@ -43,6 +43,17 @@ export interface PlatformHostedImageConfig {
 
 export interface ImageDependencyScanOptions {
   tenantId: string;
+  /**
+   * The tenant's own public origins (e.g. `https://tokenoftrust.com`), from declared tenant
+   * config -- never derived from the tenant id. An absolute URL on one of these origins is
+   * classified by its path exactly as a root-relative locator would be (tenant-hosted,
+   * platform-hosted, capture-required/local, or cross-tenant), instead of being treated as a
+   * third-party reference. Required (empty is valid) so every caller states its origins
+   * explicitly; six call sites compute finding identities and must agree, or a capture and a
+   * later publish scanning with different origins would diverge and the publish gate would
+   * refuse on an identity mismatch it can't explain.
+   */
+  tenantOrigins: readonly string[];
   platformHosted?: PlatformHostedImageConfig;
 }
 
@@ -164,6 +175,8 @@ const URL_TAB_OR_NEWLINE_RE = /[\t\n\r]/g;
 const ASCII_WHITESPACE_RE = /[\t\n\f\r ]/;
 const ASCII_WHITESPACE_RUN_RE = /[\t\n\f\r ]+/;
 const MAX_VISIBLE_FINDINGS = 100;
+/** Shared artifact-scan cap for both the publish gate and the preview capture endpoint. */
+export const MAX_IMAGE_SCAN_ARTIFACTS = 5000;
 const MAX_PERCENT_DECODE_PASSES = 8;
 const MAX_CATALOG_WALK_ITEMS = 1_000_000;
 const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
@@ -447,12 +460,25 @@ function adoptCssReferences(refs: ExtractedReference[], cssRefs: readonly Extrac
   for (const ref of cssRefs) refs.push(afterBase ? { ...ref, afterBase: true } : ref);
 }
 
+const NO_DECLARED_CUSTOM_PROPERTIES: ReadonlySet<string> = new Set();
+
 /**
  * CSS extraction uses a JavaScript parser because this module is imported by
  * Worker routes. A native CSS binding cannot be evaluated by workerd, which
  * would prevent every route sharing its bundle chunk from loading.
+ *
+ * `declaredCustomProperties` names every `--foo` declared anywhere in the
+ * scanned artifact set (see `collectDeclaredCustomProperties`). The scanner
+ * already scans `url(...)` wherever it appears, including inside a custom
+ * property's own declaration, so a `var(--foo)` reference is only deferred
+ * (unresolvable statically) when `--foo` is not declared anywhere — or when
+ * its fallback argument itself contains no scannable image source.
  */
-function cssReferences(css: string, kind: "stylesheet" | "declaration"): ExtractedReference[] {
+function cssReferences(
+  css: string,
+  kind: "stylesheet" | "declaration",
+  declaredCustomProperties: ReadonlySet<string> = NO_DECLARED_CUSTOM_PROPERTIES,
+): ExtractedReference[] {
   if (!css) return [];
   const refs: ExtractedReference[] = [];
   const parseValue = (value: string): CssScanNode | null => {
@@ -467,6 +493,28 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
     if (imageValue) rememberDeferred(refs, name);
   };
 
+  // `var(--foo)`'s own declaration site already captured any image inside it (scanValue's
+  // Url case is unconditional); a top-level `var()` reference only needs its own deferred
+  // marker when `--foo` is not declared anywhere AND its fallback argument (present only
+  // when the parse produced [Identifier, Operator, Raw]) has no scannable image source
+  // either. Scoped to scanValue's top-level property-value position only: a var() nested
+  // inside image()/image-set() keeps the existing conservative "always defer, never resolve
+  // its fallback" behaviour — those constructs are rare/synthetic and untouched by this rule.
+  const resolveVar = (node: CssScanNode, imageValue: boolean): void => {
+    if (!imageValue) return;
+    // cssChildren() is css-tree's own iterable List, not a real array (no index access,
+    // no .length) — spread it once to get an indexable copy for the fixed [name, ",", fallback] shape.
+    const children = [...cssChildren(node)];
+    const propertyName = children[0]?.type === "Identifier" ? children[0].name ?? "" : "";
+    if (propertyName && declaredCustomProperties.has(propertyName)) return;
+    const rawFallback = children[2];
+    if (rawFallback?.type === "Raw") {
+      const parsedFallback = parseValue(rawFallback.value ?? "");
+      if (parsedFallback && firstImageSource(cssChildren(parsedFallback))) return;
+    }
+    rememberDeferred(refs, "var");
+  };
+
   // image() resolves one source. A discarded non-image argument does not consume it.
   const scanNestedDeferred = (node: CssScanNode): void => {
     if (node.type !== "Function") {
@@ -481,7 +529,7 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
     for (const child of cssChildren(node)) scanNestedDeferred(child);
   };
 
-  const firstImageSource = (nodes: CssScanNode[]): boolean => {
+  function firstImageSource(nodes: CssScanNode[]): boolean {
     let chosen = false;
     for (const node of nodes) {
       if (chosen) {
@@ -509,7 +557,7 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
       if (firstImageSource(cssChildren(node))) chosen = true;
     }
     return chosen;
-  };
+  }
 
   const imageSetSources = (nodes: CssScanNode[]): void => {
     let option: CssScanNode[] = [];
@@ -541,6 +589,10 @@ function cssReferences(css: string, kind: "stylesheet" | "declaration"): Extract
         continue;
       }
       const name = (node.name ?? "").toLowerCase();
+      if (name === "var") {
+        resolveVar(node, imageValue);
+        continue;
+      }
       const deferred = deferredFunctionName(name);
       if (deferred) {
         noteDeferred(deferred, imageValue);
@@ -706,6 +758,7 @@ function collectHtmlElement(
   sourceContext: HtmlSourceContext,
   artifactPath: string,
   inheritedBase: ResolvedBase | null,
+  declaredCustomProperties: ReadonlySet<string>,
 ): void {
   const tag = element.tagName;
   const html = element.namespaceURI === HTML_NAMESPACE;
@@ -717,7 +770,7 @@ function collectHtmlElement(
   if (tag === "style") return;
   const styleValue = htmlAttribute(element, "style");
   const emitStyle = (): void => {
-    if (styleValue != null) adoptCssReferences(refs, cssReferences(styleValue, "declaration"), afterBase);
+    if (styleValue != null) adoptCssReferences(refs, cssReferences(styleValue, "declaration", declaredCustomProperties), afterBase);
   };
   if (!html) {
     if (element.namespaceURI === SVG_NAMESPACE && (tag === "image" || tag.toLowerCase() === "feimage")) {
@@ -732,7 +785,7 @@ function collectHtmlElement(
   if (tag === "iframe") {
     const srcdoc = htmlAttribute(element, "srcdoc");
     if (srcdoc != null && !isBlankLocator(srcdoc)) {
-      for (const nested of htmlReferences(srcdoc, artifactPath, inheritedBase)) {
+      for (const nested of htmlReferences(srcdoc, artifactPath, inheritedBase, declaredCustomProperties)) {
         refs.push({
           locator: nested.locator,
           surface: nested.surface,
@@ -800,7 +853,12 @@ function collectHtmlElement(
   emitStyle();
 }
 
-function htmlReferences(html: string, artifactPath: string, inherited: ResolvedBase | null = null): ExtractedReference[] {
+function htmlReferences(
+  html: string,
+  artifactPath: string,
+  inherited: ResolvedBase | null = null,
+  declaredCustomProperties: ReadonlySet<string> = NO_DECLARED_CUSTOM_PROPERTIES,
+): ExtractedReference[] {
   const refs: ExtractedReference[] = [];
   let baseHref: string | null = null;
   let sawBase = false;
@@ -815,7 +873,7 @@ function htmlReferences(html: string, artifactPath: string, inherited: ResolvedB
     const frame = stack.pop()!;
     const { node, inTemplate, sourceContext } = frame;
     if (isHtmlText(node)) {
-      if (frame.cssText) adoptCssReferences(refs, cssReferences(node.value, "stylesheet"), sawBase);
+      if (frame.cssText) adoptCssReferences(refs, cssReferences(node.value, "stylesheet", declaredCustomProperties), sawBase);
       continue;
     }
     if (node.nodeName === "#document" || node.nodeName === "#document-fragment") {
@@ -823,7 +881,7 @@ function htmlReferences(html: string, artifactPath: string, inherited: ResolvedB
       continue;
     }
     if (!isHtmlElement(node)) continue;
-    collectHtmlElement(node, refs, inTemplate, noteBase, sawBase, sourceContext, artifactPath, enclosingBase());
+    collectHtmlElement(node, refs, inTemplate, noteBase, sawBase, sourceContext, artifactPath, enclosingBase(), declaredCustomProperties);
     const childContext = childSourceContext(node.tagName, node.namespaceURI);
     if (node.tagName === "template" && node.namespaceURI === HTML_NAMESPACE && "content" in node) {
       pushHtmlChildren(stack, node.content.childNodes, true, false, childContext);
@@ -1134,15 +1192,23 @@ export function classifyImageDependency(
     tenantId: string;
     artifactPath: string;
     platformHosted?: PlatformHostedImageConfig;
+    tenantOrigins?: readonly string[];
   },
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
-  return classifyImageDependencyWithPrepared(locator, context, preparePlatformHostedConfig(context.platformHosted));
+  return classifyImageDependencyWithPrepared(
+    locator, context, preparePlatformHostedConfig(context.platformHosted), prepareTenantOrigins(context.tenantOrigins ?? []),
+  );
+}
+
+function prepareTenantOrigins(tenantOrigins: readonly string[]): ReadonlySet<string> {
+  return new Set(tenantOrigins.map(normalizedOrigin).filter((origin): origin is string => origin != null));
 }
 
 function classifyParsedHttpUrl(
   absolute: URL,
-  context: { tenantId: string },
+  context: { tenantId: string; artifactPath: string },
   platformHosted: PreparedPlatformHostedImageConfig,
+  tenantOrigins: ReadonlySet<string>,
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
   if (!absolute.hostname || absolute.username || absolute.password) {
     return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
@@ -1150,6 +1216,13 @@ function classifyParsedHttpUrl(
   if (absolutePathEscapes(absolute.pathname)) {
     return { canonicalLocator: "escape:", disposition: "security-error", reason: "tenant-escape" };
   }
+  if (tenantOrigins.has(absolute.origin) && !absolute.pathname.startsWith("//")) {
+    // The tenant's own origin: classify by path exactly as a root-relative locator would be,
+    // 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);
+  }
   absolute.hash = "";
   const canonical = absolute.toString();
   if (platformHosted.origins.has(absolute.origin) || platformHosted.references.has(stripQueryHash(canonical))) {
@@ -1166,6 +1239,7 @@ function classifyImageDependencyWithPrepared(
   locator: string,
   context: { tenantId: string; artifactPath: string },
   platformHosted: PreparedPlatformHostedImageConfig,
+  tenantOrigins: ReadonlySet<string>,
 ): Pick<ImageDependency, "canonicalLocator" | "disposition" | "reason"> {
   const raw = normalizeUrlInput(locator);
   if (!raw || CONTROL_RE.test(raw)) {
@@ -1184,14 +1258,14 @@ function classifyImageDependencyWithPrepared(
     } catch {
       return { canonicalLocator: "invalid:", disposition: "security-error", reason: "malformed" };
     }
-    return classifyParsedHttpUrl(absolute, context, platformHosted);
+    return classifyParsedHttpUrl(absolute, context, platformHosted, tenantOrigins);
   }
 
   if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) {
     return { canonicalLocator: "unsafe:", disposition: "security-error", reason: "unsafe-scheme" };
   }
   const networkUrl = backslashNetworkUrl(raw, context.artifactPath);
-  if (networkUrl) return classifyParsedHttpUrl(networkUrl, context, platformHosted);
+  if (networkUrl) return classifyParsedHttpUrl(networkUrl, context, platformHosted, tenantOrigins);
   const pathOnly = stripQueryHash(raw);
   const structural = structuralPath(pathOnly);
   if (structural.startsWith("/") && hasDotDotSegment(pathOnly)) {
@@ -1279,6 +1353,79 @@ export function buildImageDependencyWarningBatch(
   };
 }
 
+function declaredCustomPropertyNames(css: string, kind: "stylesheet" | "declaration"): Set<string> {
+  const declared = new Set<string>();
+  const walk = (node: CssScanNode): void => {
+    if (node.type === "Declaration") {
+      const property = node.property ?? "";
+      if (property.startsWith("--")) declared.add(property);
+      return;
+    }
+    if (node.block) walk(node.block);
+    for (const child of cssChildren(node)) walk(child);
+  };
+  try {
+    const parsed = parse(css, {
+      context: kind === "declaration" ? "declarationList" : "stylesheet",
+      list: false,
+    }) as unknown as CssScanNode;
+    walk(parsed);
+  } catch {
+    // Invalid CSS contributes no declarations; the real scan fails open the same way.
+  }
+  return declared;
+}
+
+/** Every `style=""` attribute value (declaration context) and `<style>` text (stylesheet context). */
+function rawCssChunksInHtml(html: string): Array<{ css: string; kind: "stylesheet" | "declaration" }> {
+  const chunks: Array<{ css: string; kind: "stylesheet" | "declaration" }> = [];
+  const stack: HtmlNode[] = [parseFragment(html)];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    if (isHtmlText(node)) continue;
+    if (node.nodeName === "#document" || node.nodeName === "#document-fragment") {
+      for (const child of node.childNodes) stack.push(child);
+      continue;
+    }
+    if (!isHtmlElement(node)) continue;
+    const styleValue = htmlAttribute(node, "style");
+    if (styleValue != null) chunks.push({ css: styleValue, kind: "declaration" });
+    if (node.tagName === "style") {
+      for (const child of node.childNodes) {
+        if (isHtmlText(child)) chunks.push({ css: child.value, kind: "stylesheet" });
+      }
+      continue;
+    }
+    if (node.tagName === "template" && node.namespaceURI === HTML_NAMESPACE && "content" in node) {
+      for (const child of node.content.childNodes) stack.push(child);
+      continue;
+    }
+    for (const child of node.childNodes) stack.push(child);
+  }
+  return chunks;
+}
+
+/**
+ * Pre-pass: every `--foo` declared anywhere in the artifact set (CSS files, `<style>` blocks,
+ * `style=""` attributes). `scanImageDependencies` threads this into every `var()` decision so a
+ * reference to a declared custom property is never deferred — its image, if any, was already
+ * captured at the declaration itself.
+ */
+function collectDeclaredCustomProperties(artifacts: readonly ImageDependencyArtifact[]): Set<string> {
+  const declared = new Set<string>();
+  for (const artifact of artifacts) {
+    const kind = inferKind(artifact);
+    if (kind === "css") {
+      for (const name of declaredCustomPropertyNames(artifact.content, "stylesheet")) declared.add(name);
+    } else if (kind === "html") {
+      for (const chunk of rawCssChunksInHtml(artifact.content)) {
+        for (const name of declaredCustomPropertyNames(chunk.css, chunk.kind)) declared.add(name);
+      }
+    }
+  }
+  return declared;
+}
+
 /** Scan a revision's already-read artifacts with no network or filesystem I/O. */
 export function scanImageDependencies(
   artifacts: readonly ImageDependencyArtifact[],
@@ -1286,12 +1433,14 @@ export function scanImageDependencies(
 ): ImageDependencyScan {
   const dependencies: ImageDependency[] = [];
   const platformHosted = preparePlatformHostedConfig(options.platformHosted);
+  const tenantOrigins = prepareTenantOrigins(options.tenantOrigins);
+  const declaredCustomProperties = collectDeclaredCustomProperties(artifacts);
   let occurrence = 0;
   for (const [artifactIndex, artifact] of artifacts.entries()) {
     const kind = inferKind(artifact);
     let refs: ExtractedReference[];
-    if (kind === "html") refs = htmlReferences(artifact.content, artifact.path);
-    else if (kind === "css") refs = cssReferences(artifact.content, "stylesheet");
+    if (kind === "html") refs = htmlReferences(artifact.content, artifact.path, null, declaredCustomProperties);
+    else if (kind === "css") refs = cssReferences(artifact.content, "stylesheet", declaredCustomProperties);
     else {
       const parsed = catalogReferences(artifact.content, artifact.path);
       if (parsed == null) {
@@ -1317,7 +1466,7 @@ export function scanImageDependencies(
       const classified = classifyImageDependencyWithPrepared(ref.classificationLocator ?? ref.locator, {
         tenantId: options.tenantId,
         artifactPath: artifact.path,
-      }, platformHosted);
+      }, platformHosted, tenantOrigins);
       dependencies.push({
         locator: ref.locator,
         artifactIndex,