@davidvornholt/standards 0.14.1 → 0.15.1

package/src/creds-args.ts

@@ -0,0 +1,108 @@
+import { resolve } from 'node:path';
+import process from 'node:process';
+import {
+  DEFAULT_R2_JURISDICTION,
+  isR2Jurisdiction,
+  type R2Jurisdiction,
+} from './creds-r2';
+
+const DAY_MS = 86_400_000;
+const MAX_PROVIDER_EXPIRATION_MS = Date.parse('9999-12-31T23:59:59.999Z');
+const POSITIVE_INTEGER = /^[1-9][0-9]*$/u;
+
+export type CredsFlags = {
+  dir: string;
+  dest: string | undefined;
+  permissions: string | undefined;
+  account: string | undefined;
+  ttlDays: number | undefined;
+  bucket: string | undefined;
+  jurisdiction: R2Jurisdiction;
+  s3: boolean;
+  org: string | undefined;
+  name: string | undefined;
+  readonly words: Array<string>;
+};
+
+const flagValue = (argv: ReadonlyArray<string>, index: number): string => {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${argv[index]} requires a value`);
+  }
+  return value;
+};
+
+export const parseTtlDays = (raw: string): number => {
+  const ttlDays = Number(raw);
+  if (
+    !(POSITIVE_INTEGER.test(raw) && Number.isSafeInteger(ttlDays)) ||
+    Date.now() + ttlDays * DAY_MS > MAX_PROVIDER_EXPIRATION_MS
+  ) {
+    throw new Error('--ttl-days must be a provider-safe positive integer');
+  }
+  return ttlDays;
+};
+
+export const parseCredsArgs = (argv: ReadonlyArray<string>): CredsFlags => {
+  const flags: CredsFlags = {
+    dir: process.cwd(),
+    dest: undefined,
+    permissions: undefined,
+    account: undefined,
+    ttlDays: undefined,
+    bucket: undefined,
+    jurisdiction: DEFAULT_R2_JURISDICTION,
+    s3: false,
+    org: undefined,
+    name: undefined,
+    words: [],
+  };
+  const setters: Readonly<Record<string, (value: string) => void>> = {
+    '--dir': (value) => {
+      flags.dir = value;
+    },
+    '--dest': (value) => {
+      flags.dest = value;
+    },
+    '--permissions': (value) => {
+      flags.permissions = value;
+    },
+    '--account': (value) => {
+      flags.account = value;
+    },
+    '--ttl-days': (value) => {
+      flags.ttlDays = parseTtlDays(value);
+    },
+    '--bucket': (value) => {
+      flags.bucket = value;
+    },
+    '--jurisdiction': (value) => {
+      if (!isR2Jurisdiction(value)) {
+        throw new Error('--jurisdiction must be default or eu');
+      }
+      flags.jurisdiction = value;
+    },
+    '--org': (value) => {
+      flags.org = value;
+    },
+    '--name': (value) => {
+      flags.name = value;
+    },
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? '';
+    const setter = setters[arg];
+    if (arg === '--s3') {
+      flags.s3 = true;
+    } else if (setter !== undefined) {
+      setter(flagValue(argv, index));
+      index += 1;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown creds option: ${arg}`);
+    } else {
+      flags.words.push(arg);
+    }
+  }
+  flags.dir = resolve(flags.dir);
+  return flags;
+};

package/src/creds-cloudflare-expiry.ts

@@ -0,0 +1,7 @@
+// Cloudflare rejects fractional seconds in expires_on before creating the
+// token; it requires whole-second RFC3339 like "2005-12-30T01:02:03Z".
+
+const FRACTIONAL_SECONDS = /\.\d{3}Z$/u;
+
+export const cloudflareExpiresOn = (epochMs: number): string =>
+  new Date(epochMs).toISOString().replace(FRACTIONAL_SECONDS, 'Z');

package/src/creds-commands.ts

@@ -1,7 +1,6 @@
-import { resolve } from 'node:path';
-import process from 'node:process';
 import { runCredsAddCloudflare } from './creds-add';
 import { runCredsAddGithub } from './creds-add-github';
+import { parseCredsArgs } from './creds-args';
 import { listPermissionGroups } from './creds-cloudflare';
 import { runCredsLoginCloudflare } from './creds-login-cloudflare';
 import { runCredsLoginGithub } from './creds-login-github';
@@ -31,94 +30,13 @@ Options:
   --permissions <list>  Comma-separated Cloudflare permission group names
   --account <id>        Cloudflare account when more than one is configured
   --ttl-days <n>        Token lifetime in days (default: 90)
+  --bucket <name>       Scope a Cloudflare token to one R2 bucket
+  --jurisdiction <name> R2 jurisdiction: default or eu (default: default)
+  --s3                  Store the derived R2 S3 credential pair (<key>.access_key_id, <key>.secret_access_key) instead of the raw token
   --org <org>           Create the GitHub App under an organization
   --name <name>         GitHub App name (default: ${BROKER_IDENTITY_NAME})
 
 Secret values are written directly into SOPS-encrypted targets and never printed.`;
-const DAY_MS = 86_400_000;
-const MAX_PROVIDER_EXPIRATION_MS = Date.parse('9999-12-31T23:59:59.999Z');
-const POSITIVE_INTEGER = /^[1-9][0-9]*$/u;
-
-type CredsFlags = {
-  dir: string;
-  dest: string | undefined;
-  permissions: string | undefined;
-  account: string | undefined;
-  ttlDays: number | undefined;
-  org: string | undefined;
-  name: string | undefined;
-  readonly words: Array<string>;
-};
-
-const flagValue = (argv: ReadonlyArray<string>, index: number): string => {
-  const value = argv[index + 1];
-  if (value === undefined || value.startsWith('--')) {
-    throw new Error(`${argv[index]} requires a value`);
-  }
-  return value;
-};
-
-export const parseTtlDays = (raw: string): number => {
-  const ttlDays = Number(raw);
-  if (
-    !(POSITIVE_INTEGER.test(raw) && Number.isSafeInteger(ttlDays)) ||
-    Date.now() + ttlDays * DAY_MS > MAX_PROVIDER_EXPIRATION_MS
-  ) {
-    throw new Error('--ttl-days must be a provider-safe positive integer');
-  }
-  return ttlDays;
-};
-
-const parseCredsArgs = (argv: ReadonlyArray<string>): CredsFlags => {
-  const flags: CredsFlags = {
-    dir: process.cwd(),
-    dest: undefined,
-    permissions: undefined,
-    account: undefined,
-    ttlDays: undefined,
-    org: undefined,
-    name: undefined,
-    words: [],
-  };
-  const setters: Readonly<Record<string, (value: string) => void>> = {
-    '--dir': (value) => {
-      flags.dir = value;
-    },
-    '--dest': (value) => {
-      flags.dest = value;
-    },
-    '--permissions': (value) => {
-      flags.permissions = value;
-    },
-    '--account': (value) => {
-      flags.account = value;
-    },
-    '--ttl-days': (value) => {
-      flags.ttlDays = parseTtlDays(value);
-    },
-    '--org': (value) => {
-      flags.org = value;
-    },
-    '--name': (value) => {
-      flags.name = value;
-    },
-  };
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index] ?? '';
-    const setter = setters[arg];
-    if (setter !== undefined) {
-      setter(flagValue(argv, index));
-      index += 1;
-    } else if (arg.startsWith('--')) {
-      throw new Error(`Unknown creds option: ${arg}`);
-    } else {
-      flags.words.push(arg);
-    }
-  }
-  flags.dir = resolve(flags.dir);
-  return flags;
-};
-
 const runCredsStatus = async (): Promise<boolean> => {
   const path = resolveBrokerPath();
   const store = await readBrokerStore(path);

package/src/creds-plan-groups.ts

@@ -0,0 +1,29 @@
+import { destinationFootprintsIntersect } from './creds-r2';
+
+type FootprintedDestination = {
+  readonly ref: { readonly target: string };
+  readonly footprint: ReadonlyArray<string>;
+};
+
+const intersects = (
+  left: FootprintedDestination,
+  right: FootprintedDestination,
+): boolean =>
+  left.ref.target === right.ref.target &&
+  destinationFootprintsIntersect(left.footprint, right.footprint);
+
+export const groupByIntersectingFootprint = <
+  Destination extends FootprintedDestination,
+>(
+  destinations: ReadonlyArray<Destination>,
+): ReadonlyArray<ReadonlyArray<Destination>> =>
+  destinations.reduce<Array<ReadonlyArray<Destination>>>(
+    (groups, destination) => {
+      const intersecting = groups.filter((group) =>
+        group.some((candidate) => intersects(candidate, destination)),
+      );
+      const separate = groups.filter((group) => !intersecting.includes(group));
+      return [...separate, [...intersecting.flat(), destination]];
+    },
+    [],
+  );

package/src/creds-plan-renew.ts

@@ -0,0 +1,124 @@
+// Renewal execution for `standards creds apply`: create the replacement
+// first, durably write and verify the SOPS destination, and only then revoke
+// the old token. An unverifiable destination keeps both tokens; a verified
+// 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,
+  verifySopsStoredValue,
+} from './creds-sops';
+import type { CloudflareBrokerAccount } from './creds-store';
+
+type RenewAction = Extract<PlannedAction, { readonly kind: 'renew' }>;
+
+const cleanupReplacement = async (
+  account: CloudflareBrokerAccount,
+  replacementId: string,
+  oldId: string,
+  context: string,
+): Promise<string> => {
+  const { accountId, token } = account;
+  const cleanup = await deleteAccountToken(accountId, token, replacementId);
+  return cleanup.ok
+    ? `${context}; deleted replacement ${replacementId} and preserved old token ${oldId}`
+    : `${context}; cleanup of replacement ${replacementId} also failed: ${cleanup.problem}; old token ${oldId} remains active`;
+};
+
+const inspectRenewDestinations = async (
+  consumer: string,
+  rel: string,
+  action: RenewAction,
+): Promise<string | null> => {
+  const paths = action.format === 's3' ? s3PairPaths(action.key) : [action.key];
+  const inspected = await Promise.all(
+    paths.map((path) => inspectSopsScalarDestination(consumer, rel, path)),
+  );
+  const blocked = inspected.find((result) => !result.ok);
+  if (blocked !== undefined && !blocked.ok) {
+    return `${action.name}: ${blocked.problem}`;
+  }
+  return inspected.some((result) => result.ok && result.state !== 'scalar')
+    ? `${action.name}: secret ${action.target}:${action.key} disappeared before renewal`
+    : null;
+};
+
+export const renewPlannedToken = async (
+  consumer: string,
+  account: CloudflareBrokerAccount,
+  action: RenewAction,
+): Promise<string | null> => {
+  const { accountId, token: bootstrapToken } = account;
+  const rel = resolveTargetRel(consumer, action.target);
+  if (rel === null) {
+    return `${action.name}: secrets target ${action.target} not found`;
+  }
+  const destinationProblem = await inspectRenewDestinations(
+    consumer,
+    rel,
+    action,
+  );
+  if (destinationProblem !== null) {
+    return destinationProblem;
+  }
+  if (action.format === 's3') {
+    const accessKey = verifySopsStoredValue(
+      consumer,
+      rel,
+      s3AccessKeyPath(action.key),
+      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`;
+    }
+  }
+  const replacement = await createAccountToken(accountId, bootstrapToken, {
+    name: action.name,
+    policies: action.policies,
+    expiresOn: action.replacementExpiresOn,
+    condition: action.condition,
+  });
+  if (!replacement.ok) {
+    return `${action.name}: ${replacement.problem}`;
+  }
+  const { id: replacementId, value } = replacement.value;
+  const writes = destinationWrites(
+    action.format,
+    action.key,
+    replacementId,
+    value,
+  );
+  const written = setSopsValues(consumer, rel, writes);
+  const verified = writes.map((write) => ({
+    path: write.path,
+    result: verifySopsStoredValue(consumer, rel, write.path, write.value),
+  }));
+  const unverifiable = verified.flatMap(({ result }) =>
+    result.ok ? [] : [result.problem],
+  );
+  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`;
+  }
+  const mismatched = verified.flatMap(({ path, result }) =>
+    result.ok && !result.matches ? [path] : [],
+  );
+  if (mismatched.length > 0) {
+    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);
+  }
+  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}`;
+};

package/src/creds-plan-revoke.ts

@@ -1,5 +1,5 @@
 import { deleteAccountToken } from './creds-cloudflare';
-import type { PlannedAction } from './creds-plan';
+import type { PlannedAction } from './creds-plan-types';
 import type { CloudflareBrokerAccount } from './creds-store';
 
 export const revokePlannedToken = async (

package/src/creds-plan-run.ts

@@ -1,24 +1,12 @@
-import {
-  createAccountToken as createToken,
-  deleteAccountToken as deleteToken,
-} from './creds-cloudflare';
-import { listSecretsTargets, resolveTargetRel } from './creds-dest';
+import { listSecretsTargets } from './creds-dest';
 import { identifyCloudflareBootstrapAuthority } from './creds-login-cloudflare';
-import {
-  type AccountToken,
-  computeCredsPlan,
-  type PlannedAction,
-} from './creds-plan';
+import { computeCredsPlan } from './creds-plan';
+import { renewPlannedToken } from './creds-plan-renew';
 import { revokePlannedToken } from './creds-plan-revoke';
-import {
-  inspectSopsScalarDestination as inspectDestination,
-  readEncryptedKeys,
-  verifySopsStoredValue as verifyStoredValue,
-  setSopsValue as writeValue,
-} from './creds-sops';
+import type { AccountToken, PlannedAction } from './creds-plan-types';
+import { readEncryptedKeys } from './creds-sops';
 import {
   type BrokerStore,
-  type CloudflareBrokerAccount,
   readBrokerStore,
   resolveBrokerPath,
 } from './creds-store';
@@ -68,20 +56,7 @@ const gatherRepoState = async (consumer: string, store: BrokerStore) => {
   return { keysByTarget, tokens, problems };
 };
 
-const cleanupReplacement = async (
-  account: CloudflareBrokerAccount,
-  replacementId: string,
-  oldId: string,
-  context: string,
-): Promise<string> => {
-  const { accountId, token } = account;
-  const cleanup = await deleteToken(accountId, token, replacementId);
-  return cleanup.ok
-    ? `${context}; deleted replacement ${replacementId} and preserved old token ${oldId}`
-    : `${context}; cleanup of replacement ${replacementId} also failed: ${cleanup.problem}; old token ${oldId} remains active`;
-};
-
-const applyAction = async (
+const applyAction = (
   consumer: string,
   store: BrokerStore,
   action: PlannedAction,
@@ -90,48 +65,13 @@ const applyAction = async (
     (entry) => entry.accountId === action.accountId,
   );
   if (account === undefined) {
-    return `${action.name}: account ${action.accountId} is not in the broker store`;
-  }
-  const { accountId, token: bootstrapToken } = account;
-  if (action.kind === 'revoke') {
-    return revokePlannedToken(account, action);
-  }
-  const rel = resolveTargetRel(consumer, action.target);
-  if (rel === null) {
-    return `${action.name}: secrets target ${action.target} not found`;
-  }
-  const destination = await inspectDestination(consumer, rel, action.key);
-  if (!destination.ok) {
-    return `${action.name}: ${destination.problem}`;
-  }
-  if (destination.state !== 'scalar') {
-    return `${action.name}: secret ${action.target}:${action.key} disappeared before renewal`;
-  }
-  const replacement = await createToken(accountId, bootstrapToken, {
-    name: action.name,
-    policies: action.policies,
-    expiresOn: action.replacementExpiresOn,
-    condition: action.condition,
-  });
-  if (!replacement.ok) {
-    return `${action.name}: ${replacement.problem}`;
-  }
-  const { id: replacementId, value } = replacement.value;
-  const written = writeValue(consumer, rel, action.key, value);
-  const verified = verifyStoredValue(consumer, rel, action.key, value);
-  if (verified.ok && !verified.matches) {
-    const problem = written.ok
-      ? `${action.name}: ${rel} at ${action.key} 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);
-  }
-  if (!verified.ok) {
-    return `${action.name}: ${written.ok ? verified.problem : `${written.problem}; ${verified.problem}`}; account ${accountId} replacement ${replacementId} and old token ${action.tokenId} remain active because the stored value is unverifiable`;
+    return Promise.resolve(
+      `${action.name}: account ${action.accountId} is not in the broker store`,
+    );
   }
-  const deleted = await deleteToken(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 action.kind === 'revoke'
+    ? revokePlannedToken(account, action)
+    : renewPlannedToken(consumer, account, action);
 };
 
 const fail = (message: string): false => {

package/src/creds-plan-types.ts

@@ -0,0 +1,36 @@
+import type { CloudflareToken, TokenPolicy } from './creds-cloudflare-api';
+import type { TokenCondition } from './creds-cloudflare-condition';
+import type { DestinationFormat } from './creds-r2';
+
+export type AccountToken = {
+  readonly accountId: string;
+  readonly token: CloudflareToken;
+};
+
+export type PlannedAction =
+  | {
+      readonly kind: 'revoke';
+      readonly accountId: string;
+      readonly tokenId: string;
+      readonly name: string;
+      readonly reason: string;
+    }
+  | {
+      readonly kind: 'renew';
+      readonly accountId: string;
+      readonly tokenId: string;
+      readonly name: string;
+      readonly target: string;
+      readonly key: string;
+      readonly format: DestinationFormat;
+      readonly policies: ReadonlyArray<TokenPolicy>;
+      readonly condition: TokenCondition | null;
+      readonly replacementExpiresOn: string;
+      readonly reason: string;
+    };
+
+export type CredsPlan = {
+  readonly actions: ReadonlyArray<PlannedAction>;
+  readonly findings: ReadonlyArray<string>;
+  readonly healthy: number;
+};

package/src/creds-plan.ts

@@ -5,47 +5,22 @@
 // lifetime. Secret keys without a brokered token are simply unmanaged — most
 // secrets are — and are never touched. Execution lives in creds-plan-run.ts.
 
-import type { CloudflareToken, TokenPolicy } from './creds-cloudflare-api';
-import type { TokenCondition } from './creds-cloudflare-condition';
+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 { destinationFormatOf, inferredDestinationFootprint } from './creds-r2';
 
 const DEFAULT_RENEW_WITHIN_DAYS = 30;
 const DAY_MS = 86_400_000;
 
-export type AccountToken = {
-  readonly accountId: string;
-  readonly token: CloudflareToken;
-};
-
-export type PlannedAction =
-  | {
-      readonly kind: 'revoke';
-      readonly accountId: string;
-      readonly tokenId: string;
-      readonly name: string;
-      readonly reason: string;
-    }
-  | {
-      readonly kind: 'renew';
-      readonly accountId: string;
-      readonly tokenId: string;
-      readonly name: string;
-      readonly target: string;
-      readonly key: string;
-      readonly policies: ReadonlyArray<TokenPolicy>;
-      readonly condition: TokenCondition | null;
-      readonly replacementExpiresOn: string;
-      readonly reason: string;
-    };
-
-export type CredsPlan = {
-  readonly actions: ReadonlyArray<PlannedAction>;
-  readonly findings: ReadonlyArray<string>;
-  readonly healthy: number;
-};
-
 type ManagedToken = AccountToken & {
   readonly ref: { readonly target: string; readonly key: string };
+  readonly footprint: ReadonlyArray<string>;
 };
 
 type Disposition =
@@ -69,7 +44,11 @@ const dispositionOf = (
       finding: `${token.name} (${accountId}/${token.id}) has status ${token.status}; it is not healthy and will not be mutated automatically`,
     };
   }
-  if (!input.keysByTarget.get(ref.target)?.has(ref.key)) {
+  const format = destinationFormatOf(
+    input.keysByTarget.get(ref.target),
+    ref.key,
+  );
+  if (format === 'absent') {
     return {
       kind: 'action',
       action: {
@@ -79,6 +58,12 @@ const dispositionOf = (
       },
     };
   }
+  if (format === 'partial') {
+    return {
+      kind: 'finding',
+      finding: `${token.name} maps to an incomplete S3 credential pair at ${ref.target}:${ref.key} (expected both access_key_id and secret_access_key); it will not be mutated automatically`,
+    };
+  }
   if (!token.condition.supported) {
     return {
       kind: 'finding',
@@ -118,11 +103,12 @@ const dispositionOf = (
       kind: 'renew',
       target: ref.target,
       key: ref.key,
+      format,
       policies: token.policies,
       condition: token.condition.value,
-      replacementExpiresOn: new Date(
+      replacementExpiresOn: cloudflareExpiresOn(
         input.now.getTime() + expiry - issued,
-      ).toISOString(),
+      ),
       reason: `expires ${token.expiresOn}`,
     },
   };
@@ -140,7 +126,7 @@ const dispositionForGroup = (
     const [first] = group;
     return {
       kind: 'finding',
-      finding: `ambiguous Cloudflare tokens target ${first?.ref.target}:${first?.ref.key} across ${group.map((candidate) => `${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(', ')}; revoke duplicates manually before plan/apply`,
     };
   }
   const [entry] = group;
@@ -163,13 +149,20 @@ export const computeCredsPlan = (input: {
   let healthy = 0;
   const managed = input.tokens.flatMap((entry) => {
     const ref = parseTokenName(entry.token.name, input.repo);
-    return ref === null ? [] : [{ ...entry, ref }];
+    return ref === null
+      ? []
+      : [
+          {
+            ...entry,
+            ref,
+            footprint: inferredDestinationFootprint(
+              input.keysByTarget.get(ref.target),
+              ref.key,
+            ),
+          },
+        ];
   });
-  const byDestination = Map.groupBy(
-    managed,
-    ({ ref }) => `${ref.target}\0${ref.key}`,
-  );
-  const dispositions = [...byDestination.values()].map((group) =>
+  const dispositions = groupByIntersectingFootprint(managed).map((group) =>
     dispositionForGroup(group, input, renewWithin),
   );
   for (const disposition of dispositions) {