@caelo-cms/provisioning 0.11.10 → 0.11.12

package/src/converge-db-trust.ts

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1373 — where the converge job (#819) opens its database queue, and whom
+ * it trusts there, BEFORE the install's database TLS step (#1338) ran.
+ *
+ * The job writes the update timeline and the request's end through that
+ * queue. Its code connects with verify-full only, which needs the
+ * instance's DNS name, and on an install whose services still dial the
+ * instance's IP the DNS name exists only once the TLS step has run. When
+ * the job ran that step before opening the queue, a failure of the step
+ * reached only the job's log: Settings → Updates showed "Interrupted" and
+ * nothing else. So the job first opens the queue on the host the install
+ * dials today and runs the TLS step as a timeline step of its own
+ * (converge-job.ts `secureDatabase`).
+ *
+ * Dialling an IP, the host-name half of verify-full cannot hold (the
+ * certificate names no IP). The connection must still authenticate the
+ * server: the job's password is the provisioner's access token, worth far
+ * more than a database password, so `sslmode=require` (encrypted, server
+ * unchecked) is not an option. The trust comes from the Cloud SQL Admin
+ * API, over an authenticated channel, about this one instance:
+ *
+ *   - per-instance CA (`GOOGLE_MANAGED_INTERNAL_CA`, the default before
+ *     #1338): the instance's own server CA (`serverCaCert`). Nobody else
+ *     holds a certificate from it, so a verified chain is this instance.
+ *   - shared CA (`GOOGLE_MANAGED_CAS_CA`): always pinned, because the
+ *     shared CA signs other customers' instances too. With its certificate
+ *     active: Google's shared-CA bundle (the one every image ships) and the
+ *     fingerprints `listServerCertificates` names; not rotated in yet: the
+ *     one certificate the API names active. A listing that does not name
+ *     the active certificate with a well-formed fingerprint is refused —
+ *     fail closed, never a guess.
+ *   - any other CA mode: refused.
+ *
+ * No input but the metadata server's placement and the APIs: the job's
+ * scrubbed-environment contract (§11.C) is unchanged.
+ */
+
+import { readFileSync } from "node:fs";
+import { CLOUD_SQL_CA_BUNDLE, isIpLiteral } from "@caelo-cms/shared";
+import { z } from "zod";
+import { describeInstance } from "./cloudsql-tls.js";
+import { findSqlInstance } from "./gateway-credentials.js";
+import { gcloud } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { GCP_STACK_ENV } from "./gcp-names.js";
+import type { HttpFetch } from "./runtime-secrets.js";
+import { CLOUD_SQL_SERVER_CA_MODE } from "./stack-contract.js";
+import { type UpgraderPlacement, upgraderDatabaseHost } from "./upgrader-gcp.js";
+
+/** How the converge job reaches the database. */
+export type ConvergeDatabaseTarget =
+  /** The services dial the DNS name already: verify-full, nothing to set up. */
+  | { readonly kind: "dns"; readonly host: string }
+  /**
+   * The services dial the instance's IP: connect there, verify the chain
+   * against `caPem` and, when `pinnedSha1` is set, the certificate's
+   * fingerprint (lower-case hex, no colons) against it.
+   */
+  | {
+      readonly kind: "ip";
+      readonly host: string;
+      readonly caPem: string;
+      readonly pinnedSha1: readonly string[] | null;
+    };
+
+export interface ConvergeDatabaseTargetDeps {
+  readonly run?: GcloudRunner;
+  readonly http?: HttpFetch;
+  /** The shipped shared-CA bundle (tests pass their own). */
+  readonly readSharedCaBundle?: () => string;
+}
+
+/** A SHA-1 fingerprint as hex without separators, lower case (`AB:CD…` and `abcd…` compare equal). */
+export function normalizedSha1(fingerprint: string): string {
+  return fingerprint.replace(/[^0-9a-f]/gi, "").toLowerCase();
+}
+
+/**
+ * The host the install dials today and, when it is the instance's IP, the
+ * server identity the converge job's connection must verify there. Throws
+ * with what could not be read: without it the job must not connect.
+ */
+export async function convergeDatabaseTarget(
+  placement: Pick<UpgraderPlacement, "projectId" | "region">,
+  deps: ConvergeDatabaseTargetDeps = {},
+): Promise<ConvergeDatabaseTarget> {
+  const run = deps.run ?? gcloud;
+  const host = await upgraderDatabaseHost(placement, run);
+  if (!isIpLiteral(host)) return { kind: "dns", host };
+  const install = { projectId: placement.projectId, env: GCP_STACK_ENV };
+  const lookup = await findSqlInstance(install, { run });
+  if (lookup.status !== "found") {
+    throw new Error(`could not find the install's Cloud SQL instance (${lookup.status})`);
+  }
+  const target = { ...install, sqlInstance: lookup.name };
+  const described = await describeInstance(target, run);
+  if (!described.ok) throw new Error(described.error);
+  const d = described.d;
+  const mode = d.settings?.ipConfiguration?.serverCaMode;
+  const ownCa = d.serverCaCert?.cert?.trim() || null;
+  if (mode === CLOUD_SQL_SERVER_CA_MODE) {
+    const listing = await serverCertificateListing(
+      target,
+      run,
+      deps.http ?? (fetch as unknown as HttpFetch),
+    );
+    // Fail closed: once the shared CA may be active, every connection is
+    // pinned to a certificate the API names — the shared CA alone would
+    // also vouch for other customers' instances.
+    const sharedBundle = (
+      deps.readSharedCaBundle ?? (() => readFileSync(CLOUD_SQL_CA_BUNDLE, "utf8"))
+    )();
+    if (listing.fingerprints.includes(listing.active)) {
+      return { kind: "ip", host, caPem: sharedBundle, pinnedSha1: listing.fingerprints };
+    }
+    // Moved to the shared CA, its certificate not rotated in yet: the
+    // server still presents the active one from its own CA. Pinned to
+    // exactly that certificate, so which CA vouches for it does not widen
+    // what is accepted.
+    const caPem = [ownCa, sharedBundle].filter((c): c is string => Boolean(c)).join("\n");
+    return { kind: "ip", host, caPem, pinnedSha1: [listing.active] };
+  }
+  // Per-instance CA (the default, which older instances do not name):
+  // nobody else holds a certificate from it, so the verified chain is this
+  // instance. Any other mode (a customer-managed CA) is not one this job
+  // can reason about.
+  if (mode !== undefined && mode !== PER_INSTANCE_CA_MODE) {
+    throw new Error(
+      `${lookup.name} uses the server CA mode ${mode}, which the converge job cannot verify a connection to ${host} for`,
+    );
+  }
+  if (!ownCa) {
+    throw new Error(
+      `${lookup.name} names no server CA certificate (serverCaCert), so the connection to ${host} could not be verified`,
+    );
+  }
+  return { kind: "ip", host, caPem: ownCa, pinnedSha1: null };
+}
+
+/** Cloud SQL's default per-instance server CA mode. */
+const PER_INSTANCE_CA_MODE = "GOOGLE_MANAGED_INTERNAL_CA";
+
+const SHA1_HEX = /^[0-9a-f]{40}$/;
+
+/**
+ * The Admin API's `listServerCertificates` answer, validated: the active
+ * certificate's fingerprint and every listed one, normalized. Throws on
+ * anything else — a missing `activeVersion`, a certificate without a
+ * well-formed fingerprint — since a guessed listing would be a guessed
+ * trust decision.
+ */
+async function serverCertificateListing(
+  t: { readonly projectId: string; readonly sqlInstance: string },
+  run: GcloudRunner,
+  http: HttpFetch,
+): Promise<{ readonly active: string; readonly fingerprints: readonly string[] }> {
+  const token = await run(["auth", "print-access-token"]);
+  const bearer = token.ok ? token.stdout.trim() : "";
+  if (!bearer) throw new Error(`gcloud auth print-access-token: ${token.stderr.trim()}`);
+  const res = await http(
+    `https://sqladmin.googleapis.com/v1/projects/${encodeURIComponent(t.projectId)}/instances/${encodeURIComponent(t.sqlInstance)}/listServerCertificates`,
+    { method: "GET", headers: { Authorization: `Bearer ${bearer}` } },
+  );
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`list server certificates: HTTP ${res.status} ${text.slice(0, 300)}`);
+  }
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error("list server certificates: the Cloud SQL Admin API answered no JSON");
+  }
+  const parsed = ListingSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new Error(
+      `list server certificates: the answer does not name the active certificate and the listed ones with SHA-1 fingerprints (${parsed.error.issues[0]?.message ?? "invalid"}), so the connection is not trusted`,
+    );
+  }
+  return {
+    active: parsed.data.activeVersion,
+    fingerprints: parsed.data.serverCerts.map((c) => c.sha1Fingerprint),
+  };
+}
+
+const Sha1 = z
+  .string()
+  .transform(normalizedSha1)
+  .refine((f) => SHA1_HEX.test(f), "a SHA-1 fingerprint");
+
+const ListingSchema = z.object({
+  activeVersion: Sha1,
+  // Before the first shared-CA certificate exists the API may list none.
+  serverCerts: z.array(z.object({ sha1Fingerprint: Sha1 })).default([]),
+});
+
+/**
+ * Why a server certificate with `fingerprint` (as `node:tls` prints it) is
+ * not the instance `target` names, or null when it is. Only for an `ip`
+ * target; the chain itself is checked against `caPem` by the TLS layer.
+ */
+export function serverIdentityProblem(
+  target: Extract<ConvergeDatabaseTarget, { kind: "ip" }>,
+  fingerprint: string,
+): string | null {
+  if (target.pinnedSha1 === null) return null;
+  return target.pinnedSha1.includes(normalizedSha1(fingerprint))
+    ? null
+    : `the database at ${target.host} presented a certificate (SHA-1 ${normalizedSha1(fingerprint)}) that the Cloud SQL Admin API does not list for this install's instance`;
+}

package/src/converge-job-gcp.ts

@@ -22,9 +22,10 @@ import { join } from "node:path";
 import { CAELO_VERSION } from "@caelo-cms/shared";
 import { readConvergeCheckpoint, writeConvergeCheckpoint } from "./converge-checkpoint.js";
 import type { ConvergeJobDeps, ConvergeQueue, ConvergeUpgradeOutcome } from "./converge-job.js";
+import { isSelfGrantableRole } from "./converge-job-preflight.js";
 import { CONVERGE_TASK_TIMEOUT_MINUTES } from "./converge-job-setup.js";
 import { gcloud } from "./gcloud.js";
-import { type GcloudRunner, realSleep } from "./gcloud-retry.js";
+import { type GcloudRunner, realSleep, runWithRetry } from "./gcloud-retry.js";
 import {
   convergeJobName,
   GCP_STACK_ENV,
@@ -42,6 +43,7 @@ import {
 } from "./install-state.js";
 import { runMigrationsViaCloudRunJob } from "./migration-runner.js";
 import { installIapAllowlist } from "./operator-access.js";
+import { provisionerServiceAccountEmail } from "./provisioner-identity.js";
 import { fetchVerifiedReleaseManifest, manifestServiceImages } from "./release-manifest.js";
 import type { HttpFetch } from "./runtime-secrets.js";
 import { publicSiteUrl, STAGING_HOST_ENV } from "./stack-contract.js";
@@ -203,10 +205,34 @@ export function startedExecutionName(stdout: string, stderr: string): string | n
   return /^[a-z0-9-]+$/.test(name) ? name : null;
 }
 
-/** Every dependency of {@link runConvergeJob} except the database and the log. */
+/**
+ * The `gcloud` argv that grants the install's provisioner — this job's
+ * own identity, never another principal — `role` on the project, or null
+ * when `role` is not on the self-grant allowlist (converge-job-preflight.ts).
+ * Exported for the tests that pin the boundary.
+ */
+export function selfGrantArgs(projectId: string, role: string): string[] | null {
+  if (!isSelfGrantableRole(role)) return null;
+  return [
+    "projects",
+    "add-iam-policy-binding",
+    projectId,
+    `--member=serviceAccount:${provisionerServiceAccountEmail(projectId)}`,
+    `--role=${role}`,
+    "--condition=None",
+    "--quiet",
+    "--format=none",
+  ];
+}
+
+/**
+ * Every dependency of {@link runConvergeJob} except the database (the queue
+ * and how it is secured, #1373) and the log.
+ */
 export function gcpConvergeDeps(
   placement: UpgraderPlacement,
   queue: ConvergeQueue,
+  secureDatabase: ConvergeJobDeps["secureDatabase"],
   log: JobLog,
 ): ConvergeJobDeps {
   const run: GcloudRunner = gcloud;
@@ -300,6 +326,9 @@ export function gcpConvergeDeps(
         domain: meta.domain,
         stagingHost: installStagingHost(meta),
         ownerEmail: meta.ownerEmail,
+        ...(meta.schedulerIntervalMinutes !== undefined
+          ? { schedulerIntervalMinutes: meta.schedulerIntervalMinutes }
+          : {}),
         targetTag: m.version,
         // This code is the target release's (stage 2), so its contract is it.
         infraContractVersion: INFRA_CONTRACT_VERSION,
@@ -355,9 +384,20 @@ export function gcpConvergeDeps(
 
   return {
     queue,
+    secureDatabase,
     projectId,
     region,
     iam: gcloudIamTester(run, http),
+    grantOwnRole: async (role) => {
+      const args = selfGrantArgs(projectId, role);
+      if (!args)
+        return { ok: false, error: `${role} is not a role the converge job may grant itself` };
+      const r = await runWithRetry(run, realSleep, args);
+      return r.ok
+        ? { ok: true }
+        : { ok: false, error: r.stderr.trim() || `gcloud exited ${r.exitCode}` };
+    },
+    sleep: realSleep,
     execution: placement.execution,
     ownVersion: CAELO_VERSION,
     // The default deps: the fixed registry and signer, never overridden.

package/src/converge-job-preflight.test.ts

@@ -7,10 +7,15 @@
  */
 
 import { describe, expect, it } from "bun:test";
+import { selfGrantArgs } from "./converge-job-gcp.js";
 import {
   CONVERGE_PREFLIGHT_VOICE,
+  CONVERGE_SELF_GRANTABLE_ROLES,
   convergeAccessChecks,
   INSTALL_ROLE_USES,
+  isSelfGrantableRole,
+  SELF_GRANT_FORBIDDEN_ROLES,
+  selfGrantPlan,
 } from "./converge-job-preflight.js";
 import { PROVISIONER_ROLE_LIST } from "./gcloud.js";
 import { INSTALL_JOB_ROLES } from "./install-job.js";
@@ -43,6 +48,11 @@ const PREDEFINED: Record<string, readonly string[]> = {
     "cloudscheduler.jobs.get",
     "cloudscheduler.jobs.update",
   ],
+  "roles/workflows.editor": [
+    "workflows.workflows.create",
+    "workflows.workflows.get",
+    "workflows.workflows.update",
+  ],
   "roles/logging.logWriter": ["logging.logEntries.create"],
 };
 
@@ -74,6 +84,7 @@ describe("convergeAccessChecks", () => {
     for (const role of INSTALL_JOB_ROLES) {
       expect(checks).toContainEqual({
         resource: { kind: "project", projectId: "acme" },
+        role,
         ...INSTALL_ROLE_USES[role],
       });
     }
@@ -106,3 +117,98 @@ describe("convergeAccessChecks", () => {
     expect(reason).toContain("Cloud Shell or the computer you installed from");
   });
 });
+
+describe("the converge job's self-grant allowlist (2026-11-03)", () => {
+  it("is exactly the roles converge-job-setup.ts grants the provisioner", () => {
+    expect([...CONVERGE_SELF_GRANTABLE_ROLES]).toEqual([...INSTALL_JOB_ROLES]);
+    expect(CONVERGE_SELF_GRANTABLE_ROLES).toContain("roles/workflows.editor");
+  });
+
+  it("names no ownership or IAM-policy role", () => {
+    for (const role of CONVERGE_SELF_GRANTABLE_ROLES) {
+      for (const f of SELF_GRANT_FORBIDDEN_ROLES) {
+        expect(role === f || (f.endsWith(".") && role.startsWith(f))).toBe(false);
+      }
+    }
+  });
+
+  it("refuses every role outside the list, escalations first", () => {
+    for (const role of [
+      "roles/owner",
+      "roles/editor",
+      "roles/resourcemanager.projectIamAdmin",
+      "roles/iam.securityAdmin",
+      "roles/iam.serviceAccountKeyAdmin",
+      "roles/run.admin",
+      "roles/workflows.admin",
+      "roles/workflows.editor ",
+      "",
+    ]) {
+      expect(isSelfGrantableRole(role)).toBe(false);
+    }
+    for (const role of INSTALL_JOB_ROLES) expect(isSelfGrantableRole(role)).toBe(true);
+  });
+
+  it("the grant names the project and the provisioner only, and refuses other roles", () => {
+    expect(selfGrantArgs("acme", "roles/workflows.editor")).toEqual([
+      "projects",
+      "add-iam-policy-binding",
+      "acme",
+      "--member=serviceAccount:caelo-provisioner@acme.iam.gserviceaccount.com",
+      "--role=roles/workflows.editor",
+      "--condition=None",
+      "--quiet",
+      "--format=none",
+    ]);
+    for (const role of [
+      "roles/owner",
+      "roles/resourcemanager.projectIamAdmin",
+      "roles/run.admin",
+    ]) {
+      expect(selfGrantArgs("acme", role)).toBeNull();
+    }
+  });
+});
+
+describe("selfGrantPlan", () => {
+  it("an install from before 0.11.11 (no workflows.editor) needs one grant and nothing blocks", async () => {
+    const r = await runIamPreflight(
+      convergeAccessChecks(TARGET),
+      provisioner([
+        ...PROVISIONER_ROLE_LIST,
+        ...INSTALL_JOB_ROLES.filter((role) => role !== "roles/workflows.editor"),
+      ]),
+    );
+    expect(r.kind).toBe("missing");
+    if (r.kind !== "missing") return;
+    expect(selfGrantPlan(r.missing)).toEqual({ grant: ["roles/workflows.editor"], blocking: [] });
+  });
+
+  it("every install-job role missing: all of them, in list order", async () => {
+    const r = await runIamPreflight(
+      convergeAccessChecks(TARGET),
+      provisioner(PROVISIONER_ROLE_LIST),
+    );
+    if (r.kind !== "missing") throw new Error("expected missing");
+    const plan = selfGrantPlan([...r.missing].reverse());
+    expect(plan.grant).toEqual([...INSTALL_JOB_ROLES]);
+    expect(plan.blocking).toEqual([]);
+  });
+
+  it("a check without a role, or with a role off the list, blocks", () => {
+    const actAs = convergeAccessChecks(TARGET).find((c) =>
+      c.permissions.includes("iam.serviceAccounts.actAs"),
+    );
+    if (!actAs) throw new Error("no actAs check");
+    const forged = {
+      ...actAs,
+      role: "roles/owner" as unknown as (typeof INSTALL_JOB_ROLES)[number],
+    };
+    const plan = selfGrantPlan([
+      { check: actAs, missing: ["iam.serviceAccounts.actAs"] },
+      { check: forged, missing: ["iam.serviceAccounts.actAs"] },
+    ]);
+    expect(plan.grant).toEqual([]);
+    expect(plan.blocking).toHaveLength(2);
+  });
+});

package/src/converge-job-preflight.ts

@@ -26,6 +26,23 @@
  *   - the Cloud SQL IAM login `ensureConvergeJob` creates (member of
  *     {@link UPGRADER_DB_ROLE}): the request row and the timeline.
  *
+ * Self-grant (maintainer decision 2026-11-03). A release may add a role to
+ * {@link INSTALL_JOB_ROLES} (0.11.11 added roles/workflows.editor for the
+ * scheduler tick, #1140); an install set up before it lacks that role until
+ * a converge's `ensureConvergeJob` grants it, and the converge job used to
+ * stop here and send the Owner to Cloud Shell for exactly that grant. Now a
+ * missing role of {@link CONVERGE_SELF_GRANTABLE_ROLES} — this release's own
+ * compiled-in list, nothing a request, a record or the environment names —
+ * is not a reason to stop: stage 1 leaves it to stage 2, and stage 2 (the
+ * target release's verified ops image, under the state lock) grants it to
+ * the provisioner at project level, records each grant on the timeline and
+ * asks IAM again (converge-job.ts). Not an escalation: the provisioner holds
+ * roles/resourcemanager.projectIamAdmin since install, so it could grant
+ * itself any role already; the allowlist only narrows what the job does
+ * with that. {@link SELF_GRANT_FORBIDDEN_ROLES} pins that the list never
+ * names an ownership or IAM-policy role, and the upgrader job — which holds
+ * no IAM rights at all — has no grant step.
+ *
  * Not checked: the permissions `pulumi up` needs for the stack. They are the
  * provisioner's PROVISIONER_ROLE_LIST (gcloud.ts), granted at install by the
  * Owner's own account; a converge cannot repair them and Pulumi names what
@@ -37,7 +54,7 @@ import { convergeJobName } from "./gcp-names.js";
 import { INSTALL_JOB_ROLES, type InstallJobRole } from "./install-job.js";
 import { provisionerServiceAccountEmail } from "./provisioner-identity.js";
 import { OPS_INSTALL_PREFIX, opsBucketName } from "./state-backend.js";
-import type { AccessCheck, PreflightVoice } from "./upgrader-iam-preflight.js";
+import type { AccessCheck, MissingAccess, PreflightVoice } from "./upgrader-iam-preflight.js";
 import { UPGRADER_DB_ROLE } from "./upgrader-setup.js";
 
 /**
@@ -62,6 +79,14 @@ export const INSTALL_ROLE_USES: Record<
       "cloudscheduler.jobs.update",
     ],
   },
+  "roles/workflows.editor": {
+    need: "deploy and update the workflow the scheduler tick runs (#1140)",
+    permissions: [
+      "workflows.workflows.create",
+      "workflows.workflows.get",
+      "workflows.workflows.update",
+    ],
+  },
   "roles/logging.logWriter": {
     need: "write the update's progress to Cloud Logging",
     permissions: ["logging.logEntries.create"],
@@ -75,17 +100,86 @@ export const CONVERGE_PREFLIGHT_VOICE: PreflightVoice = {
     "Run the update once from Cloud Shell or the computer you installed from (Settings → Updates shows the command); it repairs the converge job's access.",
 };
 
+/**
+ * The roles the converge job may grant its own account when the self-check
+ * finds them missing: exactly the roles `ensureConvergeJob` grants it, as
+ * compiled into this release (see the file comment).
+ */
+export const CONVERGE_SELF_GRANTABLE_ROLES: readonly InstallJobRole[] = INSTALL_JOB_ROLES;
+
+/**
+ * Roles the converge job must never grant itself, whatever a release's list
+ * says — ownership and IAM-policy roles (prefix matches). The tests assert
+ * {@link CONVERGE_SELF_GRANTABLE_ROLES} names none of them, and the grant
+ * step refuses them again at run time.
+ */
+export const SELF_GRANT_FORBIDDEN_ROLES = [
+  "roles/owner",
+  "roles/editor",
+  "roles/resourcemanager.",
+  "roles/iam.securityAdmin",
+  "roles/iam.organizationRoleAdmin",
+  "roles/iam.serviceAccountKeyAdmin",
+  "roles/iam.workloadIdentityPoolAdmin",
+  "roles/orgpolicy.",
+  "roles/billing.",
+] as const;
+
+/** Whether the converge job may grant `role` to its own account (see the file comment). */
+export function isSelfGrantableRole(role: string): role is InstallJobRole {
+  return (
+    (CONVERGE_SELF_GRANTABLE_ROLES as readonly string[]).includes(role) &&
+    !SELF_GRANT_FORBIDDEN_ROLES.some((f) => role === f || (f.endsWith(".") && role.startsWith(f)))
+  );
+}
+
+/** A converge self-check; `role` marks a check that granting that role repairs. */
+export interface ConvergeAccessCheck extends AccessCheck {
+  readonly role?: InstallJobRole;
+}
+
+/** What the converge job does about the self-check's missing permissions. */
+export interface SelfGrantPlan {
+  /** Allowlisted roles to grant the provisioner, in list order. */
+  readonly grant: readonly InstallJobRole[];
+  /** What no grant of the job repairs: the run stops on any of these. */
+  readonly blocking: readonly MissingAccess<ConvergeAccessCheck>[];
+}
+
+/**
+ * Split the self-check's missing permissions into roles the job grants
+ * itself and the rest. A check counts as repairable only when its whole
+ * shortfall is permissions of an allowlisted role it is marked with.
+ */
+export function selfGrantPlan(
+  missing: readonly MissingAccess<ConvergeAccessCheck>[],
+): SelfGrantPlan {
+  const grant: InstallJobRole[] = [];
+  const blocking: MissingAccess<ConvergeAccessCheck>[] = [];
+  for (const m of missing) {
+    const role = m.check.role;
+    if (role && isSelfGrantableRole(role) && !(m.unchecked && m.unchecked.length > 0)) {
+      if (!grant.includes(role)) grant.push(role);
+    } else {
+      blocking.push(m);
+    }
+  }
+  const order = CONVERGE_SELF_GRANTABLE_ROLES as readonly string[];
+  grant.sort((a, b) => order.indexOf(a) - order.indexOf(b));
+  return { grant, blocking };
+}
+
 /** Every permission a converge run relies on after its decision (see the file comment). */
 export function convergeAccessChecks(target: {
   readonly projectId: string;
   readonly region: string;
   readonly env: string;
-}): AccessCheck[] {
+}): ConvergeAccessCheck[] {
   const { projectId, region, env } = target;
   const project = { kind: "project", projectId } as const;
   const bucket = opsBucketName(projectId);
   return [
-    ...INSTALL_JOB_ROLES.map((role) => ({ resource: project, ...INSTALL_ROLE_USES[role] })),
+    ...INSTALL_JOB_ROLES.map((role) => ({ resource: project, role, ...INSTALL_ROLE_USES[role] })),
     {
       need: `read and write the install's records and state lock (${OPS_INSTALL_PREFIX}/) and the update's checkpoint (${CONVERGE_STATE_PREFIX}/) in the ops bucket`,
       resource: { kind: "bucket", bucket },

package/src/converge-job-setup.ts

@@ -41,7 +41,10 @@
  *   - {@link INSTALL_JOB_ROLES} (the operator-access step of a converge
  *     creates a custom role and a Cloud Scheduler job, and the job's lines
  *     must reach Cloud Logging) — what an install-job install already
- *     grants; not an escalation, the provisioner holds projectIamAdmin;
+ *     grants; not an escalation, the provisioner holds projectIamAdmin. The
+ *     converge job of a release that adds a role here grants it itself when
+ *     it finds it missing (converge-job-preflight.ts, the self-grant), so
+ *     the role reaches an older install without a terminal run;
  *   - a Cloud SQL IAM database login that is a member of `platform_updater`
  *     only (migration 0267): it reads its request and writes the timeline,
  *     nothing else in the database.