@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/packages/investigation/investigation-manifest.mjs

@@ -1,13 +1,14 @@
-import { boundedJsonLimitsForBytes, parseBoundedJson, parseBoundedJsonObject } from "../../lib/bounded-json.mjs";
-import { normalizeBoundedSemanticVersion } from "../../lib/semantic-version.mjs";
+import { boundedJsonLimitsForBytes, parseBoundedJson, parseBoundedJsonObject } from "../analysis/bounded-json.mjs";
+import { normalizeBoundedSemanticVersion } from "../analysis/semantic-version.mjs";
 import { canonicalArtifactJsonV2, sha256ArtifactBytes, sha256ArtifactDigestV2, SORTED_JSON_V2 } from "../evidence/artifact-integrity.mjs";
 import { array, digest, enumeration, exact, fail, integer, iso, strings, text, validateIntegrity } from "../evidence/artifact-structure.mjs";
+import { readImageDerivationDeclaration } from "../evidence/image-regions.mjs";
 import { SELECTED_FILE_MEDIA_TYPES as INVESTIGATION_FILE_MEDIA_TYPES } from "../contracts/selected-file-limits.mjs";
 import { MAX_INVESTIGATION_MANIFEST_ARTIFACTS, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES } from "../contracts/investigation-package-limits.mjs";
 export { MAX_INVESTIGATION_MANIFEST_ARTIFACTS, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, INVESTIGATION_FILE_MEDIA_TYPES };
 export const INVESTIGATION_MANIFEST_SCHEMA = 'whoisleuth.investigation-manifest';
-export const INVESTIGATION_MANIFEST_VERSION = 3;
-export const SUPPORTED_INVESTIGATION_MANIFEST_VERSIONS = [2, INVESTIGATION_MANIFEST_VERSION];
+export const INVESTIGATION_MANIFEST_VERSION = 4;
+export const SUPPORTED_INVESTIGATION_MANIFEST_VERSIONS = [2, 3, INVESTIGATION_MANIFEST_VERSION];
 // Independently bounds the path-free metadata, not the selected file content.
 import { MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES } from "../contracts/investigation-package-limits.mjs";
 export { MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES } from "../contracts/investigation-package-limits.mjs";
@@ -78,7 +79,10 @@ export async function prepareInvestigationManifest(input, generatedAt, applicati
             throw new TypeError('Manifest artefacts exceed the combined limit.');
         totalBytes += bytes.byteLength;
         const mediaType = enumeration(artifact.mediaType ?? (typeof artifact.content === 'string' ? 'application/json' : 'application/octet-stream'), INVESTIGATION_FILE_MEDIA_TYPES, 'Artefact media type');
-        return { bytes, mediaType, source: sourceDeclaration(artifact.source) };
+        const imageDerivation = artifact.imageDerivation == null ? null : readImageDerivationDeclaration(artifact.imageDerivation);
+        if (imageDerivation && mediaType !== 'image/png')
+            throw new TypeError('Image derivation requires a PNG media declaration.');
+        return { bytes, mediaType, source: sourceDeclaration(artifact.source), imageDerivation };
     });
     const artifacts = [];
     for (const [index, file] of selected.entries()) {
@@ -90,7 +94,7 @@ export async function prepareInvestigationManifest(input, generatedAt, applicati
             byteLength: file.bytes.byteLength,
             contentDigestSha256: await sha256ArtifactBytes(file.bytes),
             canonicalDigestSha256: metadata ? await sha256ArtifactDigestV2(metadata.value) : null,
-            mediaType: file.mediaType, source: file.source,
+            mediaType: file.mediaType, source: file.source, imageDerivation: file.imageDerivation,
         }));
     }
     const unsigned = Object.freeze({
@@ -109,6 +113,7 @@ export async function prepareInvestigationManifest(input, generatedAt, applicati
             'Source identities, observation times and media types are declarations, not independently authenticated evidence. Missing source times remain unknown.',
             'Packaging events use the local clock. They do not establish earlier custody, a trusted timestamp, a signature, source accuracy or current validity.',
             'Digests establish content identity. JSON parsing and declared schema metadata do not establish that a source format is supported or its claims are true.',
+            'Image derivation declares an immediate parent fingerprint and editing operations, not proof of transformation or complete redaction. Parent bytes need not be included; missing declarations leave editing history unknown.',
         ]),
     });
     const manifest = Object.freeze({ ...unsigned, integrity: Object.freeze({
@@ -124,7 +129,8 @@ export async function buildInvestigationManifest(input, generatedAt, application
 }
 export function validateInvestigationManifest(value) {
     const version = integer(value.version, 'Investigation manifest version', 2, INVESTIGATION_MANIFEST_VERSION);
-    const current = version === INVESTIGATION_MANIFEST_VERSION;
+    const current = version >= 3;
+    const withImageDerivation = version >= 4;
     const root = exact(value, ['schema', 'version', 'generatedAt', 'application', 'workflow', 'configuration', 'artifacts', 'steps', 'summary', 'limitations', 'integrity', ...(current ? ['audience'] : [])], 'Investigation manifest');
     if (root.schema !== INVESTIGATION_MANIFEST_SCHEMA)
         fail('Investigation manifest schema');
@@ -148,7 +154,7 @@ export function validateInvestigationManifest(value) {
         fail('Investigation manifest step count');
     let totalBytes = 0;
     for (const [index, candidate] of artifacts.entries()) {
-        const item = exact(candidate, ['sequence', 'id', 'schema', 'version', 'byteLength', 'contentDigestSha256', 'canonicalDigestSha256', ...(current ? ['mediaType', 'source'] : [])], `Investigation manifest artifact ${index + 1}`);
+        const item = exact(candidate, ['sequence', 'id', 'schema', 'version', 'byteLength', 'contentDigestSha256', 'canonicalDigestSha256', ...(current ? ['mediaType', 'source'] : []), ...(withImageDerivation ? ['imageDerivation'] : [])], `Investigation manifest artifact ${index + 1}`);
         if (integer(item.sequence, 'Investigation manifest artifact sequence', 1, artifacts.length) !== index + 1 || item.id !== `artifact-${index + 1}`)
             fail('Investigation manifest artifact order');
         if (item.schema !== null)
@@ -162,6 +168,11 @@ export function validateInvestigationManifest(value) {
             digest(item.canonicalDigestSha256, 'Investigation manifest canonical digest');
         else if (item.canonicalDigestSha256 !== null || item.schema !== null || item.version !== null)
             fail('Opaque artefact JSON metadata');
+        if (withImageDerivation && item.imageDerivation !== null) {
+            readImageDerivationDeclaration(item.imageDerivation);
+            if (mediaType !== 'image/png')
+                fail('Image derivation media type');
+        }
         if (current) {
             const source = exact(item.source, ['identity', 'observedAt'], 'Artefact source');
             if (source.identity !== null)
@@ -189,12 +200,27 @@ export async function readInvestigationManifest(raw) {
         throw new TypeError('Investigation manifest failed its integrity check.');
     return value;
 }
+/** Matches selected manifest entries, not unselected attachment declarations. */
+export function investigationImageParentIncluded(manifest, artifact) {
+    if (!('imageDerivation' in artifact) || !artifact.imageDerivation)
+        return null;
+    const parent = artifact.imageDerivation.source;
+    return manifest.artifacts.some(entry => entry.id !== artifact.id
+        && entry.contentDigestSha256 === parent.digestSha256 && entry.byteLength === parent.byteLength);
+}
 export function formatInvestigationManifest(manifest) {
     const lines = ['Investigation manifest', `Workflow       ${manifest.workflow}`, `Tool version   ${manifest.application.version}`,
         `Artifacts      ${manifest.summary.artifactCount}`, `Total bytes    ${manifest.summary.totalBytes}`,
         `Configuration  ${manifest.configuration.digestSha256 ?? 'not supplied'}`, `Integrity      ${manifest.integrity.digestSha256}`, '', 'Ordered artefacts:'];
-    for (const artifact of manifest.artifacts)
+    for (const artifact of manifest.artifacts) {
         lines.push(`  ${artifact.sequence}. ${artifact.schema ?? (artifact.canonicalDigestSha256 ? 'unversioned JSON' : 'opaque file')}${artifact.version ? ` v${artifact.version}` : ''} · ${artifact.contentDigestSha256}`);
+        if ('imageDerivation' in artifact && artifact.imageDerivation) {
+            const declaration = artifact.imageDerivation;
+            lines.push(`     Declared image derivation: ${declaration.method}; ${declaration.operations.join(', ')}`, `     Parent: ${declaration.source.digestSha256} · ${declaration.source.byteLength} bytes`, `     Parent entry: ${investigationImageParentIncluded(manifest, artifact) ? 'declared in this manifest' : 'not declared in this manifest'}`, '     Declared edits are not proof of transformation or complete redaction.');
+        }
+        else if ('mediaType' in artifact && artifact.mediaType.startsWith('image/'))
+            lines.push('     Editing history: not declared');
+    }
     lines.push('', 'No source file paths or artefact contents are retained in this manifest.', '');
     return lines.join('\n');
 }

package/packages/investigation/link-intake.mjs

@@ -0,0 +1,209 @@
+import { canonicalRegistrableDomain } from "../analysis/registrable-domain.mjs";
+import { parseCredentialFreeHttpUrl } from "../evidence/lookup-target.mjs";
+import { MAX_INTAKE_LINKS, MAX_INTAKE_URL_LENGTH, MAX_EMBEDDED_LINK_DEPTH, MAX_AUTH_SCOPES } from "../contracts/message-intake.mjs";
+const EXCLUDED_INPUTS = {
+    malformed: 'Malformed or overlong links were not reviewed',
+    credentials: 'Links containing credentials were not reviewed',
+    protocol: 'Non-HTTP(S) links were not reviewed',
+    port: 'Links using non-default ports were not reviewed',
+    host: 'IP-address or non-registrable-host links were not reviewed',
+    qrNetwork: 'QR network settings were not interpreted',
+    qrContact: 'QR contact details were not interpreted',
+    qrProtocol: 'QR non-HTTP(S) payloads were not interpreted',
+    qrHost: 'QR hostnames without an HTTP(S) scheme were not offered for collection',
+    qrText: 'QR text without an HTTP(S) link was not interpreted',
+};
+const AUTH_KEYS = ['client_id', 'scope', 'redirect_uri', 'response_type', 'prompt'];
+const EMBEDDED_KEYS = new Set(['url', 'u', 'target', 'redirect', 'redirect_uri', 'redirect_url', 'return', 'returnurl', 'continue', 'next', 'dest', 'destination']);
+const safeIdentifier = (value) => value && /^[a-zA-Z0-9._~:-]{1,160}$/u.test(value) ? value : null;
+const tokens = (value) => (value ?? '').split(/\s+/u).filter(Boolean);
+export function reviewAuthorisationLink(url) {
+    const params = url.searchParams;
+    const authorisation = params.has('client_id') && (params.has('scope') || params.has('response_type') || params.has('redirect_uri'));
+    const device = /\/(?:device|devicecode|devicelogin)(?:\/|$)/iu.test(url.pathname);
+    if (!authorisation && !device)
+        return null;
+    const duplicateParameters = AUTH_KEYS.filter(key => params.getAll(key).length > 1);
+    const single = (key) => duplicateParameters.includes(key) ? null : params.get(key);
+    const scopes = tokens(single('scope'));
+    const retainedScopes = scopes.filter(scope => /^[a-zA-Z0-9._:/-]{1,160}$/u.test(scope)).slice(0, MAX_AUTH_SCOPES);
+    const redirect = parseCredentialFreeHttpUrl(single('redirect_uri'), MAX_INTAKE_URL_LENGTH);
+    const responseTypes = tokens(single('response_type')).filter(value => ['code', 'token', 'id_token', 'none'].includes(value));
+    const prompt = tokens(single('prompt')).filter(value => ['none', 'login', 'consent', 'select_account', 'create'].includes(value));
+    return {
+        kind: authorisation ? 'authorisation_parameters' : 'device_code_reference',
+        clientId: safeIdentifier(single('client_id')), scopes: retainedScopes,
+        redirectOrigin: redirect?.origin ?? null, responseTypes, prompt, duplicateParameters,
+        omittedParameters: scopes.length !== retainedScopes.length || (params.has('client_id') && !safeIdentifier(single('client_id')))
+            || (params.has('redirect_uri') && !redirect) || tokens(single('response_type')).length !== responseTypes.length
+            || tokens(single('prompt')).length !== prompt.length,
+    };
+}
+export function refangIntakeUrl(raw) {
+    // Only the scheme and authority are defanged. Path/query/fragment bytes may be
+    // significant to an exact supplied target, even when they resemble defanging.
+    return raw.replace(/^(https?|hxxps?)(?::|\[:\])\/\/([^/?#]*)/iu, (_match, scheme, authority) => `${scheme.toLowerCase().replace('hxxp', 'http')}://${authority.replace(/\[\.\]|\(\.\)/gu, '.')}`);
+}
+const HTTP_PREFIX = /^(?:https?|hxxps?)(?::|\[:\])\/\//iu;
+function proseUrl(value) {
+    // Prose delimiters are not part of a URL; balanced path brackets are. Direct
+    // supplied links bypass this text-scanning cleanup entirely.
+    let result = value.replace(/[.,;!?]+$/u, '');
+    let round = 0, square = 0;
+    for (const char of result) {
+        if (char === '(')
+            round++;
+        else if (char === ')')
+            round--;
+        else if (char === '[')
+            square++;
+        else if (char === ']')
+            square--;
+    }
+    for (;;) {
+        const end = result.at(-1);
+        if (end === ')' && round < 0)
+            round++;
+        else if (end === ']' && square < 0)
+            square++;
+        else
+            return result;
+        result = result.slice(0, -1).replace(/[.,;!?]+$/u, '');
+    }
+}
+function admittedDestination(url, registrationDomain, normalisation = []) {
+    return { state: 'parsed', hostname: url.hostname, origin: url.origin, registrationDomain,
+        hasPrivateLocation: url.pathname !== '/' || Boolean(url.search || url.hash), normalisation };
+}
+export function projectIntakeDestination(value, allowBareHostname = false) {
+    const empty = (state) => ({ state, hostname: null, origin: null, registrationDomain: null, hasPrivateLocation: false, normalisation: [] });
+    if (value.length > MAX_INTAKE_URL_LENGTH)
+        return empty('unsupported');
+    const bounded = value.trim();
+    if (!bounded)
+        return empty('missing');
+    if (/[\s\\\p{Cf}]/u.test(bounded))
+        return empty('unsupported');
+    const explicitScheme = HTTP_PREFIX.test(bounded);
+    if (!explicitScheme && !allowBareHostname)
+        return empty('unsupported');
+    const refanged = refangIntakeUrl(explicitScheme ? bounded : `https://${bounded}`);
+    const parsed = parseCredentialFreeHttpUrl(refanged, MAX_INTAKE_URL_LENGTH);
+    const registrationDomain = parsed && canonicalRegistrableDomain(parsed.hostname);
+    if (!parsed || !registrationDomain || parsed.port)
+        return empty('unsupported');
+    return admittedDestination(parsed, registrationDomain, [
+        ...(!explicitScheme ? ['assumed_https_for_hostname_parsing'] : []),
+        ...(refanged !== (explicitScheme ? bounded : `https://${bounded}`) ? ['refanged_scheme_or_authority'] : []),
+        ...(/[^\x00-\x7f]/u.test(bounded.split(/[/?#]/u).slice(0, explicitScheme ? 3 : 1).join('/')) ? ['unicode_hostname_to_ascii'] : []),
+    ]);
+}
+export function compareIntakeDestinations(displayed, destination) {
+    return displayed.state !== 'parsed' || destination.state !== 'parsed' ? 'insufficient_evidence'
+        : displayed.hostname === destination.hostname ? 'same_host' : 'different_host';
+}
+function displayedHost(value) {
+    return projectIntakeDestination(value, true).hostname;
+}
+/** No resolution or request occurs here; embedded targets remain supplied text. */
+export function createLinkIntake() {
+    const links = [], targets = [];
+    const seen = new Set();
+    const exclusions = new Map();
+    let rejected = 0, bounded = false;
+    function exclude(reason, isLink = true) {
+        if (isLink)
+            rejected++;
+        exclusions.set(reason, (exclusions.get(reason) ?? 0) + 1);
+    }
+    function add(raw, source, displayed = '', parentId = null, depth = 0, location) {
+        if (links.length >= MAX_INTAKE_LINKS) {
+            bounded = true;
+            return;
+        }
+        const value = refangIntakeUrl(raw.trim());
+        const url = parseCredentialFreeHttpUrl(value, MAX_INTAKE_URL_LENGTH);
+        if (!url) {
+            let reason = 'malformed';
+            if (value.length <= MAX_INTAKE_URL_LENGTH && !/[\x00-\x20\x7f]/u.test(value)) {
+                try {
+                    const parsed = new URL(value);
+                    if (!['http:', 'https:'].includes(parsed.protocol))
+                        reason = 'protocol';
+                    else if (parsed.username || parsed.password)
+                        reason = 'credentials';
+                }
+                catch { /* Retain only the fixed malformed-input category. */ }
+            }
+            exclude(reason);
+            return;
+        }
+        if (url.port) {
+            exclude('port');
+            return;
+        }
+        const registrationDomain = canonicalRegistrableDomain(url.hostname);
+        if (!registrationDomain) {
+            exclude('host');
+            return;
+        }
+        const shown = displayedHost(displayed);
+        const key = JSON.stringify([url.href, source, parentId, shown, location ?? null]);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const id = `link-${links.length + 1}`;
+        // Compare the already admitted canonical URL, not its differently bounded raw spelling.
+        const compared = compareIntakeDestinations(projectIntakeDestination(displayed, true), admittedDestination(url, registrationDomain));
+        links.push({ id, origin: url.origin, hostname: url.hostname, registrationDomain,
+            source, ...(location ? { location } : {}), parentId, displayedHostname: shown, displayedDestination: compared === 'insufficient_evidence' ? 'not_a_hostname' : compared,
+            hasPrivateLocation: url.pathname !== '/' || Boolean(url.search || url.hash), authorisation: reviewAuthorisationLink(url) });
+        targets.push({ id, exactUrl: url.href });
+        for (const [name, value] of url.searchParams) {
+            if (!EMBEDDED_KEYS.has(name.toLowerCase()) || !HTTP_PREFIX.test(value))
+                continue;
+            if (depth >= MAX_EMBEDDED_LINK_DEPTH) {
+                bounded = true;
+                continue;
+            }
+            add(value, 'embedded_parameter', '', id, depth + 1, location);
+        }
+    }
+    function addText(text, source = 'text', location) {
+        // The caller admits bytes before this scan; iteration stops at the work bound.
+        for (const match of text.matchAll(/(?:https?|hxxps?)(?::|\[:\])\/\/[^\s<>"'`]+/giu)) {
+            add(match[0].length > MAX_INTAKE_URL_LENGTH ? match[0] : proseUrl(match[0]), source, '', null, 0, location);
+            if (links.length >= MAX_INTAKE_LINKS) {
+                bounded = true;
+                break;
+            }
+        }
+    }
+    function addQr(text, source = 'qr', location) {
+        const value = refangIntakeUrl(text.trim());
+        const scheme = /^([a-z][a-z0-9+.-]*):/iu.exec(value)?.[1]?.toLowerCase();
+        if (/^WIFI:/iu.test(value)) {
+            exclude('qrNetwork', false);
+            return;
+        }
+        if (/^(?:BEGIN:VCARD|MECARD:)/iu.test(value)) {
+            exclude('qrContact', false);
+            return;
+        }
+        if (scheme && !['http', 'https'].includes(scheme)) {
+            exclude('qrProtocol', false);
+            return;
+        }
+        if (!/(?:https?|hxxps?):\/\//iu.test(value)) {
+            exclude(displayedHost(value) ? 'qrHost' : 'qrText', false);
+            return;
+        }
+        addText(value, source, location);
+    }
+    return { add, addText, addQr, result: () => ({ links: [...links], targets: [...targets], rejected, bounded,
+            limitations: Object.keys(EXCLUDED_INPUTS).flatMap(reason => {
+                const count = exclusions.get(reason);
+                return count ? [`${EXCLUDED_INPUTS[reason]} (${count}).`] : [];
+            }),
+        }) };
+}

package/packages/investigation/lookup-asset-graph.mjs

@@ -1,7 +1,7 @@
 import { LOOKUP_ASSET_GRAPH_SCHEMA, LOOKUP_ASSET_GRAPH_VERSION, MAX_LOOKUP_ASSET_LIMITATIONS, } from "../contracts/investigation-portability.mjs";
 import { MAX_PROFILE_VALUES } from "../contracts/workspace-portability.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
-import { canonicalRegistrableDomain } from "../../lib/registrable-domain.mjs";
+import { canonicalRegistrableDomain } from "../analysis/registrable-domain.mjs";
 import { createGraphInputReader, graphInputIsIncomplete } from "./lookup-asset-graph-inputs.mjs";
 export { LOOKUP_ASSET_GRAPH_SCHEMA, LOOKUP_ASSET_GRAPH_VERSION };
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;

package/packages/investigation/mail-authentication-review.mjs

@@ -0,0 +1,222 @@
+import { lexicalSegments, normalizeHeaderDomain, addressDomains } from "./mail-header-identity.mjs";
+import { MAX_AUTHENTICATION_HEADERS, MAX_AUTHENTICATION_CLAUSES, MAX_AUTHENTICATION_VALUE_LENGTH, MAIL_AUTHENTICATION_METHODS, MAIL_AUTHENTICATION_PROPERTIES } from "../contracts/mail-authentication.mjs";
+const KEYWORD = /^[a-z][a-z0-9_-]{0,31}$/iu;
+const RESULTS = {
+    spf: ['pass', 'fail', 'softfail', 'neutral', 'none', 'temperror', 'permerror'],
+    dkim: ['pass', 'fail', 'policy', 'neutral', 'none', 'temperror', 'permerror'],
+    dmarc: ['pass', 'fail', 'none', 'temperror', 'permerror'],
+    arc: ['pass', 'fail', 'none'],
+};
+/** Remove comments, never quoted content. Keep separators so tokens cannot join. */
+function withoutComments(value) {
+    let depth = 0, quoted = false, escaped = false, output = '';
+    for (const character of value) {
+        if (escaped) {
+            if (!depth)
+                output += character;
+            escaped = false;
+            continue;
+        }
+        if (character === '\\' && (depth || quoted)) {
+            if (!depth)
+                output += character;
+            escaped = true;
+            continue;
+        }
+        if (depth) {
+            if (character === '(')
+                depth++;
+            else if (character === ')')
+                depth--;
+            continue;
+        }
+        if (character === '"')
+            quoted = !quoted;
+        if (!quoted && character === '(') {
+            depth = 1;
+            output += ' ';
+        }
+        else if (!quoted && character === ')')
+            return null;
+        else
+            output += character;
+    }
+    return depth || quoted || escaped ? null : output;
+}
+// Only the restricted, non-personal identifier projection enters a report.
+function serviceId(value) {
+    return /^[a-z0-9_.-]{1,253}$/iu.test(value) ? value : null;
+}
+function unquote(value) {
+    return value.startsWith('"') ? value.slice(1, -1).replace(/\\(.)/gu, '$1') : value;
+}
+function domainProperty(value) {
+    const direct = normalizeHeaderDomain(value) ?? normalizeHeaderDomain(value.startsWith('@') ? value.slice(1) : '');
+    if (direct)
+        return direct;
+    const domains = addressDomains([value]);
+    return domains.length === 1 ? domains[0] : null;
+}
+function properties(value) {
+    const result = new Map();
+    let rest = value.trim(), count = 0;
+    while (rest) {
+        if (++count > MAX_AUTHENTICATION_CLAUSES)
+            return { result, complete: false };
+        const match = /^([a-z][a-z0-9_-]*(?:\s*\.\s*[a-z][a-z0-9_-]*)?)\s*=\s*("(?:[^"\\]|\\.)*"|[^\s";]+)(?=\s|$)/iu.exec(rest);
+        if (!match)
+            return { result, complete: false };
+        const key = match[1].replaceAll(/\s/gu, '').toLowerCase();
+        const values = result.get(key) ?? [];
+        values.push(unquote(match[2]));
+        result.set(key, values);
+        rest = rest.slice(match[0].length).trim();
+    }
+    return { result, complete: true };
+}
+function domainsFromProperties(values) {
+    const domains = [];
+    const duplicateProperties = [];
+    let omitted = false;
+    for (const property of MAIL_AUTHENTICATION_PROPERTIES) {
+        const supplied = values.get(property);
+        if (!supplied)
+            continue;
+        if (supplied.length !== 1) {
+            duplicateProperties.push(property);
+            continue;
+        }
+        const domain = domainProperty(supplied[0]);
+        if (domain)
+            domains.push({ property, domain });
+        else
+            omitted = true;
+    }
+    return { domains, duplicateProperties, omitted };
+}
+function readHeader(input, part, headerIndex, duplicateOf) {
+    const headerName = input.name;
+    const base = { part, headerIndex, headerName, duplicateOf, receiverTrust: 'not_established' };
+    const issues = new Set();
+    const invalid = (issue) => ({ ...base, authservId: null, state: 'malformed', claims: [], issues: [issue] });
+    if (input.value.length > MAX_AUTHENTICATION_VALUE_LENGTH)
+        return invalid('Header value exceeds the authentication review bound.');
+    if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]|\p{Default_Ignorable_Code_Point}/u.test(input.value))
+        return invalid('Header value contains unsupported control characters.');
+    const segments = lexicalSegments(input.value, ';');
+    if (!segments)
+        return invalid('Header has unbalanced quoting or comments.');
+    const clauses = segments.slice(0, MAX_AUTHENTICATION_CLAUSES + 1).map(withoutComments);
+    if (clauses.some(value => value === null))
+        return invalid('Header comments could not be parsed.');
+    if (segments.length > MAX_AUTHENTICATION_CLAUSES + 1)
+        issues.add('Some clauses exceed the authentication review bound.');
+    if (headerName === 'received-spf') {
+        const first = /^\s*([a-z][a-z0-9_-]*)\b(.*)$/iu.exec(clauses.shift() ?? '');
+        if (!first || !KEYWORD.test(first[1]))
+            return invalid('The reported SPF result is malformed.');
+        const supplied = properties([first[2], ...clauses].join(' '));
+        const receiver = supplied.result.get('receiver');
+        const authservId = receiver?.length === 1 ? serviceId(receiver[0]) : null;
+        if (!supplied.complete)
+            issues.add('Some SPF properties could not be parsed.');
+        if (receiver && (receiver.length !== 1 || !authservId))
+            issues.add('The receiver identifier is ambiguous or outside the retained identifier format.');
+        const renamed = new Map(supplied.result);
+        for (const [key, property] of [['envelope-from', 'smtp.mailfrom'], ['helo', 'smtp.helo']]) {
+            if (supplied.result.has(key))
+                renamed.set(property, supplied.result.get(key));
+        }
+        const projected = domainsFromProperties(renamed);
+        if (projected.omitted)
+            issues.add('Some identity properties cannot be represented as domains.');
+        if (projected.duplicateProperties.length)
+            issues.add('Repeated identity properties were retained as ambiguous, without selecting a value.');
+        const result = first[1].toLowerCase();
+        if (!RESULTS.spf.includes(result))
+            issues.add('The reported SPF result is unsupported.');
+        return { ...base, authservId, state: issues.size ? 'partial' : 'parsed', claims: [{ method: 'spf', methodVersion: 1, result,
+                    state: RESULTS.spf.includes(result) ? 'reported' : 'unsupported', domains: projected.domains, duplicateProperties: projected.duplicateProperties }], issues: [...issues] };
+    }
+    const first = /^\s*("(?:[^"\\]|\\.)*"|[^\s";]+)(?:\s+(\d{1,9}))?\s*$/u.exec(clauses.shift() ?? '');
+    if (!first)
+        return invalid('The authentication service identifier or header version is malformed.');
+    const authservId = serviceId(unquote(first[1]));
+    if (!authservId)
+        issues.add('The service identifier is outside the retained non-personal identifier format.');
+    if (first[2] && first[2] !== '1')
+        return { ...base, authservId, state: 'unsupported', claims: [], issues: ['The header declares an unsupported authentication-results version.'] };
+    if (clauses.length === 1 && clauses[0].trim().toLowerCase() === 'none')
+        return { ...base, authservId, state: 'none', claims: [], issues: [...issues] };
+    const claims = [];
+    if (!clauses.length)
+        issues.add('The header does not contain a result clause.');
+    for (const clause of clauses) {
+        const match = /^\s*([a-z][a-z0-9_-]*)(?:\s*\/\s*(\d{1,9}))?\s*=\s*([a-z][a-z0-9_-]*)(?=\s|$)(.*)$/iu.exec(clause);
+        if (!match || !KEYWORD.test(match[1]) || !KEYWORD.test(match[3])) {
+            issues.add('A result clause is malformed.');
+            continue;
+        }
+        const method = match[1].toLowerCase();
+        if (!MAIL_AUTHENTICATION_METHODS.includes(method)) {
+            issues.add('A reported authentication method is outside this review.');
+            continue;
+        }
+        const supplied = properties(match[4]);
+        const projected = domainsFromProperties(supplied.result);
+        if (!supplied.complete)
+            issues.add('Some result properties could not be parsed.');
+        if (projected.omitted)
+            issues.add('Some identity properties cannot be represented as domains.');
+        if (projected.duplicateProperties.length)
+            issues.add('Repeated identity properties were retained as ambiguous, without selecting a value.');
+        const known = method, result = match[3].toLowerCase(), methodVersion = Number(match[2] ?? 1);
+        const state = methodVersion === 1 && RESULTS[known].includes(result) ? 'reported' : 'unsupported';
+        if (state === 'unsupported')
+            issues.add('A method version or result is unsupported.');
+        claims.push({ method: known, methodVersion, result, state, domains: projected.domains, duplicateProperties: projected.duplicateProperties });
+    }
+    return { ...base, authservId, state: issues.size ? claims.length ? 'partial' : 'malformed' : 'parsed', claims, issues: [...issues] };
+}
+/** Physical header order is preserved. Equal service names never imply trust. */
+export function reviewMailAuthentication(fields, part = 1, maximumHeaders = MAX_AUTHENTICATION_HEADERS) {
+    if (!Number.isSafeInteger(part) || part < 1 || !Number.isSafeInteger(maximumHeaders) || maximumHeaders < 0 || maximumHeaders > MAX_AUTHENTICATION_HEADERS)
+        throw new TypeError('Invalid authentication review bounds.');
+    const headers = [], previous = new Map();
+    let omittedHeaders = 0;
+    for (const [index, field] of fields.entries()) {
+        if (!['authentication-results', 'received-spf'].includes(field.name))
+            continue;
+        if (headers.length >= maximumHeaders) {
+            omittedHeaders++;
+            continue;
+        }
+        // Do not retain an oversized raw value in the temporary duplicate index.
+        const key = field.value.length <= MAX_AUTHENTICATION_VALUE_LENGTH ? `${field.name}:${field.value}` : null;
+        const duplicateOf = key === null ? null : previous.get(key) ?? null;
+        headers.push(readHeader(field, part, index + 1, duplicateOf));
+        if (key !== null && duplicateOf === null)
+            previous.set(key, index + 1);
+    }
+    return { headers, omittedHeaders };
+}
+export function selectReceiverTrust(review, selected) {
+    if (!Array.isArray(selected) || selected.length > MAX_AUTHENTICATION_HEADERS || new Set(selected).size !== selected.length
+        || selected.some(value => !/^[1-9]\d{0,5}:[1-9]\d{0,5}$/u.test(value)
+            || !review.headers.some(header => `${header.part}:${header.headerIndex}` === value && header.authservId !== null && ['parsed', 'partial', 'none'].includes(header.state)))) {
+        throw new TypeError('Select each recognised receiver header by part:header-index; unidentified, malformed and unsupported headers cannot be trusted.');
+    }
+    return { ...review, headers: review.headers.map(header => ({ ...header, receiverTrust: selected.includes(`${header.part}:${header.headerIndex}`) ? 'analyst_selected' : 'not_established' })) };
+}
+export function authenticationHeaderLabel(header) {
+    return `Part ${header.part}, header ${header.headerIndex} · ${header.headerName} · ${header.authservId ?? 'service unidentified'}`;
+}
+/** Compatibility summary only: all parsed sources, with no receiver-trust verdict. */
+export function aggregateMailAuthentication(review) {
+    const known = new Set(['fail', 'neutral', 'none', 'pass', 'permerror', 'softfail', 'temperror']);
+    return Object.fromEntries(MAIL_AUTHENTICATION_METHODS.map(method => {
+        const claims = review.headers.flatMap(header => header.claims.filter(claim => claim.method === method));
+        const states = new Set(claims.map(claim => claim.state === 'reported' && known.has(claim.result) ? claim.result : 'unknown'));
+        return [method, { state: states.size > 1 ? 'mixed' : [...states][0] ?? 'unknown', observations: claims.length }];
+    }));
+}