@caelo-cms/provisioning 0.11.9 → 0.11.11

package/src/stack-contract.ts

@@ -34,6 +34,7 @@
  * Pure module — the stacks import it from `dist/`.
  */
 
+import { CLOUD_SQL_CA_BUNDLE, isIpLiteral, verifyFullQuery } from "@caelo-cms/shared";
 import { z } from "zod";
 import type { SupportedProvider } from "./adapter.js";
 import {
@@ -44,15 +45,79 @@ import {
   gcpBucketName,
   gcpNamePrefix,
   gcpSecretId,
+  mcpAuthProxyServiceAccountEmail,
   mcpIapServiceAccountEmail,
   operatorAccessJobResource,
   runServiceAccountEmail,
+  schedulerServiceAccountEmail,
   staticPublisherServiceAccountId,
   upgraderJobResource,
 } from "./gcp-names.js";
 
 export type GcpProvider = "gcp" | "gcp-firebase";
-export type CloudRunSlug = "admin" | "gateway";
+/**
+ * The install's Cloud Run services, by role: the admin, the visitor data
+ * gateway and (#1328) the MCP-Auth-Proxy — remote MCP's sign-in broker and
+ * its forwarder to the IAP-protected admin, a service of its own so a hole
+ * in a visitor handler can never reach the operators' Google tokens.
+ * Which deployed service plays which role is {@link cloudRunServicePrefix}.
+ */
+export type CloudRunSlug = "admin" | "gateway" | "mcp-auth-proxy";
+
+/** Every {@link CloudRunSlug}, in roll order: the admin first, the proxy last. */
+export const CLOUD_RUN_SLUGS: readonly CloudRunSlug[] = ["admin", "gateway", "mcp-auth-proxy"];
+
+/**
+ * The name prefix of the Cloud Run service that plays `slug` on an install
+ * (Pulumi suffixes the names it generates; the services named explicitly,
+ * {@link fixedCloudRunServiceName}, match their prefix exactly).
+ *
+ * One asymmetry, decided as E13 (a) of the gateway hardening plan (#763):
+ * on `gcp-firebase` the MCP-Auth-Proxy is the service that was the gateway
+ * before #1328. Its `run.app` URL is the remote-MCP address every connector
+ * in claude.ai / ChatGPT holds, and the Google sign-in client's registered
+ * redirect URI points at it; neither can move without the Owner
+ * re-connecting every client and editing the OAuth client by hand. So that
+ * service keeps its name and becomes the proxy, and the visitor gateway is
+ * the new `caelo-<env>-data-gateway` (the Firebase `/api/**` rewrite the
+ * publisher writes follows the admin's `CAELO_GATEWAY_SERVICE`). On `gcp`
+ * the MCP address is the site's own host behind the load balancer, so no
+ * service name is pinned there and the proxy is the new service.
+ *
+ * No prefix is a prefix of another (`…-gateway` does not prefix
+ * `…-data-gateway`), so a `metadata.name~^<prefix>` lookup finds one role.
+ */
+export function cloudRunServicePrefix(
+  provider: GcpProvider,
+  env: string,
+  slug: CloudRunSlug,
+): string {
+  const prefix = gcpNamePrefix(env);
+  if (slug === "admin") return `${prefix}-admin`;
+  if (provider === "gcp-firebase") {
+    return slug === "gateway" ? `${prefix}-data-gateway` : `${prefix}-gateway`;
+  }
+  return slug === "gateway" ? `${prefix}-gateway` : `${prefix}-mcp-auth-proxy`;
+}
+
+/**
+ * The exact name of a service that is created under a fixed name (#1328):
+ * the `gcp-firebase` data gateway and the `gcp` MCP-Auth-Proxy. Fixed, not
+ * Pulumi-suffixed, because the converge creates them on existing installs
+ * with gcloud, and the stack's next `pulumi up` must then find the same
+ * service instead of creating a second one. Null for the services Pulumi
+ * has always auto-named.
+ */
+export function fixedCloudRunServiceName(
+  provider: GcpProvider,
+  env: string,
+  slug: CloudRunSlug,
+): string | null {
+  const fixed =
+    (provider === "gcp-firebase" && slug === "gateway") ||
+    (provider === "gcp" && slug === "mcp-auth-proxy");
+  return fixed ? cloudRunServicePrefix(provider, env, slug) : null;
+}
 
 /**
  * One container env var, in the shape Pulumi's `gcp.cloudrunv2.Service`
@@ -97,6 +162,16 @@ export interface DatabaseUrls<V = string> {
    * state the admin publishes into cms_public.
    */
   readonly public: V;
+  /**
+   * #1329 — admin_role on cms_public_staging: the admin's third pool, for
+   * the staging database's plugin schemas and its half of the projection.
+   */
+  readonly publicStagingAdmin: V;
+  /**
+   * #1329 — public_staging_role on cms_public_staging, the staging
+   * gateway's only pool (served from P3b-2 on). It reaches no live data.
+   */
+  readonly publicStaging: V;
 }
 
 /** Port Cloud SQL Postgres listens on (private IP). */
@@ -106,17 +181,84 @@ const DATABASE_PORT = 5432;
  * Password-less connection URLs for a Cloud SQL instance at `host`. The
  * password reaches the apps separately, as a Secret Manager reference
  * ({@link SERVICE_SECRET_ENV}).
+ *
+ * TLS is `verify-full` against Google's Cloud SQL shared-CA bundle, which
+ * every image carries (#1338, shared database-tls.ts). The shared CA's
+ * server certificate names the instance's DNS name and no IP, so `host`
+ * must be that name (cloudsql-tls.ts resolves it in the VPC); an IP is
+ * refused here rather than producing URLs no connection can verify.
+ *
+ * @throws Error when `host` is an IP literal
  */
 export function databaseUrls(host: string): DatabaseUrls {
+  if (isIpLiteral(host)) {
+    throw new Error(
+      `the Cloud SQL host is the IP address ${host}, but verify-full connections must use the instance's DNS name (its certificate names no IP, #1338). The converge moves the services onto it: run \`cms-provision upgrade\`.`,
+    );
+  }
   const url = (role: string, db: string) =>
-    `postgresql://${role}@${host}:${DATABASE_PORT}/${db}?sslmode=require`;
+    `postgresql://${role}@${host}:${DATABASE_PORT}/${db}?${verifyFullQuery(CLOUD_SQL_CA_BUNDLE)}`;
   return {
     admin: url("admin_role", "cms_admin"),
     publicAdmin: url("admin_role", "cms_public"),
     public: url("public_role", "cms_public"),
+    publicStagingAdmin: url("admin_role", "cms_public_staging"),
+    publicStaging: url("public_staging_role", "cms_public_staging"),
   };
 }
 
+/**
+ * #1338 — the Cloud SQL server CA mode every install runs: Google's shared
+ * CA. Its server certificate carries the instance's DNS name, so a client
+ * can verify the host (`sslmode=verify-full`). The default per-instance CA
+ * names no host a private-IP client can dial ("The SAN field contains the
+ * hostname (DNS name of the instance) only for instances enabled with
+ * Private Service Connect" — docs.cloud.google.com/sql/docs/postgres/authorize-ssl).
+ * An instance moves from per-instance to shared, never back.
+ */
+export const CLOUD_SQL_SERVER_CA_MODE = "GOOGLE_MANAGED_CAS_CA";
+
+/** #1338 — Cloud SQL refuses unencrypted connections: every client uses verify-full. */
+export const CLOUD_SQL_SSL_MODE = "ENCRYPTED_ONLY";
+
+/** The `dnsNames[].connectionType` of the name a private-services-access client dials. */
+export const CLOUD_SQL_PSA_CONNECTION_TYPE = "PRIVATE_SERVICES_ACCESS";
+
+/**
+ * The private Cloud DNS zone that resolves the instance's DNS name to its
+ * private IP inside the install's VPC. Cloud SQL assigns the name but does
+ * not resolve it: "create the DNS record in a private DNS zone in the
+ * corresponding Virtual Private Cloud (VPC) network"
+ * (docs.cloud.google.com/sql/docs/postgres/configure-ssl-instance). The zone
+ * is the name itself, holding its one A record.
+ */
+export function cloudSqlDnsZoneName(env: string): string {
+  return `${gcpNamePrefix(env)}-pg-dns`;
+}
+
+/**
+ * The DNS name a private-IP client dials, from an instance's `dnsNames`,
+ * lower-case and without the trailing dot. Null when the instance has none
+ * (a per-instance-CA instance before its move to the shared CA).
+ */
+export function cloudSqlPrivateDnsName(
+  dnsNames: readonly { readonly name?: string; readonly connectionType?: string }[] | undefined,
+): string | null {
+  const entry = (dnsNames ?? []).find((d) => d.connectionType === CLOUD_SQL_PSA_CONNECTION_TYPE);
+  const name = entry?.name?.replace(/\.$/, "").toLowerCase();
+  return name ? name : null;
+}
+
+/** The database URL vars each service carries (the env contract below sets them). */
+export const DATABASE_URL_VARS = {
+  admin: ["ADMIN_DATABASE_URL", "PUBLIC_ADMIN_DATABASE_URL", "PUBLIC_STAGING_ADMIN_DATABASE_URL"],
+  gateway: ["PUBLIC_DATABASE_URL"],
+  // #1328 — no database login at all. On gcp-firebase the service still
+  // carries the gateway's URL until its roll removes it with the rest of
+  // the gateway env (RETIRED_SERVICE_ENV), so the TLS step leaves it alone.
+  "mcp-auth-proxy": [],
+} as const;
+
 /** What a running service's env derives from: install metadata + the database. */
 export interface RuntimeEnvInputs<V = string> extends ServiceEnvInputs {
   /** From the Cloud SQL private IP — an Output in the stacks. */
@@ -199,6 +341,54 @@ export const CAPTURE_JOB_ENV_VAR = "CAELO_CAPTURE_JOB";
 export const CAPTURE_BUCKET_ENV_VAR = "CAELO_CAPTURE_BUCKET";
 export const MEDIA_BUCKET_ENV_VAR = "CAELO_MEDIA_BUCKET";
 
+/**
+ * #1140 — the admin env var naming the service account of the scheduler
+ * tick (scheduler-setup.ts): the one IAP identity the admin's
+ * `/api/internal/scheduler/tick` accepts. `upgrade` leaves it untouched when
+ * it could not set the tick up.
+ */
+export const SCHEDULER_SERVICE_ACCOUNT_ENV_VAR = "CAELO_SCHEDULER_SERVICE_ACCOUNT";
+
+/**
+ * #1140 — how often the one scheduler job calls the admin's tick, in
+ * minutes (the `schedulerIntervalMinutes` install knob). Each task's own
+ * cadence lives in the admin's due-table; this only bounds how soon a due
+ * task runs. 1 is Cloud Scheduler's floor; above 15 Cloud Run has stopped
+ * the idle admin, so every tick would pay a cold start without saving
+ * anything (maintainer decision on #1140, 2026-10-26).
+ */
+export const SCHEDULER_INTERVAL_MINUTES = { default: 5, min: 1, max: 15 } as const;
+
+/**
+ * Parse the `schedulerIntervalMinutes` knob. Undefined (not configured) is
+ * the default; anything else must be an integer in the bounds — an
+ * out-of-range or non-numeric value throws (CLAUDE.md §2: no silent
+ * substitute).
+ *
+ * @param raw - the configured value (CLI flag, Pulumi config, install.json).
+ * @param source - names where the value came from, for the error.
+ */
+export function parseSchedulerIntervalMinutes(
+  raw: string | number | undefined,
+  source = "schedulerIntervalMinutes",
+): number {
+  if (raw === undefined || raw === "") return SCHEDULER_INTERVAL_MINUTES.default;
+  const n = typeof raw === "number" ? raw : /^\s*\d+\s*$/.test(raw) ? Number(raw) : Number.NaN;
+  const { min, max } = SCHEDULER_INTERVAL_MINUTES;
+  if (!Number.isInteger(n) || n < min || n > max) {
+    throw new Error(
+      `${source} ${JSON.stringify(raw)} is not a whole number of minutes between ${min} and ${max} (default ${SCHEDULER_INTERVAL_MINUTES.default})`,
+    );
+  }
+  return n;
+}
+
+/** The Cloud Scheduler / cron expression of a tick every `minutes` minutes (UTC). */
+export function schedulerCron(minutes: number): string {
+  const m = parseSchedulerIntervalMinutes(minutes);
+  return m === 1 ? "* * * * *" : `*/${m} * * * *`;
+}
+
 /** Where the admin image ships the static-generator CLI. */
 const GENERATOR_CLI = "/app/apps/static-generator/src/cli.ts";
 
@@ -268,6 +458,8 @@ export function adminMediaVolumeTemplate(volume: MediaVolumeContract) {
 export type RuntimeSecret =
   | "postgres-password"
   | "public-role-password"
+  /** #1329 — public_staging_role's password, the staging gateway's login. */
+  | "public-staging-role-password"
   | "secret-kek"
   | "internal-secret"
   | "tool-approval-secret"
@@ -289,7 +481,7 @@ export type RuntimeSecret =
   | "mcp-oauth-seal-key";
 
 /** The Postgres roles Caelo's services log in as, with their passwords. */
-export type DatabaseRole = "admin_role" | "public_role";
+export type DatabaseRole = "admin_role" | "public_role" | "public_staging_role";
 
 /**
  * Each database role's password secret — one per role (#613), so the
@@ -301,6 +493,8 @@ export type DatabaseRole = "admin_role" | "public_role";
 export const DATABASE_ROLE_SECRET: Readonly<Record<DatabaseRole, RuntimeSecret>> = {
   admin_role: "postgres-password",
   public_role: "public-role-password",
+  // #1329 — its own, so neither gateway can ever log in as the other.
+  public_staging_role: "public-staging-role-password",
 };
 
 /**
@@ -316,6 +510,9 @@ export const CLI_GENERATED_SECRETS = [
   // #613 — the gateway's own role password. Generated (never seeded from
   // `postgres-password`), so the gateway never learns admin_role's.
   "public-role-password",
+  // #1329 — the staging gateway's role password, never shared with the
+  // live gateway's (a test asserts the two public logins share no secret).
+  "public-staging-role-password",
   // #650 — the staging access gate's key: signs "Open staging" links and
   // session cookies, derives the crawler credentials. Read by the admin
   // (issues) and the gateway (verifies).
@@ -328,6 +525,19 @@ export const CLI_GENERATED_SECRETS = [
   "mcp-oauth-seal-key",
 ] as const satisfies readonly RuntimeSecret[];
 
+/**
+ * CLI-generated secrets no running service reads yet, each with what reads
+ * it until then. Everything else in {@link CLI_GENERATED_SECRETS} must be
+ * read by a service (stack-contract.test.ts), so an orphaned secret cannot
+ * ship by accident.
+ */
+export const SECRETS_SET_UP_AHEAD_OF_THEIR_READER: Readonly<
+  Partial<Record<(typeof CLI_GENERATED_SECRETS)[number], string>>
+> = {
+  "public-staging-role-password":
+    "#1329 — public_staging_role's password. The stacks (gcp.sql.User) and the converge (staging-database.ts) set the role's password from it; the staging gateway service (#1330) is its first runtime reader.",
+};
+
 /** A CLI-generated secret's first value: random hex, random base64, or a fixed placeholder. */
 export type GeneratedSecretFormat =
   | { readonly kind: "hex32" }
@@ -344,6 +554,7 @@ export const GENERATED_SECRET_FORMAT: Readonly<
   "internal-secret": { kind: "hex32" },
   "tool-approval-secret": { kind: "hex32" },
   "public-role-password": { kind: "hex32" },
+  "public-staging-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" },
@@ -381,6 +592,8 @@ export const SERVICE_SECRET_ENV: Readonly<
   admin: {
     ADMIN_DATABASE_PASSWORD: "postgres-password",
     PUBLIC_ADMIN_DATABASE_PASSWORD: "postgres-password",
+    // #1329 — admin_role on the staging database.
+    PUBLIC_STAGING_ADMIN_DATABASE_PASSWORD: "postgres-password",
     // P18 — encrypts AI provider keys and other at-rest secrets in cms_admin.
     CAELO_SECRET_KEK: "secret-kek",
     // P15.1 — HMAC key of the /api/internal/* bearer tokens (internal-jwt.ts).
@@ -398,6 +611,10 @@ 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",
+  },
+  // #1328 — with the Google sign-in client file below, the proxy's whole
+  // Secret Manager reach: no database password, no other key.
+  "mcp-auth-proxy": {
     // #806 — seals the remote-MCP broker's state, codes and refresh tokens.
     CAELO_MCP_OAUTH_SEAL_KEY: "mcp-oauth-seal-key",
   },
@@ -418,9 +635,9 @@ export const OPERATOR_OAUTH_CLIENT_FILE_ENV = "CAELO_OPERATOR_OAUTH_CLIENT_FILE"
  * 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.
+ * client the Owner saves under Settings → Google sign-in reaches the running
+ * MCP-Auth-Proxy (which re-reads it within 60 s) without a new revision, and
+ * the admin needs no right to deploy the proxy.
  */
 export interface SecretFileContract {
   readonly secret: RuntimeSecret;
@@ -433,7 +650,7 @@ export interface SecretFileContract {
   readonly version: "latest";
 }
 
-/** The gateway's Google sign-in client file, read by the remote-MCP broker (#806, #914). */
+/** The Google sign-in client file the remote-MCP broker reads (#806, #914; in the MCP-Auth-Proxy since #1328). */
 export const OPERATOR_OAUTH_CLIENT_FILE: SecretFileContract = {
   secret: "operator-oauth-client",
   volumeName: "operator-oauth-client",
@@ -447,10 +664,11 @@ export function secretFilePath(file: SecretFileContract): string {
   return `${file.mountDir}/${file.fileName}`;
 }
 
-/** Each service's secret files. The admin has none. */
+/** Each service's secret files. Only the MCP-Auth-Proxy has one. */
 export const SERVICE_SECRET_FILES: Readonly<Record<CloudRunSlug, readonly SecretFileContract[]>> = {
   admin: [],
-  gateway: [OPERATOR_OAUTH_CLIENT_FILE],
+  gateway: [],
+  "mcp-auth-proxy": [OPERATOR_OAUTH_CLIENT_FILE],
 };
 
 /** A secret file an older contract mounted; upgrade unmounts it in the roll. */
@@ -481,6 +699,22 @@ export const RETIRED_SECRET_FILES: Readonly<Record<CloudRunSlug, readonly Retire
       fileName: "client.json",
       why: "the Google sign-in client is mounted from operator-oauth-client now (#914)",
     },
+    {
+      secret: "operator-oauth-client",
+      mountDir: "/secrets/operator-oauth-client",
+      fileName: "client.json",
+      why: "the remote-MCP broker moved to the MCP-Auth-Proxy (#1328); the visitor gateway must not hold the Google sign-in client",
+    },
+  ],
+  "mcp-auth-proxy": [
+    {
+      // gcp-firebase: the proxy is the service that was the gateway, which
+      // mounted this file until #914.
+      secret: "mcp-oauth-client",
+      mountDir: "/secrets/mcp-oauth-client",
+      fileName: "client.json",
+      why: "the Google sign-in client is mounted from operator-oauth-client now (#914)",
+    },
   ],
 };
 
@@ -540,6 +774,30 @@ export const RETIRED_SERVICE_ENV: Readonly<Record<CloudRunSlug, readonly string[
     // #635 — its gateway_role login on cms_admin is gone too.
     "GATEWAY_DATABASE_URL",
     "GATEWAY_DATABASE_PASSWORD",
+    // #1328 — remote MCP moved to the MCP-Auth-Proxy.
+    "CAELO_OPERATOR_OAUTH_CLIENT_FILE",
+    "CAELO_MCP_OAUTH_SEAL_KEY",
+    "CAELO_MCP_OAUTH_SEAL_KEY_PREVIOUS",
+    "CAELO_MCP_PUBLIC_URL",
+    "CAELO_ADMIN_URL",
+  ],
+  // #1328 — on gcp-firebase the proxy is the service that was the gateway:
+  // everything that service carried for visitor traffic goes, above all
+  // every database login and the staging gate key. The proxy's SA cannot
+  // read their secrets, so a revision that kept one would not even deploy.
+  "mcp-auth-proxy": [
+    "PUBLIC_DATABASE_URL",
+    "PUBLIC_DATABASE_PASSWORD",
+    "CAELO_STAGING_GATE_SECRET",
+    "CAELO_ENV",
+    "MEDIA_STORAGE_URL",
+    "CAELO_DB_PUBLIC_POOL_MAX",
+    "CAELO_MCP_OAUTH_CLIENT_FILE",
+    "CAELO_SECRET_KEK",
+    "ADMIN_DATABASE_URL",
+    "ADMIN_DATABASE_PASSWORD",
+    "GATEWAY_DATABASE_URL",
+    "GATEWAY_DATABASE_PASSWORD",
   ],
 };
 
@@ -573,6 +831,15 @@ function commonEnv(inputs: ServiceEnvInputs): CloudRunEnvVar[] {
  */
 export const TRUSTED_PROXY_HOPS_ENV = "CAELO_TRUSTED_PROXY_HOPS";
 
+/**
+ * #1329 — the env var naming which environment a gateway serves, `live` or
+ * `staging` (apps/api-gateway database-env.ts): its database and login
+ * follow from it, and it refuses anything of the other environment's. The
+ * gateway refuses to boot without it. Every adapter sets `live` on the
+ * gateway it runs today; the staging gateway (P3b-2) gets `staging`.
+ */
+export const GATEWAY_ENVIRONMENT_ENV = "CAELO_GATEWAY_ENVIRONMENT";
+
 /**
  * {@link TRUSTED_PROXY_HOPS_ENV} per provider — a property of each
  * adapter's topology (CLAUDE.md §11.B), so it is declared here once and every
@@ -586,10 +853,12 @@ export const GATEWAY_TRUSTED_PROXY_HOPS: Readonly<Record<SupportedProvider, numb
   // ingress is internal-and-LB only, so nothing reaches it around the LB.
   gcp: 2,
   // Cloud Run's front end appends its peer. Behind the Firebase Hosting
-  // rewrite that peer is the Hosting CDN edge, and the entry Hosting adds
-  // before it cannot be told apart from a forged one (the service is
-  // invokable on *.run.app too) — so the edge address is the most that can
-  // be trusted. Staging (Cloud Run domain mapping) gets the visitor.
+  // rewrite that peer is a Google front-end proxy that changes per request,
+  // and the visitor entry Hosting writes before it cannot be told apart
+  // from a forged one (the service is invokable on *.run.app too) — so the
+  // proxy address is the most that can be trusted
+  // (docs/dev/firebase-hosting-behaviour.md). Staging (Cloud Run domain
+  // mapping) gets the visitor.
   "gcp-firebase": 1,
   // Caddy without `trusted_proxies` replaces the header with its peer; the
   // gateway is reachable only on the Compose network.
@@ -609,27 +878,114 @@ export const GATEWAY_TRUSTED_PROXY_HOPS: Readonly<Record<SupportedProvider, numb
 export function gatewayEnvContract<V>(inputs: RuntimeEnvInputs<V>): CloudRunEnvVar<V | string>[] {
   return [
     ...commonEnv(inputs),
+    // #1329 — this service is the live site's gateway: it may reach
+    // cms_public as public_role and refuses anything of the staging data.
+    { name: GATEWAY_ENVIRONMENT_ENV, value: "live" },
     { 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
+ * #1328 — whether remote MCP can exist on a provider, as the MCP-Auth-Proxy
+ * reads it. It needs the admin behind Google IAP, which only the Google
+ * Cloud installs have. `unavailable` makes the proxy answer one fixed 404
+ * to everything but its health check: the service exists on every provider
+ * at zero minimum instances (E14 a of #763), its attack surface one branch.
+ * The proxy refuses to start without the var — no default (CLAUDE.md §2).
+ */
+export const REMOTE_MCP_MODE_ENV = "CAELO_REMOTE_MCP";
+
+/** {@link REMOTE_MCP_MODE_ENV} per provider. */
+export const REMOTE_MCP_MODE: Readonly<Record<SupportedProvider, "available" | "unavailable">> = {
+  gcp: "available",
+  "gcp-firebase": "available",
+  "self-hosted": "unavailable",
+  aws: "unavailable",
+  azure: "unavailable",
+};
+
+/**
+ * {@link TRUSTED_PROXY_HOPS_ENV} of the MCP-Auth-Proxy per provider: its
+ * rate limits key on the client address by the same rule as the gateway's
+ * (@caelo-cms/shared client-address.ts), under its own topology.
+ */
+export const MCP_AUTH_PROXY_TRUSTED_PROXY_HOPS: Readonly<Record<SupportedProvider, number>> = {
+  // Behind the external Application LB (`<client>,<LB IP>`); its ingress
+  // is internal-and-LB only.
+  gcp: 2,
+  // Its own run.app URL with no rewrite in front: Cloud Run's front end
+  // appends the client.
+  "gcp-firebase": 1,
+  // Caddy (its own vhost) replaces the header with its peer.
+  "self-hosted": 1,
+  // Not deployed yet (#749); the gateway's topology once it is.
+  aws: 2,
+  // Container Apps ingress appends its peer.
+  azure: 1,
+};
+
+/**
+ * #1328 — points the `gcp-firebase` MCP-Auth-Proxy at the visitor data
+ * gateway for the traffic that still reaches the service that used to be
+ * the gateway: the Firebase `/api/**` rewrite of the release that is live
+ * until the next Publish live, and the staging host's Cloud Run domain
+ * mapping (#650), which only the domain's verified owner could move. The
+ * proxy streams that traffic to the data gateway unchanged instead of
+ * answering it (apps/mcp-auth-proxy interim-forward.ts). gcp-firebase only.
+ */
+// FIXME(issue #1331): goes with the staging cutover, once neither a mapping
+// nor a published rewrite can point at the proxy any more.
+export const INTERIM_FORWARD_ORIGIN_ENV = "CAELO_INTERIM_FORWARD_ORIGIN";
+
+/**
+ * The env of the MCP-Auth-Proxy. No database URL, no pool size, no site
+ * settings: the broker reads env plus one secret file and nothing else
+ * (apps/mcp-auth-proxy, whose import lint keeps every database client out).
+ * The remote-MCP identity env — its public origin, the admin's URL — comes
+ * on top from {@link remoteMcpIdentityEnv}, the gcp-firebase forward origin
+ * from the stack or the converge ({@link INTERIM_FORWARD_ORIGIN_ENV}).
+ */
+export function mcpAuthProxyEnvContract(inputs: {
+  readonly provider: SupportedProvider;
+  readonly env: string;
+}): CloudRunEnvVar[] {
+  return [
+    { name: "CAELO_PROVIDER", value: inputs.provider },
+    { name: REMOTE_MCP_MODE_ENV, value: REMOTE_MCP_MODE[inputs.provider] },
+    {
+      name: TRUSTED_PROXY_HOPS_ENV,
+      value: String(MCP_AUTH_PROXY_TRUSTED_PROXY_HOPS[inputs.provider]),
+    },
+    // #806 — where the broker reads the Google sign-in client (the secret
+    // volume of SERVICE_SECRET_FILES).
+    { name: OPERATOR_OAUTH_CLIENT_FILE_ENV, value: secretFilePath(OPERATOR_OAUTH_CLIENT_FILE) },
+    ...secretEnv("mcp-auth-proxy", inputs.env),
+  ];
+}
+
+/**
+ * #806 — the MCP-Auth-Proxy's request timeout, in seconds: Cloud Run's
+ * maximum (the gateway's until #1328 moved the broker out). The proxy
+ * streams 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). A timeout is a ceiling, not a reservation: 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;
+export const MCP_AUTH_PROXY_TIMEOUT_SECONDS = 3600;
+
+/**
+ * #1328 — the MCP-Auth-Proxy's maximum instances. It holds no database
+ * pool, so the connection budget does not bound it; ten instances of
+ * streaming proxies carry far more agent sessions than an install has
+ * operators, and the ceiling caps what a flood of sign-in requests can cost.
+ * Always provisioned at minimum 0 (E14 a of #763).
+ */
+export const DEFAULT_MCP_AUTH_PROXY_MAX_INSTANCES = 10;
 
 /**
  * Whether each Cloud Run service gets CPU only while it handles a request
@@ -639,15 +995,30 @@ export const GATEWAY_TIMEOUT_SECONDS = 3600;
  * `resources`, which is how both services ran with always-on CPU without
  * anyone choosing it — billed for every idle minute an instance stayed up.
  *
- * The gateway only does work inside requests. The admin still runs its
- * background work (Tier 5: audit worker, importer, plugin cron, GC) on
- * in-process timers that need CPU between requests.
+ * The gateway and the MCP-Auth-Proxy only do work inside requests. The
+ * admin's periodic work and plugin workers run on the scheduler tick
+ * (#1140), but the quality audit and the site-import crawl still run on
+ * in-process timers that need CPU between requests (#1359, #1360), and the
+ * plugin runtime heartbeat would read an idling instance as down.
  */
 export const SERVICE_CPU_IDLE: Readonly<Record<CloudRunSlug, boolean>> = {
-  // FIXME(issue #1140): true once the admin's background work no longer
-  // depends on CPU between requests (jobs, scheduler, plugin host).
+  // FIXME(issue #1361): true once nothing in the admin depends on CPU
+  // between requests (the category-A jobs, the heartbeat at request start).
   admin: false,
   gateway: true,
+  "mcp-auth-proxy": true,
+};
+
+/**
+ * Whether each service egresses into the install's VPC: the admin and the
+ * gateway reach Cloud SQL's private IP; the MCP-Auth-Proxy reaches nothing
+ * private (#1328) — it calls Google's token endpoint and the admin's public,
+ * IAP-gated URL, so it gets no route to the database's network at all.
+ */
+export const SERVICE_VPC_EGRESS: Readonly<Record<CloudRunSlug, boolean>> = {
+  admin: true,
+  gateway: true,
+  "mcp-auth-proxy": false,
 };
 
 /** Admin env var naming the Secret Manager secret the Owner writes the Google sign-in client to. */
@@ -696,7 +1067,7 @@ export function operatorOAuthClientSecretResource(projectId: string, env: string
  * usually can.
  */
 export interface RemoteMcpIdentity {
-  /** Where the gateway proxies `/api/mcp/<surface>` to (IAP in front). */
+  /** Where the MCP-Auth-Proxy forwards `/api/mcp/<surface>` to (IAP in front). */
   readonly adminUrl: string;
   /** The broker's public origin; no trailing slash. */
   readonly mcpPublicUrl: string;
@@ -734,18 +1105,20 @@ export type RemoteMcpIdentityInputs =
       readonly adminServiceName: string;
       /** The services' `status.url` (`https://<name>-<hash>-<r>.a.run.app`). */
       readonly adminServiceUrl: string;
-      readonly gatewayServiceUrl: string;
+      /** The MCP-Auth-Proxy's: the service that was the gateway before #1328 (E13 a). */
+      readonly mcpAuthProxyServiceUrl: 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
+ *   balancer (its MCP path rules route to the MCP-Auth-Proxy's backend,
+ *   #1328), 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 MCP-Auth-Proxy's own Cloud Run
+ *   URL — the URL the gateway had before #1328 (E13 a) — never through
+ *   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>`.
@@ -763,7 +1136,7 @@ export function remoteMcpIdentity(i: RemoteMcpIdentityInputs): RemoteMcpIdentity
   }
   return {
     adminUrl: origin(i.adminServiceUrl),
-    mcpPublicUrl: origin(i.gatewayServiceUrl),
+    mcpPublicUrl: origin(i.mcpAuthProxyServiceUrl),
     iapAudience: `/projects/${i.projectNumber}/locations/${i.region}/services/${i.adminServiceName}`,
   };
 }
@@ -785,7 +1158,10 @@ export function remoteMcpIdentityEnv(
         ? [{ name: REMOTE_MCP_ENV.googleOrgDomain, value: id.googleOrgDomain }]
         : []),
     ],
-    gateway: [
+    // #1328 — the broker lives in the MCP-Auth-Proxy; the visitor gateway
+    // gets none of it.
+    gateway: [],
+    "mcp-auth-proxy": [
       { name: REMOTE_MCP_ENV.adminUrl, value: id.adminUrl },
       { name: REMOTE_MCP_ENV.mcpPublicUrl, value: id.mcpPublicUrl },
     ],
@@ -852,7 +1228,7 @@ export function remoteMcpIdentityStackEnv(
   raw: string | undefined,
 ): Record<CloudRunSlug, CloudRunEnvVar[]> {
   const id = parseRemoteMcpIdentityConfig(raw);
-  return id ? remoteMcpIdentityEnv(id) : { admin: [], gateway: [] };
+  return id ? remoteMcpIdentityEnv(id) : { admin: [], gateway: [], "mcp-auth-proxy": [] };
 }
 
 /** Whether two identities would give the services the same env. */
@@ -902,6 +1278,9 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     // admin_role on cms_public: cross-DB reads, plugin DDL, migrations.
     // Not public_role (write-limited).
     { name: "PUBLIC_ADMIN_DATABASE_URL", value: inputs.databaseUrls.publicAdmin },
+    // #1329 — admin_role on cms_public_staging: the staging database's
+    // plugin schemas and its half of the projection.
+    { name: "PUBLIC_STAGING_ADMIN_DATABASE_URL", value: inputs.databaseUrls.publicStagingAdmin },
     // #551 — the admin seeds site_defaults.site_base_url from it (canonical,
     // og:url, sitemap) when it is not configured yet.
     { name: "CAELO_SITE_URL", value: publicSiteUrl(domain) },
@@ -933,6 +1312,12 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     { name: CAPTURE_JOB_ENV_VAR, value: captureJobResource(projectId, inputs.region, env) },
     { name: CAPTURE_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "capture") },
     { name: MEDIA_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "media") },
+    // #1140 — the only IAP identity the admin's scheduler tick endpoint
+    // accepts (scheduler-setup.ts).
+    {
+      name: SCHEDULER_SERVICE_ACCOUNT_ENV_VAR,
+      value: schedulerServiceAccountEmail(projectId, env),
+    },
     // #914 — where Settings → Google sign-in writes the install's Google
     // sign-in client (add-version only, see the run SA's secretVersionAdder
     // invariant).
@@ -991,6 +1376,8 @@ export type IamPrincipal =
   | "run-sa"
   /** The runtime SA the gateway runs as. */
   | "gateway-sa"
+  /** #1328 — the MCP-Auth-Proxy's SA: two secrets, nothing else. */
+  | "mcp-auth-proxy-sa"
   /** The `gcp` stack's static-publisher SA. */
   | "static-publisher-sa"
   /** IAP's Google-managed service agent (forwards IAP traffic to Cloud Run). */
@@ -1041,21 +1428,28 @@ export interface RuntimeSecretBinding {
  * on exactly the secrets its env reads ({@link SERVICE_SECRET_ENV}).
  */
 export function runtimeSecretBindings(): RuntimeSecretBinding[] {
-  return (["admin", "gateway"] as const).flatMap((service) =>
+  return CLOUD_RUN_SLUGS.flatMap((service) =>
     serviceSecrets(service).map((secret) => ({
       service,
       secret,
       // The admin's keep the names they had when one SA served both.
-      stackResource: service === "admin" ? `${secret}-binding` : `gateway-${secret}-binding`,
+      stackResource: service === "admin" ? `${secret}-binding` : `${service}-${secret}-binding`,
     })),
   );
 }
 
+/** The runtime SA each Cloud Run service runs as. */
+export const SERVICE_PRINCIPAL: Readonly<Record<CloudRunSlug, IamPrincipal>> = {
+  admin: "run-sa",
+  gateway: "gateway-sa",
+  "mcp-auth-proxy": "mcp-auth-proxy-sa",
+};
+
 function secretAccessors(): IamInvariant[] {
   return runtimeSecretBindings().map((b) => ({
     stackResource: b.stackResource,
     role: SECRET_ACCESSOR,
-    member: b.service === "admin" ? "run-sa" : "gateway-sa",
+    member: SERVICE_PRINCIPAL[b.service],
     target: { kind: "secret", name: b.secret },
     onFailure: "abort",
     why: `the ${b.service} reads ${b.secret} from Secret Manager at boot`,
@@ -1185,7 +1579,7 @@ const GCP_FIREBASE_ONLY: readonly IamInvariant[] = [
     why: "the admin publishes the site to Firebase Hosting",
   },
   {
-    stackResource: "gateway-public-invoker",
+    stackResource: "data-gateway-public-invoker",
     role: "roles/run.invoker",
     member: "allUsers",
     target: { kind: "run-service", service: "gateway" },
@@ -1193,13 +1587,24 @@ const GCP_FIREBASE_ONLY: readonly IamInvariant[] = [
     why: "Firebase Hosting rewrites /api/** to the public gateway",
   },
   {
-    stackResource: "gateway-viewer-for-admin-sa",
+    stackResource: "data-gateway-viewer-for-admin-sa",
     role: "roles/run.viewer",
     member: "run-sa",
     target: { kind: "run-service", service: "gateway" },
     onFailure: "abort",
     why: "Firebase Hosting checks run.services.get on the rewrite target at deploy time (v0.6.5; without it every publish 403s)",
   },
+  {
+    // #1328 — the service that was the gateway (E13 a); MCP clients call
+    // its run.app URL without a Google identity of their own. The stack
+    // keeps the binding's old logical name, like the service's.
+    stackResource: "gateway-public-invoker",
+    role: "roles/run.invoker",
+    member: "allUsers",
+    target: { kind: "run-service", service: "mcp-auth-proxy" },
+    onFailure: "abort",
+    why: "MCP clients sign in and call remote MCP at the MCP-Auth-Proxy's run.app URL",
+  },
   {
     stackResource: "admin-iap-sa-invoker",
     role: "roles/run.invoker",
@@ -1240,6 +1645,26 @@ export const RETIRED_IAM_BINDINGS: readonly RetiredIamBinding[] = [
     target: { kind: "secret", name: "gateway-role-password" },
     why: "the gateway has no cms_admin login at all and must not be able to read gateway_role's password (CLAUDE.md §2, #635)",
   },
+  {
+    role: SECRET_ACCESSOR,
+    member: "gateway-sa",
+    target: { kind: "secret", name: "mcp-oauth-seal-key" },
+    why: "the remote-MCP broker moved to the MCP-Auth-Proxy (#1328); a hole in a visitor handler must not open or mint the broker's sealed tokens",
+  },
+  {
+    role: SECRET_ACCESSOR,
+    member: "gateway-sa",
+    target: { kind: "secret", name: "operator-oauth-client" },
+    why: "the remote-MCP broker moved to the MCP-Auth-Proxy (#1328); the visitor gateway must not read the Google sign-in client's secret",
+  },
+  {
+    // gcp-firebase: the Firebase rewrite targets the data gateway since
+    // #1328, so the publisher no longer needs to read the proxy.
+    role: "roles/run.viewer",
+    member: "run-sa",
+    target: { kind: "run-service", service: "mcp-auth-proxy" },
+    why: "the Firebase /api/** rewrite targets the data gateway since #1328; the admin needs no read access to the MCP-Auth-Proxy",
+  },
 ];
 
 /** Every IAM binding upgrade ensures on an install of `provider`. */
@@ -1286,6 +1711,8 @@ export function iamMember(
       return `serviceAccount:${runServiceAccountEmail(install.projectId, install.env)}`;
     case "gateway-sa":
       return `serviceAccount:${gatewayServiceAccountEmail(install.projectId, install.env)}`;
+    case "mcp-auth-proxy-sa":
+      return `serviceAccount:${mcpAuthProxyServiceAccountEmail(install.projectId, install.env)}`;
     case "static-publisher-sa":
       return `serviceAccount:${staticPublisherServiceAccountId(install.env)}@${install.projectId}.iam.gserviceaccount.com`;
     case "iap-service-agent":