@slicedearth/whoisleuth-cli 2.2.0 → 2.3.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/review-command-runner.mjs

@@ -6,6 +6,7 @@ import EXIT_CODES from "./exit-codes.mjs";
 import { MAX_OFFLINE_EVIDENCE_INPUT_BYTES, buildOfflineEvidenceReview, buildOfflineEvidenceReviewWithLocalResources, formatOfflineEvidenceReview, } from "./offline-evidence-review.mjs";
 import { buildCliLookupBrief, formatCliLookupBrief } from "./lookup-brief.mjs";
 import { MAX_MAIL_REVIEW_INPUT_BYTES, buildCliMailReview, formatCliMailReview, } from "./mail-review.mjs";
+import { MAX_MAIL_HEADER_INPUT_BYTES, buildCliMailHeaderReview, formatCliMailHeaderReview, } from "./mail-header-review.mjs";
 import { buildCliPageComparison, formatCliPageComparison } from "./page-compare.mjs";
 import { MAX_SOURCE_RELIABILITY_INPUT_BYTES, buildSourceReliabilityReport, formatSourceReliabilityReport, } from "./source-reliability.mjs";
 import { buildInterchangeFidelityReport, formatInterchangeFidelityReport, } from "./interchange-report.mjs";
@@ -180,6 +181,29 @@ async function runMailReviewCommand(args, dependencies, context) {
     }
     return EXIT_CODES.SUCCESS;
 }
+async function runMailHeadersCommand(args, dependencies, context) {
+    context.setFailureLabel('Mail-header review');
+    let input;
+    try {
+        input = dependencies.readMailHeaderInput
+            ? await dependencies.readMailHeaderInput(args.source)
+            : await context.readHeaderInput(args.source, MAX_MAIL_HEADER_INPUT_BYTES, 'Mail-header input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read mail-header input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('mail-headers requires one message or header file, or headers on stdin.');
+    const document = buildCliMailHeaderReview(input, context.now());
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatCliMailHeaderReview(document), args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
 async function runOfflineEvidenceReviewCommand(args, dependencies, context) {
     context.setFailureLabel('Offline evidence review');
     let input;
@@ -259,6 +283,7 @@ const REVIEW_COMMAND_HANDLERS = Object.freeze({
     'compare': runCompareCommand,
     'page-compare': runPageCompareCommand,
     'mail-review': runMailReviewCommand,
+    'mail-headers': runMailHeadersCommand,
     'review-evidence': runOfflineEvidenceReviewCommand,
     'brief': runBriefOrCasePackCommand,
     'case-pack': runBriefOrCasePackCommand,

package/cli/risk-calibration.mjs

@@ -5,18 +5,14 @@ import { scanBoundedJson } from "../lib/bounded-json.mjs";
 import { canonicalRegistrableDomain } from "../lib/registrable-domain.mjs";
 import { ANALYST_REVIEW_REASON_VALUES, analystInteroperabilityTags } from "../lib/analyst-taxonomy.mjs";
 import { buildRiskCalibrationSummaryReport, parseRiskCalibrationSummaryReport, RISK_CALIBRATION_SUMMARY_INTERPRETATION, RISK_CALIBRATION_SUMMARY_THRESHOLDS, } from "../lib/risk-calibration-summary.mjs";
-import { MAX_RISK_CALIBRATION_ACTIVITY_LENGTH, MAX_RISK_CALIBRATION_AVAILABILITY_LENGTH, MAX_RISK_CALIBRATION_DISPOSITION_LENGTH, MAX_RISK_CALIBRATION_DOMAIN_AGE_DAYS, MAX_RISK_CALIBRATION_DOMAIN_LENGTH, MAX_RISK_CALIBRATION_FINDING_CATEGORY_LENGTH, MAX_RISK_CALIBRATION_FINDINGS_PER_PROVIDER, MAX_RISK_CALIBRATION_INPUT_BYTES, MAX_RISK_CALIBRATION_JSON_CONTAINER_ITEMS, MAX_RISK_CALIBRATION_JSON_DEPTH, MAX_RISK_CALIBRATION_JSON_KEYS, MAX_RISK_CALIBRATION_JSON_VALUES, MAX_RISK_CALIBRATION_MUTATIONS, MAX_RISK_CALIBRATION_PROVIDER_ID_LENGTH, MAX_RISK_CALIBRATION_PROVIDER_STATE_LENGTH, MAX_RISK_CALIBRATION_PROVIDERS, MAX_RISK_CALIBRATION_RECORD_ID_LENGTH, MAX_RISK_CALIBRATION_RECORDS, MAX_RISK_CALIBRATION_REVIEW_REASON_LENGTH, MAX_RISK_CALIBRATION_SCAN_DEPTH_LENGTH, MAX_RISK_CALIBRATION_STRING_LENGTH, MAX_RISK_CALIBRATION_TIMESTAMP_LENGTH, RISK_CALIBRATION_DATASET_SCHEMA, RISK_CALIBRATION_DATASET_VERSION, RISK_CALIBRATION_REPORT_SCHEMA, RISK_CALIBRATION_REPORT_VERSION, serializeRiskCalibrationSnapshot, snapshotRiskCalibrationReportForSerialization, SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS, } from "../packages/contracts/risk-calibration.mjs";
+import { MAX_RISK_CALIBRATION_ACTIVITY_LENGTH, MAX_RISK_CALIBRATION_AVAILABILITY_LENGTH, MAX_RISK_CALIBRATION_DISPOSITION_LENGTH, MAX_RISK_CALIBRATION_DOMAIN_AGE_DAYS, MAX_RISK_CALIBRATION_DOMAIN_LENGTH, MAX_RISK_CALIBRATION_FINDING_CATEGORY_LENGTH, MAX_RISK_CALIBRATION_FINDINGS_PER_PROVIDER, MAX_RISK_CALIBRATION_INPUT_BYTES, MAX_RISK_CALIBRATION_JSON_CONTAINER_ITEMS, MAX_RISK_CALIBRATION_JSON_DEPTH, MAX_RISK_CALIBRATION_JSON_KEYS, MAX_RISK_CALIBRATION_JSON_VALUES, MAX_RISK_CALIBRATION_MUTATIONS, MAX_RISK_CALIBRATION_PROVIDER_ID_LENGTH, MAX_RISK_CALIBRATION_PROVIDER_STATE_LENGTH, MAX_RISK_CALIBRATION_PROVIDERS, MAX_RISK_CALIBRATION_RECORD_ID_LENGTH, MAX_RISK_CALIBRATION_RECORDS, MAX_RISK_CALIBRATION_REVIEW_REASON_LENGTH, MAX_RISK_CALIBRATION_SCAN_DEPTH_LENGTH, MAX_RISK_CALIBRATION_STRING_LENGTH, MAX_RISK_CALIBRATION_TIMESTAMP_LENGTH, RISK_CALIBRATION_DATASET_SCHEMA, RISK_CALIBRATION_DATASET_VERSION, RISK_CALIBRATION_REPORT_SCHEMA, RISK_CALIBRATION_REPORT_VERSION, RISK_CALIBRATION_DISPOSITIONS, serializeRiskCalibrationSnapshot, snapshotRiskCalibrationReportForSerialization, SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS, } from "../packages/contracts/risk-calibration.mjs";
 import { CliUsageError } from "./arguments.mjs";
 import { RISK_MUTATION_TYPES } from "../lib/risk-scoring.mjs";
 import { THREAT_INTELLIGENCE_CONTRACT_VERSION, THREAT_INTELLIGENCE_ENVELOPE_VERSION, THREAT_INTELLIGENCE_SCHEMA, } from "../lib/threat-intelligence-types.mjs";
 export { MAX_RISK_CALIBRATION_INPUT_BYTES, MAX_RISK_CALIBRATION_RECORDS, MAX_RISK_CALIBRATION_STRING_LENGTH, RISK_CALIBRATION_DATASET_SCHEMA, RISK_CALIBRATION_DATASET_VERSION, RISK_CALIBRATION_REPORT_SCHEMA, RISK_CALIBRATION_REPORT_VERSION, SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS, } from "../packages/contracts/risk-calibration.mjs";
 export const RISK_CALIBRATION_THRESHOLDS = RISK_CALIBRATION_SUMMARY_THRESHOLDS;
 const CONTROL_RE = /[\x00-\x1f\x7f]/;
-const DISPOSITIONS = new Set([
-    'unreviewed', 'suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action',
-]);
-const POSITIVE_DISPOSITIONS = new Set(['confirmed_abuse']);
-const NEGATIVE_DISPOSITIONS = new Set(['false_positive', 'expected']);
+const DISPOSITIONS = new Set(RISK_CALIBRATION_DISPOSITIONS);
 const AVAILABILITY_STATES = new Set(['registered', 'for_sale', 'expiring', 'available', 'unknown', 'error']);
 const ACTIVITY_STATES = new Set(['active', 'parked', 'unreachable', 'no_site']);
 const BOOLEAN_FIELDS = [
@@ -26,6 +22,17 @@ const BOOLEAN_FIELDS = [
 ];
 const REVIEW_REASON_CODES = ANALYST_REVIEW_REASON_VALUES;
 const MUTATION_TYPES = new Set(RISK_MUTATION_TYPES);
+const DISPOSITION_METRIC_CLASSES = Object.freeze({
+    unreviewed: 'excluded',
+    suspicious: 'excluded',
+    confirmed_abuse: 'positive',
+    false_positive: 'negative',
+    expected: 'negative',
+    closed_no_action: 'excluded',
+});
+function isRiskCalibrationDisposition(value) {
+    return DISPOSITIONS.has(value);
+}
 function object(value, field) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new CliUsageError(`${field} must be an object.`);
@@ -214,7 +221,7 @@ export function parseRiskCalibrationDataset(text) {
         if (!isValidAsciiDomainName(domain, { requireDot: true }))
             throw new CliUsageError(`${prefix}.domain must be a valid ASCII DNS hostname, not an IP address.`);
         const analystDisposition = boundedString(record.analystDisposition, `${prefix}.analystDisposition`, MAX_RISK_CALIBRATION_DISPOSITION_LENGTH);
-        if (!DISPOSITIONS.has(analystDisposition))
+        if (!isRiskCalibrationDisposition(analystDisposition))
             throw new CliUsageError(`${prefix}.analystDisposition is unsupported.`);
         let reviewReasonCode;
         if (record.reviewReasonCode !== null && record.reviewReasonCode !== undefined) {
@@ -225,7 +232,7 @@ export function parseRiskCalibrationDataset(text) {
         return {
             id,
             domain,
-            analystDisposition: analystDisposition,
+            analystDisposition,
             ...(reviewReasonCode ? { reviewReasonCode } : {}),
             evidence: projectEvidence(record.evidence, `${prefix}.evidence`),
         };
@@ -276,9 +283,7 @@ function metricsForThreshold(records, threshold) {
         recall,
         specificity,
         falsePositiveRate: ratio(falsePositive, falsePositive + trueNegative),
-        f1: precision === null || recall === null || precision + recall === 0
-            ? null
-            : Number(((2 * precision * recall) / (precision + recall)).toFixed(4)),
+        f1: ratio(2 * truePositive, 2 * truePositive + falsePositive + falseNegative),
         balancedAccuracy: recall === null || specificity === null
             ? null
             : Number(((recall + specificity) / 2).toFixed(4)),
@@ -290,11 +295,7 @@ function metricsForThreshold(records, threshold) {
     };
 }
 function metricClass(disposition) {
-    if (POSITIVE_DISPOSITIONS.has(disposition))
-        return 'positive';
-    if (NEGATIVE_DISPOSITIONS.has(disposition))
-        return 'negative';
-    return 'excluded';
+    return DISPOSITION_METRIC_CLASSES[disposition];
 }
 function scoreBand(score) {
     if (score === null)
@@ -395,7 +396,8 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
             if (!source || !current)
                 continue;
             const previous = options.explainPreviousRiskScore(scoringEvidence(source));
-            if (previous?.score !== current.score)
+            const previousScore = previous?.score ?? null;
+            if (previousScore !== current.score)
                 scoresChanged += 1;
             if (scoreBand(previous?.score ?? null) !== current.band)
                 bandsChanged += 1;

package/cli/runner.mjs

@@ -5,7 +5,7 @@ import { HELP, commandDefinition, commandHelp, } from "./command-reference.mjs";
 import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import { evidenceCommandFailureLabel, isEvidenceCommand, runEvidenceCommand, } from "./evidence-command-runner.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
-import { readCliTextInput } from "./input.mjs";
+import { readCliHeaderInput, readCliTextInput } from "./input.mjs";
 import { INLINE_CLI_COMMANDS, runInlineCommand } from "./inline-command-runner.mjs";
 import { canLaunchInteractiveCli, launchInteractiveCli, } from "./interactive-launcher.mjs";
 import { MAX_OFFLINE_PASSPHRASE_FILE_BYTES, } from "./artifact-verify.mjs";
@@ -98,6 +98,11 @@ async function runParsedCli(args, dependencies = {}) {
             label,
             ...(dependencies.signal ? { signal: dependencies.signal } : {}),
         }));
+        const readHeaderInput = async (source, maximumBytes, label) => (readCliHeaderInput(source, dependencies.stdin || process.stdin, {
+            maximumBytes,
+            label,
+            ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+        }));
         const readPassphraseSource = async (source) => {
             let passphraseText;
             try {
@@ -126,6 +131,7 @@ async function runParsedCli(args, dependencies = {}) {
             writeStderr: (value) => write(stderr, value),
             readSingleInput,
             readInput,
+            readHeaderInput,
             readPassphraseSource,
             now: () => dependencies.now ? dependencies.now() : new Date().toISOString(),
             beginProgress,

package/docs/cli-reference.md

@@ -63,6 +63,13 @@ disclosures without collecting. Fast is the Lookup default. Deep adds the
 applicable registration, DNS, HTTP, TLS, page, technology and network context.
 Optional browser providers are not implicit CLI actions.
 
+`mail-headers` is an offline review of one analyst-selected RFC-style header
+block. It reports domain-only identity, header-reported authentication,
+exact-domain alignment, and bounded `Received` routing. It retains no address
+local parts, display names, subject, body, attachment, or raw header value in
+its output. It does not independently validate SPF, DKIM, DMARC, or ARC and
+does not treat divergence as proof of abuse.
+
 `dnssec-validate` and `mail-transport` are isolated authorised actions. Both
 require a selected literal public resolver, a local trust-anchor document and
 `--owned-or-authorized`; mail transport also requires `--active-probe`. Mail
@@ -109,7 +116,7 @@ Readers accept only their declared public and current versions. Unknown,
 unreleased historical and future schemas fail before partial interpretation;
 an invalid import is not treated as an empty document.
 
-`inspect-archive` reads current workspace archive v7 and exact versions 5 and 6. It
+`inspect-archive` reads current workspace archive v8 and exact versions 5, 6 and 7. It
 reports section metadata and digest-only search results unless `--reveal` is
 explicitly selected. It never searches notes, contacts or arbitrary raw fields.