@davidvornholt/standards 0.19.0 → 0.21.0

package/src/creds-login-github.ts

@@ -1,15 +1,20 @@
 import { randomBytes } from 'node:crypto';
 import { openInBrowser } from './creds-browser';
+import {
+  loadOwnedGithubStore,
+  sameGithubApp,
+  upsertGithubApp,
+} from './creds-github-apps';
 import {
   buildAppManifest,
   convertManifestCode,
   createManifestState,
   MANIFEST_STATE_BYTES,
   manifestFormHtml,
+  resolveGithubAppName,
 } from './creds-login-github-manifest';
-import { BROKER_IDENTITY_NAME } from './creds-naming';
 import {
-  readBrokerStore,
+  type GithubBrokerApp,
   resolveBrokerPath,
   updateBrokerStore,
 } from './creds-store';
@@ -84,50 +89,99 @@ export const waitForCode = (
 };
 export const githubInstallMessage = (installUrl: string): string =>
   `Install it only on the selected repositories that need broker credentials: ${installUrl}`;
-export const runCredsLoginGithub = async (options: {
-  readonly name: string | undefined;
-  readonly org: string | undefined;
-}): Promise<boolean> => {
+
+type GithubLoginDependencies = {
+  readonly waitForCode: typeof waitForCode;
+  readonly convertManifestCode: typeof convertManifestCode;
+  readonly openInBrowser: typeof openInBrowser;
+};
+
+const DEFAULT_LOGIN_DEPENDENCIES: GithubLoginDependencies = {
+  waitForCode,
+  convertManifestCode,
+  openInBrowser,
+};
+
+export const runCredsLoginGithub = async (
+  options: {
+    readonly name: string | undefined;
+    readonly org: string | undefined;
+  },
+  dependencies: GithubLoginDependencies = DEFAULT_LOGIN_DEPENDENCIES,
+): Promise<boolean> => {
+  const resolvedName = resolveGithubAppName(options.name, options.org);
+  if (!resolvedName.ok) {
+    console.error(`standards creds: ${resolvedName.problem}`);
+    return false;
+  }
   const storePath = resolveBrokerPath();
-  const store = await readBrokerStore(storePath);
-  if (store.github !== null) {
-    console.error(
-      `standards creds: a broker GitHub App is already configured (${store.github.htmlUrl}); remove the "github" section from ${storePath} to re-run login`,
-    );
+  const loaded = await loadOwnedGithubStore(storePath);
+  if (!loaded.ok) {
+    console.error(`standards creds: ${loaded.problem}`);
     return false;
   }
   const action =
     options.org === undefined
       ? 'https://github.com/settings/apps/new'
       : `https://github.com/organizations/${options.org}/settings/apps/new`;
-  const name = options.name ?? BROKER_IDENTITY_NAME;
-  const code = await waitForCode((port, state) =>
+  const code = await dependencies.waitForCode((port, state) =>
     manifestFormHtml(
       action,
       JSON.stringify(
-        buildAppManifest(name, `http://127.0.0.1:${port}/callback`),
+        buildAppManifest(
+          resolvedName.value,
+          `http://127.0.0.1:${port}/callback`,
+        ),
       ),
       state,
     ),
   );
-  const conversion = await convertManifestCode(code);
+  const conversion = await dependencies.convertManifestCode(code);
   if (!conversion.ok) {
     console.error(`standards creds: ${conversion.problem}`);
     return false;
   }
   const { app } = conversion;
-  await updateBrokerStore(storePath, (current) => {
-    if (current.github !== null) {
-      throw new Error(
-        `a broker GitHub App was configured while login was in progress (${current.github.htmlUrl}); the newly created App ${app.htmlUrl} was not stored and should be deleted`,
+  const observed = loaded.value.github.find(
+    (entry) => entry.owner?.toLowerCase() === app.owner?.toLowerCase(),
+  );
+  let replaced: GithubBrokerApp | undefined;
+  try {
+    await updateBrokerStore(storePath, (current) => {
+      const currentEntry = current.github.find(
+        (entry) => entry.owner?.toLowerCase() === app.owner?.toLowerCase(),
       );
-    }
-    return { ...current, github: app };
-  });
-  console.log(`standards creds: created App ${app.slug} (${app.htmlUrl})`);
+      const unchanged =
+        observed === undefined
+          ? currentEntry === undefined
+          : currentEntry !== undefined && sameGithubApp(currentEntry, observed);
+      if (!unchanged) {
+        throw new Error(
+          `the broker App for ${app.owner} changed while this App was being created`,
+        );
+      }
+      const upserted = upsertGithubApp(current.github, app);
+      replaced = upserted.replaced ?? undefined;
+      return { ...current, github: upserted.apps };
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(
+      `standards creds: the newly created App ${app.htmlUrl} was not stored (${message}); retry login, and delete the new App if it is still absent from \`creds status\``,
+    );
+    return false;
+  }
+  console.log(
+    `standards creds: created App ${app.slug} for ${app.owner} (${app.htmlUrl})`,
+  );
   console.log(`  credentials stored in ${storePath}`);
+  if (replaced !== undefined) {
+    console.log(
+      `  replaced App ${replaced.slug} for ${app.owner}; update its SOPS destinations, verify token minting, then delete the old App`,
+    );
+  }
   const installUrl = `${app.htmlUrl}/installations/new`;
   console.log(githubInstallMessage(installUrl));
-  openInBrowser(installUrl);
+  dependencies.openInBrowser(installUrl);
   return true;
 };

package/src/creds-naming.ts

@@ -80,3 +80,16 @@ export const parseTokenName = (
   }
   return ref;
 };
+
+// The repository a minted name belongs to is carried by the name itself, so a
+// command holding no repository — `creds revoke` is account-scoped — can still
+// tell a token reconciliation owns from one nothing manages.
+export const parseAnyTokenName = (name: string): BrokeredTokenRef | null => {
+  if (!isInMintedNamespace(name)) {
+    return null;
+  }
+  const [owner, repo] = name.slice(`${NAME_PREFIX}/`.length).split('/');
+  return owner === undefined || repo === undefined
+    ? null
+    : parseTokenName(name, `${owner}/${repo}`);
+};

package/src/creds-plan-renew.ts

@@ -7,11 +7,8 @@ import { createAccountToken, deleteAccountToken } from './creds-cloudflare';
 import { resolveTargetRel } from './creds-dest';
 import type { PlannedAction } from './creds-plan-types';
 import { destinationWrites, s3AccessKeyPath, s3PairPaths } from './creds-r2';
-import {
-  inspectSopsScalarDestination,
-  setSopsValues,
-  verifySopsStoredValue,
-} from './creds-sops';
+import { inspectSopsScalarDestination, setSopsValues } from './creds-sops';
+import { verifySopsStoredValue } from './creds-sops-value';
 import type { CloudflareBrokerAccount } from './creds-store';
 
 type RenewAction = Extract<PlannedAction, { readonly kind: 'renew' }>;

package/src/creds-plan-report.ts

@@ -0,0 +1,87 @@
+// The operator-facing rendering of a computed plan. Every block is labelled and
+// printed only when it has entries, because the three lists say different
+// things: what reconciliation will do, what it will never touch, and what no
+// repository reconciles at all. The summary counts them apart for the same
+// reason.
+
+import { BROKER_IDENTITY_NAME } from './creds-naming';
+import type {
+  BrokeredElsewhereToken,
+  CredsPlan,
+  PlannedAction,
+  UnmanagedToken,
+} from './creds-plan-types';
+
+// Each listed token is offered with the exact command that retires it rather
+// than with identifiers to reassemble: `plan` already holds the account, and
+// `revoke` demands it whenever the broker holds more than one.
+const revokeCommand = (token: UnmanagedToken, extra: string): string =>
+  `\`standards creds revoke --account ${token.accountId} --token-id ${token.tokenId}${extra}\``;
+
+// One unmanaged shape has no revoke command to offer: the reserved bootstrap
+// name. This machine's own bootstrap is excluded from the listing by verified
+// ID, so a row under that name is another machine's or a superseded one, and
+// `revoke` refuses it by name — printing a command that always fails would
+// send the operator down a dead end. The remedy is the dashboard, which is
+// also the only place the machine it belongs to can be confirmed.
+const unmanagedRemedy = (token: UnmanagedToken): string =>
+  token.name === BROKER_IDENTITY_NAME
+    ? "the reserved name for a machine's broker bootstrap credential, which `revoke` refuses; retire it in the Cloudflare dashboard, where you can confirm which machine it belongs to"
+    : `retire it with ${revokeCommand(token, '')}`;
+
+const reportActions = (
+  actions: ReadonlyArray<PlannedAction>,
+  apply: boolean,
+): void => {
+  if (actions.length === 0) {
+    return;
+  }
+  console.log(`standards creds: ${apply ? '' : 'planned '}actions`);
+  for (const action of actions) {
+    console.log(
+      `  ${apply ? '' : 'would '}${action.kind} ${action.name} (${action.reason})`,
+    );
+  }
+};
+
+const reportUnmanaged = (tokens: ReadonlyArray<UnmanagedToken>): void => {
+  if (tokens.length === 0) {
+    return;
+  }
+  console.log(
+    'standards creds: unmanaged tokens — reconciliation mints nothing of this shape, and plan and apply never mutate them',
+  );
+  for (const token of tokens) {
+    console.log(
+      `  ${token.name} (${token.status}) — ${unmanagedRemedy(token)}`,
+    );
+  }
+};
+
+const reportBrokeredElsewhere = (
+  tokens: ReadonlyArray<BrokeredElsewhereToken>,
+): void => {
+  if (tokens.length === 0) {
+    return;
+  }
+  console.log(
+    'standards creds: tokens brokered to another repository — never mutated here, and reconciled there only if a checkout still mints that exact name',
+  );
+  for (const token of tokens) {
+    console.log(
+      `  ${token.name} (${token.status}) — brokered to ${token.repo}; if no checkout mints this name any more — ${token.repo} renamed, transferred, or deleted — then nothing reconciles the token, and only then: ${revokeCommand(token, ' --force')}`,
+    );
+  }
+};
+
+export const reportCredsPlan = (plan: CredsPlan, apply: boolean): void => {
+  reportActions(plan.actions, apply);
+  reportUnmanaged(plan.unmanaged);
+  reportBrokeredElsewhere(plan.brokeredElsewhere);
+  for (const finding of plan.findings) {
+    console.error(`standards creds: ${finding}`);
+  }
+  console.log(
+    `standards creds: ${plan.actions.length} action(s), ${plan.findings.length} finding(s), ${plan.healthy} brokered token(s) healthy, ${plan.unmanaged.length} unmanaged token(s), ${plan.brokeredElsewhere.length} token(s) brokered to another repository`,
+  );
+};

package/src/creds-plan-run.ts

@@ -2,6 +2,7 @@ import { listSecretsTargets } from './creds-dest';
 import { identifyCloudflareBootstrapAuthority } from './creds-login-cloudflare';
 import { computeCredsPlan } from './creds-plan';
 import { renewPlannedToken } from './creds-plan-renew';
+import { reportCredsPlan } from './creds-plan-report';
 import { revokePlannedToken } from './creds-plan-revoke';
 import type { AccountToken, PlannedAction } from './creds-plan-types';
 import { readEncryptedKeys } from './creds-sops';
@@ -109,17 +110,7 @@ export const runCredsPlan = async (
     tokens: state.tokens,
     now: new Date(),
   });
-  for (const action of plan.actions) {
-    console.log(
-      `  ${apply ? '' : 'would '}${action.kind} ${action.name} (${action.reason})`,
-    );
-  }
-  for (const finding of plan.findings) {
-    console.error(`standards creds: ${finding}`);
-  }
-  console.log(
-    `standards creds: ${plan.actions.length} action(s), ${plan.findings.length} finding(s), ${plan.healthy} brokered token(s) healthy`,
-  );
+  reportCredsPlan(plan, apply);
   if (plan.findings.length > 0) {
     return fail('reconciliation aborted until every finding is resolved');
   }

package/src/creds-plan-types.ts

@@ -7,6 +7,21 @@ export type AccountToken = {
   readonly token: CloudflareToken;
 };
 
+export type UnmanagedToken = {
+  readonly accountId: string;
+  readonly tokenId: string;
+  readonly name: string;
+  readonly status: string;
+};
+
+// A token the broker minted under another repository's name. That repository
+// normally reconciles it, so it is not unmanaged — the distinction matters
+// because it stops being true when that repository is renamed, transferred, or
+// deleted, and this account is then the only place the token is still visible.
+export type BrokeredElsewhereToken = UnmanagedToken & {
+  readonly repo: string;
+};
+
 export type PlannedAction =
   | {
       readonly kind: 'revoke';
@@ -33,4 +48,8 @@ export type CredsPlan = {
   readonly actions: ReadonlyArray<PlannedAction>;
   readonly findings: ReadonlyArray<string>;
   readonly healthy: number;
+  // Tokens in the account the broker did not mint. Reported, never mutated.
+  readonly unmanaged: ReadonlyArray<UnmanagedToken>;
+  // Tokens the broker minted for another repository. Reported, never mutated.
+  readonly brokeredElsewhere: ReadonlyArray<BrokeredElsewhereToken>;
 };

package/src/creds-plan-unmanaged.ts

@@ -0,0 +1,102 @@
+// Reconciliation matches tokens to a repository by name and used to discard
+// every other token in the account silently. That silence is where a forgotten
+// credential hides: replacing a hand-made token means minting a brokered one
+// and deleting the original, and nothing noticed when the second half was
+// skipped. Classification makes the leftovers visible without giving the broker
+// any power over them — a token named here is never mutated automatically.
+
+import type { CloudflareToken } from './creds-cloudflare-api';
+import {
+  type BrokeredTokenRef,
+  isInMintedNamespace,
+  parseAnyTokenName,
+  parseTokenName,
+  repoTokenPrefix,
+} from './creds-naming';
+import type {
+  AccountToken,
+  BrokeredElsewhereToken,
+  UnmanagedToken,
+} from './creds-plan-types';
+
+type Classification =
+  | { readonly kind: 'managed'; readonly ref: BrokeredTokenRef }
+  | { readonly kind: 'malformed' }
+  | { readonly kind: 'unmanaged' }
+  | { readonly kind: 'brokered-elsewhere'; readonly repo: string }
+  | { readonly kind: 'ignored' };
+
+const classifyAccountToken = (
+  token: CloudflareToken,
+  repo: string,
+): Classification => {
+  const ref = parseTokenName(token.name, repo);
+  if (ref !== null) {
+    return { kind: 'managed', ref };
+  }
+  // An expired token grants nothing, and listing years of them would bury the
+  // live ones. Brokered tokens keep their own expiry handling in creds-plan.
+  if (token.status === 'expired') {
+    return { kind: 'ignored' };
+  }
+  if (token.name.startsWith(repoTokenPrefix(repo))) {
+    return { kind: 'malformed' };
+  }
+  // A brokered name carries the repository that owns it, which normally
+  // reconciles it. That premise fails exactly once: rename, transfer, or delete
+  // that repository and no checkout resolves to the old name, so nothing renews
+  // the token, nothing revokes it, and no repository would ever mention it.
+  // Every account sharer reporting it is the price of the orphan being seen at
+  // all. It stays out of the unmanaged bucket, which asserts something else —
+  // that the broker mints nothing of this shape anywhere.
+  const elsewhere = parseAnyTokenName(token.name);
+  if (elsewhere !== null) {
+    return { kind: 'brokered-elsewhere', repo: elsewhere.repo };
+  }
+  return isInMintedNamespace(token.name)
+    ? { kind: 'ignored' }
+    : { kind: 'unmanaged' };
+};
+
+export type ManagedTokenRef = AccountToken & {
+  readonly ref: BrokeredTokenRef;
+};
+
+export type TokenPartition = {
+  readonly managed: ReadonlyArray<ManagedTokenRef>;
+  readonly unmanaged: ReadonlyArray<UnmanagedToken>;
+  readonly brokeredElsewhere: ReadonlyArray<BrokeredElsewhereToken>;
+  readonly findings: ReadonlyArray<string>;
+};
+
+const reported = (entry: AccountToken): UnmanagedToken => ({
+  accountId: entry.accountId,
+  tokenId: entry.token.id,
+  name: entry.token.name,
+  status: entry.token.status,
+});
+
+export const partitionAccountTokens = (
+  tokens: ReadonlyArray<AccountToken>,
+  repo: string,
+): TokenPartition => {
+  const managed: Array<ManagedTokenRef> = [];
+  const unmanaged: Array<UnmanagedToken> = [];
+  const brokeredElsewhere: Array<BrokeredElsewhereToken> = [];
+  const findings: Array<string> = [];
+  for (const entry of tokens) {
+    const classification = classifyAccountToken(entry.token, repo);
+    if (classification.kind === 'managed') {
+      managed.push({ ...entry, ref: classification.ref });
+    } else if (classification.kind === 'malformed') {
+      findings.push(
+        `${entry.token.name} claims this repository's brokered namespace but is not a name this broker mints; rename it in the dashboard or retire it with \`standards creds revoke --account ${entry.accountId} --token-id ${entry.token.id}\``,
+      );
+    } else if (classification.kind === 'unmanaged') {
+      unmanaged.push(reported(entry));
+    } else if (classification.kind === 'brokered-elsewhere') {
+      brokeredElsewhere.push({ ...reported(entry), repo: classification.repo });
+    }
+  }
+  return { managed, unmanaged, brokeredElsewhere, findings };
+};

package/src/creds-plan.ts

@@ -3,23 +3,28 @@
 // naming scheme). A brokered token whose secret key vanished from SOPS is
 // revoked; one nearing expiry is replaced while copying its live policy and
 // lifetime. Secret keys without a brokered token are simply unmanaged — most
-// secrets are — and are never touched. Execution lives in creds-plan-run.ts.
+// secrets are — and are never touched. Tokens the broker did not mint, and
+// tokens it minted for another repository, are reported
+// (creds-plan-unmanaged.ts) but never mutated. Execution lives in
+// creds-plan-run.ts.
 
 import { cloudflareExpiresOn } from './creds-cloudflare-expiry';
-import { parseTokenName } from './creds-naming';
 import { groupByIntersectingFootprint } from './creds-plan-groups';
 import type {
   AccountToken,
   CredsPlan,
   PlannedAction,
 } from './creds-plan-types';
+import {
+  type ManagedTokenRef,
+  partitionAccountTokens,
+} from './creds-plan-unmanaged';
 import { destinationFormatOf, inferredDestinationFootprint } from './creds-r2';
 
 const DEFAULT_RENEW_WITHIN_DAYS = 30;
 const DAY_MS = 86_400_000;
 
-type ManagedToken = AccountToken & {
-  readonly ref: { readonly target: string; readonly key: string };
+type ManagedToken = ManagedTokenRef & {
   readonly footprint: ReadonlyArray<string>;
 };
 
@@ -145,23 +150,16 @@ export const computeCredsPlan = (input: {
   const renewWithin =
     (input.renewWithinDays ?? DEFAULT_RENEW_WITHIN_DAYS) * DAY_MS;
   const actions: Array<PlannedAction> = [];
-  const findings: Array<string> = [];
+  const partition = partitionAccountTokens(input.tokens, input.repo);
+  const findings: Array<string> = [...partition.findings];
   let healthy = 0;
-  const managed = input.tokens.flatMap((entry) => {
-    const ref = parseTokenName(entry.token.name, input.repo);
-    return ref === null
-      ? []
-      : [
-          {
-            ...entry,
-            ref,
-            footprint: inferredDestinationFootprint(
-              input.keysByTarget.get(ref.target),
-              ref.key,
-            ),
-          },
-        ];
-  });
+  const managed = partition.managed.map((entry) => ({
+    ...entry,
+    footprint: inferredDestinationFootprint(
+      input.keysByTarget.get(entry.ref.target),
+      entry.ref.key,
+    ),
+  }));
   const dispositions = groupByIntersectingFootprint(managed).map((group) =>
     dispositionForGroup(group, input, renewWithin),
   );
@@ -174,5 +172,11 @@ export const computeCredsPlan = (input: {
       healthy += 1;
     }
   }
-  return { actions, findings, healthy };
+  return {
+    actions,
+    findings,
+    healthy,
+    unmanaged: partition.unmanaged,
+    brokeredElsewhere: partition.brokeredElsewhere,
+  };
 };

package/src/creds-revoke.ts

@@ -0,0 +1,162 @@
+// One-shot retirement of a Cloudflare token the broker does not manage, named
+// explicitly by ID. Replacing a hand-made credential means minting a brokered
+// one and deleting the original; without this the second half could only be
+// done in the dashboard. The power granted is deliberately momentary: nothing
+// is recorded, nothing becomes automatic, and a human names the target every
+// time. Tokens reconciliation owns are refused — those are retired by deleting
+// their SOPS key and running `standards creds apply`, which keeps the secret
+// and the provider in step.
+
+import { deleteAccountToken } from './creds-cloudflare';
+import { isCloudflareId } from './creds-cloudflare-id';
+import { selectAccount } from './creds-dest';
+import { identifyCloudflareBootstrapAuthority } from './creds-login-cloudflare';
+import {
+  BROKER_IDENTITY_NAME,
+  type BrokeredTokenRef,
+  parseAnyTokenName,
+} from './creds-naming';
+import { readBrokerStore, resolveBrokerPath } from './creds-store';
+import { resolveGithubRepo } from './github-api';
+
+const fail = (message: string): false => {
+  console.error(`standards creds: ${message}`);
+  return false;
+};
+
+// GitHub owner and repository names are case-insensitive, so a checkout cloned
+// as `DavidVornholt/Example` owns the token minted as `davidvornholt/example`.
+// An exact comparison would call that token foreign and let --force delete a
+// live credential this very checkout reconciles. Owner and name are compared
+// together: `otherowner/example` shares this repository's name and nothing
+// else.
+const sameRepo = (left: string, right: string): boolean =>
+  left.toLowerCase() === right.toLowerCase();
+
+// A brokered name carries the repository that owns it, and the reconciled
+// remedy — delete the SOPS key, run `apply` — only works in that repository.
+// Naming a bare `<target>:<key>` to an operator standing somewhere else would
+// have them destroy their own live credential of the same name, so the owning
+// repository is always named and the remedy is placed where it runs.
+const brokeredRefusal = ({
+  tokenId,
+  name,
+  brokered,
+  currentRepo,
+  force,
+}: {
+  readonly tokenId: string;
+  readonly name: string;
+  readonly brokered: BrokeredTokenRef;
+  readonly currentRepo: string | null;
+  readonly force: boolean;
+}): string | null => {
+  // Without a repository here, the one thing --force claims to override — that
+  // this checkout is not the owner — is the thing that could not be checked,
+  // so the override is refused rather than granted on an unevaluated guard.
+  if (currentRepo === null) {
+    return `token ${tokenId} is brokered as ${name}, which belongs to ${brokered.repo}, and this checkout cannot resolve the GitHub repository from its origin remote, so whether this checkout owns the token could not be determined; --force widens only that ownership check, so here it has nothing to widen. Re-run from a checkout whose origin remote names a GitHub repository, or point --dir at one. If ${brokered.repo} still exists, the remedy runs there: delete ${brokered.target}:${brokered.key} from its SOPS target and run \`standards creds apply\` in that checkout`;
+  }
+  if (brokered.repo === currentRepo) {
+    return `token ${tokenId} is brokered as ${name} for this repository (${brokered.repo}); delete ${brokered.target}:${brokered.key} from this repository's SOPS target and run \`standards creds apply\`, which revokes it and keeps the secret in step`;
+  }
+  // Revoke compares repository names case-insensitively, but reconciliation
+  // matches the token name exactly, so a checkout whose origin differs only in
+  // capitalisation renews nothing and revokes nothing. Sending the operator to
+  // the reconciled remedy would prescribe a no-op.
+  if (sameRepo(brokered.repo, currentRepo)) {
+    return `token ${tokenId} is brokered as ${name}, and this checkout's origin names ${currentRepo}, which differs from ${brokered.repo} only in capitalisation; reconciliation matches the token name exactly, so from here it will neither renew nor revoke this token. Re-point the origin remote at ${brokered.repo} to bring the token back under reconciliation, or retire it in the Cloudflare dashboard`;
+  }
+  if (force) {
+    return null;
+  }
+  return `token ${tokenId} is brokered as ${name}, which belongs to ${brokered.repo}, and this checkout is ${currentRepo}; the remedy runs there: delete ${brokered.target}:${brokered.key} from ${brokered.repo}'s SOPS target and run \`standards creds apply\` in that checkout. Pass --force only if ${brokered.repo} was renamed, transferred, or deleted, so no checkout resolves to that name and no apply will ever revoke this token`;
+};
+
+export const runCredsRevoke = async (options: {
+  readonly account: string | undefined;
+  readonly tokenId: string | undefined;
+  readonly dir: string;
+  readonly force: boolean;
+}): Promise<boolean> => {
+  const { tokenId } = options;
+  if (tokenId === undefined) {
+    return fail(
+      'revoke requires --token-id <id>; `standards creds plan` prints the ID inside every revoke command it offers, and the Cloudflare dashboard has the ID of anything that listing leaves out',
+    );
+  }
+  if (!isCloudflareId(tokenId)) {
+    return fail(
+      `not a token ID: ${tokenId}; --token-id takes the 32-character hexadecimal token ID`,
+    );
+  }
+  const store = await readBrokerStore(resolveBrokerPath());
+  const account = selectAccount(store, options.account);
+  if (account === null) {
+    return false;
+  }
+  const identified = await identifyCloudflareBootstrapAuthority(
+    account.accountId,
+    account.token,
+  );
+  if (!identified.ok) {
+    return fail(`account ${account.accountId}: ${identified.problem}`);
+  }
+  // The bootstrap token is matched by its verified ID rather than its name,
+  // because deleting it would strip the broker of every power it has and no
+  // rename should be able to disguise it.
+  if (identified.value.id === tokenId) {
+    return fail(
+      `token ${tokenId} is this account's broker bootstrap credential; revoking it would leave the broker unable to mint or reconcile anything`,
+    );
+  }
+  const target = identified.value.tokens.find((entry) => entry.id === tokenId);
+  if (target === undefined) {
+    return fail(
+      `no token ${tokenId} in account ${account.accountId}; revoke names a token in the account the bootstrap credential belongs to`,
+    );
+  }
+  // The broker store is machine-global and `creds login` is a per-machine
+  // bootstrap, so one account can hold several tokens under the reserved name
+  // — one per machine. Only this machine's is identified by ID above; the rest
+  // are refused by name, because deleting one locks another machine out of the
+  // account and the broker cannot re-mint its own root credential.
+  if (target.name === BROKER_IDENTITY_NAME) {
+    return fail(
+      `token ${tokenId} is named ${BROKER_IDENTITY_NAME}, the reserved name for a machine's broker bootstrap credential; this machine's own bootstrap is a different token, so this one belongs to another machine or is a superseded one — retire it in the Cloudflare dashboard, where you can confirm which machine it belongs to`,
+    );
+  }
+  const brokered = parseAnyTokenName(target.name);
+  if (brokered !== null) {
+    const refusal = brokeredRefusal({
+      tokenId,
+      name: target.name,
+      brokered,
+      currentRepo: resolveGithubRepo(options.dir),
+      force: options.force,
+    });
+    if (refusal !== null) {
+      return fail(refusal);
+    }
+  }
+  const deleted = await deleteAccountToken(
+    account.accountId,
+    account.token,
+    tokenId,
+  );
+  if (!deleted.ok) {
+    return fail(`${target.name}: ${deleted.problem}`);
+  }
+  console.log(
+    `standards creds: revoked ${target.name} (${account.accountId}/${tokenId})`,
+  );
+  if (brokered !== null) {
+    console.log(
+      `  it was brokered to ${brokered.repo}; --force took it because this checkout is not that repository`,
+    );
+  }
+  console.log(
+    '  any stored copy of its value is now dead; replace it with `standards creds add cloudflare` if something still needs it',
+  );
+  return true;
+};