@caelo-cms/provisioning 0.10.55 → 0.10.57

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,19 @@ export type RuntimeSecret =
   | "secret-kek"
   | "internal-secret"
   | "tool-approval-secret"
-  | "staging-gate-secret";
+  | "staging-gate-secret"
+  /**
+   * #806 — the Google OAuth client the remote-MCP broker signs users in
+   * with: JSON `{"client_id","client_secret"}`, `{}` while remote MCP is not
+   * set up. The Owner writes it from Settings → MCP → Remote (the admin may
+   * add versions, never read them); the gateway reads it from a file.
+   */
+  | "mcp-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 +305,38 @@ export const CLI_GENERATED_SECRETS = [
   // session cookies, derives the crawler credentials. Read by the admin
   // (issues) and the gateway (verifies).
   "staging-gate-secret",
+  // #806 — remote MCP. The client starts as the `{}` placeholder (not
+  // configured; the Owner fills it under Settings → MCP), the seal key as
+  // 32 random bytes in base64 ({@link GENERATED_SECRET_FORMAT}).
+  "mcp-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 (#806). A version must
+  // exist from the start: Cloud Run refuses a revision whose secret volume
+  // points at a secret without an enabled version.
+  "mcp-oauth-client": { kind: "placeholder", value: "{}" },
+};
+
 /**
  * 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 +366,96 @@ 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 remote-MCP Google OAuth client. */
+export const MCP_OAUTH_CLIENT_FILE_ENV = "CAELO_MCP_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 → MCP 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 remote-MCP OAuth client file (#806). */
+export const MCP_OAUTH_CLIENT_FILE: SecretFileContract = {
+  secret: "mcp-oauth-client",
+  volumeName: "mcp-oauth-client",
+  mountDir: "/secrets/mcp-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: [MCP_OAUTH_CLIENT_FILE],
+};
+
+/**
+ * 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),
+    ]),
+  ];
 }
 
 /**
@@ -411,10 +545,139 @@ 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: MCP_OAUTH_CLIENT_FILE_ENV, value: secretFilePath(MCP_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 OAuth client to. */
+export const MCP_OAUTH_CLIENT_STORE_ENV = "CAELO_MCP_OAUTH_CLIENT_STORE";
+
+/** `projects/<project>/secrets/<id>` of the remote-MCP OAuth client secret. */
+export function mcpOAuthClientSecretResource(projectId: string, env: string): string {
+  return `projects/${projectId}/secrets/${gcpSecretId(env, "mcp-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).
+ */
+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;
+}
+
+/** Env var names of {@link RemoteMcpIdentity}. */
+export const REMOTE_MCP_ENV = {
+  adminUrl: "CAELO_ADMIN_URL",
+  mcpPublicUrl: "CAELO_MCP_PUBLIC_URL",
+  iapAudience: "CAELO_IAP_AUDIENCE",
+} 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 page shows the redirect URI and the MCP URLs from it.
+      { name: REMOTE_MCP_ENV.mcpPublicUrl, value: id.mcpPublicUrl },
+    ],
+    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 +715,16 @@ 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") },
+    // #806 — where Settings → MCP → Remote writes the Google OAuth client
+    // (add-version only, see the run SA's secretVersionAdder invariant).
+    { name: MCP_OAUTH_CLIENT_STORE_ENV, value: mcpOAuthClientSecretResource(projectId, env) },
   ];
   if (inputs.provider === "gcp") {
     // v0.2.78 — the GCS StaticPublisher: Stage uploads to staging,
@@ -542,6 +811,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 +847,23 @@ function secretAccessors(): IamInvariant[] {
   }));
 }
 
+/** Bindings both GCP stacks declare beyond the secret accessors and telemetry. */
+const GCP_COMMON: readonly IamInvariant[] = [
+  {
+    stackResource: "admin-mcp-oauth-client-version-adder",
+    // Why the admin may write a secret at all: the Owner pastes the remote-
+    // MCP OAuth client under Settings → MCP → Remote, and the admin stores
+    // it where the gateway reads 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: "mcp-oauth-client" },
+    onFailure: "warn",
+    why: "the Owner's remote-MCP setup (Settings → MCP → Remote) 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 +1030,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,9 @@ 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 client file path and seal key.
+      "CAELO_MCP_OAUTH_CLIENT_FILE",
+      "CAELO_MCP_OAUTH_SEAL_KEY",
       // #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_MCP_OAUTH_CLIENT_STORE=projects/acme/secrets/caelo-production-mcp-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_MCP_OAUTH_CLIENT_FILE=/secrets/mcp-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-mcp-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-mcp-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(

package/src/stack-converge.ts

@@ -18,6 +18,9 @@
  *   - {@link planMediaVolume}: the admin's media bucket volume (gen2 + Cloud
  *     Storage volume + mount), added in the same `services update` when
  *     missing.
+ *   - {@link planSecretFiles} / {@link planRequestTimeout} (#806): the
+ *     gateway's secret file (the remote-MCP OAuth client) and its request
+ *     timeout, in the same `services update`.
  */
 
 import { removeDefaultFirewallRules } from "./default-firewall.js";
@@ -43,8 +46,10 @@ import {
   RETIRED_SERVICE_ENV,
   type RetiredIamBinding,
   type RuntimeEnvInputs,
+  type SecretFileContract,
   type ServiceEnvInputs,
   STATIC_CDN_POLICY,
+  secretFilePath,
   stackIamInvariants,
   staticBackendBucketPrefix,
 } from "./stack-contract.js";
@@ -285,6 +290,12 @@ export function planContractEnv(
   opts: {
     /** Contract vars to leave exactly as the services have them. */
     readonly leaveUntouched?: readonly string[];
+    /**
+     * Vars beyond the contract to set as well (#806: the remote-MCP identity
+     * env, resolved by the converge). A name the contract also sets is
+     * refused rather than silently doubled.
+     */
+    readonly extraEnv?: Readonly<Partial<Record<CloudRunSlug, readonly CloudRunEnvVar[]>>>;
   } = {},
 ):
   | {
@@ -320,16 +331,25 @@ export function planContractEnv(
     inputs = { ...runtime, provider: "gcp" };
   }
   const skip = new Set(opts.leaveUntouched ?? []);
-  const owned = (contract: readonly CloudRunEnvVar[]) => contract.filter((e) => !skip.has(e.name));
-  const admin = planEnvUpdate(
-    services.admin.liveEnv,
-    owned(adminEnvContract(inputs)),
-    RETIRED_SERVICE_ENV.admin,
-  );
+  const desired = (slug: CloudRunSlug, contract: readonly CloudRunEnvVar[]) => {
+    const extra = opts.extraEnv?.[slug] ?? [];
+    const clash = extra.find((e) => contract.some((c) => c.name === e.name));
+    if (clash) throw new Error(`${slug}: ${clash.name} is both in the contract and extra env`);
+    return [...contract, ...extra].filter((e) => !skip.has(e.name));
+  };
+  let adminDesired: CloudRunEnvVar[];
+  let gatewayDesired: CloudRunEnvVar[];
+  try {
+    adminDesired = desired("admin", adminEnvContract(inputs));
+    gatewayDesired = desired("gateway", gatewayEnvContract(runtime));
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+  const admin = planEnvUpdate(services.admin.liveEnv, adminDesired, RETIRED_SERVICE_ENV.admin);
   if (!admin.ok) return { ok: false, error: `admin: ${admin.error}` };
   const gateway = planEnvUpdate(
     services.gateway.liveEnv,
-    owned(gatewayEnvContract(runtime)),
+    gatewayDesired,
     RETIRED_SERVICE_ENV.gateway,
   );
   if (!gateway.ok) return { ok: false, error: `gateway: ${gateway.error}` };
@@ -713,6 +733,11 @@ const EXECUTION_ENVIRONMENT_ANNOTATION = "run.googleapis.com/execution-environme
 
 interface KnativeVolume {
   readonly name: string;
+  /** A Secret Manager volume (#806 secret files). */
+  readonly secret?: {
+    readonly secretName?: string;
+    readonly items?: readonly { readonly key?: string; readonly path?: string }[];
+  };
   readonly csi?: {
     readonly driver?: string;
     readonly readOnly?: boolean;
@@ -843,6 +868,75 @@ export function planMediaVolume(live: LiveVolumes, desired: MediaVolumeContract)
   return { ok: true, flags, changes };
 }
 
+// ===========================================================================
+// Secret files + request timeout (#806)
+// ===========================================================================
+
+export type RollAdditionsPlan =
+  | { readonly ok: true; readonly flags: string[]; readonly changes: string[] }
+  | { readonly ok: false; readonly error: string };
+
+/** `projects/<p>/secrets/<id>` or `<id>` → `<id>`. */
+function bareSecretId(name: string | undefined): string {
+  return (name ?? "").slice((name ?? "").lastIndexOf("/") + 1);
+}
+
+/**
+ * The flags that mount each of `files` (stack-contract.ts
+ * SERVICE_SECRET_FILES) where the stacks mount it, adding only what is
+ * missing — `--update-secrets=<dir>/<file>=<secret>:latest`, the form
+ * cloud.google.com/run/docs/configuring/services/secrets documents (gcloud
+ * names the volume itself). A file already mounted from the same secret at
+ * `latest` is converged whatever its volume is called. Anything else at that
+ * directory is refused with what was found: replacing it could feed the
+ * gateway a different credential.
+ */
+export function planSecretFiles(
+  live: LiveVolumes,
+  files: readonly SecretFileContract[],
+  env: string,
+): RollAdditionsPlan {
+  const flags: string[] = [];
+  const changes: string[] = [];
+  for (const file of files) {
+    const secretId = gcpSecretId(env, file.secret);
+    const mount = live.mounts.find((m) => m.mountPath === file.mountDir);
+    if (mount) {
+      const volume = live.volumes.find((v) => v.name === mount.name);
+      const item = volume?.secret?.items?.find((i) => i.path === file.fileName);
+      const inShape =
+        bareSecretId(volume?.secret?.secretName) === secretId && item?.key === file.version;
+      if (inShape) continue;
+      return {
+        ok: false,
+        error: `the service mounts volume "${mount.name}" at ${file.mountDir}, where ${secretId}:${file.version} belongs as ${file.fileName}. Remove it (gcloud run services update <service> --remove-volume-mount=${file.mountDir}) only if nothing else needs it, then re-run upgrade.`,
+      };
+    }
+    flags.push(`--update-secrets=${secretFilePath(file)}=${secretId}:${file.version}`);
+    changes.push(`secret file ${secretFilePath(file)}: (none) → ${secretId}:${file.version}`);
+  }
+  return { ok: true, flags, changes };
+}
+
+/** The request timeout of a described service, in seconds (null: Cloud Run's default, 300). */
+export function liveTimeoutSeconds(serviceJson: string): number | null {
+  const svc = JSON.parse(serviceJson) as {
+    spec?: { template?: { spec?: { timeoutSeconds?: number | string } } };
+  };
+  const t = svc.spec?.template?.spec?.timeoutSeconds;
+  return t === undefined ? null : Number(t);
+}
+
+/** `--timeout=<desired>` when the live timeout differs; nothing when it matches. */
+export function planRequestTimeout(live: number | null, desired: number): RollAdditionsPlan {
+  if (live === desired) return { ok: true, flags: [], changes: [] };
+  return {
+    ok: true,
+    flags: [`--timeout=${desired}`],
+    changes: [`request timeout: ${live === null ? "(default 300)" : live}s → ${desired}s`],
+  };
+}
+
 /**
  * The single `gcloud run services update` that rolls a service to a new
  * image, its run SA and its env changes, so all land in one new revision.

package/src/state-attach.test.ts

@@ -186,12 +186,18 @@ describe("state locks", () => {
       }
       if (args[1] === "cat")
         return objects.has(url) ? ok(objects.get(url)) : fail("matched no objects");
+      if (args[1] === "objects") {
+        const target = args[3] ?? "";
+        return objects.has(target)
+          ? ok(JSON.stringify({ generation: "1" }))
+          : fail("matched no objects");
+      }
       if (args[1] === "rm") return objects.delete(url) ? ok() : fail("matched no objects");
       return fail("unexpected");
     };
     const release = acquireBucketStateLock("acme-site-caelo-ops", "state migrate", run);
     expect(() => acquireBucketStateLock("acme-site-caelo-ops", "installer pulumi up", run)).toThrow(
-      /gcloud storage rm gs:\/\/acme-site-caelo-ops\/install\/state.lock/,
+      /held by state migrate .*lease runs until/,
     );
     release();
     acquireBucketStateLock("acme-site-caelo-ops", "installer pulumi up", run)();