@sagentix-inc/evidence-collector 0.3.5 → 0.4.1

package/apps/sos-app/src/data/checks/web.json

@@ -1,6 +1,6 @@
 {
  "source": "web",
- "title": "Websites and APIs by URL (passive GET, TLS handshake and DNS, for hosts the organization proved it controls)",
+ "title": "Websites and APIs by URL (passive GET, TLS handshake and DNS, for hosts the organization proved it controls), including its privacy notice and consent banner",
  "readScopes": [
   "None: the collector reads what any browser sees. Each host must first be proven: a TXT record at _sagentix-collector.<host> holding sagentix-collector-verification=<token>, or https://<host>/.well-known/sagentix-collector.txt holding that line, with the token sos-app issued."
  ],
@@ -82,6 +82,36 @@
    "title": "The domain limits which certificate authorities may issue for it (CAA); recommended",
    "scope": "The CAA record set at the domain or its nearest parent that has one (RFC 8659 section 3).",
    "evidenceType": "Configuration"
+  },
+  {
+   "id": "web.consent_banner",
+   "title": "The declared page loads a consent-management platform before its third-party scripts can track visitors",
+   "scope": "One GET of each declared URL, where robots.txt allows: the page's HTML is searched for the script host each vendor's installation guide names (OneTrust, Osano, Cookiebot, Usercentrics, TrustArc, Termly, iubenda, Didomi, CookieYes, Transcend). A page with no script from another site is skipped; a banner a tag manager loads later is not seen.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "web.privacy_notice_published",
+   "title": "A privacy notice is published and reachable at the address the organization declared",
+   "scope": "GET of each --web-privacy-url on a proven host, where robots.txt allows: HTTP 200, an HTML page, and a title or first heading that names privacy or personal information (English or French). Redirects are not followed.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "web.privacy_notice_dated",
+   "title": "The privacy notice shows a last-updated or effective date within the review period (default one year)",
+   "scope": "The first date that follows a label such as 'Last updated', 'Effective date' or 'Dernière mise à jour' in the notice's text; --web-privacy-max-age-days sets the period (default 365).",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "web.privacy_notice_topics",
+   "title": "The privacy notice covers what is collected, why, who receives it, how long it is kept, access and correction, whom to contact, and consent",
+   "scope": "Seven topics, each a set of English and French phrases, searched in the notice's text (NIST SP 800-53 Rev. 5 PT-5; PIPEDA Schedule 1 Principles 4.5 and 4.8; OPC Guidelines for obtaining meaningful consent). A phrase found is a clue: a person confirms the wording.",
+   "evidenceType": "Configuration"
+  },
+  {
+   "id": "web.privacy_request_channel",
+   "title": "The privacy notice tells people how to ask for, correct or delete their personal information (a privacy mailbox or a request form)",
+   "scope": "Links on the notice: a mailto to a privacy-named mailbox (privacy@, dpo@, ...) or a link whose address or text names a privacy or access request. Only the mail domain is kept, never the mailbox.",
+   "evidenceType": "Configuration"
   }
  ]
 }

package/collector/package.json

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

package/collector/src/cli.js

@@ -10,6 +10,9 @@
 //   collector agent --config collector.config.json   stays connected (outbound WebSocket); runs when sos-app asks
 //   collector config-schema                  prints the JSON schema of the config file
 //   collector google-login --client <client JSON> [--token <file>]   one-time Google Workspace sign-in
+//   collector policies --config collector.config.json   pushes the policy folders for sos-app to match (src/policies.ts)
+//   collector doctor --config collector.config.json [--source x]   credentials and permissions per source; sends nothing (src/doctor.ts)
+//   run options for every source: --concurrency <n> (default 4), --http-timeout <s> (default 60), --verbose, --debug
 //   collector run --endpoint <url> --key-id <id> [--key <pem> | env SAGENTIX_COLLECTOR_KEY]
 //                 --source cloudflare[,...] [source options] [--catalog <dir>] [--dry-run] [--out <file>]
 //                 [--fedramp-target <id> [--class A|B|C|D]]
@@ -17,7 +20,7 @@
 // Exit codes: 0 sent (or dry run), 1 error (bad key, network, a source that failed), 2 usage, 3 nothing to send,
 // 4 sos-app refused the push (its message is printed); `agent` only: 75 a signed update was written, restart me.
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { DEFAULT_CATALOG_DIR, loadCatalog } from "./catalog.js";
@@ -29,11 +32,14 @@ import { googleLogin } from "./google_login.js";
 import { V1_COLLECT_PATH, v1Payload } from "./v1/index.js";
 import { CLASSES } from "./v1/rules.js";
 import { EXIT_UPDATE, checkin, detectRunner, modeOf } from "./channel.js";
-import { RunRecorder, buildReport, deliverReport } from "./report.js";
+import { RunRecorder, buildReport, deliverReport, envSecrets, scrubText } from "./report.js";
+import { pool } from "./pool.js";
+import { PROBES, doctorHint } from "./doctor.js";
 import { agent } from "./agent.js";
 import { VAULT_FILE, Vault, keyHolderFor, runEnv } from "./vault.js";
 import { applyRefs } from "./refs.js";
 import { credentialsIn, settingsOf, vaultBridge } from "./deliveries.js";
+import { APPROVED_DIR, DOCUMENTS_KEY_ENV, pullApproved, pushPolicies, writeApproved } from "./policies.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). */
@@ -63,7 +69,26 @@ const COMMON_OPTIONS = {
     class: { type: "string" },
     "cpo-uri": { type: "string" },
     config: { type: "string" },
+    concurrency: { type: "string" },
+    "http-timeout": { type: "string" },
+    verbose: { type: "boolean" },
+    debug: { type: "boolean" },
 };
+/** Sources run side by side, at most this many at once (--concurrency; 1 is the old one-after-another). */
+export const DEFAULT_CONCURRENCY = 4;
+export const MAX_CONCURRENCY = 16;
+/** Seconds before an outbound call made by a source is abandoned (--http-timeout; 0 never). */
+export const DEFAULT_HTTP_TIMEOUT_S = 60;
+/** --concurrency and --http-timeout, or why they are wrong. */
+export function runTuning(values) {
+    const c = values.concurrency === undefined ? DEFAULT_CONCURRENCY : Number(values.concurrency);
+    if (!Number.isInteger(c) || c < 1 || c > MAX_CONCURRENCY)
+        return `--concurrency must be a whole number from 1 to ${MAX_CONCURRENCY}.`;
+    const t = values["http-timeout"] === undefined ? DEFAULT_HTTP_TIMEOUT_S : Number(values["http-timeout"]);
+    if (!Number.isFinite(t) || t < 0 || t > 3600)
+        return "--http-timeout must be a number of seconds from 0 (never) to 3600.";
+    return { concurrency: c, timeoutMs: Math.round(t * 1000) };
+}
 function usage(sources) {
     const opts = sources.flatMap((s) => Object.entries(s.options).map(([n, o]) => `    --${n}${o.type === "string" ? " <value>" : ""}${o.multiple ? " (repeatable)" : ""}  [${s.name}] ${o.help}`));
     return `usage:
@@ -72,10 +97,14 @@ function usage(sources) {
   collector agent --config collector.config.json   (stays connected to sos-app; runs when it asks)
   collector config-schema
   collector google-login --client <Desktop app client JSON> [--token sagentix-google-token.json] [--port <n>] [--login-hint <email>] [--no-browser]
+  collector doctor --config collector.config.json [--source <name>]   checks each source's credentials and permissions; collects and sends nothing
   collector run --endpoint <url> --key-id <id> [--key <pem file>] --source ${sources.map((s) => s.name).join("|")}[,...]
                 [source options] [--catalog <checks dir>] [--dry-run] [--out <file>]
+                [--concurrency <1-${MAX_CONCURRENCY}, default ${DEFAULT_CONCURRENCY}>] [--http-timeout <seconds, default ${DEFAULT_HTTP_TIMEOUT_S}>] [--verbose] [--debug]
                 [--fedramp-target <id> [--class A|B|C|D] [--cpo-uri <url>]]
   The private key may come from ${KEY_ENV} (PEM text) instead of --key.
+  --verbose prints each outbound call (method, host, path with ids as :id; never a query, header or body) and each retry;
+  --debug also prints a failed source's stack. A table of every source (checks, calls, retries, time) ends each run.
   Source options:
 ${opts.join("\n")}
   Every run checks in first (an update sos-app names is taken only with a valid Sagentix release signature, and only
@@ -120,10 +149,77 @@ function serverMessage(text) {
         return text;
     }
 }
-export async function run(argv, deps) {
-    // Every line the run writes to stderr also goes into its report (scrubbed there).
-    const rec = new RunRecorder(deps.now);
-    deps = { ...deps, err: rec.tee(deps.err) };
+/**
+ * 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.
+ */
+async function vaultEnv(o) {
+    const { configPath, keyId, dir, runner, deps } = o;
+    if (!configPath || !keyId)
+        return { env: deps.env, cleanup: () => { }, secrets: [] };
+    try {
+        const creds = credentialsIn(resolve(configPath));
+        const holder = deps.vaultKey?.(dir, keyId) ?? keyHolderFor(dir, keyId, { env: deps.env, platform: process.platform, runner });
+        const r = runEnv(dir, holder, deps.env, (name) => settingsOf(creds, name));
+        // Connectors read from the client's own vault (src/refs.ts) take all their names from there, after the local vault.
+        const refs = existsSync(join(dir, VAULT_FILE)) ? new Vault(dir, holder).refs() : {};
+        const f = Object.keys(refs).length ? await applyRefs(dir, refs, creds, r.env, deps.channel ?? deps.fetch) : null;
+        const used = r.used.length + (f?.used.length ?? 0), warnings = [...r.warnings, ...(f?.warnings ?? [])];
+        if (used)
+            deps.err(`vault: ${used} value(s) from ${VAULT_FILE}${f ? " and your own vault" : ""}`);
+        for (const w of warnings)
+            deps.err(`warning: vault: ${w}`);
+        if (warnings.length)
+            o.note(warnings);
+        return { env: f?.env ?? r.env, cleanup: () => { r.cleanup(); f?.cleanup(); }, secrets: [...r.secrets, ...(f?.secrets ?? [])] };
+    }
+    catch (e) {
+        const w = `the vault could not be opened: ${String(e?.message ?? e)}`;
+        deps.err(w);
+        o.note([w]);
+        return { env: deps.env, cleanup: () => { }, secrets: [] };
+    }
+}
+/** One line of the --verbose call log: the call's shape, scrubbed of the run's secrets. */
+function callLine(c, secrets) {
+    return scrubText(`[${c.source}] ${c.method} ${c.host}${c.path} -> ${c.status || "no answer"} in ${c.ms} ms${c.error ? ` (${c.error})` : ""}`, secrets);
+}
+/** The end-of-run table, one row per source: what it judged, what it called, how long it took. */
+export function summaryTable(reports, stats) {
+    const rows = reports.map((r) => {
+        const st = stats.get(r.name) ?? { calls: 0, retries: 0, httpErrors: 0 };
+        return [r.name, String(r.pass + r.fail + r.skipped), String(r.pass), String(r.fail), String(r.skipped), String(st.calls), String(st.retries), String(st.httpErrors),
+            `${(r.ms / 1000).toFixed(1)} s`, r.error ? "ERROR" : r.pass + r.fail ? "read" : "nothing read"];
+    });
+    const head = ["source", "results", "pass", "fail", "skipped", "calls", "retries", "http errors", "time", "source status"];
+    const total = rows.length > 1 ? [["total", ...[1, 2, 3, 4, 5, 6, 7].map((i) => String(rows.reduce((a, r) => a + Number(r[i]), 0))),
+            `${(reports.reduce((a, r) => Math.max(a, r.ms), 0) / 1000).toFixed(1)} s max`, ""]] : [];
+    const all = [head, ...rows, ...total];
+    const w = head.map((_, i) => Math.max(...all.map((r) => r[i].length)));
+    const line = (r) => r.map((c, i) => (i === 0 || i === r.length - 1 ? c.padEnd(w[i]) : c.padStart(w[i]))).join("  ").trimEnd();
+    return [line(head), w.map((n) => "-".repeat(n)).join("  "), ...rows.map(line), ...(total.length ? [w.map((n) => "-".repeat(n)).join("  "), line(total[0])] : [])];
+}
+/** A short fix for each refused call in the results: source, check, HTTP status and what to grant (src/doctor.ts). */
+export function problemLines(results, max = 20) {
+    const seen = new Set(), out = [];
+    for (const r of results) {
+        const st = r.apiError?.status;
+        if (r.result !== "skipped" || st === undefined || (st !== 401 && st !== 403))
+            continue;
+        const source = r.check.split(".")[0];
+        const k = `${r.check}|${st}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        if (out.length < max)
+            out.push(`  ${r.check} [${r.resource}]: HTTP ${st}${st === 401 ? " (credential refused)" : " (permission missing)"}; fix: ${doctorHint(source)}`);
+    }
+    if (seen.size > max)
+        out.push(`  … and ${seen.size - max} more`);
+    return out;
+}
+/** The run's options: the command line over the config file (--source adds to the file's), or the usage exit code. */
+function parseRunArgs(argv, deps) {
     const sourceOptions = {};
     for (const s of deps.sources) {
         for (const [n, o] of Object.entries(s.options)) {
@@ -152,8 +248,147 @@ export async function run(argv, deps) {
         const src = [...(c.values.source ?? []), ...(given.source ?? [])];
         values = { ...c.values, ...given, source: src };
     }
+    return { values, configPath };
+}
+/**
+ * `collector doctor`: per configured source, its credentials and one cheap read per permission it needs (src/doctor.ts),
+ * printed as pass or fail with the fix. Nothing is collected, signed or sent: no check-in, no push, no run report.
+ * With --config, --source narrows the file's sources to those named. Exit 0 when every check passes, 1 otherwise.
+ */
+export async function doctorCommand(argv, deps) {
+    const parsed = parseRunArgs(argv, deps);
+    if (typeof parsed === "number")
+        return parsed;
+    const { values, configPath } = parsed;
+    const tuning = runTuning(values);
+    if (typeof tuning === "string") {
+        deps.err(tuning);
+        return EXIT.usage;
+    }
+    // From the config, --source picks among the file's sources rather than adding to them.
+    const cli = argv.flatMap((a, i) => (a === "--source" ? [argv[i + 1]] : a.startsWith("--source=") ? [a.slice(9)] : [])).flatMap((s) => (s ?? "").split(",")).map((s) => s.trim()).filter(Boolean);
+    const all = (values.source ?? []).flatMap((s) => s.split(",")).map((s) => s.trim()).filter(Boolean);
+    const names = [...new Set(configPath && cli.length ? cli : all)];
+    if (!names.length) {
+        deps.err(`doctor: name the sources (--config with a "sources" block, or --source ${deps.sources.map((s) => s.name).join("|")}).`);
+        return EXIT.usage;
+    }
+    const unknown = names.filter((n) => !deps.sources.some((s) => s.name === n));
+    if (unknown.length) {
+        deps.err(`unknown source ${unknown.join(", ")}; known: ${deps.sources.map((x) => x.name).join(", ")}.`);
+        return EXIT.usage;
+    }
+    const keyId = typeof values["key-id"] === "string" ? values["key-id"] : undefined;
+    const dir = configPath ? dirname(resolve(configPath)) : (deps.cwd ?? process.cwd());
+    const runner = detectRunner(deps.env);
+    const lines = [];
+    const out = (s) => lines.push(s);
+    // The collector key, read and parsed locally; it is not used to sign anything here.
+    const keyChecks = [];
+    let pem;
+    if (typeof values.key === "string") {
+        try {
+            pem = readFileSync(values.key, "utf8");
+        }
+        catch (e) {
+            keyChecks.push({ what: "collector key", verdict: "fail", detail: `${values.key}: ${e.code ?? String(e)}`, fix: "point keyFile (or --key) at the PEM `collector keygen` wrote" });
+        }
+    }
+    else
+        pem = deps.env[KEY_ENV];
+    if (pem) {
+        try {
+            keyChecks.push({ what: "collector key", verdict: "pass", detail: `Ed25519 public key ${publicKeyFromPrivate(pem).slice(0, 12)}…${keyId ? `, key id ${keyId}` : " (no keyId: only --dry-run runs)"}` });
+        }
+        catch {
+            keyChecks.push({ what: "collector key", verdict: "fail", detail: "not an Ed25519 private key", fix: "use the PEM `collector keygen` wrote" });
+        }
+    }
+    else if (!keyChecks.length)
+        keyChecks.push({ what: "collector key", verdict: "skip", detail: `no --key and no ${KEY_ENV}: only --dry-run runs` });
+    if (typeof values.endpoint === "string") {
+        try {
+            collectUrl(values.endpoint);
+            keyChecks.push({ what: "endpoint", verdict: "pass", detail: new URL(values.endpoint).origin });
+        }
+        catch (e) {
+            keyChecks.push({ what: "endpoint", verdict: "fail", detail: e.message, fix: "set endpoint to your sos-app origin, https://…" });
+        }
+    }
+    const { env, cleanup, secrets } = await vaultEnv({ configPath, keyId, dir, runner, deps, note: () => { } });
+    const scrub = [...new Set([...envSecrets(env), ...secrets.filter((v) => v.length >= 6)])].sort((a, b) => b.length - a.length);
+    const results = [{ source: "collector", checks: keyChecks }];
+    const now = deps.now();
+    // One wrapper around fetch, with the run's timeout, so a probe that hangs ends like a run's call would.
+    const rec = new RunRecorder(deps.now, undefined, { timeoutMs: tuning.timeoutMs });
+    const release = rec.hold();
+    try {
+        const outcomes = await pool(names, tuning.concurrency, (name) => rec.source(name, async () => {
+            const probe = PROBES[name];
+            if (!probe)
+                return [{ what: "self-test", verdict: "skip", detail: "this source has no self-test; try `collector run --dry-run --source " + name + "`" }];
+            return probe({ opts: values, env, clients: deps.clients, now, warn: () => { } });
+        }));
+        for (const [i, o] of outcomes.entries()) {
+            const v = o.status === "fulfilled" ? o.value : { error: o.reason, value: undefined };
+            results.push({ source: names[i], checks: v.value ?? [{ what: "self-test", verdict: "fail", detail: `the probe failed: ${String(v.error?.message ?? v.error)}`, fix: "report this to Sagentix with the line above" }] });
+        }
+    }
+    finally {
+        release();
+        cleanup();
+    }
+    let failed = 0, passed = 0, skipped = 0;
+    out(`collector doctor: ${names.length} source(s); read-only checks, nothing collected or sent`);
+    for (const r of results) {
+        out(r.source);
+        const w = Math.min(44, Math.max(...r.checks.map((c) => c.what.length), 8));
+        for (const c of r.checks) {
+            if (c.verdict === "pass")
+                passed++;
+            else if (c.verdict === "fail")
+                failed++;
+            else
+                skipped++;
+            out(`  ${c.verdict.toUpperCase().padEnd(4)}  ${c.what.padEnd(w)}  ${c.detail}`);
+            if (c.fix && c.verdict !== "pass")
+                out(`        fix: ${c.fix}`);
+        }
+    }
+    out(`doctor: ${passed} passed, ${failed} failed, ${skipped} skipped${failed ? "; fix the lines marked FAIL, then run the doctor again" : "; ready for `collector run`"}`);
+    for (const l of lines)
+        deps.out(scrubText(l, scrub));
+    return failed ? EXIT.error : EXIT.ok;
+}
+export async function run(argv, deps) {
+    // Every line the run writes to stderr also goes into its report (scrubbed there); the --verbose call log and the
+    // closing table go to stderr only (the report already holds every call, and every source's counts and time).
+    const rec = new RunRecorder(deps.now);
+    const rawErr = deps.err;
+    deps = { ...deps, err: rec.tee(deps.err) };
+    const parsed = parseRunArgs(argv, deps);
+    if (typeof parsed === "number")
+        return parsed;
+    let { values } = parsed;
+    const { configPath } = parsed;
     const dry = values["dry-run"] === true;
     const v1Target = typeof values["fedramp-target"] === "string" ? values["fedramp-target"] : undefined;
+    const tuning = runTuning(values);
+    if (typeof tuning === "string") {
+        deps.err(tuning);
+        return EXIT.usage;
+    }
+    const { concurrency } = tuning;
+    const verbose = values.verbose === true || values.debug === true, debug = values.debug === true;
+    // Read when a line is printed, by then holding the vault's values too.
+    let lineSecrets = envSecrets(deps.env);
+    rec.options = {
+        timeoutMs: tuning.timeoutMs,
+        ...(verbose ? {
+            onCall: (c) => rawErr(callLine(c, lineSecrets)),
+            onRetry: (source, e) => rawErr(scrubText(`[${source}] retry ${e.attempt} after ${e.status ? `HTTP ${e.status}` : "no answer"}, waiting ${e.waitMs} ms`, lineSecrets)),
+        } : {}),
+    };
     const names = (values.source ?? []).flatMap((s) => s.split(",")).map((s) => s.trim()).filter(Boolean);
     if (!names.length) {
         deps.err(`--source is required (${deps.sources.map((s) => s.name).join(", ")}).`);
@@ -231,35 +466,10 @@ export async function run(argv, deps) {
     }
     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 holder = deps.vaultKey?.(dir, keyId) ?? keyHolderFor(dir, keyId, { env: deps.env, platform: process.platform, runner });
-            const r = runEnv(dir, holder, deps.env, (name) => settingsOf(creds, name));
-            // Connectors read from the client's own vault (src/refs.ts) take all their names from there, after the local vault.
-            const refs = existsSync(join(dir, VAULT_FILE)) ? new Vault(dir, holder).refs() : {};
-            const f = Object.keys(refs).length ? await applyRefs(dir, refs, creds, r.env, deps.channel ?? deps.fetch) : null;
-            env = f?.env ?? r.env;
-            cleanup = () => { r.cleanup(); f?.cleanup(); };
-            vaultSecrets = [...r.secrets, ...(f?.secrets ?? [])];
-            const used = r.used.length + (f?.used.length ?? 0), warnings = [...r.warnings, ...(f?.warnings ?? [])];
-            if (used)
-                deps.err(`vault: ${used} value(s) from ${VAULT_FILE}${f ? " and your own vault" : ""}`);
-            for (const w of warnings)
-                deps.err(`warning: vault: ${w}`);
-            if (warnings.length)
-                rec.note("vault", warnings);
-        }
-        catch (e) {
-            const w = `the vault could not be opened: ${String(e?.message ?? e)}`;
-            deps.err(w);
-            rec.note("vault", [w]);
-        }
-    }
+    const { env, cleanup, secrets: vaultSecrets } = await vaultEnv({ configPath, keyId, dir, runner, deps, note: (w) => rec.note("vault", w) });
+    lineSecrets = [...new Set([...envSecrets(env), ...vaultSecrets.filter((v) => v.length >= 6)])].sort((a, b) => b.length - a.length);
     let code;
+    let judged = [];
     try {
         code = await collect();
     }
@@ -270,6 +480,19 @@ export async function run(argv, deps) {
     finally {
         cleanup();
     }
+    // The closing table (stderr only), and the refused calls with what to grant.
+    const ran = rec.sources.filter((r) => chosen.some((s) => s.name === r.name));
+    if (ran.length) {
+        rawErr(`\nsummary (${ran.length} source(s), up to ${concurrency} at once):`);
+        for (const l of summaryTable(ran, rec.stats))
+            rawErr(l);
+        const problems = problemLines(judged);
+        if (problems.length) {
+            rawErr("refused calls (their checks were sent as skipped):");
+            for (const l of problems)
+                rawErr(scrubText(l, lineSecrets));
+        }
+    }
     // The report is scrubbed of every value in the run's environment, the vault's included.
     if (connectorTest)
         return code;
@@ -281,14 +504,35 @@ export async function run(argv, deps) {
         const now = deps.now();
         const raw = [];
         const failed = [];
-        for (const s of chosen) {
-            const { value, error, report } = await rec.source(s.name, () => s.run({ opts: values, env, clients: deps.clients, now, warn: deps.err }));
+        // The sources run side by side, at most --concurrency at once, under one fetch wrapper (src/report.ts) that counts each
+        // call against its source. Their outcomes are then taken in the order the sources were named, so the results, and
+        // the bytes signed, are those of a run one source after another (test/e2e.test.ts holds a golden copy).
+        const release = rec.hold();
+        let outcomes;
+        try {
+            outcomes = (await pool(chosen, concurrency, (s) => rec.source(s.name, () => s.run({ opts: values, env, clients: deps.clients, now, warn: deps.err }))))
+                .map((o) => (o.status === "fulfilled" ? o.value : { error: o.reason, report: { name: "?", ms: 0, pass: 0, fail: 0, skipped: 0, error: null, warnings: [] } }));
+        }
+        finally {
+            release();
+        }
+        // The report lists the sources in the order named, not the order they finished.
+        const order = new Map(chosen.map((s, i) => [s.name, i]));
+        const ranked = rec.sources.filter((r) => order.has(r.name)).sort((a, b) => order.get(a.name) - order.get(b.name));
+        let k = 0;
+        for (let i = 0; i < rec.sources.length; i++)
+            if (order.has(rec.sources[i].name))
+                rec.sources[i] = ranked[k++];
+        for (const [i, s] of chosen.entries()) {
+            const { value, error, report } = outcomes[i];
             let got;
             if (error !== undefined || !Array.isArray(value)) {
                 const message = error !== undefined ? String(error?.message ?? error) : "the source returned no list of results";
                 if (!report.error)
                     report.error = { message, stack: "" };
-                deps.err(`error in source ${s.name}: ${message}; its ${s.emits.length} checks are sent as skipped and the run goes on.`);
+                deps.err(`error in source ${s.name}: ${message}; its ${s.emits.length} checks are sent as skipped and the run goes on. To see why: ${doctorHint(s.name)}.`);
+                if (debug && report.error.stack)
+                    rawErr(scrubText(report.error.stack, lineSecrets));
                 failed.push(s.name);
                 got = s.emits.map((check) => ({ check, resource: `the ${s.name} source`, result: "skipped", detail: `collector error in ${s.name}: ${message}` }));
             }
@@ -301,6 +545,7 @@ export async function run(argv, deps) {
                 report[r.result === "pass" ? "pass" : r.result === "fail" ? "fail" : "skipped"]++;
             raw.push(...got);
         }
+        judged = raw;
         // A failed source makes the run exit 1 once everything else is done, as a failed engine run always has.
         const done = (c) => (c === EXIT.ok || c === EXIT.nothing) && failed.length ? EXIT.error : c;
         const vetted = vet(raw, catalog);
@@ -399,6 +644,64 @@ export async function run(argv, deps) {
         return done(EXIT.ok);
     }
 }
+/** `collector policies --config <file>`: push each file of the config's policy folders for sos-app to match (src/policies.ts). */
+export async function policiesCommand(argv, deps) {
+    let config;
+    try {
+        ({ values: { config } } = parseArgs({ args: argv, options: { config: { type: "string" } }, strict: true }));
+    }
+    catch (e) {
+        deps.err(e.message);
+        return EXIT.usage;
+    }
+    if (!config) {
+        deps.err("usage: collector policies --config <collector.config.json>");
+        return EXIT.usage;
+    }
+    const c = loadConfig(config, deps.sources);
+    if ("problems" in c) {
+        deps.err(`${config} is not a valid collector config:\n  ${c.problems.join("\n  ")}`);
+        return EXIT.usage;
+    }
+    const doc = JSON.parse(readFileSync(config, "utf8").replace(/^\uFEFF/, ""));
+    const p = doc.policies;
+    if (!p) {
+        deps.err(`${config} has no "policies" block (dir, keyId, organization): nothing to push.`);
+        return EXIT.nothing;
+    }
+    const base = dirname(config);
+    const dirs = (Array.isArray(p.dir) ? p.dir : [p.dir]).map((d) => (isAbsolute(d) ? d : join(base, d)));
+    const pem = p.keyFile ? readFileSync(isAbsolute(p.keyFile) ? p.keyFile : join(base, p.keyFile), "utf8") : deps.env[DOCUMENTS_KEY_ENV];
+    if (!pem) {
+        deps.err(`No documents key: give policies.keyFile, or set ${DOCUMENTS_KEY_ENV}.`);
+        return EXIT.usage;
+    }
+    let out;
+    try {
+        out = await pushPolicies({ endpoint: doc.endpoint, organization: p.organization, keyId: p.keyId, pem, dirs, fetch: deps.fetch, now: deps.now });
+    }
+    catch (e) {
+        deps.err(`policies: ${e.message}`);
+        return EXIT.error;
+    }
+    for (const r of out)
+        deps.out(`${r.outcome.padEnd(9)} ${r.file}: ${r.detail}`);
+    // Then the approved versions back into <folder>/approved/, so the next edit starts from the text in force (2026-11-05).
+    try {
+        const approved = await pullApproved({ endpoint: doc.endpoint, organization: p.organization, keyId: p.keyId, pem, fetch: deps.fetch, now: deps.now });
+        for (const w of writeApproved(dirs, approved))
+            if (w.outcome !== "present")
+                deps.out(`${(w.outcome === "written" ? "approved" : "missing").padEnd(9)} ${APPROVED_DIR}/${w.file}: ${w.detail}`);
+    }
+    catch (e) {
+        deps.err(`policies: the approved copies were not written: ${e.message}`);
+    }
+    const count = (k) => out.filter((r) => r.outcome === k).length;
+    deps.err(`policies: ${out.length} file(s); ${count("filed")} filed as drafts, ${count("duplicate")} unchanged, ${count("evidence")} as evidence, ${count("unmatched") + count("taken")} not matched, ${count("refused")} refused.`);
+    if (!out.length)
+        return EXIT.nothing;
+    return count("refused") === out.length ? EXIT.refused : EXIT.ok;
+}
 export async function main(argv, deps = defaultDeps()) {
     const [cmd, ...rest] = argv;
     try {
@@ -414,6 +717,10 @@ export async function main(argv, deps = defaultDeps()) {
         }
         if (cmd === "google-login")
             return await googleLogin(rest, deps);
+        if (cmd === "policies")
+            return await policiesCommand(rest, deps);
+        if (cmd === "doctor" || cmd === "selftest")
+            return await doctorCommand(rest, deps);
     }
     catch (e) {
         deps.err(String(e.message ?? e));

package/collector/src/config.js

@@ -28,6 +28,18 @@ 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." },
+        policies: {
+            type: "object",
+            additionalProperties: false,
+            required: ["dir", "keyId", "organization"],
+            description: "Where the organization keeps its policies; `collector policies` pushes each file there for sos-app to match to its control family (2026-11-05).",
+            properties: {
+                dir: { anyOf: [{ type: "string", minLength: 1 }, { type: "array", minItems: 1, items: { type: "string", minLength: 1 } }], description: "A folder (or several) of policy files: PDF, Word or text." },
+                keyId: { type: "string", minLength: 1, maxLength: 100, description: "The id of a 'documents' key registered in sos-app (not the collector key)." },
+                organization: { type: "string", minLength: 1, maxLength: 100, description: "The organization id the documents key belongs to (sos-app shows it with the key)." },
+                keyFile: { type: "string", minLength: 1, description: "Path to that key's Ed25519 private key (PEM). Omit to read SAGENTIX_DOCUMENTS_KEY." },
+            },
+        },
         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.",