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

package/packages/public-runtime/src/integration/csp-compiler.ts

@@ -0,0 +1,267 @@
+/**
+ * Version-scoped integration CSP compiler (ADR 0016 curated profiles, ADR 0018/0019
+ * exact-origin grammar + strict-dynamic rejection; ext-policy-02).
+ *
+ * Compiles the Content-Security-Policy additions a resolved integration plan
+ * contributes: it merges the exact origins a curated adapter PROFILE expands to
+ * with the exact reviewed origins an advanced declaration lists ({@link
+ * EffectivePlan.cspNeeds}), into the fixed set of directives a declaration may
+ * touch ({@link INTEGRATION_CSP_DIRECTIVES}) — and NOTHING else. The strict base
+ * policy ({@link import("../csp.js").buildCsp}) always seeds `'self'` + the
+ * per-request nonce first; this only ever APPENDS reviewed origins to those six
+ * directives, so integration policy can never replace or weaken the base:
+ * wildcards, bare schemes, insecure origins, `unsafe-inline`, `unsafe-eval`,
+ * `strict-dynamic`, unknown directives, and any full-header replacement are all
+ * outside the grammar and rejected here.
+ *
+ * The compiler is PURE and DETERMINISTIC: the same profiles + sources + revision
+ * resolve to a byte-identical additions object (origins sorted and deduped per
+ * directive), independent of input order. The output binds to the plan's
+ * `planRevision`, so it is version-scoped — the same value the candidate/edge
+ * cache identity folds in, which is what makes a rollback/uninstall drop the
+ * removed integration's origins on both the cold (recompute) and warm (new key)
+ * paths rather than surviving to TTL.
+ *
+ * It is FAIL-CLOSED PRE-RELEASE: {@link compileIntegrationCsp} returns violations
+ * (and no additions) for any forbidden source, so the promotion gate rejects the
+ * plan before it ships. On the render hot path a plan has already passed that
+ * gate; {@link compileIntegrationCspForRender} returns EMPTY additions on the
+ * defensive off-chance a source is invalid, leaving the strict base untouched
+ * rather than throwing.
+ */
+import type { CspOptions } from "../csp.js";
+import type { ContractResult } from "./result.js";
+import { Violations } from "./result.js";
+import {
+  INTEGRATION_CSP_DIRECTIVES,
+  validateCspSourceSet,
+  type CspSourceSet,
+  type IntegrationCspDirective,
+} from "./csp.js";
+import type { EffectivePlan } from "./plan.js";
+import type { IntegrationDeclarationInput } from "./resolve.js";
+
+/**
+ * The curated adapter CSP catalog: a closed, platform-owned map from a stable
+ * profile slug to the EXACT origins that adapter needs. A declaration references a
+ * slug in `browser.csp.profiles`; the platform (never the tenant) owns the origins,
+ * so a novel adapter requires a reviewed entry here — not a config edit — exactly
+ * like {@link import("../csp.js").EMBED_PROVIDERS} for tenant embeds. Every origin
+ * is an exact `https://host[:port][/path]`, never a wildcard or scheme keyword; a
+ * module-load parity test re-validates the whole catalog against the exact-origin
+ * grammar as defense in depth.
+ */
+export const INTEGRATION_CSP_PROFILES: Readonly<Record<string, CspSourceSet>> = Object.freeze({
+  // Privacy-first analytics — a lightweight, cookieless script + its beacon
+  // endpoint, both first-party to the vendor. Sandbox/broker friendly.
+  plausible: {
+    "script-src": ["https://plausible.io"],
+    "connect-src": ["https://plausible.io"],
+  },
+  fathom: {
+    "script-src": ["https://cdn.usefathom.com"],
+    "connect-src": ["https://cdn.usefathom.com"],
+  },
+
+  // Native Google Analytics / Ads measurement. The adapter sends reviewed event
+  // payloads only to Google's measurement endpoints; it does not load a remote
+  // browser container. Every origin is exact and platform-owned.
+  "google-measurement": {
+    "connect-src": ["https://www.google-analytics.com"],
+  },
+
+  // Meta pixel (fbevents.js). The loader is served from connect.facebook.net; the
+  // pixel's collect endpoint is the facebook.com tracking origin. The tenant
+  // supplies only its public pixel id.
+  "meta-pixel": {
+    "script-src": ["https://connect.facebook.net"],
+    "img-src": ["https://www.facebook.com"],
+    "connect-src": ["https://www.facebook.com"],
+  },
+
+  // Native Amplitude ingestion. Storefront-owned code posts the reviewed,
+  // minimized envelope directly to HTTP API v2. No vendor SDK, loader, remote
+  // configuration, recording, or browser-observation origin is permitted.
+  "amplitude-http": {
+    "connect-src": ["https://api2.amplitude.com"],
+  },
+
+});
+
+/** A curated profile slug known to {@link INTEGRATION_CSP_PROFILES}. */
+export type IntegrationCspProfile = keyof typeof INTEGRATION_CSP_PROFILES;
+
+/**
+ * Compiled additions for the six contributable directives — sorted, deduped exact
+ * origins. A directive is present only when it has at least one origin; an empty
+ * object is the no-integration case (folds into the base as a no-op).
+ */
+export type IntegrationCspAdditions = Partial<Record<IntegrationCspDirective, string[]>>;
+
+/** The compiled, version-scoped integration CSP contribution. */
+export interface CompiledIntegrationCsp {
+  /** Binds these additions to the exact resolved plan revision (version identity). */
+  planRevision: string;
+  /** Sorted, deduped exact origins per contributable directive; empty when nothing declares CSP. */
+  additions: IntegrationCspAdditions;
+  /** The curated profile slugs that expanded into `additions` (sorted, deduped). */
+  profiles: string[];
+}
+
+export interface CompileIntegrationCspInput {
+  /** Curated profile slugs declared across the plan's integrations (order-independent). */
+  profiles: readonly string[];
+  /** Exact reviewed origins the resolver merged ({@link EffectivePlan.cspNeeds}); advanced declarations. */
+  sources: CspSourceSet;
+  /** The resolved plan revision these additions bind to ({@link EffectivePlan.planRevision}). */
+  planRevision: string;
+}
+
+const DIRECTIVE_TO_CSP_OPTION: Readonly<Record<IntegrationCspDirective, keyof CspOptions>> = {
+  "script-src": "scriptSrc",
+  "connect-src": "connectSrc",
+  "frame-src": "frameSrc",
+  "img-src": "imgSrc",
+  "style-src": "styleSrc",
+  "font-src": "fontSrc",
+};
+
+/**
+ * Compile a resolved plan's curated profiles + advanced exact origins into
+ * version-scoped CSP additions. Fail-closed and all-or-nothing: an unknown profile
+ * slug, or any source outside the exact-origin grammar (wildcard, bare scheme,
+ * insecure origin, `unsafe-inline`/`unsafe-eval`/`strict-dynamic`, unknown
+ * directive, or a non-object/full-header shape), yields violations and NO
+ * additions — never a partial merge. This is the pre-release entry the promotion
+ * gate uses to reject an invalid plan before it can reach a live response.
+ */
+export function compileIntegrationCsp(
+  input: CompileIntegrationCspInput,
+): ContractResult<CompiledIntegrationCsp> {
+  const v = new Violations();
+
+  if (typeof input.planRevision !== "string" || input.planRevision.length === 0) {
+    v.add("planRevision", "type", "planRevision must be a non-empty string.");
+  }
+
+  // Advanced declarations: re-validate the whole source set (unknown directives,
+  // non-array/-string shapes, non-exact origins, duplicates) even though the
+  // resolver already validated `plan.cspNeeds`. A forbidden shape must be caught
+  // PRE-RELEASE, not weaken the base at render — this is the fail-closed floor.
+  validateCspSourceSet(input.sources, v, "sources");
+
+  const merged = new Map<IntegrationCspDirective, Set<string>>();
+
+  // Curated adapters expand first. An unknown slug is a closed-set violation; a
+  // known profile's origins are re-validated as defense in depth (the catalog is
+  // platform-owned, but the grammar floor is never assumed).
+  const profiles = [...new Set(input.profiles)].sort();
+  for (const slug of profiles) {
+    const profile = INTEGRATION_CSP_PROFILES[slug];
+    if (!profile) {
+      v.add(
+        `profiles.${slug}`,
+        "unknown_profile",
+        `Unknown CSP profile "${slug}"; curated adapters are a closed, platform-owned set.`,
+      );
+      continue;
+    }
+    validateCspSourceSet(profile, v, `profiles.${slug}`);
+    mergeSourceSet(profile, merged);
+  }
+
+  // Advanced exact origins merge on top of the expanded profiles.
+  mergeSourceSet(input.sources, merged);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+
+  const additions: IntegrationCspAdditions = {};
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    const set = merged.get(directive);
+    if (set && set.size > 0) additions[directive] = [...set].sort();
+  }
+
+  return { ok: true, value: { planRevision: input.planRevision, additions, profiles } };
+}
+
+/** {@link compileIntegrationCsp} keyed directly off a resolved effective plan. */
+export function compileIntegrationCspFromPlan(
+  plan: EffectivePlan,
+  profiles: readonly string[],
+): ContractResult<CompiledIntegrationCsp> {
+  return compileIntegrationCsp({
+    profiles,
+    sources: plan.cspNeeds,
+    planRevision: plan.planRevision,
+  });
+}
+
+/**
+ * Compile for the RENDER hot path: the identical deterministic merge, but a
+ * fail-closed result yields EMPTY additions (the strict base, never weakened)
+ * instead of violations. A plan reaching render has already passed the promotion
+ * gate's {@link compileIntegrationCsp}, so this only ever returns empty as a
+ * defensive backstop — it never throws on the request path.
+ */
+export function compileIntegrationCspForRender(
+  input: CompileIntegrationCspInput,
+): IntegrationCspAdditions {
+  const result = compileIntegrationCsp(input);
+  return result.ok ? result.value.additions : {};
+}
+
+/**
+ * Union the curated profile slugs declared across a plan's input declarations. The
+ * control plane collects these alongside resolving the plan (the resolver merges
+ * the advanced `sources` into `cspNeeds` but leaves profile EXPANSION to this
+ * policy layer, which owns the catalog).
+ */
+export function collectDeclaredCspProfiles(
+  declarations: readonly IntegrationDeclarationInput[],
+): string[] {
+  const set = new Set<string>();
+  for (const decl of declarations) {
+    for (const slug of decl.manifest.browser.csp.profiles) set.add(slug);
+  }
+  return [...set].sort();
+}
+
+/**
+ * Fold compiled integration additions into an assembled {@link CspOptions}
+ * object, APPENDING exact origins to the six contributable directives only. It
+ * never touches `default-src`, `base-uri`, `object-src`, `frame-ancestors`,
+ * `form-action`, `style-src-attr`, or the nonce/`'self'` seeds `buildCsp` injects
+ * — so integration policy can only ever ADD reviewed origins to the strict base,
+ * never weaken it. Empty additions return an equivalent options object, so the
+ * built header is byte-identical for a tenant with no integration (zero cost when
+ * disabled).
+ */
+export function foldIntegrationCsp(
+  base: CspOptions,
+  additions: IntegrationCspAdditions,
+): CspOptions {
+  const next: CspOptions = { ...base };
+  const mutable = next as unknown as Record<string, readonly string[] | undefined>;
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    const origins = additions[directive];
+    if (!origins || origins.length === 0) continue;
+    const key = DIRECTIVE_TO_CSP_OPTION[directive];
+    const existing = next[key] as readonly string[] | undefined;
+    mutable[key] = existing ? [...existing, ...origins] : [...origins];
+  }
+  return next;
+}
+
+/** Merge one exact-origin source set into the per-directive accumulator (post-validation; no revalidation). */
+function mergeSourceSet(
+  sources: CspSourceSet,
+  merged: Map<IntegrationCspDirective, Set<string>>,
+): void {
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    const origins = sources[directive];
+    if (!origins || origins.length === 0) continue;
+    let set = merged.get(directive);
+    if (!set) merged.set(directive, (set = new Set()));
+    for (const origin of origins) set.add(origin);
+  }
+}

package/packages/public-runtime/src/integration/csp.ts

@@ -0,0 +1,105 @@
+/**
+ * CSP source contract for integration declarations (ADR 0014 E2
+ * `integration-csp-hybrid`, ADR 0018/0019).
+ *
+ * A declaration may add exact reviewed origins to a fixed set of directives. It
+ * can never replace or weaken the base CSP: wildcards, bare schemes,
+ * `unsafe-inline`, `unsafe-eval`, and `strict-dynamic` are outside the grammar
+ * and rejected. Nonces are per-response and never serialized, so they never
+ * appear here.
+ */
+import type { Violations } from "./result.js";
+import { assertUnique, joinPath } from "./result.js";
+
+/** The fixed set of directives a declaration may contribute exact origins to. */
+export const INTEGRATION_CSP_DIRECTIVES = [
+  "script-src",
+  "connect-src",
+  "frame-src",
+  "img-src",
+  "style-src",
+  "font-src",
+] as const;
+export type IntegrationCspDirective = (typeof INTEGRATION_CSP_DIRECTIVES)[number];
+
+export type CspSourceSet = Partial<Record<IntegrationCspDirective, string[]>>;
+
+const REJECTED_SUBSTRINGS = [
+  "*",
+  "unsafe-inline",
+  "unsafe-eval",
+  "strict-dynamic",
+];
+
+const EXACT_ORIGIN = /^https:\/\/[a-z0-9.-]+(:\d+)?(\/[^\s?#*]*)?$/i;
+
+/** True for an exact `https://host[:port][/path]` origin with no wildcard, scheme keyword, or query/fragment. */
+export function isExactOrigin(source: string): boolean {
+  if (REJECTED_SUBSTRINGS.some((bad) => source.includes(bad))) return false;
+  return EXACT_ORIGIN.test(source);
+}
+
+export function validateExactOrigin(
+  source: string,
+  v: Violations,
+  path: string,
+): void {
+  if (!isExactOrigin(source)) {
+    v.add(
+      path,
+      "csp_source",
+      `"${source}" is not an exact https origin; wildcards, bare schemes, ` +
+        `unsafe-inline, unsafe-eval, and strict-dynamic are rejected.`,
+    );
+  }
+}
+
+/** Validate an array of exact CSP origins under `path`, rejecting duplicates. */
+export function validateOriginList(
+  sources: readonly string[],
+  v: Violations,
+  path: string,
+): void {
+  assertUnique(sources, v, path, "CSP origin");
+  sources.forEach((source, i) => validateExactOrigin(source, v, `${path}[${i}]`));
+}
+
+/**
+ * Validate a `{ directive: origin[] }` map: every key must be an allowed
+ * directive and every value an array of exact origins.
+ */
+export function validateCspSourceSet(
+  value: unknown,
+  v: Violations,
+  path: string,
+): void {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    v.add(path, "type", "CSP sources must be an object of directive -> origin[].");
+    return;
+  }
+  const allowed = new Set<string>(INTEGRATION_CSP_DIRECTIVES);
+  for (const [directive, sources] of Object.entries(value as Record<string, unknown>)) {
+    const directivePath = joinPath(path, directive);
+    if (!allowed.has(directive)) {
+      v.add(
+        directivePath,
+        "unknown_field",
+        `Unknown CSP directive "${directive}"; free-form directives are rejected.`,
+      );
+      continue;
+    }
+    if (!Array.isArray(sources)) {
+      v.add(directivePath, "type", "Directive value must be an array of origins.");
+      continue;
+    }
+    const originStrings: string[] = [];
+    sources.forEach((source, i) => {
+      if (typeof source !== "string") {
+        v.add(`${directivePath}[${i}]`, "type", "CSP origin must be a string.");
+        return;
+      }
+      originStrings.push(source);
+    });
+    validateOriginList(originStrings, v, directivePath);
+  }
+}

package/packages/public-runtime/src/integration/digest.ts

@@ -0,0 +1,43 @@
+/**
+ * Synchronous, engine-independent content digests for cache/identity keys.
+ *
+ * A digest here is an IDENTITY primitive, never a security boundary: `planRevision`
+ * and the candidate-evidence served fingerprint both fold the same FNV-1a-128 over a
+ * deterministic, key-sorted serialization, so equal content yields a byte-identical
+ * digest across engines without an async WebCrypto call.
+ */
+
+/** Deterministic, key-sorted serialization; `undefined` object fields are dropped. */
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj)
+    .filter((k) => obj[k] !== undefined)
+    .sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(",")}}`;
+}
+
+const FNV_OFFSET_128 = 0x6c62272e07bb014262b821756295c58dn;
+const FNV_PRIME_128 = 0x0000000001000000000000000000013bn;
+const MASK_128 = (1n << 128n) - 1n;
+
+/** FNV-1a 128-bit over the string's UTF-16 code-unit bytes, as a 32-char hex string. */
+export function fnv1a128Hex(input: string): string {
+  let hash = FNV_OFFSET_128;
+  for (let i = 0; i < input.length; i++) {
+    const code = input.charCodeAt(i);
+    hash = ((hash ^ BigInt(code & 0xff)) * FNV_PRIME_128) & MASK_128;
+    hash = ((hash ^ BigInt((code >> 8) & 0xff)) * FNV_PRIME_128) & MASK_128;
+  }
+  return hash.toString(16).padStart(32, "0");
+}
+
+/** Digest an arbitrary browser-safe value by its deterministic serialization. */
+export function digestValue(value: unknown): string {
+  return fnv1a128Hex(stableStringify(value));
+}

package/packages/public-runtime/src/integration/environment.ts

@@ -0,0 +1,228 @@
+/**
+ * The universal four-stage public browser environment (ADR 0014 E1
+ * `integration-environment-universal`, refined by ADR 0017 as a renderer-owned
+ * platform block).
+ *
+ * Every document gets this small renderer-owned object, serialized before app
+ * code in all render paths. It carries only public values — never a token,
+ * binding, or signed URL. Missing or unknown values are never treated as `live`.
+ */
+import type { ContractResult } from "./result.js";
+import {
+  Violations,
+  reqObject,
+  reqEnum,
+  reqLiteral,
+  reqString,
+  rejectUnknownKeys,
+} from "./result.js";
+import { ENVIRONMENT_SCHEMA_VERSION } from "./version.js";
+import { findForbiddenFields } from "./secrets.js";
+
+/** The four environment stages. A candidate never reports `live`. */
+export const INTEGRATION_ENVIRONMENTS = [
+  "local",
+  "candidate",
+  "staged",
+  "live",
+] as const;
+export type IntegrationEnvironment = (typeof INTEGRATION_ENVIRONMENTS)[number];
+
+/** Document surfaces that receive an environment block. */
+export const INTEGRATION_SITE_SURFACES = [
+  "storefront",
+  "checkout",
+  "admin",
+  "marketing",
+] as const;
+export type IntegrationSiteSurface = (typeof INTEGRATION_SITE_SURFACES)[number];
+
+export interface BrowserEnvironment {
+  schemaVersion: typeof ENVIRONMENT_SCHEMA_VERSION;
+  siteSurface: IntegrationSiteSurface;
+  environment: IntegrationEnvironment;
+  canonicalHost: string;
+  revision: string;
+}
+
+const HOSTNAME = /^[a-z0-9.-]+$/i;
+
+/** Fail-closed environment parse: unknown or missing values never yield `live`. */
+export function parseEnvironment(value: unknown): IntegrationEnvironment | null {
+  return typeof value === "string" &&
+    (INTEGRATION_ENVIRONMENTS as readonly string[]).includes(value)
+    ? (value as IntegrationEnvironment)
+    : null;
+}
+
+/** True only for exactly `"live"`; anything unknown is treated as not-live. */
+export function isLiveEnvironment(value: unknown): boolean {
+  return value === "live";
+}
+
+/**
+ * The authoritative server-render signals the stage derivation consumes. Each is
+ * a fact the renderer already knows about the request it is answering; none is a
+ * client-supplied value.
+ */
+export interface IntegrationEnvironmentSignals {
+  /** `import.meta.env.DEV` — the `astro dev` (Node) render. CSP is report-only here. */
+  dev: boolean;
+  /** The request host is `localhost`/`127.0.0.1`: a locally-served built Worker. */
+  localHost: boolean;
+  /** This request is a per-change candidate render (`/preview/render/…`, revision, PR). */
+  candidate: boolean;
+  /** The request host is a `preview.` host. */
+  previewHost: boolean;
+  /** The resolved customization environment: `live` production vs `test` preview. */
+  customizationEnv: "live" | "test";
+}
+
+/**
+ * Derive the authoritative stage from server-render signals. The order is
+ * fail-closed and candidate-never-live:
+ *   - a per-change candidate render is always `candidate` (never `live`, even on a
+ *     live host or in dev);
+ *   - a local render (`astro dev` OR a Worker served on localhost) is `local`;
+ *   - a preview/test surface is `staged`;
+ *   - only a genuine live production read is `live`.
+ * Any shape the branches do not reach stays `staged` — a non-live default, so an
+ * unforeseen signal combination can never be mistaken for production.
+ */
+export function deriveIntegrationEnvironment(
+  signals: IntegrationEnvironmentSignals,
+): IntegrationEnvironment {
+  if (signals.candidate) return "candidate";
+  if (signals.dev || signals.localHost) return "local";
+  if (signals.previewHost || signals.customizationEnv === "test") return "staged";
+  if (signals.customizationEnv === "live") return "live";
+  return "staged";
+}
+
+/** Reduce a host (possibly with scheme/port/path) to the bare hostname the contract requires. */
+function bareHostname(value: string): string {
+  const noScheme = value.trim().replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+  const hostAndPort = noScheme.split("/")[0] ?? noScheme;
+  return hostAndPort.split(":")[0] ?? hostAndPort;
+}
+
+/** Everything the renderer needs to build the immutable environment object. */
+export interface BrowserEnvironmentInput extends IntegrationEnvironmentSignals {
+  siteSurface: IntegrationSiteSurface;
+  /** The canonical host; scheme/port/path are stripped to a bare hostname. */
+  canonicalHost: string;
+  /** A non-secret render revision (deployed code sha, candidate versionId, …). */
+  revision: string;
+}
+
+/**
+ * Build the renderer-owned, immutable environment object from authoritative
+ * server state. The result is frozen so no downstream code can mutate the stage
+ * after the renderer has fixed it; it carries only the closed, public shape —
+ * never a token, binding, or signed URL (that is impossible by construction, the
+ * shape has no such field).
+ */
+export function resolveBrowserEnvironment(
+  input: BrowserEnvironmentInput,
+): BrowserEnvironment {
+  return Object.freeze({
+    schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+    siteSurface: input.siteSurface,
+    environment: deriveIntegrationEnvironment(input),
+    canonicalHost: bareHostname(input.canonicalHost),
+    revision: input.revision,
+  });
+}
+
+/** The browser global the environment object is published as, frozen, in every document. */
+export const BROWSER_ENVIRONMENT_GLOBAL = "__TOT_INTEGRATION_ENV__";
+
+/**
+ * Serialize an arbitrary browser-safe value to a JSON literal safe to embed in an
+ * inline `<script>`: the HTML-significant characters `<`, `>`, `&` and the JS line
+ * terminators U+2028/U+2029 are `\uXXXX`-escaped so the payload can neither break
+ * out of the surrounding `<script>` nor be mis-scanned as a nested tag by a raw-mount
+ * nonce stamper. This is the ONE serializer every renderer-owned inline global shares.
+ */
+export function serializeForInlineScript(value: unknown): string {
+  // `<` `>` `&` `U+2028` `U+2029` — escaped by code point so no line terminator or
+  // HTML-significant character is ever emitted literally into the <script>.
+  const escaped = new Set([0x3c, 0x3e, 0x26, 0x2028, 0x2029]);
+  let out = "";
+  for (const ch of JSON.stringify(value)) {
+    const code = ch.charCodeAt(0);
+    out += escaped.has(code) ? `\\u${code.toString(16).padStart(4, "0")}` : ch;
+  }
+  return out;
+}
+
+/**
+ * Serialize the environment object to an XSS-safe JSON literal with a fixed key
+ * order (so both document mounts emit byte-identical bytes for the same object).
+ */
+export function serializeBrowserEnvironment(env: BrowserEnvironment): string {
+  return serializeForInlineScript({
+    schemaVersion: env.schemaVersion,
+    siteSurface: env.siteSurface,
+    environment: env.environment,
+    canonicalHost: env.canonicalHost,
+    revision: env.revision,
+  });
+}
+
+/**
+ * The single serialization engine both document mounts use (ADR 0015, one engine,
+ * two mounts): emit the frozen environment object as the renderer-owned global,
+ * before any tenant/app code. The `nonce` is a renderer-applied SCRIPT ATTRIBUTE —
+ * never part of the serialized object (ADR 0018 nonce non-serialization). Pass an
+ * empty nonce on the raw mount, where the shared nonce stamper applies it uniformly.
+ */
+export function renderBrowserEnvironmentScript(
+  env: BrowserEnvironment,
+  nonce: string,
+): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  return `<script${nonceAttr}>window.${BROWSER_ENVIRONMENT_GLOBAL}=Object.freeze(${serializeBrowserEnvironment(env)});</script>`;
+}
+
+export function validateBrowserEnvironment(
+  input: unknown,
+): ContractResult<BrowserEnvironment> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+
+  rejectUnknownKeys(
+    obj,
+    ["schemaVersion", "siteSurface", "environment", "canonicalHost", "revision"],
+    v,
+    "",
+  );
+
+  const schemaVersion = reqLiteral(obj, "schemaVersion", ENVIRONMENT_SCHEMA_VERSION, v, "");
+  const siteSurface = reqEnum(obj, "siteSurface", INTEGRATION_SITE_SURFACES, v, "");
+  const environment = reqEnum(obj, "environment", INTEGRATION_ENVIRONMENTS, v, "");
+  const canonicalHost = reqString(obj, "canonicalHost", v, "");
+  const revision = reqString(obj, "revision", v, "");
+
+  if (canonicalHost !== undefined && !HOSTNAME.test(canonicalHost)) {
+    v.add("canonicalHost", "format", "canonicalHost must be a bare hostname (no scheme or path).");
+  }
+
+  for (const violation of findForbiddenFields(obj)) v.items.push(violation);
+
+  if (
+    !v.ok ||
+    schemaVersion === undefined ||
+    siteSurface === undefined ||
+    environment === undefined ||
+    canonicalHost === undefined ||
+    revision === undefined
+  ) {
+    return { ok: false, violations: v.items };
+  }
+  return {
+    ok: true,
+    value: { schemaVersion, siteSurface, environment, canonicalHost, revision },
+  };
+}