@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/mail-review.mjs

@@ -1,11 +1,15 @@
 import { Buffer } from 'node:buffer';
 import { getDomain } from 'tldts';
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
-import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { compareCodeUnits } from "../lib/bounded-contract-normalizers.mjs";
+import { isValidAsciiDomainName } from "../packages/contracts/domain-name.mjs";
 import { isRecord, recordOrEmpty } from "../lib/json-record.mjs";
+import { classifyQuery } from "../lib/classify.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { PASSIVE_MAIL_INTERPRETATION, PASSIVE_MAIL_LABELS } from "../packages/contracts/passive-mail.mjs";
 export const CLI_MAIL_REVIEW_SCHEMA = 'whoisleuth.cli.mail-review';
-export const CLI_MAIL_REVIEW_VERSION = 3;
+export const CLI_MAIL_REVIEW_VERSION = 4;
 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;
@@ -20,10 +24,10 @@ function boolean(value) {
     return typeof value === 'boolean' ? value : null;
 }
 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 new Date(value).toISOString();
+    const result = normalizeExplicitIsoTimestamp(value);
+    if (!result)
+        throw new CliUsageError(`${label} must be a valid bounded timestamp with an explicit timezone.`);
+    return result;
 }
 function booleanOrNull(value, label) {
     if (value === null || typeof value === 'boolean')
@@ -87,8 +91,8 @@ function validateMxEvidence(availability, summary, label, hasMx, hasNullMx) {
 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)
+    const version = item.version;
+    if (item.schema !== 'whoisleuth.cli.bulk.item' || typeof version !== 'number' || ![2, 3].includes(version)
         || (expectedVersion !== null && version !== expectedVersion)) {
         throw new CliUsageError(`${label} must use the matching WHOISleuth Bulk item schema version 2 or 3.`);
     }
@@ -193,6 +197,7 @@ function normalizeMailRow(value) {
     const providers = providerDomains(hosts);
     return {
         domain,
+        provenance: mailRowProvenance(item),
         state,
         dnsStatus,
         hasMx,
@@ -210,6 +215,29 @@ function normalizeMailRow(value) {
         ],
     };
 }
+function mailRowProvenance(item) {
+    return Object.freeze({
+        sourceGeneratedAt: timestamp(item.generatedAt, 'Bulk row generation time'),
+        observedAt: item.version === 3 ? normalizeExplicitIsoTimestamp(item.observedAt) : null,
+        dnsObservedAt: item.ok === true ? normalizeExplicitIsoTimestamp(record(record(item.availability).dns).observedAt) : null,
+        collectionOrigin: item.version === 3
+            ? item.collectionOrigin
+            : 'unknown',
+    });
+}
+function failedMailRow(item, index) {
+    let target = null;
+    try {
+        target = classifyQuery(String(item.query)).value;
+    }
+    catch { /* Invalid targets remain identifiable by input position. */ }
+    return Object.freeze({
+        rowNumber: index + 1,
+        target,
+        state: 'collection_failed',
+        provenance: mailRowProvenance(item),
+    });
+}
 function parseInput(textValue) {
     if (typeof textValue !== 'string' || Buffer.byteLength(textValue, 'utf8') > MAX_MAIL_REVIEW_INPUT_BYTES) {
         throw new CliUsageError(`Mail review input is limited to ${MAX_MAIL_REVIEW_INPUT_BYTES} bytes.`);
@@ -223,12 +251,12 @@ function parseInput(textValue) {
         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)) {
+        if (document.schema === 'whoisleuth.cli.bulk' && typeof document.version === 'number' && [2, 3].includes(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))) {
+        else if (document.schema === 'whoisleuth.cli.bulk.item' && typeof document.version === 'number' && [2, 3].includes(document.version)) {
             values = [document];
         }
         else {
@@ -258,6 +286,13 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
     const rows = inputRows.map(normalizeMailRow).filter((row) => Boolean(row));
     if (!rows.length)
         throw new CliUsageError('Mail review input contains no completed domain results.');
+    const failedRows = inputRows.flatMap((row, index) => row.ok === false ? [failedMailRow(row, index)] : []);
+    const inputCoverage = Object.freeze({
+        inputRows: inputRows.length,
+        reviewedRows: rows.length,
+        failedRows: failedRows.length,
+        unmeasuredObservationRows: [...rows, ...failedRows].filter((row) => row.provenance.observedAt === null).length,
+    });
     const counts = {
         authenticated_mail: 0,
         evidence_incomplete: 0,
@@ -293,12 +328,16 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
             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));
+        .sort((left, right) => compareCodeUnits(left.providerDomain, right.providerDomain));
     const providerRelationships = allProviderRelationships.slice(0, 100);
+    const rowsWithIncompleteDns = rows.filter((row) => row.dnsStatus !== 'success' || row.hasMx === null || row.hasNullMx === null).length;
     const providerCoverage = {
-        complete: rows.every((row) => !row.providerDomainsTruncated)
+        complete: failedRows.length === 0 && rowsWithIncompleteDns === 0
+            && rows.every((row) => !row.providerDomainsTruncated)
             && allProviderRelationships.length <= 100
             && allProviderRelationships.every((relationship) => !relationship.domainsTruncated),
+        failedRows: failedRows.length,
+        rowsWithIncompleteDns,
         rowsWithOmittedProviders: rows.filter((row) => row.providerDomainsTruncated).length,
         omittedProviderDomains: rows.reduce((sum, row) => sum + row.providerDomainsOmitted, 0),
         relationshipCount: allProviderRelationships.length,
@@ -309,16 +348,20 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
     return {
         schema: CLI_MAIL_REVIEW_SCHEMA,
         version: CLI_MAIL_REVIEW_VERSION,
-        generatedAt,
+        generatedAt: timestamp(generatedAt, 'Mail review generation time'),
         counts,
         rows,
+        failedRows,
+        inputCoverage,
         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.',
+            PASSIVE_MAIL_INTERPRETATION,
             'SMTP delivery, mailbox existence, catch-all behaviour, banner collection, and message acceptance were not tested.',
-            ...(!providerCoverage.complete
+            ...(failedRows.length ? [`${failedRows.length} input target${failedRows.length === 1 ? '' : 's'} failed collection and cannot contribute mail evidence. Input positions and normalised targets are retained; consult the original input for failure diagnostics.`] : []),
+            ...(rowsWithIncompleteDns ? [`${rowsWithIncompleteDns} reviewed domain${rowsWithIncompleteDns === 1 ? ' has' : 's have'} incomplete DNS evidence; unobserved provider relationships remain unknown.`] : []),
+            ...(providerCoverage.rowsWithOmittedProviders || providerCoverage.omittedRelationships || providerCoverage.omittedRelationshipDomains
                 ? ['Mail-provider relationship coverage reached a configured row, relationship, or domain bound; omitted relationships remain unknown.']
                 : []),
         ],
@@ -327,19 +370,30 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
 function formatCliMailReview(document) {
     const lines = [
         'Passive mail exposure review',
+        `Input targets    ${document.inputCoverage.inputRows}`,
         `Domains          ${document.rows.length}`,
-        `Authenticated    ${document.counts.authenticated_mail}`,
-        `Auth gaps        ${document.counts.mail_auth_gap}`,
+        `Failed targets   ${document.inputCoverage.failedRows}`,
+        `MX + SPF + DMARC ${document.counts.authenticated_mail}`,
+        `DNS policy gaps  ${document.counts.mail_auth_gap}`,
         `Null MX          ${document.counts.null_mx}`,
         `No explicit MX   ${document.counts.no_explicit_mx}`,
-        `Incomplete       ${document.counts.evidence_incomplete + document.counts.mail_auth_incomplete}`,
+        `Incomplete       ${document.counts.evidence_incomplete + document.counts.mail_auth_incomplete + document.inputCoverage.failedRows}`,
         '',
     ];
     for (const row of document.rows) {
-        lines.push(`${row.domain}  ${row.state.replaceAll('_', ' ')}`);
+        lines.push(`${row.domain}  ${PASSIVE_MAIL_LABELS[row.state]}`);
+        lines.push(`  Observed      ${row.provenance.observedAt ?? 'unknown'} · ${row.provenance.collectionOrigin.replaceAll('_', ' ')}`);
+        lines.push(`  DNS observed  ${row.provenance.dnsObservedAt ?? 'unknown'} · Source output ${row.provenance.sourceGeneratedAt}`);
         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'}`);
     }
+    if (document.failedRows.length) {
+        lines.push('', 'Failed collection inputs');
+        for (const row of document.failedRows) {
+            lines.push(`Input ${row.rowNumber}  ${row.target ?? 'unrecognised target'} · collection failed`);
+            lines.push(`  Observed      ${row.provenance.observedAt ?? 'unknown'} · ${row.provenance.collectionOrigin.replaceAll('_', ' ')} · Source output ${row.provenance.sourceGeneratedAt}`);
+        }
+    }
     if (document.providerRelationships.length) {
         lines.push('', 'Shared mail-provider relationships');
         for (const relationship of document.providerRelationships) {
@@ -347,7 +401,7 @@ function formatCliMailReview(document) {
         }
     }
     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('', `Provider coverage partial  ${document.providerCoverage.failedRows} failed targets · ${document.providerCoverage.rowsWithIncompleteDns} incomplete DNS rows · ${document.providerCoverage.omittedProviderDomains} row providers · ${document.providerCoverage.omittedRelationships} relationships · ${document.providerCoverage.omittedRelationshipDomains} relationship domains omitted`);
     }
     lines.push('', 'Limitations:');
     for (const limitation of document.limitations)

package/cli/manual.mjs

@@ -24,6 +24,7 @@ ${commands}
 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.
+For verify-artifact, use --strict-exit in scripts: incomplete verification then returns 4. Without it, producing a verification report can return 0 even when its checks fail. Read the report state and checks.
 .SH PRIVACY
 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

package/cli/network-arguments.mjs

@@ -0,0 +1,51 @@
+import {} from "./command-argument-grammar.mjs";
+import { commandDefaultText } from "./command-reference.mjs";
+import { NETWORK_COMMAND_DEFINITIONS } from "./network-command-definitions.mjs";
+import { terminalOptions, jsonOutput, parseOutput, singleInputAction, } from "./argument-values.mjs";
+function parsePostureArguments(parsed) {
+    const mailProfile = parsed.optionValue('--mail-profile') ?? commandDefaultText('posture', '--mail-profile');
+    return {
+        action: 'posture',
+        domain: parsed.positionalValue('domain'),
+        output: parseOutput(parsed, NETWORK_COMMAND_DEFINITIONS.posture),
+        selectorText: parsed.optionValue('--selectors'),
+        retiredSelectorText: parsed.optionValue('--retired-selectors'),
+        mailProfile: mailProfile === 'defensive-no-mail'
+            ? 'defensive_no_mail'
+            : mailProfile,
+        ownedDomain: parsed.hasOption('--owned-domain'),
+        ...(parsed.hasOption('--include-inherited-dns') ? { includeInheritedDns: true } : {}),
+        ...terminalOptions(parsed),
+    };
+}
+function parseDnssecValidateArguments(parsed) {
+    return {
+        action: 'dnssec-validate',
+        target: parsed.positionalValue('domain'),
+        resolver: parsed.optionValue('--resolver'),
+        trustAnchorSource: parsed.optionValue('--trust-anchor'),
+        ownedOrAuthorized: true,
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    };
+}
+function parseMailTransportArguments(parsed) {
+    return {
+        action: 'mail-transport',
+        source: parsed.positionalValue('source'),
+        resolver: parsed.optionValue('--resolver'),
+        trustAnchorSource: parsed.optionValue('--trust-anchor'),
+        ownedOrAuthorized: true,
+        activeProbeAcknowledged: true,
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    };
+}
+export const NETWORK_ARGUMENT_PARSERS = Object.freeze({
+    'ct-search': (parsed) => singleInputAction('ct-search', parsed, 'keyword'),
+    posture: parsePostureArguments,
+    http: (parsed) => singleInputAction('http', parsed, 'domain'),
+    tls: (parsed) => singleInputAction('tls', parsed, 'hostname'),
+    'dnssec-validate': parseDnssecValidateArguments,
+    'mail-transport': parseMailTransportArguments,
+});

package/cli/network-command-definitions.mjs

@@ -0,0 +1,130 @@
+import { positional, OPTIONAL_FILE_POSITIONAL, constraint, EMPTY_CONSTRAINTS, commandSeed } from "./command-definition.mjs";
+export const NETWORK_COMMAND_DEFINITIONS = Object.freeze({
+    "ct-search": commandSeed({
+        reference: {
+            description: 'Search certificate-transparency observations for one bounded keyword.',
+            example: 'whoisleuth ct-search "example brand" --json',
+            boundary: 'Certificate observations do not prove website activity, registration ownership, or malicious intent.',
+        },
+        collection: { scope: 'Accepts one bounded search keyword and queries the fixed certificate-transparency source.' },
+        summary: 'Search certificate observations',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('keyword', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.ct-search']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    posture: commandSeed({
+        reference: {
+            description: 'Review bounded DNS mail, delegation, and domain-control posture.',
+            example: 'whoisleuth posture example.test --mail-profile standard --json',
+            boundary: 'Missing or failed DNS observations remain inconclusive. --include-inherited-dns adds inherited policy and reporting-boundary reviews within 32 additional TXT queries and ten seconds, plus a direct parent-delegation sample. No message is sent and receiver enforcement is not inferred.',
+        },
+        collection: { scope: 'Accepts one domain and performs bounded RDAP, DNS, and conditional MTA-STS HTTPS requests. --include-inherited-dns separately adds ancestor and reporting-destination DMARC questions and direct DNS/TCP to sampled parent servers.' },
+        summary: 'Review DNS and mail posture',
+        options: ['--selectors', '--retired-selectors', '--mail-profile', '--include-inherited-dns', '--json', '--sarif', '--owned-domain', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('domain', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: Object.freeze([
+            constraint({ kind: 'mutually_exclusive', options: ['--json', '--sarif'] }),
+            constraint({ kind: 'requires_all', option: '--sarif', requiredOptions: ['--owned-domain'] }),
+        ]),
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.posture']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    http: commandSeed({
+        reference: {
+            description: 'Inspect one homepage request, redirects, and bounded response metadata.',
+            example: 'whoisleuth http example.test --json',
+            boundary: 'Requests use the shared public-address and redirect guards. Fixed content-coding and cache-policy metadata describes only the selected response, excludes raw header values, and does not prove caching, transfer savings, performance, privacy, or safety. This is not a rendered browser or vulnerability scan.',
+        },
+        collection: { scope: 'Accepts one domain and follows only the bounded SSRF-guarded homepage redirect workflow.' },
+        summary: 'Inspect one homepage request',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('domain', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.http']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    tls: commandSeed({
+        reference: {
+            description: 'Inspect one hostname certificate through a bounded TLS connection.',
+            example: 'whoisleuth tls example.test --json',
+            boundary: 'One observed connection is point-in-time evidence and does not establish every address, edge, or historical certificate.',
+        },
+        collection: { scope: 'Accepts one public hostname and opens one bounded certificate connection.' },
+        summary: 'Inspect one TLS connection',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('hostname', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.tls']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "dnssec-validate": commandSeed({
+        reference: {
+            description: 'Cryptographically validate one authorised DNSSEC chain from a supplied trust anchor through one selected public resolver.',
+            example: 'whoisleuth dnssec-validate example.test --resolver "$PUBLIC_RESOLVER_IP" --trust-anchor anchor.json --owned-or-authorized --json',
+            boundary: 'This isolated action is never invoked by Lookup, Bulk, monitoring, or recipes. It caps DNS queries, aliases, delegations, bytes, and duration; transport and validation failures remain separate, and secure is not a general safety verdict.',
+        },
+        collection: { scope: 'Accepts one authorised domain, one public resolver IP, and one local trust-anchor file; DNS-over-TCP validation is capped at 32 queries and 15 seconds.' },
+        summary: 'Validate an authorised DNSSEC chain',
+        options: ['--resolver', '--trust-anchor', '--owned-or-authorized', '--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('domain', 'text', 1, 1)]),
+        constraints: Object.freeze([
+            constraint({ kind: 'required', options: ['--resolver', '--trust-anchor', '--owned-or-authorized'] }),
+        ]),
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.dnssec-chain-validation', 'whoisleuth.dnssec-trust-anchor']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "mail-transport": commandSeed({
+        reference: {
+            description: 'Review selected authorised MX endpoints, DNSSEC-qualified TLSA evidence, SMTP capabilities, and optional STARTTLS certificates.',
+            example: 'whoisleuth mail-transport selected-mx.json --resolver "$PUBLIC_RESOLVER_IP" --trust-anchor anchor.json --owned-or-authorized --active-probe --json',
+            boundary: 'This isolated action probes at most three selected MX hosts sequentially, reports selection, public revalidation, connection, and address authentication separately, sends only EHLO and optional STARTTLS, never retries, and performs no authentication, relay, recipient, mailbox, catch-all, or message test. If a DANE-TA TLSA usage 2 association is published, active collection retains only the leaf certificate and leaves that comparison partial without certificate-path construction and trust-anchor path validation. SMTP relay PKIX-TA usage 0 and PKIX-EE usage 1 records remain unsupported and cannot complete SMTP DANE assurance; a separate usage 3 match remains eligible.',
+        },
+        collection: { scope: 'Accepts at most three selected authorised MX hosts, uses one public resolver, and performs sequential bounded SMTP connections with no retries.' },
+        summary: 'Review selected authorised SMTP transports',
+        options: ['--resolver', '--trust-anchor', '--owned-or-authorized', '--active-probe', '--json', '--quiet', '--no-color'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'required', options: ['--resolver', '--trust-anchor', '--owned-or-authorized', '--active-probe'] }),
+        ]),
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.mail-transport.input', 'whoisleuth.cli.mail-transport-review']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/network-command-runner.mjs

@@ -1,6 +1,7 @@
+import { runDiscriminatedCommandHandler, } from "./discriminated-command-handlers.mjs";
 import { fetchHomepage } from "../lib/availability.mjs";
 import { searchCertificateTransparency } from "../lib/ct-search.mjs";
-import { checkDomainPosture, normalizeAuditDomain, normalizeDkimSelectors } from "../lib/domain-posture.mjs";
+import { checkDomainPosture, normalizeAuditDomain, normalizeDkimSelectors, } from "../lib/domain-posture.mjs";
 import { collectTlsIntelligence, normalizeTlsHostname } from "../lib/tls-intelligence.mjs";
 import { MAX_DNSSEC_TRUST_ANCHOR_BYTES, formatDnssecChainReport, validateDnssecChain, } from "../lib/dnssec-chain-validation.mjs";
 import { MAX_MAIL_TRANSPORT_INPUT_BYTES, collectMailTransportReview, formatMailTransportReview, } from "../lib/smtp-transport-review.mjs";
@@ -11,9 +12,10 @@ import { buildHttpProbeResult } from "./http.mjs";
 import { normalizePostureSelectors } from "./posture.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { buildPostureSarif } from "./ci-report.mjs";
-async function runNetworkCommand(args, dependencies, context) {
-    if (args.action === 'ct-search') {
-        const keyword = args.keyword || await context.readSingleInput();
+const networkCommandHandlers = {
+    'ct-search': async (args, dependencies, context) => {
+        context.setFailureLabel('Certificate Transparency search');
+        const keyword = args.keyword || (await context.readSingleInput());
         if (!keyword)
             throw new CliUsageError('ct-search requires one keyword as an argument or on stdin.');
         const search = dependencies.searchCertificateTransparency || searchCertificateTransparency;
@@ -25,9 +27,10 @@ async function runNetworkCommand(args, dependencies, context) {
                 : context.terminal(formatTerminalCtSearch(document), args.color));
         }
         return EXIT_CODES.SUCCESS;
-    }
-    if (args.action === 'posture') {
-        const requestedDomain = args.domain || await context.readSingleInput();
+    },
+    posture: async (args, dependencies, context) => {
+        context.setFailureLabel('Domain posture audit');
+        const requestedDomain = args.domain || (await context.readSingleInput());
         if (!requestedDomain)
             throw new CliUsageError('posture requires one domain as an argument or on stdin.');
         const normalizeDomain = dependencies.normalizeAuditDomain || normalizeAuditDomain;
@@ -44,6 +47,8 @@ async function runNetworkCommand(args, dependencies, context) {
             dkimSelectors,
             retiredDkimSelectors,
             mailProtectionProfile: args.mailProfile,
+            ...(args.includeInheritedDns ? { includeInheritedDns: true } : {}),
+            ...(dependencies.signal ? { signal: dependencies.signal } : {}),
         }));
         const document = buildCliPostureDocument(requestedDomain, report, context.now());
         if (!args.quiet) {
@@ -54,9 +59,10 @@ async function runNetworkCommand(args, dependencies, context) {
                     : context.terminal(formatTerminalPosture(document), args.color));
         }
         return EXIT_CODES.SUCCESS;
-    }
-    if (args.action === 'http') {
-        const requestedDomain = args.domain || await context.readSingleInput();
+    },
+    http: async (args, dependencies, context) => {
+        context.setFailureLabel('HTTP probe');
+        const requestedDomain = args.domain || (await context.readSingleInput());
         if (!requestedDomain)
             throw new CliUsageError('http requires one domain as an argument or on stdin.');
         const normalizeDomain = dependencies.normalizeAuditDomain || normalizeAuditDomain;
@@ -72,8 +78,9 @@ async function runNetworkCommand(args, dependencies, context) {
                 : context.terminal(formatTerminalHttp(document), args.color));
         }
         return EXIT_CODES.SUCCESS;
-    }
-    if (args.action === 'dnssec-validate') {
+    },
+    'dnssec-validate': async (args, dependencies, context) => {
+        context.setFailureLabel('DNSSEC chain validation');
         let anchorInput;
         try {
             anchorInput = dependencies.readTrustAnchorInput
@@ -101,8 +108,9 @@ async function runNetworkCommand(args, dependencies, context) {
         return report.state === 'secure' || report.state === 'insecure'
             ? EXIT_CODES.SUCCESS
             : EXIT_CODES.PARTIAL_FAILURE;
-    }
-    if (args.action === 'mail-transport') {
+    },
+    'mail-transport': async (args, dependencies, context) => {
+        context.setFailureLabel('Mail transport review');
         let input;
         let anchorInput;
         try {
@@ -148,22 +156,28 @@ async function runNetworkCommand(args, dependencies, context) {
                 : context.terminal(formatMailTransportReview(review), args.color));
         }
         return review.runState === 'complete' ? EXIT_CODES.SUCCESS : EXIT_CODES.PARTIAL_FAILURE;
-    }
-    const requestedHostname = args.hostname || await context.readSingleInput();
-    if (!requestedHostname)
-        throw new CliUsageError('tls requires one hostname as an argument or on stdin.');
-    const normalizeHostname = dependencies.normalizeTlsHostname || normalizeTlsHostname;
-    const hostname = normalizeHostname(requestedHostname);
-    if (!hostname)
-        throw new CliUsageError('tls requires a valid DNS hostname, not an IP address.');
-    const collect = dependencies.collectTlsIntelligence || collectTlsIntelligence;
-    const result = await context.withProgress('Inspecting the current TLS connection', () => collect(hostname));
-    const document = buildCliTlsDocument(requestedHostname, result, context.now());
-    if (!args.quiet) {
-        context.writeStdout(args.output === 'json'
-            ? formatJsonDocument(document)
-            : context.terminal(formatTerminalTls(document), args.color));
-    }
-    return EXIT_CODES.SUCCESS;
+    },
+    tls: async (args, dependencies, context) => {
+        context.setFailureLabel('TLS evidence collection');
+        const requestedHostname = args.hostname || (await context.readSingleInput());
+        if (!requestedHostname)
+            throw new CliUsageError('tls requires one hostname as an argument or on stdin.');
+        const normalizeHostname = dependencies.normalizeTlsHostname || normalizeTlsHostname;
+        const hostname = normalizeHostname(requestedHostname);
+        if (!hostname)
+            throw new CliUsageError('tls requires a valid DNS hostname, not an IP address.');
+        const collect = dependencies.collectTlsIntelligence || collectTlsIntelligence;
+        const result = await context.withProgress('Inspecting the current TLS connection', () => collect(hostname));
+        const document = buildCliTlsDocument(requestedHostname, result, context.now());
+        if (!args.quiet) {
+            context.writeStdout(args.output === 'json'
+                ? formatJsonDocument(document)
+                : context.terminal(formatTerminalTls(document), args.color));
+        }
+        return EXIT_CODES.SUCCESS;
+    },
+};
+async function runNetworkCommand(args, dependencies, context) {
+    return runDiscriminatedCommandHandler(networkCommandHandlers, args, dependencies, context);
 }
 export { runNetworkCommand };

package/cli/offline-evidence-review.mjs

@@ -1,5 +1,7 @@
 import { Buffer } from 'node:buffer';
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { CONTEXT_INPUT_SCHEMAS, reviewContextInput } from "../packages/investigation/context-review.mjs";
+import { CONTEXT_REVIEW_KINDS } from "../packages/contracts/context-review.mjs";
 import { normalizeEncryptedDnsAdapter, planEncryptedDnsQuery, } from "../lib/encrypted-dns-contract.mjs";
 import { validateDnssecEvidence } from "../lib/dnssec-evidence-validation.mjs";
 import { reviewDomainChange } from "../lib/domain-change-review.mjs";
@@ -15,7 +17,7 @@ import { reviewDnsConvergence } from "../lib/dns-convergence-review.mjs";
 import { compareTrustStoreEvidence } from "../lib/trust-store-comparison.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
-import { LOCAL_MMDB_QUERY_SCHEMA, reviewLocalMmdb } from "./local-mmdb-review.mjs";
+import { LOCAL_MMDB_QUERY_SCHEMA, LOCAL_MMDB_QUERY_VERSION, LOCAL_MMDB_REVIEW_SCHEMA, LOCAL_MMDB_REVIEW_VERSION, reviewLocalMmdb } from "./local-mmdb-review.mjs";
 const OFFLINE_EVIDENCE_REVIEW_SCHEMA = 'whoisleuth.cli.offline-evidence-review';
 const OFFLINE_EVIDENCE_REVIEW_VERSION = 1;
 const MAX_OFFLINE_EVIDENCE_INPUT_BYTES = 16 * 1024 * 1024;
@@ -43,16 +45,24 @@ function parseInput(value) {
         throw new CliUsageError('Offline evidence review requires one valid bounded JSON document without duplicate keys.');
     }
     const document = record(parsed);
-    if (document.version !== 1 || typeof document.schema !== 'string') {
+    if (typeof document.schema !== 'string' || document.version !== 1
+        && !(document.schema === LOCAL_MMDB_QUERY_SCHEMA && document.version === LOCAL_MMDB_QUERY_VERSION)) {
         throw new CliUsageError('Offline evidence review requires a supported versioned input schema.');
     }
     return document;
 }
 function buildOfflineEvidenceReview(value, generatedAt = new Date().toISOString()) {
     const input = parseInput(value);
+    if (input.schema === LOCAL_MMDB_QUERY_SCHEMA)
+        throw new CliUsageError('Local MMDB review requires --mmdb <database-file>.');
     let kind;
     let result;
-    if (input.schema === RDAP_SEARCH_INPUT_SCHEMA) {
+    if (CONTEXT_INPUT_SCHEMAS.includes(input.schema)) {
+        const review = reviewContextInput(input, generatedAt);
+        kind = review.kind;
+        result = review;
+    }
+    else if (input.schema === RDAP_SEARCH_INPUT_SCHEMA) {
         kind = 'rdap_search';
         const request = record(input.request);
         const help = normalizeRdapSearchHelp(input.help);
@@ -163,7 +173,7 @@ async function buildOfflineEvidenceReviewWithLocalResources(value, generatedAt =
         version: OFFLINE_EVIDENCE_REVIEW_VERSION,
         generatedAt,
         kind: 'geoip',
-        result: await reviewLocalMmdb(input, options.mmdbPath),
+        result: await reviewLocalMmdb(input, options.mmdbPath, generatedAt),
         limitations: Object.freeze([
             'The review is local and uses only the supplied query metadata and analyst-supplied database. It does not transmit the address or refresh the database.',
         ]),
@@ -171,6 +181,9 @@ async function buildOfflineEvidenceReviewWithLocalResources(value, generatedAt =
 }
 function formatOfflineEvidenceReview(document) {
     const result = record(document.result);
+    if (document.kind === 'geoip' && result.schema === LOCAL_MMDB_REVIEW_SCHEMA && result.version !== LOCAL_MMDB_REVIEW_VERSION) {
+        throw new CliUsageError('Offline evidence review does not support this MMDB result version.');
+    }
     const gate = record(result.gate);
     const counts = record(result.counts);
     const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -191,7 +204,16 @@ function formatOfflineEvidenceReview(document) {
         `Kind   ${document.kind.replaceAll('_', ' ')}`,
         `State  ${state.replaceAll('_', ' ')}`,
     ];
-    if (document.kind === 'rdap_search') {
+    if (CONTEXT_REVIEW_KINDS.includes(document.kind)) {
+        lines.push(safeTerminalValue(result.summary, ''));
+        for (const item of Array.isArray(result.observations) ? result.observations : []) {
+            const row = record(item);
+            lines.push('', `${safeTerminalValue(row.label, 'Observation')} [${safeTerminalValue(row.state, 'unknown')}]`, `  ${safeTerminalValue(row.detail, '')}`, `  Source: ${safeTerminalValue(row.source, '')} · ${safeTerminalValue(row.observedAt, 'time unknown')}`);
+        }
+        for (const step of Array.isArray(result.nextSteps) ? result.nextSteps : [])
+            lines.push(`Next: ${safeTerminalValue(step, '')}`);
+    }
+    else if (document.kind === 'rdap_search') {
         const help = record(result.help);
         const plan = record(result.plan);
         const responseInspection = record(result.responseInspection);
@@ -200,6 +222,17 @@ function formatOfflineEvidenceReview(document) {
         if (result.responseInspection !== null)
             lines.push(`Result ${String(responseInspection.state ?? 'invalid').replaceAll('_', ' ')}`);
     }
+    else if (document.kind === 'geoip' && result.schema === LOCAL_MMDB_REVIEW_SCHEMA && result.version === LOCAL_MMDB_REVIEW_VERSION) {
+        const database = record(result.database), metadata = record(database.metadata), binaryFormat = record(metadata.binaryFormat);
+        const freshness = record(result.freshness), policy = record(freshness.policy), source = record(result.source), match = record(result.match);
+        lines.push(`Outcome ${safeTerminalValue(result.reason, 'unknown').replaceAll('_', ' ')}`, `Coverage ${safeTerminalValue(result.completeness, 'unavailable')}`, `Database SHA-256 ${safeTerminalValue(database.sha256, 'unavailable')}`, `Database bytes ${safeTerminalValue(database.byteLength, 'unavailable')}`, `Intrinsic type ${safeTerminalValue(metadata.databaseType, 'unavailable')}`, `Built ${safeTerminalValue(metadata.builtAt, 'unavailable')}`, `Binary format ${safeTerminalValue(binaryFormat.major, '?')}.${safeTerminalValue(binaryFormat.minor, '?')} · IP version ${safeTerminalValue(metadata.ipVersion, '?')}`, `Freshness ${safeTerminalValue(freshness.state, 'unknown')} · checked ${safeTerminalValue(freshness.checkedAt, 'unknown')}`, `Age policy ${safeTerminalValue(policy.maxAgeDays, '?')} days · ${safeTerminalValue(policy.rationale, '')}`, `Declared source ${safeTerminalValue(source.label, 'unknown')} · version ${safeTerminalValue(source.version, 'unknown')} · licence ${safeTerminalValue(source.license, 'unknown')}`);
+        if (result.match !== null) {
+            lines.push(`Matched network ${safeTerminalValue(match.network, 'unknown')}`, `Country ${safeTerminalValue(match.countryCode, 'unknown')} · region ${safeTerminalValue(match.region, 'unknown')} · city ${safeTerminalValue(match.city, 'unknown')}`, `ASN ${safeTerminalValue(match.asn, 'unknown')} · network label ${safeTerminalValue(match.asName, 'unknown')}`);
+        }
+    }
+    else if (document.kind === 'geoip') {
+        lines.push('Intrinsic MMDB freshness is not assessed by this result. A version-2 MMDB query can assess a selected local database against an explicit age policy.');
+    }
     else if (document.kind === 'zone_intent') {
         const desired = record(result.desired);
         lines.push(`Desired ${listLength(desired.records)}`);