@caelo-cms/provisioning 0.10.61 → 0.10.64

package/src/agent/lock-config.test.ts

@@ -3,11 +3,24 @@
 /** The install's upgrade lock (agent/lock.ts) and the agent's settings (agent/config.ts). */
 
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { existsSync, mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AGENT_DB_PORT_DEFAULT, agentConfigFor, agentDbConnection } from "./config.js";
-import { acquireUpgradeLock, upgradeLockPath } from "./lock.js";
+import {
+  acquireUpgradeLock,
+  UpgradeLockAccessError,
+  UpgradeLockHeldError,
+  upgradeLockPath,
+} from "./lock.js";
 
 describe("acquireUpgradeLock", () => {
   let dir: string;
@@ -48,6 +61,48 @@ describe("acquireUpgradeLock", () => {
     acquireUpgradeLock(dir, "the update agent")();
     expect(readdirSync(dir)).toEqual([]);
   });
+
+  it("contention is an UpgradeLockHeldError (#804)", () => {
+    acquireUpgradeLock(dir, "the update agent", { pid: 101, alive: () => true });
+    expect(() => acquireUpgradeLock(dir, "x", { pid: 102, alive: () => true })).toThrow(
+      UpgradeLockHeldError,
+    );
+    writeFileSync(upgradeLockPath(dir), "{not json");
+    expect(() => acquireUpgradeLock(dir, "x")).toThrow(UpgradeLockHeldError);
+  });
+
+  // Root ignores permission bits, so the EACCES case only runs as a normal user.
+  it.skipIf(process.getuid?.() === 0)(
+    "a directory it cannot write is an access error naming the lock file, not busy (#804)",
+    () => {
+      chmodSync(dir, 0o500);
+      try {
+        let thrown: unknown;
+        try {
+          acquireUpgradeLock(dir, "the update agent");
+        } catch (e) {
+          thrown = e;
+        }
+        expect(thrown).toBeInstanceOf(UpgradeLockAccessError);
+        expect((thrown as Error).message).toContain(upgradeLockPath(dir));
+        expect((thrown as Error).message).toContain("write access");
+        expect((thrown as Error).message).not.toMatch(/running on this install|try again when/i);
+      } finally {
+        chmodSync(dir, 0o700);
+      }
+    },
+  );
+
+  it("a missing install directory is an access error, not busy (#804)", () => {
+    let thrown: unknown;
+    try {
+      acquireUpgradeLock(join(dir, "gone"), "the update agent");
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(UpgradeLockAccessError);
+    expect((thrown as Error).message).toContain("does not exist");
+  });
 });
 
 describe("agentConfigFor", () => {

package/src/agent/lock.ts

@@ -13,6 +13,13 @@
  * into place, so the lock file never exists half-written: a reader that
  * finds it can always trust its pid. (An unreadable file is only taken over
  * once it is older than any run could be.)
+ *
+ * Only real contention throws {@link UpgradeLockHeldError} (#804): a live
+ * holder, a young unreadable record, a creation race. Anything else — the
+ * directory is not writable, the disk is full — throws
+ * {@link UpgradeLockAccessError} naming the lock file and the fix, so
+ * callers can tell "busy, try later" from "broken, fix the server" (the GCP
+ * upgrader's StateLockHeldError, #799).
  */
 
 import { linkSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -23,6 +30,36 @@ export function upgradeLockPath(caeloDir: string): string {
   return join(caeloDir, "upgrade.lock");
 }
 
+/** Another upgrade holds the lock: the one failure that waiting fixes. */
+export class UpgradeLockHeldError extends Error {
+  override readonly name = "UpgradeLockHeldError";
+}
+
+/**
+ * The lock could not be taken for a reason waiting does not fix (no write
+ * access, a full disk); the message names the lock file and the fix.
+ */
+export class UpgradeLockAccessError extends Error {
+  override readonly name = "UpgradeLockAccessError";
+}
+
+/** {@link UpgradeLockAccessError}'s message for filesystem error `e`. */
+function lockAccessFailure(caeloDir: string, e: unknown): string {
+  const path = upgradeLockPath(caeloDir);
+  const code = (e as NodeJS.ErrnoException | null)?.code;
+  const said = e instanceof Error ? e.message : String(e);
+  if (code === "EACCES" || code === "EPERM" || code === "EROFS") {
+    return `the upgrade lock ${path} cannot be written (${said}). Give the account the update runs as write access to ${caeloDir} (the agent runs as root through its systemd unit), then try again.`;
+  }
+  if (code === "ENOSPC" || code === "EDQUOT") {
+    return `the upgrade lock ${path} cannot be written because the disk is full (${said}). Free space on the server, then try again.`;
+  }
+  if (code === "ENOENT") {
+    return `the upgrade lock ${path} cannot be created: ${caeloDir} does not exist (${said}). Run the command from the install's directory, or re-run the installer to restore it.`;
+  }
+  return `the upgrade lock ${path} could not be taken (${said}). Check that ${caeloDir} is writable and the disk has space, then try again.`;
+}
+
 interface LockRecord {
   readonly pid: number;
   readonly holder: string;
@@ -56,12 +93,27 @@ function processAlive(pid: number): boolean {
  * Take the install's upgrade lock for `holder`.
  *
  * @returns the release function (idempotent)
- * @throws when a live process holds it, naming that holder
+ * @throws UpgradeLockHeldError when another upgrade holds it, naming that holder
+ * @throws UpgradeLockAccessError for anything else (permissions, disk space)
  */
 export function acquireUpgradeLock(
   caeloDir: string,
   holder: string,
   deps: { readonly pid?: number; readonly alive?: (pid: number) => boolean } = {},
+): () => void {
+  try {
+    return takeUpgradeLock(caeloDir, holder, deps);
+  } catch (e) {
+    if (e instanceof UpgradeLockHeldError) throw e;
+    throw new UpgradeLockAccessError(lockAccessFailure(caeloDir, e), { cause: e });
+  }
+}
+
+/** {@link acquireUpgradeLock} without the classification of its errors. */
+function takeUpgradeLock(
+  caeloDir: string,
+  holder: string,
+  deps: { readonly pid?: number; readonly alive?: (pid: number) => boolean } = {},
 ): () => void {
   const path = upgradeLockPath(caeloDir);
   const alive = deps.alive ?? processAlive;
@@ -86,18 +138,29 @@ export function acquireUpgradeLock(
       } catch (e) {
         if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
       }
+      let text: string;
+      try {
+        text = readFileSync(path, "utf8");
+      } catch (e) {
+        // Released between the link and the read: try again. A file this
+        // account may not read is an access problem, not a busy lock.
+        if ((e as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw e;
+      }
       let held: Partial<LockRecord> | null = null;
       try {
-        held = JSON.parse(readFileSync(path, "utf8")) as Partial<LockRecord>;
+        held = JSON.parse(text) as Partial<LockRecord>;
       } catch {
         // Corrupt (never half-written, see above): take it over only when old.
       }
       if (held === null) {
         if (Date.now() - lockMtime(path) < UNREADABLE_LOCK_MAX_AGE_MS) {
-          throw new Error(`another upgrade holds ${path} (its record is unreadable).`);
+          throw new UpgradeLockHeldError(
+            `another upgrade holds ${path} (its record is unreadable).`,
+          );
         }
       } else if (typeof held.pid === "number" && alive(held.pid)) {
-        throw new Error(
+        throw new UpgradeLockHeldError(
           `${held.holder ?? "another upgrade"} is running on this install (pid ${held.pid}, since ${held.at ?? "?"}).`,
         );
       }
@@ -106,5 +169,5 @@ export function acquireUpgradeLock(
   } finally {
     rmSync(temp, { force: true });
   }
-  throw new Error(`could not take ${path}; another process keeps creating it.`);
+  throw new UpgradeLockHeldError(`could not take ${path}; another process keeps creating it.`);
 }

package/src/agent/run.test.ts

@@ -12,6 +12,7 @@ import type { StoredUpdatePolicy } from "@caelo-cms/shared";
 import type { ReleaseManifest, ReleaseManifestResult } from "../release-manifest.js";
 import type { SelfHostedRelease } from "../self-hosted-release.js";
 import type { ClaimedUpdate, UpdateEnd, UpdateFacts } from "../upgrader-job.js";
+import { UpgradeLockAccessError, UpgradeLockHeldError } from "./lock.js";
 import type { AgentHeartbeat, AgentQueue } from "./queue.js";
 import { type AgentApplyRequest, type AgentRunDeps, runAgentOnce } from "./run.js";
 
@@ -216,10 +217,26 @@ describe("runAgentOnce", () => {
       name: "another upgrade holds the lock",
       over: {
         lock: () => {
-          throw new Error("`cms-provision upgrade` is running on this install (pid 42).");
+          throw new UpgradeLockHeldError(
+            "`cms-provision upgrade` is running on this install (pid 42).",
+          );
         },
       },
       expect: "failed/state-locked",
+      reason: /Try again when it has finished/,
+    },
+    {
+      name: "a lock the agent cannot write is not reported as busy (#804)",
+      over: {
+        lock: () => {
+          throw new UpgradeLockAccessError(
+            "the upgrade lock /opt/caelo/.caelo/upgrade.lock cannot be written (EACCES). Give the account write access, then try again.",
+          );
+        },
+      },
+      expect: "failed/lock-access",
+      reason:
+        /^Nothing was changed: the upgrade lock \/opt\/caelo\/.caelo\/upgrade.lock cannot be written \(EACCES\)\. Give the account write access, then try again\.$/,
     },
     {
       name: "a malformed release.json",

package/src/agent/run.ts

@@ -39,6 +39,7 @@ import type { UpdateEnd, UpdateEndStatus } from "../upgrader-job.js";
 import { recordUpdateEnd } from "../upgrader-job.js";
 import { eventReporter, type JobLog } from "../upgrader-reporter.js";
 import type { VerifiedCli } from "./cli-provenance.js";
+import { UpgradeLockHeldError } from "./lock.js";
 import type { AgentQueue } from "./queue.js";
 
 /** What the target release's `agent apply` is told (argv of the child). */
@@ -70,7 +71,11 @@ export interface AgentRunDeps {
   readonly readInstalled: () => SelfHostedRelease | null;
   /** fetchVerifiedReleaseManifest against the fixed registry. */
   readonly fetchManifest: (version: string) => Promise<ReleaseManifestResult>;
-  /** Take the install's upgrade lock (agent/lock.ts); throws when held. */
+  /**
+   * Take the install's upgrade lock (agent/lock.ts): throws
+   * UpgradeLockHeldError when another upgrade holds it, any other error
+   * when the lock cannot be written.
+   */
   readonly lock: () => () => void;
   /**
    * Install the target release's CLI and verify its npm signatures +
@@ -169,11 +174,17 @@ export async function runAgentOnce(deps: AgentRunDeps): Promise<AgentRunResult>
     try {
       release = deps.lock();
     } catch (e) {
-      return await stopWith(
-        "failed",
-        ["state-locked"],
-        `Nothing was changed: ${errorText(e)} Try again when it has finished.`,
-      );
+      // #804 — only another upgrade holding the lock is "busy"; a lock the
+      // agent cannot write (permissions, a full disk) is a server problem
+      // that waiting never fixes.
+      if (e instanceof UpgradeLockHeldError) {
+        return await stopWith(
+          "failed",
+          ["state-locked"],
+          `Nothing was changed: ${errorText(e)} Try again when it has finished.`,
+        );
+      }
+      return await stopWith("failed", ["lock-access"], `Nothing was changed: ${errorText(e)}`);
     }
 
     r.phase("verify");

package/src/caddy-redirects.test.ts

@@ -63,6 +63,7 @@ describe("Compose — Caddy picks up new redirects (#587)", () => {
     postgresPassword: "pgpw",
     rolePasswords: { admin: "a", public: "p" },
     caeloSecretKek: "0".repeat(64),
+    internalSecret: "i".repeat(48),
     diskSize: "20Gi",
     ports: { http: 80, https: 443 },
     project: "caelo-example-com",

package/src/caddy.ts

@@ -49,12 +49,21 @@
  * icon MIME the media library stores and `<link rel="icon" type>`
  * declares. file_server only fills Content-Type when no earlier handler
  * set it, so the `header` line wins over the host's mime.types name.
+ *
+ * #891 — every response of a public vhost is `nosniff`, and every SVG
+ * gets the sandboxing CSP (`SVG_DOCUMENT_CSP`, @caelo-cms/shared): an
+ * uploaded SVG opened directly must not run script on the site's origin,
+ * which also serves `/api/*`. Caddy's `path` matcher is case-insensitive,
+ * so `*.svg` covers `.SVG` too. `cms-provision upgrade` re-writes this file
+ * (self-hosted-upgrade.ts), so existing installs get the headers too.
  */
 
 import {
   CONTENT_HASHED_PATH_PATTERN,
   caddyRedirectsImport,
   IMMUTABLE_CACHE_CONTROL,
+  NOSNIFF,
+  SVG_DOCUMENT_CSP,
 } from "@caelo-cms/shared";
 
 export interface CaddyDomainSpec {
@@ -208,6 +217,9 @@ function vhost(d: CaddyDomainSpec, spec: CaddyfileSpec): string {
   header @content_hashed Cache-Control "${IMMUTABLE_CACHE_CONTROL}"
   @ico path *.ico
   header @ico Content-Type "image/x-icon"
+  header X-Content-Type-Options "${NOSNIFF}"
+  @svg path *.svg
+  header @svg Content-Security-Policy "${SVG_DOCUMENT_CSP}"
   handle /api/* {
     reverse_proxy ${spec.gatewayUpstream}
   }

package/src/cli-routing.ts

@@ -93,7 +93,7 @@ export const CLI_COMMANDS: readonly CliCommandDoc[] = [
   },
   {
     name: "upgrade",
-    args: "[--version x.y.z] [--channel stable|rc|beta] [--region <r>] [--skip-verify] [--skip-health-check] [--install <id|domain|all>]",
+    args: "[--version x.y.z] [--channel stable|rc|beta] [--region <r>] [--skip-verify] [--skip-health-check] [--install <id|domain|all>] [--project <gcp-project-id>]",
     summary:
       "Roll the install to a newer release (latest stable by default) after verifying the image signatures.",
   },

package/src/cli.ts

@@ -45,6 +45,7 @@ import {
   normalizeStagingHost,
   stagingHostProblem,
 } from "@caelo-cms/shared";
+import type { AdminInternalTarget } from "./admin-internal.js";
 import type { AgentCliContext } from "./agent/command.js";
 import type { AgentConfig } from "./agent/config.js";
 import { generateBootstrapToken } from "./bootstrap-token.js";
@@ -74,6 +75,7 @@ import {
 } from "./compose.js";
 import { tightenPrivateTree, writePrivateFile } from "./private-file.js";
 import { selfCommand } from "./self-command.js";
+import { ensureInternalSecret, writeInternalSecret } from "./self-hosted-internal-secret.js";
 import {
   bunHostRunner,
   readRelease,
@@ -277,15 +279,23 @@ function emitConfig(cfg: CaeloConfig, extraDomains: CaddyDomainSpec[] = []): voi
     cfg.caeloSecretKek = randomSecret(32);
     saveConfig(cfg);
   }
+  emitComposeFiles(cfg);
+  writeCaddyfile(cfg, extraDomains);
+}
+
+/**
+ * Write the Caddyfile for `cfg` — the seed hosts (admin, primary domain,
+ * staging host) plus `extraDomains`, the domains added via
+ * /settings/domains that regenerate-caddy / upgrade read from the live
+ * domains table. Never touches the Compose file: `upgrade` calls this after
+ * it rolled the containers onto the new Compose file (#891).
+ */
+function writeCaddyfile(cfg: CaeloConfig, extraDomains: CaddyDomainSpec[]): void {
   if (!cfg.stagingDomain) {
     cfg.stagingDomain = defaultStagingHost(cfg.domain);
     saveConfig(cfg);
   }
   if (!cfg.tls) throw new Error("config has no tls — it is back-filled on load; this is a bug");
-  emitComposeFiles(cfg);
-  // Seed the install with the admin host, the primary domain and the
-  // staging host. Extra domains added via /settings/domains are appended by
-  // regenerate-caddy when it queries the live domains table.
   const caddy = generateCaddyfile({
     ownerEmail: cfg.ownerEmail,
     tls: cfg.tls,
@@ -339,6 +349,12 @@ function renderCompose(cfg: CaeloConfig, images: ComposeImages): string {
     postgresPassword: cfg.postgresPassword,
     rolePasswords: cfg.rolePasswords,
     caeloSecretKek: cfg.caeloSecretKek,
+    // #770 — every render (up, upgrade, agent apply) hands the admin the
+    // secret host-side commands sign their /api/internal/* tokens with.
+    internalSecret: ensureInternalSecret(CAELO_DIR, {
+      randomSecret: () => randomSecret(48),
+      report: (line) => console.log(line),
+    }),
     anthropicApiKey: cfg.anthropicApiKey,
     resendApiKey: cfg.resendApiKey,
     diskSize: "20Gi",
@@ -382,6 +398,7 @@ function agentContext(cfg: CaeloConfig): AgentCliContext {
       });
     },
     renderCompose: (images) => renderCompose(cfg, images),
+    refreshCaddy: () => refreshCaddyfile(cfg),
     randomSecret: () => randomSecret(32),
   };
 }
@@ -478,6 +495,24 @@ async function refreshCaddy(
   return reloadCaddy(CAELO_DIR, bunHostRunner);
 }
 
+/**
+ * Re-render only the Caddyfile (config + the domains table) and reload the
+ * running Caddy — what `upgrade` runs after the roll, so an install picks up
+ * the edge headers of the release it moved to (#891) without its Compose
+ * file being re-written behind the upgrade's back.
+ */
+async function refreshCaddyfile(
+  cfg: CaeloConfig,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    writeCaddyfile(cfg, await fetchExtraDomains());
+  } catch (e) {
+    return { ok: false, error: `writing ${CADDYFILE_PATH} failed: ${(e as Error).message}` };
+  }
+  const { reloadCaddy } = await import("./self-hosted-start.js");
+  return reloadCaddy(CAELO_DIR, bunHostRunner);
+}
+
 /**
  * Pull, start Postgres, migrate, start everything, health-check
  * (self-hosted-start.ts). Exits non-zero with the reason on failure; the
@@ -602,6 +637,13 @@ async function init(): Promise<void> {
     composeProject: composeProjectName(domain),
   };
   saveConfig(cfg);
+  // P15.1 — the shared HMAC secret for /api/internal/* endpoints, read by
+  // the admin (CAELO_INTERNAL_SECRET, from the Compose file emitConfig
+  // writes next — so it must exist first, #770) and by host-side commands
+  // such as `owner-reset`. Long enough to defeat brute-force. GCP installs
+  // keep their own copy in Secret Manager (runtime-secrets.ts), rotated by
+  // `rotate-secret internal-secret`.
+  writeInternalSecret(CAELO_DIR, randomSecret(48));
   if (images.mode === "release") {
     recordRelease(
       CAELO_DIR,
@@ -620,17 +662,6 @@ async function init(): Promise<void> {
   mkdirSync(resolve(CAELO_DIR, BOOTSTRAP_DIR), { recursive: true, mode: 0o700 });
   writePrivateFile(PENDING_TOKEN_PATH, JSON.stringify(tok, null, 2));
 
-  // P15.1 — mint the shared HMAC secret for /api/internal/* endpoints.
-  // Same secret is read by:
-  //   - admin app (process.env.CAELO_INTERNAL_SECRET),
-  //   - cms-provision pulumi-output-sync (when running in CI / by hand),
-  //   - any future internal-only orchestration.
-  // Long enough to defeat brute-force. GCP installs keep their own copy in
-  // Secret Manager (runtime-secrets.ts), rotated by `rotate-secret
-  // internal-secret`.
-  const internalSecret = randomSecret(48);
-  const internalSecretPath = resolve(CAELO_DIR, "internal-secret.json");
-  writePrivateFile(internalSecretPath, JSON.stringify({ secret: internalSecret }, null, 2));
   // #696 Phase 4c — the update agent (Linux + systemd): the fresh volume's
   // bootstrap.sh creates its database login on Postgres's first start.
   const { reportAgentSetup, setUpAgent } = await import("./agent/command.js");
@@ -993,13 +1024,20 @@ async function upgradeSelfHostedCommand(opts: {
     process.exit(2);
   }
   const { upgradeSelfHosted } = await import("./self-hosted-upgrade.js");
-  const { acquireUpgradeLock } = await import("./agent/lock.js");
+  const { acquireUpgradeLock, UpgradeLockHeldError } = await import("./agent/lock.js");
   // The update agent rolls through the same lock: never two rolls at once.
   let unlock: () => void;
   try {
     unlock = acquireUpgradeLock(CAELO_DIR, "`cms-provision upgrade`");
   } catch (e) {
-    console.error(`Nothing was changed: ${(e as Error).message} Wait for it to finish.`);
+    // #804 — "wait" only when another upgrade holds the lock; an access
+    // failure's message already names the lock file and the fix.
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(
+      e instanceof UpgradeLockHeldError
+        ? `Nothing was changed: ${message} Wait for it to finish.`
+        : `Nothing was changed: ${message}`,
+    );
     process.exit(1);
   }
   let result: Awaited<ReturnType<typeof upgradeSelfHosted>>;
@@ -1009,6 +1047,7 @@ async function upgradeSelfHostedCommand(opts: {
       runner: bunHostRunner,
       renderCompose: (images) => renderCompose(cfg, images),
       convergeRoles: agentContext(cfg).convergeRoles,
+      refreshCaddy: () => refreshCaddyfile(cfg),
       log: {
         step: (m) => console.log(`\n==> ${m}`),
         info: (m) => console.log(`    ${m}`),
@@ -1201,8 +1240,12 @@ async function lifecycleUpgrade(): Promise<void> {
   // #607 — optional; must match the install's recorded region (upgrade
   // never moves an install between regions).
   const region = arg("region");
+  // #816 — attach the install from its project first (break-glass upgrade
+  // from a fresh Cloud Shell; nothing in $HOME has to survive).
+  const project = arg("project");
   const { upgradeCommand } = await import("./lifecycle.js");
   await upgradeCommand({
+    ...(project ? { project } : {}),
     ...(region ? { region } : {}),
     ...(version ? { version } : {}),
     ...(channel ? { channel } : {}),
@@ -1231,42 +1274,56 @@ async function lifecycleTruncate(): Promise<void> {
 }
 
 /**
- * #769 `owner-reset [--install <id>] [--email <addr>]` — print a one-time
- * reset link for a locked-out Owner, for installs whose admin cannot email
- * one (see owner-reset.ts for why the operator's cloud identity may).
+ * #769 / #770 `owner-reset [--install <id>] [--email <addr>]` — print a
+ * one-time reset link for a locked-out Owner, for installs whose admin
+ * cannot email one (see owner-reset.ts for why the operator may). Run in the
+ * self-hosted install's directory, or with `--install` for a cloud install.
  */
 async function ownerReset(): Promise<void> {
+  const email = arg("email");
+  const target = selfHostedInstallPresent()
+    ? selfHostedOwnerResetTarget()
+    : await cloudOwnerResetTarget();
+  const { describeOwnerReset, requestOwnerReset } = await import("./owner-reset.js");
+  const r = await requestOwnerReset(target, email ? { email } : {});
+  if (!r.ok) {
+    console.error(`owner-reset: ${r.error}`);
+    process.exit(1);
+  }
+  // Prints the reset link ON PURPOSE: stdout is the one place it goes; it is
+  // never written to a file or a log.
+  for (const line of describeOwnerReset(r.value)) console.log(line);
+}
+
+/** The self-hosted install in this directory, reached through `docker compose exec`. */
+function selfHostedOwnerResetTarget(): AdminInternalTarget {
+  const cfg = loadConfig();
+  if (!cfg) {
+    console.error("no config — run `cms-provision init` first");
+    process.exit(2);
+  }
+  return {
+    provider: "self-hosted",
+    caeloDir: CAELO_DIR,
+    adminUrl: siteUrl(cfg, selfHostedAdminHost(cfg.domain)),
+  };
+}
+
+/** The cloud install `--install` names (or the only one), on a provider that has the channel. */
+async function cloudOwnerResetTarget(): Promise<AdminInternalTarget> {
   const { installFlag, listInstalls, selectInstall } = await import("./install-state.js");
   const selected = selectInstall(listInstalls(), installFlag(process.argv));
   if (!selected.ok) {
     console.error(selected.message);
     process.exit(1);
   }
-  const meta = selected.meta;
-  if (meta.provider !== "gcp-firebase") {
-    console.error(
-      `owner-reset works on gcp-firebase installs so far; this one is ${meta.provider} (issue #770). ` +
-        "Until then, another Owner can set a new password under Settings -> Users, or set up email under Settings -> Email so /forgot can send the link.",
-    );
+  const { ownerResetTarget } = await import("./owner-reset.js");
+  const target = ownerResetTarget(selected.meta);
+  if (!target.ok) {
+    console.error(`owner-reset: ${target.error}`);
     process.exit(1);
   }
-  if (!meta.projectId || !meta.region) {
-    console.error(
-      `install ${meta.installId} has no project or region recorded in install.json; re-run the wizard to record it.`,
-    );
-    process.exit(1);
-  }
-  const email = arg("email");
-  const { describeOwnerReset, requestOwnerReset } = await import("./owner-reset.js");
-  const r = await requestOwnerReset(
-    { projectId: meta.projectId, region: meta.region },
-    email ? { email } : {},
-  );
-  if (!r.ok) {
-    console.error(`owner-reset: ${r.error}`);
-    process.exit(1);
-  }
-  for (const line of describeOwnerReset(r.value)) console.log(line);
+  return target.value;
 }
 
 /**
@@ -1340,6 +1397,7 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     if (!requested && meta.provider === "gcp-firebase" && meta.projectId && meta.region) {
       const { inspectStagingAdmin } = await import("./staging-admin.js");
       const inspected = await inspectStagingAdmin({
+        provider: "gcp-firebase",
         projectId: meta.projectId,
         region: meta.region,
       });
@@ -1425,7 +1483,7 @@ async function domainMappingCommand(kind: "admin" | "staging"): Promise<void> {
     // the password is printed once (never stored by the CLI).
     const { applyStagingAdmin, describeStagingApply } = await import("./staging-admin.js");
     const applied = await applyStagingAdmin(
-      { projectId: meta.projectId, region: meta.region },
+      { provider: "gcp-firebase", projectId: meta.projectId, region: meta.region },
       {
         host: r.hostname,
         ...(rotatePassword ? { rotateBasicAuth: true } : {}),

package/src/compose.ts

@@ -188,6 +188,13 @@ export interface ComposeSpec {
    * via the same randomHex(32) the GCP stack uses.
    */
   readonly caeloSecretKek: string;
+  /**
+   * #770 — the shared HMAC secret of the admin's `/api/internal/*`
+   * endpoints (`.caelo/internal-secret.json`), so host-side commands such as
+   * `owner-reset` can reach them through `docker compose exec`. Admin only;
+   * the gateway never gets it.
+   */
+  readonly internalSecret: string;
   readonly anthropicApiKey?: string;
   readonly resendApiKey?: string;
   readonly diskSize: string;
@@ -245,6 +252,10 @@ export function generateDockerCompose(spec: ComposeSpec): string {
   if (spec.agent && !isAgentDbPort(spec.agent.dbPort)) {
     throw new Error(`agent dbPort ${spec.agent.dbPort} is not a TCP port between 1024 and 65535`);
   }
+  // The admin refuses a shorter one on every /api/internal/* call (internal-jwt.ts).
+  if (spec.internalSecret.length < 32) {
+    throw new Error("internalSecret is shorter than 32 characters (.caelo/internal-secret.json)");
+  }
   return `# SPDX-License-Identifier: MPL-2.0
 # Generated by cms-provision — do not edit; re-run \`bunx cms-provision up\`.
 # Domain: ${spec.domain}
@@ -377,6 +388,7 @@ ${serviceRuntime(
       ADMIN_DATABASE_URL: "${dbUrl("admin_role", spec.rolePasswords.admin, "cms_admin")}"
       PUBLIC_ADMIN_DATABASE_URL: "${dbUrl("admin_role", spec.rolePasswords.admin, "cms_public")}"
       CAELO_SECRET_KEK: "${escapeYaml(spec.caeloSecretKek)}"
+      CAELO_INTERNAL_SECRET: "${escapeYaml(spec.internalSecret)}"
       CAELO_SITE_URL: "${escapeYaml(selfHostedSiteUrl(spec.domain, spec.ports.https))}"
       PORT: "${COMPOSE_ADMIN_PORT}"
       CAELO_OUTPUT_ROOT: "${SITE_OUTPUT_ROOT}"