@slicedearth/whoisleuth-cli 1.32.2 → 1.34.0

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,6 +23,7 @@ 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 { runLookupCommand } from "./lookup-command-runner.mjs";
@@ -65,9 +67,10 @@ Review saved evidence:
   page-compare       Compare saved static page and TLS evidence.
   mail-review        Review saved passive mail exposure evidence.
   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 +79,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.
@@ -89,11 +93,12 @@ Copyright 2026 slicedearth. Licensed under AGPL-3.0-only.
 Source and licence: https://github.com/slicedearth/whoisleuth
 `;
 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]',
@@ -111,6 +116,7 @@ const COMMAND_USAGE = Object.freeze({
     '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]',
     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 +130,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 +191,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.',
     },
@@ -224,15 +235,48 @@ const COMMAND_DETAILS = Object.freeze({
         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.' },
+    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 +385,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 +417,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'
@@ -605,6 +670,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;

package/docs/cli.md

@@ -8,7 +8,9 @@ hosted WHOISleuth deployment.
 source location. It groups commands by investigation, discovery, saved-evidence,
 integrity, and calibration workflows. `whoisleuth <command> --help` displays the
 command's purpose, focused invocation, example, and collection boundary without
-printing the full command list. Packaged copies include `LICENSE`, `NOTICE`, and
+printing the full command list. `whoisleuth commands --json` exposes those same
+contracts as a stable local catalogue for wrappers and terminal tooling.
+Packaged copies include `LICENSE`, `NOTICE`, and
 `TRADEMARKS.md` alongside the CLI documentation.
 
 ## Installation
@@ -17,11 +19,18 @@ Public releases require Node.js 24 or later and install the `whoisleuth`
 command:
 
 ```bash
-npm exec --yes --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
-npm install --global @slicedearth/whoisleuth-cli
+npm exec --yes --ignore-scripts --package=@slicedearth/whoisleuth-cli -- whoisleuth --help
+npm install --global --ignore-scripts @slicedearth/whoisleuth-cli
 whoisleuth doctor
 ```
 
+Update and verify an existing global installation with:
+
+```bash
+npm install --global --ignore-scripts @slicedearth/whoisleuth-cli@latest
+whoisleuth --version
+```
+
 The scoped package and application share one semantic version. The package runs
 locally and does not call the hosted WHOISleuth deployment. Networked commands
 contact only the sources described by their collection profile; offline review,
@@ -34,6 +43,7 @@ node bin/whoisleuth.mts lookup example.com
 node bin/whoisleuth.mts lookup AS13335 --json
 printf 'example.com\n' | node bin/whoisleuth.mts lookup --json
 node bin/whoisleuth.mts lookup example.com --deep
+node bin/whoisleuth.mts lookup example.com --deep --plan --json
 node bin/whoisleuth.mts lookup example.com --deep --summary
 node bin/whoisleuth.mts lookup example.com --deep --verbose
 node bin/whoisleuth.mts lookup example.com --deep --markdown --output lookup.md
@@ -41,6 +51,7 @@ node bin/whoisleuth.mts lookup example.com --deep --json --strict-exit --events
 cat domains.txt | node bin/whoisleuth.mts bulk --jsonl
 node bin/whoisleuth.mts bulk domains.txt --csv --registered-only
 node bin/whoisleuth.mts bulk domains.txt --domains --inconclusive-only
+node bin/whoisleuth.mts bulk domains.txt --queries --errors-only
 node bin/whoisleuth.mts bulk domains.txt --concurrency 4
 node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json
 node bin/whoisleuth.mts bulk domains.txt --deep --checkpoint bulk-checkpoint.json --resume
@@ -55,6 +66,7 @@ node bin/whoisleuth.mts tls example.com --json
 node bin/whoisleuth.mts registry-support example.uk --json
 node bin/whoisleuth.mts risk-calibrate calibration.json --json
 node bin/whoisleuth.mts verify-artifact workspace.json --json
+node bin/whoisleuth.mts verify-artifact lookup.json --json
 node bin/whoisleuth.mts verify-artifact workspace-encrypted.json --passphrase-file passphrase.txt --json
 node bin/whoisleuth.mts source-report lookup.json --json
 node bin/whoisleuth.mts inspect-archive workspace.json --json
@@ -66,12 +78,15 @@ node bin/whoisleuth.mts compare lookup.json --json
 node bin/whoisleuth.mts page-compare official.json candidate.json --json
 node bin/whoisleuth.mts mail-review bulk.json --json
 node bin/whoisleuth.mts diff first-lookup.json second-lookup.json --json
+node bin/whoisleuth.mts timeline first-observation.json second-observation.json latest-observation.json --json
 node bin/whoisleuth.mts export lookup.json > evidence.json
 node bin/whoisleuth.mts export lookup.json --markdown > evidence.md
 node bin/whoisleuth.mts export lookup.json --html > evidence.html
 node bin/whoisleuth.mts doctor
 node bin/whoisleuth.mts doctor --network --json
+node bin/whoisleuth.mts commands --json
 node bin/whoisleuth.mts completion zsh
+node bin/whoisleuth.mts completion powershell
 node bin/whoisleuth.mts manual | man -l -
 ```
 
@@ -87,10 +102,13 @@ npm run cli:package:check
 
 The check includes only the executable, reachable TypeScript modules, CLI
 guide, licence, notices, and trademark terms. It excludes application routes,
-deployment adapters, tests, and development tools. Its generated manifest stays
-private. Release-candidate assembly is a separate explicit operation and never
-publishes from a developer checkout. Use the scoped package name; an unqualified
-`npx whoisleuth` is not this project.
+deployment adapters, tests, and development tools. Direct runtime dependencies
+are pinned to the exact versions exercised by the reviewed repository lockfile.
+The package and its dependencies require no lifecycle scripts, so the install
+examples disable them explicitly.
+Its generated manifest stays private. Release-candidate assembly is a separate
+explicit operation and never publishes from a developer checkout. Use the
+scoped package name; an unqualified `npx whoisleuth` is not this project.
 
 Lookup defaults to the conservative fast profile. `--deep` must be requested
 explicitly and can add bounded WHOIS, DNS, website, TLS, registrar RDAP, and
@@ -104,6 +122,14 @@ up to five normalized PTR names; JSON retains up to eight. PTR names are
 operator-published routing context, not proof of hosting control or ownership.
 Fast lookups do not run this query.
 
+`lookup --plan` performs classification and prints a versioned preflight without
+starting collection. It lists the normalized target, selected fast or deep
+mode, planned source families, conditional operations, and the data each family
+may receive. The plan cannot predict live feature configuration, cache state,
+redirects, referrals, source availability, or an exact request count. It can be
+combined with `--json`, but not with report, detail, strict-exit, progress-event,
+or quiet options.
+
 Only one query is accepted by `lookup`. Multiple-input processing belongs to
 the explicit `bulk` command rather than being silently inferred by `lookup`.
 Standard input is capped at 4 KiB and must contain one non-empty line.
@@ -114,32 +140,49 @@ request. Its output is described below.
 
 `doctor` is offline by default. It checks the Node runtime, platform, terminal
 capabilities, and availability of offline command families. `doctor --network`
-adds bounded public-DNS and WHOIS port 43 checks against fixed diagnostic
-infrastructure. It retains only state and a bounded explanation, not resolved
-addresses or response content. A failed optional network check returns the
-partial-failure exit code rather than claiming that all CLI collection is
-unavailable.
-
-`completion bash`, `completion zsh`, and `completion fish` print static shell
-completion scripts to stdout. The command does not edit a shell profile or make
-a network request. Review the generated script before sourcing it or placing it
-in the relevant shell completion directory. `manual` prints a generated roff
-manual page and likewise changes no local configuration.
+adds independent bounded public-DNS, HTTPS/RDAP bootstrap, and WHOIS port 43
+checks against fixed IANA diagnostic infrastructure. The three probes run
+within the same per-probe ceiling so one stalled transport does not block the
+others. The report retains only state, HTTP status, and a bounded explanation,
+not resolved addresses or response content. A failed optional network check
+returns the partial-failure exit code rather than claiming that all CLI
+collection is unavailable.
+
+`completion bash`, `completion zsh`, `completion fish`, and `completion
+powershell` print static shell completion scripts to stdout. The command does
+not edit a shell profile or make a network request. Review the generated script
+before sourcing it or placing it in the relevant shell completion directory.
+`manual` prints a generated roff manual page and likewise changes no local
+configuration.
+
+`commands` prints the installed command catalogue without running collection or
+reading evidence. `commands --json` emits version 1 of the
+`whoisleuth.cli.command-catalogue` schema, including each command's usage,
+example, declared collection mode, collection scope, and boundary. This is the
+supported discovery contract for local wrappers; it is not a permission grant
+or a substitute for focused help.
+
+Focused command help and the generated manual classify every operation as
+offline or networked and state the relevant target, input, and concurrency
+ceiling. These labels describe observable behavior rather than granting
+authorization. The packaged `DISCLOSURE` defines the intended defensive scope;
+operators remain responsible for law, provider terms, and authorization.
 
 ## Deployment boundary
 
-The CLI is a local repository tool. The serverless deployment publishes only
-`frontend/build` and packages functions only from `netlify/functions`, so
-`bin/` and `cli/` are not part of the hosted static site or function bundle.
-Both the application root and the assembled CLI package remain private and are
-not published to the public npm registry.
+The CLI runs locally. The serverless deployment publishes only `frontend/build`
+and packages functions only from `netlify/functions`, so `bin/` and `cli/` are
+not part of the hosted static site or function bundle. The application root and
+ordinary package-check candidate remain private. Explicitly reviewed CLI
+release candidates can be published under the scoped public package described
+in the installation section.
 
 Commands that query RDAP, WHOIS, DNS, HTTP, TLS, or Certificate Transparency do
 so directly from the machine running the CLI. They do not use the hosted login,
 hosted session, or deployment usage controls; upstream providers can see and
 rate-limit the local machine's network address. Offline `discover`, `compare`,
-`page-compare`, `mail-review`, `diff`, `risk-calibrate`, `verify-artifact`, `source-report`, `export`,
-`completion`, and `manual` operations make no network requests. Commands write
+`page-compare`, `mail-review`, `diff`, `timeline`, `risk-calibrate`, `verify-artifact`, `source-report`, `export`,
+`commands`, `completion`, and `manual` operations make no network requests. Commands write
 to stdout unless the analyst deliberately selects a local output file.
 
 ## Output
@@ -266,6 +309,15 @@ registration, DNS, page identity, mail, certificate, and relationship fields,
 keeps missing and unavailable evidence distinct, and makes no ownership or
 maliciousness inference. The output records both original observation times.
 
+`timeline <observation.json> <observation.json> [...]` accepts from 2 to 20
+saved Lookup documents for one domain, orders them by their validated
+observation times, and compares each adjacent pair offline. The 32 MiB aggregate
+input ceiling is enforced while files are read and again by the timeline
+builder. Output retains normalized field states and observation times but no
+input filenames or raw registry payloads. A difference can reflect a domain
+change or changed collection conditions, so the command makes no current-state,
+ownership, intent, safety, or maliciousness conclusion.
+
 When diagnostics version 5, 6, 7, or 8 reports a documented registry collection
 constraint, terminal output also shows the suffix, WHOIS and RDAP access
 profiles, and the bounded limitation. This is static access-policy context: it
@@ -286,7 +338,7 @@ machine access is not evidence that a domain is unregistered or safe.
 This release supports `lookup`, `bulk`, `ct-search`, `discover`, `discover-scan`, `posture`,
 `http`, `tls`, `registry-support`, `risk-calibrate`, `verify-artifact`,
 `inspect-archive`, `sign-artifact`, `verify-signature`, `source-report`,
-`compare`, `page-compare`, `mail-review`, `diff`, `export`, `doctor`, `completion`, and `manual`. Additional command families
+`compare`, `page-compare`, `mail-review`, `diff`, `timeline`, `export`, `doctor`, `commands`, `completion`, and `manual`. Additional command families
 are added as separate bounded increments rather than exposing incomplete
 aliases.
 
@@ -385,7 +437,11 @@ Risk model.
 evidence contents. Input is capped at 15 MiB. It currently recognises ordinary
 and encrypted workspace archives, case-response packets, acquisition-decision
 exports, domain-comparison exports, Bulk mail-exposure exports, and Bulk review
-manifests.
+manifests. It also validates the bounded versioned structure of saved CLI
+Lookup JSON. Because saved Lookup documents do not embed a checksum or
+signature, that result is reported as `structure_valid` with content integrity
+explicitly unchecked. Saved Lookup validation retains its stricter 8 MiB
+document ceiling.
 
 For an ordinary workspace archive, the command validates the versioned
 structure, section byte counts, record counts, and per-section checksums. For a
@@ -469,19 +525,25 @@ deep mode.
 
 Bulk uses the shared compact lookup response, so it does not retain raw RDAP
 objects or WHOIS response bodies. `--json` returns one bounded collection;
-`--jsonl` emits one self-contained versioned item per line. Version 2 adds a
+`--jsonl` emits one self-contained versioned item per line. `--domains` emits
+only successfully normalized domain names, while `--queries` preserves the
+selected bounded input queries and is suitable for an exact retry queue.
+Version 2 adds a
 bounded `dnsSummary` projection for observed A, AAAA, NS, and MX records plus
 null MX, SPF, and DMARC state. `--csv` writes fixed columns for automation,
-including the DNS summaries and explicit outcome; `--domains` writes only the
-normalized retained domain names for a subsequent command.
-
-`--registered-only` and `--inconclusive-only` are mutually exclusive output
-filters. The first retains registered, for-sale, and expiring authority-aware
-states. The second retains unknown authority states and failed rows. Filtering
-does not change collection and never converts an unavailable or failed source
-into an unregistered result. Machine documents record collected and emitted
-counts. A mixture of successful and failed queries exits with code 4 while
-preserving every collected result before output filtering.
+including the DNS summaries and explicit outcome.
+
+`--registered-only`, `--inconclusive-only`, and `--errors-only` are mutually
+exclusive output filters. The first retains registered, for-sale, and expiring
+authority-aware states. The second retains unknown authority states and failed
+rows. The third retains only rows whose lookup operation failed, which is useful
+for producing an exact retry queue without treating an inconclusive successful
+lookup as an operational error. Filtering does not change collection and never
+converts an unavailable or failed source into an unregistered result. Machine
+documents record collected and emitted counts. A mixture of successful and
+failed queries exits with code 4 while preserving every collected result before
+output filtering. For example, `bulk domains.txt --queries --errors-only`
+produces only the exact failed inputs while retaining the partial-failure exit.
 
 ## Certificate Transparency search
 

package/frontend/src/lib/analysis/bulk-domain-comparison.js

@@ -151,7 +151,7 @@ function freshness(observedAt, now) {
 export function buildBulkDomainComparison(leftRaw, rightRaw, observedAtRaw = null, options = {}) {
     const left = normalizeBulkSessionResult(leftRaw);
     const right = normalizeBulkSessionResult(rightRaw);
-    if (!left || !right || left.domain === right.domain)
+    if (!left || !right || (left.domain === right.domain && !options.allowSameDomain))
         return null;
     const observedAt = timestamp(observedAtRaw);
     const registry = context(left, right, 'Registry and registrar evidence', ['rdap', 'availability'], observedAt, options);
@@ -214,11 +214,17 @@ export function buildBulkDomainComparison(leftRaw, rightRaw, observedAtRaw = nul
         freshness: freshness(observedAt, options.now ?? Date.now()),
         rows,
         counts,
-        limitations: [
-            'This compares compact settled evidence already present in Bulk and makes no new request.',
-            'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
-            'Equality does not establish common ownership, infrastructure control, intent, safety, or maliciousness.',
-        ],
+        limitations: options.allowSameDomain
+            ? [
+                'This compares normalized evidence already present in two saved observations for the same domain and makes no new request.',
+                'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
+                'An observed difference can reflect changed collection conditions and does not by itself establish current state, ownership, intent, safety, or maliciousness.',
+            ]
+            : [
+                'This compares compact settled evidence already present in Bulk and makes no new request.',
+                'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
+                'Equality does not establish common ownership, infrastructure control, intent, safety, or maliciousness.',
+            ],
     };
 }
 export async function buildBulkDomainComparisonExport(comparisonRaw, generatedAtRaw = new Date().toISOString()) {

package/lib/csv.mjs

@@ -1,7 +1,7 @@
 // Shared bounded CSV serialization for browser and CLI exports. Values can
 // contain upstream evidence, so normalize controls and prevent spreadsheet
 // formula execution before applying ordinary CSV quoting.
-const CSV_FORMULA_TRIGGER_RE = /^(?:[\t\r\n ]*[=+\-@]|[\t\r\n])/u;
+const CSV_FORMULA_TRIGGER_RE = /^[=+\-@]/u;
 export const MAX_CSV_CELL_LENGTH = 32_768;
 function csvText(value) {
     const raw = Array.isArray(value)

package/lib/evidence-report-markdown.mjs

@@ -21,7 +21,7 @@ function appendGroups(lines, groups) {
 function formatLookupEvidenceMarkdown(document, options = {}) {
     const report = buildLookupEvidenceReport(document, options);
     const lines = [
-        `# Lookup evidence report — ${escapeMarkdownValue(report.title)}`,
+        `# Lookup evidence report: ${escapeMarkdownValue(report.title)}`,
         '', `> ${report.notice}`, '',
     ];
     appendFields(lines, report.metadata);
@@ -42,7 +42,7 @@ function formatLookupEvidenceMarkdown(document, options = {}) {
     }
     else {
         for (const field of report.comparison.fields) {
-            lines.push(`- **${escapeMarkdownValue(field.label)} — ${escapeMarkdownValue(field.status)}:** RDAP ${escapeMarkdownValue(field.rdap)}; WHOIS ${escapeMarkdownValue(field.whois)}`);
+            lines.push(`- **${escapeMarkdownValue(field.label)} (${escapeMarkdownValue(field.status)}):** RDAP ${escapeMarkdownValue(field.rdap)}; WHOIS ${escapeMarkdownValue(field.whois)}`);
         }
         if (report.comparison.omitted)
             lines.push(`- ${report.comparison.omitted} additional comparison fields omitted.`);
@@ -51,7 +51,7 @@ function formatLookupEvidenceMarkdown(document, options = {}) {
         lines.push('', '## Registry / registrar RDAP comparison');
         appendFields(lines, report.registrarComparison.health);
         for (const field of report.registrarComparison.fields) {
-            lines.push(`- **${escapeMarkdownValue(field.label)} — ${escapeMarkdownValue(field.status)}:** Registry RDAP ${escapeMarkdownValue(field.registry)}; registrar RDAP ${escapeMarkdownValue(field.registrar)}`);
+            lines.push(`- **${escapeMarkdownValue(field.label)} (${escapeMarkdownValue(field.status)}):** Registry RDAP ${escapeMarkdownValue(field.registry)}; registrar RDAP ${escapeMarkdownValue(field.registrar)}`);
         }
         if (report.registrarComparison.omitted)
             lines.push(`- ${report.registrarComparison.omitted} additional comparison fields omitted.`);

package/package.json

@@ -2,6 +2,7 @@
   "name": "@slicedearth/whoisleuth-cli",
   "type": "module",
   "license": "AGPL-3.0-only",
+  "author": "slicedearth",
   "contentPolicy": {
     "class": "dual-use"
   },
@@ -32,11 +33,11 @@
   "bugs": {
     "url": "https://github.com/slicedearth/whoisleuth/issues"
   },
-  "version": "1.32.2",
+  "version": "1.34.0",
   "dependencies": {
-    "parse5": "^8.0.1",
-    "tldts": "^7.4.9",
-    "undici": "^8.7.0"
+    "parse5": "8.0.1",
+    "tldts": "7.4.10",
+    "undici": "8.9.0"
   },
   "files": [
     "bin/**/*.mjs",
@@ -49,6 +50,7 @@
     "LICENSES/*.txt",
     "NOTICE",
     "README.md",
+    "SECURITY.md",
     "TRADEMARKS.md",
     "third-party-notices.txt"
   ],

package/third-party-notices.txt

@@ -5130,7 +5130,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 ================================================================================
-tldts@7.4.9
+tldts@7.4.10
 Relationship: direct production dependency
 Declared licence: MIT
 Licence source: LICENSE
@@ -5149,7 +5149,7 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ================================================================================
-tldts-core@7.4.9
+tldts-core@7.4.10
 Relationship: transitive production dependency
 Declared licence: MIT
 Licence source: LICENSE