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

package/packages/public-runtime/src/integration/promotion-gate.ts

@@ -0,0 +1,451 @@
+/**
+ * The unifying, fail-closed integration PROMOTION gate (ext-policy-06).
+ *
+ * ONE gate that an integration promotion must pass before its plan can reach a
+ * staged/live pointer. It does not invent a second opinion — it COMPOSES the
+ * fail-closed verifiers each upstream card already owns and refuses promotion on
+ * ANY of their failures:
+ *
+ *   - ext-policy-02  {@link compileIntegrationCspFromPlan} — the plan's curated
+ *     profiles + advanced origins must compile under the exact-origin grammar; a
+ *     wildcard / bare scheme / `unsafe-*` / `strict-dynamic` / unknown directive is
+ *     an INVALID policy and is rejected here, before any flip.
+ *   - ext-policy-03  the consent broker's {@link ConsentSnapshot} — every
+ *     non-essential purpose the plan depends on must be eligible under a well-formed
+ *     (default-deny, `unknownState:"block"`) snapshot; a forged/absent snapshot
+ *     fails closed.
+ *   - ext-policy-04  {@link verifyObligationCoverage} — the SERVER-derived required
+ *     obligation set (never the candidate's declaration) must be completely,
+ *     unambiguously covered; a regulated tenant cannot ship with an omitted duty.
+ *   - ext-policy-05  {@link decideAssurance} — an elevated-parent integration needs
+ *     an approvable assurance record; the regulated floor is non-waivable.
+ *   - ext-kernel-06  {@link verifyCandidatePromotable} (which calls
+ *     {@link verifyServedParity}) — the evidence must EQUAL what a mount actually
+ *     served; an unobserved served output, a forged asset, secret material, or a
+ *     `live` candidate blocks.
+ *   - ext-prereq-03  {@link verifyPromotionEvidence} — the compliance-evidence check
+ *     set (age_gate / excise / jurisdiction) must be complete, matching, fresh, and
+ *     all-passing against the server-derived {@link REQUIRED_FOR_PROMOTE}.
+ *
+ * Fail-closed and non-short-circuiting: every composed verdict runs and EVERY reason
+ * is accumulated, so the diagnostics are complete and actionable. `ok` is true only
+ * when nothing objected.
+ *
+ * VERSION-BOUND (the rollback-safety property): every artifact the gate reads — the
+ * plan, its freshly-compiled CSP, and the candidate evidence — must bind to the SAME
+ * `planRevision` (and the caller's `expectedPlanRevision`, when given). A stale
+ * artifact left over from a superseded version carries a different revision and is
+ * rejected, so a promote — or a rollback that re-promotes a prior version — can never
+ * ride another version's cached CSP/evidence.
+ *
+ * SECRET-SAFE DIAGNOSTICS: the assembled diagnostics are scanned with
+ * {@link findForbiddenFields} before they leave the gate; a diagnostic payload that
+ * names secret material is redacted AND turns the verdict closed, so an operator
+ * report can never leak a nonce/token/credential.
+ */
+import {
+  verifyObligationCoverage,
+  resolveObligationIds,
+  isRegulated,
+  type ObligationTenant,
+} from "../compliance-obligations.js";
+import { verifyCandidatePromotable } from "./candidate-evidence.js";
+import type {
+  IntegrationCandidateEvidence,
+  ServedObservation,
+} from "./candidate-evidence.js";
+import { decideAssurance } from "./assurance-decision.js";
+import type { AssuranceDecisionContext } from "./assurance-decision.js";
+import {
+  decideRegulatedParentCert,
+  type RegulatedParentCertification,
+} from "./regulated-parent-cert.js";
+import {
+  compileIntegrationCspFromPlan,
+  type IntegrationCspAdditions,
+} from "./csp-compiler.js";
+import { findForbiddenFields } from "./secrets.js";
+import {
+  defaultConsentSnapshot,
+  parseConsentSnapshot,
+  isPurposeEligible,
+  type ConsentSnapshot,
+} from "./consent-broker.js";
+import type { EffectivePlan } from "./plan.js";
+import type { ComplianceAssuranceRecord } from "./assurance.js";
+import type { ContractViolation } from "./result.js";
+import {
+  verifyPromotionEvidence,
+  REQUIRED_FOR_PROMOTE,
+  PROMOTION_EVIDENCE_MAX_AGE_MS,
+  type PromotionEvidenceCheck,
+} from "../evidence.js";
+
+/** Everything the unifying gate needs to decide whether an integration may promote. */
+export interface IntegrationPromotionGateInput {
+  /**
+   * The version this promotion is FOR. When set, the plan, its compiled CSP, and the
+   * candidate evidence must all bind to this exact revision — the rollback-safety
+   * anchor. Omit to only require the three artifacts agree with each other.
+   */
+  expectedPlanRevision?: string;
+
+  /** The tenant's authoritative config — the ONLY source of the required obligations + regulated classification. */
+  tenant: ObligationTenant;
+
+  /** The resolved effective plan for the candidate being promoted (ext-kernel-03). */
+  plan: EffectivePlan | null | undefined;
+
+  /** Curated CSP profile slugs declared across the plan's integrations (ext-policy-02). */
+  cspProfiles?: readonly string[];
+
+  /** The candidate evidence derived from the plan (ext-kernel-06). */
+  candidateEvidence: IntegrationCandidateEvidence | null | undefined;
+
+  /**
+   * What a mount ACTUALLY served for this candidate — the parity anchor
+   * {@link verifyServedParity} re-derives against (ext-kernel-06). `null` = the
+   * served output was not observed, itself a blocker (parity cannot be asserted).
+   */
+  served: ServedObservation | null;
+
+  /**
+   * A forge-response integrity failure from the reconcile that produced this
+   * candidate (ext-prereq-02), if one occurred. A forged/unreadable forge response
+   * can never become promotable.
+   */
+  forgeIntegrityError?: string | null;
+
+  /**
+   * The obligation ids the candidate/app DECLARES it satisfies. Verified against the
+   * server-derived floor ({@link resolveObligationIds}) — never trusted as the
+   * required set itself (ext-policy-04).
+   */
+  declaredObligationIds: readonly string[] | null | undefined;
+
+  /** The compliance-evidence checks measured for this candidate (ext-prereq-03). */
+  complianceChecks: readonly PromotionEvidenceCheck[] | null | undefined;
+  /** The compliance evidence's `generated_at` (ISO) — required to evaluate freshness. */
+  complianceGeneratedAt?: string;
+
+  /** The promote instant (ms epoch) freshness is measured against. */
+  now?: number;
+  /** Max compliance-evidence age before STALE (ms). Defaults to {@link PROMOTION_EVIDENCE_MAX_AGE_MS}. */
+  maxAgeMs?: number;
+
+  /**
+   * The SERVER-derived consent snapshot the plan's non-essential `consentNeeds` must
+   * each be eligible under (ext-policy-03). Absent ⇒ the default-deny snapshot, so
+   * any dependent purpose blocks — consent defaults precede dependent code.
+   */
+  consentSnapshot?: ConsentSnapshot;
+
+  /** The elevated-integration assurance record, when one resolved (ext-policy-05). */
+  assurance?: ComplianceAssuranceRecord | null;
+  /**
+   * The decision context for {@link decideAssurance} (wall clock, counsel flag, the
+   * resolved material state). Required when an `assurance` record is present — an
+   * expiry/material-change verdict cannot be reached without it.
+   *
+   * NOTE: its `certifiedImmutable` is NOT read as a raw external input. The gate
+   * OVERRIDES it with the value {@link decideRegulatedParentCert} derives from
+   * `regulatedParentCert` below, so no caller can assert a regulated elevated-parent
+   * integration is certified without a cert that actually clears every clause.
+   */
+  assuranceContext?: AssuranceDecisionContext;
+  /**
+   * The regulated elevated-parent certification artifact (ext-policy-07), when one is
+   * supplied. It is the SINGLE ORIGIN of `certifiedImmutable`: the gate runs
+   * {@link decideRegulatedParentCert} against the plan's elevated-parent integration
+   * (its served content digest as the drift anchor, its app/version as the binding) and
+   * feeds the decision's boolean into the assurance context. Absent/failed ⇒ false ⇒
+   * a regulated elevated-parent integration is denied `regulated-cert-missing`.
+   */
+  regulatedParentCert?: RegulatedParentCertification | null;
+}
+
+/** One composed verdict, flattened to the `{ ok, blockers }` family the gate aggregates. */
+export interface IntegrationGateSubVerdict {
+  ok: boolean;
+  blockers: string[];
+}
+
+/** The structured, secret-scanned diagnostics an operator reads to fix a blocked promotion. */
+export interface IntegrationPromotionDiagnostics {
+  version: {
+    expected: string | null;
+    plan: string | null;
+    candidate: string | null;
+    csp: string | null;
+    consistent: boolean;
+  };
+  csp: IntegrationGateSubVerdict;
+  candidate: IntegrationGateSubVerdict;
+  obligations: IntegrationGateSubVerdict & { regulated: boolean; required: string[] };
+  compliance: IntegrationGateSubVerdict;
+  consent: IntegrationGateSubVerdict;
+  assurance: IntegrationGateSubVerdict;
+  /**
+   * The resolved per-integration public config under review — echoed so an operator
+   * can inspect exactly what the plan carries. This is the app-declared, nested,
+   * open-value structure the diagnostics secret-scan defends: a field naming secret
+   * material here (a leak the resolver should have caught) redacts the whole payload.
+   */
+  publicConfig: Record<string, Record<string, unknown>>;
+}
+
+export interface IntegrationPromotionVerdict {
+  /** True only when EVERY composed verifier passed and the diagnostics carried no secret. */
+  ok: boolean;
+  /** Every reason this integration may not promote (empty ⇔ ok). */
+  blockers: string[];
+  /**
+   * The structured diagnostics — secret-scanned. Replaced by `{ redacted: true }`
+   * (and the verdict forced closed) if any diagnostic field named secret material.
+   */
+  diagnostics: IntegrationPromotionDiagnostics | { redacted: true };
+}
+
+/**
+ * The single fail-CLOSED authority for "may this integration reach a staged/live
+ * pointer?". Composes the six upstream verifiers; refuses on any failure. See the
+ * file header for the property each clause holds.
+ */
+export function verifyIntegrationPromotable(
+  input: IntegrationPromotionGateInput,
+): IntegrationPromotionVerdict {
+  const blockers: string[] = [];
+  const { plan, candidateEvidence } = input;
+
+  // ── Version binding (rollback-safety) ────────────────────────────────────
+  // A freshly-compiled CSP for THIS plan is the pre-release fail-closed floor
+  // (ext-policy-02): an invalid policy yields violations and no additions, and is
+  // rejected before any flip. Compiling here (not trusting the evidence's embedded
+  // additions) re-validates the plan's CSP independently at promote time.
+  const csp = plan
+    ? compileIntegrationCspFromPlan(plan, input.cspProfiles ?? [])
+    : null;
+
+  const expected = input.expectedPlanRevision ?? null;
+  const planRev = plan?.planRevision ?? null;
+  const candidateRev = candidateEvidence?.planRevision ?? null;
+  const cspRev = csp?.ok ? csp.value.planRevision : null;
+  const revs = [planRev, candidateRev, cspRev].filter((r): r is string => r != null);
+  const versionConsistent =
+    revs.length > 0 &&
+    revs.every((r) => r === revs[0]) &&
+    (expected == null || revs.every((r) => r === expected));
+  if (!versionConsistent) {
+    blockers.push(
+      `Version mismatch: plan="${planRev ?? "(absent)"}", candidate="${candidateRev ?? "(absent)"}", ` +
+        `csp="${cspRev ?? "(absent)"}"${expected ? `, expected="${expected}"` : ""} — every promotion ` +
+        `artifact must bind to one plan revision (a stale artifact from a superseded version is rejected).`,
+    );
+  }
+
+  // ── ext-policy-02: CSP fail-closed ───────────────────────────────────────
+  const cspSub: IntegrationGateSubVerdict = { ok: true, blockers: [] };
+  const cspViolations: ContractViolation[] = [];
+  if (!plan) {
+    cspSub.ok = false;
+    cspSub.blockers.push("No effective plan supplied — nothing to compile or promote.");
+  } else if (csp && !csp.ok) {
+    cspSub.ok = false;
+    for (const v of csp.violations) {
+      cspViolations.push(v);
+      cspSub.blockers.push(`Invalid integration CSP at ${v.path}: ${v.message}`);
+    }
+  } else if (csp?.ok && candidateEvidence) {
+    // Defense in depth: the promote-time recompile must equal the CSP the evidence
+    // (and therefore the served response) carries — otherwise the plan would ship a
+    // policy the operator never reviewed as evidence.
+    if (canonicalCspKey(csp.value.additions) !== canonicalCspKey(candidateEvidence.cspAdditions)) {
+      cspSub.ok = false;
+      cspSub.blockers.push(
+        "Recompiled integration CSP differs from the candidate evidence's CSP additions.",
+      );
+    }
+  }
+  blockers.push(...cspSub.blockers);
+
+  // ── ext-kernel-06: candidate ⇔ served parity, assets, secrets, not-live ──
+  const candidateSub: IntegrationGateSubVerdict = candidateEvidence
+    ? verifyCandidatePromotable(candidateEvidence, input.served, {
+        forgeIntegrityError: input.forgeIntegrityError,
+      })
+    : { ok: false, blockers: ["No candidate evidence supplied — parity with the served output is unprovable."] };
+  blockers.push(...candidateSub.blockers);
+
+  // ── ext-policy-04: obligation coverage (server-derived, regulated floor) ──
+  const obligationVerdict = verifyObligationCoverage(input.tenant, input.declaredObligationIds);
+  const obligationsSub = {
+    ok: obligationVerdict.ok,
+    blockers: obligationVerdict.blockers,
+    regulated: isRegulated(input.tenant),
+    required: resolveObligationIds(input.tenant),
+  };
+  blockers.push(...obligationsSub.blockers);
+
+  // ── ext-prereq-03: compliance evidence (age_gate / excise / jurisdiction) ─
+  const complianceVerdict = verifyPromotionEvidence(input.complianceChecks, {
+    requiredIds: REQUIRED_FOR_PROMOTE,
+    generatedAt: input.complianceGeneratedAt,
+    now: input.now,
+    maxAgeMs: input.maxAgeMs ?? PROMOTION_EVIDENCE_MAX_AGE_MS,
+  });
+  blockers.push(...complianceVerdict.blockers);
+
+  // ── ext-policy-03: consent order (defaults precede, unknown blocks) ───────
+  const consentSub = verifyConsentOrder(plan, input.consentSnapshot);
+  blockers.push(...consentSub.blockers);
+
+  // ── ext-policy-05: assurance for an elevated-parent integration ───────────
+  // `certifiedImmutable` has a SINGLE ORIGIN: derive it from the certification decision
+  // (never trust a raw external flag on the context) and OVERRIDE the context with it,
+  // so no caller can bypass the decision by asserting `certifiedImmutable: true`.
+  const derivedCertifiedImmutable = deriveRegulatedParentCertified(
+    plan,
+    input.tenant,
+    input.regulatedParentCert,
+  );
+  const assuranceContext: AssuranceDecisionContext | undefined = input.assuranceContext
+    ? { ...input.assuranceContext, certifiedImmutable: derivedCertifiedImmutable }
+    : input.assuranceContext;
+  const assuranceSub = verifyAssurance(plan, input.assurance, assuranceContext);
+  blockers.push(...assuranceSub.blockers);
+
+  // ── Assemble + secret-scan the diagnostics ───────────────────────────────
+  const diagnostics: IntegrationPromotionDiagnostics = {
+    version: { expected, plan: planRev, candidate: candidateRev, csp: cspRev, consistent: versionConsistent },
+    csp: { ok: cspSub.ok, blockers: cspSub.blockers },
+    candidate: candidateSub,
+    obligations: obligationsSub,
+    compliance: complianceVerdict,
+    consent: consentSub,
+    assurance: assuranceSub,
+    publicConfig: plan?.publicConfig ?? {},
+  };
+
+  // The diagnostics are an operator-facing, potentially-serialized surface. Any field
+  // whose NAME denotes secret material (a leak from a composed verifier's payload) is
+  // never allowed out: redact the whole payload and fail the gate closed.
+  const forbidden = findForbiddenFields(diagnostics, "diagnostics");
+  if (forbidden.length > 0) {
+    blockers.push(
+      `Gate diagnostics named secret material (${forbidden.map((f) => f.path).join(", ")}) and were redacted.`,
+    );
+    return { ok: false, blockers, diagnostics: { redacted: true } };
+  }
+
+  return { ok: blockers.length === 0, blockers, diagnostics };
+}
+
+/**
+ * Every non-essential consent purpose the plan depends on must be eligible under a
+ * well-formed, default-deny snapshot. An absent snapshot is the default-deny floor
+ * (only `essential`), so any dependent purpose blocks — consent defaults precede
+ * dependent code. A forged/tampered snapshot (fails the canonical round-trip) blocks.
+ */
+function verifyConsentOrder(
+  plan: EffectivePlan | null | undefined,
+  snapshot: ConsentSnapshot | undefined,
+): IntegrationGateSubVerdict {
+  const blockers: string[] = [];
+  if (!plan) return { ok: true, blockers };
+
+  const effective = snapshot ?? defaultConsentSnapshot();
+  // Fail closed on a forged snapshot: the canonical parse recomputes the snapshotId
+  // from the eligible set and rejects a mismatched, unknown-state, or unknown-purpose
+  // payload — a caller cannot smuggle in a snapshot that grants a purpose it should not.
+  if (parseConsentSnapshot(effective) === null) {
+    blockers.push("Consent snapshot is malformed or forged — its eligibility cannot be trusted.");
+    return { ok: false, blockers };
+  }
+  if (effective.unknownState !== "block") {
+    blockers.push("Consent snapshot does not fail closed on unknown state.");
+  }
+  for (const purpose of plan.consentNeeds) {
+    if (!isPurposeEligible(effective, purpose)) {
+      blockers.push(
+        `Consent purpose "${purpose}" is required by the plan but not eligible under the approved snapshot.`,
+      );
+    }
+  }
+  return { ok: blockers.length === 0, blockers };
+}
+
+/**
+ * Assurance gates ONLY elevated-parent integrations. A sandbox/broker plan has no
+ * assurance obligation (clean pass). An elevated-parent integration with no record
+ * fails closed; with a record, `decideAssurance` must approve it (the regulated floor
+ * stays non-waivable, the vendor cannot self-approve, expiry/material-change apply).
+ */
+function verifyAssurance(
+  plan: EffectivePlan | null | undefined,
+  record: ComplianceAssuranceRecord | null | undefined,
+  context: AssuranceDecisionContext | undefined,
+): IntegrationGateSubVerdict {
+  const blockers: string[] = [];
+  const elevated = (plan?.integrations ?? []).some((i) => i.executionTier === "elevated-parent");
+
+  if (!elevated && !record) return { ok: true, blockers };
+
+  if (elevated && !record) {
+    blockers.push(
+      "An elevated-parent integration has no assurance record — full-parent authority cannot promote unacknowledged.",
+    );
+    return { ok: false, blockers };
+  }
+
+  if (record) {
+    if (!context) {
+      blockers.push("An assurance record is present but no decision context was supplied — expiry cannot be evaluated.");
+      return { ok: false, blockers };
+    }
+    const decision = decideAssurance(record, context);
+    if (!decision.ok) {
+      for (const denial of decision.denials) {
+        blockers.push(
+          `Assurance denied: ${denial.reason}${denial.subject ? ` (${denial.subject})` : ""}.`,
+        );
+      }
+    }
+  }
+  return { ok: blockers.length === 0, blockers };
+}
+
+/**
+ * Derive `certifiedImmutable` from the certification decision — the SINGLE ORIGIN of
+ * that flag (never a raw external boolean). Runs {@link decideRegulatedParentCert}
+ * against the plan's elevated-parent integration: its served content digest is the
+ * drift anchor and its app/version the binding, so a cert for a different artifact, an
+ * unpinned/mutable one, a drifted one, or one missing an adversarial obligation proof
+ * yields `false`. No elevated-parent integration ⇒ the flag is irrelevant and `false`
+ * (fail closed); a non-regulated tenant likewise decides `false` (the decision returns
+ * `not-regulated`), which the regulated-only assurance clause never consults.
+ */
+function deriveRegulatedParentCertified(
+  plan: EffectivePlan | null | undefined,
+  tenant: ObligationTenant,
+  cert: RegulatedParentCertification | null | undefined,
+): boolean {
+  const elevated = (plan?.integrations ?? []).find((i) => i.executionTier === "elevated-parent");
+  if (!elevated) return false;
+  return decideRegulatedParentCert(cert, {
+    tenant,
+    servedDigest: elevated.digest,
+    binding: { appId: elevated.appId, version: elevated.version },
+  }).certifiedImmutable;
+}
+
+/**
+ * Canonical key for compiled CSP additions. The compiler already sorts + dedupes
+ * origins per directive and omits empty directives, so ordering by directive name
+ * yields an equality key two identical additions share exactly.
+ */
+function canonicalCspKey(additions: IntegrationCspAdditions): string {
+  return Object.keys(additions)
+    .sort()
+    .map((d) => `${d}:${(additions[d as keyof IntegrationCspAdditions] ?? []).join(",")}`)
+    .join("|");
+}