@caelo-cms/provisioning 0.10.55 → 0.10.58

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 === "operator-oauth-client") {
+    return "operator-oauth-client is the install's Google sign-in client (IAP sign-in and remote MCP); the Owner replaces it under Settings → Google sign-in (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. */

package/src/seal-key-rotation.test.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { rotationRefusal } from "./runtime-secrets.js";
+import {
+  finishSealKeyRotation,
+  SEAL_KEY_PREVIOUS_ENV,
+  SEAL_KEY_ROTATION_WINDOW_DAYS,
+  SEAL_ROTATION_LABEL,
+  startSealKeyRotation,
+} from "./seal-key-rotation.js";
+
+const T = {
+  projectId: "acme",
+  region: "europe-west1",
+  env: "production",
+  gatewayService: "caelo-production-gateway-abc",
+};
+const DAY = 24 * 60 * 60 * 1000;
+const NOW = Date.UTC(2026, 9, 20);
+
+function service(opts: { previous?: boolean; startedAt?: number }) {
+  const env: unknown[] = [
+    {
+      name: "CAELO_MCP_OAUTH_SEAL_KEY",
+      valueFrom: { secretKeyRef: { name: "caelo-production-mcp-oauth-seal-key", key: "latest" } },
+    },
+  ];
+  if (opts.previous) {
+    env.push({
+      name: SEAL_KEY_PREVIOUS_ENV,
+      valueFrom: { secretKeyRef: { name: "caelo-production-mcp-oauth-seal-key", key: "3" } },
+    });
+  }
+  return JSON.stringify({
+    metadata: {
+      labels: opts.startedAt === undefined ? {} : { [SEAL_ROTATION_LABEL]: String(opts.startedAt) },
+    },
+    spec: { template: { spec: { containers: [{ env }] } } },
+  });
+}
+
+function fake(svc: string, versionName = "projects/1/secrets/s/versions/3") {
+  const calls: { line: string; stdin?: string }[] = [];
+  const run: GcloudRunner = async (args, opts) => {
+    const line = args.join(" ");
+    calls.push({ line, ...(opts?.stdin !== undefined ? { stdin: opts.stdin } : {}) });
+    const ok = (stdout = "") => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+    if (line.startsWith("run services describe")) return ok(svc);
+    if (line.startsWith("secrets versions describe latest")) return ok(`${versionName}\n`);
+    return ok();
+  };
+  return { run, calls };
+}
+
+describe("seal-key rotation (#806)", () => {
+  it("is offered by rotate-secret (two steps), not refused", () => {
+    expect(rotationRefusal("mcp-oauth-seal-key")).toBeNull();
+  });
+
+  it("start: adds a version, keeps the new key at latest and pins the old version as previous", async () => {
+    const f = fake(service({}));
+    const r = await startSealKeyRotation(T, { run: f.run, nowMs: () => NOW, generate: () => "K" });
+    expect(r.ok).toBe(true);
+    expect(f.calls.find((c) => c.line.startsWith("secrets versions add"))?.stdin).toBe("K");
+    const update = f.calls.find((c) => c.line.startsWith("run services update "))?.line ?? "";
+    expect(update).toContain(
+      `--update-secrets=CAELO_MCP_OAUTH_SEAL_KEY=caelo-production-mcp-oauth-seal-key:latest,${SEAL_KEY_PREVIOUS_ENV}=caelo-production-mcp-oauth-seal-key:3`,
+    );
+    expect(update).toContain(`--update-labels=${SEAL_ROTATION_LABEL}=${NOW}`);
+    expect(f.calls.at(-1)?.line).toContain("update-traffic caelo-production-gateway-abc");
+  });
+
+  it("start: refuses while a rotation is in progress, before touching the secret", async () => {
+    const f = fake(service({ previous: true, startedAt: NOW - DAY }));
+    const r = await startSealKeyRotation(T, { run: f.run, nowMs: () => NOW });
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain("already in progress");
+    expect(f.calls.some((c) => c.line.startsWith("secrets versions add"))).toBe(false);
+  });
+
+  it("start: refuses an unreadable version instead of pinning a guess", async () => {
+    const f = fake(service({}), "something-else");
+    const r = await startSealKeyRotation(T, { run: f.run, nowMs: () => NOW });
+    expect(r.ok).toBe(false);
+    expect(f.calls.some((c) => c.line.startsWith("secrets versions add"))).toBe(false);
+  });
+
+  it("finish: refuses inside the refresh-token window", async () => {
+    const f = fake(service({ previous: true, startedAt: NOW - 29 * DAY }));
+    const r = await finishSealKeyRotation(T, { run: f.run, nowMs: () => NOW });
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain(`${SEAL_KEY_ROTATION_WINDOW_DAYS}-day lifetime`);
+    expect(f.calls.some((c) => c.line.startsWith("run services update "))).toBe(false);
+  });
+
+  it("finish --now: removes the previous key inside the window (a leaked key)", async () => {
+    const f = fake(service({ previous: true, startedAt: NOW - DAY }));
+    const r = await finishSealKeyRotation(T, { run: f.run, nowMs: () => NOW }, { now: true });
+    expect(r.ok).toBe(true);
+    expect(f.calls.some((c) => c.line.includes(`--remove-secrets=${SEAL_KEY_PREVIOUS_ENV}`))).toBe(
+      true,
+    );
+  });
+
+  it("finish: after the window, removes the previous key and the label", async () => {
+    const f = fake(service({ previous: true, startedAt: NOW - 31 * DAY }));
+    const r = await finishSealKeyRotation(T, { run: f.run, nowMs: () => NOW });
+    expect(r.ok).toBe(true);
+    const update = f.calls.find((c) => c.line.startsWith("run services update "))?.line ?? "";
+    expect(update).toContain(`--remove-secrets=${SEAL_KEY_PREVIOUS_ENV}`);
+    expect(update).toContain(`--remove-labels=${SEAL_ROTATION_LABEL}`);
+  });
+
+  it("finish: refuses when no rotation is in progress", async () => {
+    const f = fake(service({}));
+    const r = await finishSealKeyRotation(T, { run: f.run, nowMs: () => NOW });
+    expect(r.ok).toBe(false);
+    expect(r.error).toContain("No seal-key rotation is in progress");
+  });
+
+  it("keeps the window equal to the broker's refresh-token lifetime", async () => {
+    const src = await Bun.file(
+      new URL("../../../apps/api-gateway/src/mcp/token.ts", import.meta.url),
+    ).text();
+    expect(src).toContain(
+      `REFRESH_MAX_LIFETIME_SECONDS = ${SEAL_KEY_ROTATION_WINDOW_DAYS} * 24 * 60 * 60`,
+    );
+  });
+});

package/src/seal-key-rotation.ts

@@ -0,0 +1,258 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #806 — rotating the remote-MCP broker's seal key without signing
+ * every connected MCP client out.
+ *
+ * The broker seals its OAuth state, codes and refresh tokens under
+ * `CAELO_MCP_OAUTH_SEAL_KEY` (api-gateway mcp/seal.ts, envelope v2 with a
+ * key id). While `CAELO_MCP_OAUTH_SEAL_KEY_PREVIOUS` is set it also opens
+ * values sealed under that key, and seals everything new under the current
+ * one. Refresh tokens live at most {@link SEAL_KEY_ROTATION_WINDOW_DAYS}
+ * days (mcp/token.ts), so after that window nothing sealed under the old key
+ * is still valid and the previous key can go.
+ *
+ * Two steps, both `cms-provision rotate-secret mcp-oauth-seal-key`:
+ *
+ *   start   — add a new version to the secret, then roll the gateway with
+ *             the current key at `latest` and the previous key PINNED to
+ *             the version that was latest before (a pinned version never
+ *             follows the new one), labelled with the start time.
+ *   finish  — (`--finish`) once the window has passed: drop the previous key
+ *             and the label and roll again. `--finish --now` skips the
+ *             window — for a leaked key, where signing every client out is
+ *             the point.
+ *
+ * Refused instead of guessed (CLAUDE.md §2): starting while a rotation is in
+ * progress (a second start would pin the CURRENT key as "previous" and drop
+ * the real previous one early), and finishing before the window ends.
+ *
+ * A `cms-provision upgrade` whose `pulumi up` rewrites the gateway template
+ * during the window drops the previous key (the stack does not declare it):
+ * clients sealed under it sign in again. That fails safe — no token lives
+ * longer than intended — and is documented in the rotate output.
+ */
+
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { gcpSecretId } from "./gcp-names.js";
+import { initialSecretValue } from "./runtime-secrets.js";
+import { liveContainerEnv } from "./stack-converge.js";
+
+/** The gateway env var holding the previous key during a rotation. */
+export const SEAL_KEY_PREVIOUS_ENV = "CAELO_MCP_OAUTH_SEAL_KEY_PREVIOUS";
+/** The gateway env var holding the current key (stack-contract SERVICE_SECRET_ENV). */
+export const SEAL_KEY_ENV = "CAELO_MCP_OAUTH_SEAL_KEY";
+/** Label on the gateway service: when the rotation started (epoch ms). */
+export const SEAL_ROTATION_LABEL = "caelo-seal-rotation-started";
+/**
+ * Days the previous key must stay: the broker's refresh-token lifetime
+ * (api-gateway mcp/token.ts REFRESH_MAX_LIFETIME_SECONDS, 30 days).
+ */
+export const SEAL_KEY_ROTATION_WINDOW_DAYS = 30;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** The deployed gateway a rotation works on. */
+export interface SealRotationTarget {
+  readonly projectId: string;
+  readonly region: string;
+  readonly env: string;
+  /** Deployed (Pulumi-suffixed) gateway Cloud Run service name. */
+  readonly gatewayService: string;
+}
+
+export interface SealRotationReport {
+  readonly ok: boolean;
+  readonly steps: string[];
+  readonly error?: string;
+}
+
+export interface SealRotationDeps {
+  readonly run?: GcloudRunner;
+  readonly nowMs?: () => number;
+  /** The new key (default: 32 random bytes, base64 — the secret's format). */
+  readonly generate?: () => string;
+}
+
+interface GatewayState {
+  readonly previousPinned: boolean;
+  readonly startedAtMs: number | null;
+}
+
+async function gatewayState(
+  run: GcloudRunner,
+  t: SealRotationTarget,
+): Promise<{ ok: true; state: GatewayState } | { ok: false; error: string }> {
+  const r = await run([
+    "run",
+    "services",
+    "describe",
+    t.gatewayService,
+    "--region",
+    t.region,
+    `--project=${t.projectId}`,
+    "--format=json",
+  ]);
+  if (!r.ok) return { ok: false, error: `read the gateway service: ${r.stderr.trim()}` };
+  const env = liveContainerEnv(r.stdout);
+  const labels =
+    (JSON.parse(r.stdout) as { metadata?: { labels?: Record<string, string> } }).metadata?.labels ??
+    {};
+  const raw = labels[SEAL_ROTATION_LABEL];
+  const started = raw !== undefined && /^\d+$/.test(raw) ? Number(raw) : null;
+  const current = env.get(SEAL_KEY_ENV);
+  if (current?.kind !== "secret") {
+    return {
+      ok: false,
+      error: `${SEAL_KEY_ENV} on ${t.gatewayService} is not a Secret Manager reference — run \`cms-provision upgrade\` first (it installs remote MCP's secrets).`,
+    };
+  }
+  return {
+    ok: true,
+    state: { previousPinned: env.has(SEAL_KEY_PREVIOUS_ENV), startedAtMs: started },
+  };
+}
+
+function rollFlip(t: SealRotationTarget): string[] {
+  return [
+    "run",
+    "services",
+    "update-traffic",
+    t.gatewayService,
+    "--region",
+    t.region,
+    `--project=${t.projectId}`,
+    "--to-latest",
+    "--quiet",
+  ];
+}
+
+/** Start a rotation: new key at `latest`, the old one pinned as previous. */
+export async function startSealKeyRotation(
+  t: SealRotationTarget,
+  deps: SealRotationDeps = {},
+): Promise<SealRotationReport> {
+  const run = deps.run ?? defaultGcloud;
+  const now = (deps.nowMs ?? Date.now)();
+  const generate = deps.generate ?? (() => initialSecretValue("mcp-oauth-seal-key"));
+  const secretId = gcpSecretId(t.env, "mcp-oauth-seal-key");
+  const project = `--project=${t.projectId}`;
+  const steps: string[] = [];
+
+  const live = await gatewayState(run, t);
+  if (!live.ok) return { ok: false, steps, error: live.error };
+  if (live.state.previousPinned) {
+    const since = live.state.startedAtMs;
+    return {
+      ok: false,
+      steps,
+      error: `A seal-key rotation is already in progress${since ? ` (started ${new Date(since).toISOString()})` : ""}. Finish it first with \`cms-provision rotate-secret mcp-oauth-seal-key --finish\` once ${SEAL_KEY_ROTATION_WINDOW_DAYS} days have passed; starting again now would drop the previous key early.`,
+    };
+  }
+
+  const latest = await run([
+    "secrets",
+    "versions",
+    "describe",
+    "latest",
+    `--secret=${secretId}`,
+    project,
+    "--format=value(name)",
+  ]);
+  const version = /\/versions\/(\d+)\s*$/.exec(latest.stdout.trim())?.[1];
+  if (!latest.ok || !version) {
+    return {
+      ok: false,
+      steps,
+      error: `find the current version of ${secretId}: ${latest.ok ? `unexpected answer "${latest.stdout.trim()}"` : latest.stderr.trim()}`,
+    };
+  }
+
+  const add = await run(["secrets", "versions", "add", secretId, project, "--data-file=-"], {
+    stdin: generate(),
+  });
+  if (!add.ok) {
+    return { ok: false, steps, error: `add a version to ${secretId}: ${add.stderr.trim()}` };
+  }
+  steps.push(`added a new version to ${secretId} (the previous key is version ${version})`);
+
+  const update = [
+    "run",
+    "services",
+    "update",
+    t.gatewayService,
+    "--region",
+    t.region,
+    project,
+    `--update-secrets=${SEAL_KEY_ENV}=${secretId}:latest,${SEAL_KEY_PREVIOUS_ENV}=${secretId}:${version}`,
+    `--update-labels=${SEAL_ROTATION_LABEL}=${now}`,
+    "--quiet",
+  ];
+  const rolled = await run(update);
+  const flipped = rolled.ok ? await run(rollFlip(t)) : rolled;
+  if (!flipped.ok) {
+    return {
+      ok: false,
+      steps,
+      error: `The new key is stored but the gateway does not use it yet. Do not rotate again — roll the gateway:\n    gcloud ${update.join(" ")}\n    gcloud ${rollFlip(t).join(" ")}\n(${flipped.stderr.trim()})`,
+    };
+  }
+  steps.push(
+    `rolled the gateway onto the new key; tokens sealed under version ${version} keep working`,
+    `finish after ${new Date(now + SEAL_KEY_ROTATION_WINDOW_DAYS * DAY_MS).toISOString()} with: cms-provision rotate-secret mcp-oauth-seal-key --finish`,
+    "a `cms-provision upgrade` before then drops the previous key early: clients sealed under it sign in again",
+  );
+  return { ok: true, steps };
+}
+
+/** Finish a rotation: drop the previous key once the window has passed. */
+export async function finishSealKeyRotation(
+  t: SealRotationTarget,
+  deps: SealRotationDeps = {},
+  opts: { readonly now?: boolean } = {},
+): Promise<SealRotationReport> {
+  const run = deps.run ?? defaultGcloud;
+  const now = (deps.nowMs ?? Date.now)();
+  const steps: string[] = [];
+  const live = await gatewayState(run, t);
+  if (!live.ok) return { ok: false, steps, error: live.error };
+  if (!live.state.previousPinned) {
+    return {
+      ok: false,
+      steps,
+      error: `No seal-key rotation is in progress on ${t.gatewayService} (${SEAL_KEY_PREVIOUS_ENV} is not set). Start one with \`cms-provision rotate-secret mcp-oauth-seal-key\`.`,
+    };
+  }
+  const started = live.state.startedAtMs;
+  const due = started === null ? null : started + SEAL_KEY_ROTATION_WINDOW_DAYS * DAY_MS;
+  if (!opts.now && (due === null || now < due)) {
+    return {
+      ok: false,
+      steps,
+      error:
+        due === null
+          ? `The gateway has ${SEAL_KEY_PREVIOUS_ENV} but no ${SEAL_ROTATION_LABEL} label, so the rotation's start is unknown. Wait ${SEAL_KEY_ROTATION_WINDOW_DAYS} days from when it started, then run --finish --now.`
+          : `The previous key still opens refresh tokens until ${new Date(due).toISOString()} (${SEAL_KEY_ROTATION_WINDOW_DAYS}-day lifetime). Finishing now would sign those clients out; run --finish after that time, or --finish --now if the old key leaked.`,
+    };
+  }
+  const update = [
+    "run",
+    "services",
+    "update",
+    t.gatewayService,
+    "--region",
+    t.region,
+    `--project=${t.projectId}`,
+    `--remove-secrets=${SEAL_KEY_PREVIOUS_ENV}`,
+    `--remove-labels=${SEAL_ROTATION_LABEL}`,
+    "--quiet",
+  ];
+  const rolled = await run(update);
+  const flipped = rolled.ok ? await run(rollFlip(t)) : rolled;
+  if (!flipped.ok) {
+    return { ok: false, steps, error: `roll the gateway: ${flipped.stderr.trim()}` };
+  }
+  steps.push("removed the previous seal key from the gateway; the rotation is complete");
+  return { ok: true, steps };
+}

package/src/stack-contract-parity.test.ts

@@ -146,11 +146,28 @@ describe.each(["gcp", "gcp-firebase"] as const)("%s stack ↔ upgrade parity", (
     expect(src).not.toMatch(/serviceName: "gateway",[^}]*mediaVolume:/);
     // No volume, mount or execution environment besides the contract's.
     expect(src.match(/executionEnvironment:/g)).toHaveLength(1);
-    expect(src).toContain("executionEnvironment: args.mediaVolume.executionEnvironment,");
+    expect(src).toContain("? { executionEnvironment: args.mediaVolume.executionEnvironment }");
     expect(src.match(/volumes:/g)).toHaveLength(1);
-    expect(src).toContain("volumes: [...args.mediaVolume.volumes],");
+    expect(src).toMatch(
+      /volumes: \[\s*\.\.\.\(args\.mediaVolume\?\.volumes \?\? \[\]\),\s*\.\.\.secretFileVolumesTemplate\(args\.serviceName, env\)\.volumes,\s*\]/,
+    );
     expect(src.match(/volumeMounts:/g)).toHaveLength(1);
-    expect(src).toContain("volumeMounts: [...args.mediaVolume.volumeMounts]");
+    expect(src).toMatch(
+      /volumeMounts: \[\s*\.\.\.\(args\.mediaVolume\?\.volumeMounts \?\? \[\]\),\s*\.\.\.secretFileVolumesTemplate\(args\.serviceName, env\)\.volumeMounts,\s*\]/,
+    );
+  });
+
+  it("#806 — mounts each service's secret files from the contract upgrade applies", () => {
+    // secretFileVolumesTemplate(service) is SERVICE_SECRET_FILES — the same
+    // table stack-converge.ts planSecretFiles adds to existing installs.
+    expect(src).toContain("secretFileVolumesTemplate,");
+    expect(src.match(/secretFileVolumesTemplate\(args\.serviceName, env\)/g)).toHaveLength(2);
+  });
+
+  it("#806 — gives the gateway the contract's request timeout upgrade applies", () => {
+    expect(src).toMatch(
+      /serviceName: "gateway",[\s\S]*?timeout: `\$\{GATEWAY_TIMEOUT_SECONDS\}s`,[\s\S]*?contractEnv: gatewayEnvContract\(/,
+    );
   });
 
   it("sets no env var outside the contract (C1: no secret value in a plain var)", () => {

package/src/stack-contract.test.ts

@@ -71,9 +71,13 @@ describe("adminEnvContract", () => {
       CAELO_GENERATOR_CLI: "/app/apps/static-generator/src/cli.ts",
       MEDIA_ROOT_DIR: "/app/apps/admin/data/media",
       CAELO_MCP_IAP_SERVICE_ACCOUNT: "caelo-mcp@acme.iam.gserviceaccount.com",
+      // #806 — where Settings → MCP → Remote writes the OAuth client.
+      CAELO_OPERATOR_OAUTH_CLIENT_STORE:
+        "projects/acme/secrets/caelo-production-operator-oauth-client",
       CAELO_OPERATOR_ACCESS_JOB:
         "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
       CAELO_UPGRADER_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-upgrader",
+      CAELO_CONVERGE_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-converge",
       CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
       CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
       CAELO_STATIC_BUCKET: "acme-caelo-production-static",
@@ -103,9 +107,13 @@ describe("adminEnvContract", () => {
       CAELO_GENERATOR_CLI: "/app/apps/static-generator/src/cli.ts",
       MEDIA_ROOT_DIR: "/app/apps/admin/data/media",
       CAELO_MCP_IAP_SERVICE_ACCOUNT: "caelo-mcp@acme.iam.gserviceaccount.com",
+      // #806 — where Settings → MCP → Remote writes the OAuth client.
+      CAELO_OPERATOR_OAUTH_CLIENT_STORE:
+        "projects/acme/secrets/caelo-production-operator-oauth-client",
       CAELO_OPERATOR_ACCESS_JOB:
         "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
       CAELO_UPGRADER_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-upgrader",
+      CAELO_CONVERGE_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-converge",
       CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
       CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
       CAELO_FIREBASE_SITE: "caelo-production-site-abc123",
@@ -167,6 +175,9 @@ describe("gatewayEnvContract", () => {
       PUBLIC_DATABASE_URL: "postgresql://public_role@10.20.0.3:5432/cms_public?sslmode=require",
       PUBLIC_DATABASE_PASSWORD: "secret:caelo-production-public-role-password:latest",
       CAELO_STAGING_GATE_SECRET: "secret:caelo-production-staging-gate-secret:latest",
+      // #806 — the remote-MCP broker: its client file and its seal key.
+      CAELO_OPERATOR_OAUTH_CLIENT_FILE: "/secrets/operator-oauth-client/client.json",
+      CAELO_MCP_OAUTH_SEAL_KEY: "secret:caelo-production-mcp-oauth-seal-key:latest",
     });
   });
 
@@ -198,7 +209,13 @@ describe("gatewayEnvContract", () => {
   });
 
   it("the gateway's run SA reads no admin-only secret (admin password, KEK, internal, tool approval)", () => {
-    expect(serviceSecrets("gateway")).toEqual(["public-role-password", "staging-gate-secret"]);
+    expect(serviceSecrets("gateway")).toEqual([
+      "public-role-password",
+      "staging-gate-secret",
+      // #806 — the broker's seal key (env) and OAuth client (file).
+      "mcp-oauth-seal-key",
+      "operator-oauth-client",
+    ]);
     for (const v of gateway) {
       expect(v.name).not.toMatch(/KEK|INTERNAL|TOOL_APPROVAL|PUBLIC_ADMIN/);
     }
@@ -295,6 +312,17 @@ describe("runtime secrets", () => {
         secret: "staging-gate-secret",
         stackResource: "gateway-staging-gate-secret-binding",
       },
+      {
+        service: "gateway",
+        secret: "mcp-oauth-seal-key",
+        stackResource: "gateway-mcp-oauth-seal-key-binding",
+      },
+      // The secret file counts like an env secret: the SA reads it.
+      {
+        service: "gateway",
+        secret: "operator-oauth-client",
+        stackResource: "gateway-operator-oauth-client-binding",
+      },
     ]);
   });
 
@@ -351,12 +379,14 @@ describe("stackIamInvariants", () => {
     }
   });
 
-  it("grants the gateway SA only its own role password, the staging gate key + telemetry roles", () => {
+  it("grants the gateway SA only its own role password, the staging gate key, the sign-in client, the seal key + telemetry roles", () => {
     for (const provider of ["gcp", "gcp-firebase"] as const) {
       const gateway = stackIamInvariants(provider).filter((i) => i.member === "gateway-sa");
       expect(gateway.map((i) => `${i.role} ${JSON.stringify(i.target)}`).sort()).toEqual([
         'roles/logging.logWriter {"kind":"project"}',
         'roles/monitoring.metricWriter {"kind":"project"}',
+        'roles/secretmanager.secretAccessor {"kind":"secret","name":"mcp-oauth-seal-key"}',
+        'roles/secretmanager.secretAccessor {"kind":"secret","name":"operator-oauth-client"}',
         'roles/secretmanager.secretAccessor {"kind":"secret","name":"public-role-password"}',
         'roles/secretmanager.secretAccessor {"kind":"secret","name":"staging-gate-secret"}',
       ]);