@caelo-cms/provisioning 0.10.53 → 0.10.57

package/src/remote-mcp.ts

@@ -0,0 +1,460 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #806 — the CLI's part of remote MCP on a Google IAP install (`gcp`,
+ * `gcp-firebase`), run as the operator's (or the provisioner's) gcloud
+ * identity by the wizard after `pulumi up` and by `cms-provision upgrade`
+ * after the roll. Every step is idempotent.
+ *
+ *   - {@link ensureRemoteMcpIdentityEnv}: the env vars that name generated
+ *     identities ({@link RemoteMcpIdentity} — why the stacks cannot declare
+ *     them is in stack-contract.ts), applied with `gcloud run services
+ *     update` only where they differ.
+ *   - {@link ensureRemoteMcpEdge} (`gcp` only): the load balancer's part for
+ *     installs whose URL map / Cloud Armor policy predate it — the
+ *     `/.well-known/oauth-*` path rules (the stack ignores `pathRules` after
+ *     creation, gcp-url-map.ts) and the `/api/mcp/*` Cloud Armor rule
+ *     (remote-mcp-edge.ts).
+ *
+ * The secrets, the IAM bindings, the gateway's secret volume and timeout
+ * come through the shared contract like everything else
+ * (runtime-secrets.ts, stack-contract.ts, upgrade/app-roll.ts).
+ *
+ * Nothing here enables remote MCP: that is the Owner's opt-in under
+ * Settings → MCP → Remote. Until then the gateway answers 503
+ * `remote_mcp_not_configured`.
+ */
+
+import { GCP_PUBLIC_BASE_PATHS } from "@caelo-cms/shared";
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { gcpNamePrefix } from "./gcp-names.js";
+import {
+  isMcpArmorRule,
+  type LiveArmorRule,
+  MCP_ARMOR_RULE,
+  mcpArmorRuleFlags,
+} from "./remote-mcp-edge.js";
+import type { HttpFetch } from "./runtime-secrets.js";
+import {
+  type CloudRunSlug,
+  type GcpProvider,
+  type RemoteMcpIdentity,
+  remoteMcpIdentity,
+  remoteMcpIdentityEnv,
+} from "./stack-contract.js";
+import { type EnvChange, liveContainerEnv, planEnvUpdate } from "./stack-converge.js";
+
+/** The install remote MCP is set up on. */
+export interface RemoteMcpTarget {
+  readonly provider: GcpProvider;
+  readonly projectId: string;
+  readonly region: string;
+  /** Pulumi stack name (`production`). */
+  readonly env: string;
+  readonly domain: string;
+  /** Deployed (Pulumi-suffixed) Cloud Run service names. */
+  readonly services: Readonly<Record<CloudRunSlug, string>>;
+}
+
+export type RemoteMcpResult<T> =
+  | ({ readonly ok: true } & T)
+  | { readonly ok: false; readonly error: string };
+
+/** Parse gcloud JSON output; null (never a throw) when it is not JSON. */
+function parseJson(stdout: string): unknown {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+function lines(stdout: string): string[] {
+  return stdout
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+// ===========================================================================
+// Identity env
+// ===========================================================================
+
+/**
+ * Read the live identities {@link remoteMcpIdentity} derives from: the
+ * project number, and the admin's backend service id (`gcp`) or both
+ * services' URLs (`gcp-firebase`). Fails naming what it could not read.
+ */
+export async function resolveRemoteMcpIdentity(
+  target: RemoteMcpTarget,
+  deps: { run?: GcloudRunner } = {},
+): Promise<RemoteMcpResult<{ readonly identity: RemoteMcpIdentity }>> {
+  const run = deps.run ?? defaultGcloud;
+  const project = `--project=${target.projectId}`;
+  const num = await run([
+    "projects",
+    "describe",
+    target.projectId,
+    "--format=value(projectNumber)",
+  ]);
+  const projectNumber = num.ok ? num.stdout.trim() : "";
+  if (!/^\d+$/.test(projectNumber)) {
+    return {
+      ok: false,
+      error: `read the project number of ${target.projectId}: ${num.stderr.trim() || "empty"}`,
+    };
+  }
+  if (target.provider === "gcp") {
+    const prefix = `${gcpNamePrefix(target.env)}-admin-backend`;
+    const list = await run([
+      "compute",
+      "backend-services",
+      "list",
+      "--global",
+      project,
+      `--filter=name~^${prefix} AND iap.enabled=true`,
+      "--format=value(id)",
+    ]);
+    if (!list.ok) return { ok: false, error: `list backend services: ${list.stderr.trim()}` };
+    const ids = lines(list.stdout);
+    if (ids.length !== 1 || !/^\d+$/.test(ids[0] ?? "")) {
+      return {
+        ok: false,
+        error: `expected exactly one IAP-enabled ${prefix}* backend service, found ${ids.length}`,
+      };
+    }
+    return {
+      ok: true,
+      identity: remoteMcpIdentity({
+        provider: "gcp",
+        domain: target.domain,
+        projectNumber,
+        adminBackendServiceId: ids[0] as string,
+      }),
+    };
+  }
+  const url = async (service: string) => {
+    const r = await run([
+      "run",
+      "services",
+      "describe",
+      service,
+      `--region=${target.region}`,
+      project,
+      "--format=value(status.url)",
+    ]);
+    const value = r.ok ? r.stdout.trim() : "";
+    return value.startsWith("https://") ? value : null;
+  };
+  const adminUrl = await url(target.services.admin);
+  const gatewayUrl = await url(target.services.gateway);
+  if (!adminUrl || !gatewayUrl) {
+    return {
+      ok: false,
+      error: `read the Cloud Run URL of the ${adminUrl ? "gateway" : "admin"} service (${adminUrl ? target.services.gateway : target.services.admin})`,
+    };
+  }
+  return {
+    ok: true,
+    identity: remoteMcpIdentity({
+      provider: "gcp-firebase",
+      projectNumber,
+      region: target.region,
+      adminServiceName: target.services.admin,
+      adminServiceUrl: adminUrl,
+      gatewayServiceUrl: gatewayUrl,
+    }),
+  };
+}
+
+/**
+ * Bring both services' {@link RemoteMcpIdentity} env vars to `identity`
+ * with one `gcloud run services update` per service that differs (a new
+ * revision only then). Vars already right are left alone.
+ */
+export async function applyRemoteMcpIdentityEnv(
+  target: RemoteMcpTarget,
+  identity: RemoteMcpIdentity,
+  deps: { run?: GcloudRunner } = {},
+): Promise<RemoteMcpResult<{ readonly changes: Record<CloudRunSlug, EnvChange[]> }>> {
+  const run = deps.run ?? defaultGcloud;
+  const desired = remoteMcpIdentityEnv(identity);
+  const changes: Record<CloudRunSlug, EnvChange[]> = { admin: [], gateway: [] };
+  for (const slug of ["admin", "gateway"] as const) {
+    const service = target.services[slug];
+    const describe = await run([
+      "run",
+      "services",
+      "describe",
+      service,
+      `--region=${target.region}`,
+      `--project=${target.projectId}`,
+      "--format=json",
+    ]);
+    if (!describe.ok) return { ok: false, error: `describe ${service}: ${describe.stderr.trim()}` };
+    if (parseJson(describe.stdout) === null) {
+      return { ok: false, error: `describe ${service}: output is not JSON` };
+    }
+    const plan = planEnvUpdate(liveContainerEnv(describe.stdout), desired[slug]);
+    if (!plan.ok) return { ok: false, error: `${slug}: ${plan.error}` };
+    if (plan.flags.length === 0) continue;
+    const update = await run([
+      "run",
+      "services",
+      "update",
+      service,
+      `--region=${target.region}`,
+      `--project=${target.projectId}`,
+      ...plan.flags,
+      "--quiet",
+    ]);
+    if (!update.ok) return { ok: false, error: `update ${service}: ${update.stderr.trim()}` };
+    changes[slug] = plan.changes;
+  }
+  return { ok: true, changes };
+}
+
+/** {@link resolveRemoteMcpIdentity} then {@link applyRemoteMcpIdentityEnv}. */
+export async function ensureRemoteMcpIdentityEnv(
+  target: RemoteMcpTarget,
+  deps: { run?: GcloudRunner } = {},
+): Promise<
+  RemoteMcpResult<{
+    readonly identity: RemoteMcpIdentity;
+    readonly changes: Record<CloudRunSlug, EnvChange[]>;
+  }>
+> {
+  const resolved = await resolveRemoteMcpIdentity(target, deps);
+  if (!resolved.ok) return resolved;
+  const applied = await applyRemoteMcpIdentityEnv(target, resolved.identity, deps);
+  if (!applied.ok) return applied;
+  return { ok: true, identity: resolved.identity, changes: applied.changes };
+}
+
+// ===========================================================================
+// Load balancer (gcp)
+// ===========================================================================
+
+/** A path rule / matcher / URL map as the Compute API returns them (the parts used here). */
+interface UrlMapPathRule {
+  readonly paths: string[];
+  readonly service?: string;
+  readonly urlRedirect?: unknown;
+}
+interface UrlMapPathMatcher {
+  readonly name: string;
+  readonly pathRules?: UrlMapPathRule[];
+}
+export interface LiveUrlMap {
+  readonly name: string;
+  readonly hostRules?: { readonly hosts: string[]; readonly pathMatcher: string }[];
+  readonly pathMatchers?: UrlMapPathMatcher[];
+  readonly [field: string]: unknown;
+}
+
+export type UrlMapPathsPlan =
+  | { readonly ok: true; readonly map: LiveUrlMap; readonly added: string[] }
+  | { readonly ok: false; readonly error: string };
+
+/**
+ * The URL map with every {@link GCP_PUBLIC_BASE_PATHS} entry routed like
+ * `/api/*` (to the gateway). Only the rule that carries `/api/*` changes;
+ * redirect rules the admin wrote stay as they are. `added` is empty when the
+ * map is already complete.
+ */
+export function planUrlMapPaths(maps: readonly LiveUrlMap[], siteHost: string): UrlMapPathsPlan {
+  const routing = maps.flatMap((m) =>
+    (m.hostRules ?? [])
+      .filter((h) => h.hosts.includes(siteHost))
+      .map((h) => ({ map: m, pathMatcher: h.pathMatcher })),
+  );
+  if (routing.length !== 1) {
+    return {
+      ok: false,
+      error: `expected exactly one URL map routing ${siteHost}, found ${routing.length}`,
+    };
+  }
+  const { map, pathMatcher } = routing[0] as (typeof routing)[number];
+  const matcher = (map.pathMatchers ?? []).find((m) => m.name === pathMatcher);
+  const gatewayRule = matcher?.pathRules?.find(
+    (r) => r.service !== undefined && r.urlRedirect === undefined && r.paths.includes("/api/*"),
+  );
+  if (!matcher || !gatewayRule) {
+    return {
+      ok: false,
+      error: `URL map ${map.name} has no /api/* rule to the gateway in path matcher ${pathMatcher}; re-run the installer to restore the load balancer`,
+    };
+  }
+  const added = GCP_PUBLIC_BASE_PATHS.filter((p) => !gatewayRule.paths.includes(p));
+  if (added.length === 0) return { ok: true, map, added };
+  const next: LiveUrlMap = {
+    ...map,
+    pathMatchers: (map.pathMatchers ?? []).map((m) =>
+      m !== matcher
+        ? m
+        : {
+            ...m,
+            pathRules: (m.pathRules ?? []).map((r) =>
+              r === gatewayRule ? { ...r, paths: [...r.paths, ...added] } : r,
+            ),
+          },
+    ),
+  };
+  return { ok: true, map: next, added };
+}
+
+const COMPUTE_API = "https://compute.googleapis.com/compute/v1";
+const OPERATION_POLLS = 60;
+
+/**
+ * Route the remote-MCP discovery paths to the gateway on an existing `gcp`
+ * install: read the URL map, add the missing paths to its `/api/*` rule and
+ * write it back through the Compute API (`urlMaps.update` carries the map's
+ * fingerprint, so a concurrent write — the admin publishing redirects —
+ * fails instead of being lost; a re-run then succeeds).
+ */
+export async function ensureUrlMapRemoteMcpPaths(
+  target: Pick<RemoteMcpTarget, "projectId" | "domain">,
+  deps: { run?: GcloudRunner; http?: HttpFetch; sleep?: (ms: number) => Promise<void> } = {},
+): Promise<RemoteMcpResult<{ readonly added: string[] }>> {
+  const run = deps.run ?? defaultGcloud;
+  const http = deps.http ?? (fetch as unknown as HttpFetch);
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const list = await run([
+    "compute",
+    "url-maps",
+    "list",
+    "--global",
+    `--project=${target.projectId}`,
+    "--format=json",
+  ]);
+  if (!list.ok) return { ok: false, error: `list URL maps: ${list.stderr.trim()}` };
+  const maps = parseJson(list.stdout || "[]");
+  if (!Array.isArray(maps)) return { ok: false, error: "list URL maps: output is not a JSON list" };
+  const plan = planUrlMapPaths(maps as LiveUrlMap[], target.domain);
+  if (!plan.ok) return plan;
+  if (plan.added.length === 0) return { ok: true, added: [] };
+  const token = await run(["auth", "print-access-token"]);
+  const bearer = token.ok ? token.stdout.trim() : "";
+  if (!bearer)
+    return { ok: false, error: `gcloud auth print-access-token: ${token.stderr.trim()}` };
+  const headers = { Authorization: `Bearer ${bearer}`, "Content-Type": "application/json" };
+  const base = `${COMPUTE_API}/projects/${encodeURIComponent(target.projectId)}/global`;
+  const put = await http(`${base}/urlMaps/${encodeURIComponent(plan.map.name)}`, {
+    method: "PUT",
+    headers,
+    body: JSON.stringify(plan.map),
+  });
+  if (!put.ok) {
+    return {
+      ok: false,
+      error: `update URL map ${plan.map.name}: HTTP ${put.status} ${(await put.text()).slice(0, 500)}`,
+    };
+  }
+  type Operation = { name?: string; status?: string; error?: { errors?: { message?: string }[] } };
+  let op = (parseJson(await put.text()) ?? {}) as Operation;
+  for (let i = 0; op.status !== "DONE" && i < OPERATION_POLLS; i++) {
+    await sleep(2_000);
+    const poll = await http(`${base}/operations/${encodeURIComponent(op.name ?? "")}`, {
+      method: "GET",
+      headers,
+    });
+    if (!poll.ok) return { ok: false, error: `poll ${op.name}: HTTP ${poll.status}` };
+    op = (parseJson(await poll.text()) ?? {}) as Operation;
+  }
+  if (op.status !== "DONE") return { ok: false, error: `URL-map update ${op.name} did not finish` };
+  const errors = op.error?.errors ?? [];
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      error: `URL-map update failed: ${errors.map((e) => e.message).join("; ")}`,
+    };
+  }
+  return { ok: true, added: plan.added };
+}
+
+/**
+ * Give the gateway's Cloud Armor policy the `/api/mcp/*` rule
+ * ({@link MCP_ARMOR_RULE}): create it, or bring a rule at its priority back
+ * to spec.
+ */
+export async function ensureMcpArmorRule(
+  target: Pick<RemoteMcpTarget, "projectId" | "env">,
+  deps: { run?: GcloudRunner } = {},
+): Promise<
+  RemoteMcpResult<{ readonly policy: string; readonly action: "present" | "created" | "updated" }>
+> {
+  const run = deps.run ?? defaultGcloud;
+  const project = `--project=${target.projectId}`;
+  const prefix = `${gcpNamePrefix(target.env)}-waf`;
+  const list = await run([
+    "compute",
+    "security-policies",
+    "list",
+    project,
+    `--filter=name~^${prefix}`,
+    "--format=value(name)",
+  ]);
+  if (!list.ok) return { ok: false, error: `list security policies: ${list.stderr.trim()}` };
+  const names = lines(list.stdout);
+  if (names.length !== 1) {
+    return {
+      ok: false,
+      error: `expected exactly one ${prefix}* Cloud Armor policy, found ${names.length}`,
+    };
+  }
+  const policy = names[0] as string;
+  const describe = await run([
+    "compute",
+    "security-policies",
+    "describe",
+    policy,
+    project,
+    "--format=json",
+  ]);
+  if (!describe.ok) return { ok: false, error: `describe ${policy}: ${describe.stderr.trim()}` };
+  const described = parseJson(describe.stdout) as { rules?: LiveArmorRule[] } | null;
+  if (!described) return { ok: false, error: `describe ${policy}: output is not JSON` };
+  const rules = described.rules ?? [];
+  const existing = rules.find((r) => r.priority === MCP_ARMOR_RULE.priority);
+  if (existing && isMcpArmorRule(existing)) return { ok: true, policy, action: "present" };
+  const verb = existing ? "update" : "create";
+  const r = await run([
+    "compute",
+    "security-policies",
+    "rules",
+    verb,
+    String(MCP_ARMOR_RULE.priority),
+    `--security-policy=${policy}`,
+    project,
+    ...mcpArmorRuleFlags(),
+    "--quiet",
+  ]);
+  if (!r.ok)
+    return {
+      ok: false,
+      error: `${verb} rule ${MCP_ARMOR_RULE.priority} on ${policy}: ${r.stderr.trim()}`,
+    };
+  return { ok: true, policy, action: existing ? "updated" : "created" };
+}
+
+/** Both load-balancer parts on `gcp`; a no-op success on `gcp-firebase`. */
+export async function ensureRemoteMcpEdge(
+  target: Pick<RemoteMcpTarget, "provider" | "projectId" | "env" | "domain">,
+  deps: { run?: GcloudRunner; http?: HttpFetch; sleep?: (ms: number) => Promise<void> } = {},
+): Promise<RemoteMcpResult<{ readonly done: string[] }>> {
+  if (target.provider !== "gcp") return { ok: true, done: [] };
+  const done: string[] = [];
+  const armor = await ensureMcpArmorRule(target, deps);
+  if (!armor.ok) return { ok: false, error: `Cloud Armor: ${armor.error}` };
+  done.push(`Cloud Armor rule ${MCP_ARMOR_RULE.priority} on ${armor.policy}: ${armor.action}`);
+  const paths = await ensureUrlMapRemoteMcpPaths(target, deps);
+  if (!paths.ok) return { ok: false, error: `URL map: ${paths.error}` };
+  done.push(
+    paths.added.length > 0
+      ? `URL map: routed ${paths.added.join(", ")} to the gateway`
+      : "URL map: discovery paths already routed to the gateway",
+  );
+  return { ok: true, done };
+}

package/src/runtime-secrets.test.ts

@@ -115,7 +115,7 @@ describe("ensureGeneratedSecrets", () => {
       { ...secretsInstall, replication: regional },
       { run },
     );
-    expect(outcomes.map((o) => o.status)).toEqual(["present", "present", "present", "present"]);
+    expect(outcomes.map((o) => o.status)).toEqual(Array(6).fill("present"));
     expect(lines().some((l) => l.includes(" create ") || l.includes(" add "))).toBe(false);
   });
 
@@ -126,8 +126,11 @@ describe("ensureGeneratedSecrets", () => {
       { ...secretsInstall, replication: regional },
       { run, generate: () => `generated-value-${++n}` },
     );
-    expect(outcomes.map((o) => o.status)).toEqual(["applied", "applied", "applied", "applied"]);
+    expect(outcomes.map((o) => o.status)).toEqual(Array(6).fill("applied"));
     const creates = calls.filter((c) => c.line.startsWith("secrets create"));
+    // #806 — the seal key is 32 random bytes in base64 (not the injected hex generator).
+    const sealKey = creates.find((c) => c.line.includes("mcp-oauth-seal-key"))?.stdin ?? "";
+    expect(Buffer.from(sealKey, "base64")).toHaveLength(32);
     expect(creates).toEqual([
       {
         line: "secrets create caelo-production-internal-secret --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
@@ -147,6 +150,16 @@ describe("ensureGeneratedSecrets", () => {
         line: "secrets create caelo-production-staging-gate-secret --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
         stdin: "generated-value-4",
       },
+      // #806 — remote MCP's OAuth client starts as the "not configured"
+      // placeholder; the Owner writes the real one from Settings → MCP.
+      {
+        line: "secrets create caelo-production-mcp-oauth-client --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
+        stdin: "{}",
+      },
+      {
+        line: "secrets create caelo-production-mcp-oauth-seal-key --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
+        stdin: sealKey,
+      },
     ]);
     for (const c of calls) expect(c.line).not.toContain("generated-value");
   });
@@ -165,11 +178,12 @@ describe("ensureGeneratedSecrets", () => {
       { run, generate: () => "generated" },
     );
     const creates = calls.filter((c) => c.line.startsWith("secrets create"));
-    expect(creates.map((c) => c.stdin)).toEqual([
+    expect(creates.map((c) => c.stdin).slice(0, 5)).toEqual([
       "operator-set",
       "generated",
       "generated",
       "generated",
+      "{}",
     ]);
     for (const c of calls) expect(c.line).not.toContain("operator-set");
   });
@@ -181,12 +195,21 @@ describe("ensureGeneratedSecrets", () => {
       "secrets versions list caelo-production-tool-approval-secret": [ok("v/1")],
       "secrets versions list caelo-production-public-role-password": [ok("v/1")],
       "secrets versions list caelo-production-staging-gate-secret": [ok("v/1")],
+      "secrets versions list caelo-production-mcp-oauth-client": [ok("v/1")],
+      "secrets versions list caelo-production-mcp-oauth-seal-key": [ok("v/1")],
     });
     const outcomes = await ensureGeneratedSecrets(
       { ...secretsInstall, replication: { kind: "automatic" } },
       { run, generate: () => "v" },
     );
-    expect(outcomes.map((o) => o.status)).toEqual(["applied", "present", "present", "present"]);
+    expect(outcomes.map((o) => o.status)).toEqual([
+      "applied",
+      "present",
+      "present",
+      "present",
+      "present",
+      "present",
+    ]);
     expect(calls.filter((c) => c.line.startsWith("secrets versions add"))).toEqual([
       {
         line: "secrets versions add caelo-production-internal-secret --project=acme --data-file=-",
@@ -220,7 +243,7 @@ describe("ensureGeneratedSecrets", () => {
       { ...secretsInstall, replication: { kind: "automatic" } },
       { run, generate: () => "v" },
     );
-    expect(outcomes.map((o) => o.status)).toEqual(["applied", "applied", "applied", "applied"]);
+    expect(outcomes.map((o) => o.status)).toEqual(Array(6).fill("applied"));
     expect(outcomes.every((o) => o.detail?.includes("gcp.resourceLocations"))).toBe(true);
     const creates = lines().filter((l) => l.startsWith("secrets create"));
     // One refused automatic attempt; then every secret — the refused one
@@ -232,6 +255,8 @@ describe("ensureGeneratedSecrets", () => {
       "secrets create caelo-production-public-role-password --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
       // #652 — the staging gate's key follows the same path.
       "secrets create caelo-production-staging-gate-secret --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
+      "secrets create caelo-production-mcp-oauth-client --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
+      "secrets create caelo-production-mcp-oauth-seal-key --project=acme --replication-policy=user-managed --locations=europe-west1 --data-file=- --quiet",
     ]);
   });
 
@@ -259,7 +284,7 @@ describe("ensureGeneratedSecrets", () => {
       { run, generate: () => "v" },
     );
     expect(outcomes.every((o) => o.status === "failed")).toBe(true);
-    expect(lines().filter((l) => l.startsWith("secrets create"))).toHaveLength(4);
+    expect(lines().filter((l) => l.startsWith("secrets create"))).toHaveLength(6);
   });
 });
 

package/src/runtime-secrets.ts

@@ -29,6 +29,7 @@ import {
   type CloudRunSlug,
   DATABASE_ROLE_SECRET,
   type DatabaseRole,
+  GENERATED_SECRET_FORMAT,
   type RuntimeSecret,
   SERVICE_SECRET_ENV,
   serviceSecrets,
@@ -47,6 +48,26 @@ export function generateSecretValue(): string {
   return randomBytes(32).toString("hex");
 }
 
+/**
+ * The first value of a CLI-generated secret, in its format
+ * ({@link GENERATED_SECRET_FORMAT}). `generate` makes the hex ones (tests
+ * inject it); a placeholder is the fixed value its format names.
+ */
+export function initialSecretValue(
+  name: (typeof CLI_GENERATED_SECRETS)[number],
+  generate: () => string = generateSecretValue,
+): string {
+  const format = GENERATED_SECRET_FORMAT[name];
+  switch (format.kind) {
+    case "hex32":
+      return generate();
+    case "base64-32":
+      return randomBytes(32).toString("base64");
+    case "placeholder":
+      return format.value;
+  }
+}
+
 export interface EnsureOutcome {
   readonly id: string;
   readonly status: "present" | "applied" | "failed";
@@ -282,7 +303,7 @@ export async function ensureGeneratedSecrets(
       continue;
     }
     if (!describe.ok) {
-      const value = install.seed?.[name] || generate();
+      const value = install.seed?.[name] || initialSecretValue(name, generate);
       const createWith = (replication: SecretReplication) =>
         run(
           [
@@ -341,7 +362,12 @@ export async function ensureGeneratedSecrets(
       outcomes.push({ id, status: "present" });
       continue;
     }
-    const add = await addVersion(run, secretId, project, install.seed?.[name] || generate());
+    const add = await addVersion(
+      run,
+      secretId,
+      project,
+      install.seed?.[name] || initialSecretValue(name, generate),
+    );
     outcomes.push(add.ok ? { id, status: "applied" } : { id, status: "failed", error: add.error });
   }
   return outcomes;
@@ -375,6 +401,13 @@ export const ROTATABLE_SECRETS = [
 ] as const satisfies readonly RuntimeSecret[];
 export type RotatableSecret = (typeof ROTATABLE_SECRETS)[number];
 
+/**
+ * #806 — the remote-MCP seal key rotates in two steps with an overlap
+ * window (`rotate-secret mcp-oauth-seal-key`, then `--finish`), not through
+ * {@link rotateRuntimeSecret}: see seal-key-rotation.ts.
+ */
+export const SEAL_KEY_SECRET = "mcp-oauth-seal-key" satisfies RuntimeSecret;
+
 /**
  * Why `name` cannot be rotated, or `null` when it can.
  *
@@ -384,10 +417,15 @@ export type RotatableSecret = (typeof ROTATABLE_SECRETS)[number];
  */
 export function rotationRefusal(name: string): string | null {
   if ((ROTATABLE_SECRETS as readonly string[]).includes(name)) return null;
+  // #806 — two-step rotation with an overlap window (seal-key-rotation.ts).
+  if (name === SEAL_KEY_SECRET) return null;
+  if (name === "mcp-oauth-client") {
+    return "mcp-oauth-client is the Google OAuth client of remote MCP; the Owner replaces it under Settings → MCP → Remote (create a new client secret in the Google console first).";
+  }
   if (name === "secret-kek") {
     return "secret-kek encrypts the AI provider keys and other at-rest secrets in cms_admin; a new KEK would make them unreadable. Rotating it needs a re-encryption step that does not exist yet.";
   }
-  return `${name} is not a runtime secret of this install. Rotatable: ${ROTATABLE_SECRETS.join(", ")}.`;
+  return `${name} is not a runtime secret of this install. Rotatable: ${[...ROTATABLE_SECRETS, SEAL_KEY_SECRET].join(", ")}.`;
 }
 
 /** The deployed install `rotateRuntimeSecret` works on. */