@slicedearth/whoisleuth-cli 1.47.4 → 2.0.0

package/cli/lookup-command-runner.mjs

@@ -1,6 +1,7 @@
 import { abortable } from "../lib/abort.mjs";
 import { classifyQuery } from "../lib/classify.mjs";
 import { runUnifiedLookup } from "../lib/lookup.mjs";
+import { plannedLookupProgressSources } from "../lib/lookup-source-progress.mjs";
 import { CliUsageError, boundedCliErrorMessage } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { buildCliEvidenceExport } from "./export-evidence.mjs";
@@ -10,10 +11,23 @@ import { formatLookupEvidenceMarkdown } from "./formatters/markdown.mjs";
 import { formatTerminalLookup } from "./formatters/terminal.mjs";
 import { buildCliLookupPlan, formatCliLookupPlan } from "./lookup-plan.mjs";
 import { createCliProgressEvents } from "./progress-events.mjs";
+import { serializeCliLookupDocument } from "./saved-lookup.mjs";
 import { lookupStrictExitFindings } from "./strict-exit.mjs";
 import { evaluateCliFailPolicies, formatFailPolicyNotice } from "./fail-policy.mjs";
 import { formatCliJunit } from "./ci-report.mjs";
+import { browseLookupOperation, canBrowseLookup } from "./lookup-browser.mjs";
+import { writePrivateFile } from "./output-file.mjs";
 async function runLookupCommand(args, dependencies, context) {
+    const browserInput = dependencies.stdin || process.stdin;
+    const browserEnvironment = dependencies.environment || process.env;
+    if (args.browse === true) {
+        if (!args.query)
+            throw new CliUsageError('--browse requires a positional target because interactive stdin is reserved for navigation.');
+        const supportsBrowser = dependencies.canBrowseLookup || canBrowseLookup;
+        if (!supportsBrowser(browserInput, context.stdout, browserEnvironment)) {
+            throw new CliUsageError('--browse requires interactive terminal input and output. Use ordinary terminal output or --json when redirecting.');
+        }
+    }
     const eventProgress = createCliProgressEvents(context.stderr, {
         command: 'lookup',
         enabled: args.events,
@@ -43,51 +57,100 @@ async function runLookupCommand(args, dependencies, context) {
             : context.terminal(formatCliLookupPlan(plan), args.color));
         return EXIT_CODES.SUCCESS;
     }
-    const indicator = context.beginProgress(args.deep
-        ? 'Collecting deep Lookup evidence'
-        : 'Collecting registration evidence');
-    let settledSources = 0;
-    let result;
-    try {
-        result = await abortable(() => executeLookup(classified, args.deep
-            ? {
-                fast: false,
-                compact: false,
-                ...(dependencies.signal ? { signal: dependencies.signal } : {}),
-                onSourceSettled: (settlement) => {
-                    settledSources += 1;
-                    indicator.update(`Collected ${settledSources} source${settledSources === 1 ? '' : 's'} · ${settlement.source.replaceAll('_', ' ')} ${settlement.state}`);
-                    eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
-                },
+    let documentGeneratedAt = '';
+    const buildDocument = (result) => {
+        documentGeneratedAt = context.now();
+        return buildCliLookupDocument(query, classified, result, documentGeneratedAt, args.deep ? 'deep' : 'fast', {
+            ...(args.observerLabel ? { observerLabel: args.observerLabel } : {}),
+            ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
+        });
+    };
+    let document;
+    if (args.browse === true) {
+        const browse = dependencies.browseLookupOperation || browseLookupOperation;
+        document = await browse({
+            input: browserInput,
+            output: context.stdout,
+            environment: browserEnvironment,
+            color: args.color,
+            ...(args.palette ? { palette: args.palette } : {}),
+            query,
+            mode: args.deep ? 'deep' : 'fast',
+            plannedSources: args.deep ? plannedLookupProgressSources(classified) : [],
+            ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+            collect: async ({ signal, onSourceSettled }) => {
+                const result = await abortable(() => executeLookup(classified, args.deep
+                    ? {
+                        fast: false,
+                        compact: false,
+                        signal,
+                        onSourceSettled: (settlement) => {
+                            onSourceSettled(settlement);
+                            eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
+                        },
+                    }
+                    : {
+                        fast: true,
+                        compact: false,
+                        signal,
+                    }), signal);
+                return buildDocument(result);
+            },
+        });
+        if (args.saveLookup) {
+            if (dependencies.signal?.aborted) {
+                throw dependencies.signal.reason || new DOMException('Aborted', 'AbortError');
             }
-            : {
-                fast: true,
-                compact: false,
-                ...(dependencies.signal ? { signal: dependencies.signal } : {}),
-            }), dependencies.signal);
+            const save = dependencies.writePrivateFile || writePrivateFile;
+            await save(args.saveLookup, serializeCliLookupDocument(document), {
+                existingFileMessage: 'Saved Lookup file already exists. Choose a new --save-lookup path or remove the existing file explicitly.',
+            });
+            context.writeStderr('Saved the completed private Lookup JSON. It can contain raw public registry and WHOIS responses plus target and collection context; review it before sharing.\n');
+        }
     }
-    finally {
-        context.endProgress();
+    else {
+        const indicator = context.beginProgress(args.deep
+            ? 'Collecting deep Lookup evidence'
+            : 'Collecting registration evidence');
+        let settledSources = 0;
+        let result;
+        try {
+            result = await abortable(() => executeLookup(classified, args.deep
+                ? {
+                    fast: false,
+                    compact: false,
+                    ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+                    onSourceSettled: (settlement) => {
+                        settledSources += 1;
+                        indicator.update(`Collected ${settledSources} source${settledSources === 1 ? '' : 's'} · ${settlement.source.replaceAll('_', ' ')} ${settlement.state}`);
+                        eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
+                    },
+                }
+                : {
+                    fast: true,
+                    compact: false,
+                    ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+                }), dependencies.signal);
+        }
+        finally {
+            context.endProgress();
+        }
+        document = buildDocument(result);
     }
-    const now = context.now();
-    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast', {
-        ...(args.observerLabel ? { observerLabel: args.observerLabel } : {}),
-        ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
-    });
     if (!args.quiet) {
         if (args.output === 'json')
-            context.writeStdout(formatJsonDocument(document));
+            context.writeStdout(serializeCliLookupDocument(document));
         else if (args.output === 'junit')
             context.writeStdout(formatCliJunit(document));
         else if (args.output === 'markdown' || args.output === 'html') {
             const loadEvidence = dependencies.loadEvidenceExport || (() => import("../lib/evidence-export.mjs"));
             const evidenceModule = await loadEvidence();
-            const report = buildCliEvidenceExport(JSON.stringify(document), evidenceModule, now);
+            const report = buildCliEvidenceExport(JSON.stringify(document), evidenceModule, documentGeneratedAt);
             context.writeStdout(args.output === 'markdown'
                 ? formatLookupEvidenceMarkdown(report, { includeAttribution: args.includeAttribution })
                 : formatLookupEvidenceHtml(report, { includeAttribution: args.includeAttribution }));
         }
-        else {
+        else if (args.browse !== true) {
             context.writeStdout(context.terminal(formatTerminalLookup(document, { detail: args.detail }), args.color));
         }
     }

package/cli/lookup-diff.mjs

@@ -1,7 +1,7 @@
 import { buildBulkComparisonEvidence } from "../lib/bulk-comparison-evidence.mjs";
 import { recordOrEmpty } from "../lib/bounded-contract-normalizers.mjs";
-import { buildBulkDomainComparison, } from "../frontend/src/lib/analysis/bulk-domain-comparison.js";
-import { relationshipObservation } from "../frontend/src/lib/analysis/relationship-evidence.js";
+import { buildBulkDomainComparison, } from "../packages/investigation/bulk-domain-comparison.mjs";
+import { relationshipObservation } from "../packages/comparison/relationship-evidence.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 export const CLI_LOOKUP_DIFF_SCHEMA = 'whoisleuth.cli.lookup-diff';

package/cli/lookup-plan.mjs

@@ -84,6 +84,7 @@ function formatCliLookupPlan(plan) {
         `Type: ${plan.target.type}`,
         `Mode: ${plan.mode}`,
         'Network requests made: no',
+        'Collection requires network: yes',
         '',
         'Planned collection:',
     ];

package/cli/mail-review.mjs

@@ -1,45 +1,169 @@
 import { Buffer } from 'node:buffer';
 import { getDomain } from 'tldts';
-import { analyzeTlsaEvidence } from "../lib/tlsa-evidence.mjs";
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { isValidAsciiDomainName } from "../lib/hostname.mjs";
 import { CliUsageError } from "./errors.mjs";
 export const CLI_MAIL_REVIEW_SCHEMA = 'whoisleuth.cli.mail-review';
-export const CLI_MAIL_REVIEW_VERSION = 2;
+export const CLI_MAIL_REVIEW_VERSION = 3;
 export const MAX_MAIL_REVIEW_INPUT_BYTES = 16 * 1024 * 1024;
 export const MAX_MAIL_REVIEW_ROWS = 500;
+const UNSAFE_TEXT_RE = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f]/u;
+const UNSAFE_TEXT_GLOBAL_RE = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f]+/gu;
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
 function text(value, maximum = 500) {
     return typeof value === 'string'
-        ? value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        ? value.replace(UNSAFE_TEXT_GLOBAL_RE, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
         : '';
 }
 function boolean(value) {
     return typeof value === 'boolean' ? value : null;
 }
-function mxHosts(availability, summary) {
-    const direct = Array.isArray(availability.mxHosts) ? availability.mxHosts : [];
-    const summarized = Array.isArray(summary.mx) ? summary.mx : [];
-    const output = new Set();
-    for (const candidate of [...direct, ...summarized].slice(0, 200)) {
-        const normalized = text(candidate, 300).replace(/^\d+\s+/u, '').replace(/\.$/u, '').toLowerCase();
-        if (normalized && normalized.length <= 253)
-            output.add(normalized);
-        if (output.size >= 50)
-            break;
+function timestamp(value, label) {
+    if (typeof value !== 'string' || value.length > 64 || !Number.isFinite(Date.parse(value))) {
+        throw new CliUsageError(`${label} must be a valid bounded timestamp.`);
     }
-    return [...output];
+    return new Date(value).toISOString();
 }
-function providerDomains(hosts) {
+function booleanOrNull(value, label) {
+    if (value === null || typeof value === 'boolean')
+        return value;
+    throw new CliUsageError(`${label} must be true, false, or null.`);
+}
+const DNS_STATES = new Set([
+    'success', 'partial', 'error', 'unsupported', 'not_found', 'skipped',
+    'disabled', 'not_applicable', 'unavailable', 'rate_limited',
+]);
+function parseMxValues(value, label) {
+    if (!Array.isArray(value) || value.length > 100) {
+        throw new CliUsageError(`${label} must be a bounded MX string array.`);
+    }
+    const hosts = new Set();
+    let nullMx = false;
+    for (const [index, candidate] of value.entries()) {
+        const itemLabel = `${label} item ${index + 1}`;
+        if (typeof candidate !== 'string' || candidate.length < 1 || candidate.length > 300
+            || candidate.trim() !== candidate || UNSAFE_TEXT_RE.test(candidate)) {
+            throw new CliUsageError(`${itemLabel} is not a safe canonical MX value.`);
+        }
+        const match = /^(?:(\d{1,5}) )?([^\s]+)$/u.exec(candidate);
+        if (!match || (match[1] !== undefined && Number(match[1]) > 65_535)) {
+            throw new CliUsageError(`${itemLabel} is not a valid MX priority and hostname.`);
+        }
+        const exchange = match[2];
+        if (!exchange)
+            throw new CliUsageError(`${itemLabel} is missing its MX hostname.`);
+        if (exchange === '.') {
+            nullMx = true;
+            continue;
+        }
+        const hostname = exchange.replace(/\.$/u, '').toLowerCase();
+        if (!isValidAsciiDomainName(hostname, { requireDot: true, requireLowercase: true })) {
+            throw new CliUsageError(`${itemLabel} is not a valid ASCII MX hostname.`);
+        }
+        hosts.add(hostname);
+    }
+    if (nullMx && hosts.size)
+        throw new CliUsageError(`${label} mixes a null MX marker with mail hosts.`);
+    return Object.freeze({ hosts: Object.freeze([...hosts].sort()), nullMx });
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function validateMxEvidence(availability, summary, label, hasMx, hasNullMx) {
+    const direct = parseMxValues(availability.mxHosts, `${label} availability MX hosts`);
+    const summarized = parseMxValues(summary.mx, `${label} DNS summary MX hosts`);
+    if (!sameStrings(direct.hosts, summarized.hosts)) {
+        throw new CliUsageError(`${label} has inconsistent availability and DNS summary MX hosts.`);
+    }
+    if ((direct.nullMx || summarized.nullMx) && hasNullMx !== true) {
+        throw new CliUsageError(`${label} has a null MX marker without matching null-MX evidence.`);
+    }
+    if (hasNullMx === true && (hasMx !== false || summarized.hosts.length > 0)) {
+        throw new CliUsageError(`${label} has contradictory null-MX and mail-host evidence.`);
+    }
+    return summarized.hosts;
+}
+function validateMailRow(value, index, expectedVersion) {
+    const item = record(value);
+    const label = `Mail review row ${index + 1}`;
+    const version = Number(item.version);
+    if (item.schema !== 'whoisleuth.cli.bulk.item' || ![2, 3].includes(version)
+        || (expectedVersion !== null && version !== expectedVersion)) {
+        throw new CliUsageError(`${label} must use the matching WHOISleuth Bulk item schema version 2 or 3.`);
+    }
+    timestamp(item.generatedAt, `${label} generation time`);
+    if (version === 3
+        && (!(item.observedAt === null || (typeof item.observedAt === 'string' && timestamp(item.observedAt, `${label} observation time`)))
+            || !['current_run', 'resumed_checkpoint'].includes(String(item.collectionOrigin)))) {
+        throw new CliUsageError(`${label} has invalid version 3 collection provenance.`);
+    }
+    if (item.ok === false) {
+        if (typeof item.query !== 'string' || !item.query || item.query.length > 2_048
+            || typeof item.error !== 'string' || !item.error || item.error.length > 500) {
+            throw new CliUsageError(`${label} contains an invalid failed result.`);
+        }
+        return item;
+    }
+    const availability = record(item.availability);
+    const diagnostics = record(item.diagnostics);
+    const summary = record(item.dnsSummary);
+    const domain = item.registrableDomain;
+    const inputHostname = item.inputHostname;
+    if (item.ok !== true || item.type !== 'domain' || typeof item.query !== 'string' || !item.query
+        || typeof domain !== 'string' || !isValidAsciiDomainName(domain, { requireDot: true, requireLowercase: true })
+        || typeof inputHostname !== 'string' || !isValidAsciiDomainName(inputHostname, { requireDot: true, requireLowercase: true })
+        || getDomain(inputHostname, { allowPrivateDomains: true }) !== domain
+        || typeof item.isSubdomain !== 'boolean' || !['fast', 'deep'].includes(String(item.mode))
+        || !isRecord(item.availability) || !isRecord(item.diagnostics) || !isRecord(item.dnsSummary)) {
+        throw new CliUsageError(`${label} does not match a completed domain Bulk result.`);
+    }
+    const dns = record(availability.dns);
+    const dnsStatus = text(summary.status, 40).toLowerCase();
+    if (!DNS_STATES.has(dnsStatus) || text(dns.status, 40).toLowerCase() !== dnsStatus) {
+        throw new CliUsageError(`${label} has missing or inconsistent DNS source status.`);
+    }
+    for (const key of ['a', 'aaaa', 'ns', 'mx']) {
+        if (!Array.isArray(summary[key]) || summary[key].length > 100) {
+            throw new CliUsageError(`${label} has an invalid bounded DNS ${key} summary.`);
+        }
+    }
+    const summaryNullMx = booleanOrNull(summary.hasNullMx, `${label} null-MX summary`);
+    const summarySpf = booleanOrNull(summary.hasSpf, `${label} SPF summary`);
+    const summaryDmarc = booleanOrNull(summary.hasDmarc, `${label} DMARC summary`);
+    const availabilityMx = booleanOrNull(availability.hasMx, `${label} MX state`);
+    const availabilityNullMx = booleanOrNull(availability.hasNullMx, `${label} null-MX state`);
+    const availabilitySpf = booleanOrNull(availability.hasSpf, `${label} SPF state`);
+    const availabilityDmarc = booleanOrNull(availability.hasDmarc, `${label} DMARC state`);
+    if (availabilityNullMx !== summaryNullMx || availabilitySpf !== summarySpf || availabilityDmarc !== summaryDmarc) {
+        throw new CliUsageError(`${label} has contradictory DNS and availability mail states.`);
+    }
+    const summarizedMx = validateMxEvidence(availability, summary, label, availabilityMx, availabilityNullMx);
+    if (availabilityMx !== (summarizedMx.length ? true : availabilityNullMx === null ? null : false)) {
+        throw new CliUsageError(`${label} has contradictory MX evidence.`);
+    }
+    return {
+        ...item,
+        availability: { ...availability, mxHosts: summarizedMx },
+        dnsSummary: { ...summary, mx: summarizedMx },
+    };
+}
+function allProviderDomains(hosts) {
     return [...new Set(hosts.flatMap((host) => {
-            const labels = host.split('.').filter(Boolean);
-            const domain = getDomain(host, { allowPrivateDomains: true })
-                ?? (labels.length >= 2 ? labels.slice(-2).join('.') : null);
+            const domain = getDomain(host, { allowPrivateDomains: true });
             return domain ? [domain.toLowerCase()] : [];
-        }))].sort().slice(0, 20);
+        }))].sort();
+}
+function providerDomains(hosts) {
+    const domains = allProviderDomains(hosts);
+    return { domains: domains.slice(0, 20), omitted: Math.max(0, domains.length - 20) };
 }
 function mailState(input) {
-    if (!['success', 'partial'].includes(input.dnsStatus))
+    if (input.dnsStatus !== 'success')
         return 'evidence_incomplete';
     if (input.hasNullMx === true)
         return 'null_mx';
@@ -54,50 +178,23 @@ function mailState(input) {
         return 'no_explicit_mx';
     return 'evidence_incomplete';
 }
-function alignMailDaneEvidence(report, hosts) {
-    const aligned = report.service?.transport === 'tcp'
-        && report.service.port === 25
-        && hosts.includes(report.service.hostname);
-    if (aligned || report.state === 'invalid')
-        return report;
-    return Object.freeze({
-        ...report,
-        state: 'invalid',
-        limitations: Object.freeze([
-            ...report.limitations,
-            'The TLSA service name did not identify port 25 on an MX hostname retained for this domain.',
-        ]),
-    });
-}
 function normalizeMailRow(value) {
     const item = record(value);
     if (item.ok !== true)
         return null;
     const availability = record(item.availability);
     const summary = record(item.dnsSummary);
-    const domain = text(item.registrableDomain ?? item.query ?? availability.domain, 253).toLowerCase().replace(/\.$/u, '');
-    if (!domain || !domain.includes('.'))
-        return null;
-    const dns = record(availability.dns);
-    const dnsStatus = text(summary.status ?? dns.status, 40).toLowerCase() || 'unavailable';
-    const hosts = mxHosts(availability, summary);
-    const hasMx = boolean(availability.hasMx) ?? (hosts.length ? true : null);
-    const hasNullMx = boolean(availability.hasNullMx) ?? boolean(summary.hasNullMx);
-    const hasSpf = boolean(availability.hasSpf) ?? boolean(summary.hasSpf);
-    const hasDmarc = boolean(availability.hasDmarc) ?? boolean(summary.hasDmarc);
+    const domain = text(item.registrableDomain, 253).toLowerCase().replace(/\.$/u, '');
+    const dnsStatus = text(summary.status, 40).toLowerCase();
+    const hosts = Array.isArray(availability.mxHosts)
+        ? availability.mxHosts.filter((value) => typeof value === 'string')
+        : [];
+    const hasMx = boolean(availability.hasMx);
+    const hasNullMx = boolean(availability.hasNullMx);
+    const hasSpf = boolean(availability.hasSpf);
+    const hasDmarc = boolean(availability.hasDmarc);
     const state = mailState({ dnsStatus, hasMx, hasNullMx, hasSpf, hasDmarc });
-    const tlsaInput = record(item.tlsaEvidence);
-    const dane = Object.keys(tlsaInput).length
-        ? alignMailDaneEvidence(analyzeTlsaEvidence({
-            serviceName: tlsaInput.serviceName,
-            dnssecState: tlsaInput.dnssecState,
-            pkixValidationState: tlsaInput.pkixValidationState,
-            records: tlsaInput.records,
-            certificateDerBase64: tlsaInput.certificateDerBase64,
-            spkiDerBase64: tlsaInput.spkiDerBase64,
-            authorityMaterials: tlsaInput.authorityMaterials,
-        }), hosts)
-        : null;
+    const providers = providerDomains(hosts);
     return {
         domain,
         state,
@@ -107,12 +204,12 @@ function normalizeMailRow(value) {
         hasSpf,
         hasDmarc,
         mxHosts: hosts,
-        providerDomains: providerDomains(hosts),
-        dane,
+        providerDomains: providers.domains,
+        providerDomainsOmitted: providers.omitted,
+        providerDomainsTruncated: providers.omitted > 0,
         limitations: [
             ...(dnsStatus === 'partial' ? ['DNS evidence was partial.'] : []),
             ...(state === 'no_explicit_mx' ? ['No explicit MX is not equivalent to a null MX or proof that delivery is impossible.'] : []),
-            ...(dane?.state === 'matched' ? [] : dane ? ['Supplied TLSA evidence did not establish one complete DNSSEC-validated match.'] : ['No TLSA evidence was supplied for offline DANE comparison.']),
             'Mail configuration does not establish use, control, intent, safety, or maliciousness.',
         ],
     };
@@ -125,11 +222,15 @@ function parseInput(textValue) {
     if (!textInput)
         throw new CliUsageError('Mail review requires one Bulk JSON or JSONL document.');
     let values;
+    let containerVersion = null;
     try {
+        scanBoundedJson(textInput);
         const parsed = JSON.parse(textInput);
         const document = record(parsed);
         if (document.schema === 'whoisleuth.cli.bulk' && [2, 3].includes(Number(document.version)) && Array.isArray(document.results)) {
             values = document.results;
+            containerVersion = Number(document.version);
+            timestamp(document.generatedAt, 'Mail review Bulk generation time');
         }
         else if (document.schema === 'whoisleuth.cli.bulk.item' && [2, 3].includes(Number(document.version))) {
             values = [document];
@@ -142,7 +243,10 @@ function parseInput(textValue) {
         if (error instanceof CliUsageError)
             throw error;
         try {
-            values = textInput.split(/\r?\n/u).filter(Boolean).map((line) => JSON.parse(line));
+            values = textInput.split(/\r?\n/u).filter(Boolean).map((line) => {
+                scanBoundedJson(line);
+                return JSON.parse(line);
+            });
         }
         catch {
             throw new CliUsageError('Mail review input must be valid WHOISleuth Bulk JSON or JSONL.');
@@ -151,11 +255,7 @@ function parseInput(textValue) {
     if (!values.length || values.length > MAX_MAIL_REVIEW_ROWS) {
         throw new CliUsageError(`Mail review supports between 1 and ${MAX_MAIL_REVIEW_ROWS} Bulk rows.`);
     }
-    const rows = values.map((value) => record(value));
-    if (rows.some((value) => value.schema !== 'whoisleuth.cli.bulk.item' || ![2, 3].includes(Number(value.version)))) {
-        throw new CliUsageError('Every Mail review row must use WHOISleuth Bulk item schema version 2 or 3.');
-    }
-    return rows;
+    return values.map((value, index) => validateMailRow(value, index, containerVersion));
 }
 function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
     const inputRows = parseInput(textValue);
@@ -172,48 +272,59 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
     };
     for (const row of rows)
         counts[row.state] += 1;
-    const daneCounts = {
-        matched: 0,
-        different: 0,
-        partial: 0,
-        untrusted: 0,
-        unavailable: 0,
-        invalid: 0,
-        not_supplied: 0,
-    };
-    for (const row of rows)
-        daneCounts[row.dane?.state ?? 'not_supplied'] += 1;
     const providerMap = new Map();
     for (const row of rows) {
-        for (const provider of row.providerDomains) {
+        // Row presentation is capped at 20 providers, but correlation operates on
+        // the complete already-validated MX set (itself bounded to 100 entries).
+        for (const provider of allProviderDomains(row.mxHosts)) {
             const domains = providerMap.get(provider) ?? [];
             domains.push(row.domain);
             providerMap.set(provider, domains);
         }
     }
-    const providerRelationships = [...providerMap.entries()]
+    const allProviderRelationships = [...providerMap.entries()]
         .filter(([, domains]) => new Set(domains).size >= 2)
-        .map(([providerDomain, domains]) => ({
-        providerDomain,
-        domains: [...new Set(domains)].sort().slice(0, 100),
-        method: 'Shared registrable domain of an observed MX hostname',
-        limitation: 'Shared mail providers are common and do not establish common ownership, control, intent, safety, or maliciousness.',
-    }))
-        .sort((left, right) => left.providerDomain.localeCompare(right.providerDomain))
-        .slice(0, 100);
+        .map(([providerDomain, domains]) => {
+        const uniqueDomains = [...new Set(domains)].sort();
+        const omittedDomains = Math.max(0, uniqueDomains.length - 100);
+        return {
+            providerDomain,
+            domains: uniqueDomains.slice(0, 100),
+            domainCount: uniqueDomains.length,
+            domainsTruncated: omittedDomains > 0,
+            omittedDomains,
+            method: 'Shared registrable domain of an observed MX hostname',
+            limitation: 'Shared mail providers are common and do not establish common ownership, control, intent, safety, or maliciousness.',
+        };
+    })
+        .sort((left, right) => left.providerDomain.localeCompare(right.providerDomain));
+    const providerRelationships = allProviderRelationships.slice(0, 100);
+    const providerCoverage = {
+        complete: rows.every((row) => !row.providerDomainsTruncated)
+            && allProviderRelationships.length <= 100
+            && allProviderRelationships.every((relationship) => !relationship.domainsTruncated),
+        rowsWithOmittedProviders: rows.filter((row) => row.providerDomainsTruncated).length,
+        omittedProviderDomains: rows.reduce((sum, row) => sum + row.providerDomainsOmitted, 0),
+        relationshipCount: allProviderRelationships.length,
+        retainedRelationshipCount: providerRelationships.length,
+        omittedRelationships: Math.max(0, allProviderRelationships.length - 100),
+        omittedRelationshipDomains: allProviderRelationships.reduce((sum, relationship) => sum + relationship.omittedDomains, 0),
+    };
     return {
         schema: CLI_MAIL_REVIEW_SCHEMA,
         version: CLI_MAIL_REVIEW_VERSION,
         generatedAt,
         counts,
-        daneCounts,
         rows,
         providerRelationships,
+        providerCoverage,
         limitations: [
             'This review is passive and uses DNS evidence already retained in a WHOISleuth Bulk result; it makes no network request.',
             'Null MX, no explicit MX, receiving mail, authentication gaps, and incomplete evidence remain separate states.',
-            'Optional TLSA evidence is compared offline. A DANE match requires separately validated DNSSEC evidence from the same observation.',
             'SMTP delivery, mailbox existence, catch-all behaviour, banner collection, and message acceptance were not tested.',
+            ...(!providerCoverage.complete
+                ? ['Mail-provider relationship coverage reached a configured row, relationship, or domain bound; omitted relationships remain unknown.']
+                : []),
         ],
     };
 }
@@ -226,24 +337,25 @@ function formatCliMailReview(document) {
         `Null MX          ${document.counts.null_mx}`,
         `No explicit MX   ${document.counts.no_explicit_mx}`,
         `Incomplete       ${document.counts.evidence_incomplete + document.counts.mail_auth_incomplete}`,
-        `DANE matched     ${document.daneCounts.matched}`,
         '',
     ];
     for (const row of document.rows) {
         lines.push(`${row.domain}  ${row.state.replaceAll('_', ' ')}`);
-        lines.push(`  MX providers  ${row.providerDomains.join(', ') || 'None observed'}`);
+        lines.push(`  MX providers  ${row.providerDomains.join(', ') || 'None observed'}${row.providerDomainsOmitted ? ` · +${row.providerDomainsOmitted} omitted` : ''}`);
         lines.push(`  SPF / DMARC   ${row.hasSpf === null ? 'unknown' : row.hasSpf ? 'observed' : 'not observed'} / ${row.hasDmarc === null ? 'unknown' : row.hasDmarc ? 'observed' : 'not observed'}`);
-        lines.push(`  DANE / TLSA   ${row.dane?.state ?? 'not supplied'}`);
     }
     if (document.providerRelationships.length) {
         lines.push('', 'Shared mail-provider relationships');
         for (const relationship of document.providerRelationships) {
-            lines.push(`${relationship.providerDomain}  ${relationship.domains.join(', ')}`);
+            lines.push(`${relationship.providerDomain}  ${relationship.domains.join(', ')}${relationship.omittedDomains ? ` · +${relationship.omittedDomains} omitted` : ''}`);
         }
     }
+    if (!document.providerCoverage.complete) {
+        lines.push('', `Provider coverage partial  ${document.providerCoverage.omittedProviderDomains} row providers · ${document.providerCoverage.omittedRelationships} relationships · ${document.providerCoverage.omittedRelationshipDomains} relationship domains omitted`);
+    }
     lines.push('', 'Limitations:');
     for (const limitation of document.limitations)
         lines.push(`  - ${limitation}`);
     return `${lines.join('\n')}\n`;
 }
-export { alignMailDaneEvidence, buildCliMailReview, formatCliMailReview, mailState, normalizeMailRow };
+export { buildCliMailReview, formatCliMailReview, mailState, normalizeMailRow };

package/cli/manual.mjs

@@ -12,20 +12,20 @@ function buildCliManual(options) {
     }).join('\n');
     return `.TH WHOISLEUTH 1 "" "WHOISleuth ${roffText(options.version)}" "User Commands"
 .SH NAME
-whoisleuth \- source-aware domain investigation from the terminal
+whoisleuth \- domain investigation from the terminal
 .SH SYNOPSIS
 .B whoisleuth
-command [options]
+[command|target] [options]
 .SH DESCRIPTION
-WHOISleuth performs bounded WHOIS, RDAP, DNS, HTTP, TLS, certificate-transparency, posture, lookalike, and offline evidence operations. Evidence sources remain separately attributed, and missing or failed collection is not converted into a claim of absence or safety.
+WHOISleuth performs WHOIS, RDAP, DNS, HTTP, TLS, certificate-transparency, posture, lookalike and offline evidence operations with explicit source and collection states. With no arguments, an eligible interactive terminal opens the Lookup and command launcher; unsupported or redirected terminals print help.
 .SH COMMANDS
 ${commands}
 .SH OUTPUT
-Human-readable output is the default. Versioned JSON and JSONL are available where documented. Diagnostics and optional progress events are written to standard error. Use --output with an optional --force flag for atomic private file output.
+Human-readable output is the default. Versioned JSON and JSONL are available where documented. Diagnostics and optional progress events use standard error. Use --output and optional --force for atomic private file output. Use --palette auto, light, or dark for a fixed terminal palette. Lookup --browse provides an interactive terminal view.
 .SH EXIT STATUS
 0 indicates command completion, 2 invalid usage, 3 a collection or comparison failure, 4 an explicitly detected partial result, 70 an internal bootstrap failure, 130 analyst cancellation, and 143 service termination.
 .SH PRIVACY
-Network commands disclose the target to the directly queried upstream services. Offline commands do not make network requests. Output files are created with private permissions and are never uploaded by the CLI.
+Network commands disclose the target to the sources named in focused help. Offline commands read local input only. Output files use private permissions and remain on the operator's machine.
 .SH LICENSE
 AGPL-3.0-only. Copyright 2026 slicedearth.
 .SH SEE ALSO