@slicedearth/whoisleuth-cli 1.32.2 → 1.36.1

package/cli/runner.mjs

@@ -2,12 +2,13 @@ import { Buffer } from 'node:buffer';
 import { createReadStream } from 'node:fs';
 import { createRequire } from 'node:module';
 import { abortable } from "../lib/abort.mjs";
-import { resolvePublicAddresses } from "../lib/safe-fetch.mjs";
+import { resolvePublicAddresses, safeFetch } from "../lib/safe-fetch.mjs";
 import { whoisQuery } from "../lib/whois-transport.mjs";
 import { REGISTRY_CAPABILITIES_VERSION, registryCapabilityFor } from "../lib/registry-capabilities.mjs";
 import { explainRiskScore, RISK_MODEL_VERSION, RISK_REVIEW_THRESHOLD } from "../lib/risk-scoring.mjs";
 import { CLI_COMMANDS, parseCliArguments } from "./arguments.mjs";
 import { runBulkCommand } from "./bulk-command-runner.mjs";
+import { buildCliCommandCatalogue, formatCliCommandCatalogue } from "./command-catalogue.mjs";
 import { buildShellCompletion } from "./completion.mjs";
 import { buildDoctorReport, formatDoctorReport } from "./doctor.mjs";
 import { MAX_COMPARE_INPUT_BYTES, compareLookupDocument, parseCliLookupDocument, readCompareInputBounded, } from "./compare.mjs";
@@ -22,10 +23,15 @@ import { buildCliCompareDocument, formatJsonDocument, } from "./formatters/json.
 import { formatLookupEvidenceMarkdown } from "./formatters/markdown.mjs";
 import { formatTerminalCompare, formatTerminalRegistrySupport, formatTerminalRiskCalibration, } from "./formatters/terminal.mjs";
 import { buildCliLookupDiff, formatCliLookupDiff } from "./lookup-diff.mjs";
+import { MAX_LOOKUP_TIMELINE_INPUT_BYTES, buildCliLookupTimeline, formatCliLookupTimeline, } from "./lookup-timeline.mjs";
 import { buildCliPageComparison, formatCliPageComparison } from "./page-compare.mjs";
 import { MAX_MAIL_REVIEW_INPUT_BYTES, buildCliMailReview, formatCliMailReview, } from "./mail-review.mjs";
+import { MAX_OFFLINE_EVIDENCE_INPUT_BYTES, buildOfflineEvidenceReview, formatOfflineEvidenceReview, } from "./offline-evidence-review.mjs";
+import { DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA, DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, buildDomainControlManifest, formatDomainControlResult, reviewDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
 import { runLookupCommand } from "./lookup-command-runner.mjs";
 import { buildCliManual } from "./manual.mjs";
+import { buildInvestigationPlan, formatInvestigationPlan } from "./investigation-plan.mjs";
+import { WHOISLEUTH_SOURCE_REPOSITORY_URL } from "../lib/project-metadata.mjs";
 import { createBufferedOutput, writePrivateFile } from "./output-file.mjs";
 import { createTerminalProgress } from "./progress.mjs";
 import { buildRegistrySupportDocument } from "./registry-support.mjs";
@@ -64,10 +70,14 @@ Review saved evidence:
   compare            Compare saved registry publications.
   page-compare       Compare saved static page and TLS evidence.
   mail-review        Review saved passive mail exposure evidence.
+  review-evidence    Review supplied DNS, routing, GeoIP, or RDAP evidence offline.
+  domain-control     Build or review an integrity-protected desired-state manifest.
+  workflow-plan      Plan a fixed investigation recipe without executing it.
   diff               Compare two saved domain observations.
+  timeline           Compare a sequence of observations for one domain.
   export             Convert a saved lookup into an evidence report.
   inspect-archive    Inspect a workspace archive, redacted by default.
-  verify-artifact    Validate an archive, packet, or manifest offline.
+  verify-artifact    Validate saved evidence or an integrity envelope offline.
 
 Integrity and calibration:
   sign-artifact      Sign one reviewed packet or manifest locally.
@@ -76,7 +86,8 @@ Integrity and calibration:
 
 Terminal:
   doctor             Check the local runtime; network tests require --network.
-  completion         Print a completion script for bash, zsh, or fish.
+  commands           List command contracts for people or local tooling.
+  completion         Print completion for bash, zsh, fish, or PowerShell.
   manual             Print the generated manual page.
 
 Run "whoisleuth <command> --help" for focused usage and an example.
@@ -86,14 +97,15 @@ Diagnostics are written to stderr. Fast lookup is the default; deep collection
 must be requested explicitly and can disclose a target to additional sources.
 
 Copyright 2026 slicedearth. Licensed under AGPL-3.0-only.
-Source and licence: https://github.com/slicedearth/whoisleuth
+Source and licence: ${WHOISLEUTH_SOURCE_REPOSITORY_URL}
 `;
 const COMMAND_USAGE = Object.freeze({
-    completion: 'whoisleuth completion <bash|zsh|fish>',
+    completion: 'whoisleuth completion <bash|zsh|fish|powershell>',
     doctor: 'whoisleuth doctor [--network] [--json] [--quiet] [--no-color]',
+    commands: 'whoisleuth commands [--json] [--quiet] [--no-color]',
     manual: 'whoisleuth manual',
-    lookup: 'whoisleuth lookup <domain|IP|ASN> [--json|--markdown|--html] [--fast|--deep] [--summary|--verbose] [--strict-exit] [--events] [--quiet] [--no-color]',
-    bulk: 'whoisleuth bulk [file] [--json|--jsonl|--csv|--domains] [--registered-only|--inconclusive-only] [--fast|--deep] [--concurrency <1-8>] [--checkpoint <file> [--resume]] [--events]',
+    lookup: 'whoisleuth lookup <domain|IP|ASN> [--json|--markdown|--html] [--fast|--deep] [--plan] [--summary|--verbose] [--strict-exit] [--events] [--quiet] [--no-color]',
+    bulk: 'whoisleuth bulk [file] [--json|--jsonl|--csv|--domains|--queries] [--registered-only|--inconclusive-only|--errors-only] [--fast|--deep] [--concurrency <1-8>] [--checkpoint <file> [--resume]] [--events]',
     'ct-search': 'whoisleuth ct-search <keyword> [--json] [--quiet] [--no-color]',
     discover: 'whoisleuth discover <brand|domain> [--tlds <list>] [--preset <name>|--families <ids>] [--keyboard <layout>] [--dictionary <file>] [--snapshot <file>] [--json|--jsonl|--domains]',
     'discover-scan': 'whoisleuth discover-scan <brand|domain> [--fast|--deep] [--scan-limit <n>] [--chunk-size <n>] [--concurrency <n>] [--resolver <IPs>] [--allowlist <file>] [--checkpoint <file> [--resume]] [--observation-snapshot <file>] [--json|--jsonl|--csv|--domains]',
@@ -110,7 +122,11 @@ const COMMAND_USAGE = Object.freeze({
     compare: 'whoisleuth compare [lookup.json] [--json] [--quiet] [--no-color]',
     'page-compare': 'whoisleuth page-compare <left.json> <right.json> [--json] [--quiet] [--no-color]',
     'mail-review': 'whoisleuth mail-review [bulk.json|bulk.jsonl] [--json] [--quiet] [--no-color]',
+    'review-evidence': 'whoisleuth review-evidence [evidence.json] [--json] [--quiet] [--no-color]',
+    'domain-control': 'whoisleuth domain-control [manifest-input.json|review-input.json] [--json] [--quiet] [--no-color]',
+    'workflow-plan': 'whoisleuth workflow-plan <recipe> <domain|brand> [--json] [--quiet] [--no-color]',
     diff: 'whoisleuth diff <left.json> <right.json> [--json] [--quiet] [--no-color]',
+    timeline: 'whoisleuth timeline <observation.json> <observation.json> [...] [--json] [--quiet] [--no-color]',
     export: 'whoisleuth export [lookup.json] [--markdown|--html|--compact]',
 });
 const COMMAND_DETAILS = Object.freeze({
@@ -124,6 +140,11 @@ const COMMAND_DETAILS = Object.freeze({
         example: 'whoisleuth doctor --json',
         boundary: 'The default check is offline. Public DNS and port 43 checks run only when --network is explicitly supplied.',
     },
+    commands: {
+        description: 'List the installed command contracts in terminal or versioned JSON form.',
+        example: 'whoisleuth commands --json',
+        boundary: 'Catalogue generation is offline. It reports declared command modes and limits without executing collection or inspecting local evidence.',
+    },
     manual: {
         description: 'Print a generated roff manual page for local installation.',
         example: 'whoisleuth manual | man -l -',
@@ -180,7 +201,7 @@ const COMMAND_DETAILS = Object.freeze({
         boundary: 'Calibration is offline and diagnostic. It never trains, tunes, or changes the scoring model automatically.',
     },
     'verify-artifact': {
-        description: 'Validate a supported archive, packet, or manifest without printing evidence contents.',
+        description: 'Validate a supported archive, packet, manifest, or saved Lookup without printing evidence contents.',
         example: 'whoisleuth verify-artifact workspace.json --json',
         boundary: 'Verification is offline and redacted. Encrypted archives require an explicitly supplied passphrase file.',
     },
@@ -219,20 +240,71 @@ const COMMAND_DETAILS = Object.freeze({
         example: 'whoisleuth mail-review candidates.json --json',
         boundary: 'Review is offline and sends no SMTP traffic. Missing or partial DNS evidence remains inconclusive.',
     },
+    'review-evidence': {
+        description: 'Review one versioned DNSSEC, TLSA, RPKI, GeoIP, encrypted-DNS, or RDAP planning document offline.',
+        example: 'whoisleuth review-evidence dnssec-evidence.json --json',
+        boundary: 'The command reads only the supplied document. It performs no DNS, RDAP, BGP, GeoIP-provider, TLS, HTTP, or SMTP request.',
+    },
+    'domain-control': {
+        description: 'Build an integrity-protected desired-state manifest or compare one with supplied observations.',
+        example: 'whoisleuth domain-control domain-control-input.json --json',
+        boundary: 'The command is offline and changes no registrar, DNS, mail, or certificate configuration. Only complete supplied observations can produce drift.',
+    },
+    'workflow-plan': {
+        description: 'Build a fixed domain-investigation plan from existing bounded CLI commands.',
+        example: 'whoisleuth workflow-plan domain-triage example.test --json',
+        boundary: 'Planning is offline and plan-only. It does not execute commands, expand placeholders, read files, make requests, or submit evidence.',
+    },
     diff: {
         description: 'Compare bounded evidence retained in two saved domain lookups.',
         example: 'whoisleuth diff first.json second.json --json',
         boundary: 'Comparison is offline. Missing, unavailable, equal, and different evidence remain separate states.',
     },
+    timeline: {
+        description: 'Build an ordered same-domain history from saved Lookup observations.',
+        example: 'whoisleuth timeline first.json second.json latest.json --json',
+        boundary: 'The command is offline, accepts 2 to 20 bounded inputs for one domain, retains no filenames or raw registry payloads, and does not treat changed collection conditions as a domain change.',
+    },
     export: {
         description: 'Convert one saved lookup into a versioned evidence report.',
         example: 'whoisleuth export lookup.json --markdown',
         boundary: 'Exports preserve source attribution and limitations. Compact output intentionally omits raw registry payloads.',
     },
 });
+const COMMAND_COLLECTION = Object.freeze({
+    completion: { mode: 'offline', scope: 'Prints one static script and changes no shell configuration.' },
+    doctor: { mode: 'network', scope: 'Network access is opt-in with --network and is limited to fixed public DNS, HTTPS, and WHOIS diagnostics.' },
+    commands: { mode: 'offline', scope: 'Reads the embedded command catalogue and performs no collection.' },
+    manual: { mode: 'offline', scope: 'Builds documentation from the embedded command catalogue.' },
+    lookup: { mode: 'network', scope: 'Accepts one target. Fast is the default; deep collection must be selected explicitly.' },
+    bulk: { mode: 'network', scope: 'Accepts at most 500 fast or 50 deep targets, with concurrency capped at 8 fast or 3 deep.' },
+    'ct-search': { mode: 'network', scope: 'Accepts one bounded search keyword and queries the fixed certificate-transparency source.' },
+    discover: { mode: 'offline', scope: 'Generates a bounded candidate set from local rules, dictionaries, and optional saved snapshots.' },
+    'discover-scan': { mode: 'network', scope: 'Scans at most 500 fast or 50 deep candidates, with concurrency capped at 8 fast or 3 deep.' },
+    posture: { mode: 'network', scope: 'Accepts one domain and performs bounded DNS queries only.' },
+    http: { mode: 'network', scope: 'Accepts one domain and follows only the bounded SSRF-guarded homepage redirect workflow.' },
+    tls: { mode: 'network', scope: 'Accepts one public hostname and opens one bounded certificate connection.' },
+    'registry-support': { mode: 'offline', scope: 'Reads the embedded registry capability catalogue for one domain or suffix.' },
+    'risk-calibrate': { mode: 'offline', scope: 'Reads one bounded reviewed-label dataset and changes no model or evidence.' },
+    'verify-artifact': { mode: 'offline', scope: 'Reads one selected bounded archive, packet, manifest, or saved Lookup document.' },
+    'inspect-archive': { mode: 'offline', scope: 'Reads one selected bounded workspace archive with redacted output by default.' },
+    'sign-artifact': { mode: 'offline', scope: 'Reads one selected artifact and one local private key without transmitting either.' },
+    'verify-signature': { mode: 'offline', scope: 'Reads one selected signed package and optional local public key.' },
+    'source-report': { mode: 'offline', scope: 'Reads bounded saved evidence and emits target-free source reliability data.' },
+    compare: { mode: 'offline', scope: 'Reads one saved Lookup and compares its separately attributed registry publications.' },
+    'page-compare': { mode: 'offline', scope: 'Reads two saved Lookup documents and executes no page code.' },
+    'mail-review': { mode: 'offline', scope: 'Reads one saved Bulk result and sends no DNS or SMTP traffic.' },
+    'review-evidence': { mode: 'offline', scope: 'Reads one bounded versioned evidence or request-planning document and performs no collection.' },
+    'domain-control': { mode: 'offline', scope: 'Reads one bounded desired-state or review document and performs no collection or configuration change.' },
+    'workflow-plan': { mode: 'offline', scope: 'Builds a fixed typed recipe and executes none of its network or file steps.' },
+    diff: { mode: 'offline', scope: 'Reads two saved Lookup documents for different domains.' },
+    timeline: { mode: 'offline', scope: 'Reads 2 to 20 saved observations for one domain, capped at 32 MiB in total.' },
+    export: { mode: 'offline', scope: 'Reads one saved Lookup and writes one bounded report.' },
+});
 function commandHelp(command) {
     const detail = COMMAND_DETAILS[command];
-    return `WHOISleuth ${command}\n${detail.description}\n\nUsage:\n  ${COMMAND_USAGE[command]}\n\nExample:\n  ${detail.example}\n\nBoundary:\n  ${detail.boundary}\n\nRun "whoisleuth --help" to see the grouped command list.\n`;
+    const collection = COMMAND_COLLECTION[command];
+    return `WHOISleuth ${command}\n${detail.description}\n\nUsage:\n  ${COMMAND_USAGE[command]}\n\nExample:\n  ${detail.example}\n\nCollection:\n  ${collection.mode === 'offline' ? 'Offline' : 'Network'}: ${collection.scope}\n\nBoundary:\n  ${detail.boundary}\n\nRun "whoisleuth --help" to see the grouped command list.\n`;
 }
 async function readStdinBounded(stream, limit = MAX_STDIN_BYTES) {
     if (!stream || stream.isTTY)
@@ -341,8 +413,28 @@ async function runParsedCli(args, dependencies = {}) {
             write(stdout, buildShellCompletion(args.shell));
             return EXIT_CODES.SUCCESS;
         }
+        if (args.action === 'commands') {
+            const catalogue = buildCliCommandCatalogue({
+                commands: CLI_COMMANDS,
+                collections: COMMAND_COLLECTION,
+                details: COMMAND_DETAILS,
+                usage: COMMAND_USAGE,
+                packageVersion: VERSION,
+            });
+            if (!args.quiet)
+                write(stdout, args.output === 'json'
+                    ? formatJsonDocument(catalogue)
+                    : terminal(formatCliCommandCatalogue(catalogue), args.color));
+            return EXIT_CODES.SUCCESS;
+        }
         if (args.action === 'manual') {
-            write(stdout, buildCliManual({ commands: CLI_COMMANDS, details: COMMAND_DETAILS, usage: COMMAND_USAGE, version: VERSION }));
+            write(stdout, buildCliManual({
+                commands: CLI_COMMANDS,
+                collections: COMMAND_COLLECTION,
+                details: COMMAND_DETAILS,
+                usage: COMMAND_USAGE,
+                version: VERSION,
+            }));
             return EXIT_CODES.SUCCESS;
         }
         if (args.action === 'doctor') {
@@ -353,10 +445,11 @@ async function runParsedCli(args, dependencies = {}) {
                 network: args.network,
                 presentation: terminalPresentation(stdout, args.color, environment),
                 ...(dependencies.resolvePublicAddresses ? { resolveAddresses: dependencies.resolvePublicAddresses } : {}),
+                ...(dependencies.safeFetch ? { fetchHttps: dependencies.safeFetch } : { fetchHttps: safeFetch }),
                 ...(dependencies.whoisQuery ? { queryWhois: dependencies.whoisQuery } : {}),
             });
             const report = args.network
-                ? await withProgress('Checking public DNS and WHOIS connectivity', buildReport)
+                ? await withProgress('Checking public DNS, HTTPS, and WHOIS connectivity', buildReport)
                 : await buildReport();
             if (!args.quiet) {
                 write(stdout, args.output === 'json'
@@ -579,6 +672,86 @@ async function runParsedCli(args, dependencies = {}) {
                     : terminal(formatCliMailReview(document), args.color));
             return EXIT_CODES.SUCCESS;
         }
+        if (args.action === 'review-evidence') {
+            failureLabel = 'Offline evidence review';
+            let input;
+            try {
+                input = dependencies.readArtifactInput
+                    ? await dependencies.readArtifactInput(args.source)
+                    : await readSavedLookupInputBounded(args.source
+                        ? createReadStream(args.source, { highWaterMark: 64 * 1024 })
+                        : dependencies.stdin || process.stdin, {
+                        limit: MAX_OFFLINE_EVIDENCE_INPUT_BYTES,
+                        label: 'Offline evidence input',
+                    });
+            }
+            catch (error) {
+                if (error instanceof CliUsageError)
+                    throw error;
+                throw new CliUsageError(`Could not read offline evidence input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+            }
+            if (!input.trim())
+                throw new CliUsageError('review-evidence requires one JSON file or a document on stdin.');
+            const document = buildOfflineEvidenceReview(input, commandContext.now());
+            if (!args.quiet)
+                write(stdout, args.output === 'json'
+                    ? formatJsonDocument(document)
+                    : terminal(formatOfflineEvidenceReview(document), args.color));
+            return EXIT_CODES.SUCCESS;
+        }
+        if (args.action === 'domain-control') {
+            failureLabel = 'Domain control review';
+            let input;
+            try {
+                input = dependencies.readArtifactInput
+                    ? await dependencies.readArtifactInput(args.source)
+                    : await readSavedLookupInputBounded(args.source
+                        ? createReadStream(args.source, { highWaterMark: 64 * 1024 })
+                        : dependencies.stdin || process.stdin, {
+                        limit: MAX_OFFLINE_EVIDENCE_INPUT_BYTES,
+                        label: 'Domain control input',
+                    });
+            }
+            catch (error) {
+                if (error instanceof CliUsageError)
+                    throw error;
+                throw new CliUsageError(`Could not read domain control input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+            }
+            if (!input.trim())
+                throw new CliUsageError('domain-control requires one JSON file or a document on stdin.');
+            let parsed;
+            try {
+                parsed = JSON.parse(input);
+            }
+            catch {
+                throw new CliUsageError('Domain control input is not valid JSON.');
+            }
+            const schema = parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed.schema
+                : null;
+            const document = schema === DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA
+                ? buildDomainControlManifest(parsed, commandContext.now())
+                : schema === DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA
+                    ? reviewDomainControlManifest(parsed, commandContext.now())
+                    : null;
+            if (!document) {
+                throw new CliUsageError(`Domain control input must use ${DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA} or ${DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA}.`);
+            }
+            if (!args.quiet)
+                write(stdout, args.output === 'json'
+                    ? formatJsonDocument(document)
+                    : terminal(formatDomainControlResult(document), args.color));
+            return EXIT_CODES.SUCCESS;
+        }
+        if (args.action === 'workflow-plan') {
+            failureLabel = 'Investigation plan';
+            const document = buildInvestigationPlan(args.recipe, args.subject, commandContext.now());
+            if (!args.quiet)
+                write(stdout, args.output === 'json'
+                    ? formatJsonDocument(document)
+                    : terminal(formatInvestigationPlan(document), args.color));
+            return EXIT_CODES.SUCCESS;
+        }
         if (args.action === 'diff') {
             failureLabel = 'Lookup evidence diff';
             const readDiffInput = dependencies.readDiffInput || (async (source) => (readSavedLookupInputBounded(createReadStream(source, { highWaterMark: 64 * 1024 }), {
@@ -605,6 +778,36 @@ async function runParsedCli(args, dependencies = {}) {
                     : terminal(formatCliLookupDiff(document), args.color));
             return EXIT_CODES.SUCCESS;
         }
+        if (args.action === 'timeline') {
+            failureLabel = 'Lookup observation timeline';
+            const readTimelineInput = dependencies.readDiffInput || (async (source) => (readSavedLookupInputBounded(createReadStream(source, { highWaterMark: 64 * 1024 }), {
+                limit: MAX_SAVED_LOOKUP_INPUT_BYTES,
+                label: 'Lookup timeline input',
+            })));
+            const inputs = [];
+            let totalBytes = 0;
+            try {
+                for (const source of args.sources) {
+                    const input = await readTimelineInput(source);
+                    totalBytes += Buffer.byteLength(input, 'utf8');
+                    if (totalBytes > MAX_LOOKUP_TIMELINE_INPUT_BYTES) {
+                        throw new CliUsageError(`Lookup timeline input is limited to ${MAX_LOOKUP_TIMELINE_INPUT_BYTES} bytes in total.`);
+                    }
+                    inputs.push(input);
+                }
+            }
+            catch (error) {
+                if (error instanceof CliUsageError)
+                    throw error;
+                throw new CliUsageError(`Could not read Lookup timeline input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+            }
+            const document = buildCliLookupTimeline(inputs, commandContext.now());
+            if (!args.quiet)
+                write(stdout, args.output === 'json'
+                    ? formatJsonDocument(document)
+                    : terminal(formatCliLookupTimeline(document), args.color));
+            return EXIT_CODES.SUCCESS;
+        }
         if (args.action === 'export') {
             failureLabel = 'Evidence export';
             let input;