@tokenoftrust/storefront-runner 1.3.4-rc.4 → 1.4.0

package/apps/storefront/src/lib/publish/dispatchHealth.ts

@@ -0,0 +1,269 @@
+/**
+ * Dispatch-health assessment (dg5) — is the static-publish `repository_dispatch`
+ * path actually WIRED and HEALTHY, or would a "go-live" silently hand the publish
+ * to a dead-end? The Worker fires a `repository_dispatch` and gets a 204 back
+ * having verified NOTHING about the target (see `createRepositoryDispatchSink` —
+ * it is fire-and-forget by construction). This module is the HONEST pre-flight
+ * surface that answers, per binding decision `static-publish-fails-closed-
+ * reviewed-sha`, whether that path can carry a publish at all — reporting each
+ * concrete signal pass/fail/unknown with a reason, never a silent assumption.
+ *
+ * FOUR SIGNALS:
+ *   - `dispatch-cred-present`               — is WWW_PUBLISH_DISPATCH_TOKEN set?
+ *   - `target-config-present`               — does this tenant declare a static
+ *                                             target AND does the dispatch repo resolve?
+ *   - `workflow-registered-on-default-branch` — is the publish workflow visible to
+ *                                             the Actions API? `repository_dispatch`
+ *                                             ONLY triggers workflows on the repo's
+ *                                             DEFAULT branch (main), so a workflow
+ *                                             that lives only on the deploy branch is
+ *                                             NOT yet reachable. A 404 here is the
+ *                                             honest "not yet promoted to main" state
+ *                                             (the HELD main-promotion gate,
+ *                                             `pending-main-promotion-and-production-
+ *                                             publish-activation`) — surfaced, not papered.
+ *   - `target-reachable`                    — does the published `live/manifest.json`
+ *                                             answer? DIAGNOSTIC ONLY: a pre-first-
+ *                                             publish target legitimately has none, so
+ *                                             this never blocks a ship (the post-merge
+ *                                             VERIFY in dg4's orchestrator is the real
+ *                                             no-false-live gate).
+ *
+ * FAIL-CLOSED SEMANTICS:
+ *   - `healthy` is true ONLY when every SHIP-CRITICAL signal (cred, target-config,
+ *     workflow-registration) is `pass`. An `unknown` is NOT healthy.
+ *   - `blockShip` is true only for a DEFINITIVELY-bad critical precondition (cred
+ *     missing, target-config missing, or a workflow 404). An `unknown` (e.g. the
+ *     Actions API is unreachable, or the token lacks read scope) does NOT set
+ *     `blockShip` — so GitHub reachability is never a hard dependency of every
+ *     accept; the orchestrator's post-merge verify still fails closed regardless.
+ */
+
+/** A single signal's honest state. `unknown` = we genuinely could not determine it. */
+export type DispatchHealthStatus = "pass" | "fail" | "unknown";
+
+export type DispatchHealthSignalId =
+  | "dispatch-cred-present"
+  | "target-config-present"
+  | "workflow-registered-on-default-branch"
+  | "target-reachable";
+
+export interface DispatchHealthSignal {
+  id: DispatchHealthSignalId;
+  status: DispatchHealthStatus;
+  /** Human/audit-legible reason for the status. */
+  detail: string;
+  /** Whether this signal gates a ship (false = diagnostic only, e.g. target-reachable). */
+  critical: boolean;
+}
+
+export interface DispatchHealthReport {
+  /** True ONLY when every ship-critical signal is `pass` (fail-closed: unknown ⇒ not healthy). */
+  healthy: boolean;
+  /**
+   * True when a ship should be REFUSED before merge because a critical precondition
+   * is DEFINITIVELY bad (never for an `unknown`). Consumed by the ship path so a
+   * static go-live never merges into a dead-end that could report a false live.
+   */
+  blockShip: boolean;
+  /** The one-line honest reason `blockShip` is set, else null. */
+  blockReason: string | null;
+  signals: DispatchHealthSignal[];
+}
+
+export interface AssessDispatchHealthInput {
+  /** WWW_PUBLISH_DISPATCH_TOKEN (presence only; the value never leaves env). */
+  dispatchToken: string | null;
+  /** `owner/repo` hosting the publish workflow (WWW_PUBLISH_DISPATCH_REPO). */
+  repoSlug: string | null;
+  /** The `repository_dispatch` event type (informational — surfaced for audit). */
+  eventType: string;
+  /** GitHub API base (default https://api.github.com); set for Enterprise. */
+  apiBase?: string;
+  /** The workflow file name the Actions API is probed for (e.g. "www-publish.yml"). */
+  workflowFile: string;
+  /** The tenant's static-publish target label when enabled, else null. */
+  staticPublishTarget: string | null;
+  /** Published-manifest URL for the `target-reachable` probe, or null when unresolved. */
+  manifestUrl: string | null;
+  /** Injectable fetch (Worker/Node global by default) — so this is unit-tested with no network. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Parse `owner/repo`, returning null when it isn't a clean two-part slug. */
+export function parseRepoSlug(slug: string | null): { owner: string; repo: string } | null {
+  if (!slug) return null;
+  const [owner, repo] = slug.split("/", 2);
+  if (!owner || !repo) return null;
+  return { owner, repo };
+}
+
+/**
+ * Probe the Actions API for the publish workflow. A 200 means GitHub has the
+ * workflow REGISTERED — which only happens once it is on the repo's DEFAULT
+ * branch, so `repository_dispatch` can trigger it. A 404 is the honest "not on the
+ * default branch yet" state. A 401/403/other/network error is `unknown` (we can't
+ * tell — often the token has write-only scope), NEVER a false pass or a hard block.
+ */
+async function probeWorkflowRegistered(
+  input: AssessDispatchHealthInput,
+  repo: { owner: string; repo: string },
+): Promise<DispatchHealthSignal> {
+  const base = {
+    id: "workflow-registered-on-default-branch" as const,
+    critical: true,
+  };
+  if (!input.dispatchToken) {
+    return { ...base, status: "unknown", detail: "cannot probe: dispatch credential absent" };
+  }
+  const apiBase = (input.apiBase ?? "https://api.github.com").replace(/\/+$/, "");
+  const url = `${apiBase}/repos/${repo.owner}/${repo.repo}/actions/workflows/${encodeURIComponent(input.workflowFile)}`;
+  const doFetch = input.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(url, {
+      headers: {
+        authorization: `Bearer ${input.dispatchToken}`,
+        accept: "application/vnd.github+json",
+        "user-agent": "tot-storefront-dispatch-health",
+      },
+    });
+  } catch (e) {
+    return { ...base, status: "unknown", detail: `Actions API unreachable: ${(e as Error).message}` };
+  }
+  if (res.status === 200) {
+    return {
+      ...base,
+      status: "pass",
+      detail: `${input.workflowFile} is registered on the default branch (repository_dispatch can trigger it)`,
+    };
+  }
+  if (res.status === 404) {
+    return {
+      ...base,
+      status: "fail",
+      detail:
+        `${input.workflowFile} is NOT registered on ${repo.owner}/${repo.repo}'s default branch ` +
+        `(main) — repository_dispatch cannot trigger it until it is promoted to main ` +
+        `(pending main-promotion gate).`,
+    };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return {
+      ...base,
+      status: "unknown",
+      detail: `Actions API returned HTTP ${res.status} — dispatch token lacks read scope; registration cannot be confirmed`,
+    };
+  }
+  return { ...base, status: "unknown", detail: `Actions API returned HTTP ${res.status}` };
+}
+
+/**
+ * Probe the published-manifest URL. DIAGNOSTIC ONLY (`critical: false`): a
+ * pre-first-publish target has no manifest yet, which is a legitimate bootstrap
+ * state, so this never gates a ship.
+ */
+async function probeTargetReachable(input: AssessDispatchHealthInput): Promise<DispatchHealthSignal> {
+  const base = { id: "target-reachable" as const, critical: false };
+  if (!input.manifestUrl) {
+    return { ...base, status: "unknown", detail: "no published-manifest URL resolved for this target" };
+  }
+  const doFetch = input.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await doFetch(input.manifestUrl, { headers: { accept: "application/json" } });
+  } catch (e) {
+    return { ...base, status: "unknown", detail: `manifest fetch failed: ${(e as Error).message}` };
+  }
+  if (!res.ok) {
+    return {
+      ...base,
+      status: res.status === 404 ? "fail" : "unknown",
+      detail: `manifest HTTP ${res.status}${res.status === 404 ? " (target not yet published — bootstrap)" : ""}`,
+    };
+  }
+  let hasDigest = false;
+  try {
+    const manifest = (await res.json()) as { treeDigest?: unknown };
+    hasDigest = typeof manifest.treeDigest === "string" && manifest.treeDigest.length > 0;
+  } catch {
+    return { ...base, status: "fail", detail: "manifest was not valid JSON" };
+  }
+  return {
+    ...base,
+    status: "pass",
+    detail: hasDigest ? "target serves a published manifest with a treeDigest" : "target reachable (manifest carries no treeDigest yet)",
+  };
+}
+
+/**
+ * Assess the dispatch path's health. Runs the two network probes concurrently.
+ * Pure w.r.t. its inputs — the caller resolves env/config and injects `fetchImpl`.
+ */
+export async function assessDispatchHealth(
+  input: AssessDispatchHealthInput,
+): Promise<DispatchHealthReport> {
+  const repo = parseRepoSlug(input.repoSlug);
+
+  const credSignal: DispatchHealthSignal = input.dispatchToken
+    ? {
+        id: "dispatch-cred-present",
+        status: "pass",
+        detail: "WWW_PUBLISH_DISPATCH_TOKEN is configured",
+        critical: true,
+      }
+    : {
+        id: "dispatch-cred-present",
+        status: "fail",
+        detail: "WWW_PUBLISH_DISPATCH_TOKEN is not set — the Worker cannot fire repository_dispatch",
+        critical: true,
+      };
+
+  const targetConfigSignal: DispatchHealthSignal =
+    input.staticPublishTarget && repo
+      ? {
+          id: "target-config-present",
+          status: "pass",
+          detail: `static target "${input.staticPublishTarget}" → dispatch repo ${repo.owner}/${repo.repo} (event ${input.eventType})`,
+          critical: true,
+        }
+      : {
+          id: "target-config-present",
+          status: "fail",
+          detail: !input.staticPublishTarget
+            ? "tenant declares no enabled static-publish target"
+            : "dispatch repo (WWW_PUBLISH_DISPATCH_REPO) does not resolve to owner/repo",
+          critical: true,
+        };
+
+  // The workflow probe needs a resolved repo; without one it can't be evaluated.
+  const workflowSignal: DispatchHealthSignal = repo
+    ? await probeWorkflowRegistered(input, repo)
+    : {
+        id: "workflow-registered-on-default-branch",
+        status: "unknown",
+        detail: "cannot probe: dispatch repo does not resolve",
+        critical: true,
+      };
+
+  const reachableSignal = await probeTargetReachable(input);
+
+  const signals: DispatchHealthSignal[] = [
+    credSignal,
+    targetConfigSignal,
+    workflowSignal,
+    reachableSignal,
+  ];
+
+  const critical = signals.filter((s) => s.critical);
+  const healthy = critical.every((s) => s.status === "pass");
+  // Block a ship only for a DEFINITIVELY-bad critical precondition — never an unknown.
+  const blocker = critical.find((s) => s.status === "fail") ?? null;
+
+  return {
+    healthy,
+    blockShip: blocker !== null,
+    blockReason: blocker ? `${blocker.id}: ${blocker.detail}` : null,
+    signals,
+  };
+}

package/apps/storefront/src/lib/publish/domainState.ts

@@ -0,0 +1,351 @@
+/**
+ * Apex domain-connect state + dispatch (handoff 2026-08-05-domain-connect-ux).
+ *
+ * The admin Publish tab's "Domain" section drives the apex DNS cutover
+ * (tokenoftrust.com → CloudFront) and its rollback as PRODUCT actions, not a
+ * terminal runbook. The Worker holds no AWS credentials: it fires the SAME
+ * `repository_dispatch` seam www-publish uses (`event_type=www-domain`,
+ * `client_payload.action: connect | rollback`) and the CI workflow (OIDC role)
+ * runs the existing scripts. This module owns:
+ *
+ *   - the per-tenant domain-cutover STATE record (KV) — current state
+ *     (`pantheon` | `cloudfront`), prior-DNS-records capture pointer, and the
+ *     last/in-flight run;
+ *   - the PURE state transitions (`beginDomainRun` / `completeDomainRun`) so
+ *     the refusal + completion policy is unit-testable without I/O;
+ *   - the dispatch transport (`createDomainDispatch`) mirroring
+ *     `createRepositoryDispatchSink`'s contract (throw on non-2xx).
+ *
+ * STATUS-BACK CHOICE (handoff asks to pick one and say why): CI posts a
+ * completion CALLBACK to the Worker (`POST /api/domain/callback`, HMAC over the
+ * raw body — the same webhook trust shape as `/api/preview/reconcile`), rather
+ * than the Worker polling GitHub run status. Why: the dispatch token is a
+ * write-only fine-grained credential (actions:write) and the Worker should not
+ * grow a GitHub READ credential + polling loop when the reconcile webhook trust
+ * model already exists and CI knows exactly when it finished.
+ */
+
+/** Where the apex DNS points right now. `pantheon` is the pre-cutover host. */
+export type DomainPlatformState = "pantheon" | "cloudfront";
+
+export type DomainAction = "connect" | "rollback";
+
+/** CI callbacks are terminal-only (succeeded|failed); "dispatched" is the in-flight state. */
+export type DomainRunStatus = "dispatched" | "succeeded" | "failed";
+
+/** One connect/rollback run — audit fields included (who/when, accept.ts-style). */
+export interface DomainRun {
+  /** The dispatch correlation id — `dispatchId` on the wire (both directions). */
+  runId: string;
+  action: DomainAction;
+  /** Dry-run rehearsal (cutover-dns.mjs --dry-run in CI) — never moves state. */
+  rehearsal: boolean;
+  status: DomainRunStatus;
+  /** Audit: the acting operator (viewer email / owner), never from the body. */
+  actor: string;
+  startedAt: string;
+  finishedAt: string | null;
+  /** CI run link once known (from the completion callback). */
+  runUrl: string | null;
+  /** Legible failure detail, or null. */
+  error: string | null;
+}
+
+/** The per-tenant domain-cutover state record (KV, `www-domain:state:<tenantId>`). */
+export interface DomainState {
+  state: DomainPlatformState;
+  /** When the current `state` took effect (ISO), or null if never cutover. */
+  since: string | null;
+  /**
+   * S3 key of the captured prior DNS records powering rollback
+   * (`meta/dns-prior-records.<ts>.json`) + when they were captured. Written by
+   * CI (which does the capture) via the completion callback.
+   */
+  priorRecordsKey: string | null;
+  priorCapturedAt: string | null;
+  lastRun: DomainRun | null;
+}
+
+/** KV key for a tenant's domain-cutover state. */
+export function domainStateKey(tenantId: string): string {
+  return `www-domain:state:${tenantId}`;
+}
+
+/** The starting state for a tenant that has never been cutover. */
+export function initialDomainState(): DomainState {
+  return {
+    state: "pantheon",
+    since: null,
+    priorRecordsKey: null,
+    priorCapturedAt: null,
+    lastRun: null,
+  };
+}
+
+/** Minimal KV surface (matches the `CandidateKv` shape used across the repo). */
+export interface DomainStateKv {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+
+/** Read a tenant's domain state; a missing/corrupt record is the initial state. */
+export async function readDomainState(
+  kv: DomainStateKv,
+  tenantId: string,
+): Promise<DomainState> {
+  const raw = await kv.get(domainStateKey(tenantId));
+  if (!raw) return initialDomainState();
+  try {
+    const parsed = JSON.parse(raw) as DomainState;
+    if (parsed.state !== "pantheon" && parsed.state !== "cloudfront") {
+      return initialDomainState();
+    }
+    return parsed;
+  } catch {
+    return initialDomainState();
+  }
+}
+
+export async function writeDomainState(
+  kv: DomainStateKv,
+  tenantId: string,
+  state: DomainState,
+): Promise<void> {
+  await kv.put(domainStateKey(tenantId), JSON.stringify(state));
+}
+
+export type DomainTransitionResult =
+  | { ok: true; state: DomainState }
+  | { ok: false; status: number; error: string };
+
+/** True when the state's last run is still in flight (awaiting the CI callback). */
+export function runInFlight(state: DomainState): boolean {
+  return state.lastRun?.status === "dispatched";
+}
+
+/**
+ * PURE: begin a connect/rollback run. Refuses (409) while a run is in flight —
+ * two concurrent DNS mutations is exactly the race this state exists to prevent.
+ * Also refuses (409) a non-rehearsal connect when already on `cloudfront`, and a
+ * rollback when there is no captured prior-records pointer to restore from
+ * (nothing to roll back TO — CI would have nothing to apply).
+ */
+export function beginDomainRun(
+  state: DomainState,
+  run: {
+    runId: string;
+    action: DomainAction;
+    rehearsal: boolean;
+    actor: string;
+    at: string;
+  },
+): DomainTransitionResult {
+  if (runInFlight(state)) {
+    return {
+      ok: false,
+      status: 409,
+      error: `a ${state.lastRun?.action} run is already in flight (${state.lastRun?.runId})`,
+    };
+  }
+  if (run.action === "connect" && !run.rehearsal && state.state === "cloudfront") {
+    return {
+      ok: false,
+      status: 409,
+      error: "domain is already connected (state: cloudfront)",
+    };
+  }
+  if (run.action === "rollback" && !run.rehearsal && !state.priorRecordsKey) {
+    return {
+      ok: false,
+      status: 409,
+      error: "no captured prior DNS records to roll back to",
+    };
+  }
+  return {
+    ok: true,
+    state: {
+      ...state,
+      lastRun: {
+        runId: run.runId,
+        action: run.action,
+        rehearsal: run.rehearsal,
+        status: "dispatched",
+        actor: run.actor,
+        startedAt: run.at,
+        finishedAt: null,
+        runUrl: null,
+        error: null,
+      },
+    },
+  };
+}
+
+/**
+ * The CI completion callback (wire contract with the www-domain workflow,
+ * branch issue/www-publish-auto-path). Terminal-only: succeeded | failed.
+ * Correlated on `dispatchId` — the id WE minted at dispatch time and sent in
+ * `client_payload.dispatchId`; the workflow's `runId`/`runUrl` identify the GH
+ * Actions run and are recorded/surfaced, never used for correlation.
+ */
+export interface DomainRunCallback {
+  /** Round-trips from `client_payload.dispatchId` — the correlation key. */
+  dispatchId: string;
+  status: "succeeded" | "failed";
+  /** CI-reported resulting platform state ("unknown" → infer from the action). */
+  state?: "cloudfront" | "pantheon" | "unknown" | null;
+  /** GH Actions run link — surfaced in the UI status. */
+  runUrl?: string | null;
+  error?: string | null;
+  /** On a successful connect: where CI persisted the prior-records capture. */
+  priorKey?: string | null;
+  completedAt?: string | null;
+}
+
+/**
+ * PURE: apply a CI completion callback. A callback for an unknown `dispatchId`
+ * is refused (409) — it belongs to a run this state never dispatched (or one
+ * that was superseded), and applying it would corrupt the record.
+ *
+ * On a SUCCESSFUL non-rehearsal (non-dryRun) run the platform state flips to
+ * the CI-reported `state` when concrete, else inferred from the action:
+ *   connect  → `cloudfront` (+ prior-records pointer from `priorKey`; never
+ *              overwrite an existing pointer with null — the FIRST capture is
+ *              the true pre-platform state)
+ *   rollback → `pantheon`
+ * Rehearsal (wire: dryRun) runs never move state — only the run outcome is
+ * recorded.
+ */
+export function completeDomainRun(
+  state: DomainState,
+  cb: DomainRunCallback,
+  at: string,
+): DomainTransitionResult {
+  const run = state.lastRun;
+  if (!run || run.runId !== cb.dispatchId) {
+    return {
+      ok: false,
+      status: 409,
+      error: `callback for unknown dispatch "${cb.dispatchId}"`,
+    };
+  }
+  if (run.status === "succeeded" || run.status === "failed") {
+    return {
+      ok: false,
+      status: 409,
+      error: `dispatch "${cb.dispatchId}" already completed (${run.status})`,
+    };
+  }
+
+  const updatedRun: DomainRun = {
+    ...run,
+    status: cb.status,
+    runUrl: cb.runUrl ?? run.runUrl,
+    error: cb.status === "failed" ? (cb.error ?? "run failed") : null,
+    finishedAt: cb.completedAt ?? at,
+  };
+
+  let next: DomainState = { ...state, lastRun: updatedRun };
+  if (cb.status === "succeeded" && !run.rehearsal) {
+    const reported =
+      cb.state === "cloudfront" || cb.state === "pantheon" ? cb.state : null;
+    next = {
+      ...next,
+      state: reported ?? (run.action === "connect" ? "cloudfront" : "pantheon"),
+      since: updatedRun.finishedAt,
+    };
+    if (run.action === "connect") {
+      next = {
+        ...next,
+        // Keep the FIRST capture if the callback carries none — never regress
+        // the pointer to null once a real capture exists.
+        priorRecordsKey: cb.priorKey ?? state.priorRecordsKey,
+        priorCapturedAt: cb.priorKey
+          ? (cb.completedAt ?? at)
+          : state.priorCapturedAt,
+      };
+    }
+  }
+  return { ok: true, state: next };
+}
+
+/** Config for the `www-domain` repository_dispatch (env-sourced, never tenant config). */
+export interface DomainDispatchConfig {
+  apiBase?: string;
+  owner: string;
+  repo: string;
+  /** `repository_dispatch` event type; the workflow shim routes on it. */
+  eventType: string;
+  /** Bearer token with actions:write — never logged. */
+  token: string;
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * The `client_payload` wire contract shared with the www-domain CI workflow
+ * (branch issue/www-publish-auto-path). The CI shim GATES on the presence/shape
+ * of `tenantId`, `action`, `dispatchId`, `callbackUrl`, and `dryRun`; the
+ * remaining fields are ADDITIONAL keys (audit-only, tolerated by the shim).
+ */
+export interface DomainDispatchPayload {
+  tenantId: string;
+  action: DomainAction;
+  /** Correlation id — round-trips back as the callback's `dispatchId`. */
+  dispatchId: string;
+  /** Absolute plain-https URL of /api/domain/callback (CI gates: https, no query/userinfo). */
+  callbackUrl: string;
+  /** The rehearsal flag on the wire. */
+  dryRun: boolean;
+  // --- additional (non-gated) audit keys ---
+  appDomain: string;
+  /** Audit only — CI echoes it back; authorization happened Worker-side. */
+  actor: string;
+  dispatchedAt: string;
+}
+
+/**
+ * Fire the `www-domain` repository_dispatch. Mirrors
+ * `createRepositoryDispatchSink` (publish-sink.ts): a non-2xx response or a
+ * transport error THROWS, so the caller never records a dispatched run that was
+ * never actually dispatched.
+ */
+export function createDomainDispatch(config: DomainDispatchConfig) {
+  const apiBase = (config.apiBase ?? "https://api.github.com").replace(/\/+$/, "");
+  const doFetch = config.fetchImpl ?? fetch;
+  return {
+    async dispatch(payload: DomainDispatchPayload): Promise<void> {
+      const url = `${apiBase}/repos/${config.owner}/${config.repo}/dispatches`;
+      let res: Response;
+      try {
+        res = await doFetch(url, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${config.token}`,
+            accept: "application/vnd.github+json",
+            "content-type": "application/json",
+            "user-agent": "tot-storefront-domain-dispatch",
+          },
+          body: JSON.stringify({
+            event_type: config.eventType,
+            client_payload: payload,
+          }),
+        });
+      } catch (e) {
+        throw new Error(
+          `domain dispatch to ${config.owner}/${config.repo} failed: ${(e as Error).message}`,
+        );
+      }
+      if (!res.ok) {
+        let detail = "";
+        try {
+          detail = (await res.text()).slice(0, 500);
+        } catch {
+          /* keep the HTTP status */
+        }
+        throw new Error(
+          `domain dispatch to ${config.owner}/${config.repo} returned HTTP ${res.status}` +
+            (detail ? `: ${detail}` : ""),
+        );
+      }
+    },
+  };
+}