@caelo-cms/provisioning 0.10.61 → 0.10.62

package/src/converge-job-gcp.ts

@@ -48,10 +48,10 @@ import { publicSiteUrl, STAGING_HOST_ENV } from "./stack-contract.js";
 import { attachInstall } from "./state-attach.js";
 import { hasLocalPulumiState, opsBucketName } from "./state-backend.js";
 import { acquireBucketStateLock, GcsStateStore, realSyncGcloud } from "./state-store.js";
-import { resolveGcpResourceName } from "./upgrade/gcp-lookup.js";
+import { lookupFailure, resolveGcpResourceName } from "./upgrade/gcp-lookup.js";
 import { releaseImageRef, verifyCosignAll } from "./upgrade/release-images.js";
 import { upgradeGcpInstallOutcome } from "./upgrade/upgrade.js";
-import { healthProbeFor, type UpgraderPlacement } from "./upgrader-gcp.js";
+import { gcloudIamTester, healthProbeFor, type UpgraderPlacement } from "./upgrader-gcp.js";
 import type { JobLog } from "./upgrader-reporter.js";
 
 const DIGEST = /@(sha256:[0-9a-f]{64})/;
@@ -273,14 +273,16 @@ export function gcpConvergeDeps(
       projectId,
       region,
     );
-    const described = admin
-      ? await run(["run", "services", "describe", admin, ...location, "--format=json"])
-      : null;
-    const siteCheck = !admin
-      ? "the admin service could not be found"
-      : described?.ok
-        ? deployedSiteMismatch(described.stdout, meta, region)
-        : `the admin's description could not be read (${described?.stderr.trim() ?? ""})`;
+    const described =
+      admin.status === "found"
+        ? await run(["run", "services", "describe", admin.name, ...location, "--format=json"])
+        : null;
+    const siteCheck =
+      admin.status !== "found"
+        ? lookupFailure(admin, `${gcpNamePrefix(GCP_STACK_ENV)}-admin* Cloud Run service`, "job")
+        : described?.ok
+          ? deployedSiteMismatch(described.stdout, meta, region)
+          : `the admin's description could not be read (${described?.stderr.trim() ?? ""})`;
     if (siteCheck) {
       reporter.error(
         `Nothing was changed: the install's records name ${meta.domain} in ${meta.region}, which this update could not confirm against what the admin serves today (${siteCheck}). Run the update once from Cloud Shell or the computer you installed from.`,
@@ -304,6 +306,7 @@ export function gcpConvergeDeps(
         skipVerify: false,
         skipHealthCheck: false,
         migrationsContract: m.migrations.contract,
+        credentials: "job",
       },
       {
         run,
@@ -327,7 +330,7 @@ export function gcpConvergeDeps(
             { projectId, region: meta.region as string, imageOverride: imageRef },
             { run },
           ),
-        healthProbe: (plan) => healthProbeFor(run, http, plan),
+        healthProbe: (plan, context) => healthProbeFor(run, http, plan, context),
         recordDigests: async (digests) => {
           recorded = await recordRolledRelease(
             installId,
@@ -361,6 +364,8 @@ export function gcpConvergeDeps(
   return {
     queue,
     projectId,
+    region,
+    iam: gcloudIamTester(run, http),
     execution: placement.execution,
     ownVersion: CAELO_VERSION,
     // The default deps: the fixed registry and signer, never overridden.

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

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The converge job's IAM self-check list (#884): a provisioner holding what
+ * the install and converge-job-setup.ts grant passes it, each role the setup
+ * grants on top is checked, and losing one is named with what it is for.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  CONVERGE_PREFLIGHT_VOICE,
+  convergeAccessChecks,
+  INSTALL_ROLE_USES,
+} from "./converge-job-preflight.js";
+import { PROVISIONER_ROLE_LIST } from "./gcloud.js";
+import { INSTALL_JOB_ROLES } from "./install-job.js";
+import {
+  type IamTester,
+  preflightMissingReason,
+  resourceName,
+  runIamPreflight,
+} from "./upgrader-iam-preflight.js";
+
+const TARGET = { projectId: "acme", region: "europe-west1", env: "production" };
+
+/**
+ * The permissions of the predefined roles the provisioner holds, as far as
+ * the self-check asks for them (cloud.google.com/iam/docs/understanding-roles).
+ */
+const PREDEFINED: Record<string, readonly string[]> = {
+  "roles/run.admin": ["run.jobs.get", "run.jobs.update", "run.jobs.run", "run.executions.get"],
+  "roles/cloudsql.admin": ["cloudsql.instances.get", "cloudsql.instances.login"],
+  "roles/storage.admin": [
+    "storage.objects.list",
+    "storage.objects.get",
+    "storage.objects.create",
+    "storage.objects.delete",
+  ],
+  "roles/iam.serviceAccountUser": ["iam.serviceAccounts.actAs"],
+  "roles/iam.roleAdmin": ["iam.roles.create", "iam.roles.get", "iam.roles.update"],
+  "roles/cloudscheduler.admin": [
+    "cloudscheduler.jobs.create",
+    "cloudscheduler.jobs.get",
+    "cloudscheduler.jobs.update",
+  ],
+  "roles/logging.logWriter": ["logging.logEntries.create"],
+};
+
+/**
+ * A tester for a provisioner holding `roles` project-wide: unconditional
+ * project roles reach every resource of the project, so each answers alike.
+ */
+function provisioner(roles: readonly string[]): IamTester {
+  const held = new Set(roles.flatMap((r) => PREDEFINED[r] ?? []));
+  return {
+    granted: async (_resource, permissions) => ({
+      ok: true,
+      granted: permissions.filter((p) => held.has(p)),
+    }),
+  };
+}
+
+describe("convergeAccessChecks", () => {
+  it("a provisioner with its install roles and the converge setup's roles passes", async () => {
+    const r = await runIamPreflight(
+      convergeAccessChecks(TARGET),
+      provisioner([...PROVISIONER_ROLE_LIST, ...INSTALL_JOB_ROLES]),
+    );
+    expect(r).toEqual({ kind: "ok" });
+  });
+
+  it("checks every role converge-job-setup.ts grants the provisioner", () => {
+    const checks = convergeAccessChecks(TARGET);
+    for (const role of INSTALL_JOB_ROLES) {
+      expect(checks).toContainEqual({
+        resource: { kind: "project", projectId: "acme" },
+        ...INSTALL_ROLE_USES[role],
+      });
+    }
+  });
+
+  it("asks about the converge job, the ops bucket and the provisioner's own account", () => {
+    const where = new Set(convergeAccessChecks(TARGET).map((c) => resourceName(c.resource)));
+    expect(where).toEqual(
+      new Set([
+        "projects/acme",
+        "gs://acme-caelo-ops",
+        "projects/acme/locations/europe-west1/jobs/caelo-production-converge",
+        "projects/acme/serviceAccounts/caelo-provisioner@acme.iam.gserviceaccount.com",
+      ]),
+    );
+  });
+
+  it("a provisioner without the install-job roles is stopped, each named with what it is for", async () => {
+    const r = await runIamPreflight(
+      convergeAccessChecks(TARGET),
+      provisioner(PROVISIONER_ROLE_LIST),
+    );
+    expect(r.kind).toBe("missing");
+    if (r.kind !== "missing") return;
+    expect(r.missing.flatMap((m) => m.missing).sort()).toEqual(
+      INSTALL_JOB_ROLES.flatMap((role) => INSTALL_ROLE_USES[role].permissions).sort(),
+    );
+    const reason = preflightMissingReason(r.missing, CONVERGE_PREFLIGHT_VOICE);
+    expect(reason).toContain("keeps the admin's access list in sync");
+    expect(reason).toContain("Cloud Shell or the computer you installed from");
+  });
+});

package/src/converge-job-preflight.ts

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The converge job's IAM self-check (#884): before the job takes the state
+ * lock, hands over or backs anything up, it asks Google Cloud whether its
+ * identity — the install's `caelo-provisioner` — holds what the converge
+ * relies on, and stops with every missing permission named when it does
+ * not. Same mechanism and types as the upgrader's (upgrader-iam-preflight.ts,
+ * #818); only the list and the voice differ.
+ *
+ * What is checked is what converge-job-setup.ts grants or relies on, derived
+ * from the same constants so the two cannot drift:
+ *
+ *   - every role of {@link INSTALL_JOB_ROLES} that `ensureConvergeJob`
+ *     grants the provisioner, each by the permissions the converge uses from
+ *     it ({@link INSTALL_ROLE_USES} is keyed by the role, so a new role
+ *     without a check does not compile);
+ *   - the ops bucket: install.json + the state lock under `install/`, the
+ *     checkpoint under `converge/`. The provisioner holds them through the
+ *     project's roles/storage.admin, which carries no IAM condition, so the
+ *     bucket's own testIamPermissions answers for every prefix (unlike the
+ *     upgrader's `install/`-conditioned grant, which has to be probed);
+ *   - the converge job itself: stage 1 points it at the target's ops image
+ *     and starts a new execution, and the job keeps running as the
+ *     provisioner (actAs on its own account);
+ *   - the Cloud SQL IAM login `ensureConvergeJob` creates (member of
+ *     {@link UPGRADER_DB_ROLE}): the request row and the timeline.
+ *
+ * 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
+ * it lacks precisely.
+ */
+
+import { CONVERGE_STATE_PREFIX } from "./converge-checkpoint.js";
+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 { UPGRADER_DB_ROLE } from "./upgrader-setup.js";
+
+/**
+ * What a converge does with each role `ensureConvergeJob` grants the
+ * provisioner on top of its install roles, and the permissions of that role
+ * it uses (operator-access.ts creates the custom role and the scheduler
+ * job; the job's lines go to Cloud Logging).
+ */
+export const INSTALL_ROLE_USES: Record<
+  InstallJobRole,
+  { readonly need: string; readonly permissions: readonly string[] }
+> = {
+  "roles/iam.roleAdmin": {
+    need: "create and update the custom role that decides who may open the admin",
+    permissions: ["iam.roles.create", "iam.roles.get", "iam.roles.update"],
+  },
+  "roles/cloudscheduler.admin": {
+    need: "create and update the schedule that keeps the admin's access list in sync",
+    permissions: [
+      "cloudscheduler.jobs.create",
+      "cloudscheduler.jobs.get",
+      "cloudscheduler.jobs.update",
+    ],
+  },
+  "roles/logging.logWriter": {
+    need: "write the update's progress to Cloud Logging",
+    permissions: ["logging.logEntries.create"],
+  },
+};
+
+/** The converge job's voice: the setup is re-converged by a terminal upgrade. */
+export const CONVERGE_PREFLIGHT_VOICE: PreflightVoice = {
+  subject: "the converge job",
+  repair:
+    "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.",
+};
+
+/** 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[] {
+  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] })),
+    {
+      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 },
+      permissions: [
+        "storage.objects.list",
+        "storage.objects.get",
+        "storage.objects.create",
+        "storage.objects.delete",
+      ],
+    },
+    {
+      need: "point the converge job at the new release's installer and start it",
+      resource: { kind: "run-job", projectId, region, name: convergeJobName(env) },
+      permissions: ["run.jobs.get", "run.jobs.update", "run.jobs.run"],
+    },
+    {
+      need: "see whether an earlier run of the converge job has ended",
+      resource: project,
+      permissions: ["run.executions.get"],
+    },
+    {
+      need: "keep the converge job running as the install's provisioner account",
+      resource: {
+        kind: "service-account",
+        projectId,
+        email: provisionerServiceAccountEmail(projectId),
+      },
+      permissions: ["iam.serviceAccounts.actAs"],
+    },
+    {
+      need: `sign in to the database as its ${UPGRADER_DB_ROLE} login (the update's request and timeline)`,
+      resource: project,
+      permissions: ["cloudsql.instances.get", "cloudsql.instances.login"],
+    },
+  ];
+}

package/src/converge-job.test.ts

@@ -25,6 +25,7 @@ import type { InstallMetadata } from "./install-state.js";
 import type { ReleaseManifest, ReleaseManifestResult } from "./release-manifest.js";
 import { StateLockHeldError } from "./state-store.js";
 import type { UpgradeCheckpoint } from "./upgrade/upgrade.js";
+import { type IamTester, resourceName } from "./upgrader-iam-preflight.js";
 import type { UpdateEnd, UpdateFacts } from "./upgrader-job.js";
 
 const D = (c: string) => `sha256:${c.repeat(64)}`;
@@ -144,6 +145,8 @@ function harness(
     lock?: () => () => void;
     outcome?: ConvergeUpgradeOutcome;
     imageSigned?: boolean;
+    /** What IAM answers the self-check; every permission asked for by default. */
+    iam?: IamTester;
   } = {},
 ): Harness {
   const calls: string[] = [];
@@ -154,6 +157,10 @@ function harness(
   const deps: ConvergeJobDeps = {
     queue: q.queue,
     projectId: "acme",
+    region: "europe-west1",
+    iam: opts.iam ?? {
+      granted: async (_resource, permissions) => ({ ok: true, granted: permissions }),
+    },
     execution: "caelo-production-converge-run1",
     ownVersion: opts.ownVersion ?? "0.11.0",
     fetchManifest: async (v) => {
@@ -250,6 +257,49 @@ describe("runConvergeJob — what stops the job before any change", () => {
     expect(h.calls.some((c) => /^(lock|point|start|upgrade|checkpoint)/.test(c))).toBe(false);
   };
 
+  it("#884: a missing grant stops either stage before the lock, every missing one named", async () => {
+    // The provisioner lost cloudscheduler.admin and actAs on itself.
+    const iam: IamTester = {
+      granted: async (resource, permissions) => ({
+        ok: true,
+        granted: permissions.filter(
+          (p) =>
+            !p.startsWith("cloudscheduler.") &&
+            !(resource.kind === "service-account" && p === "iam.serviceAccounts.actAs"),
+        ),
+      }),
+    };
+    for (const stage of ["0.10.53", "0.11.0"]) {
+      const h = harness({ ownVersion: stage, iam });
+      const r = await runConvergeJob(h.deps);
+      expect(r.status).toBe("needs_cloud_shell");
+      nothingChanged(h);
+      expect(h.q.ends[0]?.codes).toEqual(["iam-preflight"]);
+      const reason = h.q.ends[0]?.reason ?? "";
+      expect(reason).toStartWith("Nothing was changed: the converge job checked its access");
+      expect(reason).toContain("cloudscheduler.jobs.create");
+      expect(reason).toContain(
+        "projects/acme/serviceAccounts/caelo-provisioner@acme.iam.gserviceaccount.com",
+      );
+      expect(reason).toContain("repairs the converge job's access");
+    }
+  });
+
+  it("#884: IAM that cannot be asked fails the run before the lock", async () => {
+    const h = harness({
+      iam: {
+        granted: async (resource) =>
+          resource.kind === "bucket" ? { ok: false, error: "HTTP 503" } : { ok: true, granted: [] },
+      },
+    });
+    const r = await runConvergeJob(h.deps);
+    expect(r.status).toBe("failed");
+    nothingChanged(h);
+    expect(h.q.ends[0]?.reason).toContain(
+      `${resourceName({ kind: "bucket", bucket: "acme-caelo-ops" })}: HTTP 503`,
+    );
+  });
+
   it("a tampered or unsigned manifest", async () => {
     for (const stage of ["0.10.53", "0.11.0"]) {
       const h = harness({

package/src/converge-job.ts

@@ -15,8 +15,9 @@
  *     fetches the target's release manifest from the FIXED registry and
  *     verifies its signature (release-manifest.ts), and decides
  *     (upgrader-assess.ts, `route: "converge"`): no downgrade, nothing
- *     below minFromVersion, no automatic converge. Then it verifies the
- *     target's ops image, points this job at it BY DIGEST and starts a new
+ *     below minFromVersion, no automatic converge unless the policy allows
+ *     it; then it checks its own IAM access (converge-job-preflight.ts).
+ *     Then it verifies the target's ops image, points this job at it BY DIGEST and starts a new
  *     execution, handing the request over to it. It changes nothing else:
  *     the converge logic always comes from the release it installs.
  *
@@ -45,6 +46,8 @@
  */
 
 import type { ConvergeCheckpoint } from "./converge-checkpoint.js";
+import { CONVERGE_PREFLIGHT_VOICE, convergeAccessChecks } from "./converge-job-preflight.js";
+import { GCP_STACK_ENV } from "./gcp-names.js";
 import { decideInstallJob, type ExecutionState } from "./install-job.js";
 import type { InstallMetadata } from "./install-state.js";
 import {
@@ -55,6 +58,12 @@ import {
 import { StateLockHeldError } from "./state-store.js";
 import type { UpgradeCheckpoint } from "./upgrade/upgrade.js";
 import { assessUpgradeRequest } from "./upgrader-assess.js";
+import {
+  type IamTester,
+  preflightErrorReason,
+  preflightMissingReason,
+  runIamPreflight,
+} from "./upgrader-iam-preflight.js";
 import {
   type ClaimedUpdate,
   recordUpdateEnd,
@@ -111,6 +120,10 @@ export interface ConvergeJobDeps {
   readonly queue: ConvergeQueue;
   /** From the metadata server — never from env or argv. */
   readonly projectId: string;
+  /** The region this job runs in (metadata server). */
+  readonly region: string;
+  /** Asks IAM as this job's own identity (the IAM self-check, #884). */
+  readonly iam: IamTester;
   /** This Cloud Run execution; null outside Cloud Run. */
   readonly execution: string | null;
   /** The Caelo release this code belongs to (CAELO_VERSION of the image). */
@@ -297,6 +310,29 @@ export async function runConvergeJob(deps: ConvergeJobDeps): Promise<UpgraderRun
     for (const w of decision.warnings) r.warn(w);
     const m = decision.manifest;
 
+    // #884 — decided to run: ask IAM for what the rest needs before the
+    // lock, the hand-over or the backup (converge-job-preflight.ts). Both
+    // stages ask; stage 2's list is the target release's own.
+    const access = await runIamPreflight(
+      convergeAccessChecks({ projectId: deps.projectId, region: deps.region, env: GCP_STACK_ENV }),
+      deps.iam,
+    );
+    if (access.kind === "missing") {
+      return stopWith(
+        "needs_cloud_shell",
+        ["iam-preflight"],
+        preflightMissingReason(access.missing, CONVERGE_PREFLIGHT_VOICE),
+      );
+    }
+    if (access.kind === "error") {
+      return stopWith(
+        "failed",
+        ["iam-preflight"],
+        preflightErrorReason(access.errors, CONVERGE_PREFLIGHT_VOICE),
+      );
+    }
+    r.info("The converge job has every permission this update needs.");
+
     if (compareSemver(deps.ownVersion, m.version) !== 0) {
       return await handOver(m);
     }

package/src/gateway-credentials.test.ts

@@ -141,9 +141,10 @@ describe("planPublicRoleSwitch", () => {
 describe("findSqlInstance", () => {
   it("finds the Pulumi-suffixed instance by the stack's prefix", async () => {
     const { run, lines } = fakeGcloud({});
-    expect(await findSqlInstance({ projectId: "acme", env: "production" }, { run })).toBe(
-      "caelo-production-pg-1a2b3c",
-    );
+    expect(await findSqlInstance({ projectId: "acme", env: "production" }, { run })).toEqual({
+      status: "found",
+      name: "caelo-production-pg-1a2b3c",
+    });
     expect(lines).toContain(
       "sql instances list --project=acme --filter=name~^caelo-production-pg --format=value(name)",
     );

package/src/gateway-credentials.ts

@@ -32,6 +32,7 @@ import {
 } from "./runtime-secrets.js";
 import { DATABASE_ROLE_SECRET } from "./stack-contract.js";
 import type { LiveEnvValue } from "./stack-converge.js";
+import { type GcpLookup, lookupFromListing } from "./upgrade/gcp-lookup.js";
 
 /**
  * Whether this roll moves `public_role` onto its own password: true while
@@ -107,13 +108,14 @@ export function planPublicRoleSwitch(
 }
 
 /**
- * The install's Cloud SQL instance (Pulumi suffixes its name), or null when
- * none or the listing fails.
+ * The install's Cloud SQL instance (Pulumi suffixes its name). A failed
+ * listing comes back as an error with gcloud's stderr, never as "not found"
+ * (#630).
  */
 export async function findSqlInstance(
   install: { readonly projectId: string; readonly env: string },
   deps: { readonly run?: GcloudRunner } = {},
-): Promise<string | null> {
+): Promise<GcpLookup> {
   const run = deps.run ?? defaultGcloud;
   const r = await run([
     "sql",
@@ -123,11 +125,5 @@ export async function findSqlInstance(
     `--filter=name~^${gcpNamePrefix(install.env)}-pg`,
     "--format=value(name)",
   ]);
-  if (!r.ok) return null;
-  return (
-    r.stdout
-      .split("\n")
-      .map((l) => l.trim())
-      .find((l) => l.length > 0) ?? null
-  );
+  return lookupFromListing(r);
 }

package/src/gateway-env-isolation.test.ts

@@ -135,6 +135,7 @@ describe("self-hosted: the generated compose gateway service (#635)", () => {
       postgresPassword: "superpw",
       rolePasswords: { admin: "adminpw", public: "publicpw" },
       caeloSecretKek: "0".repeat(64),
+      internalSecret: "i".repeat(48),
       diskSize: "20Gi",
       images: {
         mode: "release" as const,

package/src/gcloud.test.ts

@@ -1,7 +1,14 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { type GcloudResult, grantProvisionerRoles, PROVISIONER_ROLE_LIST } from "./gcloud.js";
+import {
+  checkGcloudAuth,
+  type GcloudResult,
+  grantProvisionerRoles,
+  isGcloudAuthError,
+  PROVISIONER_ROLE_LIST,
+  projectDisplayName,
+} from "./gcloud.js";
 
 const ok: GcloudResult = { ok: true, stdout: "", stderr: "", exitCode: 0 };
 const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
@@ -97,3 +104,88 @@ describe("grantProvisionerRoles", () => {
     expect(result.failed).toEqual([{ role, error: SA_NOT_YET_VISIBLE }]);
   });
 });
+
+// Mirrors the Resource Manager displayName rule: 4–30 chars of letters,
+// digits, spaces, hyphens, quotes and `!`.
+const GCP_DISPLAY_NAME = /^[A-Za-z0-9 '"!-]{4,30}$/;
+
+describe("projectDisplayName", () => {
+  it("names the project after the domain so installs are distinguishable", () => {
+    expect(projectDisplayName("searchviu.com")).toBe("Caelo searchviu-com");
+    expect(projectDisplayName("docs.caelo-cms.com")).toBe("Caelo docs-caelo-cms-com");
+  });
+
+  it("stays within the GCP displayName rules for long or odd domains", () => {
+    for (const domain of [
+      "a-very-long-subdomain.of-an-even-longer-domain.example.co.uk",
+      "Example.COM",
+      "xn--mnchen-3ya.de",
+      "ab.c",
+    ]) {
+      const name = projectDisplayName(domain);
+      expect(name).toMatch(GCP_DISPLAY_NAME);
+      expect(name).not.toMatch(/-$/);
+    }
+  });
+});
+
+describe("checkGcloudAuth (#630)", () => {
+  const account = { ...ok, stdout: "owner@acme.com\n" };
+  const runner = (token: GcloudResult, list: GcloudResult = account) => {
+    const calls: string[] = [];
+    const run = async (args: string[]): Promise<GcloudResult> => {
+      calls.push(args.join(" "));
+      return args[1] === "list" ? list : token;
+    };
+    return { run, calls };
+  };
+
+  it("passes when gcloud can mint a token", async () => {
+    const { run, calls } = runner({ ...ok, stdout: "ya29.secret" });
+    expect(await checkGcloudAuth(run)).toEqual({ ok: true, account: "owner@acme.com" });
+    expect(calls[1]).toBe("auth print-access-token --quiet");
+  });
+
+  it("expired credentials pass `auth list` but fail here, with the login fix", async () => {
+    const { run } = runner(
+      fail(
+        "ERROR: (gcloud.auth.print-access-token) There was a problem refreshing your current auth tokens: Reauthentication failed. cannot prompt during non-interactive execution.",
+      ),
+    );
+    const r = await checkGcloudAuth(run);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toContain("gcloud auth login");
+    expect(r.error).toContain("owner@acme.com");
+  });
+
+  it("no logged-in account", async () => {
+    const { run } = runner(ok, ok);
+    const r = await checkGcloudAuth(run);
+    expect(r).toEqual({
+      ok: false,
+      error:
+        "No gcloud account is logged in. Run `gcloud auth login` with the Owner's Google account, then run this command again.",
+    });
+  });
+
+  it("another failure names gcloud's error, not expired credentials", async () => {
+    const { run } = runner(fail("ERROR: network unreachable"));
+    const r = await checkGcloudAuth(run);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toContain("network unreachable");
+    expect(r.error).not.toContain("expired");
+  });
+
+  it("recognises the reauth failures gcloud prints", () => {
+    for (const stderr of [
+      "Reauthentication failed. cannot prompt during non-interactive execution.",
+      "google.auth.exceptions.RefreshError: ('invalid_grant: Bad Request', ...)",
+      "Please run: $ gcloud auth login to obtain new credentials. reauth related error (invalid_rapt)",
+    ]) {
+      expect(isGcloudAuthError(stderr)).toBe(true);
+    }
+    expect(isGcloudAuthError("PERMISSION_DENIED: run.services.list")).toBe(false);
+  });
+});