@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/NOTICE

@@ -38,6 +38,12 @@ distributed as third-party-notices.txt. The website inventory is served at
 only the CLI runtime dependency closure. Both are generated from the reviewed
 lockfile, and the website inventory is checked for lockfile drift in CI.
 
+The development-only fixtures/risk-evaluation/rows.json is a minimised,
+stratified adaptation of PhiUSIIL Phishing URL (Website), Arvind Prasad and
+Shalini Chandra (2024), licensed under CC BY 4.0 without warranties. The source
+and licence links, modifications and reproduction instructions are in that
+directory's README.md. This dataset is not included in the website or CLI.
+
 The generated Unicode confusable projection is derived from Unicode UTS #39
 data file confusables.txt, Unicode version 17.0.0.
 

package/README.md

@@ -41,6 +41,7 @@ whoisleuth lookup example.test --deep --summary
 whoisleuth bulk domains.txt --csv
 whoisleuth discover example.test --preset common --jsonl
 whoisleuth compare lookup.json --json
+whoisleuth mail-headers message.eml --json
 whoisleuth verify-artifact lookup.json --json --strict-exit
 ```
 
@@ -50,14 +51,7 @@ only `bulk` accepts multiple targets.
 
 ## Command groups
 
-| Group | Common commands |
-| --- | --- |
-| Investigate | `lookup`, `bulk`, `discover`, `ct-search`, `posture`, `http`, `tls`, `compare`, `brief` |
-| Respond | `case-pack`, `change-packet`, `sharing-review`, `export` |
-| Assure | `dnssec-validate`, `mail-transport`, `domain-control`, `assurance`, `workflow-plan`, `diff`, `inspect-archive`, `verify-artifact` |
-| Utilities | `doctor`, `commands`, `completion`, `manual`, `registry-scaffold` |
-
-Use the installed registry for the complete inventory:
+Use the installed registry to browse Investigate, Respond, Assure and Utilities:
 
 ```bash
 whoisleuth commands --group investigate
@@ -66,10 +60,6 @@ whoisleuth commands --json
 whoisleuth manual | man -l -
 ```
 
-`registry-scaffold` has a separate fixture contract: its `--profile` selects a
-fixed fixture profile and it rejects shared `--config` profiles. It creates
-sanitised local fixture material.
-
 ## Collection and output
 
 Fast Lookup is registration-first. Deep Lookup explicitly adds the applicable
@@ -85,9 +75,24 @@ or domain-only output only where declared. `--output` writes a private local
 file atomically and refuses an existing path unless `--force` is selected.
 `--strict-exit` and `--fail-on` expose selected evidence states to automation.
 
-Exit codes are 0 for completion, 2 for invalid input, 3 for collection or
-comparison failure, 4 for a partial result or unmet selected evidence policy,
-70 for internal bootstrap failure, 130 for cancellation and 143 for SIGTERM.
+`case open --domain example.test --output cases.json` creates an ordinary local
+Case file. `case show`, `note`, `pin`, `assess` and `recheck` review or update it
+offline. Mutations require explicit output and preserve earlier retained evidence;
+see `docs/cli.md#local-case-files` for JSON inputs and conflict handling. Working
+files contain private analyst content, not attached file bytes.
+
+`manifest --package --output evidence.wlep --passphrase-file ./passphrase.txt`
+encrypts selected evidence files and their manifest. Use the same explicit
+passphrase file with `verify-artifact --package` to authenticate and verify it
+offline. Ordinary ZIPs and folder exports remain unencrypted; see `docs/cli.md`
+for complete examples and file-handling boundaries.
+
+`workflow-run` pauses on a partial collection. Resume retains it without
+recollection and keeps exit code 4 even if later steps finish. Failed validation
+or export steps remain retryable. See `docs/cli.md` for checkpoint compatibility.
+
+The included `docs/cli-reference.md` lists common exit codes and compatibility
+contracts. A completed command can still contain partial source evidence.
 
 ## Repository checkout
 

package/bin/whoisleuth.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import EXIT_CODES from "../cli/exit-codes.mjs";
-import { metaActionDefinition } from "../cli/command-reference.mjs";
+import { HELP, commandHelp, isCliCommand, metaActionDefinition } from "../cli/command-reference.mjs";
+import { presentTerminalOutput, terminalPresentation } from "../cli/terminal-presentation.mjs";
 for (const stream of [process.stdout, process.stderr]) {
     stream.on('error', (error) => {
         if (error.code === 'EPIPE')
@@ -10,6 +11,9 @@ for (const stream of [process.stdout, process.stderr]) {
     });
 }
 const argv = process.argv.slice(2);
+const rootHelp = argv.length === 1 && metaActionDefinition('help').aliases.includes(argv[0] ?? '');
+const command = argv.length === 2 && isCliCommand(argv[0])
+    && metaActionDefinition('help').aliases.includes(argv[1] ?? '') ? argv[0] : null;
 if (argv.length === 1 && metaActionDefinition('version').aliases.includes(argv[0] ?? '')) {
     const require = createRequire(import.meta.url);
     const metadata = require('../package.json');
@@ -21,6 +25,9 @@ if (argv.length === 1 && metaActionDefinition('version').aliases.includes(argv[0
         process.stdout.write(`${metadata.version}\n`);
     }
 }
+else if (rootHelp || command) {
+    process.stdout.write(presentTerminalOutput(command ? commandHelp(command) : HELP, terminalPresentation(process.stdout)));
+}
 else {
     const [configModule, errorsModule, outputModule, runnerModule] = await Promise.all([
         import("../cli/config-profile.mjs"),

package/cli/archive-content-digest.mjs

@@ -0,0 +1,14 @@
+/** Bare hashes retain their original v1 meaning; new identities declare v2. */
+export function parseArchiveContentDigest(value) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (typeof value !== 'string' || value.length > 'sorted-json-v2:sha256:'.length + 64) {
+        throw new TypeError('Expected archive content digest must be sha256:<64 lowercase hex> or sorted-json-v2:sha256:<64 lowercase hex>.');
+    }
+    const explicit = value.startsWith('sorted-json-v2:');
+    const digestSha256 = explicit ? value.slice('sorted-json-v2:'.length) : value;
+    if (!/^sha256:[a-f0-9]{64}$/u.test(digestSha256)) {
+        throw new TypeError('Expected archive content digest must be sha256:<64 lowercase hex> or sorted-json-v2:sha256:<64 lowercase hex>.');
+    }
+    return Object.freeze({ canonicalization: explicit ? 'sorted-json-v2' : 'sorted-json-v1', digestSha256 });
+}

package/cli/archive-inspect.mjs

@@ -1,14 +1,13 @@
 import { Buffer } from 'node:buffer';
 import { createHash } from 'node:crypto';
 import { domainToASCII } from 'node:url';
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
-import { decryptWorkspaceArchive, isEncryptedWorkspaceArchive, } from "../packages/workspace/workspace-archive-crypto.mjs";
 import { WORKSPACE_ARCHIVE_SCHEMA, readWorkspaceArchive, } from "../packages/workspace/workspace-archive.mjs";
-import { canonicalArtifactJson } from "../packages/evidence/artifact-integrity.mjs";
-import { MAX_OFFLINE_ARTIFACT_BYTES, verifyOfflineArtifact, } from "./artifact-verify.mjs";
+import { canonicalArtifactJson, canonicalArtifactJsonV2 } from "../packages/evidence/artifact-integrity.mjs";
+import { parseArchiveContentDigest } from "./archive-content-digest.mjs";
+import { verifyOfflineWorkspaceArchive } from "./artifact-verify.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
 export const ARCHIVE_INSPECTION_SCHEMA = 'whoisleuth.workspace-archive-inspection';
-export const ARCHIVE_INSPECTION_VERSION = 2;
+export const ARCHIVE_INSPECTION_VERSION = 3;
 export const MAX_ARCHIVE_SEARCH_LENGTH = 253;
 export const MAX_ARCHIVE_SEARCH_MATCHES = 100;
 export const MAX_ARCHIVE_SEARCH_NODES = 100_000;
@@ -22,32 +21,11 @@ const SEARCHABLE_FIELDS = new Set([
     'target',
 ]);
 const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
-const SHA256_DIGEST_RE = /^sha256:[a-f0-9]{64}$/u;
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
         : null;
 }
-function parseJson(raw) {
-    if (typeof raw !== 'string')
-        throw new TypeError('Archive input must be UTF-8 JSON text.');
-    const bytes = Buffer.byteLength(raw, 'utf8');
-    if (bytes === 0 || bytes > MAX_OFFLINE_ARTIFACT_BYTES) {
-        throw new TypeError(`Archive input must be between 1 byte and ${MAX_OFFLINE_ARTIFACT_BYTES} bytes.`);
-    }
-    let parsed;
-    try {
-        scanBoundedJson(raw);
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new TypeError('Archive input must be valid bounded JSON without duplicate keys.');
-    }
-    const value = record(parsed);
-    if (!value)
-        throw new TypeError('Archive input must contain one JSON object.');
-    return value;
-}
 function normalizeSearch(value) {
     if (value === null || value === undefined || value === '')
         return null;
@@ -71,7 +49,7 @@ function canonicalSearchValue(value) {
 function valueDigest(value) {
     return createHash('sha256').update(value, 'utf8').digest('hex');
 }
-function archiveContentDigest(sections) {
+function archiveContentDigests(sections) {
     const identity = sections.map((section) => ({
         id: section.id,
         schema: section.schema,
@@ -85,15 +63,10 @@ function archiveContentDigest(sections) {
             return content;
         })(),
     }));
-    return `sha256:${createHash('sha256').update(canonicalArtifactJson(identity), 'utf8').digest('hex')}`;
-}
-function expectedContentDigest(value) {
-    if (value === null || value === undefined || value === '')
-        return null;
-    if (typeof value !== 'string' || !SHA256_DIGEST_RE.test(value)) {
-        throw new TypeError('Expected archive content digest must use the form sha256 followed by 64 lowercase hexadecimal characters.');
-    }
-    return value;
+    return Object.freeze({
+        current: `sha256:${createHash('sha256').update(canonicalArtifactJsonV2(identity), 'utf8').digest('hex')}`,
+        legacy: `sha256:${createHash('sha256').update(canonicalArtifactJson(identity), 'utf8').digest('hex')}`,
+    });
 }
 function searchSection(section, value, search, reveal, results, state) {
     const stack = [{ value, depth: 0 }];
@@ -146,21 +119,10 @@ function searchSection(section, value, search, reveal, results, state) {
     }
 }
 export async function inspectWorkspaceArchive(raw, options = {}) {
-    const parsed = parseJson(raw);
-    const encrypted = isEncryptedWorkspaceArchive(parsed);
-    if (encrypted && !options.passphrase) {
-        throw new TypeError('Encrypted archive inspection requires a separate passphrase file.');
-    }
-    await verifyOfflineArtifact(raw, options.passphrase === undefined
-        ? {}
-        : { passphrase: options.passphrase });
-    const archiveValue = encrypted
-        ? await decryptWorkspaceArchive(parsed, options.passphrase)
-        : parsed;
-    const archive = await readWorkspaceArchive(archiveValue);
-    const contentDigestSha256 = archiveContentDigest(archive.sections);
-    const expectedDigest = expectedContentDigest(options.expectedContentDigest);
-    if (expectedDigest && expectedDigest !== contentDigestSha256) {
+    const expectedDigest = parseArchiveContentDigest(options.expectedContentDigest);
+    const { archive, encrypted } = await verifyOfflineWorkspaceArchive(raw, options);
+    const digests = archiveContentDigests(archive.sections);
+    if (expectedDigest && expectedDigest.digestSha256 !== (expectedDigest.canonicalization === 'sorted-json-v2' ? digests.current : digests.legacy)) {
         throw new TypeError('Workspace archive content digest did not match the expected value.');
     }
     const search = normalizeSearch(options.search);
@@ -196,7 +158,9 @@ export async function inspectWorkspaceArchive(raw, options = {}) {
             inputBytes: Buffer.byteLength(raw, 'utf8'),
             sectionCount: archive.sections.length,
             recordCount: archive.sections.reduce((sum, section) => sum + section.recordCount, 0),
-            contentDigestSha256,
+            contentDigest: `sorted-json-v2:${digests.current}`,
+            contentDigestSha256: digests.legacy,
+            expectedContentDigestCanonicalization: expectedDigest?.canonicalization ?? null,
         }),
         sections: Object.freeze(archive.sections.map((section) => Object.freeze({
             id: section.id,
@@ -218,6 +182,7 @@ export async function inspectWorkspaceArchive(raw, options = {}) {
         limitations: Object.freeze([
             'Inspection validates the archive and reports bounded section metadata without printing retained evidence by default.',
             'The content digest covers ordered section identities and normalised content after excluding each section export timestamp. Equality detects matching retained archive content but does not authenticate its source or accuracy.',
+            'Use the versioned contentDigest identity for new comparisons. The compatibility contentDigestSha256 field and bare expected hashes retain the original locale-sensitive digest; they are not a cross-locale identity guarantee.',
             'Search checks exact values in a small allowlist of target fields and never searches analyst notes, contacts, or raw evidence.',
             ...(reveal
                 ? ['Search values were revealed only because the operator supplied --reveal; handle the output as sensitive evidence.']
@@ -234,7 +199,9 @@ export function formatArchiveInspection(report) {
         `Archive: ${report.archive.encrypted ? 'encrypted' : 'plain'} · v${report.archive.version}`,
         `Sections: ${report.summary.sectionCount}`,
         `Records: ${report.summary.recordCount}`,
-        `Content digest: ${report.summary.contentDigestSha256}`,
+        `Content identity: ${report.summary.contentDigest}`,
+        ...(report.summary.expectedContentDigestCanonicalization === 'sorted-json-v1'
+            ? ['Expected digest matched using the legacy locale-sensitive form.'] : []),
     ];
     for (const section of report.sections) {
         lines.push(`${safeTerminalValue(section.label)}: ${section.recordCount} records · ${safeTerminalValue(section.status)} · ${section.bytes} bytes`);