@davidvornholt/standards 0.13.0 → 0.14.0

package/src/creds-plan.ts

@@ -0,0 +1,185 @@
+// Pure reconciliation between a repository's SOPS key structure and the
+// Cloudflare tokens the broker minted for it (matched by the deterministic
+// naming scheme). A brokered token whose secret key vanished from SOPS is
+// revoked; one nearing expiry is replaced while copying its live policy and
+// 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 { parseTokenName } from './creds-naming';
+
+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 };
+};
+
+type Disposition =
+  | { readonly kind: 'action'; readonly action: PlannedAction }
+  | { readonly kind: 'finding'; readonly finding: string }
+  | { readonly kind: 'healthy' };
+
+const dispositionOf = (
+  entry: ManagedToken,
+  input: {
+    readonly keysByTarget: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly now: Date;
+  },
+  renewWithin: number,
+): Disposition => {
+  const { accountId, token, ref } = entry;
+  const base = { accountId, tokenId: token.id, name: token.name };
+  if (token.status !== 'active') {
+    return {
+      kind: 'finding',
+      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)) {
+    return {
+      kind: 'action',
+      action: {
+        ...base,
+        kind: 'revoke',
+        reason: `secret ${ref.target}:${ref.key} no longer exists`,
+      },
+    };
+  }
+  if (!token.condition.supported) {
+    return {
+      kind: 'finding',
+      finding: `${token.name} has an unsupported condition shape; it will not be mutated automatically`,
+    };
+  }
+  if (token.expiresOn === null) {
+    return { kind: 'healthy' };
+  }
+  const expiry = Date.parse(token.expiresOn);
+  if (!Number.isFinite(expiry)) {
+    return {
+      kind: 'finding',
+      finding: `${token.name} has an invalid expires_on value`,
+    };
+  }
+  if (expiry - input.now.getTime() > renewWithin) {
+    return { kind: 'healthy' };
+  }
+  const issued =
+    token.issuedOn === null ? Number.NaN : Date.parse(token.issuedOn);
+  if (
+    !Number.isFinite(issued) ||
+    issued >= expiry ||
+    token.policies === null ||
+    token.policies.length === 0
+  ) {
+    return {
+      kind: 'finding',
+      finding: `${token.name} cannot be renewed safely because its issued_on, expires_on, or policies are incomplete`,
+    };
+  }
+  return {
+    kind: 'action',
+    action: {
+      ...base,
+      kind: 'renew',
+      target: ref.target,
+      key: ref.key,
+      policies: token.policies,
+      condition: token.condition.value,
+      replacementExpiresOn: new Date(
+        input.now.getTime() + expiry - issued,
+      ).toISOString(),
+      reason: `expires ${token.expiresOn}`,
+    },
+  };
+};
+
+const dispositionForGroup = (
+  group: ReadonlyArray<ManagedToken>,
+  input: {
+    readonly keysByTarget: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly now: Date;
+  },
+  renewWithin: number,
+): Disposition => {
+  if (group.length > 1) {
+    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`,
+    };
+  }
+  const [entry] = group;
+  return entry === undefined
+    ? { kind: 'healthy' }
+    : dispositionOf(entry, input, renewWithin);
+};
+
+export const computeCredsPlan = (input: {
+  readonly repo: string;
+  readonly keysByTarget: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly tokens: ReadonlyArray<AccountToken>;
+  readonly now: Date;
+  readonly renewWithinDays?: number;
+}): CredsPlan => {
+  const renewWithin =
+    (input.renewWithinDays ?? DEFAULT_RENEW_WITHIN_DAYS) * DAY_MS;
+  const actions: Array<PlannedAction> = [];
+  const findings: Array<string> = [];
+  let healthy = 0;
+  const managed = input.tokens.flatMap((entry) => {
+    const ref = parseTokenName(entry.token.name, input.repo);
+    return ref === null ? [] : [{ ...entry, ref }];
+  });
+  const byDestination = Map.groupBy(
+    managed,
+    ({ ref }) => `${ref.target}\0${ref.key}`,
+  );
+  const dispositions = [...byDestination.values()].map((group) =>
+    dispositionForGroup(group, input, renewWithin),
+  );
+  for (const disposition of dispositions) {
+    if (disposition.kind === 'action') {
+      actions.push(disposition.action);
+    } else if (disposition.kind === 'finding') {
+      findings.push(disposition.finding);
+    } else {
+      healthy += 1;
+    }
+  }
+  return { actions, findings, healthy };
+};

package/src/creds-prompt.ts

@@ -0,0 +1,62 @@
+// Terminal prompts for login flows. Hidden input never echoes: pasted
+// bootstrap tokens must not land in terminal scrollback or transcripts.
+
+import process from 'node:process';
+import { createInterface } from 'node:readline/promises';
+
+const END_OF_TRANSMISSION = '\u0004';
+const INTERRUPT = '\u0003';
+const DELETE = '\u007f';
+
+export const promptLine = async (question: string): Promise<string> => {
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return (await readline.question(question)).trim();
+  } finally {
+    readline.close();
+  }
+};
+
+const isSubmit = (char: string): boolean =>
+  char === '\r' || char === '\n' || char === END_OF_TRANSMISSION;
+
+const applyChar = (value: string, char: string): string =>
+  char === DELETE || char === '\b' ? value.slice(0, -1) : value + char;
+
+export const promptHidden = (question: string): Promise<string> => {
+  const { stdin, stdout } = process;
+  if (!stdin.isTTY) {
+    return promptLine(question);
+  }
+  stdout.write(question);
+  return new Promise((resolvePromise) => {
+    stdin.setRawMode(true);
+    stdin.resume();
+    let value = '';
+    const finish = (): void => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off('data', onData);
+      stdout.write('\n');
+    };
+    const onData = (chunk: Buffer): void => {
+      for (const char of chunk.toString('utf8')) {
+        if (isSubmit(char)) {
+          finish();
+          resolvePromise(value.trim());
+          return;
+        }
+        if (char === INTERRUPT) {
+          finish();
+          process.kill(process.pid, 'SIGINT');
+          return;
+        }
+        value = applyChar(value, char);
+      }
+    };
+    stdin.on('data', onData);
+  });
+};

package/src/creds-sops-editor.ts

@@ -0,0 +1,170 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import process from 'node:process';
+import { parseDocument } from 'yaml';
+import { assertWritableSopsPath } from './creds-dest';
+import {
+  inspectSopsStructure,
+  parseSopsKeyPath,
+  type SopsShapeFailure,
+  type SopsStructureResult,
+} from './creds-sops-structure';
+import { isRecord } from './github-settings-parse';
+
+export const SET_CHANGES_ENV = 'STANDARDS_SOPS_SET_CHANGES';
+export type SopsValueChange = {
+  readonly path: string;
+  readonly value: string;
+};
+export type SopsScalarStructureResult =
+  | { readonly ok: true; readonly state: 'absent' | 'scalar' }
+  | SopsShapeFailure
+  | {
+      readonly ok: false;
+      readonly kind: 'collection' | 'blocked-by-scalar';
+      readonly problem: string;
+    };
+
+export const inspectSopsScalarStructure = (
+  structure: SopsStructureResult,
+  dottedPath: string,
+): SopsScalarStructureResult => {
+  if (!structure.ok) {
+    return structure;
+  }
+  const path = parseSopsKeyPath(dottedPath);
+  if (path === null) {
+    return {
+      ok: false,
+      kind: 'unsupported-shape',
+      problem: `invalid SOPS key path: ${dottedPath}`,
+    };
+  }
+  let node: unknown = structure.root;
+  for (const [index, segment] of path.entries()) {
+    if (!isRecord(node)) {
+      return {
+        ok: false,
+        kind: 'blocked-by-scalar',
+        problem: `SOPS key path is blocked by a scalar: ${dottedPath}`,
+      };
+    }
+    const next = node[segment];
+    if (next === undefined) {
+      return { ok: true, state: 'absent' };
+    }
+    if (index === path.length - 1) {
+      return isRecord(next)
+        ? {
+            ok: false,
+            kind: 'collection',
+            problem: `SOPS key path names a mapping: ${dottedPath}`,
+          }
+        : { ok: true, state: 'scalar' };
+    }
+    node = next;
+  }
+  return { ok: true, state: 'absent' };
+};
+
+const parseChanges = (raw: string): ReadonlyArray<SopsValueChange> => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${SET_CHANGES_ENV} must contain valid JSON`, {
+      cause: error,
+    });
+  }
+  if (
+    !(
+      Array.isArray(parsed) &&
+      parsed.every(
+        (change) =>
+          isRecord(change) &&
+          typeof change.path === 'string' &&
+          typeof change.value === 'string',
+      )
+    )
+  ) {
+    throw new Error(`${SET_CHANGES_ENV} must contain SOPS value changes`);
+  }
+  return parsed;
+};
+const parseDistinctPaths = (
+  changes: ReadonlyArray<SopsValueChange>,
+): ReadonlyArray<ReadonlyArray<string>> => {
+  if (changes.length === 0) {
+    throw new Error('at least one SOPS change is required');
+  }
+  const paths = changes.map(({ path }) => {
+    const parsed = parseSopsKeyPath(path);
+    if (parsed === null) {
+      throw new Error(`invalid SOPS key path: ${path}`);
+    }
+    return parsed;
+  });
+  for (const [index, path] of paths.entries()) {
+    for (const other of paths.slice(index + 1)) {
+      const pathContainsOther = path.every(
+        (segment, part) => other[part] === segment,
+      );
+      const otherContainsPath = other.every(
+        (segment, part) => path[part] === segment,
+      );
+      if (pathContainsOther || otherContainsPath) {
+        throw new Error(
+          'SOPS changes must have distinct, non-overlapping paths',
+        );
+      }
+    }
+  }
+  return paths;
+};
+export const applySopsEditorChanges = (
+  text: string,
+  changes: ReadonlyArray<SopsValueChange>,
+): string => {
+  const structure = inspectSopsStructure(text, false);
+  if (!structure.ok) {
+    throw new Error(structure.problem);
+  }
+  const paths = parseDistinctPaths(changes);
+  for (const path of paths) {
+    assertWritableSopsPath(structure.root, path);
+  }
+  const document = parseDocument(text);
+  for (const [index, change] of changes.entries()) {
+    const path = paths[index];
+    if (path === undefined) {
+      // paths is derived index-aligned from changes; a miss is a programming
+      // error, and the old `?? []` fallback would have replaced the document
+      // root — the most destructive possible default.
+      throw new Error(`SOPS change path misalignment at index ${index}`);
+    }
+    document.setIn(path, change.value);
+  }
+  return document.toString();
+};
+const runEditor = (): void => {
+  const [, , file] = process.argv;
+  const changes = process.env[SET_CHANGES_ENV];
+  if (file === undefined || changes === undefined) {
+    console.error(`creds-sops-editor: requires a file and ${SET_CHANGES_ENV}`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const changed = applySopsEditorChanges(
+      readFileSync(file, 'utf8'),
+      parseChanges(changes),
+    );
+    writeFileSync(file, changed);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'failure';
+    console.error(`creds-sops-editor: ${message}`);
+    process.exitCode = 1;
+  }
+};
+if (import.meta.main) {
+  runEditor();
+}

package/src/creds-sops-structure.ts

@@ -0,0 +1,199 @@
+import { lstatSync, realpathSync, type Stats } from 'node:fs';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import {
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  parseDocument,
+  type YAMLMap,
+} from 'yaml';
+import { isRecord } from './github-settings-parse';
+
+const SAFE_KEY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
+const RESERVED_KEY_SEGMENTS = new Set([
+  'constructor',
+  'prototype',
+  'sops',
+  '__proto__',
+]);
+export type SopsShapeFailure = {
+  readonly ok: false;
+  readonly kind:
+    | 'malformed-yaml'
+    | 'missing-sops-metadata'
+    | 'unsupported-shape';
+  readonly problem: string;
+};
+export type SopsStructureResult =
+  | {
+      readonly ok: true;
+      readonly keys: ReadonlyArray<string>;
+      readonly root: Readonly<Record<string, unknown>>;
+    }
+  | SopsShapeFailure;
+export const isSafeSopsKeySegment = (segment: string): boolean =>
+  SAFE_KEY_SEGMENT.test(segment) && !RESERVED_KEY_SEGMENTS.has(segment);
+export const parseSopsKeyPath = (
+  dottedPath: string,
+): ReadonlyArray<string> | null => {
+  const segments = dottedPath.split('.');
+  return segments.length > 0 && segments.every(isSafeSopsKeySegment)
+    ? segments
+    : null;
+};
+const isContained = (root: string, candidate: string): boolean => {
+  const fromRoot = relative(root, candidate);
+  return (
+    fromRoot !== '' &&
+    !isAbsolute(fromRoot) &&
+    fromRoot !== '..' &&
+    !fromRoot.startsWith(`..${sep}`)
+  );
+};
+const matchesKind = (stat: Stats, kind: 'directory' | 'file'): boolean =>
+  kind === 'file' ? stat.isFile() : stat.isDirectory();
+export const isContainedSopsPath = (
+  consumer: string,
+  rel: string,
+  kind: 'directory' | 'file',
+): boolean => {
+  try {
+    if (
+      isAbsolute(rel) ||
+      rel.includes('\\') ||
+      lstatSync(consumer).isSymbolicLink()
+    ) {
+      return false;
+    }
+    const parts = rel.split('/');
+    if (
+      parts.length === 0 ||
+      parts.some((part) => ['', '.', '..'].includes(part))
+    ) {
+      return false;
+    }
+    const root = realpathSync(consumer);
+    let candidate = consumer;
+    for (const [index, part] of parts.entries()) {
+      candidate = join(candidate, part);
+      const stat = lstatSync(candidate);
+      const final = index === parts.length - 1;
+      const expectedKind = final ? kind : 'directory';
+      if (
+        stat.isSymbolicLink() ||
+        !isContained(root, realpathSync(candidate)) ||
+        !matchesKind(stat, expectedKind)
+      ) {
+        return false;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+};
+const keyName = (node: unknown): string | null =>
+  isScalar(node) && typeof node.value === 'string' && node.tag === undefined
+    ? node.value
+    : null;
+
+const collectLeaves = (
+  node: unknown,
+  prefix: ReadonlyArray<string>,
+  keys: Array<string>,
+): string | null => {
+  if (isSeq(node)) {
+    return `arrays are not supported at ${prefix.join('.')}`;
+  }
+  if (isAlias(node)) {
+    return `aliases are not supported at ${prefix.join('.')}`;
+  }
+  if (!isMap(node)) {
+    keys.push(prefix.join('.'));
+    return null;
+  }
+  for (const pair of node.items) {
+    const key = keyName(pair.key);
+    if (key === null || !isSafeSopsKeySegment(key)) {
+      return `unsupported mapping key at ${prefix.join('.')}`;
+    }
+    const problem = collectLeaves(pair.value, [...prefix, key], keys);
+    if (problem !== null) {
+      return problem;
+    }
+  }
+  return null;
+};
+type RootInspection = {
+  readonly keys: ReadonlyArray<string>;
+  readonly hasMetadata: boolean;
+  readonly problem: string | null;
+};
+const inspectRoot = (root: YAMLMap): RootInspection => {
+  const keys: Array<string> = [];
+  let hasMetadata = false;
+  for (const pair of root.items) {
+    const key = keyName(pair.key);
+    if (key === null || (!isSafeSopsKeySegment(key) && key !== 'sops')) {
+      return {
+        keys,
+        hasMetadata,
+        problem: 'secrets document has an unsupported mapping key',
+      };
+    }
+    if (key === 'sops') {
+      hasMetadata = isMap(pair.value);
+    } else {
+      const problem = collectLeaves(pair.value, [key], keys);
+      if (problem !== null) {
+        return { keys, hasMetadata, problem };
+      }
+    }
+  }
+  return { keys, hasMetadata, problem: null };
+};
+
+export const inspectSopsStructure = (
+  text: string,
+  requireMetadata: boolean,
+): SopsStructureResult => {
+  const document = parseDocument(text);
+  if (document.errors.length > 0) {
+    return {
+      ok: false,
+      kind: 'malformed-yaml',
+      problem: 'secrets document is malformed YAML',
+    };
+  }
+  if (!isMap(document.contents)) {
+    return {
+      ok: false,
+      kind: 'unsupported-shape',
+      problem: 'secrets document root must be a mapping',
+    };
+  }
+  const inspected = inspectRoot(document.contents);
+  if (inspected.problem !== null) {
+    return {
+      ok: false,
+      kind: 'unsupported-shape',
+      problem: inspected.problem,
+    };
+  }
+  if (requireMetadata && !inspected.hasMetadata) {
+    return {
+      ok: false,
+      kind: 'missing-sops-metadata',
+      problem: 'secrets document has no SOPS metadata',
+    };
+  }
+  const root = document.toJS();
+  return isRecord(root)
+    ? { ok: true, keys: inspected.keys, root }
+    : {
+        ok: false,
+        kind: 'unsupported-shape',
+        problem: 'secrets document root must be a mapping',
+      };
+};