@tokenoftrust/storefront-runner 2.4.23 → 2.4.25

package/packages/public-runtime/src/publication-reader.ts

@@ -1,12 +1,13 @@
 import {
-  publicationArtifactBundleKeyV1,
-  publicationArtifactFileBytesV1,
-  publicationArtifactKeyV1,
-  validatePublicationArtifactBundleV1,
-  type PublicationArtifactBundleV1,
-  type PublicationArtifactFileV1,
+  readPublicationArtifactFileV1,
+  readPublicationArtifactIndexV1,
+  type PublicationArtifactIndexFileV1,
+  type PublicationArtifactIndexV1,
+  type PublicationArtifactReadBucketV1,
+  type PublicationArtifactStoredObjectV1,
 } from "./publication-artifact.js";
 import {
+  resolvePublicationRoutePlanV1,
   selectPublicationRouteVersionV1,
   type PublicationRouteFailureCodeV1,
   type PublicationRoutePlanV1,
@@ -18,15 +19,10 @@ import type {
 } from "./publication-version.js";
 import type { RouteTierIndexV1 } from "./route-tier.js";
 
-export interface PublicationStoredObjectV1 {
-  text(): Promise<string>;
-  arrayBuffer(): Promise<ArrayBuffer>;
-}
+export type PublicationStoredObjectV1 = PublicationArtifactStoredObjectV1;
 
 /** Provider-neutral object-store read surface; R2 and test stores both satisfy it. */
-export interface PublicationArtifactBucketV1 {
-  get(key: string): Promise<PublicationStoredObjectV1 | null>;
-}
+export type PublicationArtifactBucketV1 = PublicationArtifactReadBucketV1;
 
 export type PublicationArtifactOpenFailureCodeV1 =
   | PublicationRouteFailureCodeV1
@@ -38,13 +34,17 @@ export type PublicationArtifactOpenFailureCodeV1 =
 
 export interface OpenPublicationArtifactV1 {
   selection: SelectedPublicationRouteV1;
-  bundle: PublicationArtifactBundleV1;
+  /** The admitted file index of the selected version. */
+  index: PublicationArtifactIndexV1;
   /** Read a UTF-8 artifact relative to the selected space's content/ root. */
   readContent(relativePath: string): string | null;
   /** List paths relative to the selected space's content/ root. */
   listContentPaths(prefix?: string): string[];
-  /** Read bytes relative to this space's declared asset namespace. */
-  readAsset(relativePath: string): Uint8Array | null;
+  /**
+   * Read bytes relative to this space's declared asset namespace. Fetched on demand and proven
+   * against the index, so opening a version never reads its assets.
+   */
+  readAsset(relativePath: string): Promise<Uint8Array | null>;
 }
 
 export type OpenPublicationArtifactResultV1 =
@@ -57,11 +57,6 @@ function safeRelativePath(path: string, allowEmpty = false): boolean {
     path.split("/").every((part) => !!part && part !== "." && part !== "..");
 }
 
-function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
-  return left.byteLength === right.byteLength &&
-    left.every((value, index) => value === right[index]);
-}
-
 /**
  * Open exactly one selected publication version and validate every physical
  * object before rendering from it. A route/state/provenance/object failure is
@@ -91,25 +86,7 @@ async function openSelectedPublicationArtifactV1(
   bucket: PublicationArtifactBucketV1,
 ): Promise<OpenPublicationArtifactResultV1> {
   const { manifest, publicationVersion } = selection;
-  let marker: PublicationStoredObjectV1 | null;
-  try {
-    marker = await bucket.get(publicationArtifactBundleKeyV1(
-      manifest.tenant,
-      manifest.id,
-      publicationVersion.versionId,
-    ));
-  } catch {
-    return { ok: false, code: "publication_artifact_source_unavailable" };
-  }
-  if (!marker) return { ok: false, code: "publication_artifact_marker_missing" };
-
-  let markerValue: unknown;
-  try {
-    markerValue = JSON.parse(await marker.text());
-  } catch {
-    return { ok: false, code: "publication_artifact_marker_malformed" };
-  }
-  const checked = await validatePublicationArtifactBundleV1(markerValue, {
+  const admitted = await readPublicationArtifactIndexV1(bucket, {
     tenant: manifest.tenant,
     spaceId: manifest.id,
     versionId: publicationVersion.versionId,
@@ -121,55 +98,38 @@ async function openSelectedPublicationArtifactV1(
     assetNamespace: manifest.assets.namespace,
     assetAccess: manifest.assets.access,
   });
-  if (!checked.ok) return { ok: false, code: "publication_artifact_marker_malformed" };
+  if (!admitted.ok) return { ok: false, code: admitted.code };
+  const { index } = admitted;
 
-  const physical = new Map<string, Uint8Array>();
-  for (const file of checked.value.files) {
-    const expected = publicationArtifactFileBytesV1(file);
-    if (!expected) return { ok: false, code: "publication_artifact_marker_malformed" };
-    let stored: PublicationStoredObjectV1 | null;
-    try {
-      stored = await bucket.get(publicationArtifactKeyV1(
-        manifest.tenant,
-        manifest.id,
-        publicationVersion.versionId,
-        file.lane,
-        file.path,
-      ));
-    } catch {
-      return { ok: false, code: "publication_artifact_source_unavailable" };
-    }
-    if (!stored) return { ok: false, code: "publication_artifact_file_missing" };
-    let actual: Uint8Array;
+  // The renderer reads content synchronously, so the content lane is loaded and proven up front.
+  // Assets are not: a page never needs every image its space carries.
+  const contentFiles = index.files.filter(
+    (file): file is PublicationArtifactIndexFileV1 & { encoding: "utf8" } =>
+      file.lane === "content" && file.encoding === "utf8" && file.path.startsWith("content/"),
+  );
+  const content = new Map<string, string>();
+  for (const file of contentFiles) {
+    const read = await readPublicationArtifactFileV1(bucket, index, file);
+    if (!read.ok) return { ok: false, code: read.code };
     try {
-      actual = new Uint8Array(await stored.arrayBuffer());
+      content.set(file.path, new TextDecoder("utf-8", { fatal: true }).decode(read.bytes));
     } catch {
-      return { ok: false, code: "publication_artifact_file_missing" };
-    }
-    if (!equalBytes(actual, expected)) {
       return { ok: false, code: "publication_artifact_file_mismatch" };
     }
-    physical.set(`${file.lane}\0${file.path}`, actual);
   }
-
-  const contentFiles = checked.value.files.filter(
-    (file): file is PublicationArtifactFileV1 & { encoding: "utf8" } =>
-      file.lane === "content" && file.encoding === "utf8" && file.path.startsWith("content/"),
-  );
   const assetLane = manifest.assets.access === "public" ? "public-asset" : "authorized-asset";
   const assetPrefix = `${manifest.assets.namespace}/`;
+  const assets = new Map(index.files
+    .filter((file) => file.lane === assetLane && file.path.startsWith(assetPrefix))
+    .map((file) => [file.path.slice(assetPrefix.length), file]));
   return {
     ok: true,
     value: {
       selection,
-      bundle: checked.value,
+      index,
       readContent(relativePath) {
         if (!safeRelativePath(relativePath)) return null;
-        const path = `content/${relativePath}`;
-        const file = contentFiles.find((candidate) => candidate.path === path);
-        if (!file) return null;
-        const bytes = physical.get(`content\0${path}`);
-        return bytes ? new TextDecoder().decode(bytes) : null;
+        return content.get(`content/${relativePath}`) ?? null;
       },
       listContentPaths(prefix = "") {
         if (!safeRelativePath(prefix.replace(/\/$/, ""), true)) return [];
@@ -178,10 +138,62 @@ async function openSelectedPublicationArtifactV1(
           .filter((path) => path.startsWith(prefix))
           .sort();
       },
-      readAsset(relativePath) {
+      async readAsset(relativePath) {
         if (!safeRelativePath(relativePath)) return null;
-        return physical.get(`${assetLane}\0${assetPrefix}${relativePath}`) ?? null;
+        const file = assets.get(relativePath);
+        if (!file) return null;
+        const read = await readPublicationArtifactFileV1(bucket, index, file);
+        return read.ok ? read.bytes : null;
       },
     },
   };
 }
+
+export type PublicationRootAssetReadV1 =
+  | { status: "legacy-root" }
+  | { status: "found"; bytes: Uint8Array; sha256: string }
+  | { status: "absent" };
+
+/**
+ * One file of the ROOT space's public asset lane, by its path under the namespace — what a
+ * whole-site tenant serves at `/tenants/<tenant>/<path>`. Reads the selected version's index and
+ * that one object, never the content lane. `legacy-root` when the tenant's root is not a public
+ * publication space this channel selected, so the legacy asset pointer still answers.
+ */
+export async function readPublicationRootAssetV1(input: {
+  index: RouteTierIndexV1;
+  state: PublicationVersionStateV1;
+  channel: PublicationChannelV1;
+  bucket: PublicationArtifactBucketV1;
+  relativePath: string;
+}): Promise<PublicationRootAssetReadV1> {
+  const plan = resolvePublicationRoutePlanV1(input.index, "/");
+  if (plan.action !== "render" || plan.manifest.routes.canonicalMount !== "/" ||
+    plan.manifest.visibility !== "public" || plan.manifest.assets.access !== "public") {
+    return { status: "legacy-root" };
+  }
+  const selected = selectPublicationRouteVersionV1(input.index, "/", plan, input.state, input.channel);
+  if (!selected.ok) {
+    return selected.code === "publication_channel_unselected" ? { status: "legacy-root" } : { status: "absent" };
+  }
+  if (!safeRelativePath(input.relativePath)) return { status: "absent" };
+  const { manifest, publicationVersion } = selected.value;
+  const admitted = await readPublicationArtifactIndexV1(input.bucket, {
+    tenant: manifest.tenant,
+    spaceId: manifest.id,
+    versionId: publicationVersion.versionId,
+    sourceSha: publicationVersion.source.commitSha,
+    artifactDigest: publicationVersion.artifactDigest,
+    forge: manifest.source.forge,
+    repo: manifest.source.repo,
+    visibility: manifest.visibility,
+    assetNamespace: manifest.assets.namespace,
+    assetAccess: manifest.assets.access,
+  });
+  if (!admitted.ok) return { status: "absent" };
+  const path = `${manifest.assets.namespace}/${input.relativePath}`;
+  const row = admitted.index.files.find((file) => file.lane === "public-asset" && file.path === path);
+  if (!row) return { status: "absent" };
+  const read = await readPublicationArtifactFileV1(input.bucket, admitted.index, row);
+  return read.ok ? { status: "found", bytes: read.bytes, sha256: row.sha256 } : { status: "absent" };
+}

package/packages/public-runtime/src/publication-routing.ts

@@ -22,6 +22,7 @@ import {
   type RouteTierIndexV1,
 } from "./route-tier.js";
 import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+import { publicationCollectionOfV1 } from "./blog-visibility.mjs";
 
 export const PUBLICATION_ROUTE_PLAN_VERSION = 1 as const;
 
@@ -42,8 +43,14 @@ export interface PublicationRouteRenderPlanV1 {
   requestPath: string;
   /** Route relative to the selected publication source. Always absolute. */
   contentPath: string;
-  /** Canonical tenant-relative route used by links and Astro dispatch. */
+  /** Canonical tenant-relative route used by links. */
   canonicalPath: string;
+  /**
+   * The platform route Astro dispatches: a path in one of the space's declared collections maps
+   * to that collection's platform route (`/blog/...`, `/the-build/...`), whatever its base inside
+   * the mount; any other path dispatches at its canonical path.
+   */
+  renderPath: string;
   assetNamespace: string;
 }
 
@@ -91,6 +98,12 @@ function appendSuffix(mount: string, suffix: string): string {
   return `${mount}${suffix}`;
 }
 
+/** The platform collection route for a mount-relative path, or null when it is in no collection. */
+function collectionRenderPath(manifest: PublicationSpaceManifestV1, contentPath: string): string | null {
+  const match = publicationCollectionOfV1(manifest, contentPath);
+  return match ? `/${match.collection}${match.rest}` : null;
+}
+
 /** Resolve one request through the already-compiled tenant mount authority. */
 export function resolvePublicationRoutePlanV1(
   index: RouteTierIndexV1,
@@ -143,6 +156,7 @@ export function resolvePublicationRoutePlanV1(
     requestPath: route.path,
     contentPath: suffix || "/",
     canonicalPath: appendSuffix(mount.canonicalMount, suffix),
+    renderPath: collectionRenderPath(manifest, suffix || "/") ?? appendSuffix(mount.canonicalMount, suffix),
     assetNamespace: manifest.assets.namespace,
   };
 }

package/packages/public-runtime/src/publication-space.ts

@@ -6,6 +6,13 @@
  * normalized mounts emitted here rather than decode or canonicalize paths again.
  */
 import type { TenantConfig } from "./tenant.js";
+import {
+  isPublicationCollectionBaseV1,
+  PUBLICATION_COLLECTIONS_V1,
+  publicationCollectionBaseV1,
+  type PublicationCollectionV1,
+} from "./blog-visibility.mjs";
+import { normalizeRedirectPath } from "./publication-redirects.mjs";
 import {
   ANNOTATION_KEYS,
   type ContractResult,
@@ -107,6 +114,14 @@ export interface PublicationSpaceAliasV1 {
   to?: string;
 }
 
+/** One exact path the root space sends to another origin. */
+export interface PublicationSpaceExternalRedirectV1 {
+  /** Normalized exact request path (`/my-account/`), never a rule. */
+  from: string;
+  /** Absolute `https:` destination without credentials, query, or fragment. */
+  to: string;
+}
+
 export interface PublicationSpaceManifestV1 {
   version: typeof PUBLICATION_SPACE_MANIFEST_VERSION;
   id: string;
@@ -115,6 +130,17 @@ export interface PublicationSpaceManifestV1 {
   routes: {
     canonicalMount: string;
     aliases?: PublicationSpaceAliasV1[];
+    /**
+     * Base path of each post collection inside the mount. Absent means the collection's own name
+     * (`blog`, `the-build`); `""` serves it at the mount root. Every collection URL is built from
+     * it by `publicationCollectionPathV1`.
+     */
+    collections?: Partial<Record<PublicationCollectionV1, string>>;
+    /**
+     * Exact paths sent off the site, as a whole-site publish does. Only the ROOT space may declare
+     * them: a mounted space owns only its mount, and its redirects stay on the tenant's origin.
+     */
+    externalRedirects?: PublicationSpaceExternalRedirectV1[];
   };
   visibility: PublicationSpaceVisibilityV1;
   authorization:
@@ -450,6 +476,100 @@ function validateRenderer(
   return contractVersion && themeContractVersion ? { contractVersion, themeContractVersion } : undefined;
 }
 
+/**
+ * A space's declared collection bases: known collections only, each `""` or lowercase segments,
+ * no two collections sharing a base, and none at the site root (the root space's home owns `/`).
+ */
+function validateCollections(
+  raw: unknown,
+  canonicalMount: string | undefined,
+  v: Violations,
+  path: string,
+): PublicationSpaceManifestV1["routes"]["collections"] {
+  if (raw === undefined) return undefined;
+  const collections = reqObject(raw, v, path);
+  if (!collections) return undefined;
+  rejectPublicationUnknownKeys(collections, [...PUBLICATION_COLLECTIONS_V1], v, path);
+  const out: Partial<Record<PublicationCollectionV1, string>> = {};
+  for (const collection of PUBLICATION_COLLECTIONS_V1) {
+    const value = collections[collection];
+    if (value === undefined) continue;
+    if (!isPublicationCollectionBaseV1(value)) {
+      v.add(`${path}.${collection}`, "publication_collection_base_malformed",
+        "A collection base is empty (the mount root) or lowercase path segments.");
+      continue;
+    }
+    if (value === "" && canonicalMount === "/") {
+      v.add(`${path}.${collection}`, "publication_collection_at_site_root",
+        "A collection cannot take the site root; the root space's home serves it.");
+      continue;
+    }
+    out[collection] = value;
+  }
+  const bases = PUBLICATION_COLLECTIONS_V1.map((collection) => publicationCollectionBaseV1({ routes: { collections: out } },
+    collection));
+  if (new Set(bases).size !== bases.length) {
+    v.add(path, "publication_collection_base_conflict", "Two collections cannot share a base path.");
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function isExternalDestination(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash &&
+      url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "") === value;
+  } catch {
+    return false;
+  }
+}
+
+/** The root space's exact off-site redirects; a mounted space declaring any is refused. */
+function validateExternalRedirects(
+  raw: unknown,
+  canonicalMount: string | undefined,
+  v: Violations,
+  path: string,
+): PublicationSpaceExternalRedirectV1[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    v.add(path, "type", "Expected externalRedirects to be an array.");
+    return undefined;
+  }
+  if (canonicalMount !== undefined && canonicalMount !== "/") {
+    v.add(path, "publication_external_redirect_on_mount",
+      "Only the root space may redirect off the site; a mounted space owns only its mount.");
+  }
+  const out: PublicationSpaceExternalRedirectV1[] = [];
+  const seen = new Set<string>();
+  raw.forEach((item, index) => {
+    const at = `${path}[${index}]`;
+    const entry = reqObject(item, v, at);
+    if (!entry) return;
+    rejectPublicationUnknownKeys(entry, ["from", "to"], v, at);
+    const from = reqString(entry, "from", v, at);
+    const to = reqString(entry, "to", v, at);
+    if (from !== undefined && (normalizeRedirectPath(from) !== from || from === "/")) {
+      v.add(`${at}.from`, "publication_external_redirect_source",
+        "An off-site redirect source is one normalized exact path, never the site root or a rule.");
+      return;
+    }
+    if (to !== undefined && !isExternalDestination(to)) {
+      v.add(`${at}.to`, "publication_external_redirect_target",
+        "An off-site redirect target is an absolute https URL without credentials, query, or fragment.");
+      return;
+    }
+    if (from === undefined || to === undefined) return;
+    if (seen.has(from)) {
+      v.add(`${at}.from`, "publication_external_redirect_duplicate", "An off-site redirect source is declared twice.");
+      return;
+    }
+    seen.add(from);
+    out.push({ from, to });
+  });
+  return out.length ? out.sort((left, right) => left.from < right.from ? -1 : left.from > right.from ? 1 : 0) : undefined;
+}
+
 /** Validate, close, and normalize one serialized publication-space manifest. */
 export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult<PublicationSpaceManifestV1> {
   const v = new Violations();
@@ -468,8 +588,11 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
   const routes = reqObject(root["routes"], v, "routes");
   let canonicalMount: string | undefined;
   let aliases: PublicationSpaceAliasV1[] | undefined;
+  let collections: PublicationSpaceManifestV1["routes"]["collections"];
+  let externalRedirects: PublicationSpaceExternalRedirectV1[] | undefined;
   if (routes) {
-    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases"], v, "routes");
+    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases", "collections", "externalRedirects"], v,
+      "routes");
     const rawMount = reqString(routes, "canonicalMount", v, "routes");
     canonicalMount = rawMount
       ? append(v, "routes.canonicalMount", normalizePublicationPath(rawMount, { mode: "mount" }))
@@ -478,6 +601,9 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
       v.add("routes.canonicalMount", "publication_reserved_mount", "Canonical mount is platform-reserved.");
     }
     aliases = validateAliases(routes["aliases"], canonicalMount, v, "routes.aliases");
+    collections = validateCollections(routes["collections"], canonicalMount, v, "routes.collections");
+    externalRedirects = validateExternalRedirects(routes["externalRedirects"], canonicalMount, v,
+      "routes.externalRedirects");
   }
   const visibility = reqEnum<PublicationSpaceVisibilityV1>(root, "visibility", ["public", "internal"], v, "");
   const authorization = validateAuthorization(root["authorization"], v, "authorization");
@@ -525,7 +651,12 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
       id,
       tenant,
       source,
-      routes: aliases === undefined ? { canonicalMount } : { canonicalMount, aliases },
+      routes: {
+        canonicalMount,
+        ...(aliases === undefined ? {} : { aliases }),
+        ...(collections === undefined ? {} : { collections }),
+        ...(externalRedirects === undefined ? {} : { externalRedirects }),
+      },
       visibility,
       authorization,
       discovery,
@@ -787,6 +918,18 @@ export function validatePublicationSpaceRegistryV1(
       );
     }
   }
+  // Precedence: a mount owns every path under it. An alias one space declares inside ANOTHER
+  // space's mount (the root's `/blog/page` once a space is mounted at `/blog`) is refused, so no
+  // route-tier or edge redirect can shadow the mounted space's own pages.
+  for (const alias of entries.filter((entry) => entry.kind === "alias")) {
+    const owner = entries.find((entry) => entry.kind === "canonical" && entry.tenant === alias.tenant &&
+      entry.spaceId !== alias.spaceId && entry.mount !== "/" &&
+      (alias.mount === entry.mount || alias.mount.startsWith(`${entry.mount}/`)));
+    if (owner) {
+      addRegistryViolation(violations, `spaces.${alias.spaceId}.routes.aliases`, "publication_alias_under_mount",
+        `Alias ${alias.mount} lies under the mount ${owner.mount} that space ${owner.spaceId} owns.`);
+    }
+  }
   detectAliasLoops(entries, violations);
   if (violations.length > 0) return { ok: false, violations };