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

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}` : ""),
+        );
+      }
+    },
+  };
+}