@caelo-cms/provisioning 0.10.47 → 0.10.49

package/src/agent/units.test.ts

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The agent's systemd units (agent/units.ts) and their installation
+ * (agent/systemd.ts) — against a temp unit directory and a fake runner, so
+ * no real systemd is touched.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CommandResult, HostRunner } from "../self-hosted-release.js";
+import {
+  type AgentHost,
+  agentHostProblem,
+  agentLogsArgv,
+  installAgentUnits,
+  installedAgentVersion,
+  repinAgentUnits,
+  uninstallAgentUnits,
+} from "./systemd.js";
+import {
+  type AgentUnitSpec,
+  agentServiceUnit,
+  agentTimerUnit,
+  agentUnitName,
+  pinnedAgentVersion,
+} from "./units.js";
+
+const SPEC: AgentUnitSpec = {
+  name: "caelo-agent-example-com",
+  domain: "example.com",
+  version: "0.10.47",
+  bunPath: "/home/op/.bun/bin/bun",
+  caeloDir: "/srv/caelo site/.caelo",
+  workDir: "/srv/caelo site",
+  path: "/home/op/.bun/bin:/usr/local/bin:/usr/bin:/bin",
+};
+
+describe("agent units", () => {
+  it("names one agent per install after its domain, kept apart by the install's folder", () => {
+    expect(agentUnitName("Example.com", "/srv/a/.caelo")).toMatch(
+      /^caelo-agent-example-com-[0-9a-f]{8}$/,
+    );
+    expect(agentUnitName("a.b.example.com", "/srv/one/.caelo")).not.toBe(
+      agentUnitName("a-b.example.com", "/srv/two/.caelo"),
+    );
+    expect(agentUnitName("example.com", "/srv/a/.caelo")).toBe(
+      agentUnitName("example.com", "/srv/a/.caelo"),
+    );
+    expect(() => agentUnitName("...", "/srv/a/.caelo")).toThrow();
+  });
+
+  it("runs the pinned CLI as a oneshot, as the user, never as root", () => {
+    const unit = agentServiceUnit(SPEC);
+    expect(unit).toContain("Type=oneshot");
+    expect(unit).toContain(
+      'ExecStart="/home/op/.bun/bin/bun" "x" "--bun" "@caelo-cms/provisioning@0.10.47" "agent" "run"',
+    );
+    expect(unit).toContain('WorkingDirectory="/srv/caelo site"');
+    expect(unit).toContain('Environment="CAELO_SELF_HOSTED_DIR=/srv/caelo site/.caelo"');
+    expect(unit).toContain("UMask=0077");
+    expect(unit).toContain("NoNewPrivileges=yes");
+    expect(unit).not.toMatch(/^User=|^Group=|docker\.sock/m);
+    expect(unit).not.toContain("DOCKER_HOST");
+    expect(pinnedAgentVersion(unit)).toBe("0.10.47");
+  });
+
+  it("passes a rootless DOCKER_HOST through and escapes systemd specifiers", () => {
+    const unit = agentServiceUnit({
+      ...SPEC,
+      dockerHost: "unix:///run/user/1000/docker.sock",
+      workDir: "/srv/100%",
+    });
+    expect(unit).toContain('Environment="DOCKER_HOST=unix:///run/user/1000/docker.sock"');
+    expect(unit).toContain('WorkingDirectory="/srv/100%%"');
+  });
+
+  it("after an update, runs the provenance-verified CLI instead of bun x", () => {
+    const cliPath =
+      "/srv/caelo site/.caelo/agent/cli/caelo-0.11.0/node_modules/@caelo-cms/provisioning/dist/cli.js";
+    const unit = agentServiceUnit({ ...SPEC, version: "0.11.0", cliPath });
+    expect(unit).toContain(`ExecStart="/home/op/.bun/bin/bun" "${cliPath}" "agent" "run"`);
+    expect(unit).not.toContain('"x"');
+    expect(pinnedAgentVersion(unit)).toBe("0.11.0");
+  });
+
+  it("refuses values that cannot be one systemd word", () => {
+    expect(() => agentServiceUnit({ ...SPEC, workDir: '/srv/"x"' })).toThrow();
+    expect(() => agentServiceUnit({ ...SPEC, path: "/bin\nExecStartPre=/evil" })).toThrow();
+    expect(() => agentServiceUnit({ ...SPEC, version: "latest" })).toThrow();
+  });
+
+  it("polls a minute after each run ends, from boot", () => {
+    const timer = agentTimerUnit(SPEC);
+    expect(timer).toContain("OnUnitInactiveSec=60s");
+    expect(timer).toContain("OnBootSec=2min");
+    expect(timer).toContain("OnActiveSec=1min");
+    expect(timer).toContain("Unit=caelo-agent-example-com.service");
+    expect(timer).toContain("WantedBy=timers.target");
+  });
+
+  it("shows the service's journal", () => {
+    expect(agentLogsArgv("caelo-agent-x", { lines: 50, follow: true })).toEqual([
+      "journalctl",
+      "--user",
+      "--no-pager",
+      "-u",
+      "caelo-agent-x.service",
+      "-n",
+      "50",
+      "-f",
+    ]);
+  });
+});
+
+type Rule = (line: string) => Partial<CommandResult> | undefined;
+
+function fakeRunner(rules: Rule[] = []): HostRunner & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    calls,
+    async run(argv) {
+      const line = argv.join(" ");
+      calls.push(line);
+      const hit = rules.map((r) => r(line)).find((r) => r !== undefined);
+      return { exitCode: 0, stdout: "", stderr: "", ...hit };
+    },
+  };
+}
+
+describe("agent units on the host", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "caelo-agent-units-"));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  const hostWith = (runner: HostRunner, platform: NodeJS.Platform = "linux"): AgentHost => ({
+    runner,
+    unitDir: join(dir, "systemd", "user"),
+    user: "op",
+    platform,
+  });
+
+  it("supports Linux with a systemd user manager only", async () => {
+    expect(await agentHostProblem(hostWith(fakeRunner(), "darwin"))).toContain("Linux");
+    const noBus = fakeRunner([
+      (l) =>
+        l.includes("show-environment")
+          ? { exitCode: 1, stderr: "Failed to connect to bus" }
+          : undefined,
+    ]);
+    expect(await agentHostProblem(hostWith(noBus))).toContain("Failed to connect to bus");
+    expect(await agentHostProblem(hostWith(fakeRunner()))).toBeNull();
+  });
+
+  it("writes both units, enables the timer and switches lingering on — idempotently", async () => {
+    const runner = fakeRunner([
+      (l) => (l.startsWith("loginctl show-user") ? { stdout: "Linger=no\n" } : undefined),
+    ]);
+    const host = hostWith(runner);
+    for (let i = 0; i < 2; i++) {
+      expect(await installAgentUnits(SPEC, host)).toEqual({ ok: true, warnings: [] });
+    }
+    const service = readFileSync(join(host.unitDir, `${SPEC.name}.service`), "utf8");
+    expect(service).toBe(agentServiceUnit(SPEC));
+    expect(existsSync(join(host.unitDir, `${SPEC.name}.timer`))).toBe(true);
+    expect(runner.calls).toContain("systemctl --user daemon-reload");
+    expect(runner.calls).toContain(`systemctl --user enable --now ${SPEC.name}.timer`);
+    expect(runner.calls).toContain("loginctl enable-linger op");
+    expect(installedAgentVersion(host, SPEC.name)).toBe("0.10.47");
+  });
+
+  it("says what an administrator runs when lingering may not be switched on", async () => {
+    const runner = fakeRunner([
+      (l) =>
+        l.startsWith("loginctl enable-linger")
+          ? { exitCode: 1, stderr: "Access denied" }
+          : undefined,
+    ]);
+    const r = await installAgentUnits(SPEC, hostWith(runner));
+    expect(r.ok && r.warnings.join(" ")).toContain("sudo loginctl enable-linger op");
+  });
+
+  it("fails loudly when systemd refuses the timer", async () => {
+    const runner = fakeRunner([
+      (l) => (l.includes("enable --now") ? { exitCode: 1, stderr: "Unit not found" } : undefined),
+    ]);
+    const r = await installAgentUnits(SPEC, hostWith(runner));
+    expect(r).toEqual({
+      ok: false,
+      error: `systemctl --user enable --now ${SPEC.name}.timer: Unit not found`,
+    });
+  });
+
+  it("re-pins an installed agent after an update, and leaves an absent one absent", async () => {
+    const runner = fakeRunner();
+    const host = hostWith(runner);
+    expect(await repinAgentUnits({ ...SPEC, version: "0.11.0" }, host)).toMatchObject({
+      ok: true,
+      installed: false,
+    });
+    expect(installedAgentVersion(host, SPEC.name)).toBeNull();
+    await installAgentUnits(SPEC, host);
+    expect(await repinAgentUnits({ ...SPEC, version: "0.11.0" }, host)).toMatchObject({
+      ok: true,
+      installed: true,
+    });
+    expect(installedAgentVersion(host, SPEC.name)).toBe("0.11.0");
+  });
+
+  it("uninstalls: timer off, both files gone", async () => {
+    const runner = fakeRunner();
+    const host = hostWith(runner);
+    await installAgentUnits(SPEC, host);
+    expect((await uninstallAgentUnits(host, SPEC.name)).ok).toBe(true);
+    expect(runner.calls).toContain(`systemctl --user disable --now ${SPEC.name}.timer`);
+    expect(existsSync(join(host.unitDir, `${SPEC.name}.service`))).toBe(false);
+    expect(existsSync(join(host.unitDir, `${SPEC.name}.timer`))).toBe(false);
+  });
+});

package/src/agent/units.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The systemd units of `caelo-agent` (#696 Phase 4c), as text. Pure, so the
+ * exact files are unit-tested; agent/systemd.ts installs them.
+ *
+ * Why a systemd --user timer on the host, and not a container: the agent
+ * has to run `docker compose` for the install, and the only way a container
+ * could is the Docker socket — root on the host for anything that gets into
+ * that container (Watchtower, the usual answer, was archived in 2025 and
+ * verifies no signatures). The agent instead runs as the operator who ran
+ * `init`, a member of the `docker` group like that operator already is to
+ * run Compose at all; nothing new gets Docker access, and no unit runs as
+ * root.
+ *
+ * Shape: a oneshot service (one poll: heartbeat, then claim and run at most
+ * one request) started by a timer every {@link PLATFORM_UPDATE_AGENT_POLL_SECONDS}
+ * seconds after the previous run ended — systemd never starts the service
+ * while a run (an upgrade can take many minutes) is still active.
+ *
+ * The service runs the provisioning CLI pinned to an exact release
+ * (`bun x --bun @caelo-cms/provisioning@<version> agent run`); a successful
+ * update re-pins it to the release it installed.
+ */
+
+import { createHash } from "node:crypto";
+import { PLATFORM_UPDATE_AGENT_POLL_SECONDS } from "@caelo-cms/shared";
+
+/** Everything the units name; all paths absolute. */
+export interface AgentUnitSpec {
+  /** Unit base name (`caelo-agent-<domain>-<hash>`), see {@link agentUnitName}. */
+  readonly name: string;
+  readonly domain: string;
+  /** The provisioning release the service runs. */
+  readonly version: string;
+  /** The `bun` binary (the one that ran `init`). */
+  readonly bunPath: string;
+  /** The install's `.caelo/` directory. */
+  readonly caeloDir: string;
+  /** Where `.caelo/` lives (the service's working directory). */
+  readonly workDir: string;
+  /** PATH for the service: docker, cosign and bun must be on it. */
+  readonly path: string;
+  /** DOCKER_HOST of the installing shell (rootless Docker), when set. */
+  readonly dockerHost?: string;
+  /**
+   * The provenance-verified CLI of {@link version} (agent/cli-provenance.ts)
+   * — what an update re-pins the agent to. Without it the service runs the
+   * release the operator installed with (`bun x`, as they did by hand).
+   */
+  readonly cliPath?: string;
+}
+
+/** The longest a single run (one full upgrade) may take before systemd stops it. */
+export const AGENT_RUN_TIMEOUT_MINUTES = 80;
+
+/**
+ * `caelo-agent-<domain>-<hash>`: one agent per install, several installs
+ * per host possible. The slug is for people; the hash of the install's
+ * `.caelo/` path keeps two installs apart even when their slugs collide
+ * (`a.b.example.com` vs `a-b.example.com`).
+ */
+export function agentUnitName(domain: string, caeloDir: string): string {
+  const slug = domain
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  if (!slug) throw new Error(`cannot name the agent unit after domain ${JSON.stringify(domain)}`);
+  const hash = createHash("sha256").update(caeloDir).digest("hex").slice(0, 8);
+  return `caelo-agent-${slug}-${hash}`;
+}
+
+/** The package the service runs, pinned. */
+export function agentPackageRef(version: string): string {
+  if (!/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`not a release version: ${JSON.stringify(version)}`);
+  }
+  return `@caelo-cms/provisioning@${version}`;
+}
+
+/**
+ * One systemd word: double-quoted, `%` escaped (systemd specifiers). Values
+ * with a quote, backslash or control character are refused rather than
+ * escaped — they are paths and versions, and such a path is a mistake.
+ */
+function word(value: string): string {
+  if (!value || /["\\\p{Cc}]/u.test(value)) {
+    throw new Error(`cannot put ${JSON.stringify(value)} into a systemd unit`);
+  }
+  return `"${value.replace(/%/g, "%%")}"`;
+}
+
+/** `Environment="KEY=value"`. */
+function environment(key: string, value: string): string {
+  return `Environment=${word(`${key}=${value}`)}`;
+}
+
+/** The argv of one agent run (also what `agent status` shows). */
+export function agentRunArgv(
+  spec: Pick<AgentUnitSpec, "bunPath" | "version" | "cliPath">,
+): string[] {
+  if (spec.cliPath) return [spec.bunPath, spec.cliPath, "agent", "run"];
+  return [spec.bunPath, "x", "--bun", agentPackageRef(spec.version), "agent", "run"];
+}
+
+/** `<name>.service`. */
+export function agentServiceUnit(spec: AgentUnitSpec): string {
+  return [
+    "# SPDX-License-Identifier: MPL-2.0",
+    "# Generated by cms-provision (agent install) — do not edit; re-run it instead.",
+    "[Unit]",
+    `Description=Caelo update agent for ${spec.domain}`,
+    "Documentation=https://caelo-cms.com/install-self-hosted",
+    "After=network-online.target",
+    "",
+    "[Service]",
+    "Type=oneshot",
+    `WorkingDirectory=${word(spec.workDir)}`,
+    environment("CAELO_SELF_HOSTED_DIR", spec.caeloDir),
+    environment("PATH", spec.path),
+    ...(spec.dockerHost ? [environment("DOCKER_HOST", spec.dockerHost)] : []),
+    `ExecStart=${agentRunArgv(spec).map(word).join(" ")}`,
+    `TimeoutStartSec=${AGENT_RUN_TIMEOUT_MINUTES}min`,
+    // Backups, config.json and the lock file: the operator's only.
+    "UMask=0077",
+    "NoNewPrivileges=yes",
+    "Nice=5",
+    "",
+  ].join("\n");
+}
+
+/** `<name>.timer`. */
+export function agentTimerUnit(spec: Pick<AgentUnitSpec, "name" | "domain">): string {
+  return [
+    "# SPDX-License-Identifier: MPL-2.0",
+    "# Generated by cms-provision (agent install) — do not edit; re-run it instead.",
+    "[Unit]",
+    `Description=Poll for Caelo updates for ${spec.domain}`,
+    "",
+    "[Timer]",
+    // The first poll a minute after the timer starts (install, boot);
+    // then a minute after each run ends.
+    "OnActiveSec=1min",
+    "OnBootSec=2min",
+    `OnUnitInactiveSec=${PLATFORM_UPDATE_AGENT_POLL_SECONDS}s`,
+    "AccuracySec=5s",
+    `Unit=${spec.name}.service`,
+    "",
+    "[Install]",
+    "WantedBy=timers.target",
+    "",
+  ].join("\n");
+}
+
+/** The release an installed service file runs, or null when it names none. */
+export function pinnedAgentVersion(serviceUnit: string): string | null {
+  const exec = /^ExecStart=.*$/m.exec(serviceUnit)?.[0] ?? "";
+  const m =
+    /@caelo-cms\/provisioning@([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)"/.exec(exec) ??
+    /\/caelo-([0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?)\/node_modules\//.exec(exec);
+  return m?.[1] ?? null;
+}

package/src/azure-front-door.test.ts

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The public site on every provider is object storage behind the provider's
+ * CDN, with no edge compute on the request path (CLAUDE.md §11.B Tier 1).
+ * Epic #676 removed the per-provider A/B edge routers; these checks keep them
+ * from coming back and pin the Azure primary domain to its Front Door
+ * endpoint. Stack checks are pure-string, like the other stack tests.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { azureFrontDoorDnsRecords } from "./azure-front-door.js";
+
+const stackDir = (provider: string) => resolve(import.meta.dir, `../stacks/${provider}`);
+const stack = (provider: string) => readFileSync(`${stackDir(provider)}/index.ts`, "utf8");
+
+describe("azureFrontDoorDnsRecords", () => {
+  const records = azureFrontDoorDnsRecords({
+    domain: "example.com",
+    endpointHostName: "caeloproduction-site-abc123.z01.azurefd.net",
+    validationToken: "tok-123",
+  });
+
+  it("points the primary domain at the Front Door endpoint", () => {
+    expect(records).toContainEqual(
+      expect.objectContaining({
+        hostname: "example.com",
+        type: "CNAME",
+        value: "caeloproduction-site-abc123.z01.azurefd.net",
+      }),
+    );
+  });
+
+  it("publishes the managed-certificate validation token", () => {
+    expect(records).toContainEqual(
+      expect.objectContaining({ hostname: "_dnsauth.example.com", type: "TXT", value: "tok-123" }),
+    );
+  });
+
+  it("refuses an endpoint without a hostname instead of emitting a dangling record", () => {
+    expect(() =>
+      azureFrontDoorDnsRecords({
+        domain: "example.com",
+        endpointHostName: "",
+        validationToken: "t",
+      }),
+    ).toThrow(/no hostName/);
+  });
+
+  it("refuses a custom domain without a validation token", () => {
+    expect(() =>
+      azureFrontDoorDnsRecords({
+        domain: "example.com",
+        endpointHostName: "x.azurefd.net",
+        validationToken: "",
+      }),
+    ).toThrow(/no validation token/);
+  });
+});
+
+describe("azure stack — static site behind Front Door", () => {
+  const src = stack("azure");
+
+  it("builds its DNS records from the Front Door endpoint and custom domain", () => {
+    expect(src).toContain("new azure.cdn.AFDEndpoint(");
+    expect(src).toContain("new azure.cdn.AFDCustomDomain(");
+    expect(src).toMatch(
+      /pulumi\s*\.all\(\[frontDoorEndpoint\.hostName, siteDomain\.validationProperties\]\)[\s\S]*?azureFrontDoorDnsRecords\(/,
+    );
+  });
+
+  it("routes the custom domain to the static-website origin", () => {
+    expect(src).toContain("new azure.storage.StorageAccountStaticWebsite(");
+    expect(src).toMatch(
+      /new azure\.cdn\.Route\([\s\S]*?customDomains: \[\{ id: siteDomain\.id \}\]/,
+    );
+  });
+
+  it("keeps owning the published $web container and edge-caches the route", () => {
+    expect(src).toMatch(/new azure\.storage\.BlobContainer\([\s\S]*?containerName: "\$web"/);
+    expect(src).toMatch(/new azure\.cdn\.Route\([\s\S]*?cacheConfiguration: \{/);
+  });
+
+  it("exposes no Container App to the public internet", () => {
+    expect(src).toContain("external: false");
+    expect(src).not.toMatch(/external:\s*(true|args\.)/);
+  });
+});
+
+describe("aws stack — edge-log sink", () => {
+  const src = stack("aws");
+
+  it("delivers CloudFront access logs to the log group it reports as the sink", () => {
+    expect(src).toMatch(
+      /new aws\.cloudwatch\.LogDeliverySource\([\s\S]*?logType: "ACCESS_LOGS",\s*resourceArn: distribution\.arn/,
+    );
+    expect(src).toContain("destinationResourceArn: edgeLogGroup.arn");
+    expect(src).toMatch(/cloudwatch:\/\/us-east-1\/\$\{edgeLogGroup\.name\}/);
+  });
+});
+
+describe.each(["aws", "azure", "gcp", "gcp-firebase", "self-hosted"])(
+  "%s stack — no edge router",
+  (provider) => {
+    const src = stack(provider);
+
+    it("runs no edge compute for the public site", () => {
+      expect(src).not.toContain("edge-router");
+      expect(src).not.toContain("lambdaFunctionAssociations");
+      expect(src).not.toContain("ab-routing.json");
+    });
+
+    it("ships no edge handler source", () => {
+      expect(existsSync(`${stackDir(provider)}/edge-handler.ts`)).toBe(false);
+    });
+  },
+);

package/src/azure-front-door.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * DNS records the Azure stack asks the operator's registrar to hold.
+ *
+ * The public site is served by Azure Front Door (CLAUDE.md §11.B Tier 1:
+ * object storage + edge CDN + managed TLS, no compute on the request path),
+ * so the primary domain points at the Front Door endpoint, and Front Door's
+ * managed certificate needs the `_dnsauth` TXT record to prove domain
+ * ownership before it issues.
+ */
+
+import type { DnsRecord } from "./adapter.js";
+
+/** Inputs the Azure stack resolves from its Front Door resources. */
+export interface AzureFrontDoorDnsInputs {
+  /** The site's primary domain (`caelo-azure:domain`). */
+  readonly domain: string;
+  /** `AFDEndpoint.hostName`, e.g. `caelo-prod-abc123.z01.azurefd.net`. */
+  readonly endpointHostName: string;
+  /** `AFDCustomDomain.validationProperties.validationToken`. */
+  readonly validationToken: string;
+}
+
+/**
+ * The records for the primary domain: a CNAME to the Front Door endpoint and
+ * the TXT record that validates the custom domain for its managed certificate.
+ *
+ * @throws when the endpoint hostname or validation token is empty — a record
+ * pointing at nothing would read fine in the DNS guidance page and then fail
+ * at the registrar (no fallbacks pre-1.0, CLAUDE.md §2).
+ */
+export function azureFrontDoorDnsRecords(input: AzureFrontDoorDnsInputs): DnsRecord[] {
+  if (input.endpointHostName.length === 0) {
+    throw new Error("azure-front-door: the Front Door endpoint has no hostName yet");
+  }
+  if (input.validationToken.length === 0) {
+    throw new Error(
+      `azure-front-door: the custom domain ${input.domain} has no validation token yet`,
+    );
+  }
+  return [
+    {
+      hostname: input.domain,
+      type: "CNAME",
+      value: input.endpointHostName,
+      purpose: "Primary domain → Azure Front Door endpoint (static site)",
+    },
+    {
+      hostname: `_dnsauth.${input.domain}`,
+      type: "TXT",
+      value: input.validationToken,
+      purpose: "Validates the primary domain for Front Door's managed TLS certificate",
+    },
+  ];
+}

package/src/bootstrap-token.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P14 — owner bootstrap token. cms-provision generates one at first
+ * `up`; the operator visits /setup?token=<…> to create the first
+ * Owner. Single-use, 24h TTL.
+ */
+
+export interface BootstrapToken {
+  readonly token: string;
+  readonly expiresAt: string;
+}
+
+export function generateBootstrapToken(): BootstrapToken {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const token = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+  const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString();
+  return { token, expiresAt };
+}