@caelo-cms/provisioning 0.10.50 → 0.10.51

package/src/admin-internal.ts

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The CLI's channel to the admin's `/api/internal/*` endpoints on a
+ * gcp-firebase install, for commands that need an answer BACK from the admin
+ * (a generated password, a reset link). A one-shot Cloud Run job could only
+ * report through Cloud Logging, which would put that secret into the
+ * project's logs; this call answers over TLS straight to the CLI process, and
+ * nothing is written anywhere (CLAUDE.md §7, #659).
+ *
+ * Getting there, as the operator's own gcloud identity — the same path the
+ * Power-MCP shim takes (packages/mcp-server/src/ingress-auth.ts):
+ *
+ *   1. the admin Cloud Run service and its URL;
+ *   2. the install's internal secret from Secret Manager (in memory only),
+ *      which signs a 5-minute token for the endpoint's scope;
+ *   3. a JWT signed as `caelo-mcp@<project>` through the IAM Credentials
+ *      API — the admin's IAP lets that service account in, and every
+ *      IAP-allowlisted operator may sign as it (`cms-provision upgrade`
+ *      grants it) — so the request passes IAP first, then Caelo's token.
+ */
+
+import { findService } from "./admin-domain.js";
+import { gcloud as defaultGcloud, type GcloudResult } from "./gcloud.js";
+import { GCP_STACK_ENV, gcpSecretId, mcpIapServiceAccountEmail } from "./gcp-names.js";
+import { mintInternalToken } from "./internal-token.js";
+
+type Run = (args: string[]) => Promise<GcloudResult>;
+
+/** Signed JWTs live at most 1 hour; one call needs a few seconds. */
+const IAP_JWT_LIFETIME_S = 600;
+
+export interface AdminInternalTarget {
+  readonly projectId: string;
+  readonly region: string;
+}
+
+export interface AdminInternalDeps {
+  readonly run?: Run;
+  readonly fetch?: typeof fetch;
+  /** Seconds since epoch (IAP JWT); tests pin it. */
+  readonly now?: () => number;
+}
+
+/** One endpoint call: where, under which token scope, with what body. */
+export interface AdminInternalCall {
+  /** Path under the admin origin, e.g. `/api/internal/owner-reset`. */
+  readonly endpoint: string;
+  /** Scope the endpoint's `requireInternalAuth` checks. */
+  readonly scope: string;
+  readonly body: Record<string, unknown>;
+  /** The issue that added the endpoint, named when an older admin answers 404. */
+  readonly introducedBy: string;
+}
+
+export type AdminInternalResult<T> = { ok: true; value: T } | { ok: false; error: string };
+
+/**
+ * POST `call.body` to the endpoint and return the admin's JSON answer and
+ * the admin URL it was reached at (to build links the operator opens).
+ * Every failure names the fix: an IAP refusal or a pre-endpoint admin points
+ * at `cms-provision upgrade`, a refusal carries the admin's own message.
+ */
+export async function callAdminInternal<T>(
+  target: AdminInternalTarget,
+  call: AdminInternalCall,
+  deps: AdminInternalDeps = {},
+): Promise<AdminInternalResult<{ answer: T; adminUrl: string }>> {
+  const run = deps.run ?? defaultGcloud;
+  const doFetch = deps.fetch ?? fetch;
+  const scope = [`--region=${target.region}`, `--project=${target.projectId}`];
+
+  const found = await findService(run, scope, "admin");
+  if (!found.ok) return { ok: false, error: found.error };
+  const url = await run([
+    "run",
+    "services",
+    "describe",
+    found.service,
+    ...scope,
+    "--format=value(status.url)",
+  ]);
+  const adminUrl = url.stdout.trim();
+  if (!url.ok || !adminUrl) {
+    return { ok: false, error: `read the admin's URL: ${url.stderr.trim() || "empty"}` };
+  }
+
+  const secretId = gcpSecretId(GCP_STACK_ENV, "internal-secret");
+  const secret = await run([
+    "secrets",
+    "versions",
+    "access",
+    "latest",
+    `--secret=${secretId}`,
+    `--project=${target.projectId}`,
+  ]);
+  const internalSecret = secret.stdout.trim();
+  if (!secret.ok || internalSecret.length < 32) {
+    return {
+      ok: false,
+      error: `read the install's internal secret (${secretId}) from Secret Manager: ${secret.stderr.trim() || "missing or too short"}. Your gcloud account needs secretmanager.versions.access on the project.`,
+    };
+  }
+
+  // Installs from before #678 may not have the IAM Credentials API on;
+  // enabling an enabled API is a no-op (codex review on #681).
+  const api = await run([
+    "services",
+    "enable",
+    "iamcredentials.googleapis.com",
+    `--project=${target.projectId}`,
+  ]);
+  if (!api.ok) {
+    return {
+      ok: false,
+      error: `enable the IAM Credentials API (iamcredentials.googleapis.com), needed to pass the admin's IAP: ${api.stderr.trim()}`,
+    };
+  }
+  const iap = await signIapJwt(run, doFetch, target.projectId, adminUrl, deps.now);
+  if (!iap.ok) return iap;
+
+  const token = await mintInternalToken(internalSecret, call.scope);
+  let res: Response;
+  try {
+    res = await doFetch(`${adminUrl}${call.endpoint}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${iap.value}`,
+        "x-caelo-internal-token": token,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(call.body),
+    });
+  } catch (e) {
+    return { ok: false, error: `reach the admin at ${adminUrl}: ${String(e)}` };
+  }
+  const text = await res.text();
+  if (res.headers.get("x-goog-iap-generated-response") === "true") {
+    return {
+      ok: false,
+      error: `Google IAP refused the request (HTTP ${res.status}: ${text.trim().slice(0, 200)}) — ${mcpIapServiceAccountEmail(target.projectId)} is not allowed on the admin's IAP yet. Run \`cms-provision upgrade\` (it allowlists that service account), then run this command again.`,
+    };
+  }
+  if (res.status === 404) {
+    return {
+      ok: false,
+      error: `the admin has no ${call.endpoint} yet (it runs a release from before ${call.introducedBy}). Run \`cms-provision upgrade\`, then run this command again.`,
+    };
+  }
+  let parsed: { ok?: boolean; error?: string } & Record<string, unknown>;
+  try {
+    parsed = JSON.parse(text) as typeof parsed;
+  } catch {
+    return {
+      ok: false,
+      error: `the admin answered HTTP ${res.status} with a non-JSON body: ${text.slice(0, 200)}`,
+    };
+  }
+  if (!res.ok || parsed.ok !== true) {
+    return {
+      ok: false,
+      error: `the admin refused (HTTP ${res.status}): ${parsed.error ?? text.slice(0, 300)}`,
+    };
+  }
+  return { ok: true, value: { answer: parsed as unknown as T, adminUrl } };
+}
+
+/** A JWT signed as the install's MCP service account, for the admin's IAP. */
+async function signIapJwt(
+  run: Run,
+  doFetch: typeof fetch,
+  projectId: string,
+  adminUrl: string,
+  now: (() => number) | undefined,
+): Promise<AdminInternalResult<string>> {
+  const access = await run(["auth", "print-access-token"]);
+  const accessToken = access.stdout.trim();
+  if (!access.ok || !accessToken) {
+    return {
+      ok: false,
+      error: `get an access token from gcloud: ${access.stderr.trim() || "empty"}. Run \`gcloud auth login\` with the account you provisioned with.`,
+    };
+  }
+  const serviceAccount = mcpIapServiceAccountEmail(projectId);
+  const iat = now ? now() : Math.floor(Date.now() / 1000);
+  const res = await doFetch(
+    `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${encodeURIComponent(serviceAccount)}:signJwt`,
+    {
+      method: "POST",
+      headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
+      body: JSON.stringify({
+        payload: JSON.stringify({
+          iss: serviceAccount,
+          sub: serviceAccount,
+          aud: `${new URL(adminUrl).origin}/*`,
+          iat,
+          exp: iat + IAP_JWT_LIFETIME_S,
+        }),
+      }),
+    },
+  );
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => "")).slice(0, 300);
+    return {
+      ok: false,
+      error: `sign an IAP token as ${serviceAccount} (HTTP ${res.status}): ${detail} — your account needs roles/iam.serviceAccountTokenCreator on it; \`cms-provision upgrade\` grants it to everyone the admin's IAP lets in.`,
+    };
+  }
+  const { signedJwt } = (await res.json()) as { signedJwt?: string };
+  if (!signedJwt) return { ok: false, error: "IAM signJwt answered without a signedJwt" };
+  return { ok: true, value: signedJwt };
+}

package/src/aws-task-roles.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The AWS stack's per-service ECS task roles (#635 review): which Secrets
+ * Manager entries each service's task role may read. One role per service,
+ * so the API gateway's identity cannot read a secret that unlocks a
+ * cms_admin login (CLAUDE.md §2: the public side has no path to cms_admin),
+ * mirroring the GCP gateway SA's bindings (stack-contract.ts
+ * `SERVICE_SECRET_ENV`). Kept apart from the Pulumi program so the
+ * provisioning tests can assert it.
+ */
+
+/** The Secrets Manager entries the AWS stack creates (`caelo-<env>-<name>`). */
+export type AwsSecret =
+  | "postgres-password"
+  | "public-role-password"
+  | "gateway-role-password"
+  | "csrf-secret"
+  | "cookie-secret"
+  | "anthropic-api-key"
+  | "resend-api-key";
+
+/** A service with its own ECS task role. */
+export type AwsTaskService = "admin" | "gateway";
+
+/**
+ * The secrets each service's task role may read. The admin side (admin and
+ * its in-process workers) reads all of them; the gateway reads only
+ * public_role's password — its one database login.
+ */
+export const AWS_SERVICE_SECRETS: Readonly<Record<AwsTaskService, readonly AwsSecret[]>> = {
+  admin: [
+    "postgres-password",
+    "public-role-password",
+    "gateway-role-password",
+    "csrf-secret",
+    "cookie-secret",
+    "anthropic-api-key",
+    "resend-api-key",
+  ],
+  gateway: ["public-role-password"],
+};
+
+/**
+ * The IAM policy document letting a task role read exactly `secretArns`.
+ *
+ * @throws on an empty list: a policy with no resource is malformed, and a
+ *   service that needs no secret should get no secrets policy at all.
+ */
+export function secretsReadPolicy(secretArns: readonly string[]): string {
+  if (secretArns.length === 0) throw new Error("secretsReadPolicy: no secret ARNs");
+  return JSON.stringify({
+    Version: "2012-10-17",
+    Statement: [
+      { Effect: "Allow", Action: "secretsmanager:GetSecretValue", Resource: [...secretArns] },
+    ],
+  });
+}

package/src/checkpoint-secrets.test.ts

@@ -40,7 +40,6 @@ const setupLink = "https://admin.acme.test/setup?token=fakeSetupToken0123456789"
 const stackOutputs = {
   adminDatabaseUrlOut: { value: databaseUrls("10.1.2.3").admin, secret: false },
   publicDatabaseUrlOut: { value: databaseUrls("10.1.2.3").public, secret: false },
-  gatewayDatabaseUrlOut: { value: databaseUrls("10.1.2.3").gateway, secret: false },
   bootstrapUrlOut: { value: setupLink, secret: false },
   bootstrapTokenExpiresAtOut: { value: "2026-10-13T00:00:00.000Z", secret: false },
   providerOut: { value: "gcp", secret: false },

package/src/cli.ts

@@ -1120,6 +1120,7 @@ const handlers: Record<string, () => Promise<void>> = {
   truncate: lifecycleTruncate,
   "admin-domain": adminDomain,
   "staging-domain": stagingDomain,
+  "owner-reset": ownerReset,
   // #696 — Pulumi state in the install's own project.
   state: async () => (await import("./state-command.js")).stateCommand(process.argv),
   attach: async () => (await import("./state-command.js")).attachCommand(process.argv),
@@ -1196,6 +1197,45 @@ async function lifecycleTruncate(): Promise<void> {
   await truncateCommand();
 }
 
+/**
+ * #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).
+ */
+async function ownerReset(): Promise<void> {
+  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.",
+    );
+    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);
+}
+
 /**
  * `admin-domain enable` — bind admin.<domain> to a gcp-firebase admin
  * (see admin-domain.ts for why this runs as the operator, not Pulumi).
@@ -1495,7 +1535,7 @@ if (route.kind === "handler" || route.kind === "wizard") {
   }
 } else {
   console.log(
-    "Usage: cms-provision [wizard] [--provider <name> --domain <d> [--staging-domain <host>] --owner-email <e> --region <r>] [--local|--install-job] | <init|up|migrate|status|upgrade|backup|restore|rotate-secret|truncate|destroy|regenerate-caddy|admin-domain|staging-domain|state migrate|attach|pulumi-output-sync|version> [options]\n" +
+    "Usage: cms-provision [wizard] [--provider <name> --domain <d> [--staging-domain <host>] --owner-email <e> --region <r>] [--local|--install-job] | <init|up|migrate|status|upgrade|backup|restore|rotate-secret|truncate|destroy|regenerate-caddy|admin-domain|staging-domain|owner-reset|state migrate|attach|pulumi-output-sync|version> [options]\n" +
       "With several installs on this machine, pick one with --install <install-id or domain> (status, upgrade and backup also take --install all); in a terminal you are asked otherwise.\n" +
       "Pass --no-wizard with no sub-command to print this usage instead of the wizard.",
   );

package/src/compose.ts

@@ -388,8 +388,8 @@ ${serviceRuntime(spec.images, "gateway", "bun run apps/api-gateway/src/server.ts
     depends_on:
       postgres: { condition: service_healthy }
     environment:
-      # Its own two logins only — no authoring credential (#613, CLAUDE.md §2).
-      GATEWAY_DATABASE_URL: "${dbUrl("gateway_role", spec.rolePasswords.gateway, "cms_admin")}"
+      # public_role on cms_public is its only database login (#613, #635,
+      # CLAUDE.md §2: the public side has no path to the authoring database).
       PUBLIC_DATABASE_URL: "${dbUrl("public_role", spec.rolePasswords.public, "cms_public")}"
       GATEWAY_PORT: "${COMPOSE_GATEWAY_PORT}"
       NODE_ENV: production`;

package/src/deployed-release.test.ts

@@ -93,6 +93,21 @@ describe("checkDeployedRuntimeEnv", () => {
   });
 
   it("passes once both services read the password from Secret Manager", async () => {
+    const { run } = fakeGcloud({
+      ...lists(),
+      "describe caelo-production-admin-abc": [
+        svc([secret("ADMIN_DATABASE_PASSWORD"), secret("PUBLIC_ADMIN_DATABASE_PASSWORD")]),
+      ],
+      "describe caelo-production-gateway-def": [
+        svc([secret("PUBLIC_DATABASE_PASSWORD", "public-role-password")]),
+      ],
+    });
+    expect(await checkDeployedRuntimeEnv({ projectId: "p", region: "r", run })).toEqual({
+      ok: true,
+    });
+  });
+
+  it("stops a wizard re-run on a gateway from before #635 (it needs its gateway_role pool)", async () => {
     const { run } = fakeGcloud({
       ...lists(),
       "describe caelo-production-admin-abc": [
@@ -105,9 +120,12 @@ describe("checkDeployedRuntimeEnv", () => {
         ]),
       ],
     });
-    expect(await checkDeployedRuntimeEnv({ projectId: "p", region: "r", run })).toEqual({
-      ok: true,
-    });
+    const r = await checkDeployedRuntimeEnv({ projectId: "p", region: "r", run });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("GATEWAY_DATABASE_PASSWORD");
+      expect(r.error).toContain("Run `upgrade` first");
+    }
   });
 
   it("stops a wizard re-run on a gateway from before #613 (it needs the admin_role pool)", async () => {
@@ -123,7 +141,7 @@ describe("checkDeployedRuntimeEnv", () => {
     const r = await checkDeployedRuntimeEnv({ projectId: "p", region: "r", run });
     expect(r.ok).toBe(false);
     if (!r.ok) {
-      expect(r.error).toContain("GATEWAY_DATABASE_PASSWORD");
+      expect(r.error).toContain("ADMIN_DATABASE_PASSWORD");
       expect(r.error).toContain("Run `upgrade` first");
     }
   });

package/src/deployed-release.ts

@@ -15,7 +15,7 @@ import { gcloud as defaultGcloud } from "./gcloud.js";
 import type { GcloudRunner } from "./gcloud-retry.js";
 import { GCP_STACK_ENV, gcpNamePrefix } from "./gcp-names.js";
 import type { ImageDigests } from "./install-state.js";
-import { type CloudRunSlug, SERVICE_SECRET_ENV } from "./stack-contract.js";
+import { type CloudRunSlug, RETIRED_SERVICE_ENV, SERVICE_SECRET_ENV } from "./stack-contract.js";
 import { liveContainerEnv } from "./stack-converge.js";
 
 /** The `sha256:…` digest an image reference pins, or null for a tag reference. */
@@ -61,8 +61,9 @@ async function findDeployedService(
  * reads the password from the URL). The wizard keeps the release an install
  * runs, so re-running it on an install `upgrade` hasn't moved over yet would
  * pair the old release with env it can't connect with. The same holds for a
- * gateway from before #613: its release needs the admin_role pool the
- * current contract no longer gives it (no GATEWAY_DATABASE_PASSWORD yet).
+ * gateway from before #613 or #635: its release needs a cms_admin pool
+ * (admin_role, then gateway_role) the current contract no longer gives it —
+ * it still carries the retired database vars.
  * Such an install has to go through `upgrade` first, which moves the image
  * and the env in one revision.
  */
@@ -88,13 +89,19 @@ export async function checkDeployedRuntimeEnv(opts: {
       return { ok: false, error: `describe ${found.name}: ${describe.stderr.trim()}` };
     }
     const env = liveContainerEnv(describe.stdout);
-    const missing = Object.keys(SERVICE_SECRET_ENV[slug]).filter(
-      (name) => name.endsWith("_PASSWORD") && env.get(name)?.kind !== "secret",
-    );
+    const missing = [
+      ...Object.keys(SERVICE_SECRET_ENV[slug]).filter(
+        (name) => name.endsWith("_PASSWORD") && env.get(name)?.kind !== "secret",
+      ),
+      // A database var the contract retired (the gateway's ADMIN_* before
+      // #613, its GATEWAY_* before #635) means the running release still
+      // needs that login.
+      ...RETIRED_SERVICE_ENV[slug].filter((name) => /DATABASE/.test(name) && env.has(name)),
+    ];
     if (missing.length > 0) {
       return {
         ok: false,
-        error: `${found.name} does not read ${missing.join(", ")} from Secret Manager — its release predates the current database env (Secret Manager runtime secrets; for the gateway, its own database logins, #613). Run \`upgrade\` first: it moves the release and its env over together. Re-running the installer now would give the running release a database env it can't connect with.`,
+        error: `${found.name} does not match the current database env (${missing.join(", ")}) — its release predates it (Secret Manager runtime secrets; for the gateway, its own database login, #613/#635). Run \`upgrade\` first: it moves the release and its env over together. Re-running the installer now would give the running release a database env it can't connect with.`,
       };
     }
   }

package/src/gateway-credentials.ts

@@ -2,9 +2,12 @@
 
 /**
  * Moving an existing install's API gateway off admin_role (issue #613),
- * as `cms-provision upgrade` does it. The env side — GATEWAY_DATABASE_URL
- * and the per-role password secrets in, ADMIN_DATABASE_* out — rides the
- * gateway's roll (stack-contract.ts). The database side is ordered around
+ * as `cms-provision upgrade` does it. The env side — the per-role password
+ * secrets in, ADMIN_DATABASE_* out (and, since #635, GATEWAY_DATABASE_* out
+ * too: the gateway has no cms_admin login at all) — rides the gateway's
+ * roll (stack-contract.ts). gateway_role keeps getting its password until
+ * the contract release drops the role, because the previous release's
+ * gateway logs in with it until it is rolled. The database side is ordered around
  * that roll so /api/* keeps working:
  *
  *   1. after migrations (which create `gateway_role` without a password):