package-registry-manager 0.22.5 → 0.22.7

package/README.md

@@ -22,3 +22,4 @@ version after confirmation; later versions publish through CI. Missing CI
 publishing jobs are offered in a draft pull request, and PyPI builds select an
 interpreter satisfying `requires-python`. See the repository README for the
 registry walkthroughs and safety details.
+See the [bootstrap, wrapper and credential guide](../docs/registry-setup.md) for branch/PR setup, dual npm names, registry policies and integration limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "package-registry-manager",
-  "version": "0.22.5",
+  "version": "0.22.7",
   "description": "Inspect repositories and guide secure package-registry setup",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
     "provenance": true
   },
   "scripts": {
-    "syntax": "node --check src/cli.mjs && node --check src/direct-execution.mjs && node --check src/index.mjs && node --check src/browser.mjs && node --check src/browser-options.mjs && node --check src/browser-catalogue.mjs && node --check src/automation.mjs && node --check src/webdriver-automation.mjs && node --check src/profile.mjs && node --check src/setup.mjs && node --check src/auth-urls.mjs && node --check src/containers.mjs && node --check src/flows.mjs && node --check src/prerequisites.mjs && node --check src/registry-state.mjs && node --check src/workflows.mjs && node --check src/publishers.mjs && node --check src/skips.mjs && node --check src/tokens.mjs && node --check src/approvals.mjs && node --check src/default-browser.mjs && node --check src/pages.mjs && node --check src/crates-api.mjs && node --check src/sign-in-import.mjs && node --check scripts/publish-to-npm.mjs && node --check scripts/setup-npm.mjs && node --check scripts/sanitize-npm-userconfig.mjs && node --check src/python.mjs && node --check src/setup-batch.mjs && node --check src/workflow-proposal.mjs",
+    "syntax": "node --check src/cli.mjs && node --check src/direct-execution.mjs && node --check src/index.mjs && node --check src/browser.mjs && node --check src/browser-options.mjs && node --check src/browser-catalogue.mjs && node --check src/automation.mjs && node --check src/webdriver-automation.mjs && node --check src/profile.mjs && node --check src/setup.mjs && node --check src/auth-urls.mjs && node --check src/containers.mjs && node --check src/flows.mjs && node --check src/prerequisites.mjs && node --check src/registry-state.mjs && node --check src/workflows.mjs && node --check src/publishers.mjs && node --check src/skips.mjs && node --check src/tokens.mjs && node --check src/approvals.mjs && node --check src/default-browser.mjs && node --check src/pages.mjs && node --check src/crates-api.mjs && node --check src/sign-in-import.mjs && node --check scripts/publish-to-npm.mjs && node --check scripts/setup-npm.mjs && node --check scripts/sanitize-npm-userconfig.mjs && node --check src/python.mjs && node --check src/setup-batch.mjs && node --check src/workflow-proposal.mjs && node --check src/repository-identity.mjs && node --check src/repository-repair.mjs && node --check src/manifest-proposal.mjs",
     "lint": "eslint src test scripts --max-warnings 0",
     "lint:fix": "eslint src test scripts --fix --max-warnings 0",
     "format": "prettier --write .",
@@ -40,8 +40,8 @@
     "audit": "node scripts/npm-audit.mjs"
   },
   "dependencies": {
-    "browser-commander": "^0.26.0",
-    "command-stream": "^1.6.2",
+    "browser-commander": "^0.26.3",
+    "command-stream": "^2.0.0",
     "playwright": "^1.63.0",
     "selenium-webdriver": "^4.50.0"
   },

package/src/bootstrap-reference.mjs

@@ -0,0 +1,76 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { inspectRepository } from "./discovery.mjs";
+
+/** Translate a branch, PR number, or GitHub pull-request URL into a fetch ref. */
+export function bootstrapRef(ref) {
+  const pull =
+    /^(?:https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/)?(\d+)$/.exec(ref);
+  const result = pull ? `refs/pull/${pull[1]}/head` : ref;
+  if (
+    !/^[\w][\w./-]*$/.test(result) ||
+    result.includes("..") ||
+    result.includes("//") ||
+    result.endsWith("/") ||
+    result.toLowerCase().endsWith(".lock")
+  ) {
+    throw new Error("invalid bootstrap ref");
+  }
+  return result;
+}
+
+/** Inspect a pushed ref in a disposable worktree without changing the checkout. */
+export async function inspectReference(repository, ref, options) {
+  const run = (args) => {
+    const result = spawnSync("git", args, {
+      cwd: repository,
+      encoding: "utf8",
+    });
+    if (result.status !== 0) {
+      throw new Error(`git failed while inspecting ref: ${result.stderr}`);
+    }
+    return result.stdout.trim();
+  };
+  const temporary = await mkdtemp(path.join(os.tmpdir(), "prm-ref-"));
+  const checkout = path.join(temporary, "checkout");
+  let created = false;
+  try {
+    run(["fetch", "origin", "HEAD"]);
+    const main = run(["rev-parse", "FETCH_HEAD"]);
+    run(["fetch", "origin", bootstrapRef(ref)]);
+    run(["worktree", "add", "--detach", checkout, "FETCH_HEAD"]);
+    created = true;
+    const inspection = await inspectRepository(checkout, options);
+    for (const item of inspection.packages.filter(
+      (item) => item.registry === "npm",
+    )) {
+      const result = spawnSync("git", ["show", `${main}:${item.manifest}`], {
+        cwd: repository,
+        encoding: "utf8",
+      });
+      let relationship = "manifest is absent from remote main";
+      if (result.status === 0) {
+        const data = JSON.parse(result.stdout);
+        relationship = `remote main is ${data.name}@${data.version}`;
+      }
+      item.warnings = [
+        ...(item.warnings ?? []),
+        `bootstrap ${item.name}@${item.version} from ${ref}; ${relationship}; the next main release must use an unpublished version`,
+      ];
+    }
+    inspection.repository.root = await import("node:fs/promises").then(
+      ({ realpath }) => realpath(repository),
+    );
+    return inspection;
+  } finally {
+    try {
+      if (created) {
+        run(["worktree", "remove", "--force", checkout]);
+      }
+    } finally {
+      await rm(temporary, { recursive: true, force: true });
+    }
+  }
+}

package/src/cli.mjs

@@ -9,6 +9,7 @@ import { parseArgs } from "node:util";
 import { launchChannels } from "./browser-catalogue.mjs";
 import { parseBrowserOptions } from "./browser-options.mjs";
 import { isDirectExecution } from "./direct-execution.mjs";
+import { inspectReference } from "./bootstrap-reference.mjs";
 import { inspectRepository } from "./discovery.mjs";
 import { parseRegistry } from "./model.mjs";
 import { buildPlans } from "./plan.mjs";
@@ -49,6 +50,7 @@ Plan and setup options:
   --add-publish-job                Propose missing publishing jobs in a draft PR;
                                   --workflow chooses its target file
   --environment <name>            GitHub environment of the trusted publisher
+  --ref <branch|pr>               Bootstrap a pushed branch or PR head before merge
   --package <name>                Plan only this package, or select it for
                                   setup when a registry has several
 
@@ -105,6 +107,7 @@ export async function main(args = process.argv.slice(2)) {
     allowPositionals: true,
     strict: true,
     options: {
+      ref: { type: "string" },
       repository: { type: "string", default: "." },
       format: { type: "string", default: "text" },
       verbose: { type: "boolean", default: false },
@@ -165,9 +168,11 @@ export async function main(args = process.argv.slice(2)) {
   });
 
   const repository = path.resolve(values.repository);
-  const discovered = await inspectRepository(repository, {
-    includeSkipped: values.verbose,
-  });
+  const discovered = values.ref
+    ? await inspectReference(repository, values.ref, {
+        includeSkipped: values.verbose,
+      })
+    : await inspectRepository(repository, { includeSkipped: values.verbose });
   const inspection = values.offline
     ? discovered
     : await probeRegistryState(discovered, { verbose: values.verbose });
@@ -198,6 +203,7 @@ export async function main(args = process.argv.slice(2)) {
     ),
   });
   const planOptions = {
+    ref: values.ref,
     verifyRelease: values["verify-release"],
     manual: values.manual,
     workflow: await workflowOverride(
@@ -414,6 +420,9 @@ function outputPlans(plans, format) {
   for (const plan of plans) {
     const mode = plan.mode ? ` (${plan.mode})` : "";
     process.stdout.write(`${plan.registry}: ${plan.package.name}${mode}\n`);
+    process.stdout.write(
+      `  credentials: ${plan.credential_policy.description}\n`,
+    );
     if (plan.mode === "complete") {
       process.stdout.write("  trusted publishing is already in use\n");
     }

package/src/containers.mjs

@@ -1,3 +1,5 @@
+import { tokenSecrets } from "./publishers.mjs";
+import { stripComments } from "./source-code.mjs";
 import { grantsPackagesWrite, publishingWorkflow } from "./workflows.mjs";
 
 export const CONTAINER_FILES = new Set(["Dockerfile", "Containerfile"]);
@@ -27,7 +29,8 @@ export function containerPackages(dockerfiles, workflows, coordinates) {
       continue;
     }
     const name =
-      literalImage(workflow.contents, host) ?? defaultImage(coordinates);
+      literalImage(stripComments(workflow.contents), host) ??
+      defaultImage(coordinates);
     const item = {
       registry,
       name: name ?? "unknown-image",
@@ -36,6 +39,10 @@ export function containerPackages(dockerfiles, workflows, coordinates) {
       publishable: Boolean(name),
       workflow: workflow.name,
     };
+    const secrets = tokenSecrets(workflows, registry);
+    if (secrets.length) {
+      item.token_secrets = [...new Set(secrets.map((secret) => secret.secret))];
+    }
     if (!name) {
       item.problems = [
         "the image name could not be derived from the workflow or a GitHub remote",

package/src/credential-browser.mjs

@@ -0,0 +1,82 @@
+/** Account pages used only in the dedicated automated browser. */
+export const TOKEN_PROVIDERS = Object.freeze({
+  "docker-hub": {
+    url: "https://app.docker.com/settings/personal-access-tokens/create",
+    secret: "DOCKERHUB_TOKEN",
+    scope: "Read & Write",
+    domains: ["docker.com", "docker.io"],
+  },
+  "maven-central": {
+    url: "https://central.sonatype.com/usertoken",
+    secret: "MAVEN_CENTRAL_TOKEN",
+    scope: "publish",
+    domains: ["sonatype.com"],
+  },
+  "vscode-marketplace": {
+    url: "https://dev.azure.com/_usersSettings/tokens",
+    secret: "VSCE_PAT",
+    scope: "Marketplace (Manage)",
+    domains: ["dev.azure.com", "login.microsoftonline.com"],
+  },
+  "open-vsx": {
+    url: "https://open-vsx.org/user-settings/tokens",
+    secret: "OVSX_PAT",
+    scope: "publish",
+    domains: ["open-vsx.org", "github.com"],
+  },
+  "chrome-web-store": {
+    url: "https://developers.google.com/oauthplayground/",
+    secret: "CHROME_WEB_STORE_REFRESH_TOKEN",
+    scope: "https://www.googleapis.com/auth/chromewebstore",
+    domains: ["google.com"],
+  },
+});
+
+/** Fill only credential name, publishing scope, repository and expiry. Never widen scope. */
+export function tokenFormScript(provider, name, expiresAt) {
+  return `(() => {
+    const values = ${JSON.stringify({ name, scope: provider.scope, expires: expiresAt.slice(0, 10) })};
+    const fields = { name: ['input[name="name"]', 'input[name="description"]', 'input[name="tokenName"]'], scope: ['select[name="scope"]', 'select[name="permissions"]'], expires: ['input[type="date"]', 'input[name="expires_at"]'] };
+    const filled = [];
+    for (const [key, selectors] of Object.entries(fields)) {
+      const field = selectors.map(selector => document.querySelector(selector)).find(Boolean);
+      if (!field) continue;
+      if (field.tagName === 'SELECT') {
+        const option = [...field.options].find(option => option.textContent.trim() === values[key] || option.value === values[key]);
+        if (!option) continue;
+        field.value = option.value;
+      } else field.value = values[key];
+      field.dispatchEvent(new Event('input', { bubbles: true }));
+      field.dispatchEvent(new Event('change', { bubbles: true }));
+      filled.push(key);
+    }
+    return { filled };
+  })()`;
+}
+
+/** Read the one-time value without returning it in any displayed diagnostic. */
+export const READ_TOKEN = `(() => {
+  const read = selectors => selectors.map(selector => document.querySelector(selector)).find(Boolean);
+  const value = read(['input[data-testid="token-value"]', 'input[name="token"]', 'textarea[name="token"]', '[data-testid="generated-token"]', 'input[name="refresh_token"]']);
+  const id = read(['[data-token-id]', 'input[name="token_id"]']);
+  const expires = read(['input[name="expires_at"]', '[data-expires-at]']);
+  const rawExpiry = expires?.value || expires?.dataset?.expiresAt;
+  const expiry = rawExpiry && /^\\d{4}-\\d{2}-\\d{2}$/.test(rawExpiry) ? rawExpiry + 'T00:00:00Z' : rawExpiry;
+  return { value: value?.value || value?.textContent?.trim(), id: id?.dataset?.tokenId || id?.value, expires_at: expiry };
+})()`;
+
+/** Verify absence only when the token list itself is visible and identifies rows. */
+export function revokedScript(id) {
+  if (typeof id !== "string" || id.length > 512) {
+    return "false";
+  }
+  const characters = Array.from(id);
+  if (characters.length === 0 || characters.length > 256) {
+    return "false";
+  }
+  // Only numeric literals enter generated code; registry text remains data.
+  const points = characters
+    .map((character) => character.codePointAt(0))
+    .join(",");
+  return `(() => { const id = String.fromCodePoint(${points}); const list = document.querySelector('[data-testid="tokens-list"], [data-token-list]'); if (!list) return false; return ![...list.querySelectorAll('[data-token-id]')].some(row => row.dataset.tokenId === id); })()`;
+}

package/src/credential-cycle.mjs

@@ -0,0 +1,91 @@
+/** Registry-specific policy; tokens are never a fallback for OIDC registries. */
+export function credentialPolicy(registry) {
+  if (
+    ["npm", "pypi", "crates-io", "rubygems", "nuget", "jsr"].includes(registry)
+  ) {
+    return {
+      mode: "trusted",
+      description: `${registry}: trusted publishing; remove unused long-lived tokens after verification`,
+    };
+  }
+  if (registry === "ghcr") {
+    return {
+      mode: "github-token",
+      description:
+        "ghcr: GITHUB_TOKEN with packages: write; no registry secret",
+    };
+  }
+  if (["go-modules", "packagist"].includes(registry)) {
+    return {
+      mode: "tags",
+      description: `${registry}: public repository tags; no publishing token secret`,
+    };
+  }
+  return {
+    mode: "token",
+    description: `${registry}: scoped expiring token; gh-manager stores selected-repository organization secrets by default`,
+  };
+}
+
+/** Unknown expiry also requires attention; GitHub cannot return secret values. */
+export function needsRotation(metadata, now = Date.now(), leadDays = 7) {
+  const expires = Date.parse(metadata.expires_at ?? "");
+  return (
+    metadata.present !== true ||
+    metadata.valid === false ||
+    !Number.isFinite(expires) ||
+    expires <= now + leadDays * 86_400_000
+  );
+}
+
+/** Provision, store, validate, then revoke. A failed validation preserves the old token. */
+export async function rotateCredential(previous, adapter) {
+  let created;
+  let stored = false;
+  try {
+    created = await adapter.create();
+    if (
+      !created.value ||
+      !created.id ||
+      !Number.isFinite(Date.parse(created.expires_at)) ||
+      Date.parse(created.expires_at) <= Date.now()
+    ) {
+      throw new Error("registry returned no usable expiring credential");
+    }
+    stored = true; // A failed ensure can have stored the secret before expiry metadata failed.
+    await adapter.store(created);
+    await adapter.verify();
+    if (previous.token_id && previous.token_id !== created.id) {
+      await adapter.revoke(previous.token_id);
+      if (!(await adapter.revoked(previous.token_id))) {
+        throw new Error("previous token revocation could not be verified");
+      }
+    }
+    return { token_id: created.id, expires_at: created.expires_at };
+  } catch (error) {
+    if (created?.id && (!stored || adapter.restore)) {
+      if (stored) {
+        await adapter.restore();
+      }
+      await adapter.revoke(created.id);
+    }
+    throw error;
+  } finally {
+    if (created) {
+      created.value = "";
+    }
+  }
+}
+
+/** Token-registry plan; setup obtains the value from its dedicated browser. */
+export function credentialSteps(registry, secret) {
+  return [
+    {
+      id: "manage-registry-token",
+      title: `Ensure and rotate ${secret}`,
+      kind: "api",
+      description: `${credentialPolicy(registry).description}. Check expiry and validity, create the narrowest publishing credential in the browser, store through gh-manager stdin, verify in a dry-run workflow, then revoke and verify the replaced token. Requires gh-manager secret support and a configured verification workflow.`,
+      confirm: true,
+    },
+  ];
+}

package/src/credential-setup.mjs

@@ -0,0 +1,210 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { verifyCredentialWorkflow } from "./credential-verification.mjs";
+import { needsRotation, rotateCredential } from "./credential-cycle.mjs";
+import {
+  TOKEN_PROVIDERS,
+  tokenFormScript,
+  READ_TOKEN,
+  revokedScript,
+} from "./credential-browser.mjs";
+
+/** Exact argv and stdin transport. Suppress all output from secret mutations. */
+export function secretCommand(args, input, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("gh-manager", args, {
+      cwd,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let output = "";
+    child.stdout.on("data", (chunk) => {
+      if (input === undefined) {
+        output += chunk;
+      }
+    });
+    child.stderr.on("data", () => {});
+    child.on("error", () =>
+      reject(
+        new Error(
+          "gh-manager with secret get-metadata/ensure support is required (gh-manager#6)",
+        ),
+      ),
+    );
+    child.stdin.on("error", () => {});
+    child.on("close", (code) =>
+      code === 0
+        ? resolve(output)
+        : reject(
+            new Error(
+              "gh-manager secret operation failed; verify installation, permissions and secret support (gh-manager#6)",
+            ),
+          ),
+    );
+    child.stdin.end(input ?? "");
+  });
+}
+
+/** Execute the token lifecycle without putting values in argv, diagnostics or files. */
+export async function setupCredential(session) {
+  const { plan, options } = session;
+  const provider = TOKEN_PROVIDERS[plan.registry];
+  if (!provider) {
+    throw new Error(`no token provider for ${plan.registry}`);
+  }
+  const contents = await readFile(
+    path.join(options.repository, ".package-registry-manager.json"),
+    "utf8",
+  ).catch((error) => {
+    if (error.code === "ENOENT") {
+      return "{}";
+    }
+    throw error;
+  });
+  const settings = JSON.parse(contents).tokens?.[plan.registry] ?? {};
+  if (!/^[\w.-]+\.ya?ml$/.test(settings.verification_workflow ?? "")) {
+    throw new Error(
+      "configure tokens.<registry>.verification_workflow for a reviewed dry-run login workflow before creating credentials",
+    );
+  }
+  const { github_owner: owner, github_repository: repository } =
+    plan.repository;
+  if (!owner || !repository) {
+    throw new Error("token setup requires GitHub repository coordinates");
+  }
+  const secret =
+    settings.secret ?? plan.package.token_secrets?.[0] ?? provider.secret;
+  if (!/^[A-Z][A-Z0-9_]*$/.test(secret)) {
+    throw new Error("invalid registry secret name");
+  }
+  if (settings.level && !["repo", "org"].includes(settings.level)) {
+    throw new Error("token secret level must be repo or org");
+  }
+  const scope =
+    settings.level === "repo"
+      ? ["--repo", `${owner}/${repository}`]
+      : ["--org", owner];
+  const visibility =
+    settings.level === "repo"
+      ? []
+      : ["--visibility", "selected", "--repos", `${owner}/${repository}`];
+  const workflow = await readFile(
+    path.join(
+      options.repository,
+      ".github/workflows",
+      settings.verification_workflow,
+    ),
+    "utf8",
+  );
+  if (
+    !workflow.includes("workflow_dispatch") ||
+    !workflow.includes("inputs.prm_nonce") ||
+    !workflow.includes("run-name:")
+  ) {
+    throw new Error(
+      "verification workflow requires workflow_dispatch input prm_nonce and run-name containing inputs.prm_nonce",
+    );
+  }
+  const days = settings.expiry_days ?? 30;
+  if (!Number.isInteger(days) || days < 1 || days > 90) {
+    throw new Error("token expiry_days must be between 1 and 90");
+  }
+  if (options.noBrowser) {
+    throw new Error(
+      "registry token creation requires the dedicated automated browser",
+    );
+  }
+  if (
+    options.browserOptions?.attach ||
+    options.browserOptions?.importScope === "full"
+  ) {
+    throw new Error(
+      "token setup requires a dedicated profile with domain-scoped sign-in import",
+    );
+  }
+  const run = options.secretCommand ?? secretCommand;
+  const previous = JSON.parse(
+    await run(
+      ["secret", "get-metadata", secret, ...scope, "--json"],
+      undefined,
+      options.repository,
+    ),
+  );
+  const verify = () =>
+    verifyCredentialWorkflow(session, settings.verification_workflow);
+  if (!needsRotation(previous)) {
+    try {
+      await verify();
+      return;
+    } catch {
+      previous.valid = false;
+    }
+  }
+  if (
+    !options.yes &&
+    !/^y(?:es)?$/i.test(
+      await session.prompt(
+        "Create and store a scoped credential, verify it, then revoke the replaced token? [y/N] ",
+      ),
+    )
+  ) {
+    throw new Error("credential creation declined");
+  }
+  if (session.automation) {
+    await session.automation.close();
+  }
+  session.automation = null;
+  const page = await session.automatedPage(
+    { ...options.browserOptions, importScope: "domains" },
+    true,
+  );
+  const expiry = new Date(Date.now() + days * 86_400_000).toISOString();
+  await rotateCredential(previous, {
+    create: async () => {
+      await page.goto(provider.url);
+      await session.prompt(
+        `Sign in, then press Enter to fill the narrow publishing scope (${provider.scope})...`,
+      );
+      await page.evaluate(
+        tokenFormScript(provider, `prm-${repository}`, expiry),
+      );
+      await session.prompt(
+        `Review the scope and expiry, create the token in this browser, then press Enter (never paste its value)...`,
+      );
+      const credential = await page.evaluate(READ_TOKEN);
+      if (!credential.expires_at) {
+        throw new Error(
+          "registry did not provide a verifiable expiry; no secret was stored",
+        );
+      }
+      return credential;
+    },
+    store: (credential) =>
+      run(
+        [
+          "secret",
+          "ensure",
+          secret,
+          ...scope,
+          ...visibility,
+          "--expires-at",
+          credential.expires_at,
+          "--token-id",
+          credential.id,
+          "--registry",
+          plan.registry,
+        ],
+        credential.value,
+        options.repository,
+      ),
+    verify,
+    revoke: async (id) => {
+      await page.goto(provider.url.replace(/\/create$/, ""));
+      await session.prompt(
+        `Revoke registry token ${id} in this browser, then press Enter...`,
+      );
+    },
+    revoked: async (id) => page.evaluate(revokedScript(id)),
+  });
+  console.log("  Credential verified; replaced token revocation verified.");
+}

package/src/credential-verification.mjs

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+
+/** Correlate dispatch by a unique run-name input, never by the latest unrelated run. */
+export async function verifyCredentialWorkflow(session, workflow) {
+  const { github_owner: owner, github_repository: repository } =
+    session.plan.repository;
+  const repo = `${owner}/${repository}`;
+  const capture = async (args) => {
+    const result = await session.capture({
+      id: "verify-registry-login",
+      command: { program: "gh", args },
+      cwd: ".",
+    });
+    if (result.code !== 0) {
+      throw new Error(
+        "credential verification command failed; old token remains active",
+      );
+    }
+    return String(result.stdout);
+  };
+  const metadata = JSON.parse(
+    await capture(["repo", "view", repo, "--json", "defaultBranchRef"]),
+  );
+  const ref = metadata.defaultBranchRef?.name;
+  if (!ref) {
+    throw new Error("cannot determine verification workflow branch");
+  }
+  const nonce = session.options.verificationNonce ?? randomUUID();
+  await capture([
+    "workflow",
+    "run",
+    workflow,
+    "--repo",
+    repo,
+    "--ref",
+    ref,
+    "-f",
+    `prm_nonce=${nonce}`,
+  ]);
+  const deadline =
+    Date.now() + (session.options.verificationTimeoutMs ?? 300_000);
+  let runId;
+  while (Date.now() < deadline) {
+    if (!runId) {
+      const runs = JSON.parse(
+        await capture([
+          "run",
+          "list",
+          "--repo",
+          repo,
+          "--workflow",
+          workflow,
+          "--event",
+          "workflow_dispatch",
+          "--limit",
+          "50",
+          "--json",
+          "databaseId,displayTitle",
+        ]),
+      );
+      const matching = runs.filter((run) => run.displayTitle?.includes(nonce));
+      if (matching.length > 1) {
+        throw new Error(
+          "ambiguous credential verification runs; old token remains active",
+        );
+      }
+      runId = matching[0]?.databaseId;
+    }
+    if (runId) {
+      const run = JSON.parse(
+        await capture([
+          "run",
+          "view",
+          String(runId),
+          "--repo",
+          repo,
+          "--json",
+          "status,conclusion",
+        ]),
+      );
+      if (run.status === "completed") {
+        if (run.conclusion !== "success") {
+          throw new Error(
+            "registry rejected credential verification; old token remains active",
+          );
+        }
+        return;
+      }
+    }
+    await (session.options.verificationDelay ?? delay)(2000);
+  }
+  throw new Error(
+    "credential verification timed out; old token remains active",
+  );
+}