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

package/packages/public-runtime/src/integration/candidate-evidence.ts

@@ -0,0 +1,377 @@
+/**
+ * Trustworthy integration-candidate evidence (ADR 0014 public-values-only,
+ * ADR 0018 nonce non-serialization; ext-kernel-06).
+ *
+ * Evidence is NOT a separate description of a candidate — it is DERIVED from the
+ * exact same inputs the mounts serve: the resolved {@link EffectivePlan}
+ * (ext-kernel-03), the fixed-phase render engine's emissions (ext-kernel-04,
+ * {@link renderIntegrationPhases}), the compiled CSP additions (ext-policy-02,
+ * {@link CompiledIntegrationCsp}), and the fail-closed materialized-asset verify
+ * (ext-prereq-01, {@link AssetVerificationResult}). So the evidence's served
+ * fingerprint is a property of calling the render engine, not a claim kept in sync
+ * with it.
+ *
+ * Three trust properties hold by construction:
+ *   1. PARITY — evidence equals what is served. {@link buildCandidateEvidence}
+ *      records a fingerprint (a digest over the nonce-free phase markup, the plan/
+ *      version cache identity, the environment stage, and the CSP origin diff);
+ *      {@link verifyServedParity} re-derives that fingerprint from what a mount
+ *      ACTUALLY served and reports every contradiction.
+ *   2. CONTRADICTIONS BLOCK PROMOTION — {@link verifyCandidatePromotable} is the
+ *      fail-closed gate (same {ok, blockers} shape as the promotion-evidence gate):
+ *      an unreadable/forged asset or forge response, a missing app asset, a
+ *      candidate that reports `live`, secret material, or ANY served-parity
+ *      contradiction leaves the candidate un-promotable. Unobserved served output
+ *      is itself a blocker — you cannot promote what you cannot prove is served.
+ *   3. PUBLIC VALUES ONLY — the assembled evidence is scanned with
+ *      {@link findForbiddenFields} (ext-kernel-01): a nonce, token, credential, or
+ *      signed URL makes the evidence invalid to build AND un-promotable.
+ *
+ * Consent and assurance surfaces are recorded from whatever the plan/record
+ * resolves today (ext-policy-03/05 fill them); the evidence FRAMEWORK surfaces the
+ * resolved state without inventing a value the plan does not carry.
+ */
+import type { ContractResult, ContractViolation } from "./result.js";
+import { findForbiddenFields } from "./secrets.js";
+import type { BrowserEnvironment, IntegrationEnvironment } from "./environment.js";
+import type { ReservedPhase, ExecutionTier, ContributionKind, EntryFormat } from "./phases.js";
+import type { IntegrationOrigin } from "./manifest.js";
+import type { AssuranceClassification } from "./manifest.js";
+import type { EffectivePlan } from "./plan.js";
+import { planCacheIdentity } from "./resolve.js";
+import {
+  renderIntegrationPhases,
+  IntegrationRenderError,
+  INTEGRATION_NONCE_PLACEHOLDER,
+  type IntegrationPhaseMarkup,
+} from "./render-phases.js";
+import type { CompiledIntegrationCsp, IntegrationCspAdditions } from "./csp-compiler.js";
+import type { ComplianceAssuranceRecord, AssuranceSurface } from "./assurance.js";
+import type { AssetVerificationResult } from "../tenant-assets.js";
+import { fnv1a128Hex, stableStringify } from "./digest.js";
+
+export const INTEGRATION_CANDIDATE_EVIDENCE_SCHEMA_VERSION = 1 as const;
+
+/**
+ * Asset-existence evidence: the public counts + missing served paths from the
+ * ext-prereq-01 verify. `unreadable` is set only when the verification itself could
+ * not run — a fail-closed non-pass, never treated as "materialized".
+ */
+export interface AssetExistenceEvidence {
+  expected: number;
+  verified: number;
+  missing: string[];
+  unreadable?: string;
+}
+
+/** The exact-version entry module surfaced in evidence — the URL the runtime loads. */
+export interface EvidenceEntryModule {
+  url: string;
+  format: EntryFormat;
+  phase: ReservedPhase;
+}
+
+/** One resolved integration, public identity only, plus the entry module it loads. */
+export interface EvidenceIntegration {
+  origin: IntegrationOrigin;
+  appId: string;
+  version: string;
+  digest: string;
+  executionTier: ExecutionTier;
+  /** The same-origin, exact-version entry module the lifecycle runtime imports. */
+  entry: EvidenceEntryModule;
+}
+
+/** One resolved contribution entry — public shape only; the executable source bytes never appear. */
+export interface EvidenceEntry {
+  id: string;
+  origin: IntegrationOrigin;
+  phase: ReservedPhase;
+  kind: ContributionKind;
+}
+
+/**
+ * The assurance state surfaced in evidence. `present:false` is the honest partial
+ * case (no elevated-integration record resolved yet); the sub-fields are the
+ * public, non-waivable floor — never an acknowledgement token or actor secret.
+ */
+export interface EvidenceAssurance {
+  present: boolean;
+  surface?: AssuranceSurface;
+  classification?: AssuranceClassification;
+  /** The regulated floor is non-waivable; always false when a record is present. */
+  regulatedSharedRuntimeWaiver?: false;
+  eligibleForOutsideGuarantee?: boolean;
+}
+
+/**
+ * The identity of exactly what the mounts serve for this plan — the parity anchor.
+ * `markupDigest` is over the NONCE-FREE (cache-template) phase markup, so cold
+ * (placeholder) and warm (stamped) served forms fingerprint identically and a live
+ * nonce is never part of the served identity (ADR 0018).
+ */
+export interface ServedFingerprint {
+  markupDigest: string;
+  planCacheIdentity: string;
+  environment: IntegrationEnvironment;
+  cspAdditions: IntegrationCspAdditions;
+}
+
+/** The full, tenant-scoped, public-values-only candidate evidence. */
+export interface IntegrationCandidateEvidence {
+  schemaVersion: typeof INTEGRATION_CANDIDATE_EVIDENCE_SCHEMA_VERSION;
+  tenantPublicId: string;
+  environment: BrowserEnvironment;
+  planRevision: string;
+  integrations: EvidenceIntegration[];
+  entries: EvidenceEntry[];
+  order: string[];
+  consentNeeds: string[];
+  /** Per-integration resolved public config; redaction is proved by the secret scan. */
+  publicConfig: Record<string, Record<string, unknown>>;
+  /** The CSP origin diff a live response's header carries beyond the strict base. */
+  cspAdditions: IntegrationCspAdditions;
+  assurance: EvidenceAssurance;
+  assets: AssetExistenceEvidence;
+  served: ServedFingerprint;
+}
+
+export interface BuildCandidateEvidenceInput {
+  /** The resolved plan (ext-kernel-03). */
+  plan: EffectivePlan;
+  /** The compiled CSP for THIS plan (ext-policy-02); its `planRevision` must match. */
+  compiledCsp: CompiledIntegrationCsp;
+  /** The fail-closed materialized-asset verify (ext-prereq-01). */
+  assets: AssetVerificationResult;
+  /** The elevated-integration assurance record, when one is resolved (ext-policy-05). */
+  assurance?: ComplianceAssuranceRecord | null;
+}
+
+/**
+ * Collapse any live CSP nonce attribute back to the placeholder and join the three
+ * phase regions, so the digest is over the nonce-free served identity — invariant
+ * across cold/warm responses (ADR 0018).
+ */
+export function canonicalizeServedMarkup(markup: IntegrationPhaseMarkup): string {
+  const joined = `${markup.head}\n${markup.bodyStart}\n${markup.bodyDeferred}`;
+  return joined.replace(/ nonce="[^"]*"/g, ` nonce="${INTEGRATION_NONCE_PLACEHOLDER}"`);
+}
+
+/** The served phase-markup digest for a resolved plan — the parity anchor both sides re-derive. */
+export function candidateServedMarkupDigest(plan: EffectivePlan): string {
+  return fnv1a128Hex(canonicalizeServedMarkup(renderIntegrationPhases(plan, INTEGRATION_NONCE_PLACEHOLDER)));
+}
+
+/**
+ * Derive candidate evidence from the resolved plan, compiled CSP, and asset verify.
+ * Fail-closed: a plan that cannot render (unknown phase, duplicate id, secret
+ * material), a CSP compiled for a different plan revision, or any secret field in
+ * the assembled evidence yields violations and NO evidence — never a partial claim.
+ */
+export function buildCandidateEvidence(
+  input: BuildCandidateEvidenceInput,
+): ContractResult<IntegrationCandidateEvidence> {
+  const { plan, compiledCsp, assets } = input;
+  const violations: ContractViolation[] = [];
+
+  if (compiledCsp.planRevision !== plan.planRevision) {
+    violations.push({
+      path: "compiledCsp.planRevision",
+      code: "plan_revision_mismatch",
+      message:
+        `Compiled CSP is bound to plan revision "${compiledCsp.planRevision}" but the plan ` +
+        `resolved to "${plan.planRevision}"; evidence must derive from one plan.`,
+    });
+  }
+
+  // Derive the served fingerprint from the SAME render engine both mounts call.
+  // An unrenderable plan cannot become promotable — surface why, fail closed.
+  let markupDigest: string;
+  try {
+    markupDigest = fnv1a128Hex(
+      canonicalizeServedMarkup(renderIntegrationPhases(plan, INTEGRATION_NONCE_PLACEHOLDER)),
+    );
+  } catch (err) {
+    if (err instanceof IntegrationRenderError) {
+      for (const reason of err.violations) {
+        violations.push({ path: "plan", code: "render_blocked", message: reason });
+      }
+      return { ok: false, violations };
+    }
+    throw err;
+  }
+
+  const evidence: IntegrationCandidateEvidence = {
+    schemaVersion: INTEGRATION_CANDIDATE_EVIDENCE_SCHEMA_VERSION,
+    tenantPublicId: plan.tenantPublicId,
+    environment: plan.environment,
+    planRevision: plan.planRevision,
+    integrations: plan.integrations.map((i) => ({
+      origin: i.origin,
+      appId: i.appId,
+      version: i.version,
+      digest: i.digest,
+      executionTier: i.executionTier,
+      entry: { url: i.entry.url, format: i.entry.format, phase: i.entry.phase },
+    })),
+    entries: plan.contributions.map((c) => ({
+      id: c.id,
+      origin: c.origin,
+      phase: c.phase,
+      kind: c.kind,
+    })),
+    order: [...plan.order],
+    consentNeeds: [...plan.consentNeeds],
+    publicConfig: plan.publicConfig,
+    cspAdditions: compiledCsp.additions,
+    assurance: summarizeAssurance(input.assurance),
+    assets: summarizeAssets(assets),
+    served: {
+      markupDigest,
+      planCacheIdentity: planCacheIdentity(plan),
+      environment: plan.environment.environment,
+      cspAdditions: compiledCsp.additions,
+    },
+  };
+
+  // Public-values-only: no nonce, token, credential, or signed URL anywhere in the
+  // assembled evidence. Defense in depth beyond the closed plan/CSP contracts.
+  for (const violation of findForbiddenFields(evidence, "evidence")) violations.push(violation);
+
+  if (violations.length > 0) return { ok: false, violations };
+  return { ok: true, value: evidence };
+}
+
+function summarizeAssurance(record: ComplianceAssuranceRecord | null | undefined): EvidenceAssurance {
+  if (!record) return { present: false };
+  return {
+    present: true,
+    surface: record.surface,
+    classification: record.classification,
+    regulatedSharedRuntimeWaiver: record.compliance.regulatedSharedRuntimeWaiver,
+    eligibleForOutsideGuarantee: record.compliance.eligibleForOutsideGuarantee,
+  };
+}
+
+function summarizeAssets(result: AssetVerificationResult): AssetExistenceEvidence {
+  return {
+    expected: result.expected,
+    verified: result.verified,
+    missing: [...result.missing],
+    ...(result.error ? { unreadable: result.error } : {}),
+  };
+}
+
+/**
+ * What a mount ACTUALLY served for a candidate, as observed off the wire/cache. The
+ * markup may be in cold (placeholder) or warm (live nonce) form — parity
+ * canonicalizes both to the nonce-free identity.
+ */
+export interface ServedObservation {
+  markup: IntegrationPhaseMarkup;
+  planCacheIdentity: string;
+  environment: IntegrationEnvironment;
+  cspAdditions: IntegrationCspAdditions;
+}
+
+export interface ParityResult {
+  ok: boolean;
+  contradictions: string[];
+}
+
+/**
+ * Re-derive the served fingerprint from what a mount actually served and report
+ * every field that contradicts the evidence. Equal fingerprint ⇒ the evidence IS
+ * the served candidate; any contradiction is a promotion blocker.
+ */
+export function verifyServedParity(
+  evidence: IntegrationCandidateEvidence,
+  served: ServedObservation,
+): ParityResult {
+  const contradictions: string[] = [];
+
+  const observedDigest = fnv1a128Hex(canonicalizeServedMarkup(served.markup));
+  if (observedDigest !== evidence.served.markupDigest) {
+    contradictions.push(
+      `phase markup digest ${observedDigest} != evidence ${evidence.served.markupDigest}`,
+    );
+  }
+  if (served.planCacheIdentity !== evidence.served.planCacheIdentity) {
+    contradictions.push(
+      `plan cache identity "${served.planCacheIdentity}" != evidence "${evidence.served.planCacheIdentity}"`,
+    );
+  }
+  if (served.environment !== evidence.served.environment) {
+    contradictions.push(
+      `environment "${served.environment}" != evidence "${evidence.served.environment}"`,
+    );
+  }
+  if (stableStringify(served.cspAdditions) !== stableStringify(evidence.served.cspAdditions)) {
+    contradictions.push("CSP additions differ from evidence");
+  }
+
+  return { ok: contradictions.length === 0, contradictions };
+}
+
+export interface CandidatePromotionVerdict {
+  ok: boolean;
+  blockers: string[];
+}
+
+export interface VerifyCandidatePromotableOptions {
+  /**
+   * The message from a forge-response integrity failure (ext-prereq-02), when the
+   * reconcile that produced this candidate hit one. A forged/unreadable forge
+   * response can never become promotable.
+   */
+  forgeIntegrityError?: string | null;
+}
+
+/**
+ * The fail-closed promotion gate (same `{ok, blockers}` shape as the
+ * promotion-evidence gate). A candidate is promotable ONLY when: the evidence
+ * carries no secret material; it does not report the live environment (a candidate
+ * is never live); every declared app asset materialized and the verify ran; no
+ * forge-integrity failure is reported; the served output WAS observed; and that
+ * observation re-derives to the same fingerprint. An unobserved served output is
+ * itself a blocker — parity cannot be confirmed by assertion.
+ */
+export function verifyCandidatePromotable(
+  evidence: IntegrationCandidateEvidence,
+  served: ServedObservation | null,
+  opts?: VerifyCandidatePromotableOptions,
+): CandidatePromotionVerdict {
+  const blockers: string[] = [];
+
+  for (const violation of findForbiddenFields(evidence, "evidence")) {
+    blockers.push(`evidence carries secret material at ${violation.path}`);
+  }
+
+  if (evidence.environment.environment === "live") {
+    blockers.push("candidate reports the live environment; a candidate is never live");
+  }
+
+  const a = evidence.assets;
+  if (a.unreadable) {
+    blockers.push(`asset verification could not run (fail closed): ${a.unreadable}`);
+  } else if (a.missing.length > 0 || a.verified !== a.expected) {
+    const count = a.missing.length || a.expected - a.verified;
+    blockers.push(
+      `${count} app asset(s) did not materialize: ${a.missing.join(", ") || "(count mismatch)"}`,
+    );
+  }
+
+  if (opts?.forgeIntegrityError) {
+    blockers.push(`forge response integrity failed: ${opts.forgeIntegrityError}`);
+  }
+
+  if (!served) {
+    blockers.push("served output not observed; parity with evidence is unconfirmed");
+  } else {
+    for (const contradiction of verifyServedParity(evidence, served).contradictions) {
+      blockers.push(`served output contradicts evidence: ${contradiction}`);
+    }
+  }
+
+  return { ok: blockers.length === 0, blockers };
+}