@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/integration/render-phases.ts

@@ -0,0 +1,267 @@
+/**
+ * The renderer-neutral fixed-phase render engine (ADR 0014 S1/S2
+ * `integration-phases-fixed-dag`, ADR 0015 one-engine-two-mounts, ADR 0018 nonce
+ * non-serialization; ext-kernel-04).
+ *
+ * ONE engine produces the renderer-owned emissions for every reserved phase, in
+ * fixed order, as three splice regions a document mount inserts at exact
+ * boundaries: `head` (platform.environment → consent.defaults → head.early),
+ * `bodyStart` (body.start fallback), and `bodyDeferred` (document.deferred global
+ * entry). Both document mounts — `Layout.astro` and `rawHtmlResponse()` — splice
+ * the SAME strings, so their per-phase markup is identical by construction (golden
+ * parity is a property of calling one function, not of keeping two in sync).
+ *
+ * Nonce discipline (ADR 0018): the engine stamps the {@link INTEGRATION_NONCE_PLACEHOLDER}
+ * sentinel, never a live nonce, onto its inline `<script>`s. The renderer replaces
+ * the sentinel with a fresh per-response nonce at serve time via {@link stampNonce}
+ * — so a cached artifact carries the sentinel (a nonce-free template), never a
+ * reusable nonce, and every response (cold render or warm cache hit) gets a fresh
+ * matching nonce/CSP pair. A nonce is thus never part of any serialized object.
+ *
+ * The engine is FAIL-CLOSED: a plan whose schema is unknown, whose contributions
+ * name an unknown or renderer-owned phase, whose ids or resolved order duplicate,
+ * or whose values carry secret material throws {@link IntegrationRenderError}
+ * rather than emitting partial or unsafe markup.
+ */
+import type { EffectivePlan } from "./plan.js";
+import { assertPlanBrowserSafe } from "./plan.js";
+import { EFFECTIVE_PLAN_SCHEMA_VERSION } from "./version.js";
+import {
+  RESERVED_PHASES,
+  VENDOR_ADDRESSABLE_PHASES,
+  isReservedPhase,
+  type ReservedPhase,
+} from "./phases.js";
+import {
+  renderBrowserEnvironmentScript,
+  serializeForInlineScript,
+} from "./environment.js";
+import { defaultConsentSnapshot } from "./consent-broker.js";
+
+/**
+ * The sentinel a renderer stamps in place of a live CSP nonce. It is a valid
+ * base64url nonce token, so an un-stamped document is still syntactically well
+ * formed, yet distinctive enough to substitute unambiguously. The renderer
+ * replaces every occurrence — in the HTML body AND the CSP header — with one fresh
+ * per-response nonce via {@link stampNonce}. The placeholder, never a live nonce,
+ * is what a cached artifact contains.
+ */
+export const INTEGRATION_NONCE_PLACEHOLDER = "__TOT_CSP_NONCE_PLACEHOLDER__";
+
+/** Browser globals the renderer-owned phase emissions publish (all frozen, all public). */
+export const INTEGRATION_CONSENT_GLOBAL = "__TOT_INTEGRATION_CONSENT__";
+export const INTEGRATION_PLAN_GLOBAL = "__TOT_INTEGRATION_PLAN__";
+
+/**
+ * One integration named in the boot descriptor: enough to identify it, IMPORT its
+ * entry module, and consent-gate that load — never secret-bearing. `entry.url` is
+ * the same-origin, exact-version asset the lifecycle runtime dynamically imports;
+ * `consent` is what must be eligible before it does.
+ */
+export interface BootDescriptorIntegration {
+  origin: EffectivePlan["integrations"][number]["origin"];
+  appId: string;
+  version: string;
+  /**
+   * The resolved authority tier. It GATES the entry-module loader: the same-origin
+   * loader loads a `elevated-parent` entry into the parent document (its honest,
+   * review-only contract) and REFUSES every other tier fail-closed. A `sandbox`-tier
+   * entry is held back until the null-origin iframe host that actually isolates it
+   * ships — it is never run with the parent authority its label does not grant.
+   */
+  executionTier: EffectivePlan["integrations"][number]["executionTier"];
+  entry: {
+    url: string;
+    format: EffectivePlan["integrations"][number]["entry"]["format"];
+  };
+  consent: {
+    purposes: string[];
+    loadWhen: EffectivePlan["integrations"][number]["consent"]["loadWhen"];
+  };
+  /**
+   * The browser-deliverable commerce events this integration declared and was
+   * validated for — the scope bound the deferred lifecycle runtime clamps this
+   * integration's receive-only subscribe handle to (F2 wire). Browser-safe: event
+   * TYPE names only, no payload or secret.
+   */
+  events: EffectivePlan["integrations"][number]["events"];
+}
+
+/**
+ * The public, browser-safe descriptor the early-head loader publishes as
+ * {@link INTEGRATION_PLAN_GLOBAL} and the deferred lifecycle runtime (ext-kernel-05)
+ * boots against. It carries plan identity, the participating integrations, the
+ * per-phase contribution ids in resolved order, public config, and consent/CSP
+ * needs — no executable content and no secret.
+ */
+export interface IntegrationBootDescriptor {
+  schemaVersion: EffectivePlan["schemaVersion"];
+  planRevision: string;
+  environment: EffectivePlan["environment"]["environment"];
+  siteSurface: EffectivePlan["environment"]["siteSurface"];
+  tenantPublicId: string;
+  integrations: BootDescriptorIntegration[];
+  order: string[];
+  phases: Record<string, string[]>;
+  publicConfig: Record<string, Record<string, unknown>>;
+  consentNeeds: string[];
+  cspNeeds: EffectivePlan["cspNeeds"];
+}
+
+/** The three splice regions a document mount inserts at exact phase boundaries. */
+export interface IntegrationPhaseMarkup {
+  /** platform.environment → consent.defaults → head.early, in fixed order; inserted at head start. */
+  head: string;
+  /** body.start fallback; inserted at the very start of `<body>`. */
+  bodyStart: string;
+  /** document.deferred global entry; inserted just before `</body>`. */
+  bodyDeferred: string;
+}
+
+/** Thrown when a plan cannot be rendered safely; carries every reason (fail closed). */
+export class IntegrationRenderError extends Error {
+  readonly violations: readonly string[];
+  constructor(violations: readonly string[]) {
+    super(`Integration render blocked (fail closed): ${violations.join("; ")}`);
+    this.name = "IntegrationRenderError";
+    this.violations = violations;
+  }
+}
+
+/** The explicit, single-occurrence boundary anchor a phase's emission is prefixed with. */
+export function phaseBoundary(phase: ReservedPhase): string {
+  return `<!--tot:phase:${phase}-->`;
+}
+
+/**
+ * Render the fixed phases of one resolved {@link EffectivePlan} into the three
+ * splice regions both document mounts consume. `nonce` is the value stamped onto
+ * the emitted inline scripts — pass {@link INTEGRATION_NONCE_PLACEHOLDER} so the
+ * renderer can stamp a fresh nonce per response; an empty string omits the
+ * attribute (for tests / mounts that stamp uniformly downstream).
+ */
+export function renderIntegrationPhases(
+  plan: EffectivePlan,
+  nonce: string = INTEGRATION_NONCE_PLACEHOLDER,
+): IntegrationPhaseMarkup {
+  assertRenderablePlan(plan);
+
+  const head =
+    phaseBoundary("platform.environment") +
+    renderBrowserEnvironmentScript(plan.environment, nonce) +
+    phaseBoundary("consent.defaults") +
+    inlineFrozenGlobal(INTEGRATION_CONSENT_GLOBAL, defaultConsentSnapshot(), nonce) +
+    phaseBoundary("head.early") +
+    inlineFrozenGlobal(INTEGRATION_PLAN_GLOBAL, bootDescriptor(plan), nonce);
+
+  const bodyStart =
+    phaseBoundary("body.start") + `<div data-tot-integration-root hidden></div>`;
+
+  const bodyDeferred =
+    phaseBoundary("document.deferred") + `<div data-tot-integration-deferred hidden></div>`;
+
+  return { head, bodyStart, bodyDeferred };
+}
+
+/**
+ * Replace every {@link INTEGRATION_NONCE_PLACEHOLDER} in `text` (an HTML body or a
+ * CSP header value) with one fresh per-response `nonce`. Idempotent on text with no
+ * placeholder (a static-bundle body, a non-HTML response) — a safe no-op.
+ */
+export function stampNonce(text: string, nonce: string): string {
+  return text.split(INTEGRATION_NONCE_PLACEHOLDER).join(nonce);
+}
+
+/**
+ * The public, browser-safe boot descriptor the early-head loader reads: plan
+ * identity, the per-phase contribution ids in resolved order, public config,
+ * consent needs, and CSP needs. It carries no executable content and no secret
+ * (guaranteed by {@link assertPlanBrowserSafe} in {@link assertRenderablePlan}).
+ */
+function bootDescriptor(plan: EffectivePlan): IntegrationBootDescriptor {
+  const byId = new Map(plan.contributions.map((c) => [c.id, c]));
+  const phases: Record<string, string[]> = {};
+  for (const phase of VENDOR_ADDRESSABLE_PHASES) phases[phase] = [];
+  for (const id of plan.order) {
+    const contribution = byId.get(id);
+    if (contribution) phases[contribution.phase]?.push(id);
+  }
+  return {
+    schemaVersion: plan.schemaVersion,
+    planRevision: plan.planRevision,
+    environment: plan.environment.environment,
+    siteSurface: plan.environment.siteSurface,
+    tenantPublicId: plan.tenantPublicId,
+    integrations: plan.integrations.map((i) => ({
+      origin: i.origin,
+      appId: i.appId,
+      version: i.version,
+      executionTier: i.executionTier,
+      entry: { url: i.entry.url, format: i.entry.format },
+      consent: { purposes: [...i.consent.purposes], loadWhen: i.consent.loadWhen },
+      events: [...(i.events ?? [])],
+    })),
+    order: plan.order,
+    phases,
+    publicConfig: plan.publicConfig,
+    consentNeeds: plan.consentNeeds,
+    cspNeeds: plan.cspNeeds,
+  };
+}
+
+function inlineFrozenGlobal(
+  globalName: string,
+  value: unknown,
+  nonce: string,
+): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  return `<script${nonceAttr}>window.${globalName}=Object.freeze(${serializeForInlineScript(value)});</script>`;
+}
+
+/**
+ * Fail-closed structural gate: an unknown plan schema, a contribution targeting an
+ * unknown or renderer-owned (`platform.environment`) phase, a duplicate id, a
+ * resolved order that is not a permutation of the contribution ids, or any secret
+ * material blocks the whole render. There is no partial emission.
+ */
+function assertRenderablePlan(plan: EffectivePlan): void {
+  const problems: string[] = [];
+
+  if (plan.schemaVersion !== EFFECTIVE_PLAN_SCHEMA_VERSION) {
+    problems.push(`unknown effective-plan schemaVersion ${String(plan.schemaVersion)}`);
+  }
+
+  const ids = new Set<string>();
+  for (const contribution of plan.contributions) {
+    if (!isReservedPhase(contribution.phase)) {
+      problems.push(`contribution "${contribution.id}" targets unknown phase "${contribution.phase}"`);
+    } else if (!(VENDOR_ADDRESSABLE_PHASES as readonly ReservedPhase[]).includes(contribution.phase)) {
+      problems.push(
+        `contribution "${contribution.id}" targets renderer-owned phase "${contribution.phase}"`,
+      );
+    }
+    if (ids.has(contribution.id)) {
+      problems.push(`duplicate contribution id "${contribution.id}"`);
+    }
+    ids.add(contribution.id);
+  }
+
+  const ordered = new Set<string>();
+  for (const id of plan.order) {
+    if (!ids.has(id)) problems.push(`resolved order references unknown contribution "${id}"`);
+    if (ordered.has(id)) problems.push(`resolved order lists "${id}" more than once`);
+    ordered.add(id);
+  }
+  for (const id of ids) {
+    if (!ordered.has(id)) problems.push(`contribution "${id}" is missing from the resolved order`);
+  }
+
+  for (const violation of assertPlanBrowserSafe(plan)) {
+    problems.push(`browser-unsafe plan value (${violation.code}) at ${violation.path}`);
+  }
+
+  if (problems.length > 0) throw new IntegrationRenderError(problems);
+}
+
+/** The reserved phases, exported for tests/tools that assert boundary order/count. */
+export const RENDERED_PHASE_ORDER: readonly ReservedPhase[] = RESERVED_PHASES;