@davidvornholt/standards 0.13.0 → 0.14.1

package/src/creds-cloudflare-condition.ts

@@ -0,0 +1,63 @@
+import { isRecord } from './github-settings-parse';
+
+export type TokenCondition = {
+  readonly requestIp: {
+    readonly in?: ReadonlyArray<string>;
+    readonly notIn?: ReadonlyArray<string>;
+  };
+};
+
+export type DecodedTokenCondition =
+  | { readonly supported: true; readonly value: TokenCondition | null }
+  | { readonly supported: false };
+
+const stringArray = (value: unknown): value is ReadonlyArray<string> =>
+  Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+
+export const decodeTokenCondition = (raw: unknown): DecodedTokenCondition => {
+  if (raw === undefined || raw === null) {
+    return { supported: true, value: null };
+  }
+  if (!isRecord(raw) || Object.keys(raw).some((key) => key !== 'request_ip')) {
+    return { supported: false };
+  }
+  const requestIp = raw.request_ip;
+  if (
+    !isRecord(requestIp) ||
+    Object.keys(requestIp).some((key) => key !== 'in' && key !== 'not_in') ||
+    ('in' in requestIp && !stringArray(requestIp.in)) ||
+    ('not_in' in requestIp && !stringArray(requestIp.not_in))
+  ) {
+    return { supported: false };
+  }
+  return {
+    supported: true,
+    value: {
+      requestIp: {
+        ...('in' in requestIp
+          ? { in: requestIp.in as ReadonlyArray<string> }
+          : {}),
+        ...('not_in' in requestIp
+          ? { notIn: requestIp.not_in as ReadonlyArray<string> }
+          : {}),
+      },
+    },
+  };
+};
+
+export const encodeTokenCondition = (
+  condition: TokenCondition,
+): Readonly<Record<string, unknown>> => ({
+  // biome-ignore lint/style/useNamingConvention: Cloudflare's condition wire field is snake_case.
+  request_ip: {
+    ...(condition.requestIp.in === undefined
+      ? {}
+      : { in: condition.requestIp.in }),
+    ...(condition.requestIp.notIn === undefined
+      ? {}
+      : {
+          // biome-ignore lint/style/useNamingConvention: Cloudflare's condition wire field is snake_case.
+          not_in: condition.requestIp.notIn,
+        }),
+  },
+});

package/src/creds-cloudflare-pagination.ts

@@ -0,0 +1,49 @@
+import {
+  type CfResult,
+  type CloudflareToken,
+  type ResultInfo,
+  tokenOf,
+} from './creds-cloudflare-api';
+
+export const decodeCloudflareTokenPage = (
+  result: unknown,
+): CfResult<ReadonlyArray<CloudflareToken>> => {
+  if (!Array.isArray(result)) {
+    return { ok: false, problem: 'token list returned a non-array result' };
+  }
+  const tokens = result
+    .map(tokenOf)
+    .filter((entry): entry is CloudflareToken => entry !== null);
+  return tokens.length === result.length
+    ? { ok: true, value: tokens }
+    : { ok: false, problem: 'token list returned a malformed token' };
+};
+
+export const cloudflarePaginationProblem = (input: {
+  readonly page: number;
+  readonly resultLength: number;
+  readonly resultInfo: ResultInfo;
+  readonly accumulated: number;
+  readonly expectedTotal: number;
+  readonly duplicate: boolean;
+}): string | null => {
+  if (
+    input.resultInfo.page !== input.page ||
+    input.resultInfo.count !== input.resultLength
+  ) {
+    return `token list returned inconsistent pagination metadata for page ${input.page}`;
+  }
+  if (
+    input.resultInfo.totalCount !== input.expectedTotal ||
+    input.accumulated + input.resultLength > input.expectedTotal
+  ) {
+    return `token list returned an inconsistent total_count for page ${input.page}`;
+  }
+  if (
+    input.duplicate ||
+    (input.resultLength === 0 && input.accumulated < input.expectedTotal)
+  ) {
+    return `token list made no unique progress on page ${input.page}`;
+  }
+  return null;
+};

package/src/creds-cloudflare.ts

@@ -0,0 +1,197 @@
+// Cloudflare account-owned API token operations for `standards creds`: the
+// broker bootstrap token (permission "Account API Tokens Write") verifies
+// itself, lists and mints scoped tokens, and revokes them. Token values
+// returned by create flow only into SOPS writers,
+// never stdout.
+
+import {
+  type CfResult,
+  type CloudflareToken,
+  cfRequest,
+  type PermissionGroup,
+  type TokenPolicy,
+} from './creds-cloudflare-api';
+import {
+  encodeTokenCondition,
+  type TokenCondition,
+} from './creds-cloudflare-condition';
+import {
+  cloudflarePaginationProblem,
+  decodeCloudflareTokenPage,
+} from './creds-cloudflare-pagination';
+import { isRecord } from './github-settings-parse';
+
+const PAGE_SIZE = 50;
+
+export type VerifiedToken = {
+  readonly id: string;
+  readonly status: string;
+};
+
+export const verifyAccountToken = async (
+  accountId: string,
+  token: string,
+): Promise<CfResult<VerifiedToken>> => {
+  const response = await cfRequest(
+    token,
+    'GET',
+    `/accounts/${accountId}/tokens/verify`,
+  );
+  if (!response.ok) {
+    return response;
+  }
+  const result = isRecord(response.value.result) ? response.value.result : {};
+  if (typeof result.id !== 'string' || result.id.length === 0) {
+    return {
+      ok: false,
+      problem: 'token verification returned no valid token ID',
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      id: result.id,
+      status: typeof result.status === 'string' ? result.status : 'unknown',
+    },
+  };
+};
+
+export const listAccountTokens = async (
+  accountId: string,
+  token: string,
+): Promise<CfResult<ReadonlyArray<CloudflareToken>>> => {
+  const tokens: Array<CloudflareToken> = [];
+  const tokenIds = new Set<string>();
+  let expectedTotal: number | null = null;
+  for (let page = 1; ; page += 1) {
+    // biome-ignore lint/performance/noAwaitInLoops: pages are sequential by definition; the next request depends on the previous page count.
+    const response = await cfRequest(
+      token,
+      'GET',
+      `/accounts/${accountId}/tokens?include_expired=true&page=${page}&per_page=${PAGE_SIZE}`,
+    );
+    if (!response.ok) {
+      return response;
+    }
+    const { result, resultInfo } = response.value;
+    const decoded = decodeCloudflareTokenPage(result);
+    if (!decoded.ok) {
+      return decoded;
+    }
+    const pageTokens = decoded.value;
+    if (resultInfo === null) {
+      return {
+        ok: false,
+        problem:
+          'token list returned invalid pagination metadata (expected page, per_page, count, and total_count)',
+      };
+    }
+    expectedTotal ??= resultInfo.totalCount;
+    const problem = cloudflarePaginationProblem({
+      page,
+      resultLength: pageTokens.length,
+      resultInfo,
+      accumulated: tokens.length,
+      expectedTotal,
+      duplicate:
+        new Set(pageTokens.map((entry) => entry.id)).size !==
+          pageTokens.length ||
+        pageTokens.some((entry) => tokenIds.has(entry.id)),
+    });
+    if (problem !== null) {
+      return { ok: false, problem };
+    }
+    for (const pageToken of pageTokens) {
+      tokenIds.add(pageToken.id);
+    }
+    tokens.push(...pageTokens);
+    if (tokens.length === expectedTotal) {
+      return { ok: true, value: tokens };
+    }
+  }
+};
+
+export const listPermissionGroups = async (
+  accountId: string,
+  token: string,
+): Promise<CfResult<ReadonlyArray<PermissionGroup>>> => {
+  const response = await cfRequest(
+    token,
+    'GET',
+    `/accounts/${accountId}/tokens/permission_groups?per_page=1000`,
+  );
+  if (!response.ok) {
+    return response;
+  }
+  const groups = Array.isArray(response.value.result)
+    ? response.value.result
+        .filter(isRecord)
+        .filter(
+          (group): group is Record<string, unknown> & PermissionGroup =>
+            typeof group.id === 'string' &&
+            typeof group.name === 'string' &&
+            Array.isArray(group.scopes) &&
+            group.scopes.every((scope) => typeof scope === 'string'),
+        )
+        .map((group) => ({
+          id: group.id,
+          name: group.name,
+          scopes: group.scopes,
+        }))
+    : [];
+  return { ok: true, value: groups };
+};
+
+export type CreatedToken = { readonly id: string; readonly value: string };
+
+export const createAccountToken = async (
+  accountId: string,
+  token: string,
+  request: {
+    readonly name: string;
+    readonly policies: ReadonlyArray<TokenPolicy>;
+    readonly expiresOn: string | null;
+    readonly condition: TokenCondition | null;
+  },
+): Promise<CfResult<CreatedToken>> => {
+  const response = await cfRequest(
+    token,
+    'POST',
+    `/accounts/${accountId}/tokens`,
+    {
+      name: request.name,
+      policies: request.policies,
+      ...(request.expiresOn === null ? {} : { expires_on: request.expiresOn }),
+      ...(request.condition === null
+        ? {}
+        : { condition: encodeTokenCondition(request.condition) }),
+    },
+  );
+  if (!response.ok) {
+    return response;
+  }
+  const { result } = response.value;
+  if (
+    !(
+      isRecord(result) &&
+      typeof result.id === 'string' &&
+      typeof result.value === 'string'
+    )
+  ) {
+    return { ok: false, problem: 'token creation returned no id and value' };
+  }
+  return { ok: true, value: { id: result.id, value: result.value } };
+};
+
+export const deleteAccountToken = async (
+  accountId: string,
+  token: string,
+  tokenId: string,
+): Promise<CfResult<null>> => {
+  const response = await cfRequest(
+    token,
+    'DELETE',
+    `/accounts/${accountId}/tokens/${tokenId}`,
+  );
+  return response.ok ? { ok: true, value: null } : response;
+};

package/src/creds-commands.ts

@@ -0,0 +1,200 @@
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { runCredsAddCloudflare } from './creds-add';
+import { runCredsAddGithub } from './creds-add-github';
+import { listPermissionGroups } from './creds-cloudflare';
+import { runCredsLoginCloudflare } from './creds-login-cloudflare';
+import { runCredsLoginGithub } from './creds-login-github';
+import { BROKER_IDENTITY_NAME } from './creds-naming';
+import { runCredsPlan } from './creds-plan-run';
+import {
+  inspectBrokerFileMode,
+  readBrokerStore,
+  resolveBrokerPath,
+} from './creds-store';
+
+const CREDS_USAGE = `Usage: standards creds <command> [options]
+
+Commands:
+  login github      Create the broker GitHub App via the manifest flow (one click) and store its credentials
+  login cloudflare  Store a Cloudflare account's bootstrap token (one guided paste per account)
+  add cloudflare    Mint a scoped, expiring account token and write it into a SOPS target
+  add github        Write the broker App's credentials into a SOPS target for runtime token minting
+  plan              Show revocations and rotations reconciling SOPS keys against brokered tokens
+  apply             Execute the plan: revoke orphaned tokens, roll expiring ones into SOPS
+  permissions       List Cloudflare permission group names for --permissions
+  status            Show the broker store location and configured providers
+
+Options:
+  --dir <path>          Repository to operate on (default: current directory)
+  --dest <target>:<key> SOPS destination, e.g. ci:ci.cloudflare_dns_token
+  --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)
+  --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);
+  console.log(`broker store: ${path}`);
+  const mode = inspectBrokerFileMode(path);
+  if (!mode.exists) {
+    console.log('  (not created yet)');
+  } else if (mode.problem !== null) {
+    console.log(`  WARNING: ${mode.problem}`);
+  }
+  console.log(
+    store.github === null
+      ? 'github: not configured (`standards creds login github`)'
+      : `github: App ${store.github.slug} (id ${store.github.appId}) — ${store.github.htmlUrl}`,
+  );
+  console.log(
+    store.cloudflare.length === 0
+      ? 'cloudflare: not configured (`standards creds login cloudflare`)'
+      : `cloudflare: ${store.cloudflare.map((entry) => entry.accountId).join(', ')}`,
+  );
+  return true;
+};
+
+const runCredsPermissions = async (
+  account: string | undefined,
+): Promise<boolean> => {
+  const store = await readBrokerStore(resolveBrokerPath());
+  const selected =
+    account === undefined && store.cloudflare.length === 1
+      ? store.cloudflare[0]
+      : store.cloudflare.find((entry) => entry.accountId === account);
+  if (selected === undefined) {
+    console.error(
+      'standards creds: configure an account with `standards creds login cloudflare` (pass --account when several are configured)',
+    );
+    return false;
+  }
+  const groups = await listPermissionGroups(selected.accountId, selected.token);
+  if (!groups.ok) {
+    console.error(`standards creds: ${groups.problem}`);
+    return false;
+  }
+  for (const group of [...groups.value].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
+    console.log(group.name);
+  }
+  return true;
+};
+
+export const runCredsCommand = (
+  argv: ReadonlyArray<string>,
+): Promise<boolean> => {
+  const flags = parseCredsArgs(argv);
+  const route = flags.words.join(' ');
+  if (route === '' || route === 'help') {
+    console.log(CREDS_USAGE);
+    return Promise.resolve(route === 'help');
+  }
+  const handlers: Readonly<Record<string, () => Promise<boolean>>> = {
+    'login github': () =>
+      runCredsLoginGithub({ name: flags.name, org: flags.org }),
+    'login cloudflare': () =>
+      runCredsLoginCloudflare({ account: flags.account }),
+    'add cloudflare': () => runCredsAddCloudflare(flags.dir, flags),
+    'add github': () => runCredsAddGithub(flags.dir, flags),
+    plan: () => runCredsPlan(flags.dir, false),
+    apply: () => runCredsPlan(flags.dir, true),
+    permissions: () => runCredsPermissions(flags.account),
+    status: () => runCredsStatus(),
+  };
+  const handler = handlers[route];
+  if (handler === undefined) {
+    console.error(`standards creds: unknown command: ${route}\n`);
+    console.error(CREDS_USAGE);
+    return Promise.resolve(false);
+  }
+  return handler();
+};

package/src/creds-dest.ts

@@ -0,0 +1,183 @@
+// Shared destination validation and repository/SOPS target resolution for
+// `standards creds add`. Untrusted paths are rejected before any SOPS or
+// provider operation can run.
+
+import { lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isContainedSopsPath, parseSopsKeyPath } from './creds-sops-structure';
+import {
+  type BrokerStore,
+  type CloudflareBrokerAccount,
+  readBrokerStore,
+  resolveBrokerPath,
+} from './creds-store';
+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 ResolvedContext = {
+  readonly repo: string;
+  readonly rel: string;
+  readonly dest: CredsDestination;
+  readonly store: BrokerStore;
+};
+
+export const parseDestination = (raw: string): CredsDestination | null => {
+  const separator = raw.indexOf(':');
+  const target = raw.slice(0, separator);
+  const key = raw.slice(separator + 1);
+  return separator > 0 &&
+    separator < raw.length - 1 &&
+    SAFE_TARGET.test(target) &&
+    parseSopsKeyPath(key) !== null
+    ? { target, key }
+    : null;
+};
+
+export const assertWritableSopsPath = (
+  root: Readonly<Record<string, unknown>>,
+  path: ReadonlyArray<string>,
+): void => {
+  let node: unknown = root;
+  for (const [index, segment] of path.entries()) {
+    if (!isRecord(node)) {
+      throw new Error(
+        `SOPS key path is blocked by a scalar: ${path.join('.')}`,
+      );
+    }
+    const next = node[segment];
+    if (next === undefined) {
+      return;
+    }
+    if (index === path.length - 1 && isRecord(next)) {
+      throw new Error(`SOPS key path names a mapping: ${path.join('.')}`);
+    }
+    node = next;
+  }
+};
+
+const isYamlSecrets = (name: string): boolean =>
+  name.endsWith('.yaml') && !name.endsWith('.example.yaml');
+const listDir = (consumer: string, rel: string): ReadonlyArray<string> => {
+  if (!isContainedSopsPath(consumer, rel, 'directory')) {
+    return [];
+  }
+  try {
+    return readdirSync(join(consumer, rel));
+  } catch {
+    return [];
+  }
+};
+const isHostTargetCandidate = (consumer: string, name: string): boolean => {
+  const rel = `infra/hosts/${name}`;
+  if (isContainedSopsPath(consumer, rel, 'directory')) {
+    return listDir(consumer, rel).includes('secrets.yaml');
+  }
+  try {
+    return lstatSync(join(consumer, rel)).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+
+export const listSecretsTargets = (
+  consumer: string,
+): ReadonlyArray<SecretsTarget> => {
+  const flat = listDir(consumer, 'secrets')
+    .filter(isYamlSecrets)
+    .map((name) => ({
+      target: name.slice(0, -'.yaml'.length),
+      rel: `secrets/${name}`,
+    }))
+    .filter(({ target }) => SAFE_TARGET.test(target));
+  const hosts = listDir(consumer, 'infra/hosts')
+    .filter(
+      (name) => SAFE_TARGET.test(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 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;
+};
+
+export const resolveContext = async (
+  consumer: string,
+  destRaw: string | undefined,
+): Promise<ResolvedContext | null> => {
+  if (destRaw === undefined) {
+    console.error(
+      'standards creds: --dest <target>:<dotted.key> is required (e.g. --dest ci:ci.cloudflare_dns_token)',
+    );
+    return null;
+  }
+  const dest = parseDestination(destRaw);
+  if (dest === null) {
+    console.error(`standards creds: invalid --dest value: ${destRaw}`);
+    return null;
+  }
+  const repo = resolveGithubRepo(consumer);
+  if (repo === null) {
+    console.error(
+      'standards creds: cannot resolve the GitHub repository from the origin remote',
+    );
+    return null;
+  }
+  const rel = resolveTargetRel(consumer, dest.target);
+  if (rel === null) {
+    console.error(
+      `standards creds: secrets target "${dest.target}" not found; create it with \`just secrets edit ${dest.target}\` first`,
+    );
+    return null;
+  }
+  return { repo, rel, dest, store: await readBrokerStore(resolveBrokerPath()) };
+};
+
+export const selectAccount = (
+  store: BrokerStore,
+  accountId: string | undefined,
+): CloudflareBrokerAccount | null => {
+  if (store.cloudflare.length === 0) {
+    console.error(
+      'standards creds: no Cloudflare accounts configured; run `standards creds login cloudflare`',
+    );
+    return null;
+  }
+  if (accountId === undefined) {
+    if (store.cloudflare.length === 1) {
+      return store.cloudflare[0] ?? null;
+    }
+    console.error(
+      `standards creds: multiple Cloudflare accounts configured; pass --account (${store.cloudflare.map((entry) => entry.accountId).join(', ')})`,
+    );
+    return null;
+  }
+  const account = store.cloudflare.find(
+    (entry) => entry.accountId === accountId,
+  );
+  if (account === undefined) {
+    console.error(`standards creds: account ${accountId} is not configured`);
+  }
+  return account ?? null;
+};