@sagentix-inc/evidence-collector 0.3.2 → 0.3.3

package/README.md

@@ -143,6 +143,27 @@ Top-level keys are `endpoint` (required), `keyId`, `keyFile`, `out`, `dryRun` an
 
 The file holds no secret. The private key comes from the `keyFile` path or from `SAGENTIX_COLLECTOR_KEY`, and each source reads its credentials from the environment as before; a value that looks like a PEM block or a well-known token prefix (`ghp_`, `github_pat_`, `AKIA`, `xoxb-` …) is refused. Paths are relative to the directory the command runs in. Options given on the command line override the file's, and `--source` on the command line adds to the file's sources.
 
+### Vault: connector secrets set from sos-app (0.3.3)
+
+Since 0.3.3 an owner or admin sets each connector's secrets and settings on sos-app's Connect screen (Your collectors,
+Connectors). A secret is encrypted in their browser for this collector only (X25519, HKDF-SHA256, AES-256-GCM): sos-app
+keeps and relays bytes it cannot open, and the collector opens them into `sagentix-collector.vault` beside the config
+(mode 0600, each value sealed on its own). Each run reads the vault into its environment; a variable already set wins.
+The collector takes a value only for a name its config's `credentials` lists, and a secret only while its connector's
+settings are the ones it was entered with. Design: `apps/sos-app/docs/COLLECTOR_VAULT.md` in the Sagentix repository.
+
+The vault's key is kept in the strongest place the computer has: a systemd credential, a Docker secret, the macOS
+Keychain, Windows DPAPI, or else `sagentix-collector.vault.key` (mode 0600). With a plain key file, seal it:
+
+- **systemd** (Linux, the collector run as a system service; the generated agent unit is a user unit, so this means
+  installing it under `/etc/systemd/system` instead): `sudo systemd-creds encrypt --name=sagentix-vault-key sagentix-collector.vault.key /etc/credstore.encrypted/sagentix-vault-key`,
+  add `LoadCredentialEncrypted=sagentix-vault-key` to the collector's unit, restart it, then delete `sagentix-collector.vault.key`.
+- **Docker**: create a Docker secret named `sagentix-vault-key` from the key file and give it to the container
+  (`/run/secrets/sagentix-vault-key`), then delete `sagentix-collector.vault.key`.
+
+Values written earlier to `sagentix-collector.env` by the setup scripts keep working; the Connect screen offers to move
+them into the vault, after which the collector removes those lines.
+
 ### The older v1 push
 
 `--fedramp-target <id> [--class A|B|C|D]` sends the v1 format (`sagentix-fedramp-collect/1`) to `/api/fedramp/collect` instead. It carries the original 11 checks grouped into five KSIs with a Security Decision Record, validated locally against FedRAMP's schema. New installs should use the default v2 push; v1 stays for targets already wired to it.

package/collector/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@sagentix-inc/evidence-collector",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module"
 }

package/collector/src/agent.js

@@ -11,6 +11,8 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { CONNECT_PATH, EXIT_UPDATE, MODE_ENV, checkin, collectorInfo, detectRunner } from "./channel.js";
 import { loadConfig } from "./config.js";
+import { vaultBridge } from "./deliveries.js";
+import { keyHolderFor } from "./vault.js";
 import { signBody } from "./keys.js";
 export const PING_MS = 50_000;
 export const CHECKIN_MS = 6 * 3600_000;
@@ -111,6 +113,38 @@ export class AgentSession {
     /** Stops a run in progress (the agent is exiting). */
     stop() { this.busy?.child.kill(); }
 }
+export const TEST_TIMEOUT_MS = 5 * 60_000;
+/** A connector test asked from sos-app: this file's own cli.ts, `run --dry-run` of its sources, no check-in, no report. */
+export function testRun(configPath, env, sources) {
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [...process.execArgv, CLI_PATH, "run", "--config", configPath, "--dry-run", ...sources.flatMap((x) => ["--source", x])], { cwd: dirname(configPath), env: { ...env, SAGENTIX_CONNECTOR_TEST: "1" }, stdio: ["ignore", "pipe", "pipe"] });
+        let out = "", err = "", timedOut = false;
+        child.stdout.on("data", (d) => { if (out.length < 32 * 1024 * 1024)
+            out += d; });
+        child.stderr.on("data", (d) => { if (err.length < 256 * 1024)
+            err += d; });
+        const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, TEST_TIMEOUT_MS);
+        child.once("error", (e) => { clearTimeout(timer); done({ exit: null, passed: 0, failed: 0, skipped: 0, errors: [String(e.message)] }); });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            done({ ...summaryOf(out), exit: code, errors: err.split(/\r?\n/).filter((l) => /^error in source |^collector error|vault/.test(l)), ...(timedOut ? { timedOut } : {}) });
+        });
+    });
+}
+/** The pass, fail and skipped counts a dry run prints (one push, or several). */
+export function summaryOf(stdout) {
+    const z = { passed: 0, failed: 0, skipped: 0 };
+    try {
+        const j = JSON.parse(stdout);
+        for (const sm of j.summary ? [j.summary] : (j.pushes ?? []).map((x) => x.summary)) {
+            z.passed += sm?.passed ?? 0;
+            z.failed += sm?.failed ?? 0;
+            z.skipped += sm?.skipped ?? 0;
+        }
+    }
+    catch { /* nothing printed: the errors say why */ }
+    return z;
+}
 /** What a run started from sos-app executes (exported for the tests). */
 export function runCommand(configPath, exists, platform = process.platform) {
     const dir = dirname(resolve(configPath));
@@ -201,9 +235,12 @@ export async function agent(argv, deps, io = realAgentIo()) {
     // A signed update written by a check-in ends the agent with 75 once no run is going: Docker's wrapper loop restarts
     // the container on the new digest, a service manager restarts the script, which checks out the ref on start.
     let restartPending = false;
+    const dir = dirname(configPath);
+    const vault = vaultBridge({ configPath, keyId, now: deps.now, log, test: (sources) => testRun(configPath, deps.env, sources),
+        holder: deps.vaultKey?.(dir, keyId) ?? keyHolderFor(dir, keyId, { env: deps.env, platform: process.platform, runner: detectRunner(deps.env) }) });
     const doCheckin = async () => {
         try {
-            const out = await checkin(channel, { write: true, log });
+            const out = await checkin(channel, { write: true, log, vault });
             if (out.wrote && !restartPending) {
                 restartPending = true;
                 log(`agent: exiting with ${EXIT_UPDATE} to restart on the update${session.running ? ` once run ${session.running} ends` : ""}`);

package/collector/src/channel.js

@@ -2,7 +2,8 @@
 // collector is (version, commit, runner), the signed POST every message uses, and the check-in that may name a
 // signed update. Every connection goes out; nothing here listens, and nothing the server answers can make the
 // collector run a command or change a configuration. The most it can do is have `sagentix-collector.ref` (or
-// `.image`) written beside the config, which the generated script reads on its next start.
+// `.image`) written beside the config, which the generated script reads on its next start, and deliver values to
+// the vault for the names the config already lists (src/deliveries.ts: a secret only sealed for this collector).
 import { spawnSync } from "node:child_process";
 import { chmodSync, existsSync, writeFileSync } from "node:fs";
 import { arch, platform, release } from "node:os";
@@ -12,6 +13,7 @@ import { fileURLToPath } from "node:url";
 import { signBody } from "./keys.js";
 import { COLLECTOR_VERSION } from "./payload.js";
 import { RELEASE_PUBLIC_KEYS } from "./release_keys.js";
+import { ack } from "./deliveries.js";
 export const CHECKIN_PATH = "/api/collect/checkin";
 export const REPORT_PATH = "/api/collect/report";
 export const CONNECT_PATH = "/api/collect/connect";
@@ -133,9 +135,17 @@ function targetOf(v) {
 export async function checkin(c, o) {
     const warnings = [];
     const warn = (s) => { warnings.push(s); o.log(`warning: check-in: ${s}`); };
+    // The vault's names, kinds, dates and sealing key (section 8): never a value.
+    let vault;
+    try {
+        vault = o.vault?.summary();
+    }
+    catch (e) {
+        warn(`the vault summary failed: ${String(e?.message ?? e)}`);
+    }
     const body = new TextEncoder().encode(JSON.stringify({
         format: "sagentix-checkin/1", issuedAt: c.now().toISOString(), collector: collectorInfo(c.env),
-        runner: c.runner, mode: c.mode, os: osInfo(), node: process.version,
+        runner: c.runner, mode: c.mode, os: osInfo(), node: process.version, ...(vault ? { vault } : {}),
     }));
     let res;
     try {
@@ -157,6 +167,17 @@ export async function checkin(c, o) {
         warn("the answer is not JSON");
         return { action: "failed", warnings };
     }
+    // Values sent to the vault from sos-app (section 8), whatever the update answer. A dry run applies nothing.
+    if (o.vault && o.write && Array.isArray(a.deliveries) && a.deliveries.length) {
+        try {
+            const results = await o.vault.apply(a.deliveries, { agent: c.mode === "agent" });
+            if (results.length)
+                await ack(c, results, o.vault.summary(), o.log);
+        }
+        catch (e) {
+            warn(`the deliveries failed: ${String(e?.message ?? e)}`);
+        }
+    }
     const reason = typeof a.reason === "string" ? a.reason.slice(0, 500) : "";
     switch (a.action) {
         case "none": return { action: "none", warnings };

package/collector/src/cli.js

@@ -31,8 +31,12 @@ import { CLASSES } from "./v1/rules.js";
 import { EXIT_UPDATE, checkin, detectRunner, modeOf } from "./channel.js";
 import { RunRecorder, buildReport, deliverReport } from "./report.js";
 import { agent } from "./agent.js";
+import { VAULT_FILE, keyHolderFor, runEnv } from "./vault.js";
+import { credentialsIn, settingsOf, vaultBridge } from "./deliveries.js";
 export const COLLECT_PATH = "/api/collect";
 export const KEY_ENV = "SAGENTIX_COLLECTOR_KEY";
+/** Set by the agent on a connector test asked from sos-app (a dry run of one connector). */
+export const TEST_ENV = "SAGENTIX_CONNECTOR_TEST";
 /** `update` (75) is the agent's only: it wrote a signed update and exits so it is restarted on it. */
 export const EXIT = { ok: 0, error: 1, usage: 2, nothing: 3, refused: 4, update: EXIT_UPDATE };
 export function defaultDeps() {
@@ -215,10 +219,39 @@ export async function run(argv, deps) {
     const channel = pem && keyId
         ? { origin: new URL(url).origin, keyId, pem, fetch: deps.channel ?? deps.fetch, dir, runner, mode, env: deps.env, now: deps.now }
         : undefined;
-    if (channel)
-        rec.note("checkin", (await checkin(channel, { write: !dry, log: deps.err })).warnings);
+    // A connector test asked from sos-app runs that connector dry: no check-in, and no run report, so the last real run's
+    // report beside the config stays what sos-app shows.
+    const connectorTest = dry && deps.env[TEST_ENV] === "1";
+    if (connectorTest) { /* neither */ }
+    else if (channel) {
+        const vault = configPath && keyId ? vaultBridge({ configPath: resolve(configPath), keyId, now: deps.now, log: deps.err,
+            holder: deps.vaultKey?.(dir, keyId) ?? keyHolderFor(dir, keyId, { env: deps.env, platform: process.platform, runner }) }) : undefined;
+        rec.note("checkin", (await checkin(channel, { write: !dry, log: deps.err, vault })).warnings);
+    }
     else
         deps.err("check-in skipped: a dry run without a key cannot sign one.");
+    // The connectors' secrets and settings, set in sos-app and sealed for this collector (src/vault.ts), when the run has a config and a key id.
+    // A vault that cannot be opened is a warning: the sources that need its values fail on their own, the run goes on.
+    let env = deps.env, cleanup = () => { }, vaultSecrets = [];
+    if (configPath && keyId) {
+        try {
+            const creds = credentialsIn(resolve(configPath));
+            const r = runEnv(dir, deps.vaultKey?.(dir, keyId) ?? keyHolderFor(dir, keyId, { env: deps.env, platform: process.platform, runner }), deps.env, (name) => settingsOf(creds, name));
+            ({ env, cleanup } = r);
+            vaultSecrets = r.secrets;
+            if (r.used.length)
+                deps.err(`vault: ${r.used.length} value(s) from ${VAULT_FILE}`);
+            for (const w of r.warnings)
+                deps.err(`warning: vault: ${w}`);
+            if (r.warnings.length)
+                rec.note("vault", r.warnings);
+        }
+        catch (e) {
+            const w = `the vault could not be opened: ${String(e?.message ?? e)}`;
+            deps.err(w);
+            rec.note("vault", [w]);
+        }
+    }
     let code;
     try {
         code = await collect();
@@ -227,7 +260,13 @@ export async function run(argv, deps) {
         deps.err(`collector error: ${String(e?.message ?? e)}`);
         code = EXIT.error;
     }
-    await deliverReport(buildReport(rec, { now: deps.now(), exitCode: code, runner, mode, env: deps.env }), { dry, channel, dir, log: deps.err });
+    finally {
+        cleanup();
+    }
+    // The report is scrubbed of every value in the run's environment, the vault's included.
+    if (connectorTest)
+        return code;
+    await deliverReport(buildReport(rec, { now: deps.now(), exitCode: code, runner, mode, env, secrets: vaultSecrets }), { dry, channel, dir, log: deps.err });
     return code;
     async function collect() {
         // Run every chosen source inside a guard, then keep only what the server will accept. A source that throws gives
@@ -236,7 +275,7 @@ export async function run(argv, deps) {
         const raw = [];
         const failed = [];
         for (const s of chosen) {
-            const { value, error, report } = await rec.source(s.name, () => s.run({ opts: values, env: deps.env, clients: deps.clients, now, warn: deps.err }));
+            const { value, error, report } = await rec.source(s.name, () => s.run({ opts: values, env, clients: deps.clients, now, warn: deps.err }));
             let got;
             if (error !== undefined || !Array.isArray(value)) {
                 const message = error !== undefined ? String(error?.message ?? error) : "the source returned no list of results";

package/collector/src/config.js

@@ -28,6 +28,24 @@ export const CONFIG_SCHEMA = {
         out: { type: "string", minLength: 1, description: "Also write the signed payload to this file." },
         dryRun: { type: "boolean", description: "Print the payload and send nothing." },
         catalog: { type: "string", minLength: 1, description: "The check catalogue directory." },
+        credentials: {
+            type: "object",
+            description: "Per connector, the names of what it reads (sos-app writes them; sos-app sends a sealed value only for a name listed here). Names only, never a value.",
+            additionalProperties: {
+                type: "object",
+                additionalProperties: false,
+                required: ["sources"],
+                properties: {
+                    sources: { type: "array", items: { type: "string" } },
+                    secrets: { type: "array", items: { type: "string", pattern: "^[A-Z][A-Z0-9_]{0,99}$" } },
+                    files: { type: "array", items: { type: "string", pattern: "^[A-Z][A-Z0-9_]{0,99}$" } },
+                    settings: { type: "array", items: { type: "string", pattern: "^[A-Z][A-Z0-9_]{0,99}$" } },
+                    optional: { type: "object", additionalProperties: { type: "string" } },
+                    instead: { type: "object", additionalProperties: { type: "string" } },
+                    signIn: { type: "boolean" },
+                },
+            },
+        },
         sources: {
             type: "object",
             minProperties: 1,

package/collector/src/deliveries.js

@@ -0,0 +1,244 @@
+// What sos-app may deliver to the vault (apps/sos-app/docs/COLLECTOR_CHANNEL.md, section 8), and the vault's summary the
+// check-in reports. A check-in answer may carry `deliveries`; each is one of four things, and nothing else:
+//
+//   set         a value for a name the config's `credentials` lists, with that name's kind: a secret or file sealed in
+//               the browser to this collector's key (sos-app cannot open it), or a setting in clear
+//   remove      the vault's value for such a name
+//   import-env  move such names' values from sagentix-collector.env into the vault, then drop those lines
+//   test        run one connector of the config dry (resident mode only), and report its counts
+//
+// A delivery for a name the config does not list, or with another kind, is refused and reported, never applied: what
+// sos-app says cannot widen what this collector reads. No delivery can name a file, a command or a source option.
+// The outcome of each goes back in a signed POST /api/collect/vault/ack, with the vault's new summary.
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { signedPost, writePrivate } from "./channel.js";
+import { scrubText } from "./report.js";
+import { KINDS, MAX_VALUE, NAME, Vault, canonicalBind } from "./vault.js";
+export const ACK_PATH = "/api/collect/vault/ack";
+export const ENV_FILE = "sagentix-collector.env";
+export const MAX_DELIVERIES = 50;
+const ID = /^[A-Za-z0-9-]{1,64}$/;
+/** Each name a connector reads, with its kind: the only names a delivery may touch. */
+export function knownNames(creds) {
+    const m = new Map();
+    for (const c of Object.values(creds)) {
+        for (const n of c.secrets ?? [])
+            m.set(n, "secret");
+        for (const n of c.files ?? [])
+            m.set(n, "file");
+        for (const n of Object.values(c.instead ?? {}))
+            if (!m.has(n))
+                m.set(n, n.endsWith("_FILE") ? "file" : "secret");
+        for (const n of [...(c.settings ?? []), ...Object.keys(c.optional ?? {})])
+            if (!m.has(n))
+                m.set(n, "setting");
+    }
+    return m;
+}
+/** The settings of the connector a secret belongs to, as the vault holds them now: what a sealed value binds to. */
+export function bindFor(creds, name, v) {
+    const out = {};
+    for (const k of settingsOf(creds, name)) {
+        const val = v.get(k);
+        if (val !== undefined)
+            out[k] = val;
+    }
+    return out;
+}
+/** The settings (required and optional) of every connector that reads this secret or file. */
+export function settingsOf(creds, name) {
+    const out = new Set();
+    for (const c of Object.values(creds)) {
+        if (![...(c.secrets ?? []), ...(c.files ?? []), ...Object.values(c.instead ?? {})].includes(name))
+            continue;
+        for (const k of [...(c.settings ?? []), ...Object.keys(c.optional ?? {})])
+            out.add(k);
+    }
+    return [...out];
+}
+/** The config's credentials, or none when the file cannot be read. */
+export function credentialsIn(configPath) {
+    try {
+        return JSON.parse(readFileSync(configPath, "utf8").replace(/^\uFEFF/, "")).credentials ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** A file's text when it exists and is at most MAX_VALUE bytes; one open, so the size checked is the file read. */
+function readSmall(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return null;
+    }
+    try {
+        if (fstatSync(fd).size > MAX_VALUE)
+            return null;
+        const buf = Buffer.alloc(MAX_VALUE + 1);
+        const n = readSync(fd, buf, 0, buf.length, 0);
+        return n > MAX_VALUE ? null : buf.subarray(0, n).toString("utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The vault beside a config, as the check-in sees it. `test`: the agent's dry run of some sources (absent in `run`). */
+export function vaultBridge(o) {
+    const dir = dirname(o.configPath), envPath = join(dir, ENV_FILE);
+    let vault;
+    const v = () => (vault ??= new Vault(dir, o.holder));
+    const creds = () => {
+        try {
+            return JSON.parse(readFileSync(o.configPath, "utf8").replace(/^/, "")).credentials ?? {};
+        }
+        catch {
+            return {};
+        }
+    };
+    const envLines = (known) => !existsSync(envPath) ? [] : readFileSync(envPath, "utf8").split(/\r?\n/)
+        .map((l) => /^(?:export\s+)?([A-Z][A-Z0-9_]*)=(.*)$/.exec(l.trim()))
+        .filter((m) => !!m && known.has(m[1]) && m[2].length > 0)
+        .map((m) => ({ name: m[1], value: m[2].replace(/^(['"])(.*)\1$/, "$2") }));
+    function summary() {
+        const c = creds(), known = knownNames(c);
+        let sealKey = null, entries = [], error = null, protection = null;
+        try {
+            protection = v().protection;
+            // A setting's value goes along (a URL, a tenant id), so sos-app shows it and the browser binds a secret to it.
+            entries = v().list().map((e) => e.kind === "setting" ? { ...e, value: v().get(e.name) } : e);
+            sealKey = Object.keys(c).length ? v().sealPublicKey() : null;
+        }
+        catch (e) {
+            error = String(e?.message ?? e).slice(0, 300);
+        }
+        return { sealKey, protection, error, entries, envFile: [...new Set(envLines(known).map((l) => l.name))], credentials: c };
+    }
+    function importEnv(known) {
+        const moved = [], leftFiles = [], problems = [], c = creds();
+        // Settings first, so each secret binds to the settings it came with.
+        for (const l of envLines(known).sort((x, y) => Number(known.get(x.name) !== "setting") - Number(known.get(y.name) !== "setting"))) {
+            const kind = known.get(l.name);
+            try {
+                if (kind === "file") {
+                    const path = isAbsolute(l.value) ? l.value : join(dir, l.value);
+                    const text = readSmall(path);
+                    if (text === null) {
+                        problems.push(`${l.name}: the file it names is missing or too large`);
+                        continue;
+                    }
+                    v().set(l.name, text, { kind, now: o.now(), bind: bindFor(c, l.name, v()) });
+                    leftFiles.push(l.value);
+                }
+                else
+                    v().set(l.name, l.value, { kind, now: o.now(), ...(kind !== "setting" ? { bind: bindFor(c, l.name, v()) } : {}) });
+                moved.push(l.name);
+            }
+            catch (e) {
+                problems.push(`${l.name}: ${String(e?.message ?? e)}`);
+            }
+        }
+        if (moved.length) {
+            const keep = readFileSync(envPath, "utf8").split(/\r?\n/).filter((l) => !moved.includes(/^(?:export\s+)?([A-Z][A-Z0-9_]*)=/.exec(l.trim())?.[1] ?? ""));
+            writePrivate(envPath, keep.join("\n").replace(/\n*$/, "\n"));
+        }
+        return { moved, leftFiles, ...(problems.length ? { error: problems.join("; ") } : {}) };
+    }
+    async function apply(raw, a) {
+        if (!Array.isArray(raw))
+            return [];
+        const c = creds(), known = knownNames(c), out = [];
+        for (const d of raw.slice(0, MAX_DELIVERIES)) {
+            if (typeof d !== "object" || d === null || typeof d.id !== "string" || !ID.test(d.id))
+                continue;
+            const refuse = (error) => { out.push({ id: d.id, ok: false, error }); o.log(`vault: refused delivery ${d.id}: ${error}`); };
+            try {
+                if (d.op === "set" || d.op === "remove") {
+                    const name = String(d.name ?? ""), kind = known.get(name);
+                    if (!NAME.test(name) || !kind) {
+                        refuse(`${name.slice(0, 100)} is not a name this collector's connectors read`);
+                        continue;
+                    }
+                    if (d.op === "remove") {
+                        v().remove(name);
+                        o.log(`vault: ${name} removed`);
+                        out.push({ id: d.id, ok: true });
+                        continue;
+                    }
+                    if (d.kind !== kind || !KINDS.includes(d.kind)) {
+                        refuse(`${name} is a ${kind}, not a ${String(d.kind)}`);
+                        continue;
+                    }
+                    let value;
+                    if (kind === "setting") {
+                        if (typeof d.value !== "string" || !d.value.trim()) {
+                            refuse(`${name}: no value`);
+                            continue;
+                        }
+                        value = d.value.trim();
+                    }
+                    else {
+                        if (!d.sealed || d.sealed.name !== name || d.sealed.kind !== kind) {
+                            refuse(`${name}: a ${kind} must come sealed, for this name and kind`);
+                            continue;
+                        }
+                        // The connector's settings as they stand now must be the ones the person saw when sealing.
+                        const bind = d.sealed.bind ?? {}, want = bindFor(c, name, v());
+                        const missing = Object.values(c).filter((x) => [...(x.secrets ?? []), ...(x.files ?? []), ...Object.values(x.instead ?? {})].includes(name))
+                            .flatMap((x) => x.settings ?? []).filter((k) => want[k] === undefined);
+                        if (missing.length) {
+                            refuse(`${name}: set ${missing.join(", ")} first, so the secret is bound to where it goes`);
+                            continue;
+                        }
+                        if (canonicalBind(bind) !== canonicalBind(want)) {
+                            refuse(`${name}: the connector's settings changed since it was sealed; enter it again`);
+                            continue;
+                        }
+                        value = v().openSealed(o.keyId, d.sealed);
+                    }
+                    v().set(name, value, { kind, now: o.now(), ...(kind !== "setting" ? { bind: d.sealed.bind ?? {} } : {}) });
+                    o.log(`vault: ${name} set`);
+                    out.push({ id: d.id, ok: true });
+                }
+                else if (d.op === "import-env") {
+                    const r = importEnv(known);
+                    o.log(`vault: ${r.moved?.length ?? 0} value(s) moved from ${ENV_FILE}`);
+                    out.push({ id: d.id, ok: !r.error, ...r });
+                }
+                else if (d.op === "test") {
+                    if (!a.agent || !o.test)
+                        continue; // left for the resident agent, which can run it now
+                    const id = String(d.connector ?? ""), cred = c[id];
+                    if (!cred) {
+                        refuse(`${id.slice(0, 40)} is not a connector of this collector`);
+                        continue;
+                    }
+                    const t = await o.test(cred.sources);
+                    const secrets = v().all().filter((e) => e.kind !== "setting").map((e) => e.value).filter((x) => x.length >= 6);
+                    out.push({ id: d.id, ok: true, test: { ...t, errors: t.errors.slice(0, 10).map((e) => scrubText(e, secrets).slice(0, 500)) } });
+                }
+                else
+                    refuse(`unknown operation ${String(d.op).slice(0, 20)}`);
+            }
+            catch (e) {
+                refuse(String(e?.message ?? e).slice(0, 300));
+            }
+        }
+        return out;
+    }
+    return { summary, apply };
+}
+/** Reports what the deliveries did, with the vault's summary after them. Never throws. */
+export async function ack(c, results, s, log) {
+    try {
+        const r = await signedPost(c, ACK_PATH, new TextEncoder().encode(JSON.stringify({ format: "sagentix-vault-ack/1", results, vault: s })));
+        if (r.status !== 200)
+            log(`warning: vault ack: HTTP ${r.status}`);
+    }
+    catch (e) {
+        log(`warning: vault ack failed: ${String(e?.message ?? e)}`);
+    }
+}

package/collector/src/report.js

@@ -187,6 +187,7 @@ export class RunRecorder {
     }
 }
 // ── Building, trimming, sending ───────────────────────────────────────────────────────────────────
+/** `secrets`: values to cut whatever their variable is called (the vault's secrets and files). */
 export function buildReport(rec, o) {
     const report = {
         format: REPORT_FORMAT,
@@ -205,7 +206,8 @@ export function buildReport(rec, o) {
     };
     if (rec.log.length > MAX_LOG_LINES)
         report.log[MAX_LOG_LINES - 1] = `(log cut: ${rec.log.length} lines, the first ${MAX_LOG_LINES - 1} kept)`;
-    return trimReport(scrubDeep(report, envSecrets(o.env)));
+    const secrets = [...new Set([...envSecrets(o.env), ...(o.secrets ?? []).filter((v) => v.length >= 6)])].sort((a, b) => b.length - a.length);
+    return trimReport(scrubDeep(report, secrets));
 }
 const bytes = (r) => Buffer.byteLength(JSON.stringify(r, null, 2));
 /** At most MAX_REPORT_BYTES: drops log lines first, then calls, then stacks, and says so in a last log line. */

package/collector/src/vault.js

@@ -0,0 +1,303 @@
+// The collector's vault (apps/sos-app/docs/COLLECTOR_VAULT.md): the connectors' secrets and settings. A person
+// types them in sos-app; the browser seals each one to this collector's own X25519 key, so sos-app stores and relays
+// only what it cannot open; the collector opens it here, and each run reads the vault into its own environment, so the
+// sources do not change.
+//
+// One file beside the config, sagentix-collector.vault (mode 0600): each value sealed on its own with AES-256-GCM, its
+// name as additional data, so a value cannot be moved under another name. The names and dates are readable without
+// the key (the check-in reports them to sos-app); the values are not. The file is only as safe as its 256-bit key, so the key lives
+// in the strongest place the computer offers, in this order:
+//
+//   systemd     $CREDENTIALS_DIRECTORY/sagentix-vault-key: a systemd credential (LoadCredentialEncrypted=, sealed to
+//               the TPM where there is one), never on disk in clear
+//   docker      /run/secrets/sagentix-vault-key: a Docker secret
+//   keychain    macOS: the Keychain item sagentix-collector-vault / <key id>, through `security` (base64 on stdin)
+//   dpapi       Windows: sagentix-collector.vault.key.dpapi, the key protected by DPAPI for the collector's account
+//               (the protection Windows Credential Manager uses), through PowerShell (base64 on stdin)
+//   file        anywhere else: sagentix-collector.vault.key, mode 0600; sos-app says the protection is the
+//               file's permission only, and how to seal it
+//
+// A value is never logged and never sent to sos-app in clear.
+import { spawnSync } from "node:child_process";
+import { createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writePrivate } from "./channel.js";
+export const VAULT_FILE = "sagentix-collector.vault";
+export const KEY_FILE = "sagentix-collector.vault.key";
+export const DPAPI_FILE = "sagentix-collector.vault.key.dpapi";
+export const CREDENTIAL_NAME = "sagentix-vault-key";
+export const DOCKER_SECRET = `/run/secrets/${CREDENTIAL_NAME}`;
+export const KEYCHAIN_SERVICE = "sagentix-collector-vault";
+/** A name the vault takes: an environment variable's. */
+export const NAME = /^[A-Z][A-Z0-9_]{0,99}$/;
+export const MAX_VALUE = 64 * 1024;
+export const KINDS = ["secret", "file", "setting"];
+export const SEAL_FORMAT = "sagentix-seal/1";
+/** The bytes both sides bind in: the format, the collector's key id, the name and the kind. A value sealed for one
+ *  name, kind or collector does not open as another. */
+export const sealInfo = (keyId, name, kind, bind = {}) => Buffer.from(`${SEAL_FORMAT}\n${keyId}\n${name}\n${kind}\n${canonicalBind(bind)}`);
+/** The settings a value is bound to, in one spelling both sides compute: names sorted, JSON. */
+export const canonicalBind = (b) => JSON.stringify(Object.keys(b).sort().map((k) => [k, b[k]]));
+export const realExec = (cmd, args, input) => {
+    const r = spawnSync(cmd, args, { input, encoding: "utf8", timeout: 30_000, windowsHide: true });
+    return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+};
+const key32 = (b) => (b && b.length === 32 ? b : null);
+const fromB64 = (s) => key32(Buffer.from(s.trim(), "base64"));
+function fileHolder(path, protection, readOnly) {
+    return {
+        protection,
+        read: () => {
+            if (!existsSync(path))
+                return null;
+            const raw = readFileSync(path);
+            return raw.length === 32 ? raw : fromB64(raw.toString("utf8"));
+        },
+        create: () => {
+            if (readOnly)
+                throw new Error(`the vault key ${path} is provided by ${protection} and is missing or unreadable`);
+            const k = randomBytes(32);
+            writePrivate(path, k.toString("base64") + "\n");
+            return k;
+        },
+    };
+}
+/** `keychain`: a keychain file other than the login one (the tests use a throwaway keychain). */
+function keychainHolder(account, exec, keychain) {
+    // The account goes into a `security -i` command line: a key id only (letters, digits, -).
+    if (!/^[A-Za-z0-9-]{1,80}$/.test(account))
+        throw new Error("the key id is not one the Keychain item may be named after");
+    const kc = keychain ? [keychain] : [];
+    return {
+        protection: "keychain",
+        read: () => {
+            const r = exec("/usr/bin/security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", account, "-w", ...kc], "");
+            return r.status === 0 ? fromB64(r.stdout) : null;
+        },
+        create: () => {
+            const k = randomBytes(32);
+            // `security -i` reads its commands on standard input, so the key never appears in a process listing.
+            const r = exec("/usr/bin/security", ["-i"], `add-generic-password -U -s ${KEYCHAIN_SERVICE} -a ${account} -l "Sagentix collector vault" -w ${k.toString("base64")}${keychain ? ` "${keychain}"` : ""}\n`);
+            if (r.status !== 0)
+                throw new Error(`the Keychain refused the vault key (${r.stderr.trim() || r.status})`);
+            return k;
+        },
+    };
+}
+const DPAPI_PROTECT = "$in=[Console]::In.ReadToEnd().Trim();Add-Type -AssemblyName System.Security;"
+    + "[Convert]::ToBase64String([Security.Cryptography.ProtectedData]::Protect([Convert]::FromBase64String($in),$null,'CurrentUser'))";
+const DPAPI_UNPROTECT = "$in=[Console]::In.ReadToEnd().Trim();Add-Type -AssemblyName System.Security;"
+    + "[Convert]::ToBase64String([Security.Cryptography.ProtectedData]::Unprotect([Convert]::FromBase64String($in),$null,'CurrentUser'))";
+const PS = ["-NoProfile", "-NonInteractive", "-Command"];
+function dpapiHolder(path, exec) {
+    return {
+        protection: "dpapi",
+        read: () => {
+            if (!existsSync(path))
+                return null;
+            const r = exec("powershell.exe", [...PS, DPAPI_UNPROTECT], readFileSync(path, "utf8"));
+            return r.status === 0 ? fromB64(r.stdout) : null;
+        },
+        create: () => {
+            const k = randomBytes(32);
+            const r = exec("powershell.exe", [...PS, DPAPI_PROTECT], k.toString("base64"));
+            if (r.status !== 0 || !r.stdout.trim())
+                throw new Error(`DPAPI refused the vault key (${r.stderr.trim() || r.status})`);
+            writePrivate(path, r.stdout.trim() + "\n");
+            return k;
+        },
+    };
+}
+/** The strongest key holder this computer offers (see the top of this file). */
+export function keyHolderFor(dir, keyId, o) {
+    const exec = o.exec ?? realExec, exists = o.exists ?? existsSync;
+    const credDir = o.env.CREDENTIALS_DIRECTORY;
+    if (credDir && exists(join(credDir, CREDENTIAL_NAME)))
+        return fileHolder(join(credDir, CREDENTIAL_NAME), "systemd", true);
+    if (exists(DOCKER_SECRET))
+        return fileHolder(DOCKER_SECRET, "docker", true);
+    if (o.runner !== "docker" && o.platform === "darwin")
+        return keychainHolder(keyId, exec, o.keychain);
+    if (o.runner !== "docker" && o.platform === "win32")
+        return dpapiHolder(join(dir, DPAPI_FILE), exec);
+    return fileHolder(join(dir, KEY_FILE), "file", false);
+}
+export class Vault {
+    path;
+    holder;
+    key = null;
+    constructor(dir, holder) { this.path = join(dir, VAULT_FILE); this.holder = holder; }
+    get protection() { return this.holder.protection; }
+    doc() {
+        if (!existsSync(this.path))
+            return { format: "sagentix-vault/1", entries: {} };
+        const d = JSON.parse(readFileSync(this.path, "utf8"));
+        if (d?.format !== "sagentix-vault/1" || typeof d.entries !== "object")
+            throw new Error(`${this.path} is not a collector vault`);
+        return d;
+    }
+    write(d) {
+        // A new file renamed over the old one, so a crash mid-write never leaves half a vault.
+        const tmp = `${this.path}.${randomBytes(4).toString("hex")}.tmp`;
+        writePrivate(tmp, JSON.stringify(d, null, 1) + "\n");
+        renameSync(tmp, this.path);
+    }
+    /** The key, made on the first write when there is none. Reading an empty vault needs no key. */
+    keyFor(create) {
+        if (this.key)
+            return this.key;
+        this.key = this.holder.read();
+        if (!this.key && create)
+            this.key = this.holder.create();
+        return this.key;
+    }
+    /** Names, dates and whether each is a secret: no value, no key needed. */
+    list() {
+        return Object.entries(this.doc().entries).map(([name, e]) => ({ name, setAt: e.setAt, kind: e.kind, ...(e.bind ? { bind: e.bind } : {}) })).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    set(name, value, o) {
+        if (!KINDS.includes(o.kind))
+            throw new Error(`${o.kind} is not a kind of vault entry`);
+        if (!NAME.test(name))
+            throw new Error(`${name} is not a name the vault takes (capital letters, digits and _)`);
+        if (typeof value !== "string" || value.length === 0)
+            throw new Error("the value is empty");
+        if (Buffer.byteLength(value) > MAX_VALUE)
+            throw new Error(`the value is larger than ${MAX_VALUE / 1024} KiB`);
+        const key = this.keyFor(true);
+        const iv = randomBytes(12), c = createCipheriv("aes-256-gcm", key, iv);
+        c.setAAD(Buffer.from(`sagentix-vault/1\n${name}`));
+        const data = Buffer.concat([c.update(value, "utf8"), c.final()]);
+        const d = this.doc();
+        d.entries[name] = { iv: iv.toString("base64"), tag: c.getAuthTag().toString("base64"), data: data.toString("base64"), setAt: o.now.toISOString(), kind: o.kind, ...(o.bind && o.kind !== "setting" ? { bind: o.bind } : {}) };
+        this.write(d);
+    }
+    remove(name) {
+        const d = this.doc();
+        if (!(name in d.entries))
+            return false;
+        delete d.entries[name];
+        this.write(d);
+        return true;
+    }
+    /** One value, or undefined when it is not there. Throws when the key is missing or the value was tampered with. */
+    get(name) {
+        const e = this.doc().entries[name];
+        if (!e)
+            return undefined;
+        const key = this.keyFor(false);
+        if (!key)
+            throw new Error(`the vault key is missing (${this.holder.protection}); the vault cannot be read`);
+        const d = createDecipheriv("aes-256-gcm", key, Buffer.from(e.iv, "base64"));
+        d.setAAD(Buffer.from(`sagentix-vault/1\n${name}`));
+        d.setAuthTag(Buffer.from(e.tag, "base64"));
+        try {
+            return Buffer.concat([d.update(Buffer.from(e.data, "base64")), d.final()]).toString("utf8");
+        }
+        catch {
+            throw new Error(`the vault value ${name} does not open with this key (changed, or sealed with another key)`);
+        }
+    }
+    sealWith(key, plain, aad) {
+        const iv = randomBytes(12), c = createCipheriv("aes-256-gcm", key, iv);
+        c.setAAD(Buffer.from(aad));
+        const data = Buffer.concat([c.update(plain), c.final()]);
+        return { iv: iv.toString("base64"), tag: c.getAuthTag().toString("base64"), data: data.toString("base64") };
+    }
+    /** This collector's sealing public key (32 bytes, base64url), made with the vault key on first use. */
+    sealPublicKey() {
+        const d = this.doc();
+        if (d.seal)
+            return d.seal.publicKey;
+        const key = this.keyFor(true);
+        const { privateKey, publicKey } = generateKeyPairSync("x25519");
+        const raw = publicKey.export({ format: "jwk" }).x;
+        d.seal = { ...this.sealWith(key, privateKey.export({ type: "pkcs8", format: "der" }), "sagentix-vault/1\nseal"), publicKey: raw };
+        this.write(d);
+        return raw;
+    }
+    /** Opens a value sealed in the browser for this collector (ECDH X25519, HKDF-SHA256, AES-256-GCM); throws when it
+     *  was sealed for another collector, name or kind, or changed on the way. */
+    openSealed(keyId, v) {
+        const d = this.doc();
+        if (!d.seal)
+            throw new Error("this collector has no sealing key yet");
+        const key = this.keyFor(false);
+        if (!key)
+            throw new Error(`the vault key is missing (${this.holder.protection})`);
+        const dk = createDecipheriv("aes-256-gcm", key, Buffer.from(d.seal.iv, "base64"));
+        dk.setAAD(Buffer.from("sagentix-vault/1\nseal"));
+        dk.setAuthTag(Buffer.from(d.seal.tag, "base64"));
+        const priv = createPrivateKey({ key: Buffer.concat([dk.update(Buffer.from(d.seal.data, "base64")), dk.final()]), format: "der", type: "pkcs8" });
+        const epk = Buffer.from(v.epk, "base64url");
+        if (epk.length !== 32)
+            throw new Error("the sealed value's ephemeral key is not 32 bytes");
+        const shared = diffieHellman({ privateKey: priv, publicKey: createPublicKey({ key: { kty: "OKP", crv: "X25519", x: v.epk }, format: "jwk" }) });
+        const info = sealInfo(keyId, v.name, v.kind, v.bind ?? {});
+        const aes = Buffer.from(hkdfSync("sha256", shared, Buffer.concat([epk, Buffer.from(d.seal.publicKey, "base64url")]), info, 32));
+        const all = Buffer.from(v.data, "base64"), iv = Buffer.from(v.iv, "base64");
+        if (iv.length !== 12 || all.length < 17)
+            throw new Error("the sealed value is malformed");
+        const dc = createDecipheriv("aes-256-gcm", aes, iv);
+        dc.setAAD(info);
+        dc.setAuthTag(all.subarray(all.length - 16));
+        try {
+            return Buffer.concat([dc.update(all.subarray(0, all.length - 16)), dc.final()]).toString("utf8");
+        }
+        catch {
+            throw new Error(`the sealed value for ${v.name} does not open with this collector's key`);
+        }
+    }
+    /** Every entry with its value, for a run's environment. */
+    all() {
+        return this.list().map(({ name, kind, bind }) => ({ name, kind, value: this.get(name), ...(bind ? { bind } : {}) }));
+    }
+}
+/**
+ * A run's environment: the process's own, plus each vault entry it does not already set (a variable set on purpose
+ * wins). `settingsOf(name)`: the settings of the connector a secret belongs to (the config's credentials). A `file` entry is written to a private temporary folder beside the config, its path put in the variable, and
+ * the folder removed by `cleanup` when the run ends. No vault file: the environment as it is.
+ */
+export function runEnv(dir, holder, base, settingsOf = () => []) {
+    const v = new Vault(dir, holder);
+    if (!existsSync(v.path))
+        return { env: base, used: [], secrets: [], warnings: [], cleanup: () => { } };
+    const env = { ...base }, used = [], secrets = [], warnings = [];
+    const all = v.all();
+    for (const e of all)
+        if (e.kind === "setting" && !env[e.name]) {
+            env[e.name] = e.value;
+            used.push(e.name);
+        }
+    let tmp;
+    for (const e of all) {
+        if (e.kind === "setting" || env[e.name])
+            continue;
+        // A secret is used only while its connector's settings are the ones it was set with: all of them, so a setting
+        // added since (an optional URL) counts as a change too.
+        if (e.bind) {
+            const now = {};
+            for (const k of settingsOf(e.name))
+                if (env[k])
+                    now[k] = env[k];
+            if (canonicalBind(now) !== canonicalBind(e.bind)) {
+                const changed = [...new Set([...Object.keys(now), ...Object.keys(e.bind)])].filter((k) => now[k] !== e.bind[k]);
+                warnings.push(`${e.name} is not used: ${changed.join(", ")} changed since it was set; set ${e.name} again`);
+                continue;
+            }
+        }
+        if (e.kind === "file") {
+            tmp ??= mkdtempSync(join(dir, ".sagentix-run-"));
+            const p = join(tmp, e.name.toLowerCase());
+            writePrivate(p, e.value);
+            env[e.name] = p;
+        }
+        else
+            env[e.name] = e.value;
+        used.push(e.name);
+        secrets.push(e.value, ...e.value.split(/\r?\n/).filter((l) => l.length >= 16));
+    }
+    return { env, used, secrets, warnings, cleanup: () => { if (tmp)
+            rmSync(tmp, { recursive: true, force: true }); } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentix-inc/evidence-collector",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Customer-side evidence collector: reads systems read-only, runs checks, signs the results and pushes them outbound to sos-app.",
   "type": "module",
   "engines": {