@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/cli/command-seeds.mjs

@@ -0,0 +1,18 @@
+import { SUPPORT_COMMAND_DEFINITIONS } from "./support-command-definitions.mjs";
+import { ASSURANCE_COMMAND_DEFINITIONS } from "./assurance-command-definitions.mjs";
+import { COLLECTION_COMMAND_DEFINITIONS } from "./collection-command-definitions.mjs";
+import { NETWORK_COMMAND_DEFINITIONS } from "./network-command-definitions.mjs";
+import { REVIEW_COMMAND_DEFINITIONS } from "./review-command-definitions.mjs";
+import { EVIDENCE_COMMAND_DEFINITIONS } from "./evidence-command-definitions.mjs";
+import { WORKFLOW_COMMAND_DEFINITIONS } from "./workflow-command-definitions.mjs";
+import { HISTORY_COMMAND_DEFINITIONS } from "./history-command-definitions.mjs";
+export const COMMAND_SEEDS = Object.freeze({
+    ...SUPPORT_COMMAND_DEFINITIONS,
+    ...ASSURANCE_COMMAND_DEFINITIONS,
+    ...COLLECTION_COMMAND_DEFINITIONS,
+    ...NETWORK_COMMAND_DEFINITIONS,
+    ...REVIEW_COMMAND_DEFINITIONS,
+    ...EVIDENCE_COMMAND_DEFINITIONS,
+    ...WORKFLOW_COMMAND_DEFINITIONS,
+    ...HISTORY_COMMAND_DEFINITIONS,
+});

package/cli/compare.mjs

@@ -1,4 +1,4 @@
-import { CliUsageError } from "./arguments.mjs";
+import { CliUsageError } from "./errors.mjs";
 import { isRdapRegistryAccessProfile, isWhoisRegistryAccessProfile, } from "./registry-access.mjs";
 import { MAX_SAVED_LOOKUP_INPUT_BYTES, MAX_SAVED_LOOKUP_STRING_LENGTH, SAVED_LOOKUP_SCHEMA, SAVED_LOOKUP_SCHEMA_VERSION, parseSavedLookupDocument, readSavedLookupInputBounded, } from "./saved-lookup.mjs";
 const MAX_COMPARE_INPUT_BYTES = MAX_SAVED_LOOKUP_INPUT_BYTES;

package/cli/config-profile.mjs

@@ -4,7 +4,7 @@ import { join, resolve } from 'node:path';
 import { CliUsageError } from "./errors.mjs";
 import { cliInvocationOptionIndices, cliMetaActionForInvocation } from "./command-reference.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
 export const CLI_CONFIG_SCHEMA = 'whoisleuth.cli.config';
 export const CLI_CONFIG_VERSION = 1;
 export const MAX_CLI_CONFIG_BYTES = 64 * 1024;

package/cli/ct-event-intake.mjs

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { domainToASCII } from 'node:url';
-import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
+import { compareCodeUnits, exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
 import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, retainExternalFindingLimitations, } from "../packages/interchange/external-findings-import.mjs";
 export const CT_EVENT_BATCH_SCHEMA = 'whoisleuth.ct-event-batch';
 export const CT_EVENT_BATCH_VERSION = 1;
@@ -118,9 +118,9 @@ export function buildCtEventFindings(inputRaw) {
     });
     const seen = new Set();
     const unique = candidates
-        .sort((left, right) => left.domain.localeCompare(right.domain)
-        || left.observedAt.localeCompare(right.observedAt)
-        || left.structuredObservation.value.localeCompare(right.structuredObservation.value))
+        .sort((left, right) => compareCodeUnits(left.domain, right.domain)
+        || compareCodeUnits(left.observedAt, right.observedAt)
+        || compareCodeUnits(left.structuredObservation.value, right.structuredObservation.value))
         .filter((item) => {
         const key = `${item.domain}\u0000${item.observedAt}\u0000${item.structuredObservation.value}\u0000${item.structuredObservation.eventId}`;
         if (seen.has(key))

package/cli/discover.mjs

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { decodeBoundedUtf8 } from "../lib/bounded-file.mjs";
-import { CliUsageError } from "./arguments.mjs";
-import { normalizeDiscoverySuffix } from "../lib/registrable-domain.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { normalizeDiscoverySuffix } from "../packages/analysis/registrable-domain.mjs";
 const DEFAULT_DISCOVERY_TLDS = Object.freeze(['com', 'net', 'org']);
 const MAX_DISCOVERY_TLD_TEXT_LENGTH = 1024;
 const MAX_DISCOVERY_TLD_TOKENS_INSPECTED = 80;

package/cli/discovery-observation-snapshot.mjs

@@ -2,9 +2,9 @@ import { createHash } from 'node:crypto';
 import { availabilityState, bulkDnsSummary } from "./bulk-output.mjs";
 import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
-import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { isValidAsciiDomainName } from "../packages/contracts/domain-name.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 export const CLI_DISCOVERY_OBSERVATION_SCHEMA = 'whoisleuth.cli.discovery-observation-snapshot';
 export const CLI_DISCOVERY_OBSERVATION_VERSION = 2;

package/cli/discovery-scan-command-runner.mjs

@@ -23,7 +23,7 @@ async function readAllowlist(source, dependencies, context, classify) {
     catch (error) {
         if (error instanceof CliUsageError)
             throw error;
-        throw new CliUsageError(`Could not read discovery scan allowlist: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+        throw new CliUsageError(`Could not read discovery scan allowlist: ${boundedCliErrorMessage(error, 'Input could not be read')}`, 'input_unavailable');
     }
 }
 async function runDiscoveryScanCommand(args, dependencies, context) {
@@ -52,7 +52,7 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
     const queries = candidates.map((candidate) => String(candidate.domain));
     if (args.plan) {
         const document = buildCollectionPreflight({
-            command: 'discover-scan', targetCount: queries.length, targetLimit: args.deep ? 50 : 500,
+            command: 'discover-scan', targetCount: queries.length,
             deep: args.deep, concurrency: args.concurrency, output: args.output, checkpoint: false,
             customResolvers: Boolean(args.resolverText), allowlist: Boolean(args.allowlistSource),
         });
@@ -86,7 +86,7 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
             throw new CliUsageError('Bulk checkpoint collection context does not match the current DNS resolver selection.');
         }
         if (item.observedAt === null || item.observedAt === undefined) {
-            throw new CliUsageError('Discovery resume requires an observation time for every retained checkpoint result.');
+            throw new CliUsageError('Discovery resume requires an observation time for every retained checkpoint result.', 'missing_input');
         }
     }
     const indicator = context.beginProgress(`Collecting 0 of ${queries.length} generated candidates`);
@@ -135,6 +135,10 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
         }
         catch (error) {
             checkpointFailure = error;
+            eventProgress.emit({ event: 'warning', state: 'checkpoint_unavailable' });
+            if (!eventProgress.enabled) {
+                context.writeStderr(`Checkpoint warning: ${boundedCliErrorMessage(error, 'Checkpoint could not be written')}. The latest progress may not be saved.\n`);
+            }
         }
     }
     const snapshot = args.observationSnapshot
@@ -170,12 +174,6 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
         else
             context.writeStdout(context.terminal(formatTerminalDiscoveryScan(document), args.color));
     }
-    if (checkpointFailure) {
-        eventProgress.emit({ event: 'warning', state: 'checkpoint_unavailable' });
-        if (!eventProgress.enabled) {
-            context.writeStderr(`Checkpoint warning: ${boundedCliErrorMessage(checkpointFailure, 'Checkpoint could not be written')}. Completed output is still available.\n`);
-        }
-    }
     const policyFindings = evaluateCliFailPolicies(document, args.failOn || []);
     if (policyFindings.length && !eventProgress.enabled)
         context.writeStderr(formatFailPolicyNotice(policyFindings));

package/cli/discovery-scan.mjs

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { Buffer } from 'node:buffer';
 import { decodeBoundedUtf8 } from "../lib/bounded-file.mjs";
-import { MAX_DISCOVERY_SUFFIX_LENGTH } from "../lib/registrable-domain.mjs";
+import { MAX_DISCOVERY_SUFFIX_LENGTH } from "../packages/analysis/registrable-domain.mjs";
 import { runBulkLookups } from "./bulk.mjs";
 import { REGISTERED_STATES, BULK_CSV_METADATA_COLUMNS, availabilityState, bulkCsvMetadataValues, bulkDnsSummary } from "./bulk-output.mjs";
 import { cliCsvCell } from "./csv.mjs";

package/cli/discovery-snapshot.mjs

@@ -1,9 +1,9 @@
 import { createHash } from 'node:crypto';
 import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
-import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { isValidAsciiDomainName } from "../packages/contracts/domain-name.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 export const CLI_DISCOVERY_SNAPSHOT_SCHEMA = 'whoisleuth.cli.discovery-snapshot';
 export const CLI_DISCOVERY_SNAPSHOT_VERSION = 1;

package/cli/discovery-workflow.mjs

@@ -4,7 +4,7 @@ import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 async function generateDiscoveryCandidates(args, dependencies, context) {
     const seed = args.seed || await context.readSingleInput();
     if (!seed)
-        throw new CliUsageError('discover requires one brand label or domain as an argument or on stdin.');
+        throw new CliUsageError('discover requires one brand label or domain as an argument or on stdin.', 'missing_input');
     const loadGenerator = dependencies.loadTyposquatGenerator || (() => import("../lib/typosquat-generator.mjs"));
     const generator = await loadGenerator();
     const tlds = normalizeDiscoveryTlds(args.tldText || DEFAULT_DISCOVERY_TLDS.join(','), generator.MAX_GENERATION_TLDS);
@@ -23,7 +23,7 @@ async function generateDiscoveryCandidates(args, dependencies, context) {
         if (args.preset === 'custom'
             && !mutationFamilies.includes('dictionary')
             && !mutationFamilies.includes('dictionary_token_replacement')) {
-            throw new CliUsageError('--dictionary requires a dictionary mutation family.');
+            throw new CliUsageError('--dictionary requires a dictionary mutation family.', 'conflicting_options');
         }
         try {
             dictionaryText = dependencies.readDiscoveryDictionary
@@ -33,11 +33,11 @@ async function generateDiscoveryCandidates(args, dependencies, context) {
         catch (error) {
             if (error instanceof CliUsageError)
                 throw error;
-            throw new CliUsageError(`Could not read discovery dictionary: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+            throw new CliUsageError(`Could not read discovery dictionary: ${boundedCliErrorMessage(error, 'Input could not be read')}`, 'input_unavailable');
         }
         const normalizedDictionary = generator.normalizeCustomDictionaryTerms(dictionaryText);
         if (!normalizedDictionary.values.length) {
-            throw new CliUsageError('The discovery dictionary did not contain any valid terms.');
+            throw new CliUsageError('The discovery dictionary did not contain any valid terms.', 'missing_input');
         }
     }
     const result = generator.generateTyposquatCandidateSet(seed, tlds, {

package/cli/domain-control-monitor.mjs

@@ -1,9 +1,9 @@
 import { classifyQuery } from "../lib/classify.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
 import { buildDomainControlFlightRecorder, validateDomainControlFlightRecorderDocument, normalizeDomainControlFlightRecorderObservations, } from "../lib/domain-control-flight-recorder.mjs";
-import { DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, } from "../packages/contracts/domain-control-flight-recorder.mjs";
-import { DOMAIN_CONTROL_REVIEW_SCHEMA, DOMAIN_CONTROL_REVIEW_VERSION, PUBLIC_DOMAIN_CONTROL_REVIEW_VERSION, CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_VERSION, } from "../packages/contracts/domain-control-review.mjs";
-import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, CLI_DOMAIN_CONTROL_MONITOR_VERSION, PUBLIC_CLI_DOMAIN_CONTROL_MONITOR_VERSION, SUPPORTED_CLI_DOMAIN_CONTROL_MONITOR_VERSIONS, DOMAIN_CONTROL_MONITOR_COLLECTION_KEYS, DOMAIN_CONTROL_MONITOR_FAILURE_CATEGORIES, DOMAIN_CONTROL_MONITOR_FAILURE_KEYS, DOMAIN_CONTROL_MONITOR_LIMITATIONS, DOMAIN_CONTROL_MONITOR_MANIFEST_KEYS, DOMAIN_CONTROL_MONITOR_ROOT_KEYS, MAX_DOMAIN_CONTROL_MONITOR_CONCURRENCY, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS as CONTRACT_MAX_DOMAIN_CONTROL_MONITOR_DOMAINS, MAX_DOMAIN_CONTROL_MONITOR_ERROR_LENGTH, MAX_DOMAIN_CONTROL_MONITOR_FAILURES, MAX_DOMAIN_CONTROL_MONITOR_INPUT_BYTES, MAX_DOMAIN_CONTROL_MONITOR_JSON_CONTAINER_ITEMS, MAX_DOMAIN_CONTROL_MONITOR_JSON_DEPTH, MAX_DOMAIN_CONTROL_MONITOR_JSON_KEYS, MAX_DOMAIN_CONTROL_MONITOR_JSON_VALUES, MIN_DOMAIN_CONTROL_MONITOR_CONCURRENCY, MIN_DOMAIN_CONTROL_MONITOR_DOMAINS, } from "../packages/contracts/domain-control-monitor.mjs";
+import { DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, } from "../packages/contracts/domain-control-flight-recorder.mjs";
+import { DOMAIN_CONTROL_REVIEW_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_VERSION, } from "../packages/contracts/domain-control-review.mjs";
+import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, CLI_DOMAIN_CONTROL_MONITOR_VERSION, PUBLIC_CLI_DOMAIN_CONTROL_MONITOR_VERSION, SUPPORTED_CLI_DOMAIN_CONTROL_MONITOR_VERSIONS, DOMAIN_CONTROL_MONITOR_COLLECTION_KEYS, DOMAIN_CONTROL_MONITOR_EMBEDDED_VERSIONS, DOMAIN_CONTROL_MONITOR_FAILURE_CATEGORIES, DOMAIN_CONTROL_MONITOR_FAILURE_KEYS, DOMAIN_CONTROL_MONITOR_LIMITATIONS, DOMAIN_CONTROL_MONITOR_MANIFEST_KEYS, DOMAIN_CONTROL_MONITOR_ROOT_KEYS, MAX_DOMAIN_CONTROL_MONITOR_CONCURRENCY, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS as CONTRACT_MAX_DOMAIN_CONTROL_MONITOR_DOMAINS, MAX_DOMAIN_CONTROL_MONITOR_ERROR_LENGTH, MAX_DOMAIN_CONTROL_MONITOR_FAILURES, MAX_DOMAIN_CONTROL_MONITOR_INPUT_BYTES, MAX_DOMAIN_CONTROL_MONITOR_JSON_CONTAINER_ITEMS, MAX_DOMAIN_CONTROL_MONITOR_JSON_DEPTH, MAX_DOMAIN_CONTROL_MONITOR_JSON_KEYS, MAX_DOMAIN_CONTROL_MONITOR_JSON_VALUES, MIN_DOMAIN_CONTROL_MONITOR_CONCURRENCY, MIN_DOMAIN_CONTROL_MONITOR_DOMAINS, } from "../packages/contracts/domain-control-monitor.mjs";
 import { validateDomainControlReviewDocument, verifyDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
 import { requireDomainName, requireIsoTimestamp } from "../lib/bounded-contract-normalizers.mjs";
 import { buildCliLookupDocument } from "./formatters/json.mjs";
@@ -62,8 +62,7 @@ function previousSnapshot(input, currentGeneratedAt) {
         throw new CliUsageError(`Previous monitor snapshot must use ${CLI_DOMAIN_CONTROL_MONITOR_SCHEMA} supported version ${SUPPORTED_CLI_DOMAIN_CONTROL_MONITOR_VERSIONS.join(' or ')}.`);
     }
     const legacy = root.version === PUBLIC_CLI_DOMAIN_CONTROL_MONITOR_VERSION;
-    const reviewVersion = legacy ? PUBLIC_DOMAIN_CONTROL_REVIEW_VERSION : DOMAIN_CONTROL_REVIEW_VERSION;
-    const flightVersion = legacy ? PUBLIC_DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION : DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION;
+    const { review: reviewVersion, flightRecorder: flightVersion } = DOMAIN_CONTROL_MONITOR_EMBEDDED_VERSIONS[root.version];
     let previousGeneratedAt;
     try {
         previousGeneratedAt = requireIsoTimestamp(root.generatedAt, 'Previous monitor snapshot generatedAt');
@@ -307,6 +306,7 @@ export function formatDomainControlMonitor(document) {
         `Succeeded    ${document.collection.succeeded}`,
         `Failed       ${document.collection.failed}`,
         `Review       ${document.review.state}`,
+        `Due          ${document.review.counts.due ?? 0}`,
         `Unexpected   ${document.flightRecorder.summary.unexpectedChanges}`,
         '',
     ].join('\n');

package/cli/domain-control-observations.mjs

@@ -4,7 +4,7 @@ import { canonicalCaaRecord, canonicalDsRecord, canonicalMxRecord, canonicalDoma
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 import { postureTransferRestriction } from "../packages/evidence/domain-posture-context.mjs";
 import { MAX_DOMAIN_CONTROL_INPUT_RECORDS, PUBLIC_DOMAIN_CONTROL_MANIFEST_VERSION } from "../packages/contracts/domain-control-manifest.mjs";
-import { scanBoundedJson, } from "../lib/bounded-json.mjs";
+import { scanBoundedJson, } from "../packages/analysis/bounded-json.mjs";
 import { CLI_DOMAIN_CONTROL_REVIEW_INPUT_KEYS, CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_LIMITATIONS, CLI_DOMAIN_CONTROL_REVIEW_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_VERSION, PUBLIC_CLI_DOMAIN_CONTROL_REVIEW_VERSION, SUPPORTED_CLI_DOMAIN_CONTROL_REVIEW_VERSIONS, DOMAIN_CONTROL_REVIEW_VERSION, MAX_DOMAIN_CONTROL_REVIEW_INPUT_BYTES, MAX_DOMAIN_CONTROL_REVIEW_JSON_DEPTH, MAX_DOMAIN_CONTROL_REVIEW_JSON_KEYS, MAX_DOMAIN_CONTROL_REVIEW_JSON_VALUES, MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS, MIN_DOMAIN_CONTROL_REVIEW_LOOKUPS, } from "../packages/contracts/domain-control-review.mjs";
 import { MAX_FLIGHT_RECORDER_VALUES, mergeConcurrentDomainControlFields, } from "../lib/domain-control-flight-recorder.mjs";
 import { DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, reviewDomainControlManifest, verifyDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
@@ -289,6 +289,7 @@ export function formatCliDomainControlReview(document) {
         `Domains     ${review.domains.length}`,
         `Lookups     ${document.input.lookupsReceived}`,
         `Drift       ${review.counts.drift ?? 0}`,
+        `Due         ${review.counts.due ?? 0}`,
         `Incomplete  ${(review.counts.partial ?? 0) + (review.counts.unavailable ?? 0) + (review.counts.unsupported ?? 0)}`,
         '',
         ...review.domains.map((item) => `${item.domain}  ${item.state}`),

package/cli/domain-feed.mjs

@@ -0,0 +1,61 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { DOMAIN_FEED_LIMITS, normalizeDomainFeedSelection } from "../packages/monitoring/domain-feed.mjs";
+import { CliUsageError } from "./errors.mjs";
+export function parseDomainFeedSelectors(values) {
+    const hosts = [], terms = [], negativeTerms = [];
+    for (const value of values) {
+        if (value.startsWith('host:'))
+            hosts.push(value.slice(5));
+        else if (value.startsWith('term:'))
+            terms.push(value.slice(5));
+        else if (value.startsWith('exclude:'))
+            negativeTerms.push(value.slice(8));
+        else
+            throw new CliUsageError('--select requires host:<plain-hostname>, term:<literal-text> or exclude:<literal-text>.');
+    }
+    const selection = normalizeDomainFeedSelection({ hosts, terms, ...(negativeTerms.length ? { negativeTerms } : {}) });
+    if (!selection.hosts.length && !selection.terms.length)
+        throw new CliUsageError('Select at least one exact host or literal term.');
+    return selection;
+}
+/** Stream one descriptor-bound local regular file; URLs, pipes and symlinks are not inputs. */
+export async function* readDomainFeedFile(source, signal) {
+    if (!source || /^[a-z][a-z0-9+.-]*:\/\//iu.test(source))
+        throw new CliUsageError('Domain feed review requires an explicit local regular file, not a URL.');
+    if (signal?.aborted)
+        throw new DOMException('Feed reading was cancelled.', 'AbortError');
+    const handle = await open(source, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    let stream;
+    const abort = () => stream?.destroy(new DOMException('Feed reading was cancelled.', 'AbortError'));
+    try {
+        if (signal?.aborted)
+            throw new DOMException('Feed reading was cancelled.', 'AbortError');
+        const before = await handle.stat();
+        if (!before.isFile())
+            throw new CliUsageError('The domain feed must be a regular file.');
+        if (before.size > DOMAIN_FEED_LIMITS.bytes)
+            throw new CliUsageError('The domain feed exceeds its 256 MiB raw-byte ceiling.');
+        stream = handle.createReadStream({ autoClose: false, highWaterMark: 64 * 1024 });
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
+        let bytes = 0;
+        for await (const chunk of stream) {
+            if (signal?.aborted)
+                throw new DOMException('Feed reading was cancelled.', 'AbortError');
+            if (!(chunk instanceof Uint8Array) || chunk.byteLength > DOMAIN_FEED_LIMITS.bytes - bytes)
+                throw new CliUsageError('The domain feed exceeds its raw-byte ceiling.');
+            bytes += chunk.byteLength;
+            yield chunk;
+        }
+        const after = await handle.stat();
+        if (bytes !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+            throw new CliUsageError('The domain feed changed while it was being read; no review was produced.');
+    }
+    finally {
+        signal?.removeEventListener('abort', abort);
+        stream?.destroy();
+        await handle.close();
+    }
+}

package/cli/errors.mjs

@@ -1,12 +1,14 @@
 import { stripVTControlCharacters } from 'node:util';
+import { hasUnsafeCliText } from "../packages/contracts/cli-grammar.mjs";
 const MAX_CLI_ERROR_MESSAGE_LENGTH = 300;
 const MAX_CLI_DIAGNOSTIC_BYTES = 4_096;
-const CLI_DEFAULT_IGNORABLE_RE = /\p{Default_Ignorable_Code_Point}/u;
 const CLI_DEFAULT_IGNORABLE_GLOBAL_RE = /\p{Default_Ignorable_Code_Point}/gu;
 class CliUsageError extends Error {
-    constructor(message) {
+    reason;
+    constructor(message, reason = 'invalid_input') {
         super(message);
         this.name = 'CliUsageError';
+        this.reason = reason;
     }
 }
 function errorMessage(error) {
@@ -22,9 +24,6 @@ function boundedCliErrorMessage(error, fallback = 'Unexpected command failure')
         .trim()
         .slice(0, MAX_CLI_ERROR_MESSAGE_LENGTH) || fallback;
 }
-function hasUnsafeCliText(value) {
-    return /[\x00-\x1f\x7f-\x9f]/u.test(value) || CLI_DEFAULT_IGNORABLE_RE.test(value);
-}
 // A transient stderr preview, never a checkpoint field. Bound before collecting
 // and redact request URLs and credential-shaped fields before shortening text.
 function createCliDiagnosticOutput() {
@@ -59,6 +58,6 @@ function boundedCliInputError(error, label) {
     if (error instanceof CliUsageError)
         return error;
     const safeLabel = label.replace(/[^A-Za-z0-9 ()_-]+/gu, '').trim().slice(0, 80) || 'Input';
-    return new CliUsageError(`${safeLabel} could not be read as a bounded regular file.`);
+    return new CliUsageError(`${safeLabel} could not be read as a bounded regular file.`, 'input_unavailable');
 }
 export { CliUsageError, MAX_CLI_ERROR_MESSAGE_LENGTH, boundedCliErrorMessage, boundedCliInputError, createCliDiagnosticOutput, hasUnsafeCliText, };

package/cli/evidence-arguments.mjs

@@ -0,0 +1,46 @@
+import {} from "./command-argument-grammar.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { parseArchiveContentDigest } from "./archive-content-digest.mjs";
+import { terminalOptions } from "./argument-values.mjs";
+function parseInspectArchiveArguments(parsed) {
+    const expectedContentDigest = parsed.optionValue('--expect-content-digest');
+    try {
+        parseArchiveContentDigest(expectedContentDigest);
+    }
+    catch {
+        throw new CliUsageError('--expect-content-digest requires sha256:<64 lowercase hex> or sorted-json-v2:sha256:<64 lowercase hex>.');
+    }
+    return {
+        action: 'inspect-archive',
+        source: parsed.positionalValue('source'),
+        passphraseSource: parsed.optionValue('--passphrase-file'),
+        search: parsed.optionValue('--search'),
+        reveal: parsed.hasOption('--reveal'),
+        requireMatch: parsed.hasOption('--require-match'),
+        expectedContentDigest,
+        output: parsed.hasOption('--json') ? 'json' : 'terminal',
+        ...terminalOptions(parsed),
+    };
+}
+function parseSignArtifactArguments(parsed) {
+    return {
+        action: 'sign-artifact',
+        source: parsed.positionalValue('source'),
+        privateKeySource: parsed.optionValue('--private-key-file'),
+    };
+}
+function parseVerifySignatureArguments(parsed) {
+    return {
+        action: 'verify-signature',
+        source: parsed.positionalValue('source'),
+        publicKeySource: parsed.optionValue('--public-key-file'),
+        trustStoreSource: parsed.optionValue('--trust-store-file'),
+        output: parsed.hasOption('--json') ? 'json' : 'terminal',
+        ...terminalOptions(parsed),
+    };
+}
+export const EVIDENCE_ARGUMENT_PARSERS = Object.freeze({
+    'inspect-archive': parseInspectArchiveArguments,
+    'sign-artifact': parseSignArtifactArguments,
+    'verify-signature': parseVerifySignatureArguments,
+});

package/cli/evidence-command-definitions.mjs

@@ -0,0 +1,69 @@
+import { WORKSPACE_ARCHIVE_VERSION } from "../packages/contracts/case-portability.mjs";
+import { LEGACY_WORKSPACE_ARCHIVE_DESCRIPTION, LEGACY_WORKSPACE_ARCHIVE_SCOPE, OPTIONAL_FILE_POSITIONAL, constraint, EMPTY_CONSTRAINTS, commandSeed } from "./command-definition.mjs";
+export const EVIDENCE_COMMAND_DEFINITIONS = Object.freeze({
+    "inspect-archive": commandSeed({
+        reference: {
+            description: `Summarise or search one current version-${WORKSPACE_ARCHIVE_VERSION} workspace archive, with exact ${LEGACY_WORKSPACE_ARCHIVE_DESCRIPTION} support and redacted output by default.`,
+            example: 'whoisleuth inspect-archive workspace.json --search example.test --json',
+            boundary: 'Exact values require --reveal. New content comparisons use the reported sorted-json-v2:sha256 identity with --expect-content-digest; bare sha256 hashes retain their legacy locale-sensitive meaning. Retired and future archives are rejected. The archive is read locally and is never uploaded.',
+        },
+        collection: { scope: `Reads one selected bounded workspace archive v${WORKSPACE_ARCHIVE_VERSION}, retains exact ${LEGACY_WORKSPACE_ARCHIVE_SCOPE} compatibility, and redacts output by default.` },
+        summary: 'Inspect an archive locally',
+        options: ['--passphrase-file', '--search', '--require-match', '--reveal', '--expect-content-digest', '--json', '--quiet', '--no-color'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'requires_all', option: '--reveal', requiredOptions: ['--search'] }),
+            constraint({ kind: 'requires_all', option: '--require-match', requiredOptions: ['--search'] }),
+        ]),
+        handlerOwner: 'evidence',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.workspace-archive-inspection']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "sign-artifact": commandSeed({
+        reference: {
+            description: 'Sign one reviewed response packet or supported manifest with a local private key.',
+            example: 'whoisleuth sign-artifact packet.json --private-key-file analyst-private.pem',
+            boundary: 'The command never creates, stores, or transmits keys. Key custody and signer identity remain the operator\'s responsibility.',
+        },
+        collection: { scope: 'Reads one selected artefact and one local private key without transmitting either.' },
+        summary: 'Sign a reviewed artefact locally',
+        options: ['--private-key-file'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'required', options: ['--private-key-file'] }),
+        ]),
+        handlerOwner: 'evidence',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.signed-evidence-package']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "verify-signature": commandSeed({
+        reference: {
+            description: 'Verify one signed package and report embedded-artefact assurance separately. --trust-store-file also checks an explicit local fingerprint policy and emits a signer-trust report; unknown, retired, revoked or future-reviewed entries exit 4.',
+            example: 'whoisleuth verify-signature packet.signed.json --trust-store-file trust.json --json',
+            boundary: 'A valid signature proves package consistency for the embedded key, not identity, authority or evidence accuracy. With --trust-store-file, unknown, retired, revoked or future-reviewed entries exit 4 even if --public-key-file matches. Replacement fingerprints need their own trusted entry; no signing date overrides current revocation.',
+        },
+        collection: { scope: 'Reads one selected signed package, optional local public key and explicit fingerprint trust file. No automatic trust discovery or network requests.' },
+        summary: 'Verify a signed evidence package',
+        options: ['--public-key-file', '--trust-store-file', '--json', '--quiet', '--no-color'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'evidence',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.evidence-signature-verification', 'whoisleuth.evidence-signer-trust-store', 'whoisleuth.evidence-signer-trust-report']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/evidence-command-runner.mjs

@@ -1,6 +1,7 @@
 import { MAX_OFFLINE_ARTIFACT_BYTES, MAX_OFFLINE_PASSPHRASE_FILE_BYTES, } from "./artifact-verify.mjs";
 import { formatArchiveInspection, inspectWorkspaceArchive, } from "./archive-inspect.mjs";
 import { MAX_SIGNING_KEY_FILE_BYTES, formatEvidenceSignatureVerification, signEvidencePackage, verifyEvidencePackageSignature, } from "./evidence-signing.mjs";
+import { commandHasOwner } from "./command-reference.mjs";
 import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { formatJsonDocument } from "./formatters/json.mjs";
@@ -8,9 +9,7 @@ import { readCliTextInput } from "./input.mjs";
 import { assessEvidenceSignerTrust, formatSignerTrustReport, MAX_SIGNER_TRUST_STORE_BYTES } from "./signer-trust.mjs";
 import { runDiscriminatedCommandHandler } from "./discriminated-command-handlers.mjs";
 export function isEvidenceCommand(args) {
-    return args.action === 'inspect-archive'
-        || args.action === 'sign-artifact'
-        || args.action === 'verify-signature';
+    return commandHasOwner(args.action, 'evidence');
 }
 export function evidenceCommandFailureLabel(action) {
     if (action === 'inspect-archive')

package/cli/evidence-signing.mjs

@@ -169,7 +169,8 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
     }
     catch { /* Signature validity remains independently reportable. */ }
     let publicKeyMatched = null;
-    if (trustedPublicKeyPem) {
+    const trustedKeySupplied = trustedPublicKeyPem !== undefined && trustedPublicKeyPem !== null;
+    if (trustedKeySupplied) {
         const trustedDer = spkiDer(importPublicKey(trustedPublicKeyPem, 'Trusted public key file'));
         publicKeyMatched = trustedDer.equals(publicDer);
         if (!publicKeyMatched)
@@ -181,7 +182,7 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
         state: 'signature_valid',
         signature: Object.freeze({
             state: 'valid',
-            signerTrust: trustedPublicKeyPem ? 'trusted_key' : 'embedded_key_only',
+            signerTrust: trustedKeySupplied ? 'trusted_key' : 'embedded_key_only',
             signedAt,
             keyIdSha256: signature.keyIdSha256,
             publicKeyMatched,

package/cli/external-observation-mapping.mjs

@@ -1,5 +1,5 @@
 import { domainToASCII } from 'node:url';
-import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
+import { compareCodeUnits, exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
 import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, parseExternalFindingsDocument, retainExternalFindingLimitations, } from "../packages/interchange/external-findings-import.mjs";
 export const EXTERNAL_OBSERVATION_MAPPING_SCHEMA = 'whoisleuth.external-observation-mapping';
 export const EXTERNAL_OBSERVATION_MAPPING_VERSION = 1;
@@ -112,7 +112,7 @@ export function mapExternalObservations(inputRaw) {
                 : null,
             structuredObservation: null,
         });
-    }).sort((left, right) => left.domain.localeCompare(right.domain) || left.observedAt.localeCompare(right.observedAt) || left.summary.localeCompare(right.summary));
+    }).sort((left, right) => compareCodeUnits(left.domain, right.domain) || compareCodeUnits(left.observedAt, right.observedAt) || compareCodeUnits(left.summary, right.summary));
     const selected = [];
     const seen = new Set();
     const domainCounts = new Map();

package/cli/formatters/json.mjs

@@ -1,6 +1,7 @@
 import { bulkDnsSummary } from "../bulk-output.mjs";
 import { SAVED_LOOKUP_SCHEMA_VERSION, buildCliLookupDocument, } from "../saved-lookup.mjs";
 import { CLI_LOOKUP_SCHEMA } from "../../packages/contracts/cli-lookup.mjs";
+import { terminalSafeJson } from "../../packages/interchange/json-output.mjs";
 const CLI_BULK_SCHEMA = 'whoisleuth.cli.bulk';
 const CLI_BULK_ITEM_SCHEMA = 'whoisleuth.cli.bulk.item';
 const CLI_CT_SEARCH_SCHEMA = 'whoisleuth.cli.ct-search';
@@ -18,19 +19,6 @@ const CLI_POSTURE_SCHEMA_VERSION = 1;
 const CLI_HTTP_SCHEMA_VERSION = 3;
 const CLI_TLS_SCHEMA_VERSION = 1;
 const CLI_COMPARE_SCHEMA_VERSION = 3;
-const TERMINAL_UNSAFE_JSON_RE = /[\u007f-\u009f\u2028\u2029]|\p{Default_Ignorable_Code_Point}/gu;
-function jsonUnicodeEscape(value) {
-    const codePoint = value.codePointAt(0);
-    if (codePoint <= 0xffff)
-        return `\\u${codePoint.toString(16).padStart(4, '0')}`;
-    const offset = codePoint - 0x10000;
-    const high = 0xd800 + (offset >> 10);
-    const low = 0xdc00 + (offset & 0x3ff);
-    return `\\u${high.toString(16).padStart(4, '0')}\\u${low.toString(16).padStart(4, '0')}`;
-}
-function terminalSafeJson(value, space) {
-    return JSON.stringify(value, null, space).replace(TERMINAL_UNSAFE_JSON_RE, jsonUnicodeEscape);
-}
 function formatJsonDocument(document) {
     return `${terminalSafeJson(document, 2)}\n`;
 }

package/cli/formatters/terminal-command-formats.mjs

@@ -168,6 +168,12 @@ function formatTerminalPosture(document) {
         `Dependencies   ${dependencies.length} observed · ${dmarcAuthorizations.length} DMARC reporting destination${dmarcAuthorizations.length === 1 ? '' : 's'} checked`,
         '',
     ];
+    for (const value of dmarcAuthorizations.slice(0, 10)) {
+        const item = terminalRecord(value);
+        lines.push(`Reporting      ${safeTerminalValue(item.destination)} · ${safeTerminalValue(item.reportType)} · ${item.state === 'self' ? 'same organisational scope' : safeTerminalValue(item.state).replaceAll('_', ' ')}`);
+        if (item.error)
+            lines.push(`  Detail       ${safeTerminalValue(item.error)}`);
+    }
     for (const value of checks) {
         const item = terminalRecord(value);
         lines.push(`[${safeTerminalValue(item.status, 'info').toUpperCase()}] ${safeTerminalValue(item.label)}: ${safeTerminalValue(item.summary)}`);

package/cli/formatters/terminal-lookup.mjs

@@ -1,4 +1,5 @@
 import { registryAccessProfileLabel } from "../registry-access.mjs";
+import { dnsAddressFamilyEvidence } from "../../packages/evidence/dns-query-outcome.mjs";
 import { appendTechnologyLines } from "./terminal-technology.mjs";
 import { appendDeliveryMetadataLines, appendPublicationMetadataLines } from "./terminal-metadata.mjs";
 import { securityPostureReview, summarizeSecurityPostureReview } from "../../lib/website-security-posture.mjs";
@@ -319,6 +320,11 @@ function formatTerminalLookup(document, { detail = 'standard' } = {}) {
         if (Object.keys(dns).length) {
             dnsLines.push(`Evidence       ${titleCase(dns.status)}`);
             dnsLines.push(`Completeness   ${dns.complete === true ? 'Complete' : 'Incomplete'}`);
+            for (const family of ['a', 'aaaa']) {
+                const evidence = dnsAddressFamilyEvidence(dns, family);
+                if (evidence.value)
+                    dnsLines.push(`${family.toUpperCase().padEnd(14)} ${safeTerminalValue(evidence.value)}`);
+            }
             const recordTypes = [
                 ['a', 'A'], ['aaaa', 'AAAA'], ['cname', 'CNAME'], ['ns', 'NS'],
                 ['mx', 'MX'], ['spf', 'SPF'], ['dmarc', 'DMARC'], ['caa', 'CAA'],

package/cli/history-arguments.mjs

@@ -0,0 +1,39 @@
+import {} from "./command-argument-grammar.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { terminalOptions, jsonOutput, parseTwoFileComparisonArguments, uniqueSources, } from "./argument-values.mjs";
+function parseDiffArguments(parsed) {
+    const compared = parseTwoFileComparisonArguments(parsed, 'diff');
+    const leftSessionId = parsed.optionValue('--left-session');
+    const rightSessionId = parsed.optionValue('--right-session');
+    for (const [option, value] of [
+        ['--left-session', leftSessionId],
+        ['--right-session', rightSessionId],
+    ]) {
+        if (value !== null && !/^[A-Za-z0-9_-]{1,128}$/u.test(value)) {
+            throw new CliUsageError(`${option} requires one bounded saved-session ID.`);
+        }
+    }
+    return { action: 'diff', ...compared, leftSessionId, rightSessionId };
+}
+export const HISTORY_ARGUMENT_PARSERS = Object.freeze({
+    diff: parseDiffArguments,
+    reconcile: (parsed) => ({
+        action: 'reconcile',
+        sources: uniqueSources(parsed, 'reconcile'),
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    }),
+    timeline: (parsed) => ({
+        action: 'timeline',
+        sources: uniqueSources(parsed, 'timeline'),
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    }),
+    export: (parsed) => ({
+        action: 'export',
+        source: parsed.positionalValue('source'),
+        format: parsed.hasOption('--markdown') ? 'markdown' : parsed.hasOption('--html') ? 'html' : 'json',
+        compact: parsed.hasOption('--compact'),
+        includeAttribution: !parsed.hasOption('--no-attribution'),
+    }),
+});