@davidvornholt/standards 0.26.3 → 0.27.0

package/src/creds-naming.ts

@@ -60,7 +60,10 @@ export const parseTokenName = (
   repo: string,
 ): BrokeredTokenRef | null => {
   const prefix = repoTokenPrefix(repo);
-  if (!name.startsWith(prefix)) {
+  if (
+    !isInMintedNamespace(name) ||
+    name.slice(0, prefix.length).toLowerCase() !== prefix.toLowerCase()
+  ) {
     return null;
   }
   const rest = name.slice(prefix.length);

package/src/creds-plan-renew.ts

@@ -8,7 +8,8 @@ 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 { type CloudflareBrokerAccount, resolveBrokerPath } from './creds-store';
+import { withBrokerLock } from './creds-store-lock';
 import { resolveTargetRelResult } from './creds-target';
 import type { BrokeredRefreshEvidence } from './dev-env-brokered-refresh';
 
@@ -63,7 +64,7 @@ const inspectRenewDestinations = async (
     : null;
 };
 
-export const renewPlannedToken = async (
+const renewWhileLocked = async (
   consumer: string,
   account: CloudflareBrokerAccount,
   action: RenewAction,
@@ -151,3 +152,14 @@ export const renewPlannedToken = async (
     refreshEvidence(action, 'verified'),
   );
 };
+
+// Duplicate retirement uses this same lock. Hold it before minting until the
+// replacement is durably verified and the old token's deletion has finished.
+export const renewPlannedToken = (
+  consumer: string,
+  account: CloudflareBrokerAccount,
+  action: RenewAction,
+): Promise<RenewPlannedTokenResult> =>
+  withBrokerLock(resolveBrokerPath(), () =>
+    renewWhileLocked(consumer, account, action),
+  );

package/src/creds-plan-report.ts

@@ -25,7 +25,7 @@ const revokeCommand = (token: UnmanagedToken, extra: string): string =>
 // 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
+  token.name.toLowerCase() === 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, '')}`;
 

package/src/creds-plan-unmanaged.ts

@@ -8,7 +8,6 @@
 import type { CloudflareToken } from './creds-cloudflare-api';
 import {
   type BrokeredTokenRef,
-  isInMintedNamespace,
   parseAnyTokenName,
   parseTokenName,
   repoTokenPrefix,
@@ -39,7 +38,9 @@ const classifyAccountToken = (
   if (token.status === 'expired') {
     return { kind: 'ignored' };
   }
-  if (token.name.startsWith(repoTokenPrefix(repo))) {
+  if (
+    token.name.toLowerCase().startsWith(repoTokenPrefix(repo).toLowerCase())
+  ) {
     return { kind: 'malformed' };
   }
   // A brokered name carries the repository that owns it, which normally
@@ -53,9 +54,7 @@ const classifyAccountToken = (
   if (elsewhere !== null) {
     return { kind: 'brokered-elsewhere', repo: elsewhere.repo };
   }
-  return isInMintedNamespace(token.name)
-    ? { kind: 'ignored' }
-    : { kind: 'unmanaged' };
+  return { kind: 'unmanaged' };
 };
 
 export type ManagedTokenRef = AccountToken & {

package/src/creds-plan.ts

@@ -133,7 +133,7 @@ const dispositionForGroup = (
     const [first] = group;
     return {
       kind: 'finding',
-      finding: `ambiguous Cloudflare tokens have destination footprints intersecting in ${first?.ref.target}: ${group.map((candidate) => `${candidate.ref.key} (${candidate.accountId}/${candidate.token.id})`).join(', ')}; revoke duplicates manually before plan/apply`,
+      finding: `ambiguous Cloudflare tokens have destination footprints intersecting in ${first?.ref.target}: ${group.map((candidate) => `${candidate.ref.key} (${candidate.accountId}/${candidate.token.id})`).join(', ')}; for same-name duplicates, keep the encrypted key intact and use \`standards creds revoke --account <account-id> --token-id <duplicate-id>\` to retire only a token proven not to be stored; resolve other intersecting destinations before plan/apply`,
     };
   }
   const [entry] = group;

package/src/creds-revoke-duplicate.ts

@@ -0,0 +1,127 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isContainedPath } from './contained-path';
+import { deleteAccountToken, verifyAccountToken } from './creds-cloudflare';
+import type { CloudflareToken } from './creds-cloudflare-api';
+import type { BrokeredTokenRef } from './creds-naming';
+import { lookupS3Pair, s3PairPaths } from './creds-r2';
+import { verifySopsStoredValue } from './creds-sops-value';
+import type { CloudflareBrokerAccount } from './creds-store';
+import { resolveBrokerPath } from './creds-store';
+import { withBrokerLock } from './creds-store-lock';
+import { resolveTargetRelResult } from './creds-target';
+import { isRecord } from './github-settings-parse';
+import { decryptSopsJson } from './sops-exec';
+
+type Proof =
+  | {
+      readonly ok: true;
+      readonly id: string | null;
+      readonly values: ReadonlyArray<{
+        readonly path: string;
+        readonly value: string;
+      }>;
+    }
+  | { readonly ok: false };
+const storedProof = async (
+  document: unknown,
+  key: string,
+  accountId: string,
+): Promise<Proof> => {
+  let node = document;
+  for (const segment of key.split('.')) {
+    if (!isRecord(node)) {
+      return { ok: false };
+    }
+    if (!Object.hasOwn(node, segment)) {
+      return { ok: true, id: null, values: [] };
+    }
+    node = node[segment];
+  }
+  if (typeof node === 'string') {
+    const verified = await verifyAccountToken(accountId, node);
+    return verified.ok && verified.value.status === 'active'
+      ? {
+          ok: true,
+          id: verified.value.id,
+          values: [{ path: key, value: node }],
+        }
+      : { ok: false };
+  }
+  const pair = lookupS3Pair(document, key);
+  if (!pair.ok) {
+    return { ok: false };
+  }
+  const [accessPath, secretPath] = s3PairPaths(key);
+  return {
+    ok: true,
+    id: pair.accessKeyId,
+    values: [
+      { path: accessPath, value: pair.accessKeyId },
+      { path: secretPath, value: pair.secretAccessKey },
+    ],
+  };
+};
+
+const unchangedStoredValues = (
+  consumer: string,
+  rel: string,
+  proof: Extract<Proof, { readonly ok: true }>,
+  ciphertext: Buffer,
+): boolean =>
+  proof.values.every(({ path, value }) => {
+    const result = verifySopsStoredValue(consumer, rel, path, value);
+    return result.ok && result.matches;
+  }) && readFileSync(join(consumer, rel)).equals(ciphertext);
+
+const isActiveDuplicate = (
+  id: string | null,
+  duplicates: ReadonlyArray<CloudflareToken>,
+): boolean =>
+  id === null ||
+  duplicates.some((token) => token.id === id && token.status === 'active');
+
+// Only the explicit non-stored member of a same-name duplicate set may be
+// retired. Keep the current secret and every token if identity is uncertain.
+export const revokeStoredDuplicate = async (input: {
+  readonly consumer: string;
+  readonly account: CloudflareBrokerAccount;
+  readonly tokenId: string;
+  readonly ref: BrokeredTokenRef;
+  readonly duplicates: ReadonlyArray<CloudflareToken>;
+}): Promise<string | null> =>
+  withBrokerLock(resolveBrokerPath(), async () => {
+    const { consumer, account, ref, tokenId, duplicates } = input;
+    const target = resolveTargetRelResult(consumer, ref.target);
+    if (!(target.ok && isContainedPath(consumer, target.rel, 'file'))) {
+      return 'cannot safely resolve the duplicate token SOPS destination; keep its stored key intact';
+    }
+    const ciphertext = readFileSync(join(consumer, target.rel));
+    const decrypted = decryptSopsJson(consumer, target.rel);
+    if (!decrypted.ok) {
+      return 'cannot decrypt the duplicate token destination; keep its stored key intact';
+    }
+    const proof = await storedProof(
+      decrypted.value,
+      ref.key,
+      account.accountId,
+    );
+    if (!proof.ok) {
+      return 'cannot prove which duplicate token the stored credential uses; keep its stored key intact';
+    }
+    if (!isActiveDuplicate(proof.id, duplicates)) {
+      return 'stored credential does not identify an active duplicate; no token revoked';
+    }
+    if (proof.id === tokenId) {
+      return `token ${tokenId} is the credential currently stored at ${ref.target}:${ref.key}; choose a different duplicate ID`;
+    }
+    if (!unchangedStoredValues(consumer, target.rel, proof, ciphertext)) {
+      return 'stored credential changed or became unreadable during duplicate verification; no token revoked';
+    }
+    const deleted = await deleteAccountToken(
+      account.accountId,
+      account.token,
+      tokenId,
+    );
+    return deleted.ok ? null : deleted.problem;
+  });

package/src/creds-revoke.ts

@@ -3,9 +3,9 @@
 // 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.
+// time. Singular tokens reconciliation owns are retired through apply. A
+// same-name duplicate may be explicitly retired after proving it is not the
+// stored credential; this recovers interrupted renewal without deleting a key.
 
 import { deleteAccountToken } from './creds-cloudflare';
 import { isCloudflareId } from './creds-cloudflare-id';
@@ -16,6 +16,7 @@ import {
   type BrokeredTokenRef,
   parseAnyTokenName,
 } from './creds-naming';
+import { revokeStoredDuplicate } from './creds-revoke-duplicate';
 import { readBrokerStore, resolveBrokerPath } from './creds-store';
 import { resolveGithubRepo } from './github-api';
 
@@ -30,8 +31,8 @@ const fail = (message: string): false => {
 // 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();
+const sameRepo = (left: string, right: string | null): boolean =>
+  right !== null && 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.
@@ -57,15 +58,8 @@ const brokeredRefusal = ({
   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`;
+    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`;
   }
   if (force) {
     return null;
@@ -73,6 +67,16 @@ const brokeredRefusal = ({
   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`;
 };
 
+const reportDuplicate = (problem: string | null, label: string): boolean => {
+  if (problem !== null) {
+    return fail(problem);
+  }
+  console.log(
+    `standards creds: revoked duplicate ${label}; preserved the stored credential`,
+  );
+  return true;
+};
+
 export const runCredsRevoke = async (options: {
   readonly account: string | undefined;
   readonly tokenId: string | undefined;
@@ -121,18 +125,35 @@ export const runCredsRevoke = async (options: {
   // — 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) {
+  if (target.name.toLowerCase() === 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 currentRepo = resolveGithubRepo(options.dir);
+    const duplicates = identified.value.tokens.filter(
+      (entry) => entry.name === target.name,
+    );
+    if (sameRepo(brokered.repo, currentRepo) && duplicates.length > 1) {
+      const problem = await revokeStoredDuplicate({
+        consumer: options.dir,
+        account,
+        tokenId,
+        ref: brokered,
+        duplicates,
+      });
+      return reportDuplicate(
+        problem,
+        `${target.name} (${account.accountId}/${tokenId})`,
+      );
+    }
     const refusal = brokeredRefusal({
       tokenId,
       name: target.name,
       brokered,
-      currentRepo: resolveGithubRepo(options.dir),
+      currentRepo,
       force: options.force,
     });
     if (refusal !== null) {

package/src/creds-store-lock-inspection.ts

@@ -1,4 +1,4 @@
-import { readdir, readFile, rmdir, stat, unlink } from 'node:fs/promises';
+import { lstat, readdir, readFile, rmdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isRecord } from './github-settings-parse';
 
@@ -24,15 +24,11 @@ type ExistingGeneration =
       readonly modifiedAt: number;
     };
 
-const directoryModifiedAt = async (
-  lockPath: string,
-): Promise<number | null> => {
-  try {
-    return (await stat(lockPath)).mtimeMs;
-  } catch {
-    return null;
-  }
-};
+const missingOr = (
+  error: unknown,
+  fallback: ExistingGeneration,
+): ExistingGeneration =>
+  isErrorCode(error, 'ENOENT') ? { kind: 'missing' } : fallback;
 
 const readExistingGeneration = async (
   lockPath: string,
@@ -41,15 +37,12 @@ const readExistingGeneration = async (
   try {
     names = await readdir(lockPath);
   } catch (error) {
-    return isErrorCode(error, 'ENOENT')
-      ? { kind: 'missing' }
-      : { kind: 'unknown' };
+    return missingOr(error, { kind: 'unknown' });
   }
   if (names.length === 0) {
-    const modifiedAt = await directoryModifiedAt(lockPath);
-    return modifiedAt === null
-      ? { kind: 'missing' }
-      : { entryPath: null, kind: 'incomplete', modifiedAt };
+    // Empty directories are immediately replaceable by an initialized
+    // candidate's atomic rename, including the holder-unlink release gap.
+    return { kind: 'missing' };
   }
   const entryName = names.length === 1 ? names[0] : undefined;
   if (entryName === undefined) {
@@ -58,9 +51,13 @@ const readExistingGeneration = async (
   const entryPath = join(lockPath, entryName);
   let modifiedAt: number;
   try {
-    modifiedAt = (await stat(entryPath)).mtimeMs;
-  } catch {
-    return { kind: 'unknown' };
+    const entry = await lstat(entryPath);
+    if (!entry.isFile()) {
+      return { kind: 'unknown' };
+    }
+    modifiedAt = entry.mtimeMs;
+  } catch (error) {
+    return missingOr(error, { kind: 'unknown' });
   }
   const incomplete = {
     entryPath,
@@ -72,8 +69,16 @@ const readExistingGeneration = async (
   ) {
     return incomplete;
   }
+  let raw: string;
+  try {
+    raw = await readFile(entryPath, 'utf8');
+  } catch (error) {
+    // Only a vanished regular holder permits immediate retry. An I/O error
+    // cannot establish that a stale holder is malformed or safe to reclaim.
+    return missingOr(error, { kind: 'unknown' });
+  }
   try {
-    const decoded: unknown = JSON.parse(await readFile(entryPath, 'utf8'));
+    const decoded: unknown = JSON.parse(raw);
     const generation = entryName.slice(
       HOLDER_PREFIX.length,
       -HOLDER_SUFFIX.length,

package/src/creds-store-lock.ts

@@ -7,6 +7,7 @@
 
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import process from 'node:process';
 import {
   type HeldBrokerLock,
   releaseBrokerLock,
@@ -74,6 +75,18 @@ export const withBrokerLock = async <T>(
   try {
     return await operation();
   } finally {
-    await releaseBrokerLock(held);
+    try {
+      await releaseBrokerLock(held);
+    } catch (error) {
+      // Cleanup must preserve either the durable operation result or its
+      // original failure. The stopped lease makes abandoned holders stale.
+      try {
+        process.stderr.write(
+          `standards creds: warning: lock cleanup failed for ${lockPath}: ${error instanceof Error ? error.message : String(error)}; the operation result is unchanged; retry after the stale-lock window\n`,
+        );
+      } catch {
+        // Even an unavailable diagnostic stream cannot change that result.
+      }
+    }
   }
 };

package/src/dependabot-directory-overlap.ts

@@ -15,7 +15,7 @@ type Automaton = {
   readonly edges: ReadonlyArray<Edge>;
 };
 
-const compileDirectory = (
+const compilePattern = (
   directory: string,
   supportsGlobs: boolean,
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Ruby glob tokens have distinct NFA transitions that are clearest in one ordered parser.
@@ -94,15 +94,11 @@ const compileDirectory = (
   return { accept: current, edges };
 };
 
-export const directoriesOverlap = (
-  leftDirectory: string,
-  leftSupportsGlobs: boolean,
-  rightDirectory: string,
-  rightSupportsGlobs: boolean,
+const automataOverlap = (
+  left: Automaton,
+  right: Automaton,
   // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: The product walk must process both automata's epsilon and consuming transitions together.
 ): boolean => {
-  const left = compileDirectory(leftDirectory, leftSupportsGlobs);
-  const right = compileDirectory(rightDirectory, rightSupportsGlobs);
   const pending: Array<readonly [number, number]> = [[0, 0]];
   const visited = new Set<string>();
   for (const [leftState, rightState] of pending) {
@@ -137,3 +133,99 @@ export const directoriesOverlap = (
   }
   return false;
 };
+
+const dotAliasScan = (segments: ReadonlyArray<string>) => {
+  const firstScan = segments.findIndex((segment) =>
+    compilePattern(segment, true).edges.some(
+      (edge) => edge.matcher === null || edge.matcher.kind !== 'literal',
+    ),
+  );
+  let aliasIndex = firstScan;
+  while (segments[aliasIndex] === '**' && aliasIndex < segments.length - 1) {
+    aliasIndex += 1;
+  }
+  return { firstScan, aliasIndex };
+};
+
+const compileDirectory = (
+  directory: string,
+  supportsGlobs: boolean,
+): Automaton => {
+  if (!supportsGlobs || directory === '/') {
+    return compilePattern(directory, supportsGlobs);
+  }
+  const edges: Array<Edge> = [];
+  let current = 0;
+  let states = 1;
+  const segments = directory.split('/').slice(1);
+  const { firstScan, aliasIndex } = dotAliasScan(segments);
+  let aliasStart = 0;
+  for (const [index, segment] of segments.entries()) {
+    if (index === firstScan) {
+      aliasStart = current;
+    }
+    if (segment === '**' && index < segments.length - 1) {
+      const loop = states;
+      states += 1;
+      edges.push({ from: current, to: loop, matcher: null });
+      current = loop;
+      const part = compilePattern('/*', true);
+      const offset = states;
+      states += part.accept + 1;
+      edges.push(
+        { from: current, to: offset, matcher: null },
+        ...part.edges.map((edge) => ({
+          ...edge,
+          from: edge.from + offset,
+          to: edge.to + offset,
+        })),
+        { from: offset + part.accept, to: current, matcher: null },
+      );
+    } else {
+      const part = compilePattern(`/${segment}`, true);
+      const offset = states;
+      states += part.accept + 1;
+      edges.push(
+        { from: current, to: offset, matcher: null },
+        ...part.edges.map((edge) => ({
+          ...edge,
+          from: edge.from + offset,
+          to: edge.to + offset,
+        })),
+      );
+      current = offset + part.accept;
+      if (
+        index === aliasIndex &&
+        automataOverlap(
+          compilePattern(segment, true),
+          compilePattern('.', false),
+        )
+      ) {
+        // Ruby sets FNM_GLOB_SKIPDOT after its first directory scan. A
+        // recursive prefix may match zero directories in that same scan;
+        // after consuming a child it cannot return to this alias start.
+        edges.push({ from: aliasStart, to: current, matcher: null });
+      }
+    }
+  }
+  const compiled = { accept: current, edges };
+  if (automataOverlap(compiled, { accept: 0, edges: [] })) {
+    edges.push({
+      from: 0,
+      to: current,
+      matcher: { kind: 'literal', value: '/'.codePointAt(0) ?? 0 },
+    });
+  }
+  return compiled;
+};
+
+export const directoriesOverlap = (
+  leftDirectory: string,
+  leftSupportsGlobs: boolean,
+  rightDirectory: string,
+  rightSupportsGlobs: boolean,
+): boolean =>
+  automataOverlap(
+    compileDirectory(leftDirectory, leftSupportsGlobs),
+    compileDirectory(rightDirectory, rightSupportsGlobs),
+  );

package/src/dependabot-update.ts

@@ -110,6 +110,17 @@ export const updateTarget = (
   const rawDirectories: ReadonlyArray<string> = hasDirectory
     ? [directory as string]
     : (directories as ReadonlyArray<string>);
+  if (
+    hasDirectories &&
+    rawDirectories.some(
+      (path) =>
+        isDependabotGlob(path) && (path.includes('{') || path.includes('}')),
+    )
+  ) {
+    problems.push(
+      `${label}.directories brace expansion is unsupported; list each alternative explicitly`,
+    );
+  }
   const normalized = [...new Set(rawDirectories)].sort();
   const normalizedDirectories = [
     ...new Set(normalized.map(normalizeDependabotDirectory)),

package/src/dev-env-brokered-allowlist.ts

@@ -1,4 +1,4 @@
-import { parseDestination } from './creds-dest';
+import { validBrokeredIdentity } from './dev-env-brokered-source';
 import type { DevEnvLayerKind } from './dev-env-document';
 
 export const BROKERED_REFERENCES_KEY = 'brokeredReferences';
@@ -32,7 +32,7 @@ export const parseBrokeredAllowlist = (
   const entries = new Set<string>();
   const problems: Array<string> = [];
   for (const [index, entry] of raw.entries()) {
-    if (typeof entry !== 'string' || parseDestination(entry) === null) {
+    if (typeof entry !== 'string' || !validBrokeredIdentity(entry)) {
       problems.push(
         `${source} "${BROKERED_REFERENCES_KEY}" entry ${index + 1} must be an exact "<target>:<dotted.key>" string`,
       );

package/src/dev-env-brokered-preflight.ts

@@ -0,0 +1,69 @@
+import type { BrokeredS3Reference } from './dev-env-brokered';
+import {
+  brokeredReferenceIdentity,
+  resolveBrokeredSource,
+} from './dev-env-brokered-source';
+import type { ComposedDevEnvTarget } from './dev-env-compose';
+
+type SelectedReference = Readonly<{
+  label: string;
+  reference: BrokeredS3Reference;
+}>;
+type Source = Readonly<{ root: string; rel: string }>;
+const selectedReferences = (
+  targets: ReadonlyArray<ComposedDevEnvTarget>,
+): ReadonlyArray<SelectedReference> =>
+  targets.flatMap((target) =>
+    Object.entries(target.env).flatMap(([key, reference]) =>
+      typeof reference === 'string'
+        ? []
+        : [
+            {
+              label: `${target.group}.${target.workspace}.${key} reference to secrets target "${reference.brokeredS3}"`,
+              reference,
+            },
+          ],
+    ),
+  );
+
+export const prepareBrokeredSources = (
+  consumer: string,
+  targets: ReadonlyArray<ComposedDevEnvTarget>,
+  allowed: ReadonlySet<string>,
+  preserved: ReadonlySet<string>,
+): Readonly<{
+  sources: ReadonlyMap<BrokeredS3Reference, Source>;
+  problems: ReadonlyArray<string>;
+}> => {
+  const sources = new Map<BrokeredS3Reference, Source>();
+  const roots = new Map<string, string>();
+  const problems = selectedReferences(targets).flatMap(
+    ({ label, reference }) => {
+      const identity = brokeredReferenceIdentity(reference);
+      if (!allowed.has(identity)) {
+        return [
+          `${label}: unauthorized brokered S3 pair; add "${identity}" to the encrypted secrets/dev.yaml brokeredReferences allowlist`,
+        ];
+      }
+      if (preserved.has(identity)) {
+        return [];
+      }
+      const resolved = resolveBrokeredSource(consumer, reference);
+      if (!resolved.ok) {
+        return [`${label}: ${resolved.problem}`];
+      }
+      if (reference.source !== undefined) {
+        const previous = roots.get(reference.source.repository);
+        if (previous !== undefined && previous !== resolved.root) {
+          return [
+            `${label}: one source repository must resolve to one checkout per generation`,
+          ];
+        }
+        roots.set(reference.source.repository, resolved.root);
+      }
+      sources.set(reference, resolved);
+      return [];
+    },
+  );
+  return { sources, problems };
+};