@starci/hfs 4.11.21 → 4.12.0

package/stack/sealed.mjs

@@ -7,148 +7,144 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readMap } from '../runtime/scripts/hfs/secret-store.mjs';
 import { refusal } from './errors.mjs';
-
 const KEY_NAME = /^[A-Z][A-Z0-9_]*$/u;
 const UNSAFE_SETTING = /[\r\n"'\\]/u;
 const MAX_NAME = 64;
-
 /** sha256 of the bytes, as lowercase hex. */
 export const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
-
 const CR = String.fromCodePoint(13);
 const LF = String.fromCodePoint(10);
-
 /** True for content that is not text: a NUL byte in the first 8 KiB. Binary files are never rewritten. */
 const isBinary = (bytes) => bytes.subarray(0, 8192).includes(0);
-
 /** Every CRLF of a string becomes LF. */
 const lfText = (text) => text.replaceAll(CR + LF, LF);
-
 /**
  * Line endings of a text file as the services need them: every CRLF becomes LF (a script rendered from a Windows checkout failed with
  * `set: Illegal option -`). Binary content is returned untouched. Takes and returns a Buffer.
  */
 function lfBytes(bytes) {
-  if (isBinary(bytes) || !bytes.includes(13)) return bytes;
-  return Buffer.from(lfText(bytes.toString('latin1')), 'latin1');
+    if (isBinary(bytes) || !bytes.includes(13))
+        return bytes;
+    return Buffer.from(lfText(bytes.toString('latin1')), 'latin1');
 }
-
 /** The bytes of a config file as they are hashed and created: LF-normalised text, untouched binary. */
 export const configBytes = (file) => lfBytes(fs.readFileSync(file));
-
 /** The key that makes the version suffix of a secret name unguessable from the name alone: a local fixture key or the age identity. */
 function versionKeyOf(ctx) {
-  const key = ctx.env.STARCI_SECRET_VERSION_KEY || ctx.env.SOPS_AGE_KEY;
-  if (!key) throw refusal('STACK_VERSION_KEY_MISSING', 'STARCI_SECRET_VERSION_KEY (a local fixture) or SOPS_AGE_KEY is needed to version the secret names');
-  return key;
+    const key = ctx.env.STARCI_SECRET_VERSION_KEY || ctx.env.SOPS_AGE_KEY;
+    if (!key)
+        throw refusal('STACK_VERSION_KEY_MISSING', 'STARCI_SECRET_VERSION_KEY (a local fixture) or SOPS_AGE_KEY is needed to version the secret names');
+    return key;
 }
-
 /** `<stack>-<key>-v<10 hex of HMAC(versionKey, key NUL value)>`: a changed value is a new name, an unchanged one keeps its name. */
 function secretRuntimeName(stack, key, value, versionKey) {
-  const version = createHmac('sha256', versionKey).update(`${key}\0${value}`).digest('hex').slice(0, 10);
-  const name = `${stack}-${key.toLowerCase().replaceAll('_', '-')}-v${version}`;
-  if (name.length > MAX_NAME) throw refusal('STACK_SECRET_NAME_TOO_LONG', `the Swarm secret name for ${key} would exceed ${MAX_NAME} characters`);
-  return name;
+    const version = createHmac('sha256', versionKey).update(`${key}\0${value}`).digest('hex').slice(0, 10);
+    const name = `${stack}-${key.toLowerCase().replaceAll('_', '-')}-v${version}`;
+    if (name.length > MAX_NAME)
+        throw refusal('STACK_SECRET_NAME_TOO_LONG', `the Swarm secret name for ${key} would exceed ${MAX_NAME} characters`);
+    return name;
 }
-
 const AGE_HINT = 'add SOPS_AGE_KEY to .claude/secret.env of the app or the harness secret.env of the owner machine (the CI secret in a workflow) and retry';
-
 /**
  * True when the sops seam found an age identity (secret-init.mjs decryptionIdentity, the one lookup every decrypt uses). A seam
  * that reports no `identity` (a spec double) decides for itself.
  */
 export function hasAgeIdentity(ctx) {
-  const { identity } = ctx.sops;
-  return identity === undefined || identity.source !== null;
+    const { identity } = ctx.sops;
+    return identity === undefined || identity.source !== null;
 }
-
 /** Refuses up front, before any work, when sealed custody must be opened and no age identity is reachable. */
-export function requireAgeIdentity(ctx, config, purpose) {
-  if (!hasAgeIdentity(ctx)) throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available (looked in ${ctx.sops.identity.looked.join(', ')}): ${AGE_HINT}`);
+export function requireAgeIdentity(ctx, _config, purpose) {
+    if (!hasAgeIdentity(ctx))
+        throw refusal('STACK_AGE_IDENTITY_MISSING', `${purpose} needs the sealed members, and no age identity is available (looked in ${ctx.sops.identity?.looked.join(', ')}): ${AGE_HINT}`);
 }
-
 /**
  * Opens one sealed member (`<secretsDir>/<member>.enc.yaml`, or a legacy `.enc`) into a { KEY: value } map. A failure is refused
  * naming the member and the seam's reason (its format, recipients and the identity tried); no value.
  */
 export function openMember(ctx, config, member) {
-  try {
-    const map = readMap(memberFile(config.secretsDir, member), ctx.sops);
-    return Object.fromEntries(Object.entries(map).map(([key, value]) => [key, typeof value === 'string' && !value.includes(String.fromCodePoint(0)) ? lfText(value) : value]));
-  } catch (error) {
-    throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened: ${error.message}${hasAgeIdentity(ctx) ? '' : `; ${AGE_HINT}`}`);
-  }
+    try {
+        const map = readMap(memberFile(config.secretsDir, member), ctx.sops);
+        return Object.fromEntries(Object.entries(map).map(([key, value]) => [key, typeof value === 'string' && !value.includes(String.fromCodePoint(0)) ? lfText(value) : value]));
+    }
+    catch (error) {
+        throw refusal('STACK_SECRET_MEMBER_UNREADABLE', `the sealed member ${member} cannot be opened: ${error.message}${hasAgeIdentity(ctx) ? '' : `; ${AGE_HINT}`}`);
+    }
 }
-
 const present = (map, key) => typeof map[key] === 'string' && map[key] !== '';
-
 function sourceKeys(map, source) {
-  if (source.keys !== null) return source.keys;
-  return Object.keys(map).filter((key) => KEY_NAME.test(key) && !key.endsWith('_FILE'));
+    if (source.keys !== null)
+        return source.keys;
+    return Object.keys(map).filter((key) => KEY_NAME.test(key) && !key.endsWith('_FILE'));
 }
-
 /** The KEY -> value pairs one grant source contributes, given what the same service already holds. */
 function takeFromSource(map, source, held) {
-  const taken = {};
-  for (const key of sourceKeys(map, source)) {
-    if (!present(map, key)) {
-      if (source.required) throw refusal('STACK_SECRET_MISSING', `the sealed member ${source.member} has no value for ${key}`);
-    } else if (!(source.fill && Object.hasOwn(held, key))) taken[key] = map[key];
-  }
-  return taken;
+    const taken = {};
+    for (const key of sourceKeys(map, source)) {
+        if (!present(map, key)) {
+            if (source.required)
+                throw refusal('STACK_SECRET_MISSING', `the sealed member ${source.member} has no value for ${key}`);
+        }
+        else if (!(source.fill && Object.hasOwn(held, key)))
+            taken[key] = map[key]; // present() proved a non-empty string
+    }
+    return taken;
 }
-
 function serviceValues(grant, memberOf) {
-  const held = {};
-  for (const source of grant.from) Object.assign(held, takeFromSource(memberOf(source.member), source, held));
-  return held;
+    const held = {};
+    for (const source of grant.from)
+        Object.assign(held, takeFromSource(memberOf(source.member), source, held));
+    return held;
 }
-
 function sealGrants(config, memberOf, versionKey) {
-  const grants = {};
-  const secrets = {};
-  const owner = {};
-  for (const grant of config.secrets.grants) {
-    const values = { ...grants[grant.service]?.values, ...serviceValues(grant, memberOf) };
-    grants[grant.service] = { values };
-    for (const [key, value] of Object.entries(values)) {
-      if (Object.hasOwn(secrets, key) && secrets[key].value !== value) throw refusal('STACK_SECRET_CONFLICT', `${key} has different values for ${owner[key]} and ${grant.service}`);
-      owner[key] ??= grant.service;
-      secrets[key] ??= { runtimeName: secretRuntimeName(config.stack, key, value, versionKey), value };
+    const grants = {};
+    const secrets = {};
+    const owner = {};
+    for (const grant of config.secrets.grants) {
+        const values = { ...grants[grant.service]?.values, ...serviceValues(grant, memberOf) };
+        grants[grant.service] = { values };
+        for (const [key, value] of Object.entries(values)) {
+            if (Object.hasOwn(secrets, key) && secrets[key]?.value !== value)
+                throw refusal('STACK_SECRET_CONFLICT', `${key} has different values for ${owner[key]} and ${grant.service}`);
+            owner[key] ??= grant.service;
+            secrets[key] ??= { runtimeName: secretRuntimeName(config.stack, key, value, versionKey), value };
+        }
     }
-  }
-  return { secrets, grants: Object.fromEntries(Object.entries(grants).map(([service, entry]) => [service, Object.keys(entry.values).sort()])) };
+    return { secrets, grants: Object.fromEntries(Object.entries(grants).map(([service, entry]) => [service, Object.keys(entry.values).sort()])) };
 }
-
 function sealSettings(config, memberOf) {
-  const settings = {};
-  for (const block of config.secrets.settings) {
-    const map = memberOf(block.member);
-    for (const key of block.keys.filter((name) => present(map, name))) {
-      if (UNSAFE_SETTING.test(map[key])) throw refusal('STACK_SETTING_INVALID', `${key} must be a plain one-line value`);
-      settings[key] = map[key];
+    const settings = {};
+    for (const block of config.secrets.settings) {
+        const map = memberOf(block.member);
+        for (const key of block.keys.filter((name) => present(map, name))) {
+            const value = map[key]; // present() proved a non-empty string
+            if (UNSAFE_SETTING.test(value))
+                throw refusal('STACK_SETTING_INVALID', `${key} must be a plain one-line value`);
+            settings[key] = value;
+        }
     }
-  }
-  return settings;
+    return settings;
 }
-
 /**
  * Opens the sealed members once each and returns what every service is granted:
  * { secrets: { KEY: { runtimeName, value } }, grants: { service: [KEY...] }, settings: { KEY: value } }. The caller must not log a value.
  */
 export function loadSealed(ctx, config) {
-  const versionKey = versionKeyOf(ctx);
-  const opened = new Map();
-  const memberOf = (member) => {
-    if (!opened.has(member)) opened.set(member, openMember(ctx, config, member));
-    return opened.get(member);
-  };
-  const { secrets, grants } = sealGrants(config, memberOf, versionKey);
-  return { secrets, grants, settings: sealSettings(config, memberOf) };
+    const versionKey = versionKeyOf(ctx);
+    const opened = new Map();
+    const memberOf = (member) => {
+        let map = opened.get(member);
+        if (map === undefined) {
+            map = openMember(ctx, config, member);
+            opened.set(member, map);
+        }
+        return map;
+    };
+    const { secrets, grants } = sealGrants(config, memberOf, versionKey);
+    return { secrets, grants, settings: sealSettings(config, memberOf) };
 }
-
 /** The config objects: non-secret files mounted into services, named by the digest of their content. */
 export const configObjects = (config) => config.configs.map((entry) => {
-  const file = path.join(config.envDir, entry.file);
-  return { logical: entry.name, env: entry.env, file, name: `${config.stack}-${entry.name}-c${sha(configBytes(file)).slice(0, 10)}` };
+    const file = path.join(config.envDir, entry.file);
+    return { logical: entry.name, env: entry.env, file, name: `${config.stack}-${entry.name}-c${sha(configBytes(file)).slice(0, 10)}` };
 });

package/stack/server-key.d.mts

@@ -0,0 +1,67 @@
+import type { StackContext } from './context.mjs';
+import type { ActionResult, RunnerDeps } from './remote.mjs';
+/** The gh port of ci/github.mjs that server-key reads and writes through. */
+export interface GithubPort {
+    repository(): string;
+    json(args: string[]): any;
+    run(args: string[]): unknown;
+}
+/** The collaborators the specs inject. */
+export interface ServerKeyDeps extends RunnerDeps {
+    github?: GithubPort;
+    ghCommand?: {
+        command: string;
+        args: string[];
+    };
+}
+/** The action a server-key call performs. */
+export interface ServerKeyOptions {
+    execute?: boolean | undefined;
+    rotate?: boolean | undefined;
+    backup?: string | undefined;
+    restore?: string | undefined;
+}
+/**
+ * The deploy server's age identity: sops' default key file of root, so a decrypt on the server reads it with nothing set, and
+ * SOPS_AGE_KEY_FILE names it where one is set. The one owner of this path; the restore workflow is rendered from it.
+ */
+export declare const SERVER_AGE_IDENTITY = "/root/.config/sops/age/keys.txt";
+/** The managed workflow `--restore github` dispatches (templates/app/ci-workflows*). */
+export declare const RESTORE_WORKFLOW = "stack-key-restore.yml";
+/**
+ * The directories, after root's PATH, where age-keygen is looked for: sudo's secure_path (AlmaLinux 10, RHEL) leaves out
+ * /usr/local/bin, where the static installer puts it, so the presence check and every call resolve it the same way, as root.
+ */
+export declare const AGE_KEYGEN_DIRS: string[];
+/** The shell lines that set k to age-keygen's absolute path as root sees it, or exit 127 naming it missing. Every root script holds them. */
+export declare const RESOLVE_AGE_KEYGEN: string;
+/** The root script that only resolves age-keygen and prints its path: the presence check, run exactly as the calls run. */
+export declare const ageKeygenScript: () => string;
+/**
+ * The GitHub Environment secret that holds an environment's server identity. It carries the name the deploy workflows read
+ * (secrets.SOPS_AGE_KEY), scoped to the Environment <env>: for a job bound to <env> it overrides a repository secret of that name.
+ */
+export declare const BACKUP_SECRET = "SOPS_AGE_KEY";
+/** The shell that keeps `file` when it is an ordinary file, else makes it with age-keygen (umask 077), then prints only its public key. */
+export declare function ensureIdentityScript(file: string): string;
+/** The shell that prints only the public key of `file`, or exits 5 when there is none. */
+export declare function publicKeyScript(file: string): string;
+/** The shell that swaps the staged `<file>.next` in, keeping the old identity as `retired`, then prints only the new public key. */
+export declare function swapIdentityScript(file: string, retired: string): string;
+/** The one remote command that streams `file` to stdout as root; only --backup github runs it, into the stdin of gh. */
+export declare const streamIdentityCommand: (file: string) => string;
+/**
+ * The GitHub Environment that holds the backup, refused unless it exists in the app's origin repository and is protected: required
+ * reviewers, or deployment branches limited to main. Names what is missing.
+ */
+export declare function protectedEnvironment(gh: GithubPort, env: string): string;
+/**
+ * The warning lines about a repository-level SOPS_AGE_KEY of `repo`, read by name only (gh api repos/<repo>/actions/secrets): a job
+ * bound to no Environment, or to one without its own SOPS_AGE_KEY, reads that one. Empty when the repository holds none.
+ */
+export declare function repositoryKeyWarnings(gh: GithubPort, repo: string): string[];
+/**
+ * Runs one server-key action. `options`: { execute, rotate, backup, restore };
+ * `deps` (specs): { ssh (an injected runner), github (the gh port of ci/github.mjs), ghCommand ({ command, args } the pipe's sink) }.
+ */
+export declare function serverKey(ctx: StackContext, env: string, options: ServerKeyOptions, deps?: ServerKeyDeps): Promise<ActionResult>;