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

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

@@ -0,0 +1,92 @@
+/**
+ * The no-secret-in-the-browser guard — charter invariant 3 (secrets, bindings,
+ * preview tokens, signed URLs, and raw PII never enter browser configuration)
+ * and ADR 0018 (a CSP nonce is per-response and never serialized).
+ *
+ * A secret field is made impossible two ways:
+ *   1. Every browser-facing contract is CLOSED (`rejectUnknownKeys`), so a field
+ *      such as `nonce` is not in the schema and is rejected as unknown.
+ *   2. This scanner is defense-in-depth: any object about to cross into a
+ *      serialized surface — evidence artifact, cache entry, log line, API
+ *      response, or cross-request persistence — runs through
+ *      `findForbiddenFields`, so a secret introduced by a nested or opaque value
+ *      is caught even where the schema is open.
+ */
+import type { ContractViolation } from "./result.js";
+import { isPlainObject } from "./result.js";
+
+/** Single-word key tokens that denote secret material. */
+const FORBIDDEN_WORDS: readonly string[] = [
+  "nonce",
+  "token",
+  "secret",
+  "credential",
+  "bearer",
+  "password",
+  "passwd",
+  "passphrase",
+  "signature",
+];
+
+/** Multi-word key forms (compared against the collapsed, tokenized key). */
+const FORBIDDEN_COLLAPSED: readonly string[] = [
+  "signedurl",
+  "apikey",
+  "privatekey",
+  "sessionkey",
+  "accesskey",
+  "clientsecret",
+  "accesstoken",
+  "refreshtoken",
+];
+
+function tokenize(key: string): string[] {
+  return key
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_\-.$]/g, " ")
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/** True when a field name denotes a nonce, token, credential, or signed URL. */
+export function isForbiddenKey(key: string): boolean {
+  const tokens = tokenize(key);
+  if (tokens.some((t) => FORBIDDEN_WORDS.includes(t))) return true;
+  const collapsed = tokens.join("");
+  return FORBIDDEN_COLLAPSED.some((c) => collapsed.includes(c));
+}
+
+/**
+ * Recursively report every field whose name denotes secret material. Returns an
+ * empty array for a browser-safe payload. Scans keys only; values are validated
+ * by field-level format checks (e.g. exact-origin CSP sources reject query-param
+ * signed URLs).
+ */
+export function findForbiddenFields(value: unknown, path = ""): ContractViolation[] {
+  const out: ContractViolation[] = [];
+  walk(value, path, out);
+  return out;
+}
+
+function walk(value: unknown, path: string, out: ContractViolation[]): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => walk(item, `${path}[${i}]`, out));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = path ? `${path}.${key}` : key;
+    if (isForbiddenKey(key)) {
+      out.push({
+        path: childPath,
+        code: "secret_field",
+        message:
+          `Field "${key}" names secret material; nonces, tokens, credentials, ` +
+          `signed URLs, and secrets must never appear in browser configuration, ` +
+          `effective plans, evidence, events, or assurance records.`,
+      });
+    }
+    walk(child, childPath, out);
+  }
+}

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

@@ -0,0 +1,205 @@
+/**
+ * The tamper-evidence beacon contract — the durable, secret-free record a
+ * protected-surface sentinel emits when it detects and recovers from third-party
+ * mutation of a platform-owned compliance/commerce surface (D-R7,
+ * `integration-protected-tamper-recovery`).
+ *
+ * This is the wire shape shared by the browser sentinel (which BUILDS and EMITS a
+ * beacon) and the server recovery path (which VALIDATES it, records it, and
+ * suspends the attributable integration). It is scoped to `tenant` + integration
+ * `attribution` (appId + version + origin) so a recovery action names exactly what
+ * to suspend.
+ *
+ * This is a DETECTIVE control. Full-parent DOM reach cannot be enforceably
+ * narrowed (WS2 security model), so a sentinel cannot PREVENT mutation — it
+ * detects it, restores safe state, and attributes it after the fact. The `control`
+ * field is the literal `"detective"` and the validator REJECTS any other value, so
+ * a beacon can never claim preventative isolation on the wire.
+ *
+ * Like every browser-facing contract here it is CLOSED and FAIL-CLOSED (unknown
+ * fields, unknown enum members, malformed shapes rejected) and secret-free
+ * (`findForbiddenFields`): a beacon carries structural facts about WHICH surface
+ * was tampered and HOW, never the altered copy itself, so no customer PII or
+ * secret can ride it.
+ */
+import type { ContractResult } from "./result.js";
+import {
+  Violations,
+  reqObject,
+  reqString,
+  reqEnum,
+  reqBool,
+  reqLiteral,
+  reqIsoTimestamp,
+  rejectUnknownKeys,
+} from "./result.js";
+import { TAMPER_EVIDENCE_SCHEMA_VERSION } from "./version.js";
+import { INTEGRATION_ENVIRONMENTS, INTEGRATION_SITE_SURFACES } from "./environment.js";
+import type { IntegrationEnvironment, IntegrationSiteSurface } from "./environment.js";
+import { findForbiddenFields } from "./secrets.js";
+import { PROTECTED_SURFACES, type ProtectedSurface } from "../compliance-obligations.js";
+
+/**
+ * The one honest label for this class of control. A sentinel recovers safe state
+ * AFTER a mutation; it never prevents one. Any other value is rejected by
+ * {@link validateTamperEvidenceBeacon}, so "preventative"/"isolation" cannot be
+ * asserted on the wire.
+ */
+export const TAMPER_CONTROL = "detective" as const;
+export type TamperControl = typeof TAMPER_CONTROL;
+
+/**
+ * The observed mutation classes a sentinel distinguishes. Every one is a DETECTED
+ * tamper that was RECOVERED; the taxonomy drives operator triage, not enforcement.
+ *   - `removed`            — the protected node was detached from the document.
+ *   - `displaced`          — a different node now claims the surface marker.
+ *   - `listener-stripped`  — the node was replaced by an identical-markup clone,
+ *                            dropping its event listeners.
+ *   - `hidden`             — visually suppressed (display/visibility/opacity/hidden/aria-hidden).
+ *   - `overlaid`           — a foreign covering element was inserted over the surface.
+ *   - `text-altered`       — the protected copy/state text was changed in place.
+ *   - `subtree-mutated`    — any other structural mutation within the surface.
+ */
+export const TAMPER_KINDS = [
+  "removed",
+  "displaced",
+  "listener-stripped",
+  "hidden",
+  "overlaid",
+  "text-altered",
+  "subtree-mutated",
+] as const;
+export type TamperKind = (typeof TAMPER_KINDS)[number];
+
+/**
+ * The integration a tamper is attributed to — the exact `appId` + `version` +
+ * `origin` a recovery action suspends. `null` attribution is HONEST and expected:
+ * anonymous full-parent DOM reach cannot always be pinned to one integration, so
+ * an unattributable tamper is still detected, recovered, and alerted, but no
+ * specific integration is auto-suspended.
+ */
+export interface TamperAttribution {
+  appId: string;
+  version: string;
+  origin: string;
+}
+
+/**
+ * The durable evidence a sentinel emits per detected+recovered tamper. Scoped to
+ * `tenant` + `attribution` (app/version) and stamped with `environment` +
+ * `siteSurface` so the record is unambiguous across tiers.
+ */
+export interface TamperEvidenceBeacon {
+  schemaVersion: typeof TAMPER_EVIDENCE_SCHEMA_VERSION;
+  /** Always `"detective"` — see {@link TAMPER_CONTROL}. */
+  control: TamperControl;
+  tenant: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+  /** The platform-owned protected anchor (policy-04 `PROTECTED_SURFACES`) that was tampered. */
+  surface: ProtectedSurface;
+  kind: TamperKind;
+  /** ISO-8601 instant the tamper was detected. */
+  detectedAt: string;
+  /** True when the sentinel restored safe state (re-inspected clean after recovery). */
+  recovered: boolean;
+  /** The attributable integration, or `null` when the mutation is unattributable. */
+  attribution: TamperAttribution | null;
+}
+
+/** The fields a caller supplies to {@link buildTamperEvidenceBeacon}. */
+export type TamperEvidenceInput = Omit<
+  TamperEvidenceBeacon,
+  "schemaVersion" | "control"
+>;
+
+/**
+ * Assemble a beacon with the fixed `schemaVersion` + `control` stamped. The only
+ * constructor — so a beacon can never be built claiming a non-detective control.
+ */
+export function buildTamperEvidenceBeacon(
+  input: TamperEvidenceInput,
+): TamperEvidenceBeacon {
+  return {
+    schemaVersion: TAMPER_EVIDENCE_SCHEMA_VERSION,
+    control: TAMPER_CONTROL,
+    ...input,
+  };
+}
+
+function validateAttribution(value: unknown, v: Violations): void {
+  if (value === null) return;
+  const obj = reqObject(value, v, "attribution");
+  if (!obj) return;
+  rejectUnknownKeys(obj, ["appId", "version", "origin"], v, "attribution");
+  reqString(obj, "appId", v, "attribution");
+  reqString(obj, "version", v, "attribution");
+  reqString(obj, "origin", v, "attribution");
+}
+
+/**
+ * The single fail-CLOSED authority for "is this a well-formed tamper beacon?".
+ * Rejects an unknown schema version, a non-`detective` control (so no beacon can
+ * claim prevention), an unknown surface or kind, a malformed attribution, or any
+ * secret-bearing field. The server recovery path validates every inbound beacon
+ * through this before acting on it.
+ */
+export function validateTamperEvidenceBeacon(
+  input: unknown,
+): ContractResult<TamperEvidenceBeacon> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+
+  rejectUnknownKeys(
+    obj,
+    [
+      "schemaVersion",
+      "control",
+      "tenant",
+      "environment",
+      "siteSurface",
+      "surface",
+      "kind",
+      "detectedAt",
+      "recovered",
+      "attribution",
+    ],
+    v,
+    "",
+  );
+
+  reqLiteral(obj, "schemaVersion", TAMPER_EVIDENCE_SCHEMA_VERSION, v, "");
+  reqLiteral(obj, "control", TAMPER_CONTROL, v, "");
+  reqString(obj, "tenant", v, "");
+  reqEnum(obj, "environment", INTEGRATION_ENVIRONMENTS, v, "");
+  reqEnum(obj, "siteSurface", INTEGRATION_SITE_SURFACES, v, "");
+  reqEnum(obj, "surface", PROTECTED_SURFACES, v, "");
+  reqEnum(obj, "kind", TAMPER_KINDS, v, "");
+  reqIsoTimestamp(obj, "detectedAt", v, "");
+  reqBool(obj, "recovered", v, "");
+  if (!("attribution" in obj)) {
+    v.add("attribution", "type", 'Expected "attribution" to be an object or null.');
+  } else {
+    validateAttribution(obj["attribution"], v);
+  }
+
+  for (const violation of findForbiddenFields(obj)) v.items.push(violation);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return { ok: true, value: input as TamperEvidenceBeacon };
+}
+
+/**
+ * Resolve attribution from the integrations that could be responsible. Anonymous
+ * DOM mutation carries no provenance, so attribution is the honest SOLE-SUSPECT
+ * rule: attribute to the one integration when exactly one is present, otherwise
+ * `null` (unattributable — recover + alert, but auto-suspend nothing). A caller
+ * that positively identifies the actor (e.g. an injected node carrying an
+ * integration's marker) resolves it directly instead of relying on this.
+ */
+export function attributeSoleSuspect(
+  candidates: readonly TamperAttribution[],
+): TamperAttribution | null {
+  return candidates.length === 1 ? candidates[0]! : null;
+}

package/packages/public-runtime/src/integration/tamper-recovery.ts

@@ -0,0 +1,127 @@
+/**
+ * Edge recovery decisions for protected-surface tamper beacons (D-R7,
+ * `integration-protected-tamper-recovery`).
+ *
+ * The browser sentinel restores safe state IN the document and posts a
+ * {@link TamperEvidenceBeacon}. This is the trusted receiver's pure decision core:
+ * it VALIDATES the beacon fail-closed, turns it into a durable append-only
+ * {@link TamperEvidenceRecord}, and resolves the SUSPEND directive that disables the
+ * attributable integration's install. It is edge-safe (no Node) so the storefront
+ * Worker — where the beacon lands — can run it directly; the actuation (the actual
+ * registry suspend + audit write) belongs to the caller.
+ *
+ * This is a DETECTIVE control. Suspension happens AFTER a detected+recovered tamper,
+ * keyed on the beacon's `attribution` (appId + version), and is deliberately
+ * conservative: it suspends only when exactly one ACTIVE install matches. An
+ * unattributable beacon, or an ambiguous match, records the evidence and alerts but
+ * suspends nothing — recovery never suspends the wrong app.
+ */
+import type { ContractViolation } from "./result.js";
+import {
+  validateTamperEvidenceBeacon,
+  type TamperEvidenceBeacon,
+} from "./tamper-evidence.js";
+
+/** The minimal install facts suspension resolution needs (the registry row projection). */
+export interface AttributableInstall {
+  installId: string;
+  appId: string;
+  appVersion: string;
+  status: "active" | "suspended" | "uninstalled";
+}
+
+/** The durable, append-only record a validated beacon becomes on the server. */
+export interface TamperEvidenceRecord {
+  recordId: string;
+  /** ISO instant the server received the beacon. */
+  receivedAt: string;
+  beacon: TamperEvidenceBeacon;
+}
+
+/** The suspension a recovery drives — names exactly one install to disable. */
+export interface SuspendDirective {
+  installId: string;
+  appId: string;
+  version: string;
+  reason: string;
+}
+
+export interface TamperRecoveryPlan {
+  record: TamperEvidenceRecord;
+  /** The install to suspend, or `null` when unattributable / no single active match. */
+  suspend: SuspendDirective | null;
+  /** Always true — every detected tamper is surfaced to operations. */
+  alert: boolean;
+}
+
+export type TamperRecoveryResult =
+  | { ok: true; plan: TamperRecoveryPlan }
+  | { ok: false; violations: ContractViolation[] };
+
+export interface PlanTamperRecoveryOptions {
+  recordId: string;
+  /** ISO server receive time; passed in so the record is deterministic/testable. */
+  receivedAt: string;
+}
+
+/**
+ * Resolve which install to suspend for a beacon, or `null`. Fail-SAFE: suspends
+ * only when the beacon is attributed AND exactly one ACTIVE install matches that
+ * app id and version. Zero matches, an already-suspended/uninstalled install, or an
+ * ambiguous multi-match resolves to `null` — the evidence still stands, but no app
+ * is auto-suspended on a guess.
+ */
+export function resolveSuspendTarget(
+  beacon: TamperEvidenceBeacon,
+  installs: readonly AttributableInstall[],
+): SuspendDirective | null {
+  const attribution = beacon.attribution;
+  if (!attribution) return null;
+
+  const matches = installs.filter(
+    (i) =>
+      i.status === "active" &&
+      i.appId === attribution.appId &&
+      i.appVersion === attribution.version,
+  );
+  if (matches.length !== 1) return null;
+
+  const install = matches[0]!;
+  return {
+    installId: install.installId,
+    appId: attribution.appId,
+    version: attribution.version,
+    reason: `Detective tamper recovery: integration mutated the protected "${beacon.surface}" surface (${beacon.kind}); auto-suspended.`,
+  };
+}
+
+/**
+ * Validate an inbound beacon and produce the recovery plan: a durable evidence
+ * record, the (optional) suspend directive, and the always-on alert. Returns the
+ * structured violations on a malformed/secret-bearing/non-detective beacon so the
+ * caller can 400 it rather than act on unvalidated input.
+ */
+export function planTamperRecovery(
+  rawBeacon: unknown,
+  installs: readonly AttributableInstall[],
+  opts: PlanTamperRecoveryOptions,
+): TamperRecoveryResult {
+  const validated = validateTamperEvidenceBeacon(rawBeacon);
+  if (!validated.ok) return { ok: false, violations: validated.violations };
+
+  const beacon = validated.value;
+  const record: TamperEvidenceRecord = {
+    recordId: opts.recordId,
+    receivedAt: opts.receivedAt,
+    beacon,
+  };
+
+  return {
+    ok: true,
+    plan: {
+      record,
+      suspend: resolveSuspendTarget(beacon, installs),
+      alert: true,
+    },
+  };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Semver-versioned browser-integration contract (ADR 0006).
+ *
+ * The browser contract carries a single MAJOR.MINOR.PATCH version. A manifest
+ * declares the range it supports in `compatibility.storefrontBrowserContract`;
+ * compatibility is resolved fail-closed — an unparseable range, or a current
+ * contract version outside the range, is rejected rather than assumed
+ * compatible.
+ *
+ * Each payload family additionally pins an integer `schemaVersion`. Unknown
+ * schema versions fail closed.
+ */
+
+export const BROWSER_INTEGRATION_CONTRACT_VERSION = "2.0.0" as const;
+
+export const ENVIRONMENT_SCHEMA_VERSION = 1 as const;
+export const INTEGRATION_MANIFEST_SCHEMA_VERSION = 2 as const;
+export const EFFECTIVE_PLAN_SCHEMA_VERSION = 1 as const;
+export const COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION = 1 as const;
+export const CONSENT_SNAPSHOT_SCHEMA_VERSION = 1 as const;
+export const RECEIPT_MEASUREMENT_GRANT_SCHEMA_VERSION = 1 as const;
+export const CONSENT_CONFIG_SCHEMA_VERSION = 1 as const;
+export const ASSURANCE_RECORD_SCHEMA_VERSION = 1 as const;
+export const TAMPER_EVIDENCE_SCHEMA_VERSION = 1 as const;
+export const OBSERVABILITY_SIGNAL_SCHEMA_VERSION = 1 as const;
+
+export interface SemVer {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+export function parseSemVer(input: string): SemVer | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(input.trim());
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+}
+
+export function compareSemVer(a: SemVer, b: SemVer): number {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
+  return 0;
+}
+
+type Comparator = ">=" | "<=" | ">" | "<" | "=";
+
+function satisfiesComparator(version: SemVer, op: Comparator, target: SemVer): boolean {
+  const cmp = compareSemVer(version, target);
+  switch (op) {
+    case ">=":
+      return cmp >= 0;
+    case "<=":
+      return cmp <= 0;
+    case ">":
+      return cmp > 0;
+    case "<":
+      return cmp < 0;
+    case "=":
+      return cmp === 0;
+  }
+}
+
+/**
+ * True only when `version` satisfies every space-separated comparator in
+ * `range` (AND semantics), e.g. `>=1.0.0 <2.0.0`. A bare version means `=`.
+ * Any unparseable comparator makes the whole range unsatisfied (fail closed).
+ */
+export function satisfiesRange(version: string, range: string): boolean {
+  const parsed = parseSemVer(version);
+  if (!parsed) return false;
+  const parts = range.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return false;
+  for (const part of parts) {
+    const match = /^(>=|<=|>|<|=)?(\d+\.\d+\.\d+)$/.exec(part);
+    if (!match) return false;
+    const target = parseSemVer(match[2] ?? "");
+    if (!target) return false;
+    const op = (match[1] ?? "=") as Comparator;
+    if (!satisfiesComparator(parsed, op, target)) return false;
+  }
+  return true;
+}
+
+/** Whether the current browser contract version satisfies a manifest's declared range. */
+export function isCompatibleWithCurrentContract(range: string): boolean {
+  return satisfiesRange(BROWSER_INTEGRATION_CONTRACT_VERSION, range);
+}