@davidvornholt/standards 0.21.0 → 0.22.0

package/README.md

@@ -29,7 +29,7 @@ standards poller --print-units --config <path>
 
 `dependabot --write` regenerates the composed `.github/dependabot.yml` from the canonical `.github/dependabot.base.yml` and the optional repo-owned `.github/dependabot.local.yml`; `init` and `sync` do the same automatically. `dependabot --check` verifies the generated file still matches its sources, and `doctor`/`check` include the same verification. The overlay is deliberately lean and additive only: new update blocks for repo-specific ecosystems, top-level private registry definitions, and `ignore` or `registries` entries appended by repeating a canonical block's normalized target. Matching blocks cannot add labels, groups, cooldowns, pull-request limits, or other policy. Update blocks for the same ecosystem and target branch must not select intersecting directories after Dependabot's path normalization. A plural `directories` target is expanded as a glob when it contains `*`, `?`, or both `[` and `]`: `*` and bare `**` stay within one path segment, `**/` matches zero or more directory segments, `?` matches one non-separator character, and bracket expressions match character sets or ranges. Singular `directory` values are always literal.
 
-`dev-env` composes each workspace's dev environment from three layers sharing one shape — keyed by workspace group and a one-segment kebab-case workspace name (`apps.<name>`, `packages.<name>`), each mapping portable environment variable names to string values: the tracked plain `config/dev.yaml`, the SOPS-encrypted `secrets/dev.yaml` (required, decrypted via sops), and the gitignored plain `config/dev.local.yaml`, applied in that order with later layers overriding per key. A key declared in both tracked shared layers is a validation problem — a value is either configuration or a secret — while a local override of either is the file's purpose. Plain layers are optional and may be comment-only; `config/dev.local.yaml` must itself be gitignored because it may override secret values. The command transactionally writes every declared workspace's `.env.local` with owner-only permissions and a do-not-edit header naming the contributing sources. It also discovers direct `apps/*` and `packages/*` directories containing `package.json` and removes a stale `.env.local` only when its first line is that exact header; hand-owned files, edited headers, nested directories, and symlinked paths are left untouched. Writes and removals commit or roll back as one transaction, preserving prior contents, modes, and absent files. The final files and the transaction's actual random `.env.local.standards-*.tmp` and `.env.local.standards-*.bak` paths must all be gitignored before staging starts. Existing consumers must add those two artifact patterns themselves because `.gitignore` is seeded only during `init`; `sync` does not change it. Its Bun-specific dotenv codec exactly round-trips every value it accepts without adding helper environment variables; a value the codec cannot encode exactly is gathered as a validation problem instead of being changed silently. Validation gathers all document, containment, destination-type, workspace, and gitignore problems before writing anything; symlink destinations, duplicate resolved destinations, changed parent-directory identities, and symlinked workspace paths are rejected without following the link. Cleanup trouble after a completed commit is reported loudly as a warning rather than falsely reporting generation failure. Parent identities are checked immediately before each path operation; an unavoidable swap in the syscall-sized interval after a check remains outside the non-hostile maintainer threat model. The canonical `justfile` exposes the command as `just dev-env-generate`, and `just dev-refresh` chains a `just secrets edit dev` session into regeneration.
+`dev-env` composes each workspace's dev environment from three layers sharing one workspace shape — keyed by workspace group and a one-segment kebab-case workspace name (`apps.<name>`, `packages.<name>`): the tracked plain `config/dev.yaml`, the SOPS-encrypted `secrets/dev.yaml` (required, decrypted via sops), and the gitignored plain `config/dev.local.yaml`, applied in that order with later layers overriding per key. Secret-layer env values are strings; a plain-layer env value may be a string or the brokered reference described below. A key declared in both tracked shared layers is a validation problem — a value is either configuration or a secret — while a local override of either is the file's purpose. Plain layers are optional and may be comment-only; `config/dev.local.yaml` must itself be gitignored because it may override secret values. The command transactionally writes every declared workspace's `.env.local` with owner-only permissions and a do-not-edit header naming the contributing sources. It also discovers direct `apps/*` and `packages/*` directories containing `package.json` and removes a stale `.env.local` only when its first line is that exact header; hand-owned files, edited headers, nested directories, and symlinked paths are left untouched. Writes and removals commit or roll back as one transaction, preserving prior contents, modes, and absent files. The final files and the transaction's actual random `.env.local.standards-*.tmp` and `.env.local.standards-*.bak` paths must all be gitignored before staging starts. Existing consumers must add those two artifact patterns themselves because `.gitignore` is seeded only during `init`; `sync` does not change it. Its Bun-specific dotenv codec exactly round-trips every value it accepts without adding helper environment variables; a value the codec cannot encode exactly is gathered as a validation problem instead of being changed silently. Validation gathers all document, containment, destination-type, workspace, and gitignore problems before writing anything; symlink destinations, duplicate resolved destinations, changed parent-directory identities, and symlinked workspace paths are rejected without following the link. Cleanup trouble after a completed commit is reported loudly as a warning rather than falsely reporting generation failure. Parent identities are checked immediately before each path operation; an unavoidable swap in the syscall-sized interval after a check remains outside the non-hostile maintainer threat model. The canonical `justfile` exposes the command as `just dev-env-generate`, and `just dev-refresh` chains a `just secrets edit dev` session into regeneration. A plain configuration layer may declare a **brokered S3 pair reference** instead of a literal: an object value `{ brokeredS3: <secrets-target>, key: <dotted.key>, part: access_key_id | secret_access_key }` pointing at a credential pair `creds add cloudflare --s3` minted into another SOPS target. An existing target name must bind exactly one contained file, either `infra/hosts/<name>/secrets.yaml` or `secrets/<name>.yaml`; both files existing is an ambiguity error, never host preference. The SOPS-encrypted `secrets/dev.yaml` must authorize every referenced pair with its exact `<secrets-target>:<dotted.key>` string under the reserved top-level `brokeredReferences` list. Plain layers reject that reserved key, and the secrets layer rejects reference objects: configuration selects a pair while encrypted policy authorizes its release into plaintext `.env.local`. Resolution rejects an unauthorized pair with the exact allowlist entry to add before invoking SOPS on that target. It then requires both `access_key_id` and `secret_access_key` to be strings, even when the reference selects only one part. Resolution runs after layer composition, so a later layer's literal overrides an earlier layer's reference and a reference that lost the merge is never decrypted; each authorized referenced target is decrypted once per run, and a missing target, ambiguous target, missing or partial pair, or unencodable resolved value is gathered as a named validation problem without exposing secret values. The secret value therefore keeps exactly one home — the broker's ledger. The loop closes on the broker side: after `creds add` verifies an exact referenced pair write, and after `creds apply` verifies a renewal in one, the command regenerates the dev env files itself, so a rotated pair reaches every generated `.env.local` without a manual step. Refresh evidence is pair-granular: a bearer sibling in the same SOPS file cannot trigger rendering of an unsafe pair, and a verified S3 sibling updates while an unsafe pair keeps its prior generated lines. If those prior owned lines cannot be proven and preserved, the refresh fails without changing any env file; every refresh failure is reported after the durable SOPS write remains committed.
 
 `check` also rejects the raw token formed by `biome-` + `ignore` anywhere in lock-listed canonical files. The intentionally blunt policy keeps synced sources compatible with consumer Biome configurations without invoking Biome or maintaining language-aware comment parsing.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davidvornholt/standards",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Bootstrap, synchronize, and validate davidvornholt/standards consumers",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,7 @@
     "src/creds-cloudflare-expiry.ts",
     "src/creds-cloudflare-id.ts",
     "src/creds-cloudflare-pagination.ts",
+    "src/creds-cloudflare-request.ts",
     "src/creds-cloudflare-zone.ts",
     "src/creds-commands.ts",
     "src/creds-args.ts",
@@ -65,6 +66,7 @@
     "src/creds-store-lock-holder.ts",
     "src/creds-store-lock-inspection.ts",
     "src/creds-store-lock-lease.ts",
+    "src/creds-target.ts",
     "src/dependabot-compose-input.ts",
     "src/dependabot-compose.ts",
     "src/dependabot-directory-character-class.ts",
@@ -72,6 +74,12 @@
     "src/dependabot-directory-overlap.ts",
     "src/dependabot-inspect.ts",
     "src/dependabot-update.ts",
+    "src/dev-env-brokered.ts",
+    "src/dev-env-brokered-allowlist.ts",
+    "src/dev-env-brokered-preserve.ts",
+    "src/dev-env-brokered-resolve.ts",
+    "src/dev-env-brokered-refresh.ts",
+    "src/dev-env-plain-layer.ts",
     "src/dev-env-compose.ts",
     "src/dev-env-document.ts",
     "src/dev-env-destination-duplicates.ts",

package/src/creds-add.ts

@@ -19,10 +19,25 @@ import {
   s3PairPaths,
 } from './creds-r2';
 import { readEncryptedKeys, setSopsValues } from './creds-sops';
+import { refreshDevEnvForSopsWrites } from './dev-env-brokered-refresh';
 
 const DEFAULT_TTL_DAYS = 90;
 const DAY_MS = 86_400_000;
 
+const addRefreshEvidence = (
+  format: DestinationFormat,
+  destination: { readonly target: string; readonly key: string },
+) =>
+  format === 's3'
+    ? [
+        {
+          target: destination.target,
+          key: destination.key,
+          safety: 'verified' as const,
+        },
+      ]
+    : [];
+
 const printSuccess = (input: {
   readonly name: string;
   readonly permissions: ReadonlyArray<string>;
@@ -168,5 +183,8 @@ export const runCredsAddCloudflare = async (
         : DEFAULT_R2_JURISDICTION,
     policies: resolved.policies,
   });
-  return true;
+  return await refreshDevEnvForSopsWrites(
+    consumer,
+    addRefreshEvidence(format, context.dest),
+  );
 };

package/src/creds-cloudflare-api.ts

@@ -5,10 +5,9 @@ import {
   type DecodedTokenCondition,
   decodeTokenCondition,
 } from './creds-cloudflare-condition';
+import { requestCloudflare } from './creds-cloudflare-request';
 import { isRecord } from './github-settings-parse';
 
-const API_ROOT = 'https://api.cloudflare.com/client/v4';
-
 export type CfResult<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly problem: string };
@@ -57,14 +56,11 @@ export const cfRequest = async (
   path: string,
   body?: unknown,
 ): Promise<CfResult<Envelope>> => {
-  const response = await fetch(`${API_ROOT}${path}`, {
-    method,
-    headers: {
-      authorization: `Bearer ${token}`,
-      ...(body === undefined ? {} : { 'content-type': 'application/json' }),
-    },
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
+  const requested = await requestCloudflare(token, method, path, body);
+  if (!requested.ok) {
+    return requested;
+  }
+  const response = requested.value;
   let parsed: unknown = null;
   try {
     parsed = (await response.json()) as unknown;

package/src/creds-cloudflare-request.ts

@@ -0,0 +1,31 @@
+const API_ROOT = 'https://api.cloudflare.com/client/v4';
+
+type CloudflareRequestResult =
+  | { readonly ok: true; readonly value: Response }
+  | { readonly ok: false; readonly problem: string };
+
+export const requestCloudflare = async (
+  token: string,
+  method: string,
+  path: string,
+  body: unknown,
+): Promise<CloudflareRequestResult> => {
+  try {
+    const response = await fetch(`${API_ROOT}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    return { ok: true, value: response };
+  } catch (error) {
+    return {
+      ok: false,
+      problem: `${method} ${path}: request failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
+  }
+};

package/src/creds-dest.ts

@@ -11,16 +11,22 @@ import {
   readBrokerStore,
   resolveBrokerPath,
 } from './creds-store';
+import {
+  isSafeSecretsTargetName,
+  resolveTargetRelResult,
+} from './creds-target';
 import { resolveGithubRepo } from './github-api';
 import { isRecord } from './github-settings-parse';
 
-const SAFE_TARGET = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9_-])?$/u;
-
 export type CredsDestination = {
   readonly target: string;
   readonly key: string;
 };
 export type SecretsTarget = { readonly target: string; readonly rel: string };
+export type SecretsTargetInventory = {
+  readonly targets: ReadonlyArray<SecretsTarget>;
+  readonly problems: ReadonlyArray<string>;
+};
 export type ResolvedContext = {
   readonly repo: string;
   readonly rel: string;
@@ -34,7 +40,7 @@ export const parseDestination = (raw: string): CredsDestination | null => {
   const key = raw.slice(separator + 1);
   return separator > 0 &&
     separator < raw.length - 1 &&
-    SAFE_TARGET.test(target) &&
+    isSafeSecretsTargetName(target) &&
     parseSopsKeyPath(key) !== null
     ? { target, key }
     : null;
@@ -88,38 +94,38 @@ const isHostTargetCandidate = (consumer: string, name: string): boolean => {
 
 export const listSecretsTargets = (
   consumer: string,
-): ReadonlyArray<SecretsTarget> => {
+): SecretsTargetInventory => {
   const flat = listDir(consumer, 'secrets')
     .filter(isYamlSecrets)
     .map((name) => ({
       target: name.slice(0, -'.yaml'.length),
       rel: `secrets/${name}`,
     }))
-    .filter(({ target }) => SAFE_TARGET.test(target));
+    .filter(({ target }) => isSafeSecretsTargetName(target));
   const hosts = listDir(consumer, 'infra/hosts')
     .filter(
-      (name) => SAFE_TARGET.test(name) && isHostTargetCandidate(consumer, name),
+      (name) =>
+        isSafeSecretsTargetName(name) && isHostTargetCandidate(consumer, name),
     )
     .map((name) => ({
       target: name,
       rel: `infra/hosts/${name}/secrets.yaml`,
     }));
-  return [...flat, ...hosts];
-};
-
-export const resolveTargetRel = (
-  consumer: string,
-  target: string,
-): string | null => {
-  if (!SAFE_TARGET.test(target)) {
-    return null;
+  const targets = [...flat, ...hosts];
+  const relsByTarget = new Map<string, Array<string>>();
+  for (const { target, rel } of targets) {
+    const rels = relsByTarget.get(target) ?? [];
+    rels.push(rel);
+    relsByTarget.set(target, rels);
   }
-  const host = `infra/hosts/${target}/secrets.yaml`;
-  if (isContainedSopsPath(consumer, host, 'file')) {
-    return host;
-  }
-  const flat = `secrets/${target}.yaml`;
-  return isContainedSopsPath(consumer, flat, 'file') ? flat : null;
+  const problems = [...relsByTarget.entries()].flatMap(([target, rels]) =>
+    rels.length > 1
+      ? [
+          `secrets target "${target}" is ambiguous because ${rels.join(' and ')} both claim that identity; rename one target so the name binds exactly one encrypted file`,
+        ]
+      : [],
+  );
+  return { targets, problems };
 };
 
 export const resolveContext = async (
@@ -144,14 +150,23 @@ export const resolveContext = async (
     );
     return null;
   }
-  const rel = resolveTargetRel(consumer, dest.target);
-  if (rel === null) {
+  const resolved = resolveTargetRelResult(consumer, dest.target);
+  if (!resolved.ok) {
     console.error(
-      `standards creds: secrets target "${dest.target}" not found; create it with \`just secrets edit ${dest.target}\` first`,
+      `standards creds: ${
+        resolved.kind === 'missing'
+          ? `${resolved.problem}; create it with \`just secrets edit ${dest.target}\` first`
+          : resolved.problem
+      }`,
     );
     return null;
   }
-  return { repo, rel, dest, store: await readBrokerStore(resolveBrokerPath()) };
+  return {
+    repo,
+    rel: resolved.rel,
+    dest,
+    store: await readBrokerStore(resolveBrokerPath()),
+  };
 };
 
 export const selectAccount = (

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-run.ts

@@ -1,7 +1,10 @@
 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';
@@ -11,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),
@@ -61,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,
+    });
+  }
+  if (action.kind === 'renew') {
+    return renewPlannedToken(consumer, account, action);
   }
-  return action.kind === 'revoke'
-    ? revokePlannedToken(account, action)
-    : renewPlannedToken(consumer, account, action);
+  return revokePlannedToken(account, action).then((failure) => ({
+    failure,
+    refreshEvidence: null,
+  }));
 };
 
 const fail = (message: string): false => {
@@ -117,13 +134,18 @@ export const runCredsPlan = async (
   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-target.ts

@@ -0,0 +1,57 @@
+import { isContainedSopsPath } from './creds-sops-structure';
+
+const SAFE_TARGET = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9_-])?$/u;
+
+export const isSafeSecretsTargetName = (target: string): boolean =>
+  SAFE_TARGET.test(target);
+
+export type TargetRelResolution =
+  | { readonly ok: true; readonly rel: string }
+  | {
+      readonly ok: false;
+      readonly kind: 'invalid' | 'missing' | 'ambiguous';
+      readonly problem: string;
+    };
+
+export const resolveTargetRelResult = (
+  consumer: string,
+  target: string,
+): TargetRelResolution => {
+  if (!isSafeSecretsTargetName(target)) {
+    return {
+      ok: false,
+      kind: 'invalid',
+      problem: `secrets target "${target}" is not a safe target name`,
+    };
+  }
+  const host = `infra/hosts/${target}/secrets.yaml`;
+  const flat = `secrets/${target}.yaml`;
+  const hostExists = isContainedSopsPath(consumer, host, 'file');
+  const flatExists = isContainedSopsPath(consumer, flat, 'file');
+  if (hostExists && flatExists) {
+    return {
+      ok: false,
+      kind: 'ambiguous',
+      problem: `secrets target "${target}" is ambiguous because both ${flat} and ${host} exist; rename one target so the name binds exactly one encrypted file`,
+    };
+  }
+  if (hostExists) {
+    return { ok: true, rel: host };
+  }
+  if (flatExists) {
+    return { ok: true, rel: flat };
+  }
+  return {
+    ok: false,
+    kind: 'missing',
+    problem: `secrets target "${target}" does not exist`,
+  };
+};
+
+export const resolveTargetRel = (
+  consumer: string,
+  target: string,
+): string | null => {
+  const resolved = resolveTargetRelResult(consumer, target);
+  return resolved.ok ? resolved.rel : null;
+};

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

@@ -0,0 +1,44 @@
+import { parseDestination } from './creds-dest';
+import type { DevEnvLayerKind } from './dev-env-document';
+
+export const BROKERED_REFERENCES_KEY = 'brokeredReferences';
+
+export type ParsedBrokeredAllowlist = {
+  readonly entries: ReadonlySet<string>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export const parseBrokeredAllowlist = (
+  source: string,
+  raw: unknown,
+  layerKind: DevEnvLayerKind,
+): ParsedBrokeredAllowlist => {
+  if (layerKind === 'configuration') {
+    return {
+      entries: new Set(),
+      problems: [
+        `${source} reserved top-level key "${BROKERED_REFERENCES_KEY}" belongs only in the SOPS-encrypted secrets/dev.yaml layer`,
+      ],
+    };
+  }
+  if (!Array.isArray(raw)) {
+    return {
+      entries: new Set(),
+      problems: [
+        `${source} "${BROKERED_REFERENCES_KEY}" must list exact "<target>:<dotted.key>" entries`,
+      ],
+    };
+  }
+  const entries = new Set<string>();
+  const problems: Array<string> = [];
+  for (const [index, entry] of raw.entries()) {
+    if (typeof entry !== 'string' || parseDestination(entry) === null) {
+      problems.push(
+        `${source} "${BROKERED_REFERENCES_KEY}" entry ${index + 1} must be an exact "<target>:<dotted.key>" string`,
+      );
+    } else {
+      entries.add(entry);
+    }
+  }
+  return { entries, problems };
+};

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

@@ -0,0 +1,65 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { DevEnvValue } from './dev-env-document';
+import { preserveRenderedDotenvValues, renderDotenv } from './dev-env-dotenv';
+
+export type DevEnvRunOptions = {
+  readonly preservedBrokeredReferences: ReadonlySet<string>;
+};
+
+type RenderInput = {
+  readonly consumer: string;
+  readonly rel: string;
+  readonly sourcePath: string;
+  readonly sources: ReadonlyArray<string>;
+  readonly resolvedEnv: Readonly<Record<string, string>>;
+  readonly composedEnv: Readonly<Record<string, DevEnvValue>>;
+  readonly preservedReferences: ReadonlySet<string>;
+};
+
+type RenderResult =
+  | { readonly ok: true; readonly content: string }
+  | { readonly ok: false; readonly problem: string };
+
+const preservedKeys = (
+  env: Readonly<Record<string, DevEnvValue>>,
+  references: ReadonlySet<string>,
+): ReadonlyArray<string> =>
+  Object.entries(env).flatMap(([key, value]) =>
+    typeof value !== 'string' &&
+    references.has(`${value.brokeredS3}:${value.key}`)
+      ? [key]
+      : [],
+  );
+
+export const renderDevEnvPreservingUnsafeReferences = (
+  input: RenderInput,
+): RenderResult => {
+  const rendered = renderDotenv(
+    input.sourcePath,
+    input.sources,
+    input.resolvedEnv,
+  );
+  const keys = preservedKeys(input.composedEnv, input.preservedReferences);
+  if (keys.length === 0) {
+    return { ok: true, content: rendered };
+  }
+  let previous: string;
+  try {
+    const path = join(input.consumer, input.rel);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+      throw new Error('not a regular file');
+    }
+    previous = readFileSync(path, 'utf8');
+  } catch {
+    return {
+      ok: false,
+      problem: `${input.rel} has no readable prior generated values for unsafe brokered references`,
+    };
+  }
+  const preserved = preserveRenderedDotenvValues(previous, rendered, keys);
+  return preserved.ok
+    ? preserved
+    : { ok: false, problem: `${input.rel}: ${preserved.problem}` };
+};