@tokenoftrust/storefront-runner 2.0.17 → 2.0.19

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

@@ -0,0 +1,220 @@
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+import { sha256Hex } from "./hash.js";
+
+const PUBLICATION_ARTIFACT_IDENTIFIER_RE = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+const PUBLICATION_ARTIFACT_VERSION_RE = /^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$/;
+
+/** Renderer-safe description of one immutable publication artifact file. */
+export interface PublicationArtifactFileV1 {
+  lane: "content" | "public-asset" | "authorized-asset";
+  path: string;
+  encoding: "utf8" | "base64";
+  content: string;
+  byteSize: number;
+}
+
+/** Renderer-safe marker for one complete tenant+space+version artifact set. */
+export interface PublicationArtifactBundleV1 {
+  tenant: string;
+  spaceId: string;
+  versionId: string;
+  sourceSha: string;
+  artifactDigest: string;
+  sourceLock: string;
+  visibility: PublicationSpaceManifestV1["visibility"];
+  assetNamespace: string;
+  assetAccess: PublicationSpaceManifestV1["assets"]["access"];
+  files: PublicationArtifactFileV1[];
+}
+
+export interface PublicationArtifactBundleExpectationV1 {
+  tenant: string;
+  spaceId: string;
+  versionId: string;
+  sourceSha: string;
+  artifactDigest: string;
+  forge: string;
+  repo: string;
+  visibility?: PublicationArtifactBundleV1["visibility"];
+  assetNamespace?: string;
+  assetAccess?: PublicationArtifactBundleV1["assetAccess"];
+}
+
+/** Locale-independent canonical order for immutable publication files. */
+export function comparePublicationArtifactFilesV1(
+  left: PublicationArtifactFileV1,
+  right: PublicationArtifactFileV1,
+): number {
+  const leftIdentity = `${left.lane}\0${left.path}`;
+  const rightIdentity = `${right.lane}\0${right.path}`;
+  return leftIdentity < rightIdentity ? -1 : leftIdentity > rightIdentity ? 1 : 0;
+}
+
+function safeArtifactPath(path: string): boolean {
+  return !!path && !path.startsWith("/") && !path.includes("\\") && !path.includes("\0") &&
+    path.split("/").every((part) => !!part && part !== "." && part !== "..");
+}
+
+function hasExactKeys(value: object, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function decodePublicationArtifactFileV1(file: PublicationArtifactFileV1): Uint8Array | null {
+  try {
+    if (file.encoding === "utf8") return new TextEncoder().encode(file.content);
+    if (file.encoding !== "base64" ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(file.content)) return null;
+    const binary = atob(file.content);
+    if (btoa(binary) !== file.content) return null;
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+
+function validPublicationArtifactFileV1(value: unknown): value is PublicationArtifactFileV1 {
+  if (!value || typeof value !== "object" || !hasExactKeys(value,
+    ["lane", "path", "encoding", "content", "byteSize"])) return false;
+  const file = value as PublicationArtifactFileV1;
+  return ["content", "public-asset", "authorized-asset"].includes(file.lane) &&
+    ["utf8", "base64"].includes(file.encoding) && typeof file.path === "string" &&
+    safeArtifactPath(file.path) && typeof file.content === "string" &&
+    Number.isSafeInteger(file.byteSize) && file.byteSize >= 0;
+}
+
+/** Decode one canonical portable artifact file while enforcing its declared byte length. */
+export function publicationArtifactFileBytesV1(file: PublicationArtifactFileV1): Uint8Array | null {
+  if (!validPublicationArtifactFileV1(file)) return null;
+  try {
+    const decoded = decodePublicationArtifactFileV1(file);
+    if (!decoded) return null;
+    return decoded.byteLength === file.byteSize ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Canonical marker admission shared by the writer-side activation gate and the
+ * renderer. It validates shape, identity, source provenance/lock, and recomputes
+ * the complete file-list digest; a marker cannot define its own admission facts.
+ */
+export async function validatePublicationArtifactBundleV1(
+  value: unknown,
+  expected: PublicationArtifactBundleExpectationV1,
+): Promise<{ ok: true; value: PublicationArtifactBundleV1 } | { ok: false }> {
+  if (!value || typeof value !== "object") return { ok: false };
+  const bundle = value as PublicationArtifactBundleV1;
+  if (!hasExactKeys(bundle, ["tenant", "spaceId", "versionId", "sourceSha", "artifactDigest",
+    "sourceLock", "visibility", "assetNamespace", "assetAccess", "files"]) ||
+    bundle.tenant !== expected.tenant || bundle.spaceId !== expected.spaceId ||
+    bundle.versionId !== expected.versionId || bundle.sourceSha !== expected.sourceSha ||
+    !/^[0-9a-f]{40}$/.test(bundle.sourceSha) || bundle.artifactDigest !== expected.artifactDigest ||
+    !/^[0-9a-f]{64}$/.test(bundle.artifactDigest) || typeof bundle.sourceLock !== "string" ||
+    !/^[0-9a-f]{64}$/.test(bundle.sourceLock) ||
+    !["public", "internal"].includes(bundle.visibility) || typeof bundle.assetNamespace !== "string" ||
+    !bundle.assetNamespace ||
+    !["public", "authorized"].includes(bundle.assetAccess) || !Array.isArray(bundle.files) ||
+    (expected.visibility !== undefined && bundle.visibility !== expected.visibility) ||
+    (expected.assetNamespace !== undefined && bundle.assetNamespace !== expected.assetNamespace) ||
+    (expected.assetAccess !== undefined && bundle.assetAccess !== expected.assetAccess)) return { ok: false };
+  const paths = new Set<string>();
+  for (const file of bundle.files) {
+    if (!validPublicationArtifactFileV1(file) || !publicationArtifactFileBytesV1(file)) {
+      return { ok: false };
+    }
+    if ((file.lane === "public-asset" && bundle.assetAccess !== "public") ||
+      (file.lane === "authorized-asset" && bundle.assetAccess !== "authorized")) return { ok: false };
+    if (paths.has(file.path)) return { ok: false };
+    paths.add(file.path);
+  }
+  try {
+    const digest = await publicationArtifactDigestV1(bundle.files);
+    if (digest !== expected.artifactDigest) return { ok: false };
+    const sourceLock = await publicationArtifactSourceLockV1({
+      tenant: expected.tenant,
+      spaceId: expected.spaceId,
+      forge: expected.forge,
+      repo: expected.repo,
+      sourceSha: expected.sourceSha,
+      versionId: expected.versionId,
+      artifactDigest: digest,
+    });
+    return sourceLock === bundle.sourceLock ? { ok: true, value: bundle } : { ok: false };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/** Canonical content digest shared by the trusted writer and renderer readback. */
+export async function publicationArtifactDigestV1(
+  files: readonly PublicationArtifactFileV1[],
+): Promise<string> {
+  if (!Array.isArray(files)) throw new Error("publication artifact file list is malformed");
+  const ordered = [...files].sort(comparePublicationArtifactFilesV1);
+  const paths = new Set<string>();
+  const rows = await Promise.all(ordered.map(async (file) => {
+    if (!validPublicationArtifactFileV1(file) || paths.has(file.path)) {
+      throw new Error("publication artifact file is malformed or duplicated");
+    }
+    paths.add(file.path);
+    const bytes = publicationArtifactFileBytesV1(file);
+    if (!bytes) throw new Error("publication artifact file is malformed");
+    return `${file.lane}\0${file.path}\0${file.encoding}\0${file.byteSize}\0${await sha256Hex(bytes)}`;
+  }));
+  return sha256Hex(rows.join("\n"));
+}
+
+/** Canonical source lock binds one immutable artifact to its configured source. */
+export function publicationArtifactSourceLockV1(input: {
+  tenant: string;
+  spaceId: string;
+  forge: string;
+  repo: string;
+  sourceSha: string;
+  versionId: string;
+  artifactDigest: string;
+}): Promise<string> {
+  return sha256Hex([
+    input.tenant, input.spaceId, input.forge, input.repo,
+    input.sourceSha, input.versionId, input.artifactDigest,
+  ].join("\0"));
+}
+
+/** Physical immutable namespace. Logical artifact paths are always relative. */
+export function publicationArtifactKeyV1(
+  tenant: string,
+  spaceId: string,
+  versionId: string,
+  lane: PublicationArtifactFileV1["lane"],
+  relativePath: string,
+): string {
+  if (!PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(tenant) ||
+    !PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(spaceId) ||
+    !PUBLICATION_ARTIFACT_VERSION_RE.test(versionId)) {
+    throw new Error("publication artifact identity is unsafe");
+  }
+  if (!["content", "public-asset", "authorized-asset"].includes(lane) ||
+    !relativePath || relativePath.startsWith("/") || relativePath.includes("\\") ||
+    relativePath.includes("\0") ||
+    relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error("publication artifact path is unsafe");
+  }
+  return `publications/${tenant}/${spaceId}/${versionId}/${lane}/${relativePath}`;
+}
+
+/** Marker address for one immutable tenant+space+version bundle. */
+export function publicationArtifactBundleKeyV1(
+  tenant: string,
+  spaceId: string,
+  versionId: string,
+): string {
+  if (!PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(tenant) ||
+    !PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(spaceId) ||
+    !PUBLICATION_ARTIFACT_VERSION_RE.test(versionId)) {
+    throw new Error("publication artifact identity is unsafe");
+  }
+  return `publications/${tenant}/${spaceId}/${versionId}/bundle.json`;
+}

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}`;
+}