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

package/packages/public-runtime/src/integration/receipt-measurement.ts

@@ -0,0 +1,370 @@
+/**
+ * Cross-domain consent propagation for hosted-receipt measurement (ADR 0022
+ * `receipt-consent-propagation`, ADR 0023 Q3 `analytics-consent-required`;
+ * ext-commerce-06). The "receipt" is the post-purchase page the PROVIDER (Foxy)
+ * renders on ITS OWN origin — a DIFFERENT domain from the storefront — so any
+ * browser measurement there is cross-domain.
+ *
+ * This is the decision seam that says whether that cross-domain browser measurement
+ * may run, and if so, exactly what may cross the domain boundary with it. It is
+ * DEFAULT-SAFE to server-side-only conversion: the storefront's own verified-order
+ * → server conversion join ({@link ./order-conversion.ts}) is the authoritative,
+ * always-on path; receipt-page BROWSER measurement is an additive best-effort layer
+ * that is enabled ONLY when every gate below holds, and is silently skipped (server
+ * conversion still fires) otherwise.
+ *
+ * Two BINDING board decisions gate it, both fail-closed:
+ *
+ *   - `integration-receipt-consent`: non-essential receipt-page browser measurement
+ *     requires VERIFIED provider-supported consent propagation. Until provider
+ *     discovery + counsel verify that the provider honours and propagates the
+ *     shopper's analytics-consent decision on the receipt origin, conversion stays
+ *     SERVER-SIDE ONLY. {@link ProviderReceiptSupport.consentPropagationVerified}
+ *     defaults CLOSED (unverified), so with no verified provider integration this
+ *     seam always returns `server-only`.
+ *
+ *   - `gate-legal-q3` (analytics-consent-required): the shopper's analytics-consent
+ *     decision (Q3) must TRAVEL WITH, and GATE, any browser measurement. When the
+ *     shopper is not analytics-eligible, no browser measurement runs — attribution
+ *     is dropped and conversion is server-side only.
+ *
+ * What crosses the boundary is a {@link ReceiptMeasurementGrant}: a bounded, opaque,
+ * CLOSED descriptor carrying ONLY public execution-context facts (tenant, stage,
+ * provider), the OPAQUE bounded correlation THREAD id (never the signed correlation
+ * TOKEN, never the signing secret, never a re-usable capability), and the
+ * analytics-consent snapshot that travels with the measurement. It carries NO PII
+ * and NO secret by construction — the shape has no such field and
+ * {@link findForbiddenFields} is asserted over every serialized grant.
+ *
+ * Pure and dependency-injected: the provider-support fact and the correlation thread
+ * are inputs from trusted server context, so the whole decision is exercised in node
+ * with no edge runtime.
+ */
+import type { IntegrationEnvironment } from "./environment.js";
+import { INTEGRATION_ENVIRONMENTS } from "./environment.js";
+import type { ConsentSnapshot } from "./consent-broker.js";
+import { isPurposeEligible, toEventConsentSnapshot } from "./consent-broker.js";
+import type { EventConsentSnapshot, EventCorrelation } from "./events.js";
+import type { ConsentPurpose } from "../integration-capabilities.js";
+import { CONSENT_PURPOSES } from "../integration-capabilities.js";
+import { RECEIPT_MEASUREMENT_GRANT_SCHEMA_VERSION, CONSENT_SNAPSHOT_SCHEMA_VERSION } from "./version.js";
+import { findForbiddenFields } from "./secrets.js";
+
+/** The consent purpose receipt-page browser measurement requires (ADR 0023 Q3). */
+export const RECEIPT_MEASUREMENT_CONSENT_PURPOSE: ConsentPurpose = "analytics";
+
+/**
+ * The server-verified fact of whether a provider's hosted receipt supports propagating
+ * the shopper's analytics-consent decision to browser measurement on the receipt origin.
+ * This is NOT a caller assertion the browser can set — it is resolved from trusted
+ * server context (a provider-integration registry gated by counsel + discovery).
+ */
+export interface ProviderReceiptSupport {
+  /** The provider whose hosted receipt this is (e.g. `"foxy"`) — a public fact. */
+  provider: string;
+  /**
+   * Whether this provider's receipt has VERIFIED consent-propagation support. DEFAULT
+   * CLOSED: absent/unknown ⇒ `false` ⇒ server-side conversion only. Only a
+   * counsel-and-discovery-verified provider integration flips this `true`.
+   */
+  consentPropagationVerified: boolean;
+}
+
+/**
+ * The bounded, opaque descriptor that crosses storefront → provider → app domains to
+ * enable receipt-page browser measurement. CLOSED and browser-safe: it carries ONLY
+ * public execution-context facts, the opaque correlation THREAD id, its bounded expiry,
+ * and the analytics-consent snapshot that travels with the measurement. It carries no
+ * PII, no signing secret, and no re-usable token — the correlation thread id verifies
+ * nothing on its own.
+ */
+export interface ReceiptMeasurementGrant {
+  schemaVersion: typeof RECEIPT_MEASUREMENT_GRANT_SCHEMA_VERSION;
+  /** The provider whose receipt origin the measurement runs on — a public fact. */
+  provider: string;
+  /** The tenant the handoff ran in — a public execution-context fact. */
+  tenant: string;
+  /** The stage the handoff ran in; a staged grant can never enable a live receipt read. */
+  environment: IntegrationEnvironment;
+  /**
+   * The OPAQUE bounded correlation thread id (the handoff `eventId`) — the ONE
+   * cross-site attribution handle. NOT the signed correlation token, NOT a capability:
+   * it verifies nothing and authorizes nothing; it only threads this measurement to its
+   * authoritative server conversion.
+   */
+  correlationId: string;
+  /** The correlation's bounded expiry (ISO 8601). Measurement past this is dropped. */
+  correlationExpiresAt: string;
+  /**
+   * The analytics-consent snapshot that TRAVELS WITH the measurement (Q3): eligible
+   * purpose names + snapshot id, never raw consent state and never PII.
+   */
+  consent: EventConsentSnapshot;
+}
+
+/** Why receipt-page browser measurement was not enabled (server-side conversion only). */
+export type ReceiptMeasurementDenyReason =
+  /** The shopper is not analytics-eligible (Q3 gate) — attribution dropped. */
+  | "analytics-consent-required"
+  /** The provider has no VERIFIED consent-propagation support (board decision). */
+  | "provider-unverified"
+  /** No opaque correlation thread to carry (the handoff was unattributed). */
+  | "correlation-missing"
+  /** The correlation thread is past its bounded lifetime. */
+  | "correlation-expired"
+  /** The grant's tenant/stage does not match the receipt-read's trusted context. */
+  | "context-mismatch";
+
+/**
+ * The receipt-measurement decision. `browser` carries the bounded {@link
+ * ReceiptMeasurementGrant} to propagate across the domain boundary; `server-only` is
+ * the default-safe outcome — no browser measurement, the server conversion join alone.
+ */
+export type ReceiptMeasurementDecision =
+  | { mode: "browser"; grant: ReceiptMeasurementGrant }
+  | { mode: "server-only"; reason: ReceiptMeasurementDenyReason };
+
+export interface ResolveReceiptMeasurementInput {
+  /** The tenant, from trusted server execution context — never a client value. */
+  tenant: string;
+  /** The stage, from the renderer-owned `BrowserEnvironment.environment` (server-supplied). */
+  environment: IntegrationEnvironment;
+  /** The shopper's LIVE consent snapshot (parsed fail-closed by the caller). */
+  consent: ConsentSnapshot;
+  /**
+   * The provider's server-verified receipt-consent-propagation support. `null`/`undefined`
+   * ⇒ unverified ⇒ server-side only (the expected state until Foxy discovery + counsel).
+   */
+  providerSupport: ProviderReceiptSupport | null | undefined;
+  /**
+   * The opaque bounded correlation thread from the attributed checkout handoff. `null`/
+   * `undefined` ⇒ the handoff was unattributed ⇒ nothing to carry ⇒ server-side only.
+   */
+  correlation: EventCorrelation | null | undefined;
+  /** Injectable wall clock in ms (defaults to `Date.now()`) for deterministic tests. */
+  now?: number;
+}
+
+/** Parse an ISO timestamp to epoch ms, or `null` if it is not a valid date. */
+function parseIsoMs(iso: string): number | null {
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Decide whether cross-domain browser measurement may run on the hosted receipt, and
+ * build the bounded grant that crosses the boundary if so. Fail-closed and
+ * default-safe: the gates run consent FIRST (the provider-support fact and the
+ * correlation are never even consulted for a shopper who withheld analytics consent),
+ * then verified provider support, then a present + unexpired correlation thread. Any
+ * gate that does not hold yields `server-only` — the authoritative server conversion
+ * still fires; only the additive browser layer is withheld. Never throws.
+ */
+export function resolveReceiptMeasurement(
+  input: ResolveReceiptMeasurementInput,
+): ReceiptMeasurementDecision {
+  // Q3 consent gate FIRST: a shopper who is not analytics-eligible gets NO browser
+  // measurement; the provider fact and correlation are never consulted for them.
+  if (!isPurposeEligible(input.consent, RECEIPT_MEASUREMENT_CONSENT_PURPOSE)) {
+    return { mode: "server-only", reason: "analytics-consent-required" };
+  }
+
+  // Board decision `integration-receipt-consent`: no browser measurement without
+  // VERIFIED provider-supported consent propagation. Default-closed.
+  if (!input.providerSupport?.consentPropagationVerified) {
+    return { mode: "server-only", reason: "provider-unverified" };
+  }
+
+  // Nothing to correlate: an unattributed handoff carries no opaque thread.
+  const correlation = input.correlation;
+  if (!correlation || typeof correlation.id !== "string" || correlation.id.length === 0) {
+    return { mode: "server-only", reason: "correlation-missing" };
+  }
+
+  // Bounded lifetime: never mint a grant whose correlation thread is already dead.
+  const expMs = parseIsoMs(correlation.expiresAt);
+  const nowMs = input.now ?? Date.now();
+  if (expMs === null || nowMs >= expMs) {
+    return { mode: "server-only", reason: "correlation-expired" };
+  }
+
+  const grant: ReceiptMeasurementGrant = {
+    schemaVersion: RECEIPT_MEASUREMENT_GRANT_SCHEMA_VERSION,
+    provider: input.providerSupport.provider,
+    tenant: input.tenant,
+    environment: input.environment,
+    correlationId: correlation.id,
+    correlationExpiresAt: correlation.expiresAt,
+    // The analytics-consent decision travels WITH the measurement.
+    consent: toEventConsentSnapshot(input.consent),
+  };
+  return { mode: "browser", grant };
+}
+
+// --- cross-domain carry -----------------------------------------------------------
+
+/**
+ * Serialize a grant for propagation across the domain boundary (a redirect param or a
+ * `postMessage` payload). Asserts, defense-in-depth, that no field name denotes secret
+ * material before it can cross — so a future field addition that names a secret is
+ * caught here, not in production. The shape is already CLOSED and PII-free by design.
+ */
+export function serializeReceiptMeasurementGrant(grant: ReceiptMeasurementGrant): string {
+  const forbidden = findForbiddenFields(grant);
+  if (forbidden.length > 0) {
+    throw new Error(
+      `receipt measurement grant carries forbidden field(s): ${forbidden.map((f) => f.path).join(", ")}`,
+    );
+  }
+  // Fixed key order so an equal grant always serializes to byte-identical output.
+  return JSON.stringify({
+    schemaVersion: grant.schemaVersion,
+    provider: grant.provider,
+    tenant: grant.tenant,
+    environment: grant.environment,
+    correlationId: grant.correlationId,
+    correlationExpiresAt: grant.correlationExpiresAt,
+    consent: {
+      schemaVersion: grant.consent.schemaVersion,
+      snapshotId: grant.consent.snapshotId,
+      eligiblePurposes: [...grant.consent.eligiblePurposes],
+    },
+  });
+}
+
+const GRANT_KEYS: readonly (keyof ReceiptMeasurementGrant)[] = [
+  "schemaVersion",
+  "provider",
+  "tenant",
+  "environment",
+  "correlationId",
+  "correlationExpiresAt",
+  "consent",
+];
+
+/** Validate an {@link EventConsentSnapshot} fail-closed: shape + only known purposes. */
+function parseEventConsentSnapshot(raw: unknown): EventConsentSnapshot | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const obj = raw as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (!["schemaVersion", "snapshotId", "eligiblePurposes"].includes(key)) return null;
+  }
+  if (obj.schemaVersion !== CONSENT_SNAPSHOT_SCHEMA_VERSION) return null;
+  if (typeof obj.snapshotId !== "string" || obj.snapshotId.length === 0) return null;
+  if (!Array.isArray(obj.eligiblePurposes)) return null;
+  const known = new Set<string>(CONSENT_PURPOSES);
+  for (const p of obj.eligiblePurposes) {
+    if (typeof p !== "string" || !known.has(p)) return null;
+  }
+  return {
+    schemaVersion: CONSENT_SNAPSHOT_SCHEMA_VERSION,
+    snapshotId: obj.snapshotId,
+    eligiblePurposes: [...(obj.eligiblePurposes as string[])],
+  };
+}
+
+/**
+ * Parse a serialized grant fail-closed. An unknown schema version, an unknown or missing
+ * field, an invalid stage, a malformed consent snapshot, a non-string opaque handle, or
+ * ANY field name that denotes secret material yields `null` — a caller on the receipt
+ * origin cannot smuggle a forged, tampered, or secret-bearing grant into measurement.
+ */
+export function parseReceiptMeasurementGrant(raw: unknown): ReceiptMeasurementGrant | null {
+  let obj: unknown = raw;
+  if (typeof raw === "string") {
+    try {
+      obj = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) return null;
+  const o = obj as Record<string, unknown>;
+
+  for (const key of Object.keys(o)) {
+    if (!(GRANT_KEYS as readonly string[]).includes(key)) return null;
+  }
+  // Defense-in-depth: reject any grant carrying a secret-named field, at any depth.
+  if (findForbiddenFields(o).length > 0) return null;
+
+  if (o.schemaVersion !== RECEIPT_MEASUREMENT_GRANT_SCHEMA_VERSION) return null;
+  if (typeof o.provider !== "string" || o.provider.length === 0) return null;
+  if (typeof o.tenant !== "string" || o.tenant.length === 0) return null;
+  if (
+    typeof o.environment !== "string" ||
+    !(INTEGRATION_ENVIRONMENTS as readonly string[]).includes(o.environment)
+  ) {
+    return null;
+  }
+  if (typeof o.correlationId !== "string" || o.correlationId.length === 0) return null;
+  if (typeof o.correlationExpiresAt !== "string" || parseIsoMs(o.correlationExpiresAt) === null) {
+    return null;
+  }
+  const consent = parseEventConsentSnapshot(o.consent);
+  if (!consent) return null;
+
+  return {
+    schemaVersion: RECEIPT_MEASUREMENT_GRANT_SCHEMA_VERSION,
+    provider: o.provider,
+    tenant: o.tenant,
+    environment: o.environment as IntegrationEnvironment,
+    correlationId: o.correlationId,
+    correlationExpiresAt: o.correlationExpiresAt,
+    consent,
+  };
+}
+
+/** The trusted receipt-origin context a consumed grant is re-checked against. */
+export interface ReceiptMeasurementContext {
+  /** The tenant, from the receipt read's trusted context. */
+  tenant: string;
+  /** The stage, from the receipt read's trusted context. */
+  environment: IntegrationEnvironment;
+  /** Injectable wall clock in ms (defaults to `Date.now()`). */
+  now?: number;
+}
+
+/**
+ * The consume-side gate on the receipt origin. `enabled: true` means browser
+ * measurement may fire with the parsed grant; `enabled: false` means it must not (the
+ * server conversion already covers it). `malformed` is a grant that failed the
+ * fail-closed parse.
+ */
+export type ReceiptMeasurementGate =
+  | { enabled: true; grant: ReceiptMeasurementGrant }
+  | { enabled: false; reason: ReceiptMeasurementDenyReason | "malformed" };
+
+/**
+ * Re-validate a propagated grant on the receipt origin before any browser measurement
+ * fires — defense-in-depth across the domain boundary, independent of the producer.
+ * Fail-closed: it re-checks that analytics consent still travels with the grant, that
+ * the grant is bound to THIS tenant/stage (env-consistency — a staged grant can never
+ * enable a live receipt read), and that the correlation thread has not expired. Any
+ * failure ⇒ `enabled: false` ⇒ server-side conversion only.
+ */
+export function receiptMeasurementEnabled(
+  rawGrant: unknown,
+  ctx: ReceiptMeasurementContext,
+): ReceiptMeasurementGate {
+  const grant = parseReceiptMeasurementGrant(rawGrant);
+  if (!grant) return { enabled: false, reason: "malformed" };
+
+  // Q3 consent must STILL travel with the grant.
+  if (!grant.consent.eligiblePurposes.includes(RECEIPT_MEASUREMENT_CONSENT_PURPOSE)) {
+    return { enabled: false, reason: "analytics-consent-required" };
+  }
+
+  // Env-consistency: the grant is bound to the tenant/stage it was minted in; a
+  // cross-tenant or cross-stage grant can never enable measurement here.
+  if (grant.tenant !== ctx.tenant || grant.environment !== ctx.environment) {
+    return { enabled: false, reason: "context-mismatch" };
+  }
+
+  const expMs = parseIsoMs(grant.correlationExpiresAt);
+  const nowMs = ctx.now ?? Date.now();
+  if (expMs === null || nowMs >= expMs) {
+    return { enabled: false, reason: "correlation-expired" };
+  }
+
+  return { enabled: true, grant };
+}

package/packages/public-runtime/src/integration/regulated-parent-cert.ts

@@ -0,0 +1,311 @@
+/**
+ * Regulated elevated-parent CERTIFICATION enforcement (ext-policy-07; ADR 0016 G2,
+ * ADR 0023 Q6, decision `integration-sandbox-first-surface-matrix`).
+ *
+ * Full parent authority (`elevated-parent`) is a review-only tier — its DOM reach
+ * is not enforceably narrow. On a `regulated` surface it is therefore DISABLED BY
+ * DEFAULT and may run ONLY behind a green certification that:
+ *
+ *   (a) ADVERSARIALLY proves EACH server-derived compliance obligation (ext-policy-04)
+ *       is satisfied — fail-closed on any obligation that is unproven, absent, or
+ *       merely asserted without a withstood adversarial challenge;
+ *   (b) is IMMUTABLY PINNED to an exact content digest — a mutable container (no
+ *       pinned digest, a malformed digest, or merchant-mutable parent code) is
+ *       INELIGIBLE and rejected, never "certified" (Q6);
+ *   (c) auto-disables on any DRIFT — the digest actually being served must equal the
+ *       certified pinned digest, or the certification no longer holds;
+ *   (d) never certifies mutable parent code on regulated regardless of anything else.
+ *
+ * This module does NOT re-implement the assurance or promotion layers — it PRODUCES
+ * the `certifiedImmutable` flag those layers already consume:
+ *   - `IntegrationContext.certifiedImmutable` (../integration-capabilities.ts), which
+ *     turns the `cert-required` matrix cell from `elevated-parent-uncertified` into a
+ *     grant; and
+ *   - `AssuranceDecisionContext.certifiedImmutable` (./assurance-decision.ts), the G2
+ *     clause that a regulated elevated-parent record needs proof, never a mere
+ *     acknowledgement.
+ * The required obligation set is SERVER-DERIVED from authoritative tenant config via
+ * ext-policy-04's `resolveObligationIds` / `verifyObligationCoverage` — never taken
+ * from the (spoofable) certificate — so nothing external can drop a duty.
+ */
+import type { CodeForm, Surface } from "../integration-capabilities.js";
+import {
+  isRegulated,
+  resolveObligationIds,
+  verifyObligationCoverage,
+  type ObligationTenant,
+} from "../compliance-obligations.js";
+import { digestValue } from "./digest.js";
+import type { ExecutionTier } from "./phases.js";
+
+/** Contract token — bump the minor for additive vocabulary, the major for a break (ADR 0006 semver). */
+export const REGULATED_PARENT_CERT_MODEL = "regulated-parent-cert-model@1" as const;
+export type RegulatedParentCertModel = typeof REGULATED_PARENT_CERT_MODEL;
+
+/**
+ * The outcome of an adversarial challenge run against one obligation. Only
+ * `withstood` — the obligation held under an active attempt to bypass it — is
+ * accepted. `breached` (the attempt succeeded) and `not-run` (no adversarial test
+ * was performed) both fail closed: an unproven obligation is never "satisfied".
+ */
+export const OBLIGATION_PROOF_RESULTS = ["withstood", "breached", "not-run"] as const;
+export type ObligationProofResult = (typeof OBLIGATION_PROOF_RESULTS)[number];
+
+/**
+ * The adversarial proof for a single compliance obligation. It is not a claim that
+ * the duty is met — it is evidence that an adversarial challenge tried to defeat the
+ * duty and could not. `evidenceDigest` pins that evidence to exact content so the
+ * proof cannot be swapped after review.
+ */
+export interface ObligationProof {
+  /** The obligation this proves — must be a server-recognized obligation id (ext-policy-04). */
+  obligationId: string;
+  /** The adversarial challenge that was run (what attack the obligation withstood). Non-empty. */
+  adversarialChallenge: string;
+  /** The challenge outcome. Anything other than `withstood` fails closed. */
+  result: ObligationProofResult;
+  /** Content digest pinning the evidence backing this proof. Must be a well-formed pinned digest. */
+  evidenceDigest: string;
+}
+
+/**
+ * A regulated elevated-parent certification artifact. It is bound to one app+version,
+ * pinned to one immutable content digest, scoped to the `regulated` surface and the
+ * `elevated-parent` tier, and carries one adversarial proof per applicable obligation.
+ */
+export interface RegulatedParentCertification {
+  model: RegulatedParentCertModel;
+  appId: string;
+  version: string;
+  /** Must be `regulated`; a certificate for any other surface does not enable regulated parent code. */
+  surface: Surface;
+  /** Must be `elevated-parent`; this certification exists only for full-parent authority. */
+  executionTier: ExecutionTier;
+  /** Must be `pinned-immutable`; `mutable-container` is prohibited on regulated (Q6). */
+  codeForm: CodeForm;
+  /** The exact content digest the certified artifact is immutably pinned to. */
+  pinnedDigest: string;
+  /** One adversarial proof per applicable compliance obligation (ext-policy-04). */
+  proofs: readonly ObligationProof[];
+  certifierId: string;
+  certifiedAt: string;
+}
+
+/** Server-resolved evaluation context for a certification decision. */
+export interface RegulatedParentCertContext {
+  /** The tenant's authoritative config — the ONLY source of the required obligation set + regulated classification. */
+  tenant: ObligationTenant;
+  /**
+   * The content digest of the artifact currently resolved to serve. When present and
+   * different from the certified `pinnedDigest`, the served code has DRIFTED from what
+   * was certified and enablement auto-disables (c).
+   */
+  servedDigest?: string;
+  /**
+   * The integration being evaluated. A certificate whose app/version does not match is
+   * for a different artifact and does not cover this one.
+   */
+  binding?: { appId: string; version: string };
+}
+
+export type RegulatedParentCertDenialReason =
+  /** The tenant is not on the regulated surface — this certification gate does not apply here. */
+  | "not-regulated"
+  /** No certification supplied — regulated elevated-parent is disabled by default (a). */
+  | "certificate-absent"
+  | "unknown-model"
+  | "wrong-surface"
+  | "not-elevated-parent"
+  /** Merchant-mutable parent code — prohibited on regulated regardless (b/d). */
+  | "mutable-parent-prohibited"
+  /** No exact content digest (or a malformed one) — a mutable container is ineligible (b). */
+  | "unpinned"
+  /** The certificate is for a different app/version than the integration under evaluation. */
+  | "binding-mismatch"
+  /** The served digest differs from the certified pinned digest — drift (c). */
+  | "digest-drift"
+  /** ext-policy-04 coverage failed (absent / unknown / duplicated / omitted obligation). */
+  | "obligation-coverage"
+  /** A server-required obligation carries no proof at all (a). */
+  | "obligation-unproven"
+  /** A required obligation's proof did not withstand its adversarial challenge (a). */
+  | "proof-not-adversarial"
+  /** A required obligation's proof evidence is not pinned to exact content. */
+  | "proof-evidence-unpinned";
+
+export interface RegulatedParentCertDenial {
+  reason: RegulatedParentCertDenialReason;
+  /** The offending value (obligation id, digest, surface, tier, or a coverage message), when one applies. */
+  subject?: string;
+}
+
+/**
+ * The certification decision. `certifiedImmutable` is the single boolean the assurance
+ * and capability layers consume: it is `true` ONLY on the `ok` branch, so a regulated
+ * elevated-parent integration is enabled exactly when every clause above holds.
+ */
+export type RegulatedParentCertDecision =
+  | {
+      ok: true;
+      certifiedImmutable: true;
+      certification: RegulatedParentCertification;
+      /** The server-derived obligations proven under adversarial challenge (canonical order). */
+      provenObligations: string[];
+    }
+  | { ok: false; certifiedImmutable: false; denials: RegulatedParentCertDenial[] };
+
+// A pinned digest is either the runtime's own FNV-1a-128 identity digest (32 lowercase
+// hex chars) or an algorithm-prefixed content hash (e.g. `sha256:<hex>`). A mutable
+// container has neither. Anything else is treated as unpinned and fails closed.
+const FNV128_HEX = /^[0-9a-f]{32}$/;
+const ALGO_DIGEST = /^[a-z][a-z0-9-]*:[0-9a-f]{16,}$/;
+
+/** True when a string is a well-formed immutable content digest (never a mutable container). */
+export function isPinnedDigest(digest: string | null | undefined): boolean {
+  return typeof digest === "string" && (FNV128_HEX.test(digest) || ALGO_DIGEST.test(digest));
+}
+
+/**
+ * Compute the runtime's deterministic content digest for an artifact — the value a
+ * certifier pins and a mount's served-digest is compared against. Reuses the shared
+ * identity primitive (./digest.ts) so a pin and a drift check fold the same bytes.
+ */
+export function computeArtifactDigest(content: unknown): string {
+  return digestValue(content);
+}
+
+/** True when a served artifact has drifted from what was certified (c). */
+export function isCertifiedDigestDrift(
+  certification: RegulatedParentCertification,
+  servedDigest: string | undefined,
+): boolean {
+  return servedDigest !== undefined && servedDigest !== certification.pinnedDigest;
+}
+
+/** True when a single obligation proof is an accepted adversarial, evidence-pinned proof. */
+function isAcceptedProof(proof: ObligationProof | undefined): boolean {
+  return (
+    !!proof &&
+    proof.result === "withstood" &&
+    proof.adversarialChallenge.trim().length > 0 &&
+    isPinnedDigest(proof.evidenceDigest)
+  );
+}
+
+/**
+ * Decide whether a regulated elevated-parent integration may be enabled. Fail-closed
+ * and non-short-circuiting: every clause runs and EVERY reason is accumulated, so the
+ * operator sees the complete set of what to fix. `certifiedImmutable` is `true` only
+ * when nothing objected — feed it straight into `IntegrationContext` /
+ * `AssuranceDecisionContext`.
+ *
+ * The gate applies to REGULATED tenants only. A non-regulated tenant returns
+ * `not-regulated` (this is not its enablement path — see the outside-guarantee posture
+ * in ./assurance-decision.ts); it never produces a trivially-true certification.
+ */
+export function decideRegulatedParentCert(
+  certification: RegulatedParentCertification | null | undefined,
+  context: RegulatedParentCertContext,
+): RegulatedParentCertDecision {
+  // The gate is scoped to the regulated surface. Elsewhere, `certifiedImmutable` is
+  // not the enablement lever, so this gate declines rather than certifies.
+  if (!isRegulated(context.tenant)) {
+    return { ok: false, certifiedImmutable: false, denials: [{ reason: "not-regulated" }] };
+  }
+
+  // Disabled by default: absent certification ⇒ disabled (a).
+  if (!certification) {
+    return { ok: false, certifiedImmutable: false, denials: [{ reason: "certificate-absent" }] };
+  }
+
+  const denials: RegulatedParentCertDenial[] = [];
+
+  if (certification.model !== REGULATED_PARENT_CERT_MODEL) {
+    denials.push({ reason: "unknown-model", subject: String(certification.model) });
+  }
+  if (certification.surface !== "regulated") {
+    denials.push({ reason: "wrong-surface", subject: certification.surface });
+  }
+  if (certification.executionTier !== "elevated-parent") {
+    denials.push({ reason: "not-elevated-parent", subject: certification.executionTier });
+  }
+
+  // (b)/(d) Immutable pinning. Merchant-mutable parent code is never
+  // certifiable on regulated — it is rejected, never "certified".
+  if (certification.codeForm === "mutable-container") {
+    denials.push({ reason: "mutable-parent-prohibited", subject: certification.codeForm });
+  } else if (certification.codeForm !== "pinned-immutable") {
+    denials.push({ reason: "unpinned", subject: certification.codeForm });
+  }
+  if (!isPinnedDigest(certification.pinnedDigest)) {
+    denials.push({ reason: "unpinned", subject: certification.pinnedDigest || "(absent)" });
+  }
+
+  // The certificate must cover the integration actually being evaluated.
+  if (context.binding) {
+    if (context.binding.appId !== certification.appId) {
+      denials.push({ reason: "binding-mismatch", subject: certification.appId });
+    }
+    if (context.binding.version !== certification.version) {
+      denials.push({ reason: "binding-mismatch", subject: certification.version });
+    }
+  }
+
+  // (c) Drift ⇒ auto-disable: the served digest must equal the certified pinned digest.
+  if (isCertifiedDigestDrift(certification, context.servedDigest)) {
+    denials.push({ reason: "digest-drift", subject: context.servedDigest });
+  }
+
+  // (a) Adversarial per-obligation proof of the SERVER-derived required set. First
+  // reuse the ext-policy-04 coverage authority (absent / unknown / duplicated /
+  // omitted), then require each required obligation carry a withstood, evidence-pinned
+  // proof — a mere present-and-known proof is not enough.
+  const proofIds = certification.proofs.map((p) => p.obligationId);
+  const coverage = verifyObligationCoverage(context.tenant, proofIds);
+  if (!coverage.ok) {
+    for (const blocker of coverage.blockers) {
+      denials.push({ reason: "obligation-coverage", subject: blocker });
+    }
+  }
+
+  const proofById = new Map<string, ObligationProof>();
+  for (const proof of certification.proofs) {
+    if (!proofById.has(proof.obligationId)) proofById.set(proof.obligationId, proof);
+  }
+  const required = resolveObligationIds(context.tenant);
+  for (const id of required) {
+    const proof = proofById.get(id);
+    if (!proof) {
+      denials.push({ reason: "obligation-unproven", subject: id });
+      continue;
+    }
+    if (proof.result !== "withstood" || proof.adversarialChallenge.trim().length === 0) {
+      denials.push({ reason: "proof-not-adversarial", subject: id });
+    }
+    if (!isPinnedDigest(proof.evidenceDigest)) {
+      denials.push({ reason: "proof-evidence-unpinned", subject: id });
+    }
+  }
+
+  if (denials.length > 0) {
+    return { ok: false, certifiedImmutable: false, denials };
+  }
+  return { ok: true, certifiedImmutable: true, certification, provenObligations: required };
+}
+
+/**
+ * True iff a regulated elevated-parent integration is enabled by this certification —
+ * the boolean `IntegrationContext.certifiedImmutable` / `AssuranceDecisionContext
+ * .certifiedImmutable` expect. Disabled by default: any absent, unpinned, drifted, or
+ * incompletely-proven certification yields `false`.
+ */
+export function isRegulatedParentCertified(
+  certification: RegulatedParentCertification | null | undefined,
+  context: RegulatedParentCertContext,
+): boolean {
+  return decideRegulatedParentCert(certification, context).certifiedImmutable;
+}
+
+// `isAcceptedProof` is exported for downstream review UIs that render per-proof status
+// without re-deriving the whole decision.
+export { isAcceptedProof };