@davidvornholt/standards 0.20.0 → 0.22.0

package/src/creds-plan-renew.ts

@@ -4,15 +4,34 @@
 // mismatch deletes the replacement and preserves the old token.
 
 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 } from './creds-sops';
 import { verifySopsStoredValue } from './creds-sops-value';
 import type { CloudflareBrokerAccount } from './creds-store';
+import { resolveTargetRelResult } from './creds-target';
+import type { BrokeredRefreshEvidence } from './dev-env-brokered-refresh';
 
 type RenewAction = Extract<PlannedAction, { readonly kind: 'renew' }>;
 
+export type RenewPlannedTokenResult = {
+  readonly failure: string | null;
+  readonly refreshEvidence: BrokeredRefreshEvidence | null;
+};
+
+const renewalResult = (
+  failure: string | null,
+  evidence: BrokeredRefreshEvidence | null = null,
+): RenewPlannedTokenResult => ({ failure, refreshEvidence: evidence });
+
+const refreshEvidence = (
+  action: RenewAction,
+  safety: BrokeredRefreshEvidence['safety'],
+): BrokeredRefreshEvidence | null =>
+  action.format === 's3'
+    ? { target: action.target, key: action.key, safety }
+    : null;
+
 const cleanupReplacement = async (
   account: CloudflareBrokerAccount,
   replacementId: string,
@@ -48,19 +67,20 @@ export const renewPlannedToken = async (
   consumer: string,
   account: CloudflareBrokerAccount,
   action: RenewAction,
-): Promise<string | null> => {
+): Promise<RenewPlannedTokenResult> => {
   const { accountId, token: bootstrapToken } = account;
-  const rel = resolveTargetRel(consumer, action.target);
-  if (rel === null) {
-    return `${action.name}: secrets target ${action.target} not found`;
+  const resolved = resolveTargetRelResult(consumer, action.target);
+  if (!resolved.ok) {
+    return renewalResult(`${action.name}: ${resolved.problem}`);
   }
+  const { rel } = resolved;
   const destinationProblem = await inspectRenewDestinations(
     consumer,
     rel,
     action,
   );
   if (destinationProblem !== null) {
-    return destinationProblem;
+    return renewalResult(destinationProblem, refreshEvidence(action, 'unsafe'));
   }
   if (action.format === 's3') {
     const accessKey = verifySopsStoredValue(
@@ -70,7 +90,10 @@ export const renewPlannedToken = async (
       action.tokenId,
     );
     if (!(accessKey.ok && accessKey.matches)) {
-      return `${action.name}: could not prove the stored S3 access key belongs to the managed token; renewal stopped before mutation`;
+      return renewalResult(
+        `${action.name}: could not prove the stored S3 access key belongs to the managed token; renewal stopped before mutation`,
+        refreshEvidence(action, 'unsafe'),
+      );
     }
   }
   const replacement = await createAccountToken(accountId, bootstrapToken, {
@@ -80,7 +103,7 @@ export const renewPlannedToken = async (
     condition: action.condition,
   });
   if (!replacement.ok) {
-    return `${action.name}: ${replacement.problem}`;
+    return renewalResult(`${action.name}: ${replacement.problem}`);
   }
   const { id: replacementId, value } = replacement.value;
   const writes = destinationWrites(
@@ -99,7 +122,10 @@ export const renewPlannedToken = async (
   );
   if (unverifiable.length > 0) {
     const detail = unverifiable.join('; ');
-    return `${action.name}: ${written.ok ? detail : `${written.problem}; ${detail}`}; account ${accountId} replacement ${replacementId} and old token ${action.tokenId} remain active because the stored value is unverifiable`;
+    return renewalResult(
+      `${action.name}: ${written.ok ? detail : `${written.problem}; ${detail}`}; account ${accountId} replacement ${replacementId} and old token ${action.tokenId} remain active because the stored value is unverifiable`,
+      refreshEvidence(action, 'unsafe'),
+    );
   }
   const mismatched = verified.flatMap(({ path, result }) =>
     result.ok && !result.matches ? [path] : [],
@@ -108,14 +134,20 @@ export const renewPlannedToken = async (
     const problem = written.ok
       ? `${action.name}: ${rel} at ${mismatched.join(', ')} now holds a value matching neither the old nor the replacement token; repair the stored value manually`
       : `${action.name}: ${written.problem}`;
-    return cleanupReplacement(account, replacementId, action.tokenId, problem);
+    return renewalResult(
+      await cleanupReplacement(account, replacementId, action.tokenId, problem),
+      refreshEvidence(action, 'unsafe'),
+    );
   }
   const deleted = await deleteAccountToken(
     accountId,
     bootstrapToken,
     action.tokenId,
   );
-  return deleted.ok
-    ? null
-    : `${action.name}: replacement ${replacementId} is stored, but old token ${action.tokenId} could not be revoked: ${deleted.problem}`;
+  return renewalResult(
+    deleted.ok
+      ? null
+      : `${action.name}: replacement ${replacementId} is stored, but old token ${action.tokenId} could not be revoked: ${deleted.problem}`,
+    refreshEvidence(action, 'verified'),
+  );
 };

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

@@ -1,7 +1,11 @@
 import { listSecretsTargets } from './creds-dest';
 import { identifyCloudflareBootstrapAuthority } from './creds-login-cloudflare';
 import { computeCredsPlan } from './creds-plan';
-import { renewPlannedToken } from './creds-plan-renew';
+import {
+  type RenewPlannedTokenResult,
+  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';
@@ -10,12 +14,21 @@ import {
   readBrokerStore,
   resolveBrokerPath,
 } from './creds-store';
+import { refreshDevEnvForSopsWrites } from './dev-env-brokered-refresh';
 import { resolveGithubRepo } from './github-api';
 
 const gatherRepoState = async (consumer: string, store: BrokerStore) => {
+  const inventory = listSecretsTargets(consumer);
+  if (inventory.problems.length > 0) {
+    return {
+      keysByTarget: new Map<string, ReadonlySet<string>>(),
+      tokens: [] as Array<AccountToken>,
+      problems: inventory.problems,
+    };
+  }
   const keysByTarget = new Map<string, ReadonlySet<string>>();
   const targetKeys = await Promise.all(
-    listSecretsTargets(consumer).map(async ({ target, rel }) => ({
+    inventory.targets.map(async ({ target, rel }) => ({
       target,
       rel,
       keys: await readEncryptedKeys(consumer, rel),
@@ -60,18 +73,23 @@ const applyAction = (
   consumer: string,
   store: BrokerStore,
   action: PlannedAction,
-): Promise<string | null> => {
+): Promise<RenewPlannedTokenResult> => {
   const account = store.cloudflare.find(
     (entry) => entry.accountId === action.accountId,
   );
   if (account === undefined) {
-    return Promise.resolve(
-      `${action.name}: account ${action.accountId} is not in the broker store`,
-    );
+    return Promise.resolve({
+      failure: `${action.name}: account ${action.accountId} is not in the broker store`,
+      refreshEvidence: null,
+    });
   }
-  return action.kind === 'revoke'
-    ? revokePlannedToken(account, action)
-    : renewPlannedToken(consumer, account, action);
+  if (action.kind === 'renew') {
+    return renewPlannedToken(consumer, account, action);
+  }
+  return revokePlannedToken(account, action).then((failure) => ({
+    failure,
+    refreshEvidence: null,
+  }));
 };
 
 const fail = (message: string): false => {
@@ -109,30 +127,25 @@ 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');
   }
   if (!apply || plan.actions.length === 0) {
     return true;
   }
-  const failures = (
-    await Promise.all(
-      plan.actions.map((action) => applyAction(consumer, store, action)),
-    )
-  ).filter((failure): failure is string => failure !== null);
+  const results = await Promise.all(
+    plan.actions.map((action) => applyAction(consumer, store, action)),
+  );
+  const failures = results.flatMap(({ failure }) =>
+    failure === null ? [] : [failure],
+  );
   for (const failure of failures) {
     console.error(`standards creds: ${failure}`);
   }
-  return failures.length === 0;
+  const refreshEvidence = results.flatMap(({ refreshEvidence: evidence }) =>
+    evidence === null ? [] : [evidence],
+  );
+  const refreshed = await refreshDevEnvForSopsWrites(consumer, refreshEvidence);
+  return failures.length === 0 && refreshed;
 };

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,
+  };
 };