@tokenoftrust/storefront-runner 2.0.18 → 2.0.19

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

@@ -0,0 +1,187 @@
+import {
+  publicationArtifactBundleKeyV1,
+  publicationArtifactFileBytesV1,
+  publicationArtifactKeyV1,
+  validatePublicationArtifactBundleV1,
+  type PublicationArtifactBundleV1,
+  type PublicationArtifactFileV1,
+} from "./publication-artifact.js";
+import {
+  selectPublicationRouteVersionV1,
+  type PublicationRouteFailureCodeV1,
+  type PublicationRoutePlanV1,
+  type SelectedPublicationRouteV1,
+} from "./publication-routing.js";
+import type {
+  PublicationChannelV1,
+  PublicationVersionStateV1,
+} from "./publication-version.js";
+import type { RouteTierIndexV1 } from "./route-tier.js";
+
+export interface PublicationStoredObjectV1 {
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+
+/** Provider-neutral object-store read surface; R2 and test stores both satisfy it. */
+export interface PublicationArtifactBucketV1 {
+  get(key: string): Promise<PublicationStoredObjectV1 | null>;
+}
+
+export type PublicationArtifactOpenFailureCodeV1 =
+  | PublicationRouteFailureCodeV1
+  | "publication_artifact_marker_missing"
+  | "publication_artifact_marker_malformed"
+  | "publication_artifact_file_missing"
+  | "publication_artifact_file_mismatch"
+  | "publication_artifact_source_unavailable";
+
+export interface OpenPublicationArtifactV1 {
+  selection: SelectedPublicationRouteV1;
+  bundle: PublicationArtifactBundleV1;
+  /** 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;
+}
+
+export type OpenPublicationArtifactResultV1 =
+  | { ok: true; value: OpenPublicationArtifactV1 }
+  | { ok: false; code: PublicationArtifactOpenFailureCodeV1 };
+
+function safeRelativePath(path: string, allowEmpty = false): boolean {
+  if (path === "") return allowEmpty;
+  return !path.startsWith("/") && !path.includes("\\") && !path.includes("\0") &&
+    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
+ * terminal for this source; callers must not fall through to another space.
+ */
+export async function openPublicationArtifactV1(input: {
+  index: RouteTierIndexV1;
+  requestPath: string;
+  plan: PublicationRoutePlanV1;
+  state: PublicationVersionStateV1;
+  channel: PublicationChannelV1;
+  bucket: PublicationArtifactBucketV1;
+}): Promise<OpenPublicationArtifactResultV1> {
+  const selected = selectPublicationRouteVersionV1(
+    input.index,
+    input.requestPath,
+    input.plan,
+    input.state,
+    input.channel,
+  );
+  if (!selected.ok) return { ok: false, code: selected.code };
+  return openSelectedPublicationArtifactV1(selected.value, input.bucket);
+}
+
+async function openSelectedPublicationArtifactV1(
+  selection: SelectedPublicationRouteV1,
+  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, {
+    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 (!checked.ok) return { ok: false, code: "publication_artifact_marker_malformed" };
+
+  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;
+    try {
+      actual = new Uint8Array(await stored.arrayBuffer());
+    } 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}/`;
+  return {
+    ok: true,
+    value: {
+      selection,
+      bundle: checked.value,
+      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;
+      },
+      listContentPaths(prefix = "") {
+        if (!safeRelativePath(prefix.replace(/\/$/, ""), true)) return [];
+        return contentFiles
+          .map((file) => file.path.slice("content/".length))
+          .filter((path) => path.startsWith(prefix))
+          .sort();
+      },
+      readAsset(relativePath) {
+        if (!safeRelativePath(relativePath)) return null;
+        return physical.get(`${assetLane}\0${assetPrefix}${relativePath}`) ?? null;
+      },
+    },
+  };
+}

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

@@ -0,0 +1,246 @@
+/**
+ * One publication request plan: normalized mount resolution, canonical route,
+ * content lookup path, and independently selected immutable version.
+ *
+ * The route-tier resolver owns normalization and longest-prefix matching. This
+ * module consumes that answer without decoding or canonicalizing the request a
+ * second time, so request routing, preview, static materialization, and canonical
+ * URL generation cannot disagree about which publication space owns a path.
+ */
+import type { ContractViolation } from "./integration/result.js";
+import {
+  resolvePublicationChannelVersionV1,
+  validatePublicationVersionStateV1,
+  type PublicationChannelPointerV1,
+  type PublicationChannelV1,
+  type PublicationVersionStateV1,
+  type PublicationVersionV1,
+} from "./publication-version.js";
+import {
+  resolveRouteTierV1,
+  type ResolvedRouteTierV1,
+  type RouteTierIndexV1,
+} from "./route-tier.js";
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+
+export const PUBLICATION_ROUTE_PLAN_VERSION = 1 as const;
+
+export type PublicationRouteFailureCodeV1 =
+  | "publication_route_unresolved"
+  | "publication_route_authority_mismatch"
+  | "publication_state_malformed"
+  | "publication_channel_unselected"
+  | "publication_version_provenance_mismatch"
+  | "publication_renderer_contract_mismatch";
+
+export interface PublicationRouteRenderPlanV1 {
+  version: typeof PUBLICATION_ROUTE_PLAN_VERSION;
+  action: "render";
+  route: ResolvedRouteTierV1;
+  manifest: PublicationSpaceManifestV1;
+  /** Normalized route as requested, with the matched mount still attached. */
+  requestPath: string;
+  /** Route relative to the selected publication source. Always absolute. */
+  contentPath: string;
+  /** Canonical tenant-relative route used by links and Astro dispatch. */
+  canonicalPath: string;
+  assetNamespace: string;
+}
+
+export interface PublicationRouteRedirectPlanV1 {
+  version: typeof PUBLICATION_ROUTE_PLAN_VERSION;
+  action: "redirect-308";
+  route: ResolvedRouteTierV1;
+  manifest: PublicationSpaceManifestV1;
+  requestPath: string;
+  /** Canonical tenant-relative redirect target, including the unmatched suffix. */
+  locationPath: string;
+}
+
+export interface PublicationRouteFailedPlanV1 {
+  version: typeof PUBLICATION_ROUTE_PLAN_VERSION;
+  action: "fail-closed";
+  route: ResolvedRouteTierV1;
+  code: "publication_route_unresolved";
+  violations: readonly ContractViolation[];
+}
+
+export type PublicationRoutePlanV1 =
+  | PublicationRouteRenderPlanV1
+  | PublicationRouteRedirectPlanV1
+  | PublicationRouteFailedPlanV1;
+
+export interface SelectedPublicationRouteV1 extends PublicationRouteRenderPlanV1 {
+  channel: PublicationChannelV1;
+  pointer: PublicationChannelPointerV1;
+  publicationVersion: PublicationVersionV1;
+}
+
+export type PublicationRouteSelectionV1 =
+  | { ok: true; value: SelectedPublicationRouteV1 }
+  | { ok: false; code: PublicationRouteFailureCodeV1; plan: PublicationRoutePlanV1 };
+
+function suffixAfterMount(path: string, mount: string): string {
+  if (mount === "/") return path === "/" ? "" : path;
+  return path === mount ? "" : path.slice(mount.length);
+}
+
+function appendSuffix(mount: string, suffix: string): string {
+  if (!suffix) return mount;
+  if (mount === "/") return suffix;
+  return `${mount}${suffix}`;
+}
+
+/** Resolve one request through the already-compiled tenant mount authority. */
+export function resolvePublicationRoutePlanV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+): PublicationRoutePlanV1 {
+  const route = resolveRouteTierV1(index, requestPath);
+  const mount = route.mount;
+  const spaceId = route.space?.spaceId;
+  const manifest = spaceId ? index.spaces.get(spaceId) : undefined;
+  if (route.origin !== "publication-space" || !mount || !manifest) {
+    return {
+      version: PUBLICATION_ROUTE_PLAN_VERSION,
+      action: "fail-closed",
+      route,
+      code: "publication_route_unresolved",
+      violations: route.violations,
+    };
+  }
+
+  const suffix = suffixAfterMount(route.path, mount.mount);
+  if (mount.behavior === "redirect-308") {
+    if (!mount.redirectTo) {
+      return {
+        version: PUBLICATION_ROUTE_PLAN_VERSION,
+        action: "fail-closed",
+        route,
+        code: "publication_route_unresolved",
+        violations: [{
+          path: "mount.redirectTo",
+          code: "publication_redirect_target_required",
+          message: "A redirect publication mount must have a canonical target.",
+        }],
+      };
+    }
+    return {
+      version: PUBLICATION_ROUTE_PLAN_VERSION,
+      action: "redirect-308",
+      route,
+      manifest,
+      requestPath: route.path,
+      locationPath: appendSuffix(mount.redirectTo, suffix),
+    };
+  }
+
+  return {
+    version: PUBLICATION_ROUTE_PLAN_VERSION,
+    action: "render",
+    route,
+    manifest,
+    requestPath: route.path,
+    contentPath: suffix || "/",
+    canonicalPath: appendSuffix(mount.canonicalMount, suffix),
+    assetNamespace: manifest.assets.namespace,
+  };
+}
+
+/**
+ * Prove a carried plan still describes the current registry and request. This
+ * check must run before pointer or artifact I/O whenever a plan crosses a seam.
+ */
+export function publicationRoutePlanIsCurrentV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+  plan: PublicationRoutePlanV1,
+): boolean {
+  return JSON.stringify(resolvePublicationRoutePlanV1(index, requestPath)) === JSON.stringify(plan);
+}
+
+/**
+ * Bind a render plan to exactly one channel pointer and immutable version.
+ * Any malformed/missing/mismatched state fails closed; there is no root or
+ * tenant-wide fallback after a publication space has been selected.
+ */
+export function selectPublicationRouteVersionV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+  plan: PublicationRoutePlanV1,
+  stateRaw: PublicationVersionStateV1,
+  channel: PublicationChannelV1,
+): PublicationRouteSelectionV1 {
+  if (!publicationRoutePlanIsCurrentV1(index, requestPath, plan)) {
+    return { ok: false, code: "publication_route_authority_mismatch", plan };
+  }
+  if (plan.action !== "render") {
+    return { ok: false, code: "publication_route_unresolved", plan };
+  }
+  const checked = validatePublicationVersionStateV1(stateRaw);
+  if (!checked.ok) return { ok: false, code: "publication_state_malformed", plan };
+  const selected = resolvePublicationChannelVersionV1(
+    checked.value,
+    plan.manifest.tenant,
+    plan.manifest.id,
+    channel,
+  );
+  if (!selected) return { ok: false, code: "publication_channel_unselected", plan };
+  const { pointer, version } = selected;
+  if (
+    version.source.forge !== plan.manifest.source.forge ||
+    version.source.repo !== plan.manifest.source.repo ||
+    version.source.commitSha !== pointer.sourceSha
+  ) {
+    return { ok: false, code: "publication_version_provenance_mismatch", plan };
+  }
+  if (
+    version.renderer.contractVersion !== plan.manifest.renderer.contractVersion ||
+    version.renderer.themeContractVersion !== plan.manifest.renderer.themeContractVersion
+  ) {
+    return { ok: false, code: "publication_renderer_contract_mismatch", plan };
+  }
+  return {
+    ok: true,
+    value: {
+      ...plan,
+      channel,
+      pointer,
+      publicationVersion: version,
+    },
+  };
+}
+
+/** Build an absolute canonical URL without carrying query or fragment input. */
+export function publicationCanonicalUrlV1(
+  canonicalOrigin: string,
+  plan: Pick<PublicationRouteRenderPlanV1, "canonicalPath">,
+): string {
+  const origin = new URL(canonicalOrigin);
+  return new URL(plan.canonicalPath, `${origin.protocol}//${origin.host}`).toString();
+}
+
+/**
+ * Canonicalize a tenant-relative link through the same mount authority as a
+ * request. Queries/fragments are opaque suffixes; only the path is resolved.
+ * External, protocol-relative, reserved, and malformed routes fail closed.
+ */
+export function canonicalizePublicationLinkV1(
+  index: RouteTierIndexV1,
+  href: string,
+): string | null {
+  if (!href.startsWith("/") || href.startsWith("//")) return null;
+  const query = href.indexOf("?");
+  const fragment = href.indexOf("#");
+  const delimiter = query === -1
+    ? fragment
+    : fragment === -1
+      ? query
+      : Math.min(query, fragment);
+  const path = delimiter === -1 ? href : href.slice(0, delimiter);
+  const suffix = delimiter === -1 ? "" : href.slice(delimiter);
+  const plan = resolvePublicationRoutePlanV1(index, path);
+  if (plan.action === "fail-closed") return null;
+  const canonicalPath = plan.action === "render" ? plan.canonicalPath : plan.locationPath;
+  return `${canonicalPath}${suffix}`;
+}

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

@@ -390,6 +390,21 @@ export function serializePublicationTransitionRequestV1(value: PublicationTransi
   return serializeValidated(value, validatePublicationTransitionRequestV1, "PublicationTransitionRequestV1");
 }
 
+export function parsePublicationVersionStateV1Json(json: string): ContractResult<PublicationVersionStateV1> {
+  return parseJson(json, (raw) => validatePublicationVersionStateV1(raw as PublicationVersionStateV1));
+}
+export function serializePublicationVersionStateV1(value: PublicationVersionStateV1): string {
+  return serializeValidated(
+    value,
+    (raw) => validatePublicationVersionStateV1(raw as PublicationVersionStateV1),
+    "PublicationVersionStateV1",
+  );
+}
+/** Public read projection for one tenant's exact publication pointer state. */
+export function publicationVersionStateKey(tenant: string): string {
+  return `cust:publication-state:${tenant}`;
+}
+
 export function publicationVersionKey(tenant: string, spaceId: string, versionId: string): string {
   return `cust:publication-version:${tenant}:${spaceId}:${versionId}`;
 }