@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/secret-output.d.mts

@@ -0,0 +1,18 @@
+import type { SecretSops } from "./secret-sops.mjs";
+/** Where the values of a secret go: stdout for `reveal`, private KEY files (their paths on `fileOutput`) for `toFile`. */
+export interface SecretOutput {
+    repoRoot: string;
+    environment: string;
+    env?: NodeJS.ProcessEnv | undefined;
+    platform?: NodeJS.Platform | undefined;
+    stdout: (text: string) => unknown;
+    fileOutput?: ((text: string) => unknown) | undefined;
+    reveal?: boolean | undefined;
+    toFile?: boolean | undefined;
+}
+export declare function listSecrets(directory: string, stdout: (text: string) => unknown): number;
+export declare function materializeSecrets(directory: string, sops: SecretSops, output: SecretOutput): number;
+export declare function getSecret(file: string, key: string | undefined, sops: SecretSops, opts: {
+    reveal?: boolean | undefined;
+    "to-file"?: unknown;
+}, output: SecretOutput, stderr: (text: string) => unknown): number;

package/runtime/scripts/hfs/secret-output.mjs

@@ -7,95 +7,67 @@ import { envelopeOf, validateKey } from "./secret-document.mjs";
 import { fileOf, readMap, sealedFiles } from "./secret-store.mjs";
 import { memberOfName } from "../lib/sealed-member.mjs";
 import { SecretError, publicStorage } from "./secret-errors.mjs";
-
 function validateWindowsKeys(map) {
-  const names = new Set();
-  for (const key of Object.keys(map)) {
-    const normalized = key.toUpperCase();
-    if (names.has(normalized))
-      throw new SecretError(
-        "KEY names differing only by case cannot be materialized on Windows",
-      );
-    if (/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/.test(normalized))
-      throw new SecretError(
-        "a KEY uses a reserved Windows file name and cannot be materialized",
-      );
-    names.add(normalized);
-  }
+    const names = new Set();
+    for (const key of Object.keys(map)) {
+        const normalized = key.toUpperCase();
+        if (names.has(normalized))
+            throw new SecretError("KEY names differing only by case cannot be materialized on Windows");
+        if (/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/.test(normalized))
+            throw new SecretError("a KEY uses a reserved Windows file name and cannot be materialized");
+        names.add(normalized);
+    }
 }
-
-function exportValues(
-  map,
-  {
-    repoRoot,
-    environment,
-    env,
-    platform,
-    stdout,
-    fileOutput = stdout,
-    reveal = false,
-    toFile = true,
-  },
-) {
-  if (toFile && platform === "win32") validateWindowsKeys(map);
-  const directory = toFile
-    ? publicStorage(() =>
-        materializedDirectory(repoRoot, environment, env, platform),
-      )
-    : null;
-  for (const key of Object.keys(map).sort(byCodeUnit)) {
-    if (toFile) {
-      const file = publicStorage(() =>
-        writeSecretFile(directory, key, map[key]),
-      );
-      fileOutput(`${key}_FILE=${file}\n`);
+function exportValues(map, { repoRoot, environment, env, platform, stdout, fileOutput = stdout, reveal = false, toFile = true, }) {
+    if (toFile && platform === "win32")
+        validateWindowsKeys(map);
+    const directory = toFile
+        ? publicStorage(() => materializedDirectory(repoRoot, environment, env, platform))
+        : null;
+    for (const key of Object.keys(map).sort(byCodeUnit)) {
+        if (toFile) {
+            const file = publicStorage(() => writeSecretFile(directory, key, map[key]));
+            fileOutput(`${key}_FILE=${file}\n`);
+        }
+        if (reveal)
+            stdout(`${key}=${map[key]}\n`);
     }
-    if (reveal) stdout(`${key}=${map[key]}\n`);
-  }
-  return 0;
+    return 0;
 }
-
 export function listSecrets(directory, stdout) {
-  const keys = new Set();
-  for (const name of sealedFiles(directory)) {
-    for (const item of envelopeOf(
-      fs.readFileSync(path.join(directory, name), "utf8"),
-    ).keys) {
-      validateKey(item);
-      keys.add(item);
+    const keys = new Set();
+    for (const name of sealedFiles(directory)) {
+        for (const item of envelopeOf(fs.readFileSync(path.join(directory, name), "utf8")).keys) {
+            validateKey(item);
+            keys.add(item);
+        }
     }
-  }
-  for (const item of [...keys].sort(byCodeUnit)) stdout(`${item}\n`);
-  return 0;
+    for (const item of [...keys].sort(byCodeUnit))
+        stdout(`${item}\n`);
+    return 0;
 }
-
 export function materializeSecrets(directory, sops, output) {
-  const map = Object.create(null);
-  for (const name of sealedFiles(directory)) {
-    for (const [item, value] of Object.entries(
-      readMap(fileOf(directory, memberOfName(name)), sops),
-    )) {
-      if (Object.hasOwn(map, item))
-        throw new SecretError(
-          `duplicate KEY ${item} across secret slugs; each materialized KEY needs one owner`,
-        );
-      map[item] = value;
+    const map = Object.create(null);
+    for (const name of sealedFiles(directory)) {
+        for (const [item, value] of Object.entries(readMap(fileOf(directory, memberOfName(name)), sops))) {
+            if (Object.hasOwn(map, item))
+                throw new SecretError(`duplicate KEY ${item} across secret slugs; each materialized KEY needs one owner`);
+            map[item] = value;
+        }
     }
-  }
-  return exportValues(map, output);
+    return exportValues(map, output);
 }
-
 export function getSecret(file, key, sops, opts, output, stderr) {
-  let map = readMap(file, sops);
-  if (key !== undefined) {
-    if (!Object.hasOwn(map, key))
-      throw new SecretError(`the secret has no KEY ${key}`);
-    map = { [key]: map[key] };
-  }
-  return exportValues(map, {
-    ...output,
-    fileOutput: stderr,
-    reveal: opts.reveal,
-    toFile: opts["to-file"] === true,
-  });
+    let map = readMap(file, sops);
+    if (key !== undefined) {
+        if (!Object.hasOwn(map, key))
+            throw new SecretError(`the secret has no KEY ${key}`);
+        map = { [key]: map[key] };
+    }
+    return exportValues(map, {
+        ...output,
+        fileOutput: stderr,
+        reveal: opts.reveal,
+        toFile: opts["to-file"] === true,
+    });
 }

package/runtime/scripts/hfs/secret-prompt.d.mts

@@ -0,0 +1,39 @@
+/** Where the prompt reads from and writes its label and `*` echo to. */
+export interface PromptOptions {
+    input?: NodeJS.ReadStream | undefined;
+    output?: ((text: string) => unknown) | undefined;
+}
+/** Asks for one hidden value under a label. */
+export type Prompt = (label: string) => Promise<string>;
+/** The stdin port of `setValues`: a function returning the text, or a stream with `fd` and `isTTY`. */
+export type StdinPort = (() => string) | {
+    fd?: number;
+    isTTY?: boolean;
+};
+/** What `setValues` reads from. */
+export interface SetValuesOptions {
+    generate?: unknown;
+    stdin?: StdinPort | undefined;
+    prompt?: Prompt | undefined;
+    random?: ((bytes: number) => Buffer) | undefined;
+    fromFile?: Record<string, string> | undefined;
+}
+/**
+ * Read one line from a terminal with no echo: `input` a TTY read stream (raw mode while reading), `output` where the label and
+ * one `*` per character go (stderr, so stdout stays clean). Backspace erases, Enter ends, Ctrl+C or Ctrl+D on an empty line
+ * cancels. Resolves the typed text; the stream is paused, unreferenced (a waiting terminal never holds the process open) and
+ * its raw mode restored either way.
+ */
+export declare function promptHidden(label: string, { input, output, }?: PromptOptions): Promise<string>;
+/**
+ * The values of `keys` in redirected stdin text: one key takes the whole text as its value (a trailing newline dropped, so a
+ * multi-line value survives); several take one `KEY=value` line each (blank and `#` lines skipped, the value after the first
+ * `=`, a trailing CR dropped), every key exactly once and no other.
+ */
+export declare function stdinValues(keys: string[], text: unknown): Record<string, string>;
+/**
+ * The values `set` seals for `keys`: each `fromFile` key read byte for byte from its file; the rest from `--generate <bytes>`
+ * (random base64url per key), else the `stdin` port (a function returning the text, as the harness CLI hands a host key, or a
+ * stream with `fd` and `isTTY`): a terminal is prompted through `prompt` (promptHidden by default), anything else is read whole.
+ */
+export declare function setValues(keys: string[], { generate, stdin, prompt, random, fromFile }: SetValuesOptions): Promise<Record<string, string>>;

package/runtime/scripts/hfs/secret-prompt.mjs

@@ -2,127 +2,142 @@
 // redirected stdin, or generated. A value stays in memory; the prompt echoes one `*` per character and nothing else.
 import fs from "node:fs";
 import { SecretError } from "./secret-errors.mjs";
-
 const ENTER = new Set(["\r", "\n"]);
 const ERASE = new Set(["\u007f", "\b"]);
 const INTERRUPT = "\u0003";
 const END = "\u0004";
-
 /**
  * Read one line from a terminal with no echo: `input` a TTY read stream (raw mode while reading), `output` where the label and
  * one `*` per character go (stderr, so stdout stays clean). Backspace erases, Enter ends, Ctrl+C or Ctrl+D on an empty line
  * cancels. Resolves the typed text; the stream is paused, unreferenced (a waiting terminal never holds the process open) and
  * its raw mode restored either way.
  */
-export function promptHidden(label, { input = process.stdin, output = (s) => process.stderr.write(s) } = {}) {
-  return new Promise((resolve, reject) => {
-    const wasRaw = input.isRaw === true;
-    let typed = "";
-    const finish = (error) => {
-      input.removeListener("data", onData);
-      input.removeListener("end", onEnd);
-      input.setRawMode?.(wasRaw);
-      input.pause();
-      input.unref?.();
-      output("\n");
-      if (error) reject(error);
-      else resolve(typed);
-    };
-    const cancelled = () => new SecretError("cancelled at the prompt; nothing was sealed");
-    const onEnd = () => finish(typed ? null : cancelled());
-    const onData = (chunk) => {
-      for (const char of String(chunk)) {
-        if (ENTER.has(char)) return finish(null);
-        if (char === INTERRUPT || (char === END && !typed)) return finish(cancelled());
-        if (ERASE.has(char)) {
-          if (typed) {
-            typed = [...typed].slice(0, -1).join("");
-            output("\b \b");
-          }
-        } else if (char >= " ") {
-          typed += char;
-          output("*");
-        }
-      }
-      return undefined;
-    };
-    output(label);
-    input.setRawMode?.(true);
-    input.setEncoding?.("utf8");
-    input.on("data", onData);
-    input.on("end", onEnd);
-    input.ref?.();
-    input.resume();
-  });
+export function promptHidden(label, { input = process.stdin, output = (s) => process.stderr.write(s), } = {}) {
+    return new Promise((resolve, reject) => {
+        const wasRaw = input.isRaw === true;
+        let typed = "";
+        const finish = (error) => {
+            input.removeListener("data", onData);
+            input.removeListener("end", onEnd);
+            input.setRawMode?.(wasRaw);
+            input.pause();
+            input.unref?.();
+            output("\n");
+            if (error)
+                reject(error);
+            else
+                resolve(typed);
+        };
+        const cancelled = () => new SecretError("cancelled at the prompt; nothing was sealed");
+        const onEnd = () => finish(typed ? null : cancelled());
+        const onData = (chunk) => {
+            for (const char of String(chunk)) {
+                if (ENTER.has(char))
+                    return finish(null);
+                if (char === INTERRUPT || (char === END && !typed))
+                    return finish(cancelled());
+                if (ERASE.has(char)) {
+                    if (typed) {
+                        typed = [...typed].slice(0, -1).join("");
+                        output("\b \b");
+                    }
+                }
+                else if (char >= " ") {
+                    typed += char;
+                    output("*");
+                }
+            }
+            return undefined;
+        };
+        output(label);
+        input.setRawMode?.(true);
+        input.setEncoding?.("utf8");
+        input.on("data", onData);
+        input.on("end", onEnd);
+        input.ref?.();
+        input.resume();
+    });
 }
-
 /** Each key typed once at the terminal, in order; an empty value seals nothing. */
 async function typedValues(keys, prompt) {
-  const values = {};
-  for (const key of keys) {
-    const value = await prompt(`${key}: `);
-    if (!value) throw new SecretError(`${key} is empty; nothing was sealed`);
-    values[key] = value;
-  }
-  return values;
+    const values = {};
+    for (const key of keys) {
+        const value = await prompt(`${key}: `);
+        if (!value)
+            throw new SecretError(`${key} is empty; nothing was sealed`);
+        values[key] = value;
+    }
+    return values;
 }
-
 /**
  * The values of `keys` in redirected stdin text: one key takes the whole text as its value (a trailing newline dropped, so a
  * multi-line value survives); several take one `KEY=value` line each (blank and `#` lines skipped, the value after the first
  * `=`, a trailing CR dropped), every key exactly once and no other.
  */
 export function stdinValues(keys, text) {
-  if (keys.length === 1) {
-    const value = String(text).replace(/\r?\n$/u, "");
-    if (!value) throw new SecretError("the value on stdin is empty");
-    return { [keys[0]]: value };
-  }
-  const wanted = new Set(keys);
-  const values = Object.create(null);
-  for (const raw of String(text).split("\n")) {
-    const line = raw.replace(/\r$/u, "");
-    if (!line.trim() || line.trimStart().startsWith("#")) continue;
-    const at = line.indexOf("=");
-    const key = at < 0 ? line.trim() : line.slice(0, at).trim();
-    if (at < 0) throw new SecretError(`stdin line for ${key} has no =; give one KEY=value line per key`);
-    if (!wanted.has(key)) throw new SecretError(`stdin names ${key}, which this set does not; nothing was sealed`);
-    if (Object.hasOwn(values, key)) throw new SecretError(`stdin gives ${key} twice; nothing was sealed`);
-    const value = line.slice(at + 1);
-    if (!value) throw new SecretError(`${key} is empty on stdin; nothing was sealed`);
-    values[key] = value;
-  }
-  const missing = keys.filter((key) => !Object.hasOwn(values, key));
-  if (missing.length) throw new SecretError(`stdin lacks ${missing.join(", ")}; give one KEY=value line per key; nothing was sealed`);
-  return { ...values };
+    if (keys.length === 1) {
+        const value = String(text).replace(/\r?\n$/u, "");
+        if (!value)
+            throw new SecretError("the value on stdin is empty");
+        return { [keys[0]]: value };
+    }
+    const wanted = new Set(keys);
+    const values = Object.create(null);
+    for (const raw of String(text).split("\n")) {
+        const line = raw.replace(/\r$/u, "");
+        if (!line.trim() || line.trimStart().startsWith("#"))
+            continue;
+        const at = line.indexOf("=");
+        const key = at < 0 ? line.trim() : line.slice(0, at).trim();
+        if (at < 0)
+            throw new SecretError(`stdin line for ${key} has no =; give one KEY=value line per key`);
+        if (!wanted.has(key))
+            throw new SecretError(`stdin names ${key}, which this set does not; nothing was sealed`);
+        if (Object.hasOwn(values, key))
+            throw new SecretError(`stdin gives ${key} twice; nothing was sealed`);
+        const value = line.slice(at + 1);
+        if (!value)
+            throw new SecretError(`${key} is empty on stdin; nothing was sealed`);
+        values[key] = value;
+    }
+    const missing = keys.filter((key) => !Object.hasOwn(values, key));
+    if (missing.length)
+        throw new SecretError(`stdin lacks ${missing.join(", ")}; give one KEY=value line per key; nothing was sealed`);
+    return { ...values };
 }
-
 /** The text of a `--from-file` value, byte for byte (a trailing newline kept); an empty file seals nothing. */
 function fileValue(key, file) {
-  let text;
-  try { text = fs.readFileSync(file, "utf8"); }
-  catch (error) { throw new SecretError(`--from-file ${key}: the file cannot be read (${error.code ?? "unreadable"})`); }
-  if (!text) throw new SecretError(`--from-file ${key}: the file is empty; nothing was sealed`);
-  return text;
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new SecretError(`--from-file ${key}: the file cannot be read (${error.code ?? "unreadable"})`);
+    }
+    if (!text)
+        throw new SecretError(`--from-file ${key}: the file is empty; nothing was sealed`);
+    return text;
 }
-
 /**
  * The values `set` seals for `keys`: each `fromFile` key read byte for byte from its file; the rest from `--generate <bytes>`
  * (random base64url per key), else the `stdin` port (a function returning the text, as the harness CLI hands a host key, or a
  * stream with `fd` and `isTTY`): a terminal is prompted through `prompt` (promptHidden by default), anything else is read whole.
  */
 export async function setValues(keys, { generate, stdin, prompt = promptHidden, random, fromFile = {} }) {
-  const files = Object.fromEntries(Object.entries(fromFile).map(([key, file]) => [key, fileValue(key, file)]));
-  const rest = keys.filter((key) => !Object.hasOwn(files, key));
-  if (!rest.length) return files;
-  if (generate !== undefined) {
-    const bytes = Number(generate);
-    if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024)
-      throw new SecretError("--generate must be a whole byte count from 1 to 1024");
-    return { ...files, ...Object.fromEntries(rest.map((key) => [key, random(bytes).toString("base64url")])) };
-  }
-  if (typeof stdin === "function") return { ...files, ...stdinValues(rest, stdin()) };
-  const source = stdin ?? process.stdin;
-  if (source.isTTY) return { ...files, ...(await typedValues(rest, prompt)) };
-  return { ...files, ...stdinValues(rest, fs.readFileSync(source.fd ?? 0, "utf8")) };
+    const files = Object.fromEntries(Object.entries(fromFile).map(([key, file]) => [key, fileValue(key, file)]));
+    const rest = keys.filter((key) => !Object.hasOwn(files, key));
+    if (!rest.length)
+        return files;
+    if (generate !== undefined) {
+        const bytes = Number(generate);
+        if (!Number.isInteger(bytes) || bytes < 1 || bytes > 1024)
+            throw new SecretError("--generate must be a whole byte count from 1 to 1024");
+        return { ...files, ...Object.fromEntries(rest.map((key) => [key, random(bytes).toString("base64url")])) };
+    }
+    if (typeof stdin === "function")
+        return { ...files, ...stdinValues(rest, stdin()) };
+    const source = stdin ?? process.stdin;
+    if (source.isTTY)
+        return { ...files, ...(await typedValues(rest, prompt)) };
+    return { ...files, ...stdinValues(rest, fs.readFileSync(source.fd ?? 0, "utf8")) };
 }

package/runtime/scripts/hfs/secret-sops.d.mts

@@ -0,0 +1,29 @@
+import { type AgeHost, type SecretToolOverrides } from "./secret-init.mjs";
+/** Where the age identity of a sops adapter came from (null when nowhere) and every place looked for one. */
+export interface AgeIdentitySource {
+    source: string | null;
+    looked: string[];
+}
+/** One seal request: the plaintext, its sops input type, the public recipients and the member file it stands in for. */
+export interface SealRequest {
+    inputType: string;
+    plaintext: string;
+    recipients: string[];
+    filenameOverride: string;
+}
+/** The runtime's sops seam: decrypt, rewrap and seal sealed members without ever printing a value. */
+export interface SecretSops {
+    identity: AgeIdentitySource;
+    requireIdentity: (file: string) => void;
+    decrypt: (file: string, format: string) => Record<string, string>;
+    decryptBinary: (file: string) => string;
+    updateKeys: (file: string) => void;
+    seal: (request: SealRequest) => string;
+}
+/**
+ * The default sops seam: the runtime's sops api, which finds the binary on this machine; the age identity is decryptionIdentity's
+ * (`host` the harness CLI's secret.env, then sops' keys.txt). `identity` says where the age identity
+ * was found (`source`, null when nowhere) and where it was looked for; `requireIdentity(file)` refuses, before any value is
+ * read, an operation that must decrypt `file` with no identity.
+ */
+export declare function defaultSops(env?: NodeJS.ProcessEnv, repoRoot?: string, platform?: NodeJS.Platform | undefined, tools?: SecretToolOverrides | undefined, host?: AgeHost | null): SecretSops;