@caelo-cms/provisioning 0.10.55 → 0.10.58

package/src/stack-contract.ts

@@ -37,6 +37,7 @@
 import type { SupportedProvider } from "./adapter.js";
 import {
   auditJobResource,
+  convergeJobResource,
   gatewayServiceAccountEmail,
   gcpBucketName,
   gcpNamePrefix,
@@ -170,6 +171,13 @@ export const OPERATOR_ACCESS_JOB_ENV_VAR = "CAELO_OPERATOR_ACCESS_JOB";
  */
 export const UPGRADER_JOB_ENV_VAR = "CAELO_UPGRADER_JOB";
 
+/**
+ * The admin env var naming the converge job (#819) — what "Install update"
+ * starts for a release that changes the cloud setup. `upgrade` leaves it
+ * untouched when it could not set the job up.
+ */
+export const CONVERGE_JOB_ENV_VAR = "CAELO_CONVERGE_JOB";
+
 /**
  * #875 — the admin env vars naming the parallel quality-audit job and the
  * bucket its tasks write results into (admin-core quality/
@@ -251,7 +259,22 @@ export type RuntimeSecret =
   | "secret-kek"
   | "internal-secret"
   | "tool-approval-secret"
-  | "staging-gate-secret";
+  | "staging-gate-secret"
+  /**
+   * #914 — the install's Google sign-in client: JSON
+   * `{"client_id","client_secret"}`, `{}` while it is not set up. One client
+   * for IAP browser login, IAP programmatic access and the remote-MCP broker
+   * (#806 introduced it as `mcp-oauth-client`). The Owner writes it from
+   * Settings → Google sign-in (the admin may add versions, never read them);
+   * the gateway reads it from a file, the operator-access sync job reads it
+   * to hand it to IAP.
+   */
+  | "operator-oauth-client"
+  /**
+   * #806 — the broker's AES-256-GCM key (base64, 32 bytes) that seals its
+   * stateless OAuth state, codes and refresh tokens. Gateway only.
+   */
+  | "mcp-oauth-seal-key";
 
 /** The Postgres roles Caelo's services log in as, with their passwords. */
 export type DatabaseRole = "admin_role" | "public_role";
@@ -285,8 +308,55 @@ export const CLI_GENERATED_SECRETS = [
   // session cookies, derives the crawler credentials. Read by the admin
   // (issues) and the gateway (verifies).
   "staging-gate-secret",
+  // #914 / #806 — the Google sign-in client starts as the `{}` placeholder
+  // (not configured; the Owner fills it under Settings → Google sign-in),
+  // the broker's seal key as 32 random bytes in base64
+  // ({@link GENERATED_SECRET_FORMAT}).
+  "operator-oauth-client",
+  "mcp-oauth-seal-key",
 ] as const satisfies readonly RuntimeSecret[];
 
+/** A CLI-generated secret's first value: random hex, random base64, or a fixed placeholder. */
+export type GeneratedSecretFormat =
+  | { readonly kind: "hex32" }
+  | { readonly kind: "base64-32" }
+  | { readonly kind: "placeholder"; readonly value: string };
+
+/**
+ * How each CLI-generated secret's first version is made. Every secret not
+ * listed is 32 random bytes as hex — the shape the stacks always generated.
+ */
+export const GENERATED_SECRET_FORMAT: Readonly<
+  Record<(typeof CLI_GENERATED_SECRETS)[number], GeneratedSecretFormat>
+> = {
+  "internal-secret": { kind: "hex32" },
+  "tool-approval-secret": { kind: "hex32" },
+  "public-role-password": { kind: "hex32" },
+  "staging-gate-secret": { kind: "hex32" },
+  // The gateway's seal key contract (#806): base64 of exactly 32 bytes.
+  "mcp-oauth-seal-key": { kind: "base64-32" },
+  // "Not configured" until the Owner pastes a client (#914). A version must
+  // exist from the start: Cloud Run refuses a revision whose secret volume
+  // points at a secret without an enabled version.
+  "operator-oauth-client": { kind: "placeholder", value: "{}" },
+};
+
+/**
+ * Secrets an older contract created that nothing reads any more. Upgrade
+ * deletes each once both services rolled onto revisions that no longer
+ * reference it (stack-converge.ts `deleteRetiredSecrets`); deleting a
+ * secret drops its IAM bindings with it. Pre-1.0 delete-don't-migrate: a
+ * renamed secret is created fresh, never copied.
+ */
+export const RETIRED_RUNTIME_SECRETS: readonly { readonly name: string; readonly why: string }[] = [
+  {
+    // #914 — renamed to `operator-oauth-client`; nobody had configured
+    // remote MCP when the rename shipped, so there is nothing to carry over.
+    name: "mcp-oauth-client",
+    why: "the Google sign-in client moved to operator-oauth-client (#914)",
+  },
+];
+
 /**
  * Each service's Secret Manager-backed env vars and the secret each reads.
  * The services' run SAs get `secretAccessor` on exactly these secrets
@@ -316,12 +386,119 @@ export const SERVICE_SECRET_ENV: Readonly<
     PUBLIC_DATABASE_PASSWORD: "public-role-password",
     // #650 — verifies staging-host requests (api-gateway staging-proxy.ts).
     CAELO_STAGING_GATE_SECRET: "staging-gate-secret",
+    // #806 — seals the remote-MCP broker's state, codes and refresh tokens.
+    CAELO_MCP_OAUTH_SEAL_KEY: "mcp-oauth-seal-key",
   },
 };
 
-/** The secrets `service` reads (deduplicated, table order). */
+// ===========================================================================
+// Secret files (#806)
+// ===========================================================================
+
+/** Env var naming the file that holds the install's Google sign-in client (#914). */
+export const OPERATOR_OAUTH_CLIENT_FILE_ENV = "CAELO_OPERATOR_OAUTH_CLIENT_FILE";
+
+/**
+ * A Secret Manager secret mounted into a service as one file, at `latest`.
+ *
+ * Why a file and not an env var: Cloud Run resolves a secret env var once,
+ * at instance start, but reads a secret volume from Secret Manager each
+ * time the file is read ("When reading a volume, Cloud Run always fetches
+ * the secret value from the Secret Manager to use the value with the latest
+ * version" — cloud.google.com/run/docs/configuring/services/secrets). So the
+ * client the Owner saves under Settings → Google sign-in reaches the running gateway
+ * (which re-reads it within 60 s) without a new revision, and the admin
+ * needs no right to deploy the gateway.
+ */
+export interface SecretFileContract {
+  readonly secret: RuntimeSecret;
+  /** Volume name the stacks give it (gcloud names the ones upgrade adds itself). */
+  readonly volumeName: string;
+  /** Directory the volume is mounted at; must not exist in the image. */
+  readonly mountDir: string;
+  readonly fileName: string;
+  /** Always `latest`: a pinned version would never see the Owner's new client. */
+  readonly version: "latest";
+}
+
+/** The gateway's Google sign-in client file, read by the remote-MCP broker (#806, #914). */
+export const OPERATOR_OAUTH_CLIENT_FILE: SecretFileContract = {
+  secret: "operator-oauth-client",
+  volumeName: "operator-oauth-client",
+  mountDir: "/secrets/operator-oauth-client",
+  fileName: "client.json",
+  version: "latest",
+};
+
+/** Full path of a secret file inside the container. */
+export function secretFilePath(file: SecretFileContract): string {
+  return `${file.mountDir}/${file.fileName}`;
+}
+
+/** Each service's secret files. The admin has none. */
+export const SERVICE_SECRET_FILES: Readonly<Record<CloudRunSlug, readonly SecretFileContract[]>> = {
+  admin: [],
+  gateway: [OPERATOR_OAUTH_CLIENT_FILE],
+};
+
+/** A secret file an older contract mounted; upgrade unmounts it in the roll. */
+export interface RetiredSecretFile {
+  readonly mountDir: string;
+  readonly fileName: string;
+  readonly why: string;
+}
+
+/**
+ * Secret files older contracts mounted that nothing reads any more, per
+ * service. The roll removes each mount (`--remove-secrets=<path>`) in the
+ * same revision that mounts its replacement.
+ */
+export const RETIRED_SECRET_FILES: Readonly<Record<CloudRunSlug, readonly RetiredSecretFile[]>> = {
+  admin: [],
+  gateway: [
+    {
+      mountDir: "/secrets/mcp-oauth-client",
+      fileName: "client.json",
+      why: "the Google sign-in client is mounted from operator-oauth-client now (#914)",
+    },
+  ],
+};
+
+/**
+ * The secret files of `service` in the shape `gcp.cloudrunv2.Service`
+ * takes: `volumes` on the template, `volumeMounts` on the container.
+ */
+export function secretFileVolumesTemplate(
+  service: CloudRunSlug,
+  env: string,
+): {
+  readonly volumes: {
+    name: string;
+    secret: { secret: string; items: { version: string; path: string }[] };
+  }[];
+  readonly volumeMounts: { name: string; mountPath: string }[];
+} {
+  const files = SERVICE_SECRET_FILES[service];
+  return {
+    volumes: files.map((f) => ({
+      name: f.volumeName,
+      secret: {
+        secret: gcpSecretId(env, f.secret),
+        items: [{ version: f.version, path: f.fileName }],
+      },
+    })),
+    volumeMounts: files.map((f) => ({ name: f.volumeName, mountPath: f.mountDir })),
+  };
+}
+
+/** The secrets `service` reads, as env or as files (deduplicated, table order). */
 export function serviceSecrets(service: CloudRunSlug): RuntimeSecret[] {
-  return [...new Set(Object.values(SERVICE_SECRET_ENV[service]))];
+  return [
+    ...new Set([
+      ...Object.values(SERVICE_SECRET_ENV[service]),
+      ...SERVICE_SECRET_FILES[service].map((f) => f.secret),
+    ]),
+  ];
 }
 
 /**
@@ -332,8 +509,11 @@ export function serviceSecrets(service: CloudRunSlug): RuntimeSecret[] {
  * credential is in its env (apps/api-gateway `adminDatabaseAccessInEnv`).
  */
 export const RETIRED_SERVICE_ENV: Readonly<Record<CloudRunSlug, readonly string[]>> = {
-  admin: [],
+  // #914 — the sign-in client's store was renamed with its secret.
+  admin: ["CAELO_MCP_OAUTH_CLIENT_STORE"],
   gateway: [
+    // #914 — renamed to CAELO_OPERATOR_OAUTH_CLIENT_FILE with its secret.
+    "CAELO_MCP_OAUTH_CLIENT_FILE",
     "CAELO_SECRET_KEK",
     "ADMIN_DATABASE_URL",
     "ADMIN_DATABASE_PASSWORD",
@@ -411,10 +591,159 @@ export function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvV
     ...commonEnv(inputs),
     { name: TRUSTED_PROXY_HOPS_ENV, value: String(GATEWAY_TRUSTED_PROXY_HOPS[inputs.provider]) },
     { name: "PUBLIC_DATABASE_URL", value: inputs.databaseUrls.public },
+    // #806 — where the remote-MCP broker reads its Google OAuth client
+    // (the secret volume of SERVICE_SECRET_FILES).
+    { name: OPERATOR_OAUTH_CLIENT_FILE_ENV, value: secretFilePath(OPERATOR_OAUTH_CLIENT_FILE) },
     ...secretEnv("gateway", inputs.env),
   ];
 }
 
+/**
+ * #806 — the gateway's request timeout, in seconds: Cloud Run's maximum.
+ * The gateway proxies remote-MCP requests to the admin, and a `caelo_chat`
+ * turn streams for as long as the admin's own chat stream may (the admin
+ * runs at 3600 s for the same reason). Visitor endpoints are unaffected: a
+ * timeout is a ceiling, not a reservation, and Cloud Run bills request time,
+ * not the allowed maximum. On `gcp` the load balancer in front adds no
+ * shorter limit — the backend-service timeout does not apply to serverless
+ * NEGs, which get a fixed 60 minutes
+ * (cloud.google.com/load-balancing/docs/negs/serverless-neg-concepts).
+ */
+export const GATEWAY_TIMEOUT_SECONDS = 3600;
+
+/** Admin env var naming the Secret Manager secret the Owner writes the Google sign-in client to. */
+export const OPERATOR_OAUTH_CLIENT_STORE_ENV = "CAELO_OPERATOR_OAUTH_CLIENT_STORE";
+
+/** `projects/<project>/secrets/<id>` of the Google sign-in client secret (#914). */
+export function operatorOAuthClientSecretResource(projectId: string, env: string): string {
+  return `projects/${projectId}/secrets/${gcpSecretId(env, "operator-oauth-client")}`;
+}
+
+// ===========================================================================
+// Remote MCP identity env (#806)
+// ===========================================================================
+
+/**
+ * The remote-MCP env vars that name generated identities of the install:
+ * the admin's URL, the gateway's public origin, and the audience of the IAP
+ * JWTs the admin verifies.
+ *
+ * They are not part of {@link adminEnvContract} / {@link gatewayEnvContract}
+ * because the stacks cannot declare them: on `gcp-firebase` each service's
+ * value names a Cloud Run service Pulumi auto-names (the admin's audience is
+ * its own name; the gateway's public URL is its own URL; the admin's URL is
+ * a service created after the gateway), and on `gcp` the audience is the
+ * numeric id of a backend service created after the admin. A resource
+ * cannot take its own (or a later resource's) output as input. So the CLI
+ * reads the live identities after deploy and applies these vars with gcloud
+ * — the wizard after every `pulumi up`, `upgrade` after every roll
+ * (remote-mcp.ts `ensureRemoteMcpIdentityEnv`). A roll that does not set
+ * them leaves them as they are (planEnvUpdate never removes a var the
+ * contract does not own).
+ *
+ * #914 adds two the admin's Google sign-in needs: its own URL (the
+ * self-check opens it signed out) and the project's Google organisation
+ * domain, which the admin's service account cannot read (organisation
+ * metadata needs a grant on the organisation) but the operator's identity
+ * usually can.
+ */
+export interface RemoteMcpIdentity {
+  /** Where the gateway proxies `/api/mcp/<surface>` to (IAP in front). */
+  readonly adminUrl: string;
+  /** The broker's public origin; no trailing slash. */
+  readonly mcpPublicUrl: string;
+  /** The `aud` of the admin's IAP JWTs. */
+  readonly iapAudience: string;
+  /**
+   * #914 — the project's Google organisation domain, `none` when the project
+   * is in no organisation, undefined when it could not be read (the var is
+   * then left as it is and the admin reports the organisation as unknown).
+   */
+  readonly googleOrgDomain?: string;
+}
+
+/** Env var names of {@link RemoteMcpIdentity}. */
+export const REMOTE_MCP_ENV = {
+  adminUrl: "CAELO_ADMIN_URL",
+  mcpPublicUrl: "CAELO_MCP_PUBLIC_URL",
+  iapAudience: "CAELO_IAP_AUDIENCE",
+  googleOrgDomain: "CAELO_GOOGLE_ORG_DOMAIN",
+} as const;
+
+/** What {@link remoteMcpIdentity} derives the identity from — all read from the live install. */
+export type RemoteMcpIdentityInputs =
+  | {
+      readonly provider: "gcp";
+      readonly domain: string;
+      readonly projectNumber: string;
+      /** Numeric `id` of the admin's IAP-enabled backend service. */
+      readonly adminBackendServiceId: string;
+    }
+  | {
+      readonly provider: "gcp-firebase";
+      readonly projectNumber: string;
+      readonly region: string;
+      readonly adminServiceName: string;
+      /** The services' `status.url` (`https://<name>-<hash>-<r>.a.run.app`). */
+      readonly adminServiceUrl: string;
+      readonly gatewayServiceUrl: string;
+    };
+
+/**
+ * The install's remote-MCP identity.
+ *
+ * - `gcp`: the broker answers on the site's own host through the load
+ *   balancer (`/api/*` and the `/.well-known/oauth-*` path rules), the admin
+ *   on `admin.<domain>` behind the LB's IAP; the IAP audience is
+ *   `/projects/<number>/global/backendServices/<id>`.
+ * - `gcp-firebase`: the broker answers on the gateway's own Cloud Run URL
+ *   (Firebase Hosting rewrites cut requests at 60 s and buffer streams), the
+ *   admin on its Cloud Run URL behind native IAP — whatever custom domain
+ *   is mapped to it, IAP and its audience are the service's; the audience
+ *   is `/projects/<number>/locations/<region>/services/<name>`.
+ *
+ * Audience formats: cloud.google.com/iap/docs/signed-headers-howto.
+ */
+export function remoteMcpIdentity(i: RemoteMcpIdentityInputs): RemoteMcpIdentity {
+  const origin = (url: string) => url.replace(/\/+$/, "");
+  if (i.provider === "gcp") {
+    return {
+      adminUrl: `https://admin.${i.domain}`,
+      mcpPublicUrl: publicSiteUrl(i.domain),
+      iapAudience: `/projects/${i.projectNumber}/global/backendServices/${i.adminBackendServiceId}`,
+    };
+  }
+  return {
+    adminUrl: origin(i.adminServiceUrl),
+    mcpPublicUrl: origin(i.gatewayServiceUrl),
+    iapAudience: `/projects/${i.projectNumber}/locations/${i.region}/services/${i.adminServiceName}`,
+  };
+}
+
+/** {@link RemoteMcpIdentity} as each service's env vars. */
+export function remoteMcpIdentityEnv(
+  id: RemoteMcpIdentity,
+): Record<CloudRunSlug, CloudRunEnvVar[]> {
+  return {
+    admin: [
+      { name: REMOTE_MCP_ENV.iapAudience, value: id.iapAudience },
+      // The setup pages show the redirect URI and the MCP URLs from it.
+      { name: REMOTE_MCP_ENV.mcpPublicUrl, value: id.mcpPublicUrl },
+      // #914 — Google sign-in's self-check opens the admin signed out.
+      { name: REMOTE_MCP_ENV.adminUrl, value: id.adminUrl },
+      // #914 — who IAP admits without the Google sign-in client
+      // (admin-core security/identity-gate.ts).
+      ...(id.googleOrgDomain
+        ? [{ name: REMOTE_MCP_ENV.googleOrgDomain, value: id.googleOrgDomain }]
+        : []),
+    ],
+    gateway: [
+      { name: REMOTE_MCP_ENV.adminUrl, value: id.adminUrl },
+      { name: REMOTE_MCP_ENV.mcpPublicUrl, value: id.mcpPublicUrl },
+    ],
+  };
+}
+
 /**
  * The env of the admin service.
  *
@@ -452,10 +781,20 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     // #696 — the job "Install update" starts (upgrader-setup.ts); the admin
     // may only run it, never override it.
     { name: UPGRADER_JOB_ENV_VAR, value: upgraderJobResource(projectId, inputs.region, env) },
+    // #819 — the job "Install update" starts for a release that changes the
+    // cloud setup (converge-job-setup.ts); start-only as well.
+    { name: CONVERGE_JOB_ENV_VAR, value: convergeJobResource(projectId, inputs.region, env) },
     // #875 — the job the quality audit fans its Lighthouse runs out to, and
     // where the tasks write their results (audit-job-setup.ts).
     { name: AUDIT_JOB_ENV_VAR, value: auditJobResource(projectId, inputs.region, env) },
     { name: AUDIT_RESULTS_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "audit-results") },
+    // #914 — where Settings → Google sign-in writes the install's Google
+    // sign-in client (add-version only, see the run SA's secretVersionAdder
+    // invariant).
+    {
+      name: OPERATOR_OAUTH_CLIENT_STORE_ENV,
+      value: operatorOAuthClientSecretResource(projectId, env),
+    },
   ];
   if (inputs.provider === "gcp") {
     // v0.2.78 — the GCS StaticPublisher: Stage uploads to staging,
@@ -542,6 +881,7 @@ export interface IamInvariant {
 }
 
 const SECRET_ACCESSOR = "roles/secretmanager.secretAccessor";
+const SECRET_VERSION_ADDER = "roles/secretmanager.secretVersionAdder";
 
 /** One `secretAccessor` binding a stack declares for a service's run SA. */
 export interface RuntimeSecretBinding {
@@ -577,6 +917,24 @@ function secretAccessors(): IamInvariant[] {
   }));
 }
 
+/** Bindings both GCP stacks declare beyond the secret accessors and telemetry. */
+const GCP_COMMON: readonly IamInvariant[] = [
+  {
+    stackResource: "admin-operator-oauth-client-version-adder",
+    // Why the admin may write a secret at all: the Owner pastes the
+    // install's Google sign-in client under Settings → Google sign-in, and
+    // the admin stores it where the gateway and the operator-access sync job
+    // read it. secretVersionAdder is add-version only (no access, no
+    // destroy, no IAM), bound on this one secret only — the admin can
+    // replace the client, never read it or any other secret.
+    role: SECRET_VERSION_ADDER,
+    member: "run-sa",
+    target: { kind: "secret", name: "operator-oauth-client" },
+    onFailure: "warn",
+    why: "the Owner's Google sign-in setup (Settings → Google sign-in) stores the OAuth client; without it only that setup fails",
+  },
+];
+
 /** v0.6.6 — a custom runtime SA gets no telemetry roles implicitly. */
 const TELEMETRY: readonly IamInvariant[] = [
   {
@@ -743,6 +1101,7 @@ export const RETIRED_IAM_BINDINGS: readonly RetiredIamBinding[] = [
 export function stackIamInvariants(provider: GcpProvider): IamInvariant[] {
   return [
     ...secretAccessors(),
+    ...GCP_COMMON,
     ...(provider === "gcp" ? GCP_ONLY : GCP_FIREBASE_ONLY),
     ...TELEMETRY,
   ];

package/src/stack-converge-secrets.test.ts

@@ -342,6 +342,10 @@ describe("upgrading a v0.10.35 install: the gateway leaves admin_role (#613)", (
     expect(plan.ok && plan.services.gateway.changes.map((c) => c.name).sort()).toEqual([
       "ADMIN_DATABASE_PASSWORD",
       "ADMIN_DATABASE_URL",
+      // #806 — the remote-MCP broker's seal key and (#914) the Google
+      // sign-in client file path.
+      "CAELO_MCP_OAUTH_SEAL_KEY",
+      "CAELO_OPERATOR_OAUTH_CLIENT_FILE",
       // #650 — the staging gate key arrives in the same roll.
       "CAELO_STAGING_GATE_SECRET",
       // #845 — and which forwarded address is the visitor.

package/src/stack-converge.test.ts

@@ -312,13 +312,14 @@ describe("planContractEnv", () => {
     // #650 — the same roll converges the protected staging domain's host
     // and gate key onto an install that predates it.
     expect(plan.services.admin.flags).toEqual([
-      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,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_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_STAGING_HOST=staging.acme.com",
+      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,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_OPERATOR_OAUTH_CLIENT_STORE=projects/acme/secrets/caelo-production-operator-oauth-client,CAELO_STAGING_HOST=staging.acme.com",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     expect(plan.services.gateway.flags).toEqual([
       // The gateway learns which forwarded address is the visitor (#845).
-      "--update-env-vars=CAELO_TRUSTED_PROXY_HOPS=1",
-      "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
+      // #806 — and where the remote-MCP broker's client file and seal key are.
+      "--update-env-vars=CAELO_TRUSTED_PROXY_HOPS=1,CAELO_OPERATOR_OAUTH_CLIENT_FILE=/secrets/operator-oauth-client/client.json",
+      "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest,CAELO_MCP_OAUTH_SEAL_KEY=caelo-production-mcp-oauth-seal-key:latest",
     ]);
   });
 
@@ -474,7 +475,11 @@ describe("ensureStackInvariants", () => {
       ]),
     ],
     "secrets get-iam-policy": [
-      policy([{ role: "roles/secretmanager.secretAccessor", members: [RUN_SA, GW_SA] }]),
+      policy([
+        { role: "roles/secretmanager.secretAccessor", members: [RUN_SA, GW_SA] },
+        // #806 — the admin adds remote-MCP OAuth client versions.
+        { role: "roles/secretmanager.secretVersionAdder", members: [RUN_SA] },
+      ]),
     ],
     "storage buckets get-iam-policy": [
       policy([{ role: "roles/storage.objectAdmin", members: [RUN_SA] }]),
@@ -673,7 +678,10 @@ describe("ensureStackInvariants", () => {
         ]),
       ],
       "secrets get-iam-policy": [
-        policy([{ role: "roles/secretmanager.secretAccessor", members: [RUN_SA, GW_SA] }]),
+        policy([
+          { role: "roles/secretmanager.secretAccessor", members: [RUN_SA, GW_SA] },
+          { role: "roles/secretmanager.secretVersionAdder", members: [RUN_SA] },
+        ]),
       ],
       "storage buckets get-iam-policy": [
         policy([
@@ -779,6 +787,14 @@ describe("ensureStackInvariants", () => {
       expect(gatewayGrants).toEqual([
         `secrets add-iam-policy-binding caelo-production-public-role-password --project=acme --member=${GW_SA} --role=roles/secretmanager.secretAccessor --quiet --format=none`,
         `secrets add-iam-policy-binding caelo-production-staging-gate-secret --project=acme --member=${GW_SA} --role=roles/secretmanager.secretAccessor --quiet --format=none`,
+        // #806 — the remote-MCP broker's seal key and OAuth client file.
+        `secrets add-iam-policy-binding caelo-production-mcp-oauth-seal-key --project=acme --member=${GW_SA} --role=roles/secretmanager.secretAccessor --quiet --format=none`,
+        `secrets add-iam-policy-binding caelo-production-operator-oauth-client --project=acme --member=${GW_SA} --role=roles/secretmanager.secretAccessor --quiet --format=none`,
+      ]);
+      // #806 — the admin may add versions to the OAuth client secret, and to no other.
+      const adders = calls.filter((c) => c.includes("roles/secretmanager.secretVersionAdder"));
+      expect(adders).toEqual([
+        `secrets add-iam-policy-binding caelo-production-operator-oauth-client --project=acme --member=${RUN_SA} --role=roles/secretmanager.secretVersionAdder --quiet --format=none`,
       ]);
       for (const secret of ["internal-secret", "tool-approval-secret", "secret-kek"]) {
         expect(calls).toContain(