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

package/apps/storefront/src/lib/apps/integrationLifecycle.ts

@@ -0,0 +1,614 @@
+/**
+ * The tenant integration configuration lifecycle (ext-admin-07) — the state
+ * machine behind the `IntegrationLifecycleAction`s ext-admin-01's IA names
+ * (`preview` / `publish` / `rollback` / `suspend` / `resume` / `uninstall`),
+ * built ON the candidate/change-control substrate the umbrella already carries:
+ * kernel-06 candidate evidence (the code/config/CSP/consent/assurance facets),
+ * admin-02's read model (the same DISTINCT effective/candidate/desired slots),
+ * and policy-06's unifying promotion gate ({@link verifyIntegrationPromotable}).
+ *
+ * It is PURE and SYNCHRONOUS over already-materialized inputs — resolving plans,
+ * evidence, and the gate's server-derived facts is the control plane's job (the
+ * route); transitioning the lifecycle over them is this module's. Four properties
+ * hold by construction, one per acceptance clause:
+ *
+ *   1. FOUR ENVS DISTINCT — {@link TenantIntegrationLifecycleState.stages} keys the
+ *      `local` / `candidate` / `staged` / `live` facets under SEPARATE slots that
+ *      are never merged. A transition advances exactly the slots it names; a read of
+ *      one stage never returns another's revision. `candidate` is asserted to carry
+ *      the `candidate` environment (a candidate is never live).
+ *   2. FAILED PUBLISH LEAVES ACTUAL — {@link publishCandidate} routes the candidate
+ *      THROUGH the policy-06 gate and flips `live` ONLY on `verdict.ok`. A blocked
+ *      candidate (or a version/scope mismatch) returns the input state UNCHANGED —
+ *      the `live` (last-good) facets never move, so there is no half-applied publish.
+ *   3. CANDIDATE SHOWS EVERY FACET — {@link diffStageFacets} reports the candidate's
+ *      code, config, CSP origins, consent needs, and assurance against what is live,
+ *      all derived from the kernel-06 evidence — the effective diff a reviewer reads
+ *      before publishing.
+ *   4. ROLLBACK / REMOVAL LEAVE NO STALE EFFECT — {@link rollbackIntegration} repoints
+ *      `live` to a recorded known-good revision (planRevision-scoped; no page edit),
+ *      and {@link removeIntegration} clears EVERY stage slot. Nothing partial is left
+ *      behind; a suspended/uninstalled install serves nothing ({@link effectiveServing}).
+ *
+ * Fail-closed throughout: a cross-tenant evidence, a candidate claiming a non-candidate
+ * stage, or any secret-named facet aborts the transition with the state untouched.
+ */
+import type { AppInstallStatus } from "./registryService.js";
+import {
+  INTEGRATION_CSP_DIRECTIVES,
+  findForbiddenFields,
+  verifyIntegrationPromotable,
+  type IntegrationEnvironment,
+  type IntegrationCandidateEvidence,
+  type EvidenceAssurance,
+  type ExecutionTier,
+  type IntegrationCspAdditions,
+  type IntegrationPromotionGateInput,
+  type IntegrationPromotionVerdict,
+} from "@tot/public-runtime";
+
+/** One resolved integration's public code identity — the "code" facet of a stage. */
+export interface IntegrationCode {
+  appId: string;
+  version: string;
+  digest: string;
+  executionTier: ExecutionTier;
+}
+
+/**
+ * The effective facets serving at one lifecycle stage — the reviewable surface a
+ * candidate and the live state each carry. `planRevision` is the identity that keeps
+ * stages DISTINCT: two stages holding different revisions can never be conflated.
+ */
+export interface StageFacets {
+  planRevision: string;
+  /** The primary install's app version at this stage. */
+  version: string;
+  /** Per-integration public code identity. */
+  code: IntegrationCode[];
+  /** Per-integration resolved public config (no secret material). */
+  config: Record<string, Record<string, unknown>>;
+  /** Sorted, deduped exact CSP origins across every contributable directive. */
+  cspOrigins: string[];
+  /** Consent purpose ids this stage's plan depends on. */
+  consentNeeds: string[];
+  /** The elevated-integration assurance state (public, non-waivable floor only). */
+  assurance: EvidenceAssurance;
+}
+
+/** Sorted, deduped exact origins across all contributable directives. */
+function flattenCspOrigins(additions: IntegrationCspAdditions | undefined): string[] {
+  if (!additions) return [];
+  const set = new Set<string>();
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    for (const origin of additions[directive] ?? []) set.add(origin);
+  }
+  return [...set].sort();
+}
+
+/**
+ * Derive the reviewable stage facets from kernel-06 candidate evidence. The evidence
+ * is the SAME public-values-only artifact the mounts serve and the gate verifies, so
+ * a stage's facets are a property of the evidence, not a claim kept in sync with it.
+ */
+export function facetsFromEvidence(
+  evidence: IntegrationCandidateEvidence,
+  appId: string,
+): StageFacets {
+  const code: IntegrationCode[] = evidence.integrations.map((i) => ({
+    appId: i.appId,
+    version: i.version,
+    digest: i.digest,
+    executionTier: i.executionTier,
+  }));
+  const primary = code.find((c) => c.appId === appId);
+  return {
+    planRevision: evidence.planRevision,
+    version: primary?.version ?? evidence.planRevision,
+    code,
+    config: evidence.publicConfig,
+    cspOrigins: flattenCspOrigins(evidence.cspAdditions),
+    consentNeeds: [...evidence.consentNeeds],
+    assurance: evidence.assurance,
+  };
+}
+
+/** One integration's code identity changing between the live and candidate stages. */
+export interface CodeChange {
+  appId: string;
+  actual: Omit<IntegrationCode, "appId"> | null;
+  candidate: Omit<IntegrationCode, "appId"> | null;
+}
+
+/** One public-config field differing between live and candidate. */
+export interface ConfigChange {
+  /** `<appId>.<key>` — never a value, so the diff itself carries no secret. */
+  field: string;
+  actual: unknown;
+  candidate: unknown;
+}
+
+/** A set-valued facet's diff (CSP origins, consent purposes). */
+export interface SetDiff {
+  added: string[];
+  removed: string[];
+}
+
+/**
+ * The effective diff a reviewer reads before publishing — every facet a candidate
+ * changes against what is live: code, config, CSP origins, consent needs, assurance.
+ */
+export interface IntegrationCandidateDiff {
+  planRevision: { actual: string | null; candidate: string };
+  code: CodeChange[];
+  config: ConfigChange[];
+  csp: SetDiff;
+  consent: SetDiff;
+  assurance: { changed: boolean; actual: EvidenceAssurance | null; candidate: EvidenceAssurance };
+  /** True when no facet effectively changes — a publish that would alter nothing. */
+  unchanged: boolean;
+}
+
+function setDiff(actual: readonly string[], candidate: readonly string[]): SetDiff {
+  const a = new Set(actual);
+  const c = new Set(candidate);
+  return {
+    added: candidate.filter((x) => !a.has(x)).sort(),
+    removed: actual.filter((x) => !c.has(x)).sort(),
+  };
+}
+
+/** Diff a candidate's facets against the live facets, facet by facet. */
+export function diffStageFacets(
+  actual: StageFacets | null,
+  candidate: StageFacets,
+): IntegrationCandidateDiff {
+  const code: CodeChange[] = [];
+  const appIds = new Set<string>([
+    ...(actual?.code ?? []).map((c) => c.appId),
+    ...candidate.code.map((c) => c.appId),
+  ]);
+  for (const appId of [...appIds].sort()) {
+    const a = actual?.code.find((c) => c.appId === appId) ?? null;
+    const c = candidate.code.find((x) => x.appId === appId) ?? null;
+    const aFacet = a ? { version: a.version, digest: a.digest, executionTier: a.executionTier } : null;
+    const cFacet = c ? { version: c.version, digest: c.digest, executionTier: c.executionTier } : null;
+    if (JSON.stringify(aFacet) !== JSON.stringify(cFacet)) {
+      code.push({ appId, actual: aFacet, candidate: cFacet });
+    }
+  }
+
+  const config: ConfigChange[] = [];
+  const actualConfig = actual?.config ?? {};
+  const configApps = new Set<string>([...Object.keys(actualConfig), ...Object.keys(candidate.config)]);
+  for (const appId of [...configApps].sort()) {
+    const aApp = actualConfig[appId] ?? {};
+    const cApp = candidate.config[appId] ?? {};
+    const keys = new Set<string>([...Object.keys(aApp), ...Object.keys(cApp)]);
+    for (const key of [...keys].sort()) {
+      const aVal = aApp[key];
+      const cVal = cApp[key];
+      if (JSON.stringify(aVal) !== JSON.stringify(cVal)) {
+        config.push({ field: `${appId}.${key}`, actual: aVal, candidate: cVal });
+      }
+    }
+  }
+
+  const csp = setDiff(actual?.cspOrigins ?? [], candidate.cspOrigins);
+  const consent = setDiff(actual?.consentNeeds ?? [], candidate.consentNeeds);
+  const assuranceChanged = JSON.stringify(actual?.assurance ?? null) !== JSON.stringify(candidate.assurance);
+
+  return {
+    planRevision: { actual: actual?.planRevision ?? null, candidate: candidate.planRevision },
+    code,
+    config,
+    csp,
+    consent,
+    assurance: { changed: assuranceChanged, actual: actual?.assurance ?? null, candidate: candidate.assurance },
+    unchanged:
+      code.length === 0 &&
+      config.length === 0 &&
+      csp.added.length === 0 &&
+      csp.removed.length === 0 &&
+      consent.added.length === 0 &&
+      consent.removed.length === 0 &&
+      !assuranceChanged,
+  };
+}
+
+/** The lifecycle actions ext-admin-01's IA names; each is a transition below. */
+export type LifecycleAction =
+  | "preview"
+  | "publish"
+  | "rollback"
+  | "suspend"
+  | "resume"
+  | "uninstall";
+
+/** One audit record — actor, action, targeted version, result. Never secret-bearing. */
+export interface LifecycleEvent {
+  action: LifecycleAction;
+  actor: string;
+  at: string;
+  /** The plan revision the action targeted (candidate's, promoted, or rolled-to), or null. */
+  planRevision: string | null;
+  result: "applied" | "refused";
+  reason?: string;
+}
+
+/**
+ * The full tenant-scoped lifecycle state for ONE install. The four env slots are
+ * independent keys — a transition advances only the ones it names, so a stage read
+ * never conflates with another (acceptance clause 1).
+ */
+export interface TenantIntegrationLifecycleState {
+  tenantPublicId: string;
+  installId: string;
+  appId: string;
+  installStatus: AppInstallStatus;
+  /** The four DISTINCT env slots — never merged. */
+  stages: Record<IntegrationEnvironment, StageFacets | null>;
+  /** Prior good live facets to roll back to; most-recent last. planRevision-scoped. */
+  knownGood: StageFacets[];
+  /** Applied transitions, in order — the audit trail. Refusals are surfaced on the result, not folded here. */
+  history: LifecycleEvent[];
+}
+
+export interface InitialLifecycleInput {
+  tenantPublicId: string;
+  installId: string;
+  appId: string;
+  installStatus?: AppInstallStatus;
+}
+
+/** A fresh lifecycle state — every stage empty, nothing serving, no rollback target. */
+export function initialLifecycleState(input: InitialLifecycleInput): TenantIntegrationLifecycleState {
+  return {
+    tenantPublicId: input.tenantPublicId,
+    installId: input.installId,
+    appId: input.appId,
+    installStatus: input.installStatus ?? "active",
+    stages: { local: null, candidate: null, staged: null, live: null },
+    knownGood: [],
+    history: [],
+  };
+}
+
+export type LifecycleRefusalReason =
+  | "not_active"
+  | "no_candidate"
+  | "version_mismatch"
+  | "gate_blocked"
+  | "stale_live"
+  | "no_known_good"
+  | "unknown_target"
+  | "already_removed"
+  | "not_suspended"
+  | "invalid_stage"
+  | "cross_tenant"
+  | "integrity";
+
+export interface LifecycleApplied {
+  ok: true;
+  /** The advanced state — a NEW value; the input is never mutated. */
+  state: TenantIntegrationLifecycleState;
+  event: LifecycleEvent;
+}
+
+export interface LifecycleRefused {
+  ok: false;
+  reason: LifecycleRefusalReason;
+  blockers: string[];
+  /** The UNCHANGED input state — a refusal never advances ACTUAL (same reference). */
+  state: TenantIntegrationLifecycleState;
+  event: LifecycleEvent;
+}
+
+export type LifecycleResult = LifecycleApplied | LifecycleRefused;
+
+/** A `preview` result also carries the effective diff the reviewer reads. */
+export interface PreviewApplied extends LifecycleApplied {
+  diff: IntegrationCandidateDiff;
+}
+export type PreviewResult = PreviewApplied | LifecycleRefused;
+
+export interface LifecycleActionContext {
+  /** Opaque audit actor (already pseudonymized upstream) — never PII. */
+  actor: string;
+  now?: () => string;
+}
+
+function stamp(ctx: LifecycleActionContext): string {
+  return (ctx.now ?? (() => new Date().toISOString()))();
+}
+
+function refuse(
+  state: TenantIntegrationLifecycleState,
+  action: LifecycleAction,
+  ctx: LifecycleActionContext,
+  reason: LifecycleRefusalReason,
+  blockers: string[],
+  planRevision: string | null = null,
+): LifecycleRefused {
+  return {
+    ok: false,
+    reason,
+    blockers,
+    state,
+    event: { action, actor: ctx.actor, at: stamp(ctx), planRevision, result: "refused", reason },
+  };
+}
+
+function apply(
+  state: TenantIntegrationLifecycleState,
+  action: LifecycleAction,
+  ctx: LifecycleActionContext,
+  next: Omit<TenantIntegrationLifecycleState, "history">,
+  planRevision: string | null,
+): LifecycleApplied {
+  const event: LifecycleEvent = { action, actor: ctx.actor, at: stamp(ctx), planRevision, result: "applied" };
+  return { ok: true, state: { ...next, history: [...state.history, event] }, event };
+}
+
+/** Fail-closed: no facet may name secret material (defense in depth over the evidence scan). */
+function secretPaths(facets: StageFacets): string[] {
+  return findForbiddenFields(facets, "facets").map((v) => v.path);
+}
+
+/**
+ * `preview` — record a prepared candidate in the `candidate` slot and return the
+ * effective diff against what is live. Fail-closed: a cross-tenant evidence, a
+ * non-`candidate` environment (a candidate is never live/staged/local), or a
+ * secret-named facet aborts with the state untouched. Only the `candidate` slot
+ * moves — `local` / `staged` / `live` are never touched here.
+ */
+export function stageCandidate(
+  state: TenantIntegrationLifecycleState,
+  evidence: IntegrationCandidateEvidence,
+  ctx: LifecycleActionContext,
+): PreviewResult {
+  if (state.installStatus !== "active") {
+    return refuse(state, "preview", ctx, "not_active", [`Install is ${state.installStatus}; cannot stage a candidate.`]);
+  }
+  if (evidence.tenantPublicId !== state.tenantPublicId) {
+    return refuse(state, "preview", ctx, "cross_tenant", [
+      `Candidate evidence is scoped to "${evidence.tenantPublicId}", not "${state.tenantPublicId}".`,
+    ]);
+  }
+  if (evidence.environment.environment !== "candidate") {
+    return refuse(state, "preview", ctx, "invalid_stage", [
+      `Candidate evidence reports the "${evidence.environment.environment}" environment; a candidate must be "candidate".`,
+    ]);
+  }
+  const facets = facetsFromEvidence(evidence, state.appId);
+  const forbidden = secretPaths(facets);
+  if (forbidden.length > 0) {
+    return refuse(state, "preview", ctx, "integrity", [`Candidate facets named secret material: ${forbidden.join(", ")}.`]);
+  }
+  const diff = diffStageFacets(state.stages.live, facets);
+  const applied = apply(
+    state,
+    "preview",
+    ctx,
+    { ...state, stages: { ...state.stages, candidate: facets } },
+    facets.planRevision,
+  );
+  return { ...applied, diff };
+}
+
+export interface PublishOptions {
+  /**
+   * The caller's last-seen live revision — an optimistic concurrency guard. When set
+   * and it no longer matches the live slot, the publish is refused `stale_live`
+   * (re-review before publishing). Pass `null` to assert nothing is live yet.
+   */
+  expectedLiveRevision?: string | null;
+}
+
+/**
+ * `publish` — promote the pending candidate to `live` THROUGH the policy-06 gate.
+ * The gate ({@link verifyIntegrationPromotable}) composes CSP / consent / obligations
+ * / assurance / candidate-served-parity / compliance and is fail-closed; `live` flips
+ * ONLY on `verdict.ok`. A blocked candidate returns the input state UNCHANGED — the
+ * last-good `live` facets never move (no half-applied publish). On success the prior
+ * live becomes a known-good rollback target and the `candidate` slot is consumed.
+ */
+export function publishCandidate(
+  state: TenantIntegrationLifecycleState,
+  gate: IntegrationPromotionGateInput,
+  ctx: LifecycleActionContext,
+  opts: PublishOptions = {},
+): LifecycleResult {
+  if (state.installStatus !== "active") {
+    return refuse(state, "publish", ctx, "not_active", [`Install is ${state.installStatus}; cannot publish.`]);
+  }
+  const candidate = state.stages.candidate;
+  if (!candidate) {
+    return refuse(state, "publish", ctx, "no_candidate", ["No candidate is staged to publish; preview one first."]);
+  }
+  // The gate must target THIS candidate — bind its evidence revision to the staged slot.
+  const gateRevision = gate.candidateEvidence?.planRevision ?? null;
+  if (gateRevision !== candidate.planRevision) {
+    return refuse(
+      state,
+      "publish",
+      ctx,
+      "version_mismatch",
+      [
+        `Promotion gate is for plan revision "${gateRevision ?? "(absent)"}" but the staged candidate is "${candidate.planRevision}".`,
+      ],
+      candidate.planRevision,
+    );
+  }
+  // Optimistic concurrency against the live slot (re-review if it moved under us).
+  if (opts.expectedLiveRevision !== undefined) {
+    const liveRevision = state.stages.live?.planRevision ?? null;
+    if (opts.expectedLiveRevision !== liveRevision) {
+      return refuse(
+        state,
+        "publish",
+        ctx,
+        "stale_live",
+        [`Live moved to "${liveRevision ?? "(none)"}" (you last saw "${opts.expectedLiveRevision ?? "(none)"}"); re-review before publishing.`],
+        candidate.planRevision,
+      );
+    }
+  }
+
+  // Route THROUGH the policy-06 gate — the single fail-closed authority for reaching live.
+  const verdict: IntegrationPromotionVerdict = verifyIntegrationPromotable(gate);
+  if (!verdict.ok) {
+    return refuse(state, "publish", ctx, "gate_blocked", verdict.blockers, candidate.planRevision);
+  }
+
+  const priorLive = state.stages.live;
+  const knownGood = priorLive ? [...state.knownGood, priorLive] : state.knownGood;
+  return apply(
+    state,
+    "publish",
+    ctx,
+    {
+      ...state,
+      stages: { ...state.stages, live: candidate, candidate: null },
+      knownGood,
+    },
+    candidate.planRevision,
+  );
+}
+
+export interface RollbackOptions {
+  /** Explicit known-good revision to restore. Omit for "one step back" (the most recent). */
+  targetRevision?: string;
+}
+
+/**
+ * `rollback` — repoint `live` to a recorded known-good revision. planRevision-scoped:
+ * it swaps the whole `live` facets to a previously-good revision in one step — no page
+ * edit, nothing half-applied. The rolled-FROM revision is NOT re-recorded as known-good
+ * (it is the suspect one); known-good newer than the restored point is dropped so a
+ * further "one step back" is well-defined.
+ */
+export function rollbackIntegration(
+  state: TenantIntegrationLifecycleState,
+  ctx: LifecycleActionContext,
+  opts: RollbackOptions = {},
+): LifecycleResult {
+  if (state.installStatus !== "active") {
+    return refuse(state, "rollback", ctx, "not_active", [`Install is ${state.installStatus}; nothing is live to roll back.`]);
+  }
+  if (state.knownGood.length === 0) {
+    return refuse(state, "rollback", ctx, "no_known_good", ["No version has gone live before; there is no known-good version to roll back to."]);
+  }
+  const idx =
+    opts.targetRevision === undefined
+      ? state.knownGood.length - 1
+      : state.knownGood.findIndex((f) => f.planRevision === opts.targetRevision);
+  const restored = idx < 0 ? undefined : state.knownGood[idx];
+  if (!restored) {
+    return refuse(state, "rollback", ctx, "unknown_target", [
+      `No known-good version "${opts.targetRevision}" is available to roll back to.`,
+    ]);
+  }
+  return apply(
+    state,
+    "rollback",
+    ctx,
+    {
+      ...state,
+      stages: { ...state.stages, live: restored },
+      knownGood: state.knownGood.slice(0, idx),
+    },
+    restored.planRevision,
+  );
+}
+
+/**
+ * `uninstall` — remove the integration completely. Every stage slot is cleared and
+ * the rollback history dropped, so nothing serves and no stale candidate/staged/live
+ * facet is left behind. The install status becomes `uninstalled` (terminal).
+ */
+export function removeIntegration(
+  state: TenantIntegrationLifecycleState,
+  ctx: LifecycleActionContext,
+): LifecycleResult {
+  if (state.installStatus === "uninstalled") {
+    return refuse(state, "uninstall", ctx, "already_removed", ["Install is already uninstalled."]);
+  }
+  return apply(
+    state,
+    "uninstall",
+    ctx,
+    {
+      ...state,
+      installStatus: "uninstalled",
+      stages: { local: null, candidate: null, staged: null, live: null },
+      knownGood: [],
+    },
+    null,
+  );
+}
+
+/** `suspend` — stop serving without removing. Live facets are retained for `resume`. */
+export function suspendIntegration(
+  state: TenantIntegrationLifecycleState,
+  ctx: LifecycleActionContext,
+): LifecycleResult {
+  if (state.installStatus !== "active") {
+    return refuse(state, "suspend", ctx, "not_active", [`Install is ${state.installStatus}; cannot suspend.`]);
+  }
+  return apply(state, "suspend", ctx, { ...state, installStatus: "suspended" }, state.stages.live?.planRevision ?? null);
+}
+
+/** `resume` — restore a suspended install to active; serving resumes exactly where it stopped. */
+export function resumeIntegration(
+  state: TenantIntegrationLifecycleState,
+  ctx: LifecycleActionContext,
+): LifecycleResult {
+  if (state.installStatus !== "suspended") {
+    return refuse(state, "resume", ctx, "not_suspended", [`Install is ${state.installStatus}; only a suspended install can resume.`]);
+  }
+  return apply(state, "resume", ctx, { ...state, installStatus: "active" }, state.stages.live?.planRevision ?? null);
+}
+
+/**
+ * What ACTUALLY serves in production right now — the `live` facets only while the
+ * install is active. A suspended or uninstalled install serves nothing, so a withdrawn
+ * install can never leave a stale live effect.
+ */
+export function effectiveServing(state: TenantIntegrationLifecycleState): StageFacets | null {
+  return state.installStatus === "active" ? state.stages.live : null;
+}
+
+/** The facets at one env stage — a DISTINCT read that never returns another stage's value. */
+export function stageFacets(
+  state: TenantIntegrationLifecycleState,
+  env: IntegrationEnvironment,
+): StageFacets | null {
+  return state.stages[env];
+}
+
+export interface LifecycleRollbackAvailability {
+  available: boolean;
+  targetRevision: string | null;
+  targetVersion: string | null;
+  reason: string;
+}
+
+/** Accurate rollback availability — reflects a real recorded known-good revision. */
+export function rollbackAvailability(state: TenantIntegrationLifecycleState): LifecycleRollbackAvailability {
+  const target = state.knownGood.at(-1) ?? null;
+  if (!target) {
+    return {
+      available: false,
+      targetRevision: null,
+      targetVersion: null,
+      reason: "No version has gone live yet; there is no known-good version to roll back to.",
+    };
+  }
+  return {
+    available: true,
+    targetRevision: target.planRevision,
+    targetVersion: target.version,
+    reason: `A known-good version (${target.version}) is available to roll back to.`,
+  };
+}