@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/cli/local-mmdb-review.mjs

@@ -0,0 +1,76 @@
+import { stat } from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { open } from 'maxmind';
+import { formatIpPrefix, parseIpPrefix } from "../lib/ip-prefix.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const LOCAL_MMDB_QUERY_SCHEMA = 'whoisleuth.local-mmdb-query';
+export const MAX_LOCAL_MMDB_BYTES = 512 * 1024 * 1024;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function boundedText(value, maximum) {
+    return typeof value === 'string' && value.length <= maximum && !/[\u0000-\u001f\u007f]/u.test(value)
+        ? value.replace(/\s+/gu, ' ').trim() || null
+        : null;
+}
+function names(value) {
+    const source = record(value);
+    return boundedText(source.en, 120);
+}
+export async function reviewLocalMmdb(input, databasePath) {
+    const address = boundedText(input.address, 64)?.toLowerCase() ?? '';
+    const sourceLabel = boundedText(input.sourceLabel, 120);
+    const databaseVersion = boundedText(input.databaseVersion, 80);
+    const license = boundedText(input.license, 240);
+    if (!isIP(address))
+        throw new CliUsageError('Local MMDB review requires one valid IP address.');
+    if (!sourceLabel || !databaseVersion || !license) {
+        throw new CliUsageError('Local MMDB review requires bounded sourceLabel, databaseVersion, and licence metadata.');
+    }
+    let info;
+    try {
+        info = await stat(databasePath);
+    }
+    catch {
+        throw new CliUsageError('The supplied MMDB file could not be read.');
+    }
+    if (!info.isFile() || info.size <= 0 || info.size > MAX_LOCAL_MMDB_BYTES) {
+        throw new CliUsageError(`The supplied MMDB must be a file no larger than ${MAX_LOCAL_MMDB_BYTES} bytes.`);
+    }
+    let reader;
+    try {
+        reader = await open(databasePath, { cache: { max: 1_000 } });
+    }
+    catch {
+        throw new CliUsageError('The supplied file is not a readable MaxMind DB database.');
+    }
+    const [rawMatch, prefixLength] = reader.getWithPrefixLength(address);
+    const match = record(rawMatch);
+    const traits = record(match.traits);
+    const country = record(match.country);
+    const registeredCountry = record(match.registered_country);
+    const subdivisions = Array.isArray(match.subdivisions) ? match.subdivisions : [];
+    const subdivision = record(subdivisions[0]);
+    const city = record(match.city);
+    const asnValue = match.autonomous_system_number ?? traits.autonomous_system_number;
+    const asn = typeof asnValue === 'number' && Number.isSafeInteger(asnValue) && asnValue >= 0 ? asnValue : null;
+    const prefix = parseIpPrefix(`${address}/${prefixLength}`);
+    return Object.freeze({
+        state: rawMatch ? 'matched' : 'not_found',
+        address,
+        match: rawMatch ? Object.freeze({
+            network: prefix ? formatIpPrefix(prefix) : null,
+            countryCode: boundedText(country.iso_code ?? registeredCountry.iso_code, 2)?.toUpperCase() ?? null,
+            region: names(subdivision.names) ?? boundedText(subdivision.iso_code, 120),
+            city: names(city.names),
+            asn,
+            asName: boundedText(match.autonomous_system_organization ?? traits.autonomous_system_organization, 240),
+        }) : null,
+        source: Object.freeze({ label: sourceLabel, version: databaseVersion, license }),
+        limitations: Object.freeze([
+            'This CLI-only result comes from an analyst-supplied local MMDB file. WHOISleuth does not bundle, download, update, license, or transmit the database.',
+            'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
+            'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
+        ]),
+    });
+}

package/cli/lookalike-calibration.mjs

@@ -0,0 +1,121 @@
+import { Buffer } from 'node:buffer';
+const LOOKALIKE_CALIBRATION_INPUT_SCHEMA = 'whoisleuth.lookalike-calibration-input';
+const LOOKALIKE_CALIBRATION_SCHEMA = 'whoisleuth.lookalike-calibration';
+const LOOKALIKE_CALIBRATION_VERSION = 1;
+const MAX_LOOKALIKE_CALIBRATION_BYTES = 2 * 1024 * 1024;
+const MAX_LOOKALIKE_CALIBRATION_RECORDS = 5_000;
+const MIN_LOOKALIKE_CALIBRATION_SAMPLE = 20;
+const DISPOSITIONS = ['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action'];
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function token(value, field) {
+    if (typeof value !== 'string')
+        throw new TypeError(`${field} must be text.`);
+    const normalized = value.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9_-]{0,79}$/u.test(normalized))
+        throw new TypeError(`${field} must be a bounded identifier.`);
+    return normalized;
+}
+function ratio(value, total) {
+    return total ? Number((value / total).toFixed(4)) : 0;
+}
+function emptyCounts() {
+    return { suspicious: 0, confirmed_abuse: 0, false_positive: 0, expected: 0, closed_no_action: 0 };
+}
+function buildLookalikeCalibration(raw, generatedAt = new Date().toISOString()) {
+    if (Buffer.byteLength(raw, 'utf8') > MAX_LOOKALIKE_CALIBRATION_BYTES) {
+        throw new TypeError(`Lookalike calibration input is limited to ${MAX_LOOKALIKE_CALIBRATION_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new TypeError('Lookalike calibration input must be valid JSON.');
+    }
+    const input = record(parsed);
+    if (input.schema !== LOOKALIKE_CALIBRATION_INPUT_SCHEMA || input.version !== LOOKALIKE_CALIBRATION_VERSION) {
+        throw new TypeError(`Lookalike calibration input must use ${LOOKALIKE_CALIBRATION_INPUT_SCHEMA} version ${LOOKALIKE_CALIBRATION_VERSION}.`);
+    }
+    if (!Array.isArray(input.records) || input.records.length < 1 || input.records.length > MAX_LOOKALIKE_CALIBRATION_RECORDS) {
+        throw new TypeError(`Lookalike calibration input must contain from 1 to ${MAX_LOOKALIKE_CALIBRATION_RECORDS} reviewed records.`);
+    }
+    const ids = new Set();
+    const familyCounts = new Map();
+    const totalCounts = emptyCounts();
+    for (let index = 0; index < input.records.length; index++) {
+        const item = record(input.records[index]);
+        const id = token(item.id, `records[${index}].id`);
+        if (ids.has(id))
+            throw new TypeError(`Lookalike calibration record id "${id}" is duplicated.`);
+        ids.add(id);
+        if (typeof item.disposition !== 'string' || !DISPOSITIONS.includes(item.disposition)) {
+            throw new TypeError(`records[${index}].disposition is not a supported reviewed disposition.`);
+        }
+        const disposition = item.disposition;
+        if (!Array.isArray(item.mutationFamilies) || item.mutationFamilies.length < 1 || item.mutationFamilies.length > 12) {
+            throw new TypeError(`records[${index}].mutationFamilies must contain from 1 to 12 identifiers.`);
+        }
+        const families = [...new Set(item.mutationFamilies.map((value) => token(value, `records[${index}].mutationFamilies`)))];
+        totalCounts[disposition] += 1;
+        for (const family of families) {
+            const counts = familyCounts.get(family) || emptyCounts();
+            counts[disposition] += 1;
+            familyCounts.set(family, counts);
+        }
+    }
+    const families = [...familyCounts.entries()].map(([id, dispositions]) => {
+        const reviewedCandidates = Object.values(dispositions).reduce((sum, count) => sum + count, 0);
+        return {
+            id,
+            reviewedCandidates,
+            sampleState: reviewedCandidates >= MIN_LOOKALIKE_CALIBRATION_SAMPLE ? 'reviewed' : 'insufficient',
+            dispositions,
+            reviewLeadRate: ratio(dispositions.suspicious + dispositions.confirmed_abuse, reviewedCandidates),
+            falsePositiveRate: ratio(dispositions.false_positive, reviewedCandidates),
+        };
+    }).sort((left, right) => right.reviewedCandidates - left.reviewedCandidates || left.id.localeCompare(right.id));
+    const reviewedCandidates = input.records.length;
+    return {
+        schema: LOOKALIKE_CALIBRATION_SCHEMA,
+        version: LOOKALIKE_CALIBRATION_VERSION,
+        generatedAt,
+        summary: {
+            reviewedCandidates,
+            mutationFamilies: families.length,
+            sampleState: reviewedCandidates >= MIN_LOOKALIKE_CALIBRATION_SAMPLE ? 'reviewed' : 'insufficient',
+            reviewLeadRate: ratio(totalCounts.suspicious + totalCounts.confirmed_abuse, reviewedCandidates),
+            falsePositiveRate: ratio(totalCounts.false_positive, reviewedCandidates),
+            expectedRate: ratio(totalCounts.expected, reviewedCandidates),
+        },
+        families,
+        privacy: { candidateIdsRetained: 0, domainsRetained: 0, notesRetained: 0 },
+        limitations: [
+            'This offline report summarises analyst dispositions for the supplied reviewed sample and never changes mutation generation, ordering, Risk, or filtering automatically.',
+            'Suspicious and confirmed-abuse dispositions are counted as review leads, not proof of maliciousness; expected and false-positive dispositions are not proof of safety.',
+            `A family remains an insufficient sample below ${MIN_LOOKALIKE_CALIBRATION_SAMPLE} reviewed candidates, and even larger local samples may not generalize across brands, languages, registries, or time.`,
+            'Candidate identifiers, domains, notes, and evidence are intentionally omitted from output. Retain the reviewed source dataset under an appropriate local privacy policy.',
+        ],
+    };
+}
+function formatLookalikeCalibration(report) {
+    const output = [
+        'Lookalike review-yield calibration',
+        `Reviewed candidates ${report.summary.reviewedCandidates}`,
+        `Mutation families   ${report.summary.mutationFamilies}`,
+        `Sample state        ${report.summary.sampleState}`,
+        `Review-lead rate    ${(report.summary.reviewLeadRate * 100).toFixed(1)}%`,
+        `False-positive rate ${(report.summary.falsePositiveRate * 100).toFixed(1)}%`,
+        '',
+    ];
+    for (const family of report.families) {
+        output.push(`${family.id} [${family.sampleState}]`);
+        output.push(`  ${family.reviewedCandidates} reviewed · ${(family.reviewLeadRate * 100).toFixed(1)}% review leads · ${(family.falsePositiveRate * 100).toFixed(1)}% false positives`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of report.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { LOOKALIKE_CALIBRATION_INPUT_SCHEMA, LOOKALIKE_CALIBRATION_SCHEMA, LOOKALIKE_CALIBRATION_VERSION, MAX_LOOKALIKE_CALIBRATION_BYTES, MAX_LOOKALIKE_CALIBRATION_RECORDS, MIN_LOOKALIKE_CALIBRATION_SAMPLE, buildLookalikeCalibration, formatLookalikeCalibration, };

package/cli/lookup-command-runner.mjs

@@ -68,7 +68,10 @@ async function runLookupCommand(args, dependencies, context) {
         context.endProgress();
     }
     const now = context.now();
-    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast');
+    const document = buildCliLookupDocument(query, classified, result, now, args.deep ? 'deep' : 'fast', {
+        ...(args.observerLabel ? { observerLabel: args.observerLabel } : {}),
+        ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
+    });
     if (!args.quiet) {
         if (args.output === 'json')
             context.writeStdout(formatJsonDocument(document));

package/cli/lookup-plan.mjs

@@ -3,13 +3,13 @@ export const CLI_LOOKUP_PLAN_VERSION = 1;
 const RDAP = Object.freeze({
     source: 'rdap',
     purpose: 'Collect authoritative registration or allocation evidence where supported.',
-    disclosure: 'The normalized target is sent to the applicable RDAP bootstrap and service endpoints.',
+    disclosure: 'The normalised target is sent to the applicable RDAP bootstrap and service endpoints.',
     conditional: false,
 });
 const WHOIS = Object.freeze({
     source: 'whois',
     purpose: 'Collect separately attributed registry and referral publications.',
-    disclosure: 'The normalized target is sent over bounded TCP connections to applicable WHOIS services.',
+    disclosure: 'The normalised target is sent over bounded TCP connections to applicable WHOIS services.',
     conditional: false,
 });
 const FAST_DOMAIN_EVIDENCE = Object.freeze({
@@ -39,7 +39,7 @@ const NETWORK_CONTEXT = Object.freeze({
 const REVERSE_DNS = Object.freeze({
     source: 'reverse_dns',
     purpose: 'Collect operator-published reverse-DNS context for a public IP address.',
-    disclosure: 'A DNS resolver receives the reverse lookup for the normalized IP address.',
+    disclosure: 'A DNS resolver receives the reverse lookup for the normalised IP address.',
     conditional: false,
 });
 function plannedSources(classified, deep) {

package/cli/lookup-reconcile.mjs

@@ -0,0 +1,141 @@
+import { CliUsageError } from "./errors.mjs";
+import { buildCliLookupDiff } from "./lookup-diff.mjs";
+import { parseSavedLookupDocument } from "./saved-lookup.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;
+function object(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function label(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, 80);
+    return normalized || null;
+}
+function observationContext(document) {
+    const context = object(document.collectionContext);
+    return {
+        generatedAt: document.generatedAt,
+        mode: document.mode,
+        observerLabel: label(context.observerLabel),
+        vantageLabel: label(context.vantageLabel),
+    };
+}
+function comparable(value, sourceState) {
+    if (['error', 'not_recorded', 'partial', 'skipped', 'unavailable', 'unsupported'].includes(sourceState))
+        return false;
+    return value !== 'Not observed' && value !== 'Not recorded in compact Bulk evidence';
+}
+function normalizedValue(value) {
+    return value.replace(/\s+/gu, ' ').trim().toLocaleLowerCase('en-US');
+}
+function buildCliLookupReconciliation(inputs, generatedAt = new Date().toISOString()) {
+    if (inputs.length < 2 || inputs.length > 5)
+        throw new CliUsageError('Lookup reconciliation requires from 2 to 5 observations.');
+    const documents = inputs.map((input, index) => parseSavedLookupDocument(input, {
+        label: `Lookup reconciliation observation ${index + 1}`,
+    }));
+    const domain = documents[0]?.registrableDomain;
+    if (!domain || documents.some((document) => document.registrableDomain !== domain)) {
+        throw new CliUsageError('Lookup reconciliation requires observations for one domain.');
+    }
+    const comparisons = documents.slice(1).map((document, index) => buildCliLookupDiff(inputs[0], inputs[index + 1], generatedAt, { domainMode: 'same' }));
+    const firstRows = comparisons[0]?.comparison.rows || [];
+    const fields = firstRows.map((firstRow) => {
+        const values = [{
+                observation: 0,
+                value: firstRow.left,
+                sourceState: firstRow.leftSourceState,
+                comparable: comparable(firstRow.left, firstRow.leftSourceState),
+            }];
+        for (let index = 0; index < comparisons.length; index++) {
+            const row = comparisons[index].comparison.rows.find((candidate) => candidate.id === firstRow.id);
+            if (!row)
+                continue;
+            values.push({
+                observation: index + 1,
+                value: row.right,
+                sourceState: row.rightSourceState,
+                comparable: comparable(row.right, row.rightSourceState),
+            });
+        }
+        const comparableValues = values.filter((value) => value.comparable);
+        const distinctValues = new Set(comparableValues.map((value) => normalizedValue(value.value)));
+        const state = comparableValues.length < 2
+            ? 'non_comparable'
+            : distinctValues.size === 1
+                ? 'agreement'
+                : 'disagreement';
+        return {
+            id: firstRow.id,
+            category: firstRow.category,
+            label: firstRow.label,
+            source: firstRow.source,
+            state,
+            method: firstRow.method,
+            values,
+            limitations: firstRow.limitations,
+        };
+    });
+    const observations = documents.map(observationContext);
+    const identities = observations.map((observation) => (observation.observerLabel && observation.vantageLabel
+        ? `${observation.observerLabel}\u0000${observation.vantageLabel}`
+        : null));
+    const labelsComplete = identities.every((identity) => identity !== null);
+    const labelsDistinct = labelsComplete && new Set(identities).size === identities.length;
+    const independence = labelsDistinct
+        ? {
+            state: 'verified_distinct_labels',
+            reason: 'Every observation carries a different analyst-supplied observer and vantage label.',
+        }
+        : {
+            state: 'unverified',
+            reason: 'Observer and vantage labels are missing or repeated; independent collection cannot be inferred.',
+        };
+    return {
+        schema: CLI_LOOKUP_RECONCILIATION_SCHEMA,
+        version: CLI_LOOKUP_RECONCILIATION_VERSION,
+        generatedAt,
+        domain,
+        independence,
+        observations,
+        fields,
+        summary: {
+            observationCount: observations.length,
+            agreement: fields.filter((field) => field.state === 'agreement').length,
+            disagreement: fields.filter((field) => field.state === 'disagreement').length,
+            nonComparable: fields.filter((field) => field.state === 'non_comparable').length,
+        },
+        privacy: { filenamesRetained: 0, rawRegistryPayloadsCopied: 0 },
+        limitations: [
+            'This report reconciles only bounded normalised values already present in saved Lookup documents and makes no network request.',
+            'Observer and vantage labels are analyst-supplied metadata. Distinct labels do not prove independent resolvers, networks, providers, caches, or collection paths.',
+            'Agreement can reflect shared upstream data or collection conditions. Disagreement can reflect collection timing, propagation, source health, or a real domain change.',
+            'Non-comparable evidence remains separate from agreement and is never interpreted as absence, safety, or a negative finding.',
+        ],
+    };
+}
+function formatCliLookupReconciliation(document) {
+    const output = [
+        'Lookup observation reconciliation',
+        `Domain             ${document.domain}`,
+        `Observations       ${document.summary.observationCount}`,
+        `Independence       ${document.independence.state.replaceAll('_', ' ')}`,
+        `Agreement          ${document.summary.agreement}`,
+        `Disagreement       ${document.summary.disagreement}`,
+        `Non-comparable     ${document.summary.nonComparable}`,
+        '',
+    ];
+    for (const field of document.fields.filter((candidate) => candidate.state !== 'agreement')) {
+        output.push(`${field.label} [${field.state.replaceAll('_', ' ')}]`);
+        for (const value of field.values) {
+            output.push(`  Observation ${value.observation + 1}: ${value.value} (${value.sourceState.replaceAll('_', ' ')})`);
+        }
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of document.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { CLI_LOOKUP_RECONCILIATION_SCHEMA, CLI_LOOKUP_RECONCILIATION_VERSION, MAX_LOOKUP_RECONCILIATION_INPUT_BYTES, buildCliLookupReconciliation, formatCliLookupReconciliation, };

package/cli/lookup-timeline.mjs

@@ -85,7 +85,7 @@ function buildCliLookupTimeline(inputs, generatedAt = new Date().toISOString())
             rawRegistryPayloadsCopied: 0,
         },
         limitations: [
-            'The timeline compares only bounded normalized fields already present in the selected saved Lookup documents and makes no network request.',
+            'The timeline compares only bounded normalised fields already present in the selected saved Lookup documents and makes no network request.',
             'Input filenames and raw registry payloads are not copied into the timeline output.',
             'Missing, unavailable, and not-recorded evidence remain separate from an observed difference.',
             'A difference can reflect a domain change or changed collection conditions and does not by itself establish current state, ownership, intent, safety, or maliciousness.',

package/cli/mail-review.mjs

@@ -1,8 +1,9 @@
 import { Buffer } from 'node:buffer';
 import { getDomain } from 'tldts';
+import { analyzeTlsaEvidence } from "../lib/tlsa-evidence.mjs";
 import { CliUsageError } from "./errors.mjs";
 export const CLI_MAIL_REVIEW_SCHEMA = 'whoisleuth.cli.mail-review';
-export const CLI_MAIL_REVIEW_VERSION = 1;
+export const CLI_MAIL_REVIEW_VERSION = 2;
 export const MAX_MAIL_REVIEW_INPUT_BYTES = 16 * 1024 * 1024;
 export const MAX_MAIL_REVIEW_ROWS = 500;
 function record(value) {
@@ -53,6 +54,21 @@ function mailState(input) {
         return 'no_explicit_mx';
     return 'evidence_incomplete';
 }
+function alignMailDaneEvidence(report, hosts) {
+    const aligned = report.service?.transport === 'tcp'
+        && report.service.port === 25
+        && hosts.includes(report.service.hostname);
+    if (aligned || report.state === 'invalid')
+        return report;
+    return Object.freeze({
+        ...report,
+        state: 'invalid',
+        limitations: Object.freeze([
+            ...report.limitations,
+            'The TLSA service name did not identify port 25 on an MX hostname retained for this domain.',
+        ]),
+    });
+}
 function normalizeMailRow(value) {
     const item = record(value);
     if (item.ok !== true)
@@ -70,6 +86,18 @@ function normalizeMailRow(value) {
     const hasSpf = boolean(availability.hasSpf) ?? boolean(summary.hasSpf);
     const hasDmarc = boolean(availability.hasDmarc) ?? boolean(summary.hasDmarc);
     const state = mailState({ dnsStatus, hasMx, hasNullMx, hasSpf, hasDmarc });
+    const tlsaInput = record(item.tlsaEvidence);
+    const dane = Object.keys(tlsaInput).length
+        ? alignMailDaneEvidence(analyzeTlsaEvidence({
+            serviceName: tlsaInput.serviceName,
+            dnssecState: tlsaInput.dnssecState,
+            pkixValidationState: tlsaInput.pkixValidationState,
+            records: tlsaInput.records,
+            certificateDerBase64: tlsaInput.certificateDerBase64,
+            spkiDerBase64: tlsaInput.spkiDerBase64,
+            authorityMaterials: tlsaInput.authorityMaterials,
+        }), hosts)
+        : null;
     return {
         domain,
         state,
@@ -80,9 +108,11 @@ function normalizeMailRow(value) {
         hasDmarc,
         mxHosts: hosts,
         providerDomains: providerDomains(hosts),
+        dane,
         limitations: [
             ...(dnsStatus === 'partial' ? ['DNS evidence was partial.'] : []),
             ...(state === 'no_explicit_mx' ? ['No explicit MX is not equivalent to a null MX or proof that delivery is impossible.'] : []),
+            ...(dane?.state === 'matched' ? [] : dane ? ['Supplied TLSA evidence did not establish one complete DNSSEC-validated match.'] : ['No TLSA evidence was supplied for offline DANE comparison.']),
             'Mail configuration does not establish use, control, intent, safety, or maliciousness.',
         ],
     };
@@ -142,6 +172,17 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
     };
     for (const row of rows)
         counts[row.state] += 1;
+    const daneCounts = {
+        matched: 0,
+        different: 0,
+        partial: 0,
+        untrusted: 0,
+        unavailable: 0,
+        invalid: 0,
+        not_supplied: 0,
+    };
+    for (const row of rows)
+        daneCounts[row.dane?.state ?? 'not_supplied'] += 1;
     const providerMap = new Map();
     for (const row of rows) {
         for (const provider of row.providerDomains) {
@@ -165,12 +206,14 @@ function buildCliMailReview(textValue, generatedAt = new Date().toISOString()) {
         version: CLI_MAIL_REVIEW_VERSION,
         generatedAt,
         counts,
+        daneCounts,
         rows,
         providerRelationships,
         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 behavior, banner collection, and message acceptance were not tested.',
+            'Optional TLSA evidence is compared offline. A DANE match requires separately validated DNSSEC evidence from the same observation.',
+            'SMTP delivery, mailbox existence, catch-all behaviour, banner collection, and message acceptance were not tested.',
         ],
     };
 }
@@ -183,12 +226,14 @@ function formatCliMailReview(document) {
         `Null MX          ${document.counts.null_mx}`,
         `No explicit MX   ${document.counts.no_explicit_mx}`,
         `Incomplete       ${document.counts.evidence_incomplete + document.counts.mail_auth_incomplete}`,
+        `DANE matched     ${document.daneCounts.matched}`,
         '',
     ];
     for (const row of document.rows) {
         lines.push(`${row.domain}  ${row.state.replaceAll('_', ' ')}`);
         lines.push(`  MX providers  ${row.providerDomains.join(', ') || 'None observed'}`);
         lines.push(`  SPF / DMARC   ${row.hasSpf === null ? 'unknown' : row.hasSpf ? 'observed' : 'not observed'} / ${row.hasDmarc === null ? 'unknown' : row.hasDmarc ? 'observed' : 'not observed'}`);
+        lines.push(`  DANE / TLSA   ${row.dane?.state ?? 'not supplied'}`);
     }
     if (document.providerRelationships.length) {
         lines.push('', 'Shared mail-provider relationships');
@@ -201,4 +246,4 @@ function formatCliMailReview(document) {
         lines.push(`  - ${limitation}`);
     return `${lines.join('\n')}\n`;
 }
-export { buildCliMailReview, formatCliMailReview, mailState, normalizeMailRow };
+export { alignMailDaneEvidence, buildCliMailReview, formatCliMailReview, mailState, normalizeMailRow };

package/cli/offline-evidence-review.mjs

@@ -0,0 +1,159 @@
+import { Buffer } from 'node:buffer';
+import { normalizeEncryptedDnsAdapter, planEncryptedDnsQuery, } from "../lib/encrypted-dns-contract.mjs";
+import { validateDnssecEvidence } from "../lib/dnssec-evidence-validation.mjs";
+import { buildLocalGeoIpDatabase, lookupLocalGeoIp, } from "../lib/local-geoip-evidence.mjs";
+import { normalizeRdapSearchHelp, planRdapReverseSearch, } from "../lib/rdap-search-workbench.mjs";
+import { reviewRpkiRoute } from "../lib/rpki-evidence.mjs";
+import { analyzeTlsaEvidence } from "../lib/tlsa-evidence.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { LOCAL_MMDB_QUERY_SCHEMA, 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;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function parseInput(value) {
+    if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > MAX_OFFLINE_EVIDENCE_INPUT_BYTES) {
+        throw new CliUsageError(`Offline evidence input is limited to ${MAX_OFFLINE_EVIDENCE_INPUT_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('Offline evidence review requires one valid JSON document.');
+    }
+    const document = record(parsed);
+    if (document.version !== 1 || typeof document.schema !== 'string') {
+        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);
+    let kind;
+    let result;
+    if (input.schema === 'whoisleuth.rdap-search-input') {
+        kind = 'rdap_search';
+        const request = record(input.request);
+        const help = normalizeRdapSearchHelp(input.help);
+        result = Object.freeze({
+            help,
+            plan: planRdapReverseSearch(help, {
+                searchableResourceType: String(request.searchableResourceType ?? ''),
+                relatedResourceType: String(request.relatedResourceType ?? ''),
+                property: String(request.property ?? ''),
+                value: request.value,
+            }),
+        });
+    }
+    else if (input.schema === 'whoisleuth.dnssec-evidence-input') {
+        kind = 'dnssec';
+        result = validateDnssecEvidence({
+            ownerName: input.ownerName,
+            delegationSigned: input.delegationSigned,
+            dsRecords: input.dsRecords,
+            dnskeyRecords: input.dnskeyRecords,
+            rrSigRecords: input.rrSigRecords,
+            observedAt: input.observedAt,
+        });
+    }
+    else if (input.schema === 'whoisleuth.tlsa-evidence-input') {
+        kind = 'tlsa';
+        result = analyzeTlsaEvidence({
+            serviceName: input.serviceName,
+            dnssecState: input.dnssecState,
+            pkixValidationState: input.pkixValidationState,
+            records: input.records,
+            certificateDerBase64: input.certificateDerBase64,
+            spkiDerBase64: input.spkiDerBase64,
+            authorityMaterials: input.authorityMaterials,
+        });
+    }
+    else if (input.schema === 'whoisleuth.rpki-route-input') {
+        kind = 'rpki';
+        result = reviewRpkiRoute({
+            routePrefix: input.routePrefix,
+            originAsn: input.originAsn,
+            authorizations: input.authorizations,
+        });
+    }
+    else if (input.schema === 'whoisleuth.local-geoip-query') {
+        kind = 'geoip';
+        result = lookupLocalGeoIp(buildLocalGeoIpDatabase(input.database), input.address);
+    }
+    else if (input.schema === 'whoisleuth.encrypted-dns-plan-input') {
+        kind = 'encrypted_dns';
+        const query = record(input.query);
+        result = planEncryptedDnsQuery(normalizeEncryptedDnsAdapter(input.adapter), { name: query.name, type: query.type });
+    }
+    else {
+        throw new CliUsageError('Offline evidence review does not recognise this input schema.');
+    }
+    return Object.freeze({
+        schema: OFFLINE_EVIDENCE_REVIEW_SCHEMA,
+        version: OFFLINE_EVIDENCE_REVIEW_VERSION,
+        generatedAt,
+        kind,
+        result,
+        limitations: Object.freeze([
+            'The review is local and uses only the supplied document. It does not refresh, transmit, or independently establish the current completeness of the evidence.',
+        ]),
+    });
+}
+async function buildOfflineEvidenceReviewWithLocalResources(value, generatedAt = new Date().toISOString(), options = {}) {
+    const input = parseInput(value);
+    if (input.schema !== LOCAL_MMDB_QUERY_SCHEMA)
+        return buildOfflineEvidenceReview(value, generatedAt);
+    if (!options.mmdbPath)
+        throw new CliUsageError('Local MMDB review requires --mmdb <database-file>.');
+    return Object.freeze({
+        schema: OFFLINE_EVIDENCE_REVIEW_SCHEMA,
+        version: OFFLINE_EVIDENCE_REVIEW_VERSION,
+        generatedAt,
+        kind: 'geoip',
+        result: await reviewLocalMmdb(input, options.mmdbPath),
+        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.',
+        ]),
+    });
+}
+function formatOfflineEvidenceReview(document) {
+    const result = record(document.result);
+    const state = typeof result.state === 'string' ? result.state : 'reviewed';
+    const lines = [
+        'Offline evidence review',
+        `Kind   ${document.kind.replaceAll('_', ' ')}`,
+        `State  ${state.replaceAll('_', ' ')}`,
+    ];
+    if (document.kind === 'rdap_search') {
+        const help = record(result.help);
+        const plan = record(result.plan);
+        lines.push(`Help   ${String(help.state ?? 'unavailable').replaceAll('_', ' ')}`);
+        lines.push(`Plan   ${String(plan.state ?? 'unavailable').replaceAll('_', ' ')}`);
+    }
+    else {
+        for (const [label, key] of [
+            ['Records', 'records'],
+            ['Rejected', 'rejectedCount'],
+            ['Matches', 'matchingAuthorizationCount'],
+        ]) {
+            const candidate = result[key];
+            if (Array.isArray(candidate))
+                lines.push(`${label.padEnd(7)}${candidate.length}`);
+            else if (typeof candidate === 'number')
+                lines.push(`${label.padEnd(7)}${candidate}`);
+        }
+    }
+    lines.push('', 'Limitations:');
+    for (const limitation of document.limitations)
+        lines.push(`  - ${limitation}`);
+    const nestedLimitations = Array.isArray(result.limitations) ? result.limitations : [];
+    for (const limitation of nestedLimitations) {
+        if (typeof limitation === 'string')
+            lines.push(`  - ${limitation}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export { MAX_OFFLINE_EVIDENCE_INPUT_BYTES, OFFLINE_EVIDENCE_REVIEW_SCHEMA, OFFLINE_EVIDENCE_REVIEW_VERSION, buildOfflineEvidenceReview, buildOfflineEvidenceReviewWithLocalResources, formatOfflineEvidenceReview, };