@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/investigation/lookup-claim-readiness.mjs

@@ -21,6 +21,24 @@ export const LOOKUP_CLAIM_REQUIREMENT_IDS = [
     'reviewed-case-recipient',
     'authoritative-rdap',
 ];
+const CLAIM_QUESTIONS = Object.freeze({
+    'registration-state': 'What does the registration authority establish?',
+    'current-web-observation': 'What was the website doing at the observed time?',
+    'brand-resemblance': 'Does the observed page resemble the reviewed Brand?',
+    'controlled-change': 'Which registration and DNS dependencies need review?',
+    'incident-response': 'What evidence and recipient route support a response?',
+    'network-context': 'What does the authoritative network record establish?',
+});
+/** A presentation of existing readiness, not a new verdict or collection plan. */
+export function lookupQuestionsNeedingEvidence(readiness) {
+    return readiness.entries.filter((entry) => entry.state !== 'ready').map((entry) => ({
+        id: entry.id,
+        question: CLAIM_QUESTIONS[entry.id],
+        href: entry.href,
+        requirements: entry.requirements.filter((requirement) => requirement.state !== 'complete'),
+        limitations: entry.limitations,
+    }));
+}
 const MAX_TEXT = 320;
 const MAX_DIAGNOSTICS = 12;
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;

package/packages/investigation/lookup-investigation-brief.mjs

@@ -40,7 +40,7 @@ export function buildLookupInvestigationBrief(input) {
     const limitedSources = input.quality.entries
         .filter((entry) => entry.state !== 'complete')
         .map((entry) => `${entry.label}: ${entry.statusLabel}`);
-    const graphKinds = uniqueText(input.graph.edges.map((edge) => edge.label), 12);
+    const graphKinds = uniqueText(input.graph.edges.map((edge) => edge.label), 64);
     const brief = Object.freeze({
         schema: LOOKUP_INVESTIGATION_BRIEF_SCHEMA,
         schemaVersion: LOOKUP_INVESTIGATION_BRIEF_VERSION,
@@ -66,10 +66,10 @@ export function buildLookupInvestigationBrief(input) {
             kinds: Object.freeze(graphKinds),
         }),
         limitations: Object.freeze(uniqueText([
-            ...limitedSources,
-            ...input.graph.limitations,
             'This brief is a deterministic organisation of collected and derived evidence, not an attribution, ownership, safety, availability, or maliciousness conclusion.',
             'Analyst assertions, hypotheses, and decisions must remain separate from observed evidence.',
+            ...input.graph.limitations,
+            ...limitedSources,
         ])),
     });
     if (new TextEncoder().encode(JSON.stringify(brief)).byteLength > MAX_LOOKUP_INVESTIGATION_BRIEF_BYTES) {

package/packages/investigation/lookup-task-guidance.mjs

@@ -0,0 +1,58 @@
+export const LOOKUP_GUIDANCE_TASKS = Object.freeze([
+    'general',
+    'acquisition',
+    'brand',
+    'incident',
+    'owned',
+]);
+const GUIDANCE = Object.freeze({
+    general: Object.freeze({
+        task: 'general',
+        label: 'General investigation',
+        recommendation: 'fast',
+        reason: 'Fast starts with authority-aware registration and availability evidence before a broader collection is justified.',
+        requestExplanation: 'Fast requests the existing lower-request authority and RDAP registration path and omits WHOIS, DNS, HTTP, TLS, network-context, and optional intelligence branches.',
+        limitation: 'A Fast result can still be partial, unavailable, or inconclusive. Use Deep only when the question needs the additional source families.',
+    }),
+    brand: Object.freeze({
+        task: 'brand',
+        label: 'Brand review',
+        recommendation: 'deep',
+        reason: 'Deep provides the existing source-qualified web, DNS, TLS, registration, and relationship context used by brand review.',
+        requestExplanation: 'Deep requests the existing registry RDAP, WHOIS, domain evidence, registrar RDAP, DNS, HTTP, TLS, and network-context branches. Optional intelligence sources receive data only when separately selected.',
+        limitation: 'Deep is broader, not complete or authoritative for every question. Missing and conflicting sources remain explicit.',
+    }),
+    acquisition: Object.freeze({
+        task: 'acquisition',
+        label: 'Acquisition review',
+        recommendation: 'deep',
+        reason: 'Deep provides the existing bounded registration, web, DNS, TLS, and uncertainty context expected by acquisition review.',
+        requestExplanation: 'Deep uses the existing request budget and source branches. It does not appraise a domain, contact a seller, or establish clean title or legal sufficiency.',
+        limitation: 'The recommendation organises due diligence; it does not make an acquisition recommendation or guarantee completeness.',
+    }),
+    incident: Object.freeze({
+        task: 'incident',
+        label: 'Incident response',
+        recommendation: 'deep',
+        reason: 'Deep collects the web, DNS, TLS, registration, and network evidence needed to review an incident and choose a response route.',
+        requestExplanation: 'Deep requests the existing source branches. It does not submit a report, test a published contact, or establish responsibility for the observed content.',
+        limitation: 'Collection supports review; it does not determine maliciousness or authorise a response.',
+    }),
+    owned: Object.freeze({
+        task: 'owned',
+        label: 'Owned-domain posture',
+        recommendation: 'deep',
+        reason: 'Deep collects the current registration, DNS, TLS, mail, and web observations needed for a source-by-source posture review.',
+        requestExplanation: 'Deep uses the existing bounded source branches. Retained baselines remain separate and must be compared using their observation times and source states.',
+        limitation: 'A changed or missing observation does not by itself establish compromise, remediation, or control.',
+    }),
+});
+export const LOOKUP_TASK_VIEWS = Object.freeze(LOOKUP_GUIDANCE_TASKS.map((task) => Object.freeze({
+    id: task,
+    label: GUIDANCE[task].label,
+})));
+export function lookupTaskGuidance(task) {
+    return typeof task === 'string' && LOOKUP_GUIDANCE_TASKS.includes(task)
+        ? GUIDANCE[task]
+        : GUIDANCE.general;
+}

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 }];
+    }));
+}

package/packages/investigation/mail-header-identity.mjs

@@ -0,0 +1,209 @@
+import { isValidAsciiDomainName } from "../contracts/domain-name.mjs";
+import { MAIL_AUTHENTICATION_METHODS } from "../contracts/mail-authentication.mjs";
+export const MAX_MAIL_REVIEW_DOMAINS = 128;
+export const AUTHENTICATION_METHODS = MAIL_AUTHENTICATION_METHODS;
+export function normalizeHeaderDomain(value) {
+    const normalized = value.trim().toLowerCase().replace(/^\[|\]$/gu, '').replace(/\.$/u, '');
+    return isValidAsciiDomainName(normalized, { requireLowercase: true }) ? normalized : null;
+}
+export 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);
+}
+export 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();
+}
+export function messageIdDomains(values) {
+    return addressDomains(values.map((value) => value.replace(/[<>]/gu, '')));
+}
+export 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);
+}
+export 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);
+}