@slicedearth/whoisleuth-cli 2.3.0 → 2.4.0

package/cli/terminal-input.mjs

@@ -0,0 +1,168 @@
+import { StringDecoder } from 'node:string_decoder';
+import { CliUsageError, hasUnsafeCliText } from "./errors.mjs";
+export function canReadInteractiveLine(input, output, environment = process.env) {
+    return input?.isTTY === true && output?.isTTY === true
+        && typeof input.setRawMode === 'function' && typeof input.resume === 'function'
+        && typeof input.pause === 'function' && typeof input.on === 'function'
+        && typeof input.off === 'function' && typeof output.write === 'function'
+        && !environment.CI;
+}
+const MAX_INTERACTIVE_ANSWER_SCALARS = 1_024;
+const MAX_INTERACTIVE_ANSWER_BYTES = 4_096;
+function boundedInteractiveAnswer(value) {
+    const supplied = typeof value === 'string' ? value : '';
+    if (Buffer.byteLength(supplied, 'utf8') > MAX_INTERACTIVE_ANSWER_BYTES
+        || Array.from(supplied).length > MAX_INTERACTIVE_ANSWER_SCALARS
+        || hasUnsafeCliText(supplied)) {
+        throw new CliUsageError('Interactive input must be bounded text without control characters.');
+    }
+    return supplied.trim();
+}
+function abortError() {
+    return new DOMException('Aborted', 'AbortError');
+}
+function readBoundedInteractiveLine(prompt, options) {
+    const { input, output, signal } = options;
+    if (signal?.aborted)
+        return Promise.reject(signal.reason || abortError());
+    const previousRaw = input.isRaw === true;
+    const wasPaused = input.isPaused?.() === true;
+    let receivedBytes = 0;
+    let receivedScalars = 0;
+    let settled = false;
+    let characters = [];
+    const decoder = new StringDecoder('utf8');
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            let failure = null;
+            const attempt = (operation) => {
+                try {
+                    operation();
+                }
+                catch (error) {
+                    failure ||= error instanceof Error ? error : new Error('Interactive terminal cleanup failed.');
+                }
+            };
+            attempt(() => input.off?.('data', onData));
+            attempt(() => input.off?.('end', onEnd));
+            attempt(() => signal?.removeEventListener('abort', onAbort));
+            attempt(() => input.setRawMode?.(previousRaw));
+            if (wasPaused)
+                attempt(() => input.pause?.());
+            return failure;
+        };
+        const finish = (value, error) => {
+            if (settled)
+                return;
+            settled = true;
+            const cleanupFailure = cleanup();
+            characters = [];
+            if (error && cleanupFailure) {
+                reject(new AggregateError([error, cleanupFailure], `${error.message}; terminal cleanup also failed: ${cleanupFailure.message}`));
+            }
+            else if (error || cleanupFailure)
+                reject(error || cleanupFailure);
+            else
+                resolve(value || '');
+        };
+        const rejectUsage = () => finish(undefined, new CliUsageError('Interactive input must be bounded text without control characters.'));
+        const onData = (chunk) => {
+            if (settled)
+                return;
+            let rawChunk;
+            if (Buffer.isBuffer(chunk)) {
+                if (chunk.length > MAX_INTERACTIVE_ANSWER_BYTES - receivedBytes) {
+                    rejectUsage();
+                    return;
+                }
+                rawChunk = chunk;
+            }
+            else {
+                const supplied = String(chunk ?? '');
+                if (supplied.length > MAX_INTERACTIVE_ANSWER_BYTES - receivedBytes
+                    || Buffer.byteLength(supplied, 'utf8') > MAX_INTERACTIVE_ANSWER_BYTES - receivedBytes) {
+                    rejectUsage();
+                    return;
+                }
+                rawChunk = Buffer.from(supplied, 'utf8');
+            }
+            receivedBytes += rawChunk.length;
+            const value = decoder.write(rawChunk);
+            receivedScalars += Array.from(value).length;
+            if (receivedBytes > MAX_INTERACTIVE_ANSWER_BYTES
+                || receivedScalars > MAX_INTERACTIVE_ANSWER_SCALARS
+                || value.includes('\ufffd')) {
+                rejectUsage();
+                return;
+            }
+            for (const character of value) {
+                if (character === '\r' || character === '\n') {
+                    try {
+                        output.write('\n');
+                    }
+                    catch (error) {
+                        finish(undefined, error instanceof Error ? error : new Error('Interactive terminal output failed.'));
+                        return;
+                    }
+                    finish(characters.join(''));
+                    return;
+                }
+                if (character === '\u0003' || character === '\u0004' || character === '\u001b') {
+                    finish(undefined, abortError());
+                    return;
+                }
+                if (character === '\u0008' || character === '\u007f') {
+                    if (characters.length) {
+                        characters.pop();
+                        try {
+                            output.write('\b \b');
+                        }
+                        catch (error) {
+                            finish(undefined, error instanceof Error ? error : new Error('Interactive terminal output failed.'));
+                            return;
+                        }
+                    }
+                    continue;
+                }
+                if (hasUnsafeCliText(character)) {
+                    rejectUsage();
+                    return;
+                }
+                characters.push(character);
+                try {
+                    output.write(character);
+                }
+                catch (error) {
+                    finish(undefined, error instanceof Error ? error : new Error('Interactive terminal output failed.'));
+                    return;
+                }
+            }
+        };
+        const onEnd = () => {
+            const remainder = decoder.end();
+            if (remainder)
+                rejectUsage();
+            else
+                finish(undefined, abortError());
+        };
+        const onAbort = () => finish(undefined, signal?.reason instanceof Error ? signal.reason : abortError());
+        try {
+            output.write(prompt);
+            input.on?.('data', onData);
+            input.on?.('end', onEnd);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            input.setRawMode?.(true);
+            if (settled)
+                return;
+            input.resume?.();
+        }
+        catch (error) {
+            finish(undefined, error instanceof Error ? error : new Error('Interactive terminal input failed.'));
+        }
+    });
+}
+export { MAX_INTERACTIVE_ANSWER_BYTES, MAX_INTERACTIVE_ANSWER_SCALARS, boundedInteractiveAnswer, readBoundedInteractiveLine };

package/cli/workflow-command-runner.mjs

@@ -1,15 +1,39 @@
 import { formatCliJunit } from "./ci-report.mjs";
 import { formatDomainControlMonitor, runDomainControlMonitor } from "./domain-control-monitor.mjs";
-import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
+import { boundedCliErrorMessage, createCliDiagnosticOutput, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { evaluateCliFailPolicies, formatFailPolicyNotice } from "./fail-policy.mjs";
 import { formatJsonDocument } from "./formatters/json.mjs";
 import { buildInvestigationPlan, buildWorkflowRecipeCatalogue, formatInvestigationPlan, formatWorkflowRecipeCatalogue, } from "./investigation-plan.mjs";
-import { MAX_INVESTIGATION_RUN_BYTES, formatInvestigationRun, runInvestigationRecipe, } from "./investigation-run.mjs";
+import { MAX_INVESTIGATION_RUN_BYTES, formatInvestigationRun, investigationRunExitCode, runInvestigationRecipe, } from "./investigation-run.mjs";
 import { MAX_OFFLINE_EVIDENCE_INPUT_BYTES } from "./offline-evidence-review.mjs";
+import { MAX_OFFLINE_ARTIFACT_BYTES } from "./artifact-verify.mjs";
+import { MAX_RETAINED_ARTIFACT_DIFF_BYTES } from "./retained-artifact-diff.mjs";
+import { MAX_SAVED_LOOKUP_INPUT_BYTES } from "./saved-lookup.mjs";
+import { MAX_COMPARE_INPUT_BYTES } from "./compare.mjs";
+import { MAX_SOURCE_RELIABILITY_INPUT_BYTES } from "./source-reliability.mjs";
+import { MAX_SHARING_REVIEW_BYTES } from "./sharing-review.mjs";
 import { createBufferedOutput } from "./output-file.mjs";
+import { boundedInteractiveAnswer, canReadInteractiveLine, readBoundedInteractiveLine } from "./terminal-input.mjs";
 import { WORKFLOW_INLINE_COMMANDS } from "./inline-command-families.mjs";
 import { runDiscriminatedCommandHandler } from "./discriminated-command-handlers.mjs";
+function boundWorkflowInputs(command, inputs, dependencies, context) {
+    if (!inputs.size)
+        return {};
+    const read = (source, fallback, maximumBytes, label) => typeof source === 'string' && inputs.has(source)
+        ? inputs.get(source)
+        : fallback ? fallback(source) : context.readInput(source, maximumBytes, label);
+    switch (command) {
+        case 'export': return { readExportInput: (source) => read(source, dependencies.readExportInput, MAX_SAVED_LOOKUP_INPUT_BYTES, 'Evidence export input') };
+        case 'verify-artifact': return { readArtifactInput: (source) => read(source, dependencies.readArtifactInput, MAX_OFFLINE_ARTIFACT_BYTES, 'Artefact input') };
+        case 'sharing-review': return { readArtifactInput: (source) => read(source, dependencies.readArtifactInput, MAX_SHARING_REVIEW_BYTES, 'Sharing review input') };
+        case 'compare': return { readCompareInput: (source) => read(source, dependencies.readCompareInput, MAX_COMPARE_INPUT_BYTES, 'Comparison input') };
+        case 'source-report': return { readSourceReliabilityInput: (source) => read(source, dependencies.readSourceReliabilityInput, MAX_SOURCE_RELIABILITY_INPUT_BYTES, 'Source reliability input') };
+        case 'diff':
+        case 'timeline': return { readDiffInput: (source) => read(source, dependencies.readDiffInput, command === 'diff' ? MAX_RETAINED_ARTIFACT_DIFF_BYTES : MAX_SAVED_LOOKUP_INPUT_BYTES, command === 'diff' ? 'Retained diff input' : 'Lookup timeline input') };
+        default: throw new CliUsageError('This fixed-workflow command does not accept retained artefacts.');
+    }
+}
 async function runMonitorOnceCommand(args, dependencies, context) {
     context.setFailureLabel('One-shot domain control review');
     let manifestInput;
@@ -82,12 +106,18 @@ async function runWorkflowPlanCommand(args, dependencies, context) {
 }
 async function runWorkflowRecipeCommand(args, dependencies, context) {
     context.setFailureLabel('Investigation workflow');
+    const input = (dependencies.stdin ?? process.stdin);
+    if (args.interactive && !canReadInteractiveLine(input, context.stderr, dependencies.environment)) {
+        throw new CliUsageError('--interactive requires terminal input and terminal stderr. Use --select for unattended workflows.');
+    }
     let resumeInput = null;
     if (args.resumeSource) {
         try {
-            resumeInput = dependencies.readDiffInput
-                ? await dependencies.readDiffInput(args.resumeSource)
-                : await context.readInput(args.resumeSource, MAX_INVESTIGATION_RUN_BYTES, 'Investigation resume state');
+            resumeInput = dependencies.workflowResumeInput !== undefined
+                ? dependencies.workflowResumeInput
+                : dependencies.readDiffInput
+                    ? await dependencies.readDiffInput(args.resumeSource)
+                    : await context.readInput(args.resumeSource, MAX_INVESTIGATION_RUN_BYTES, 'Investigation resume state');
         }
         catch (error) {
             if (error instanceof CliUsageError)
@@ -98,17 +128,42 @@ async function runWorkflowRecipeCommand(args, dependencies, context) {
     const document = await runInvestigationRecipe(args.recipe, args.subject, {
         approveNetwork: args.approveNetwork,
         selections: args.selections,
+        artifactBindings: args.artifactBindings,
+        confirmedReviews: args.confirmedReviews,
+        ...(args.interactive ? { selectInputs: async (request) => {
+                context.writeStderr(`${request.label}\nEnter literal input paths or values. Leave blank to pause; no approval is implied.\n`);
+                const answers = [];
+                for (const placeholder of request.inputs) {
+                    const prompt = `${request.stepId} ${placeholder}: `;
+                    const answer = boundedInteractiveAnswer(await (dependencies.workflowQuestion
+                        ? dependencies.workflowQuestion(prompt)
+                        : readBoundedInteractiveLine(prompt, { input: input, output: context.stderr,
+                            ...(dependencies.signal ? { signal: dependencies.signal } : {}) })));
+                    if (!answer)
+                        break;
+                    answers.push(answer);
+                }
+                return answers;
+            } } : {}),
         resumeInput,
         generatedAt: context.now(),
         ...(dependencies.signal ? { signal: dependencies.signal } : {}),
-        execute: async (command, stepArguments) => {
+        execute: async (command, stepArguments, inputs) => {
             const stepStdout = createBufferedOutput();
-            const stepStderr = createBufferedOutput();
-            const exitCode = await context.executeCli([command, ...stepArguments], {
-                stdout: stepStdout.stream,
-                stderr: stepStderr.stream,
-            });
-            return { exitCode, stdout: stepStdout.value() };
+            const stepStderr = createCliDiagnosticOutput();
+            try {
+                const exitCode = await context.executeCli([command, ...stepArguments], {
+                    stdout: stepStdout.stream,
+                    stderr: stepStderr.stream,
+                    ...boundWorkflowInputs(command, inputs, dependencies, context),
+                });
+                return { exitCode, stdout: stepStdout.value() };
+            }
+            finally {
+                const diagnostic = stepStderr.value();
+                if (diagnostic)
+                    context.writeStderr(`${command}: ${diagnostic}\n`);
+            }
         },
     });
     if (!args.quiet) {
@@ -116,7 +171,7 @@ async function runWorkflowRecipeCommand(args, dependencies, context) {
             ? formatJsonDocument(document)
             : context.terminal(formatInvestigationRun(document), args.color));
     }
-    return document.state === 'step_failed' ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+    return investigationRunExitCode(document);
 }
 const WORKFLOW_COMMAND_HANDLERS = Object.freeze({
     'monitor-once': runMonitorOnceCommand,

package/docs/cli-reference.md

@@ -12,20 +12,8 @@ contains the exhaustive recipient, retention and export metadata.
 
 ## Installation
 
-Public releases require Node.js 24 or later. Release verification uses the
-exact Node.js 24 maintainer runtime and separately exercises the installed
-package on Node.js 26:
-
-```bash
-npm exec --yes --ignore-scripts --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
-npm install --global --ignore-scripts @slicedearth/whoisleuth-cli
-whoisleuth doctor
-```
-
-The scoped package and application share one semantic version. The package
-requires no dependency lifecycle scripts and does not call the hosted
-WHOISleuth deployment. From a repository checkout, replace `whoisleuth` with
-`node bin/whoisleuth.mts`.
+Use the [installation guide](cli.md#installation) for runtime requirements,
+installation and updates. The CLI runs locally without a hosted account.
 
 ## Find and inspect commands
 
@@ -46,6 +34,13 @@ command position as Lookup shorthand. Use explicit `lookup` where input needs
 supported URL-like normalisation. Credentials, paths, queries, fragments, ports
 and unsupported special-use targets are rejected by the shorthand.
 
+Explicit `lookup` normally uses only a pasted URL's hostname. Add
+`--deep --exact-url` to collect that page's path and query instead of the
+homepage; fragments are not sent. `--plan` discloses this scope without making
+requests or copying the URL into the plan. Use stdin to keep a sensitive URL
+out of shell history. Saved request provenance omits queries, but paths and
+page-derived text still require review before sharing.
+
 `registry-scaffold` has a separate fixture contract: its `--profile` selects one
 fixed fixture profile and shared `--config` profiles are rejected. It produces
 sanitised local fixture material and makes no registry request.
@@ -63,12 +58,8 @@ disclosures without collecting. Fast is the Lookup default. Deep adds the
 applicable registration, DNS, HTTP, TLS, page, technology and network context.
 Optional browser providers are not implicit CLI actions.
 
-`mail-headers` is an offline review of one analyst-selected RFC-style header
-block. It reports domain-only identity, header-reported authentication,
-exact-domain alignment, and bounded `Received` routing. It retains no address
-local parts, display names, subject, body, attachment, or raw header value in
-its output. It does not independently validate SPF, DKIM, DMARC, or ARC and
-does not treat divergence as proof of abuse.
+The [message-header review](cli.md#message-header-review) is offline and reports
+publisher claims, not independent DNS or cryptographic validation.
 
 `dnssec-validate` and `mail-transport` are isolated authorised actions. Both
 require a selected literal public resolver, a local trust-anchor document and
@@ -77,6 +68,8 @@ transport handles at most three selected MX hosts sequentially, sends `EHLO`
 and uses `STARTTLS` only when advertised. It does not send mail, authenticate,
 test relay, enumerate recipients or retry automatically. DNSSEC, TLSA/DANE,
 PKIX, STARTTLS and SMTP transport remain separate evidence states.
+STARTTLS detection uses the full bounded reply. If the retained capability
+inventory is shortened, the report remains partial and names the omission.
 
 The repository-only rendered-capture package is outside hosted and distributable
 collection. It executes remote page JavaScript only for an explicitly
@@ -91,11 +84,20 @@ refused. Output goes to the terminal unless a command supports `--output`.
 Private output is written atomically and an existing path is refused unless
 replacement is explicit.
 
+`--` ends option processing. All later arguments are literal positional inputs,
+including names such as `--help`. Use `./-evidence.json` for a hyphen-prefixed
+filename when completing paths across shells. Options must precede `--`.
+
 Terminal text is the default. JSON, JSONL, CSV, Markdown, HTML and domain-only
 formats are available only where the installed command declares them.
 Redirected and machine output contains no ANSI or progress text. Diagnostics
 and optional target-free `--events` output use standard error.
 
+For `bulk` and `discover-scan`, `--csv-with-metadata` adds the source schema and
+version, observation and report times, collection origin, scan mode, diagnostic
+version and source-health states. Missing clocks remain `unknown`; a null
+source state is unmeasured, not a negative result. `--csv` keeps the compact columns.
+
 `--fail-on` and `--strict-exit` expose selected evidence states to automation
 without changing the result document. Review focused help for the policies a
 command supports.
@@ -116,16 +118,18 @@ Readers accept only their declared public and current versions. Unknown,
 unreleased historical and future schemas fail before partial interpretation;
 an invalid import is not treated as an empty document.
 
-`inspect-archive` reads current workspace archive v8 and exact versions 5, 6 and 7. It
+`inspect-archive` reads current workspace archive v9 and exact versions 5–8. It
 reports section metadata and digest-only search results unless `--reveal` is
 explicitly selected. It never searches notes, contacts or arbitrary raw fields.
 
 `export` reads supported saved Lookup v1 or v2 and writes current Lookup
-evidence schema 28. Published v2 schema 27 and exact v1 schema 26 remain
-readable. Versions 27 and 28 exclude raw registration payloads, expanded
+evidence schema 29. Published v2 schemas 27 and 28 and exact v1 schema 26 remain
+readable. Versions 27–29 exclude raw registration payloads, expanded
 contacts, credentials, complete query-bearing URLs and provider payloads;
-schema 28 can also retain the bounded, separately attributed registrar-standing
-projection shown by Lookup.
+schemas 28 and 29 also retain the bounded registrar-standing projection.
+Schema 29 identifies the hostname used for DNS, TLS and web observations,
+separately from the registrable domain used by registration sources. Older
+evidence retains its original collection scope.
 
 `verify-artifact` checks a recognised structure and its applicable integrity
 contract. `interchange-report` describes retained and omitted fields.
@@ -133,6 +137,45 @@ contract. `interchange-report` describes retained and omitted fields.
 validity and signer trust separate. None of these checks establishes that
 evidence is accurate, current, safe to share or attributable to a person.
 
+### Signer trust
+
+Use `verify-signature package.json --trust-store-file trust.json --json` to
+check an explicitly selected fingerprint policy offline. The result contains
+the ordinary signature verification and a separate current trust decision.
+Only a matching `trusted` entry succeeds; unknown, `retired`, `revoked` or
+future-reviewed entries return exit code 4, including with `--quiet`.
+Malformed files return 2. Without this option, the existing verification
+output is unchanged. A supplied `--public-key-file` must also match.
+
+The trust file contains no keys. For example:
+
+```json
+{
+  "schema": "whoisleuth.evidence-signer-trust-store",
+  "version": 1,
+  "entries": [{
+    "keyIdSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "label": "Evidence reviewer",
+    "status": "trusted",
+    "updatedAt": "2026-09-01T00:00:00.000Z",
+    "note": "Fingerprint confirmed through the established contact channel."
+  }]
+}
+```
+
+Replace the example fingerprint with the SHA-256 fingerprint of the signer's
+SPKI DER public-key bytes, confirmed through an authenticated channel—not
+merely copied from the package being checked. Review rotation and revocation
+updates through that channel. On rotation, mark the old entry `retired` and
+optionally record `successorKeyIdSha256`; independently confirm and add the
+replacement entry. Use `revoked` for a withdrawn trust decision. Neither a
+successor link nor a claimed signing date overrides current status.
+
+Files support 1,024 distinct entries within 4 MiB. Labels and single-line notes
+allow 160 and 2,048 characters respectively. Reports include only the matching
+entry and the exact file digest. Keep the file and any saved reports under your
+own retention policy. No automatic key discovery, key storage or trust refresh occurs.
+
 ## Command-family boundaries
 
 - Evidence collection commands retain separate source states. A failed or
@@ -144,17 +187,20 @@ evidence is accurate, current, safe to share or attributable to a person.
 - Bulk applies one declared collection contract per target. Fast accepts up to
   500 targets and Deep up to 50; each target remains a separate request.
 - Respond commands package browser-created Cases and prepare local packets,
-  reports and sharing reviews. They do not create durable Cases, submit,
-  publish, notify or grant recipient authorisation.
+  reports and sharing reviews. The offline [`case` workflow](cli.md#local-case-files)
+  also creates and updates ordinary local Case files through explicit, conflict-checked
+  output. Neither workflow submits, publishes, notifies or grants recipient authorisation.
 - Assurance, comparison and calibration commands describe supplied or retained
   evidence. They do not tune the running model, change infrastructure or turn an
   analyst label into observed truth.
 - `workflow-plan` lists fixed installed recipes without executing them.
   `workflow-run` executes only installed steps, requires approval for network
   work and pauses at unresolved analyst selections. Repeat
-  `--select <step-id>=<path-or-value>` in placeholder order to resume a selected
-  step; version-1 checkpoints remain readable and version 2 retains the exact
-  selections in the local checkpoint.
+  `--select <step-id>=<path-or-value>` for remaining placeholders in order, or bind
+  a compatible earlier output with `--use-artifact <step-id>:<input-number>=<earlier-step-id>`.
+  Checkpoints retain exact selections and bindings and distinguish incomplete
+  collection from retryable failures; see [resuming a fixed workflow](cli.md#resuming-a-fixed-workflow)
+  for the supported versions and resume behaviour.
 
 Use the installed focused help for positional inputs, exact ceilings, options,
 network effects, outputs and command-specific exit behaviour.