@tokenoftrust/storefront-runner 2.2.84 → 2.2.86

package/packages/public-runtime/src/publication-redirects.mjs

@@ -1,379 +1,5 @@
 // @ts-check
-// The pure core that turns a tenant's DECLARED redirects into a substrate-neutral redirect set
-// the publish pipeline can emit.
-//
-// A tenant's public site is served CDN -> static object (ADR 0013), so a redirect cannot be a
-// request-time decision in the Worker: it must exist in the published artifact. Both substrates
-// express it the same way — a precomputed map consulted by the single permitted edge function —
-// so the set below is substrate-neutral and the adapters only serialize it.
-//
-// Redirects are DECLARED, never derived from a tenant id. Three declaration sources normalize into
-// the one `redirect-308` contract `PublicationSpaceAliasV1` already defines:
-//   - publication-space `routes.aliases` entries whose behavior is `redirect-308`;
-//   - a content collection's `redirects.json` (old slug -> new slug), which becomes
-//     `/<collection>/<old>/` -> `/<collection>/<new>/`;
-//   - the tenant-wide `content/redirects.json` (relative path -> relative path or an explicit
-//     HTTPS destination), for legacy URLs that belong to no single collection.
-// Adding a tenant is a declaration, not a code change.
-//
-// 308 rather than 301 throughout: both pass ranking signal, and 308 additionally preserves the
-// request method, so a redirected non-GET is not silently rewritten. The declared alias contract
-// already specifies 308; collection renames join it rather than introducing a second status.
-//
-// Fails closed. An ambiguous declaration (one `from`, two targets), a cycle, or a set that exceeds
-// the substrate's ceiling REFUSES rather than emitting a partial map — a redirect that silently
-// does not exist is the failure this mechanism exists to prevent.
-
-/** The status every materialized redirect carries. */
-export const REDIRECT_STATUS = 308;
-
-/**
- * CloudFront Functions cap total code size at 10 KB, and the map is baked into the one
- * viewer-request function the public path already carries. The emitter refuses above the budget
- * left for it rather than shipping a function that cannot publish.
- */
-export const EDGE_FUNCTION_CODE_LIMIT_BYTES = 10240;
-/** Bump only when the meaning of a whole-site delivery manifest changes without changing its values. */
-export const WHOLE_SITE_DELIVERY_CONTRACT = "whole-site-delivery-v1";
-/** Reserved for the function's own logic, so the map gets the rest. */
-export const EDGE_FUNCTION_RESERVED_BYTES = 2048;
-/** Bytes available to the serialized map. */
-export const REDIRECT_MAP_BUDGET_BYTES =
-  EDGE_FUNCTION_CODE_LIMIT_BYTES - EDGE_FUNCTION_RESERVED_BYTES;
-
-/** JSON is not quite JS: these are legal in a JSON string but terminate a line to a JS parser. */
-const LINE_SEPARATOR = "
";
-const PARAGRAPH_SEPARATOR = "
";
-
-/**
- * @typedef {Object} DeclaredRedirect
- * @property {string} from    root-absolute request path
- * @property {string} to      root-absolute destination path
- * @property {string} source  which declaration produced it, for the report
- */
-
-/**
- * @typedef {Object} RedirectSet
- * @property {boolean} ok
- * @property {{from: string, to: string}[]} redirects  normalized, deduped, chain-collapsed
- * @property {string[]} violations  why it refused; empty when ok
- * @property {number} bytes         serialized size of the map
- * @property {number} budget        bytes available to the map
- */
-
-/**
- * Normalize a declared path to the form the edge function compares against: root-absolute, no
- * query or fragment, with a trailing slash unless the last segment names a file.
- * Returns null when the value cannot be a same-origin request path.
- * @param {string} raw
- * @returns {string | null}
- */
-export function normalizeRedirectPath(raw) {
-  if (typeof raw !== "string") return null;
-  const trimmed = raw.trim();
-  if (!trimmed.startsWith("/")) return null;
-  // Protocol-relative (`//host/...`) would leave the origin.
-  if (trimmed.startsWith("//")) return null;
-  const withoutSuffix = trimmed.split("?")[0].split("#")[0];
-  if (withoutSuffix.includes("..")) return null;
-  const collapsed = withoutSuffix.replace(/\/{2,}/g, "/");
-  if (collapsed === "/") return "/";
-  // The last NON-EMPTY segment: a trailing slash otherwise hides the filename from this test.
-  const segments = collapsed.split("/").filter(Boolean);
-  const last = segments[segments.length - 1] ?? "";
-  const namesFile = last.includes(".");
-  if (namesFile) return collapsed.replace(/\/$/, "");
-  return collapsed.endsWith("/") ? collapsed : `${collapsed}/`;
-}
-
-/**
- * Turn a content collection's `redirects.json` (old slug -> new slug) into declared redirects
- * under that collection's route prefix.
- * @param {string} collection  e.g. "blog"
- * @param {Record<string, unknown>} rows
- * @returns {DeclaredRedirect[]}
- */
-export function redirectsFromCollection(collection, rows) {
-  if (!rows || typeof rows !== "object") return [];
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const [oldSlug, newSlug] of Object.entries(rows)) {
-    if (typeof newSlug !== "string" || !oldSlug || !newSlug) continue;
-    out.push({
-      from: `/${collection}/${oldSlug}/`,
-      to: `/${collection}/${newSlug}/`,
-      source: `content/${collection}/redirects.json`,
-    });
-  }
-  return out;
-}
-
-/**
- * Turn the tenant-wide `content/redirects.json` map into root-relative declarations.
- * Its keys and same-origin values are repository paths without a leading slash; an
- * explicit HTTPS destination remains absolute and is validated by `buildRedirectSet`.
- * @param {Record<string, unknown>} rows
- * @returns {DeclaredRedirect[]}
- */
-export function redirectsFromSiteMap(rows) {
-  if (!rows || typeof rows !== "object" || Array.isArray(rows)) {
-    throw new TypeError(
-      "content/redirects.json must be an object mapping relative paths to destinations",
-    );
-  }
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const [from, rawTo] of Object.entries(rows)) {
-    if (
-      !from || from.startsWith("/") || typeof rawTo !== "string" || !rawTo || rawTo.startsWith("/")
-    ) {
-      throw new TypeError(
-        "content/redirects.json keys and same-origin destinations must be non-empty paths without a leading slash",
-      );
-    }
-    const rootedFrom = `/${from}`;
-    const isExternal = /^[A-Za-z][A-Za-z0-9+.-]*:/.test(rawTo);
-    const rootedTo = isExternal ? rawTo : `/${rawTo}`;
-    out.push({
-      from: normalizeRedirectPath(rootedFrom) ?? rootedFrom,
-      to: isExternal ? rawTo : normalizeRedirectPath(rootedTo) ?? rootedTo,
-      source: SITE_REDIRECTS_PATH,
-    });
-  }
-  return out;
-}
-
-/**
- * A content collection's redirect declaration, as it appears in a composed bundle's file list.
- * `content/blog/redirects.json` declares redirects for the `blog` collection.
- */
-export const COLLECTION_REDIRECTS_PATH = /^content\/([A-Za-z0-9][A-Za-z0-9_-]*)\/redirects\.json$/;
-
-/** The tenant-wide redirect declaration, for legacy URLs that belong to no single collection. */
-export const SITE_REDIRECTS_PATH = "content/redirects.json";
-
-/**
- * Does this composed file declare redirects the composition lifts into `routes.aliases`?
- * @param {string} path
- * @returns {boolean}
- */
-export function isRedirectDeclarationPath(path) {
-  return path === SITE_REDIRECTS_PATH || COLLECTION_REDIRECTS_PATH.test(path ?? "");
-}
-
-/**
- * Declared redirects for every content collection present in a composed revision.
- *
- * Reads the COMPOSED files rather than a working tree, so the redirects are bound to the same
- * revision as the pages they point at — a rename and its redirect can never publish apart.
- *
- * @param {{path: string, json: unknown}[]} entries  composed files, already parsed
- * @returns {DeclaredRedirect[]}
- */
-export function declaredRedirectsFromContent(entries) {
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const entry of entries ?? []) {
-    if (entry?.path === SITE_REDIRECTS_PATH) {
-      out.push(...redirectsFromSiteMap(/** @type {Record<string, unknown>} */ (entry.json)));
-      continue;
-    }
-    const match = COLLECTION_REDIRECTS_PATH.exec(entry?.path ?? "");
-    if (!match) continue;
-    out.push(
-      ...redirectsFromCollection(
-        /** @type {string} */ (match[1]),
-        /** @type {Record<string, unknown>} */ (entry.json),
-      ),
-    );
-  }
-  return out;
-}
-
-/**
- * Normalize a same-origin path or a deliberately external HTTPS destination.
- *
- * A source is always same-origin; a TARGET may leave the origin, but only when the declaration
- * says so in full: `https:` only, no credentials, no query, no fragment. Anything else — including
- * every shape that merely looks absolute — is not a usable destination and refuses.
- * @param {string} raw
- * @returns {string | null}
- */
-function normalizeRedirectDestination(/** @type {string} */ raw) {
-  const sameOrigin = normalizeRedirectPath(raw);
-  if (sameOrigin !== null) return sameOrigin;
-  try {
-    const url = new URL(raw);
-    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
-      return null;
-    }
-    return url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "");
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Turn publication-space aliases into declared redirects. Only `redirect-308` aliases produce a
- * redirect; a `render` alias is served, not redirected.
- * @param {{from?: string, behavior?: string, to?: string}[]} aliases
- * @param {string} [source]
- * @returns {DeclaredRedirect[]}
- */
-export function redirectsFromAliases(aliases, source = "publication-space routes.aliases") {
-  if (!Array.isArray(aliases)) return [];
-  /** @type {DeclaredRedirect[]} */
-  const out = [];
-  for (const alias of aliases) {
-    if (!alias || alias.behavior !== "redirect-308") continue;
-    if (typeof alias.from !== "string" || typeof alias.to !== "string") continue;
-    out.push({ from: alias.from, to: alias.to, source });
-  }
-  return out;
-}
-
-/**
- * Follow `from -> to` through the declared map so a rename chain (a -> b, b -> c) resolves to a
- * single hop (a -> c). A chain costs an extra round trip on every visit and dilutes the signal the
- * redirect exists to preserve. A cycle is unresolvable and refuses.
- * @param {Map<string, string>} direct
- * @param {string} from
- * @returns {{to: string} | {cycle: string[]}}
- */
-function collapseChain(direct, from) {
-  const seen = [from];
-  let to = /** @type {string} */ (direct.get(from));
-  while (direct.has(to)) {
-    if (seen.includes(to)) return { cycle: [...seen, to] };
-    seen.push(to);
-    to = /** @type {string} */ (direct.get(to));
-  }
-  return { to };
-}
-
-/**
- * Build the substrate-neutral redirect set from every declared source.
- * @param {DeclaredRedirect[]} declared
- * @param {number} [budget]
- * @returns {RedirectSet}
- */
-export function buildRedirectSet(declared, budget = REDIRECT_MAP_BUDGET_BYTES) {
-  /** @type {string[]} */
-  const violations = [];
-  /** @type {Map<string, string>} */
-  const direct = new Map();
-  /** @type {Map<string, string>} */
-  const origin = new Map();
-
-  for (const entry of declared) {
-    const from = normalizeRedirectPath(entry.from);
-    const to = normalizeRedirectDestination(entry.to);
-    if (from === null) {
-      violations.push(`${entry.source}: redirect source is not a usable request path`);
-      continue;
-    }
-    if (to === null) {
-      violations.push(`${entry.source}: redirect target is not a usable destination path`);
-      continue;
-    }
-    if (from === to) {
-      violations.push(`${entry.source}: "${from}" redirects to itself`);
-      continue;
-    }
-    const existing = direct.get(from);
-    if (existing !== undefined && existing !== to) {
-      violations.push(
-        `"${from}" is declared twice with different targets ("${existing}" in ${origin.get(from)}, "${to}" in ${entry.source})`,
-      );
-      continue;
-    }
-    direct.set(from, to);
-    origin.set(from, entry.source);
-  }
-
-  /** @type {{from: string, to: string}[]} */
-  const redirects = [];
-  for (const from of [...direct.keys()].sort()) {
-    const resolved = collapseChain(direct, from);
-    if ("cycle" in resolved) {
-      violations.push(`redirect cycle: ${resolved.cycle.join(" -> ")}`);
-      continue;
-    }
-    redirects.push({ from, to: resolved.to });
-  }
-
-  const bytes = serializeRedirectMap(redirects).length;
-  if (bytes > budget) {
-    violations.push(
-      `redirect map is ${bytes} bytes, over the ${budget}-byte edge budget (${redirects.length} redirects) — move the map to a key-value store before declaring more`,
-    );
-  }
-
-  return { ok: violations.length === 0, redirects, violations, bytes, budget };
-}
-
-/**
- * The map exactly as an edge function embeds it: compact JSON, keys sorted, so the same declared
- * input always produces byte-identical output and the published artifact stays deterministic.
- *
- * The output is embedded as a JS literal in generated edge-function source, and its keys and values
- * are tenant-declared strings. `JSON.stringify` escapes quotes and backslashes, which closes the
- * obvious break-out; the escapes below close the rest of the JSON-is-not-quite-JS gap — the two
- * separator code points are legal in JSON strings but are line terminators to a JS parser, and `<`
- * is neutralized so the same bytes stay inert if the map is ever inlined into markup.
- * @param {{from: string, to: string}[]} redirects
- * @returns {string}
- */
-export function serializeRedirectMap(redirects) {
-  /** @type {Record<string, string>} */
-  const map = {};
-  for (const { from, to } of [...redirects].sort((a, b) => a.from.localeCompare(b.from))) {
-    map[from] = to;
-  }
-  return JSON.stringify(map)
-    .split(LINE_SEPARATOR)
-    .join("\\u2028")
-    .split(PARAGRAPH_SEPARATOR)
-    .join("\\u2029")
-    .split("<")
-    .join("\\u003c");
-}
-
-/**
- * The declared set as publication-space aliases — the shape `routes.aliases` already carries and
- * `publicationRedirects()` (scripts/publish/lib/publication-space-release.mjs) already consumes on
- * its way into the live pointer. Emitting this rather than a parallel structure is what keeps
- * redirects ONE contract: the edge function, the pointer value, and the declaration all agree
- * because there is only one of them.
- *
- * Returns an empty array when the set refused, so a caller that ignores `ok` cannot publish a
- * half-built topology.
- * @param {RedirectSet} set
- * @returns {{from: string, behavior: "redirect-308", to: string}[]}
- */
-export function aliasesFromRedirectSet(set) {
-  if (!set.ok) return [];
-  return set.redirects.map(({ from, to }) => ({
-    from,
-    behavior: /** @type {"redirect-308"} */ ("redirect-308"),
-    to,
-  }));
-}
-
-/**
- * @param {RedirectSet} set
- * @returns {string}
- */
-export function formatRedirectSetReport(set) {
-  const lines = [];
-  lines.push(
-    `== Redirect materialization == ${set.redirects.length} redirect(s), ${set.bytes}/${set.budget} bytes`,
-  );
-  for (const violation of set.violations) lines.push(`  REFUSE: ${violation}`);
-  lines.push(
-    set.ok
-      ? `OK — every declared redirect materializes at ${REDIRECT_STATUS}.`
-      : `REFUSED — ${set.violations.length} violation(s); nothing emitted.`,
-  );
-  return lines.join("\n");
-}
+// The redirect contract — declaration format, edge budget, reference matcher — is the agency kit's
+// pure module, so a store developer validates a map with the kit alone and a publish applies the
+// same code. This subpath is how the platform imports it.
+export * from "../../../agency-kit/tools/lib/redirect-declaration.mjs";

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

@@ -169,7 +169,10 @@ export interface StaticBundleManifest {
   htmlCacheControl?: string;
   /** T6 classification: relPath -> {hash, kind}. Absent on a pre-T6 manifest — every lookup then falls back to the old versions/<digest>/<rel> key (see `resolveStaticBundleObjectKey`). */
   files?: Record<string, StaticBundleFileEntry>;
-  /** Exact, version-bound whole-site redirects materialized from content/redirects.json. */
+  /**
+   * Version-bound whole-site redirects materialized from content/redirects.json: exact paths and
+   * `/<dir>/*` rules (see `publication-redirects.mjs` for the declaration contract).
+   */
   redirects?: Array<{ from: string; to: string }>;
 }
 
@@ -179,6 +182,50 @@ function isManifestRedirectPath(value: string): boolean {
     !value.split("/").includes("..");
 }
 
+/** A `/<dir>/*` rule (or rule target): `*` only as the whole last segment. */
+function isManifestRedirectRule(value: string): boolean {
+  return value.endsWith("/*") && value.indexOf("*") === value.length - 1 &&
+    isManifestRedirectPath(value.slice(0, -1));
+}
+
+/**
+ * Where a rule sends a request whose path continues `capture` past the rule's directory; null
+ * unless the result is a same-origin path. Same semantics as `ruleLocation` in
+ * `publication-redirects.mjs` and the CloudFront function — the three are held together by
+ * `tests/fixtures/redirect-match-cases.json`.
+ */
+function ruleLocation(to: string, capture: string): string | null {
+  const location = to.endsWith("/*") ? `${to.slice(0, -1)}${capture}` : to;
+  return location.startsWith("/") && !location.startsWith("//") && !location.includes("\\")
+    ? location
+    : null;
+}
+
+/**
+ * The redirect the manifest declares for `pathname`, as a location, or null. An exact entry wins
+ * outright; otherwise the rule with the longest directory that the trailing-slash form of the path
+ * starts with decides — and when its location is unusable there is no redirect.
+ */
+function staticBundleRedirectLocation(
+  redirects: StaticBundleManifest["redirects"],
+  pathname: string,
+): string | null {
+  if (!redirects?.length) return null;
+  const path = pathname === "/" || pathname.split("/").pop()?.includes(".")
+    ? pathname
+    : pathname.endsWith("/") ? pathname : `${pathname}/`;
+  let rule: { from: string; to: string } | null = null;
+  for (const redirect of redirects) {
+    if (redirect.from.endsWith("/*")) {
+      const dir = redirect.from.slice(0, -1);
+      if (path.startsWith(dir) && (rule === null || dir.length > rule.from.length - 1)) rule = redirect;
+    } else if (redirect.from === pathname || redirect.from === path) {
+      return redirect.to;
+    }
+  }
+  return rule === null ? null : ruleLocation(rule.to, path.slice(rule.from.length - 1));
+}
+
 function isManifestRedirectDestination(value: string): boolean {
   if (isManifestRedirectPath(value)) return true;
   try {
@@ -219,9 +266,13 @@ function parseManifest(raw: string): StaticBundleManifest | null {
       redirects = [];
       for (const value of m.redirects) {
         const redirect = value as { from?: unknown; to?: unknown };
-        if (!redirect || typeof redirect.from !== "string" || typeof redirect.to !== "string" ||
-            !isManifestRedirectPath(redirect.from) ||
-            !isManifestRedirectDestination(redirect.to)) return null;
+        if (!redirect || typeof redirect.from !== "string" || typeof redirect.to !== "string") return null;
+        const valid = isManifestRedirectRule(redirect.from)
+          ? redirect.from !== "/*" && (isManifestRedirectRule(redirect.to) ||
+            (!redirect.to.includes("*") && isManifestRedirectPath(redirect.to)))
+          : !redirect.from.includes("*") && isManifestRedirectPath(redirect.from) &&
+            !redirect.to.includes("*") && isManifestRedirectDestination(redirect.to);
+        if (!valid) return null;
         redirects.push({ from: redirect.from, to: redirect.to });
       }
     }
@@ -426,15 +477,12 @@ export async function serveStaticBundle(
     return failClosed(deps, `missing/unreadable manifest for digest ${digest}`);
   }
 
-  const redirectPath = pathname === "/" || pathname.split("/").pop()?.includes(".")
-    ? pathname
-    : pathname.endsWith("/") ? pathname : `${pathname}/`;
-  const redirect = manifest.redirects?.find(({ from }) => from === pathname || from === redirectPath);
-  if (redirect) {
-    const query = redirect.to.startsWith("/") ? search : "";
+  const redirectTo = staticBundleRedirectLocation(manifest.redirects, pathname);
+  if (redirectTo !== null) {
+    const query = redirectTo.startsWith("/") ? search : "";
     return new Response(null, {
       status: 308,
-      headers: { location: `${redirect.to}${query}`, "cache-control": "public, max-age=300" },
+      headers: { location: `${redirectTo}${query}`, "cache-control": "public, max-age=300" },
     });
   }
 

package/packages/public-runtime/tests/fixtures/redirect-match-cases.json

@@ -0,0 +1,34 @@
+{
+  "description": "One redirect set and the location every edge must answer for each request path. Run against the reference matcher (publication-redirects.mjs resolveRedirect), the Cloudflare static plane (static-bundle.ts serveStaticBundle) and the CloudFront viewer function (live-pointer-rewrite.mjs). null means no redirect.",
+  "redirects": [
+    { "from": "/blogs/*", "to": "/blog/" },
+    { "from": "/blogs/news/*", "to": "/blog/*" },
+    { "from": "/blogs/news/special/", "to": "/blog/featured/" },
+    { "from": "/collections/*", "to": "/shop/" },
+    { "from": "/my-account/", "to": "https://app.example.com/signin" },
+    { "from": "/pages/*", "to": "/*" },
+    { "from": "/sitemap_index.xml", "to": "/sitemap.xml" }
+  ],
+  "cases": [
+    { "path": "/blogs/news/hello", "location": "/blog/hello/" },
+    { "path": "/blogs/news/hello/", "location": "/blog/hello/" },
+    { "path": "/blogs/news/", "location": "/blog/" },
+    { "path": "/blogs/news", "location": "/blog/" },
+    { "path": "/blogs/news/feed.atom", "location": "/blog/feed.atom" },
+    { "path": "/blogs/news/special/", "location": "/blog/featured/" },
+    { "path": "/blogs/news/special", "location": "/blog/featured/" },
+    { "path": "/blogs/other/post/", "location": "/blog/" },
+    { "path": "/blogs/", "location": "/blog/" },
+    { "path": "/pages/about", "location": "/about/" },
+    { "path": "/pages/policies/terms/", "location": "/policies/terms/" },
+    { "path": "/pages//evil.example/", "location": null },
+    { "path": "/collections/vapes/", "location": "/shop/" },
+    { "path": "/collections/vapes/products/x", "location": "/shop/" },
+    { "path": "/sitemap_index.xml", "location": "/sitemap.xml" },
+    { "path": "/my-account", "location": "https://app.example.com/signin" },
+    { "path": "/blog/hello/", "location": null },
+    { "path": "/blogsx/", "location": null },
+    { "path": "/pages.html", "location": null },
+    { "path": "/", "location": null }
+  ]
+}