@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/cli/lookup-command-runner.mjs

@@ -38,7 +38,7 @@ async function runLookupCommand(args, dependencies, context) {
     eventProgress.emit({ event: 'started' });
     const input = args.query || await context.readSingleInput();
     if (!input)
-        throw new CliUsageError('lookup requires one domain, IP address, or ASN as an argument or on stdin.');
+        throw new CliUsageError('lookup requires one domain, IP address, or ASN as an argument or on stdin.', 'missing_input');
     const classify = dependencies.classifyQuery || classifyQuery;
     const executeLookup = dependencies.runUnifiedLookup || runUnifiedLookup;
     let classified;
@@ -74,6 +74,18 @@ async function runLookupCommand(args, dependencies, context) {
             ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
         });
     };
+    const collect = (signal, onSourceSettled) => abortable(() => executeLookup(classified, {
+        fast: !args.deep,
+        compact: false,
+        ...(signal ? { signal } : {}),
+        ...(args.deep ? {
+            ...(selectedUrl ? { selectedUrl } : {}),
+            onSourceSettled: settlement => {
+                onSourceSettled(settlement);
+                eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
+            },
+        } : {}),
+    }), signal);
     let document;
     if (args.browse === true) {
         const browse = dependencies.browseLookupOperation || browseLookupOperation;
@@ -88,23 +100,7 @@ async function runLookupCommand(args, dependencies, context) {
             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,
-                        ...(selectedUrl ? { selectedUrl } : {}),
-                        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);
+                return buildDocument(await collect(signal, onSourceSettled));
             },
         });
         if (args.saveLookup) {
@@ -125,23 +121,10 @@ async function runLookupCommand(args, dependencies, context) {
         let settledSources = 0;
         let result;
         try {
-            result = await abortable(() => executeLookup(classified, args.deep
-                ? {
-                    fast: false,
-                    compact: false,
-                    ...(selectedUrl ? { selectedUrl } : {}),
-                    ...(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);
+            result = await collect(dependencies.signal, settlement => {
+                settledSources += 1;
+                indicator.update(`Collected ${settledSources} source${settledSources === 1 ? '' : 's'} · ${settlement.source.replaceAll('_', ' ')} ${settlement.state}`);
+            });
         }
         finally {
             context.endProgress();

package/cli/lookup-diff.mjs

@@ -5,6 +5,7 @@ import { relationshipObservation } from "../packages/comparison/relationship-evi
 import { CliUsageError } from "./errors.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 import { lookupObservationHostname } from "../packages/evidence/lookup-target.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 export const CLI_LOOKUP_DIFF_SCHEMA = 'whoisleuth.cli.lookup-diff';
 export const CLI_LOOKUP_DIFF_VERSION = 1;
 function text(value, maximum = 300) {
@@ -198,10 +199,10 @@ function formatCliLookupDiff(document) {
     const rows = document.comparison.rows.filter((row) => row.state !== 'equal');
     const output = [
         'Domain evidence diff',
-        `Left             ${document.left.domain}`,
-        `Left observed    ${document.left.generatedAt}`,
-        `Right            ${document.right.domain}`,
-        `Right observed   ${document.right.generatedAt}`,
+        `Left             ${safeTerminalValue(document.left.domain)}`,
+        `Left observed    ${safeTerminalValue(document.left.generatedAt)}`,
+        `Right            ${safeTerminalValue(document.right.domain)}`,
+        `Right observed   ${safeTerminalValue(document.right.generatedAt)}`,
         `Changed          ${document.comparison.counts.different + document.comparison.counts.conflicting}`,
         `One-sided        ${document.comparison.counts.missing}`,
         `Unavailable      ${document.comparison.counts.unavailable + document.comparison.counts.not_recorded}`,
@@ -210,14 +211,14 @@ function formatCliLookupDiff(document) {
     if (!rows.length)
         output.push('No bounded differences were observed in the comparable fields.');
     for (const row of rows) {
-        output.push(`${row.label} [${row.state.replaceAll('_', ' ')}]`);
-        output.push(`  Left:  ${row.left}`);
-        output.push(`  Right: ${row.right}`);
-        output.push(`  Source: ${row.source}`);
+        output.push(`${safeTerminalValue(row.label)} [${safeTerminalValue(row.state).replaceAll('_', ' ')}]`);
+        output.push(`  Left:  ${safeTerminalValue(row.left)}`);
+        output.push(`  Right: ${safeTerminalValue(row.right)}`);
+        output.push(`  Source: ${safeTerminalValue(row.source)}`);
     }
     output.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        output.push(`  - ${limitation}`);
+        output.push(`  - ${safeTerminalValue(limitation)}`);
     return `${output.join('\n')}\n`;
 }
 export { buildCliLookupDiff, formatCliLookupDiff };

package/cli/lookup-plan.mjs

@@ -1,3 +1,4 @@
+import { plannedLookupSources } from "../lib/lookup-progress.mjs";
 export const CLI_LOOKUP_PLAN_SCHEMA = 'whoisleuth.cli.lookup-plan';
 export const CLI_LOOKUP_PLAN_VERSION = 1;
 const RDAP = Object.freeze({
@@ -43,20 +44,15 @@ const REVERSE_DNS = Object.freeze({
     conditional: false,
 });
 function plannedSources(classified, deep, selectedUrl) {
-    if (!deep) {
-        return Object.freeze(classified.type === 'domain' ? [RDAP, FAST_DOMAIN_EVIDENCE] : [RDAP]);
-    }
-    if (classified.type === 'domain') {
-        const domainEvidence = selectedUrl ? Object.freeze({
-            ...DEEP_DOMAIN_EVIDENCE,
-            disclosure: 'The selected URL path and query are sent to the website and followed redirects. The fragment is not sent. DNS and TLS use its hostname; registration uses the registrable domain. Saved HTTP provenance omits queries, but page-derived text may contain sensitive information.',
-        }) : DEEP_DOMAIN_EVIDENCE;
-        return Object.freeze([RDAP, WHOIS, domainEvidence, REGISTRAR_RDAP, NETWORK_CONTEXT]);
-    }
-    if (classified.type === 'ipv4' || classified.type === 'ipv6') {
-        return Object.freeze([RDAP, WHOIS, REVERSE_DNS]);
-    }
-    return Object.freeze([RDAP, WHOIS]);
+    const domainEvidence = selectedUrl && deep ? Object.freeze({
+        ...DEEP_DOMAIN_EVIDENCE,
+        disclosure: 'The selected URL path and query are sent to the website and followed redirects. The fragment is not sent. DNS and TLS use its hostname; registration uses the registrable domain. Saved HTTP provenance omits queries, but page-derived text may contain sensitive information.',
+    }) : deep ? DEEP_DOMAIN_EVIDENCE : FAST_DOMAIN_EVIDENCE;
+    const sources = {
+        rdap: RDAP, whois: WHOIS, domain_evidence: domainEvidence,
+        registrar_rdap: REGISTRAR_RDAP, network_context: NETWORK_CONTEXT, reverse_dns: REVERSE_DNS,
+    };
+    return Object.freeze(plannedLookupSources(classified.type, deep ? 'deep' : 'fast').map(id => sources[id]));
 }
 function buildCliLookupPlan(query, classified, deep, selectedUrl = false) {
     return Object.freeze({

package/cli/lookup-reconcile.mjs

@@ -2,6 +2,7 @@ import { CliUsageError } from "./errors.mjs";
 import { buildCliLookupDiff } from "./lookup-diff.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 import { compareObservationContexts } from "../packages/comparison/capture-context.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 const CLI_LOOKUP_RECONCILIATION_SCHEMA = 'whoisleuth.cli.lookup-reconciliation';
 const CLI_LOOKUP_RECONCILIATION_VERSION = 1;
 const MAX_LOOKUP_RECONCILIATION_INPUT_BYTES = 32 * 1024 * 1024;
@@ -117,7 +118,7 @@ function formatCliLookupReconciliation(document) {
     const context = compareObservationContexts(document.observations.map(observation => ({ ...observation, observedAt: observation.generatedAt })));
     const output = [
         'Lookup observation reconciliation',
-        `Domain             ${document.domain}`,
+        `Domain             ${safeTerminalValue(document.domain)}`,
         `Observations       ${document.summary.observationCount}`,
         `Declared labels    ${context.labels}; collection independence not verified`,
         `Capture time span  ${context.time.spanMilliseconds === null ? 'unknown' : `${context.time.spanMilliseconds / 1000} seconds`}`,
@@ -125,18 +126,18 @@ function formatCliLookupReconciliation(document) {
         `Disagreement       ${document.summary.disagreement}`,
         `Non-comparable     ${document.summary.nonComparable}`,
         '',
-        ...document.observations.map((observation, index) => `Observation ${index + 1}: ${observation.generatedAt} · ${observation.mode} · observer ${observation.observerLabel ?? 'not declared'} · vantage ${observation.vantageLabel ?? 'not declared'}`),
+        ...document.observations.map((observation, index) => `Observation ${index + 1}: ${safeTerminalValue(observation.generatedAt)} · ${safeTerminalValue(observation.mode)} · observer ${safeTerminalValue(observation.observerLabel, 'not declared')} · vantage ${safeTerminalValue(observation.vantageLabel, 'not declared')}`),
         '',
     ];
     for (const field of document.fields.filter((candidate) => candidate.state !== 'agreement')) {
-        output.push(`${field.label} [${field.state.replaceAll('_', ' ')}]`);
+        output.push(`${safeTerminalValue(field.label)} [${safeTerminalValue(field.state).replaceAll('_', ' ')}]`);
         for (const value of field.values) {
-            output.push(`  Observation ${value.observation + 1}: ${value.value} (${value.sourceState.replaceAll('_', ' ')})`);
+            output.push(`  Observation ${value.observation + 1}: ${safeTerminalValue(value.value)} (${safeTerminalValue(value.sourceState).replaceAll('_', ' ')})`);
         }
     }
     output.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        output.push(`  - ${limitation}`);
+        output.push(`  - ${safeTerminalValue(limitation)}`);
     output.push('  - These selected observations do not establish worldwide availability, removal or takedown.');
     return `${output.join('\n')}\n`;
 }

package/cli/lookup-timeline.mjs

@@ -2,6 +2,7 @@ import { Buffer } from 'node:buffer';
 import { CliUsageError } from "./errors.mjs";
 import { buildCliLookupDiff } from "./lookup-diff.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 export const CLI_LOOKUP_TIMELINE_SCHEMA = 'whoisleuth.cli.lookup-timeline';
 export const CLI_LOOKUP_TIMELINE_VERSION = 1;
 export const MAX_LOOKUP_TIMELINE_OBSERVATIONS = 20;
@@ -95,10 +96,10 @@ function buildCliLookupTimeline(inputs, generatedAt = new Date().toISOString())
 function formatCliLookupTimeline(document) {
     const output = [
         'Same-domain observation timeline',
-        `Domain             ${document.domain}`,
+        `Domain             ${safeTerminalValue(document.domain)}`,
         `Observations       ${document.summary.observationCount}`,
-        `First observed     ${document.observations[0]?.generatedAt || 'Unavailable'}`,
-        `Last observed      ${document.observations.at(-1)?.generatedAt || 'Unavailable'}`,
+        `First observed     ${safeTerminalValue(document.observations[0]?.generatedAt, 'Unavailable')}`,
+        `Last observed      ${safeTerminalValue(document.observations.at(-1)?.generatedAt, 'Unavailable')}`,
         `Changed transitions ${document.summary.transitionsWithObservedChanges}`,
     ];
     for (const transition of document.transitions) {
@@ -106,18 +107,18 @@ function formatCliLookupTimeline(document) {
         const to = document.observations[transition.toObservation];
         const counts = transition.comparison.counts;
         const changedRows = transition.comparison.rows.filter((row) => (row.state === 'conflicting' || row.state === 'different' || row.state === 'missing'));
-        output.push('', `${from?.generatedAt || 'Unavailable'} to ${to?.generatedAt || 'Unavailable'}`, `  Observed changes ${counts.conflicting + counts.different}`, `  One-sided fields ${counts.missing}`, `  Unavailable      ${counts.unavailable + counts.not_recorded}`);
+        output.push('', `${safeTerminalValue(from?.generatedAt, 'Unavailable')} to ${safeTerminalValue(to?.generatedAt, 'Unavailable')}`, `  Observed changes ${counts.conflicting + counts.different}`, `  One-sided fields ${counts.missing}`, `  Unavailable      ${counts.unavailable + counts.not_recorded}`);
         if (!changedRows.length)
             output.push('  No observed field changes in comparable evidence.');
         for (const row of changedRows.slice(0, 10)) {
-            output.push(`  ${row.label} [${row.state.replaceAll('_', ' ')}]: ${row.left} -> ${row.right}`);
+            output.push(`  ${safeTerminalValue(row.label)} [${safeTerminalValue(row.state).replaceAll('_', ' ')}]: ${safeTerminalValue(row.left)} -> ${safeTerminalValue(row.right)}`);
         }
         if (changedRows.length > 10)
             output.push(`  ${changedRows.length - 10} additional changed fields omitted; use --json for the complete bounded comparison.`);
     }
     output.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        output.push(`  - ${limitation}`);
+        output.push(`  - ${safeTerminalValue(limitation)}`);
     return `${output.join('\n')}\n`;
 }
 export { buildCliLookupTimeline, formatCliLookupTimeline };

package/cli/mail-header-review.mjs

@@ -1,20 +1,19 @@
 import { createHash } from 'node:crypto';
 import { Buffer } from 'node:buffer';
-import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+import { MAX_MAIL_REVIEW_DOMAINS, addressDomains, messageIdDomains, authenticationServiceDomains, dkimSigningDomains, normalizeHeaderDomain } from "../packages/investigation/mail-header-identity.mjs";
+export { MAX_MAIL_REVIEW_DOMAINS } from "../packages/investigation/mail-header-identity.mjs";
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { reviewMailAuthentication, selectReceiverTrust, authenticationHeaderLabel, aggregateMailAuthentication } from "../packages/investigation/mail-authentication-review.mjs";
 export const CLI_MAIL_HEADER_REVIEW_SCHEMA = 'whoisleuth.cli.mail-header-review';
-export const CLI_MAIL_HEADER_REVIEW_VERSION = 1;
+export const CLI_MAIL_HEADER_REVIEW_VERSION = 2;
 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.');
@@ -75,240 +74,6 @@ function parseHeaderFields(value) {
 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;
@@ -348,21 +113,26 @@ function addDomainRoles(store, domains, role) {
         store.set(domain, roles);
     }
 }
-export function buildCliMailHeaderReview(value, generatedAt = new Date().toISOString()) {
+export function buildCliMailHeaderReview(value, generatedAt = new Date().toISOString(), trustedHeaders = []) {
     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);
+    let authenticationReview;
+    try {
+        authenticationReview = selectReceiverTrust(reviewMailAuthentication(parsed.fields), trustedHeaders);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            throw new CliUsageError(cause.message);
+        throw cause;
+    }
     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 authentication = aggregateMailAuthentication(authenticationReview);
     const authServiceDomains = authenticationServiceDomains(authenticationResults);
     const signerDomains = dkimSigningDomains(fieldsNamed(parsed.fields, 'dkim-signature'));
     const receivedValues = fieldsNamed(parsed.fields, 'received');
@@ -414,6 +184,7 @@ export function buildCliMailHeaderReview(value, generatedAt = new Date().toISOSt
             messageIdentifierDomains: Object.freeze(messageIdentifierDomains),
         }),
         authentication: Object.freeze(authentication),
+        authenticationReview,
         routing: Object.freeze({
             receivedHops: Object.freeze(receivedHops),
             omittedReceivedHops,
@@ -428,6 +199,7 @@ export function buildCliMailHeaderReview(value, generatedAt = new Date().toISOSt
         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.',
+            'Receiver trust is an explicit analyst selection for an exact header, not a conclusion from a matching service name. Aggregate counts combine all reported sources, not a trusted verdict.',
             '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.`] : []),
@@ -444,8 +216,13 @@ export function formatCliMailHeaderReview(document) {
         `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'})`),
+        'Authentication by source header',
+        ...document.authenticationReview.headers.flatMap(header => [
+            `  ${authenticationHeaderLabel(header)} · ${header.state} · receiver trust: ${header.receiverTrust.replaceAll('_', ' ')}`,
+            ...header.claims.map(claim => `    ${claim.method.toUpperCase()}/${claim.methodVersion}: ${claim.result}${claim.state === 'unsupported' ? ' (unsupported)' : ''}${claim.domains.map(value => ` · ${value.property}=${value.domain}`).join('')}${claim.duplicateProperties.length ? ` · ambiguous: ${claim.duplicateProperties.join(', ')}` : ''}`),
+            ...(header.duplicateOf ? [`    Duplicate of header ${header.duplicateOf} in this part.`] : []),
+            ...header.issues.map(issue => `    ${issue}`),
+        ]),
         '',
         'Exact-domain alignment',
         `  From / Reply-To     ${document.alignment.fromToReplyTo}`,

package/cli/mail-review.mjs

@@ -1,11 +1,13 @@
 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 = 4;
 export const MAX_MAIL_REVIEW_INPUT_BYTES = 16 * 1024 * 1024;
@@ -326,7 +328,7 @@ 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 = {
@@ -355,7 +357,7 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
         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.',
             ...(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.`] : []),
@@ -371,15 +373,15 @@ function formatCliMailReview(document) {
         `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}`,
+        `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 + 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` : ''}`);