@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/cli/mail-header-review.mjs

@@ -0,0 +1,467 @@
+import { createHash } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const CLI_MAIL_HEADER_REVIEW_SCHEMA = 'whoisleuth.cli.mail-header-review';
+export const CLI_MAIL_HEADER_REVIEW_VERSION = 1;
+export const MAX_MAIL_HEADER_INPUT_BYTES = 256 * 1024;
+export const MAX_MAIL_HEADER_FIELDS = 512;
+export const MAX_MAIL_HEADER_LINE_BYTES = 4 * 1024;
+export const MAX_MAIL_HEADER_VALUE_LENGTH = 16 * 1024;
+export const MAX_MAIL_RECEIVED_HOPS = 64;
+export const MAX_MAIL_REVIEW_DOMAINS = 128;
+const UNSAFE_HEADER_CONTROL_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2060-\u206f]/u;
+const HEADER_NAME_RE = /^[A-Za-z0-9-]{1,78}$/u;
+const AUTHENTICATION_METHODS = Object.freeze(['spf', 'dkim', 'dmarc', 'arc']);
+const AUTHENTICATION_STATES = new Set(['fail', 'neutral', 'none', 'pass', 'permerror', 'softfail', 'temperror']);
+function boundedHeaderSection(value) {
+    if (typeof value !== 'string' || !value)
+        throw new CliUsageError('Mail-header review requires one UTF-8 message or header block.');
+    const candidate = value.slice(0, MAX_MAIL_HEADER_INPUT_BYTES * 2 + 4);
+    const crlf = candidate.indexOf('\r\n\r\n');
+    const lf = candidate.indexOf('\n\n');
+    const separator = crlf < 0 ? lf : lf < 0 ? crlf : Math.min(crlf, lf);
+    const header = separator >= 0 ? candidate.slice(0, separator) : candidate;
+    const bytes = Buffer.byteLength(header, 'utf8');
+    if (bytes < 1 || bytes > MAX_MAIL_HEADER_INPUT_BYTES || (separator < 0 && value.length > candidate.length)) {
+        throw new CliUsageError(`Mail headers are limited to ${MAX_MAIL_HEADER_INPUT_BYTES} bytes before the message body.`);
+    }
+    return header;
+}
+function parseHeaderFields(value) {
+    const header = boundedHeaderSection(value);
+    const physicalLines = header.split(/\r\n|\n/u);
+    if (physicalLines.at(-1) === '')
+        physicalLines.pop();
+    const fields = [];
+    for (const [index, line] of physicalLines.entries()) {
+        if (Buffer.byteLength(line, 'utf8') > MAX_MAIL_HEADER_LINE_BYTES) {
+            throw new CliUsageError(`Mail header line ${index + 1} exceeds the ${MAX_MAIL_HEADER_LINE_BYTES}-byte limit.`);
+        }
+        if (UNSAFE_HEADER_CONTROL_RE.test(line))
+            throw new CliUsageError(`Mail header line ${index + 1} contains unsafe control characters.`);
+        if (/^[ \t]/u.test(line)) {
+            const previous = fields.at(-1);
+            if (!previous)
+                throw new CliUsageError('Mail headers contain a continuation without a preceding field.');
+            const continuation = line.trim();
+            const combined = continuation ? `${previous.value} ${continuation}` : previous.value;
+            if (combined.length > MAX_MAIL_HEADER_VALUE_LENGTH)
+                throw new CliUsageError(`Mail header ${previous.name} exceeds its unfolded value limit.`);
+            previous.value = combined;
+            continue;
+        }
+        const separator = line.indexOf(':');
+        if (separator < 1)
+            throw new CliUsageError(`Mail header line ${index + 1} is malformed.`);
+        const name = line.slice(0, separator);
+        const fieldValue = line.slice(separator + 1).trim();
+        if (!HEADER_NAME_RE.test(name))
+            throw new CliUsageError(`Mail header line ${index + 1} has an invalid field name.`);
+        if (fieldValue.length > MAX_MAIL_HEADER_VALUE_LENGTH)
+            throw new CliUsageError(`Mail header ${name} exceeds its unfolded value limit.`);
+        fields.push({ name: name.toLowerCase(), value: fieldValue });
+        if (fields.length > MAX_MAIL_HEADER_FIELDS)
+            throw new CliUsageError(`Mail headers contain more than ${MAX_MAIL_HEADER_FIELDS} fields.`);
+    }
+    if (!fields.length)
+        throw new CliUsageError('Mail-header review did not find any header fields.');
+    return Object.freeze({
+        fields: Object.freeze(fields.map((field) => Object.freeze({ ...field }))),
+        bytes: Buffer.byteLength(header, 'utf8'),
+    });
+}
+function fieldsNamed(fields, name) {
+    return fields.filter((field) => field.name === name).map((field) => field.value);
+}
+function normalizeHeaderDomain(value) {
+    const normalized = value.trim().toLowerCase().replace(/^\[|\]$/gu, '').replace(/\.$/u, '');
+    return isValidAsciiDomainName(normalized, { requireLowercase: true }) ? normalized : null;
+}
+function lexicalSegments(value, delimiter, trackAngles = false) {
+    const segments = [];
+    let start = 0;
+    let quoted = false;
+    let escaped = false;
+    let commentDepth = 0;
+    let angleDepth = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index] ?? '';
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === '\\' && (quoted || commentDepth > 0)) {
+            escaped = true;
+            continue;
+        }
+        if (commentDepth > 0) {
+            if (character === '(')
+                commentDepth += 1;
+            else if (character === ')')
+                commentDepth -= 1;
+            continue;
+        }
+        if (quoted) {
+            if (character === '"')
+                quoted = false;
+            continue;
+        }
+        if (character === '"')
+            quoted = true;
+        else if (character === '(')
+            commentDepth = 1;
+        else if (character === ')')
+            return null;
+        else if (trackAngles && character === '<') {
+            if (angleDepth !== 0)
+                return null;
+            angleDepth = 1;
+        }
+        else if (trackAngles && character === '>') {
+            if (angleDepth !== 1)
+                return null;
+            angleDepth = 0;
+        }
+        else if (character === delimiter && angleDepth === 0) {
+            segments.push(value.slice(start, index));
+            start = index + 1;
+        }
+    }
+    if (escaped || quoted || commentDepth !== 0 || angleDepth !== 0)
+        return null;
+    segments.push(value.slice(start));
+    return segments;
+}
+function angleAddress(value) {
+    let quoted = false;
+    let escaped = false;
+    let commentDepth = 0;
+    let start = -1;
+    let end = -1;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index] ?? '';
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === '\\' && (quoted || commentDepth > 0)) {
+            escaped = true;
+            continue;
+        }
+        if (commentDepth > 0) {
+            if (character === '(')
+                commentDepth += 1;
+            else if (character === ')')
+                commentDepth -= 1;
+            continue;
+        }
+        if (quoted) {
+            if (character === '"')
+                quoted = false;
+            continue;
+        }
+        if (character === '"')
+            quoted = true;
+        else if (character === '(')
+            commentDepth = 1;
+        else if (character === ')')
+            return null;
+        else if (character === '<') {
+            if (start >= 0 || end >= 0)
+                return null;
+            start = index;
+        }
+        else if (character === '>') {
+            if (start < 0 || end >= 0)
+                return null;
+            end = index;
+        }
+    }
+    if (escaped || quoted || commentDepth !== 0 || (start >= 0) !== (end >= 0))
+        return null;
+    return start >= 0 ? value.slice(start + 1, end) : value;
+}
+function addressDomain(value) {
+    let candidate = '';
+    let quoted = false;
+    let escaped = false;
+    let commentDepth = 0;
+    const separators = [];
+    for (const character of value) {
+        if (escaped) {
+            candidate += character;
+            escaped = false;
+            continue;
+        }
+        if (character === '\\' && (quoted || commentDepth > 0)) {
+            if (quoted)
+                candidate += character;
+            escaped = true;
+            continue;
+        }
+        if (commentDepth > 0) {
+            if (character === '(')
+                commentDepth += 1;
+            else if (character === ')')
+                commentDepth -= 1;
+            continue;
+        }
+        if (quoted) {
+            candidate += character;
+            if (character === '"')
+                quoted = false;
+            continue;
+        }
+        if (character === '"') {
+            quoted = true;
+            candidate += character;
+        }
+        else if (character === '(')
+            commentDepth = 1;
+        else if (character === ')')
+            return null;
+        else {
+            if (character === '@')
+                separators.push(candidate.length);
+            candidate += character;
+        }
+    }
+    if (escaped || quoted || commentDepth !== 0 || separators.length !== 1)
+        return null;
+    const separator = separators[0] ?? -1;
+    const local = candidate.slice(0, separator).trim();
+    const domain = candidate.slice(separator + 1).trim();
+    const validLocal = /^(?:[^\s"<>(),:;@]+|"(?:[^"\\]|\\.)+")$/u.test(local);
+    if (!validLocal || !domain || /\s/u.test(domain))
+        return null;
+    return normalizeHeaderDomain(domain);
+}
+function addressDomains(values) {
+    const domains = new Set();
+    for (const value of values) {
+        const mailboxes = lexicalSegments(value, ',', true);
+        if (!mailboxes)
+            continue;
+        for (const mailbox of mailboxes) {
+            const selected = angleAddress(mailbox);
+            const domain = selected === null ? null : addressDomain(selected);
+            if (domain)
+                domains.add(domain);
+            if (domains.size >= MAX_MAIL_REVIEW_DOMAINS)
+                return [...domains].sort();
+        }
+    }
+    return [...domains].sort();
+}
+function messageIdDomains(values) {
+    return addressDomains(values.map((value) => value.replace(/[<>]/gu, '')));
+}
+function authenticationState(values, method, directValues = []) {
+    const states = new Set();
+    let observations = 0;
+    for (const value of values) {
+        const clauses = lexicalSegments(value, ';');
+        if (!clauses)
+            continue;
+        for (const clause of clauses) {
+            const match = /^\s*([a-z][a-z0-9_-]*)\s*=\s*([a-z0-9_-]+)(?=\s|$)/iu.exec(clause);
+            if (match?.[1]?.toLowerCase() === method) {
+                observations += 1;
+                const raw = (match[2] ?? '').toLowerCase();
+                states.add(AUTHENTICATION_STATES.has(raw) ? raw : 'unknown');
+            }
+        }
+    }
+    for (const value of directValues) {
+        const match = /^\s*([a-z0-9_-]+)(?=\s|\(|$)/iu.exec(value);
+        const raw = (match?.[1] ?? '').toLowerCase();
+        if (!raw)
+            continue;
+        observations += 1;
+        states.add(AUTHENTICATION_STATES.has(raw) ? raw : 'unknown');
+    }
+    return Object.freeze({
+        state: observations === 0 ? 'unknown' : states.size === 1 ? [...states][0] : 'mixed',
+        observations,
+    });
+}
+function authenticationServiceDomains(values) {
+    const output = new Set();
+    for (const value of values) {
+        const clauses = lexicalSegments(value, ';');
+        const service = normalizeHeaderDomain((clauses?.[0] ?? '').trim().split(/\s/u, 1)[0] ?? '');
+        if (service)
+            output.add(service);
+    }
+    return [...output].sort().slice(0, MAX_MAIL_REVIEW_DOMAINS);
+}
+function dkimSigningDomains(values) {
+    const output = new Set();
+    for (const value of values) {
+        for (const clause of lexicalSegments(value, ';') ?? []) {
+            const match = /^\s*d\s*=\s*([^\s;]+)/iu.exec(clause);
+            const domain = normalizeHeaderDomain(match?.[1] ?? '');
+            if (domain)
+                output.add(domain);
+        }
+    }
+    return [...output].sort().slice(0, MAX_MAIL_REVIEW_DOMAINS);
+}
+function reportedDate(values) {
+    if (values.length !== 1 || values[0].length > 240)
+        return null;
+    const parsed = Date.parse(values[0]);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function receivedHost(value, keyword) {
+    const expression = keyword === 'from' ? /(?:^|\s)from\s+([^\s(;]+)/iu : /(?:^|\s)by\s+([^\s(;]+)/iu;
+    const match = expression.exec(value);
+    return normalizeHeaderDomain(match?.[1] ?? '');
+}
+function receivedTransport(value) {
+    const match = /(?:^|\s)with\s+([A-Za-z0-9_-]{1,40})/iu.exec(value);
+    return match?.[1]?.toUpperCase() ?? null;
+}
+function receivedTimestamp(value) {
+    const separator = value.lastIndexOf(';');
+    if (separator < 0)
+        return null;
+    const raw = value.slice(separator + 1).trim();
+    if (!raw || raw.length > 240)
+        return null;
+    const parsed = Date.parse(raw);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function exactAlignment(left, right) {
+    if (!left.length || !right.length)
+        return 'unavailable';
+    return left.some((domain) => right.includes(domain)) ? 'aligned' : 'divergent';
+}
+function addDomainRoles(store, domains, role) {
+    for (const domain of domains) {
+        if (!store.has(domain) && store.size >= MAX_MAIL_REVIEW_DOMAINS)
+            return;
+        const roles = store.get(domain) ?? new Set();
+        roles.add(role);
+        store.set(domain, roles);
+    }
+}
+export function buildCliMailHeaderReview(value, generatedAt = new Date().toISOString()) {
+    const normalizedGeneratedAt = normalizeExplicitIsoTimestamp(generatedAt);
+    if (!normalizedGeneratedAt)
+        throw new CliUsageError('Mail-header review generation time must be a valid ISO 8601 timestamp.');
+    const parsed = parseHeaderFields(value);
+    const fromDomains = addressDomains(fieldsNamed(parsed.fields, 'from'));
+    const replyToDomains = addressDomains(fieldsNamed(parsed.fields, 'reply-to'));
+    const returnPathDomains = addressDomains(fieldsNamed(parsed.fields, 'return-path'));
+    const messageIdentifierDomains = messageIdDomains(fieldsNamed(parsed.fields, 'message-id'));
+    const authenticationResults = fieldsNamed(parsed.fields, 'authentication-results');
+    const receivedSpf = fieldsNamed(parsed.fields, 'received-spf');
+    const authentication = Object.fromEntries(AUTHENTICATION_METHODS.map((method) => [
+        method,
+        authenticationState(authenticationResults, method, method === 'spf' ? receivedSpf : []),
+    ]));
+    const authServiceDomains = authenticationServiceDomains(authenticationResults);
+    const signerDomains = dkimSigningDomains(fieldsNamed(parsed.fields, 'dkim-signature'));
+    const receivedValues = fieldsNamed(parsed.fields, 'received');
+    const omittedReceivedHops = Math.max(0, receivedValues.length - MAX_MAIL_RECEIVED_HOPS);
+    const receivedHops = receivedValues.slice(0, MAX_MAIL_RECEIVED_HOPS).map((header, index) => Object.freeze({
+        position: index + 1,
+        order: 'most_recent_first',
+        fromDomain: receivedHost(header, 'from'),
+        byDomain: receivedHost(header, 'by'),
+        transport: receivedTransport(header),
+        reportedAt: receivedTimestamp(header),
+    }));
+    const roles = new Map();
+    addDomainRoles(roles, fromDomains, 'from');
+    addDomainRoles(roles, replyToDomains, 'reply_to');
+    addDomainRoles(roles, returnPathDomains, 'return_path');
+    addDomainRoles(roles, messageIdentifierDomains, 'message_id');
+    addDomainRoles(roles, authServiceDomains, 'authentication_service');
+    addDomainRoles(roles, signerDomains, 'dkim_signer');
+    for (const hop of receivedHops) {
+        if (hop.fromDomain)
+            addDomainRoles(roles, [hop.fromDomain], 'received_from');
+        if (hop.byDomain)
+            addDomainRoles(roles, [hop.byDomain], 'received_by');
+    }
+    const domains = [...roles.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([domain, domainRoles]) => Object.freeze({
+        domain,
+        roles: Object.freeze([...domainRoles].sort()),
+    }));
+    const digest = createHash('sha256').update(boundedHeaderSection(value), 'utf8').digest('hex');
+    return Object.freeze({
+        schema: CLI_MAIL_HEADER_REVIEW_SCHEMA,
+        version: CLI_MAIL_HEADER_REVIEW_VERSION,
+        generatedAt: normalizedGeneratedAt,
+        provenance: Object.freeze({
+            input: 'analyst_selected_header_block',
+            headerBytes: parsed.bytes,
+            headerFields: parsed.fields.length,
+            headerDigestSha256: `sha256:${digest}`,
+            bodyRetained: false,
+            attachmentsRetained: false,
+            localPartsRetained: false,
+        }),
+        identity: Object.freeze({
+            reportedAt: reportedDate(fieldsNamed(parsed.fields, 'date')),
+            fromDomains: Object.freeze(fromDomains),
+            replyToDomains: Object.freeze(replyToDomains),
+            returnPathDomains: Object.freeze(returnPathDomains),
+            messageIdentifierDomains: Object.freeze(messageIdentifierDomains),
+        }),
+        authentication: Object.freeze(authentication),
+        routing: Object.freeze({
+            receivedHops: Object.freeze(receivedHops),
+            omittedReceivedHops,
+            complete: omittedReceivedHops === 0,
+        }),
+        alignment: Object.freeze({
+            fromToReplyTo: exactAlignment(fromDomains, replyToDomains),
+            fromToReturnPath: exactAlignment(fromDomains, returnPathDomains),
+            fromToDkimSigner: exactAlignment(fromDomains, signerDomains),
+        }),
+        domains: Object.freeze(domains),
+        limitations: Object.freeze([
+            'This review parses analyst-selected message headers offline. It makes no DNS, SMTP, HTTP, registry or provider request.',
+            'Authentication results are claims reported in the supplied headers; they are not independently validated here.',
+            'Exact-domain alignment is descriptive. Divergence can be legitimate and does not establish spoofing, abuse or maliciousness.',
+            'Display names, subjects, address local parts, message bodies, attachments and raw header values are not retained in the output.',
+            ...(omittedReceivedHops ? [`${omittedReceivedHops} older Received header${omittedReceivedHops === 1 ? ' was' : 's were'} omitted by the ${MAX_MAIL_RECEIVED_HOPS}-hop bound.`] : []),
+        ]),
+    });
+}
+export function formatCliMailHeaderReview(document) {
+    const lines = [
+        'Offline mail-header review',
+        `Header identity    ${document.provenance.headerDigestSha256}`,
+        `Header fields      ${document.provenance.headerFields}`,
+        `Reported date      ${document.identity.reportedAt ?? 'Unavailable'}`,
+        `From domains       ${document.identity.fromDomains.join(', ') || 'Unavailable'}`,
+        `Reply-To domains   ${document.identity.replyToDomains.join(', ') || 'Unavailable'}`,
+        `Return-Path        ${document.identity.returnPathDomains.join(', ') || 'Unavailable'}`,
+        '',
+        'Reported authentication',
+        ...AUTHENTICATION_METHODS.map((method) => `  ${method.toUpperCase().padEnd(6)} ${document.authentication[method].state} (${document.authentication[method].observations} observation${document.authentication[method].observations === 1 ? '' : 's'})`),
+        '',
+        'Exact-domain alignment',
+        `  From / Reply-To     ${document.alignment.fromToReplyTo}`,
+        `  From / Return-Path  ${document.alignment.fromToReturnPath}`,
+        `  From / DKIM signer  ${document.alignment.fromToDkimSigner}`,
+        '',
+        `Received path      ${document.routing.receivedHops.length} retained${document.routing.omittedReceivedHops ? ` · ${document.routing.omittedReceivedHops} omitted` : ''}`,
+    ];
+    for (const hop of document.routing.receivedHops) {
+        lines.push(`  ${hop.position}. ${hop.fromDomain ?? 'unknown'} → ${hop.byDomain ?? 'unknown'}${hop.transport ? ` · ${hop.transport}` : ''}${hop.reportedAt ? ` · ${hop.reportedAt}` : ''}`);
+    }
+    lines.push('', `Header domains     ${document.domains.length}`);
+    for (const domain of document.domains)
+        lines.push(`  ${domain.domain}  ${domain.roles.join(', ')}`);
+    lines.push('', 'Limitations:');
+    for (const limitation of document.limitations)
+        lines.push(`  - ${limitation}`);
+    return `${lines.join('\n')}\n`;
+}

package/cli/mail-review.mjs

@@ -3,9 +3,11 @@ import { getDomain } from 'tldts';
 import { scanBoundedJson } from "../lib/bounded-json.mjs";
 import { isValidAsciiDomainName } from "../lib/hostname.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";
 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 +22,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 +89,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 +195,7 @@ function normalizeMailRow(value) {
     const providers = providerDomains(hosts);
     return {
         domain,
+        provenance: mailRowProvenance(item),
         state,
         dnsStatus,
         hasMx,
@@ -210,6 +213,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 +249,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 +284,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,
@@ -295,10 +328,14 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
     })
         .sort((left, right) => left.providerDomain.localeCompare(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 +346,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.',
             '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 +368,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}`,
+        `Failed targets   ${document.inputCoverage.failedRows}`,
         `Authenticated    ${document.counts.authenticated_mail}`,
         `Auth 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(`  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 +399,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-command-runner.mjs

@@ -44,6 +44,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) {