@davidvornholt/standards 0.20.0 → 0.22.0

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

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

@@ -10,6 +10,13 @@ const OWNER_ONLY_FILE_MODE = 0o600;
 const HOLDER_PREFIX = 'holder-';
 const HOLDER_SUFFIX = '.json';
 const LEASE_DIVISOR = 3;
+// Both codes mean the lock is no longer this owner's to clean up. ENOENT: it is
+// already gone. ENOTEMPTY: a contender published its own generation into the
+// directory during the moment the unlink left it empty — renaming onto an empty
+// directory succeeds, which is exactly how a waiter takes the lock. Releasing
+// runs from a finally, so throwing here would replace the result of an
+// operation that already succeeded.
+const RELEASABLE_RMDIR_CODES = ['ENOENT', 'ENOTEMPTY'] as const;
 
 export type HeldBrokerLock = {
   readonly holderPath: string;
@@ -91,7 +98,7 @@ export const releaseBrokerLock = async ({
   try {
     await rmdir(lockPath);
   } catch (error) {
-    if (!isErrorCode(error, 'ENOENT')) {
+    if (!RELEASABLE_RMDIR_CODES.some((code) => isErrorCode(error, code))) {
       throw error;
     }
   }

package/src/creds-store-lock.ts

@@ -2,7 +2,8 @@
 // place before its operation starts. A worker-thread lease remains live while
 // synchronous SOPS/Nix blocks the main event loop. Cleanup unlinks the exact
 // generation token before removing the directory, so an old owner cannot
-// remove a replacement.
+// remove a replacement — and finding one there instead of an empty directory
+// is a no-op, never a failure of the operation being unwound.
 
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';

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

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

@@ -0,0 +1,129 @@
+// After the creds broker writes into a SOPS target, the generated dev env
+// files are stale if any workspace env key references a brokered pair in
+// that target. Regenerating here closes the rotation loop: a renewed pair
+// reaches every generated .env.local without a manual copy step.
+
+import { resolveTargetRelResult } from './creds-target';
+import { runDevEnv } from './dev-env';
+import { parseDevEnvDocument } from './dev-env-document';
+import { readPlainLayer } from './dev-env-plain-layer';
+
+const DEV_PLAIN_LAYERS = ['config/dev.yaml', 'config/dev.local.yaml'] as const;
+
+type LayerReferenceDiscovery = {
+  readonly references: ReadonlyArray<{
+    readonly target: string;
+    readonly key: string;
+  }>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+const layerReferenceTargets = (
+  consumer: string,
+  layerRel: string,
+): LayerReferenceDiscovery => {
+  const layer = readPlainLayer(consumer, layerRel);
+  if (layer.input === null) {
+    return { references: [], problems: layer.problems };
+  }
+  const document = parseDevEnvDocument(
+    layer.input.raw,
+    layerRel,
+    'configuration',
+  );
+  return {
+    references: document.targets.flatMap((target) =>
+      Object.values(target.env).flatMap((value) =>
+        typeof value === 'string'
+          ? []
+          : [{ target: value.brokeredS3, key: value.key }],
+      ),
+    ),
+    problems: [...layer.problems, ...document.problems],
+  };
+};
+
+type BrokeredReferenceDiscovery = {
+  readonly references: ReadonlySet<string>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+export type BrokeredRefreshEvidence = {
+  readonly target: string;
+  readonly key: string;
+  readonly safety: 'verified' | 'unsafe';
+};
+
+const referenceIdentity = (target: string, key: string): string =>
+  `${target}:${key}`;
+
+const discoverBrokeredReferenceRels = (
+  consumer: string,
+): BrokeredReferenceDiscovery => {
+  const references = new Set<string>();
+  const problems: Array<string> = [];
+  for (const layerRel of DEV_PLAIN_LAYERS) {
+    const layer = layerReferenceTargets(consumer, layerRel);
+    problems.push(...layer.problems);
+    for (const reference of layer.references) {
+      const resolved = resolveTargetRelResult(consumer, reference.target);
+      if (resolved.ok) {
+        references.add(referenceIdentity(reference.target, reference.key));
+      } else {
+        problems.push(
+          resolved.kind === 'ambiguous'
+            ? `dev config references ${resolved.problem}`
+            : `dev config references secrets target "${reference.target}", but it is missing or is not a contained regular SOPS file`,
+        );
+      }
+    }
+  }
+  return { references, problems };
+};
+
+export const refreshDevEnvForSopsWrites = async (
+  consumer: string,
+  evidence: ReadonlyArray<BrokeredRefreshEvidence>,
+): Promise<boolean> => {
+  if (evidence.length === 0) {
+    return true;
+  }
+  const discovery = discoverBrokeredReferenceRels(consumer);
+  if (discovery.problems.length > 0) {
+    console.error(
+      `standards creds: cannot determine whether changed credentials require dev env regeneration because the configuration has ${discovery.problems.length} problem(s):`,
+    );
+    console.error(
+      discovery.problems.map((problem) => `  - ${problem}`).join('\n'),
+    );
+    console.error(
+      'standards creds: credential changes were written, but generated .env.local files were not updated; fix the configuration and run `bun standards dev-env`',
+    );
+    return false;
+  }
+  const unsafe = new Set(
+    evidence
+      .filter((entry) => entry.safety === 'unsafe')
+      .map((entry) => referenceIdentity(entry.target, entry.key)),
+  );
+  const verified = new Set(
+    evidence
+      .filter((entry) => entry.safety === 'verified')
+      .map((entry) => referenceIdentity(entry.target, entry.key)),
+  );
+  const changedReferences = [...verified].filter(
+    (reference) =>
+      discovery.references.has(reference) && !unsafe.has(reference),
+  );
+  if (changedReferences.length === 0) {
+    return true;
+  }
+  console.log(
+    'standards creds: regenerating dev env files (a brokered pair referenced by the dev config changed)',
+  );
+  return await runDevEnv(consumer, {
+    preservedBrokeredReferences: new Set(
+      [...unsafe].filter((reference) => discovery.references.has(reference)),
+    ),
+  });
+};

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

@@ -0,0 +1,158 @@
+// Resolves brokered S3 pair references in the composed dev env into literal
+// values by decrypting each referenced SOPS target once. Resolution runs
+// after layer composition so a later layer's literal can override an earlier
+// layer's reference, and a reference that lost the merge is never decrypted.
+
+import { resolveTargetRelResult } from './creds-target';
+import type { BrokeredS3Reference } from './dev-env-brokered';
+import type { ComposedDevEnvTarget } from './dev-env-compose';
+import { encodeBunDotenvValue } from './dev-env-dotenv-value';
+import { isRecord } from './github-settings-parse';
+import { runSops } from './sops-exec';
+
+export type ResolvedDevEnvTarget = {
+  readonly group: string;
+  readonly workspace: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly sources: ReadonlyArray<string>;
+};
+
+export type ResolvedDevEnv = {
+  readonly targets: ReadonlyArray<ResolvedDevEnvTarget>;
+  readonly problems: ReadonlyArray<string>;
+};
+
+type SopsDocumentResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly problem: string };
+
+const decryptSopsJson = (consumer: string, rel: string): SopsDocumentResult => {
+  const result = runSops(['--decrypt', '--output-type', 'json', rel], consumer);
+  if (result.status !== 0) {
+    const detail = result.errorMessage ?? result.stderr.trim();
+    return {
+      ok: false,
+      problem: detail
+        ? `could not decrypt ${rel}: ${detail}`
+        : `could not decrypt ${rel}`,
+    };
+  }
+  try {
+    return { ok: true, value: JSON.parse(result.stdout) as unknown };
+  } catch (error) {
+    return {
+      ok: false,
+      problem: `could not parse decrypted ${rel} as JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
+  }
+};
+
+const lookupReference = (
+  document: unknown,
+  reference: BrokeredS3Reference,
+): { readonly value: string | null; readonly problem: string | null } => {
+  let node: unknown = document;
+  for (const segment of reference.key.split('.')) {
+    if (!isRecord(node) || node[segment] === undefined) {
+      return {
+        value: null,
+        problem: `has no key "${reference.key}"; mint the pair with \`bun standards creds add cloudflare --s3 --dest ${reference.brokeredS3}:${reference.key}\``,
+      };
+    }
+    node = node[segment];
+  }
+  if (
+    !isRecord(node) ||
+    typeof node.access_key_id !== 'string' ||
+    typeof node.secret_access_key !== 'string'
+  ) {
+    return {
+      value: null,
+      problem: `key "${reference.key}" does not hold a complete brokered S3 pair; both "access_key_id" and "secret_access_key" must be strings`,
+    };
+  }
+  return { value: node[reference.part] as string, problem: null };
+};
+
+export const resolveBrokeredReferences = (
+  consumer: string,
+  targets: ReadonlyArray<ComposedDevEnvTarget>,
+  allowedReferences: ReadonlySet<string>,
+  preservedReferences: ReadonlySet<string> = new Set(),
+): ResolvedDevEnv => {
+  const problems: Array<string> = [];
+  const documents = new Map<string, SopsDocumentResult>();
+  const readDocument = (targetName: string): SopsDocumentResult => {
+    const cached = documents.get(targetName);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const resolved = resolveTargetRelResult(consumer, targetName);
+    const result = resolved.ok
+      ? decryptSopsJson(consumer, resolved.rel)
+      : {
+          ok: false as const,
+          problem:
+            resolved.kind === 'ambiguous'
+              ? resolved.problem
+              : `secrets target "${targetName}" does not exist; create it and mint the pair with \`bun standards creds add cloudflare --s3\``,
+        };
+    documents.set(targetName, result);
+    return result;
+  };
+  const resolveValue = (
+    label: string,
+    reference: BrokeredS3Reference,
+  ): { readonly value: string | null; readonly problem: string | null } => {
+    const allowlistEntry = `${reference.brokeredS3}:${reference.key}`;
+    if (!allowedReferences.has(allowlistEntry)) {
+      return {
+        value: null,
+        problem: `${label}: unauthorized brokered S3 pair; add "${allowlistEntry}" to the encrypted secrets/dev.yaml brokeredReferences allowlist`,
+      };
+    }
+    if (preservedReferences.has(allowlistEntry)) {
+      return { value: '', problem: null };
+    }
+    const document = readDocument(reference.brokeredS3);
+    if (!document.ok) {
+      return { value: null, problem: `${label}: ${document.problem}` };
+    }
+    const lookup = lookupReference(document.value, reference);
+    if (lookup.value === null) {
+      return { value: null, problem: `${label}: ${lookup.problem}` };
+    }
+    if (encodeBunDotenvValue(lookup.value) === null) {
+      return {
+        value: null,
+        problem: `${label}: resolved value cannot be represented losslessly in Bun dotenv syntax`,
+      };
+    }
+    return { value: lookup.value, problem: null };
+  };
+  const resolved = targets.map((target) => {
+    const env = Object.create(null) as Record<string, string>;
+    for (const [key, value] of Object.entries(target.env)) {
+      if (typeof value === 'string') {
+        env[key] = value;
+      } else {
+        const label = `${target.group}.${target.workspace}.${key} reference to secrets target "${value.brokeredS3}"`;
+        const outcome = resolveValue(label, value);
+        if (outcome.value === null) {
+          problems.push(outcome.problem ?? `${label}: unresolved reference`);
+        } else {
+          env[key] = outcome.value;
+        }
+      }
+    }
+    return {
+      group: target.group,
+      workspace: target.workspace,
+      env,
+      sources: target.sources,
+    };
+  });
+  return { targets: resolved, problems };
+};