@slicedearth/whoisleuth-cli 2.5.1 → 2.7.0

package/packages/investigation/intake-context.mjs

@@ -0,0 +1,284 @@
+import { parseBoundedJson } from "../analysis/bounded-json.mjs";
+import { exact, exactOptional, enumeration, text, array, integer } from "../evidence/artifact-structure.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { INTAKE_DISTRIBUTION_CHANNELS, MAX_INTAKE_INDICATORS, MAX_INTAKE_INDICATOR_CANDIDATES, INTAKE_TEXT_BASES, INTAKE_PHONE_ROLES, MAX_INTAKE_URL_LENGTH, } from "../contracts/message-intake.mjs";
+import { canonicalIpAddress } from "../contracts/ip-address.mjs";
+import { phoneCandidateValue, validatePhoneReview, MAX_SELECTED_INTAKE_PHONES, MAX_INTAKE_PHONE_CHARACTERS } from "./intake-phones.mjs";
+import { compareIntakeDestinations, projectIntakeDestination } from "./link-intake.mjs";
+export const INTAKE_CONTEXT_SCHEMA = 'whoisleuth.intake-context';
+export const INTAKE_CONTEXT_VERSION = 1;
+export const INTAKE_CONTEXT_SELECTION_VERSION = 2;
+export const MAX_INTAKE_CONTEXT_BYTES = 8_192;
+export const INTAKE_SELECTED_EVIDENCE_LIMITATIONS = [
+    'Selected contact values are supplied candidates, not verified numbers, ownership, common control or independent corroboration.',
+    'Source labels, roles, country context and observation times are analyst declarations; a digest identifies selected bytes, not authorship or capture time.',
+    'Selected phone values and private source text are excluded from public and trusted Case summaries and are not mapped to STIX or MISP; use the deliberately selected private review only.',
+    'Destination pairs compare supplied hostnames only. Exact entered URLs are not retained, redirects are not followed, and a mismatch does not establish phishing.',
+];
+function label(value, name, maximum, nullable = true) {
+    if (nullable && (value === null || value === ''))
+        return null;
+    const result = text(value, name, maximum);
+    if (!result.trim())
+        throw new TypeError(`${name} cannot be blank.`);
+    if (/@|:\/\/|[?&][^\s=]+=/u.test(result))
+        throw new TypeError(`${name} must be a non-sensitive label, not an address or exact URL.`);
+    return result;
+}
+function declarationFields(input) {
+    const observedAt = input.observedAt === null ? null : normalizeExplicitIsoTimestamp(input.observedAt);
+    if (input.observedAt !== null && !observedAt)
+        throw new TypeError('Declared observation time requires an explicit timezone.');
+    const sourceLabel = label(input.sourceLabel, 'Selected evidence source label', 160, false);
+    if (/\p{Cf}|\d[\d ()+\-\u00a0]{5,}\d/u.test(sourceLabel))
+        throw new TypeError('Use a non-sensitive source label, not a contact number or identifier.');
+    return { sourceLabel, observedAt, basis: enumeration(input.basis, INTAKE_TEXT_BASES, 'Selected text basis') };
+}
+export function readIntakePhoneDeclaration(raw) {
+    const input = exact(raw, ['sourceLabel', 'observedAt', 'basis', 'role', 'countryCallingCode'], 'Phone declaration');
+    if (input.countryCallingCode !== null && (typeof input.countryCallingCode !== 'string' || !/^\+[1-9][0-9]{0,2}$/u.test(input.countryCallingCode)))
+        throw new TypeError('Country calling context must be an explicitly supplied + prefix of one to three digits, or unknown.');
+    return { ...declarationFields(input), role: enumeration(input.role, INTAKE_PHONE_ROLES, 'Phone role'), countryCallingCode: input.countryCallingCode };
+}
+function destinationDeclaration(raw, displayed) {
+    const input = exact(raw, ['sourceLabel', 'observedAt', 'basis', 'role'], 'Destination declaration');
+    return { ...declarationFields(input), role: enumeration(input.role, displayed ? ['displayed_claim'] : ['claimed_landing', 'supplied_redirect'], 'Destination evidence role') };
+}
+function phoneMeaning(original, declaration) {
+    const parsed = phoneCandidateValue(original);
+    if (parsed.state === 'unsupported')
+        throw new TypeError('Unsupported phone candidates cannot be selected.');
+    const conflict = parsed.canonical && declaration.countryCallingCode && !parsed.canonical.startsWith(declaration.countryCallingCode);
+    return { canonical: conflict ? null : parsed.canonical, extension: parsed.extension,
+        state: conflict ? 'country_context_conflict' : parsed.state };
+}
+/** A deliberate projection: unselected candidates and exact paired URLs never enter the report. */
+export function withIntakeSelectedEvidence(result, raw) {
+    if (result.report.schemaVersion !== 2)
+        throw new TypeError('Historical intake reports require a fresh review before selecting evidence.');
+    if (raw === null) {
+        const { selectedEvidence: _removed, ...report } = result.report;
+        return report;
+    }
+    const input = exact(raw, ['sourceDigestSha256', 'phones', 'destinationPair'], 'Selected intake evidence');
+    if (input.sourceDigestSha256 !== result.report.source.digestSha256)
+        throw new TypeError('Selected evidence does not identify this complete input digest.');
+    validatePhoneReview(result);
+    const phones = [];
+    const seenSpans = new Set(), groups = new Map();
+    for (const rawSelection of array(input.phones, 'Selected phone spans', MAX_SELECTED_INTAKE_PHONES)) {
+        const selection = exact(rawSelection, ['start', 'end', 'declaration'], 'Selected phone span');
+        if (!result.phoneReview)
+            throw new TypeError('Phone selections require a fresh plaintext review.');
+        const start = integer(selection.start, 'Phone span start', 0, result.phoneReview.sourceTextLength), end = integer(selection.end, 'Phone span end', start + 1, result.phoneReview.sourceTextLength);
+        const candidate = result.phoneReview.candidates.find(item => item.start === start && item.end === end);
+        const span = `${start}:${end}`;
+        if (!candidate || seenSpans.has(span))
+            throw new TypeError('Select each exact reviewed phone span at most once.');
+        seenSpans.add(span);
+        const declaration = readIntakePhoneDeclaration(selection.declaration), meaning = phoneMeaning(candidate.original, declaration);
+        // Group only safely canonicalised equivalent observations; keep every exact source occurrence.
+        const key = meaning.canonical ? JSON.stringify([meaning.canonical, meaning.extension, declaration]) : span;
+        const occurrence = { original: candidate.original, start, end }, existing = groups.get(key);
+        if (existing === undefined) {
+            groups.set(key, phones.length);
+            phones.push({ ...meaning, declaration, occurrences: [occurrence] });
+        }
+        else
+            phones[existing].occurrences.push(occurrence);
+    }
+    let destinationPair = null;
+    if (input.destinationPair !== null) {
+        const pair = exact(input.destinationPair, ['displayed', 'destination', 'displayedDeclaration', 'destinationDeclaration'], 'Supplied destination pair');
+        for (const value of [pair.displayed, pair.destination])
+            if (typeof value !== 'string' || value.length > MAX_INTAKE_URL_LENGTH)
+                throw new TypeError('Supplied destination values exceed the bounded text limit.');
+        const displayed = projectIntakeDestination(pair.displayed, true), destination = projectIntakeDestination(pair.destination, true);
+        destinationPair = { displayed, destination, displayedDeclaration: destinationDeclaration(pair.displayedDeclaration, true), destinationDeclaration: destinationDeclaration(pair.destinationDeclaration, false), state: compareIntakeDestinations(displayed, destination) };
+    }
+    const selectedEvidence = { version: 1, sourceDigestSha256: result.report.source.digestSha256,
+        phoneCoverage: result.phoneReview ? { state: result.phoneReview.state, candidatesReviewed: result.phoneReview.candidatesReviewed, candidatesShown: result.phoneReview.candidates.length } : { state: 'not_reviewed', candidatesReviewed: 0, candidatesShown: 0 },
+        sourceTextLength: result.phoneReview?.sourceTextLength ?? null, offsetUnit: 'utf16_code_unit', phones, destinationPair, limitations: [...INTAKE_SELECTED_EVIDENCE_LIMITATIONS] };
+    const report = { ...result.report, selectedEvidence };
+    validateIntakeSelectedEvidence(report);
+    return report;
+}
+function validateDestinationProjection(raw) {
+    const input = exact(raw, ['state', 'hostname', 'origin', 'registrationDomain', 'hasPrivateLocation', 'normalisation'], 'Retained destination projection');
+    enumeration(input.state, ['parsed', 'missing', 'unsupported'], 'Destination state');
+    if (typeof input.hasPrivateLocation !== 'boolean')
+        throw new TypeError('Destination privacy state is malformed.');
+    const flags = array(input.normalisation, 'Destination normalisation', 3);
+    for (const flag of flags)
+        enumeration(flag, ['assumed_https_for_hostname_parsing', 'refanged_scheme_or_authority', 'unicode_hostname_to_ascii'], 'Destination normalisation');
+    if (new Set(flags).size !== flags.length)
+        throw new TypeError('Destination normalisation is duplicated.');
+    if (input.state === 'parsed') {
+        if (typeof input.origin !== 'string')
+            throw new TypeError('Retained destination origin is malformed.');
+        const parsed = projectIntakeDestination(input.origin);
+        if (parsed.state !== 'parsed' || parsed.origin !== input.origin || parsed.hostname !== input.hostname || parsed.registrationDomain !== input.registrationDomain || parsed.hasPrivateLocation)
+            throw new TypeError('Retained destinations must contain only a canonical origin and hostname.');
+    }
+    else if (input.hostname !== null || input.origin !== null || input.registrationDomain !== null || input.hasPrivateLocation || flags.length)
+        throw new TypeError('An unavailable destination cannot declare parsed values.');
+    return input;
+}
+export function validateIntakeSelectedEvidence(report) {
+    if (!Object.hasOwn(report, 'selectedEvidence'))
+        return;
+    if (report.schemaVersion !== 2)
+        throw new TypeError('Selected evidence requires intake version 2.');
+    const input = exact(report.selectedEvidence, ['version', 'sourceDigestSha256', 'sourceTextLength', 'phoneCoverage', 'offsetUnit', 'phones', 'destinationPair', 'limitations'], 'Retained selected evidence');
+    if (input.version !== 1 || input.sourceDigestSha256 !== report.source.digestSha256 || input.offsetUnit !== 'utf16_code_unit')
+        throw new TypeError('Unsupported selected-evidence version or source identity.');
+    const sourceLength = input.sourceTextLength === null ? null : integer(input.sourceTextLength, 'Selected source text length', 0, report.source.byteLength);
+    if (sourceLength !== null && report.source.kind !== 'text')
+        throw new TypeError('Only plaintext has phone source spans.');
+    const coverage = exact(input.phoneCoverage, ['state', 'candidatesReviewed', 'candidatesShown'], 'Retained phone coverage');
+    enumeration(coverage.state, ['reviewed', 'partial', 'not_reviewed'], 'Retained phone coverage');
+    const reviewed = integer(coverage.candidatesReviewed, 'Reviewed phone candidates', 0, MAX_INTAKE_INDICATOR_CANDIDATES), shown = integer(coverage.candidatesShown, 'Shown phone candidates', 0, MAX_INTAKE_INDICATORS);
+    if (reviewed < shown || (coverage.state === 'not_reviewed' ? sourceLength !== null || reviewed !== 0 || shown !== 0 : sourceLength === null))
+        throw new TypeError('Retained phone coverage is inconsistent.');
+    let occurrences = 0;
+    const spans = new Set();
+    for (const rawPhone of array(input.phones, 'Retained phone groups', MAX_SELECTED_INTAKE_PHONES)) {
+        if (report.source.kind !== 'text' || sourceLength === null)
+            throw new TypeError('Retained phones require plaintext source identity.');
+        const phone = exact(rawPhone, ['canonical', 'extension', 'state', 'declaration', 'occurrences'], 'Retained phone');
+        const declaration = readIntakePhoneDeclaration(phone.declaration);
+        for (const rawOccurrence of array(phone.occurrences, 'Retained phone occurrences', MAX_SELECTED_INTAKE_PHONES, 1)) {
+            if (++occurrences > MAX_SELECTED_INTAKE_PHONES)
+                throw new TypeError('Selected phone occurrences exceed their aggregate limit.');
+            const occurrence = exact(rawOccurrence, ['original', 'start', 'end'], 'Retained phone occurrence');
+            const start = integer(occurrence.start, 'Phone span start', 0, sourceLength), end = integer(occurrence.end, 'Phone span end', start + 1, sourceLength);
+            if (typeof occurrence.original !== 'string' || occurrence.original.length !== end - start || occurrence.original.length > MAX_INTAKE_PHONE_CHARACTERS || spans.has(`${start}:${end}`))
+                throw new TypeError('Retained phone occurrence is malformed or duplicated.');
+            spans.add(`${start}:${end}`);
+            const parsed = phoneMeaning(occurrence.original, declaration);
+            if (phone.canonical !== parsed.canonical || phone.extension !== parsed.extension || phone.state !== parsed.state)
+                throw new TypeError('Retained phone meaning contradicts its original text or declaration.');
+        }
+        if (phone.canonical === null && phone.occurrences.length !== 1)
+            throw new TypeError('Ambiguous phone occurrences cannot be merged.');
+    }
+    if (occurrences > shown)
+        throw new TypeError('Selected phone occurrences exceed the reviewed candidates.');
+    if (input.destinationPair !== null) {
+        const pair = exact(input.destinationPair, ['displayed', 'destination', 'displayedDeclaration', 'destinationDeclaration', 'state'], 'Retained destination pair');
+        const displayed = validateDestinationProjection(pair.displayed), destination = validateDestinationProjection(pair.destination);
+        destinationDeclaration(pair.displayedDeclaration, true);
+        destinationDeclaration(pair.destinationDeclaration, false);
+        if (pair.state !== compareIntakeDestinations(displayed, destination))
+            throw new TypeError('Destination comparison contradicts its retained hosts.');
+    }
+    if (JSON.stringify(input.limitations) !== JSON.stringify(INTAKE_SELECTED_EVIDENCE_LIMITATIONS))
+        throw new TypeError('Selected evidence must retain its privacy and source limitations.');
+}
+/** Existing v1 context remains supported; v2 selections are bound to the current transient review. */
+export function applyIntakeContextInput(result, input) {
+    const parsed = parseBoundedJson(input, { label: 'Intake context input', maximumBytes: MAX_INTAKE_CONTEXT_BYTES });
+    const root = exactOptional(parsed, ['schema', 'version', 'context'], ['review'], 'Intake context input');
+    if (root.schema !== INTAKE_CONTEXT_SCHEMA)
+        throw new TypeError('Unsupported intake context schema.');
+    if (root.version === 1)
+        return withIntakeDistributionContext(result.report, parseIntakeContextInput(input));
+    if (root.version !== INTAKE_CONTEXT_SELECTION_VERSION)
+        throw new TypeError('Unsupported intake context version.');
+    const report = withIntakeDistributionContext(result.report, root.context);
+    return Object.hasOwn(root, 'review') ? withIntakeSelectedEvidence({ ...result, report }, root.review) : report;
+}
+export function readIntakeDistributionContext(raw) {
+    if (raw === null)
+        return null;
+    const input = exact(raw, ['channel', 'observedAt', 'sourceLabel', 'reference', 'observerLabel', 'vantageLabel'], 'Supplied distribution context');
+    const observedAt = input.observedAt === null ? null : normalizeExplicitIsoTimestamp(input.observedAt);
+    if (input.observedAt !== null && !observedAt)
+        throw new TypeError('Declared observation time requires an explicit timezone.');
+    return {
+        channel: enumeration(input.channel, INTAKE_DISTRIBUTION_CHANNELS, 'Distribution channel'),
+        observedAt,
+        sourceLabel: label(input.sourceLabel, 'Context source label', 160, false),
+        reference: label(input.reference, 'Context reference', 160),
+        observerLabel: label(input.observerLabel, 'Observer label', 80),
+        vantageLabel: label(input.vantageLabel, 'Vantage label', 80),
+    };
+}
+export function parseIntakeContextInput(input) {
+    const root = exact(parseBoundedJson(input, {
+        label: 'Intake context input',
+        maximumBytes: MAX_INTAKE_CONTEXT_BYTES,
+    }), ['schema', 'version', 'context'], 'Intake context input');
+    if (root.schema !== INTAKE_CONTEXT_SCHEMA || root.version !== INTAKE_CONTEXT_VERSION)
+        throw new TypeError('Unsupported intake context schema or version.');
+    const result = readIntakeDistributionContext(root.context);
+    if (!result)
+        throw new TypeError('Supply an explicit distribution context.');
+    return result;
+}
+export function withIntakeDistributionContext(report, raw) {
+    if (report.schemaVersion !== 2)
+        throw new TypeError('Historical intake reports cannot acquire new declarations without a fresh review.');
+    return { ...report, distributionContext: readIntakeDistributionContext(raw) };
+}
+/** Validate only the versioned additions; this is not a general report importer. */
+export function validateIntakeExtensions(report) {
+    if (report.schemaVersion === 1) {
+        if (['indicators', 'indicatorCoverage', 'distributionContext', 'selectedEvidence'].some((key) => Object.hasOwn(report, key)))
+            throw new TypeError('Version-1 intake reports cannot declare version-2 evidence.');
+        return;
+    }
+    if (report.schemaVersion !== 2)
+        throw new TypeError('Unsupported intake report version.');
+    const locations = new Set([
+        'input',
+        ...report.messageParts.map((part) => `message-${part.part}`),
+        ...(report.documentReview?.parts.map((part) => part.id) ?? []),
+    ]);
+    array(report.indicators, 'Extracted indicators', MAX_INTAKE_INDICATORS).forEach((raw, index) => {
+        const value = exact(raw, ['id', 'kind', 'value', 'source', 'location', 'basis'], 'Extracted indicator');
+        const kind = enumeration(value.kind, ['ipv4', 'ipv6', 'md5', 'sha1', 'sha256'], 'Indicator kind');
+        const content = text(value.value, 'Indicator value', 64);
+        const location = exact(value.location, ['partId', 'page'], 'Indicator location');
+        if (value.id !== `indicator-${index + 1}` ||
+            value.basis !== 'literal_text' ||
+            !locations.has(String(location.partId)))
+            throw new TypeError('Indicator source reference is not present in this review.');
+        if (location.page !== null)
+            integer(location.page, 'Indicator page', 1, 100_000);
+        const source = enumeration(value.source, ['text', 'calendar', 'document_text'], 'Indicator source');
+        if (kind === 'ipv4' || kind === 'ipv6') {
+            if (canonicalIpAddress(content) !== content || content.includes(':') !== (kind === 'ipv6'))
+                throw new TypeError('Indicator IP address is not canonical.');
+        }
+        else if (!new RegExp(`^[a-f0-9]{${{ md5: 32, sha1: 40, sha256: 64 }[kind]}}$`, 'u').test(content))
+            throw new TypeError('Indicator hash is malformed.');
+        const part = report.documentReview?.parts.find((part) => part.id === location.partId);
+        if (part ? location.page !== part.page : location.page !== null)
+            throw new TypeError('Indicator page does not match its source part.');
+        const messageParts = report.messageParts.filter((part) => `message-${part.part}` === location.partId);
+        const validSource = source === 'document_text'
+            ? (report.source.kind === 'pdf' || report.source.kind === 'docx') && part?.kind === 'text'
+            : report.source.kind === 'email'
+                ? messageParts.length === 1
+                : location.partId === 'input' && report.source.kind === source;
+        if (!validSource)
+            throw new TypeError('Indicator source kind does not match the reviewed text part.');
+    });
+    const coverage = exact(report.indicatorCoverage, ['state', 'candidatesReviewed'], 'Indicator coverage');
+    enumeration(coverage.state, ['reviewed', 'partial', 'not_reviewed'], 'Indicator coverage');
+    const candidatesReviewed = integer(coverage.candidatesReviewed, 'Indicator candidate count', 0, MAX_INTAKE_INDICATOR_CANDIDATES);
+    if (candidatesReviewed < report.indicators.length ||
+        (coverage.state === 'not_reviewed' && candidatesReviewed !== 0))
+        throw new TypeError('Indicator coverage contradicts the retained observations.');
+    if (report.source.kind === 'identity' ||
+        report.source.kind === 'har' ||
+        report.source.kind === 'qr') {
+        if (report.indicators.length ||
+            coverage.state !== 'not_reviewed' ||
+            coverage.candidatesReviewed !== 0)
+            throw new TypeError('This input keeps its existing sensitive-data projection; indicator text was not reviewed.');
+    }
+    readIntakeDistributionContext(report.distributionContext);
+    validateIntakeSelectedEvidence(report);
+}

package/packages/investigation/intake-indicators.mjs

@@ -0,0 +1,116 @@
+import { canonicalIpAddress } from "../contracts/ip-address.mjs";
+import { MAX_INTAKE_INDICATORS, MAX_INTAKE_INDICATOR_CANDIDATES, } from "../contracts/message-intake.mjs";
+export const MAX_INTAKE_INDICATOR_TEXT = 2 * 1024 * 1024;
+export function minimiseIndicatorToken(token) {
+    if (token.includes('//') || token.includes('@'))
+        return ' ';
+    const unwrapped = token.replace(/^[([{,;]+|[)\]},;.!?]+$/gu, '');
+    // A bare IPv6 address or explicit hash label is an observation, not a URI.
+    // Other schemes include opaque forms such as data: and urn:, whose commas
+    // and nested hash labels must not enter the later indicator scanners.
+    if (unwrapped.length <= 98 && canonicalIpAddress(unwrapped))
+        return token;
+    // Field prefixes such as value= must not conceal an opaque URI. Match at
+    // token boundaries, not just the beginning, before any punctuation splitting.
+    for (const match of unwrapped.matchAll(/(?<![a-z0-9+.-])([a-z][a-z0-9+.-]*)(?::|\[:\])/giu)) {
+        if (!/^(?:md5|sha-?1|sha-?256)$/iu.test(match[1]))
+            return ' ';
+    }
+    return token;
+}
+/** Literal selected text only. A syntactic indicator is not a network target or threat verdict. */
+export function createIndicatorIntake() {
+    const indicators = [], seen = new Set();
+    let candidatesReviewed = 0, textReviewed = 0, partial = false, reviewed = false;
+    function admit(kind, value, source, location) {
+        const key = JSON.stringify([kind, value, source, location]);
+        if (seen.has(key))
+            return;
+        if (indicators.length >= MAX_INTAKE_INDICATORS) {
+            partial = true;
+            return;
+        }
+        seen.add(key);
+        indicators.push({
+            id: `indicator-${indicators.length + 1}`,
+            kind,
+            value,
+            source,
+            location: { ...location },
+            basis: 'literal_text',
+        });
+    }
+    function candidate() {
+        if (candidatesReviewed >= MAX_INTAKE_INDICATOR_CANDIDATES) {
+            partial = true;
+            return false;
+        }
+        candidatesReviewed++;
+        return true;
+    }
+    return {
+        markPartial() {
+            reviewed = true;
+            partial = true;
+        },
+        addText(value, source, location) {
+            reviewed = true;
+            if (partial || value.length > MAX_INTAKE_INDICATOR_TEXT - textReviewed) {
+                partial = true;
+                return;
+            }
+            textReviewed += value.length;
+            // Exclude complete URLs (including rejected/defanged URLs), addresses and
+            // credential-bearing lines before either scanner. Never scan raw HAR or
+            // identity-provider objects, message headers, script or style content.
+            const minimised = value
+                .replace(/^.*\b(?:authorization|proxy-authorization|cookie|set-cookie|password|passwd|access[_ -]?token|refresh[_ -]?token|session[_ -]?id|secret|api[_ -]?key|token)\s*[:=].*$/gimu, ' ')
+                .replace(/[^\s<>"'`]+/gu, minimiseIndicatorToken);
+            // Hashes require an explicit algorithm label. Bare opaque hexadecimal
+            // strings may be session material and are deliberately not interpreted.
+            for (const match of minimised.matchAll(/\b(md5|sha-?1|sha-?256)[ \t]*(?::|=|[ \t])[ \t]*([a-f0-9]+)\b/giu)) {
+                if (!candidate())
+                    return;
+                const kind = match[1].toLowerCase().replace('-', '');
+                const hash = match[2].toLowerCase();
+                if (hash.length === { md5: 32, sha1: 40, sha256: 64 }[kind])
+                    admit(kind, hash, source, location);
+            }
+            for (const match of minimised.matchAll(/[^\s<>"'`()\[\]{},;]+/gu)) {
+                const token = match[0];
+                if (!token.includes('.') && !token.includes(':'))
+                    continue;
+                if (!candidate())
+                    return;
+                if (token.length > 98)
+                    continue;
+                const raw = token.replace(/[.!?]+$/u, '');
+                const address = canonicalIpAddress(raw);
+                if (address)
+                    admit(address.includes(':') ? 'ipv6' : 'ipv4', address, source, location);
+            }
+        },
+        result() {
+            return {
+                indicators: [...indicators],
+                indicatorCoverage: {
+                    state: partial
+                        ? 'partial'
+                        : reviewed
+                            ? 'reviewed'
+                            : 'not_reviewed',
+                    candidatesReviewed,
+                },
+            };
+        },
+    };
+}
+/** Version-1 reports have no indicator coverage; absence is not reinterpreted. */
+export function intakeIndicators(report) {
+    return report.schemaVersion === 2 ? report.indicators : [];
+}
+export function intakeIndicatorSource(report, indicator) {
+    const document = report.documentReview?.parts.find((part) => part.id === indicator.location.partId);
+    const message = report.messageParts.find((part) => `message-${part.part}` === indicator.location.partId);
+    return document?.digestSha256 ?? message?.digestSha256 ?? report.source.digestSha256;
+}

package/packages/investigation/intake-phones.mjs

@@ -0,0 +1,155 @@
+import { MAX_INTAKE_INDICATORS, MAX_INTAKE_INDICATOR_CANDIDATES } from "../contracts/message-intake.mjs";
+import { exact, array, digest, integer, enumeration } from "../evidence/artifact-structure.mjs";
+import { MAX_INTAKE_INDICATOR_TEXT, minimiseIndicatorToken } from "./intake-indicators.mjs";
+export const MAX_INTAKE_PHONE_CHARACTERS = 96;
+export const MAX_SELECTED_INTAKE_PHONES = 64;
+const CREDENTIAL_LINE = /\b(?:authorization|proxy-authorization|cookie|set-cookie|password|passwd|access[_ -]?token|refresh[_ -]?token|session[_ -]?id|secret|api[_ -]?key|token)\s*[:=]/iu;
+const PHONE_LABEL = /\b(?:phone|telephone|tel|call|support|contact|fax)\s*[:=]?\s*$/iu;
+const NOT_PHONE_LABEL = /\b(?:date|order|account|invoice|reference|id|md5|sha-?1|sha-?256)\s*[:=#]?\s*$/iu;
+const SEPARATORS = /[ ()\t\u00a0\u202f\-\u2010-\u2014]/gu;
+const UNSUPPORTED = /[^+0-9 ()\t\u00a0\u202f\-\u2010-\u2014]/u;
+/** Bounded by the admitted text length; unterminated markup excludes the remainder. */
+function excludeMarkup(value, mark) {
+    function tagEnd(start) {
+        let quote = null;
+        for (let cursor = start + 1; cursor < value.length; cursor++) {
+            const character = value[cursor];
+            if (quote) {
+                if (character === quote)
+                    quote = null;
+            }
+            else if (character === '"' || character === "'")
+                quote = character;
+            else if (character === '>')
+                return cursor + 1;
+        }
+        return value.length;
+    }
+    let cursor = 0;
+    for (;;) {
+        const start = value.indexOf('<', cursor);
+        if (start < 0)
+            return;
+        let end = tagEnd(start);
+        const rawTag = /^<(script|style)(?=[\t\n\f\r />])/iu.exec(value.slice(start, start + 9))?.[1]?.toLowerCase();
+        if (rawTag) {
+            let closing = value.indexOf('</', end);
+            while (closing >= 0) {
+                const nameEnd = closing + 2 + rawTag.length;
+                if (value.slice(closing + 2, nameEnd).toLowerCase() === rawTag && /[\t\n\f\r />]/u.test(value[nameEnd] ?? '')) {
+                    end = tagEnd(closing);
+                    break;
+                }
+                closing = value.indexOf('</', closing + 2);
+            }
+            if (closing < 0)
+                end = value.length;
+        }
+        mark(start, end);
+        cursor = end;
+    }
+}
+/** Syntax only, not numbering-plan validation or ownership/reachability evidence. */
+export function phoneCandidateValue(original) {
+    let body = original;
+    const suffix = /[ \t\u00a0\u202f]*(?:ext\.?|x)[ \t\u00a0\u202f]*([0-9]{1,6})$/iu.exec(body);
+    const extension = suffix?.[1] ?? null;
+    if (suffix)
+        body = body.slice(0, suffix.index).trimEnd();
+    const digits = body.replace(SEPARATORS, '');
+    const issues = [];
+    if (original.length > MAX_INTAKE_PHONE_CHARACTERS)
+        issues.push('The candidate exceeds the supported character limit.');
+    if (UNSUPPORTED.test(body))
+        issues.push('Unsupported digits, controls or punctuation were preserved, not normalised.');
+    if (!/^\+?[0-9]{7,15}$/u.test(digits))
+        issues.push('Only seven to fifteen ASCII digits with supported separators are reviewable.');
+    if ((body.match(/[0-9]{7,}/gu)?.length ?? 0) > 1)
+        issues.push('Separate long digit runs are not joined into a phone number.');
+    if (body.includes('(') !== body.includes(')') || (body.includes('(') && body.indexOf('(') > body.indexOf(')')) || (body.match(/\(/gu)?.length ?? 0) > 1 || (body.match(/\)/gu)?.length ?? 0) > 1)
+        issues.push('Parentheses are unsupported or unbalanced.');
+    if (/^\+0/u.test(digits))
+        issues.push('An international candidate cannot begin with zero.');
+    if (issues.length)
+        return { canonical: null, extension, state: 'unsupported', issues };
+    return { canonical: digits.startsWith('+') ? digits : null, extension,
+        state: digits.startsWith('+') ? 'international_candidate' : 'national_ambiguous', issues: [] };
+}
+/** Selected plaintext only. The original string is never normalised before indexing. */
+export function reviewPhoneCandidates(value, sourceDigestSha256) {
+    digest(sourceDigestSha256, 'Phone input digest');
+    const candidates = [];
+    let candidatesReviewed = 0, partial = false;
+    if (value.length > MAX_INTAKE_INDICATOR_TEXT)
+        partial = true;
+    else {
+        // Mark excluded ranges without changing string lengths or source offsets.
+        const excluded = new Uint8Array(value.length);
+        const mark = (start, end) => excluded.fill(1, start, end);
+        for (const line of value.matchAll(/[^\r\n]+/gu))
+            if (CREDENTIAL_LINE.test(line[0]))
+                mark(line.index, line.index + line[0].length);
+        for (const token of value.matchAll(/[^\s<>"'`]+/gu))
+            if (minimiseIndicatorToken(token[0]) === ' ')
+                mark(token.index, token.index + token[0].length);
+        // Pasted markup is not a request to inspect attributes or executable content.
+        excludeMarkup(value, mark);
+        for (const match of value.matchAll(/[+\uFF0B(]?[\p{Nd}][\p{Nd} ()\t\u00a0\u202f\-\u2010-\u2014\p{Cf}]{5,}(?:(?:ext\.?|x)[ \t\u00a0\u202f]*[\p{Nd}]+)?/giu)) {
+            if (candidatesReviewed >= MAX_INTAKE_INDICATOR_CANDIDATES || candidates.length >= MAX_INTAKE_INDICATORS) {
+                partial = true;
+                break;
+            }
+            candidatesReviewed++;
+            const original = match[0].trimEnd(), start = match.index, end = start + original.length;
+            if (original.length > MAX_INTAKE_PHONE_CHARACTERS) {
+                partial = true;
+                continue;
+            }
+            if (excluded.subarray(start, end).some(Boolean))
+                continue;
+            const before = value.slice(Math.max(0, start - 48), start);
+            const after = value.slice(end, end + 2);
+            // Sentence punctuation is outside the original span; embedded dots still reject.
+            if (/[\p{L}\p{N}_./:@+-]$/u.test(before)
+                || (/^[\p{L}\p{N}_./:@+-]/u.test(after) && !/^\.(?:\s|$)/u.test(after)))
+                continue;
+            if (NOT_PHONE_LABEL.test(before) || /^\d{4}[- ]\d{1,2}[- ]\d{1,2}$/u.test(original) || /^\d{1,2}[- ]\d{1,2}[- ]\d{2,4}$/u.test(original))
+                continue;
+            if (!/^[+\uFF0B]/u.test(original) && !PHONE_LABEL.test(before))
+                continue;
+            const parsed = phoneCandidateValue(original);
+            candidates.push({ id: `phone-${candidates.length + 1}`, original, start, end, ...parsed });
+        }
+    }
+    return { version: 1, sourceDigestSha256, sourceTextLength: value.length, offsetUnit: 'utf16_code_unit',
+        state: partial ? 'partial' : 'reviewed', candidatesReviewed, candidates };
+}
+/** Validate transient worker data separately from serialisable report evidence. */
+export function validatePhoneReview(result) {
+    if (result.phoneReview === undefined)
+        return;
+    if (result.report.source.kind !== 'text' || result.report.schemaVersion !== 2)
+        throw new TypeError('Phone review requires selected plaintext.');
+    const review = exact(result.phoneReview, ['version', 'sourceDigestSha256', 'sourceTextLength', 'offsetUnit', 'state', 'candidatesReviewed', 'candidates'], 'Phone review');
+    if (review.version !== 1 || review.sourceDigestSha256 !== result.report.source.digestSha256 || review.offsetUnit !== 'utf16_code_unit')
+        throw new TypeError('Phone review source identity is inconsistent.');
+    const length = integer(review.sourceTextLength, 'Phone source length', 0, result.report.source.byteLength);
+    enumeration(review.state, ['reviewed', 'partial'], 'Phone review coverage');
+    const reviewed = integer(review.candidatesReviewed, 'Phone candidate count', 0, MAX_INTAKE_INDICATOR_CANDIDATES);
+    let previousEnd = 0;
+    const candidates = array(review.candidates, 'Phone candidates', MAX_INTAKE_INDICATORS);
+    if (reviewed < candidates.length)
+        throw new TypeError('Phone review counts are inconsistent.');
+    if (length > MAX_INTAKE_INDICATOR_TEXT && (review.state !== 'partial' || reviewed || candidates.length))
+        throw new TypeError('Overlong plaintext cannot claim phone extraction.');
+    candidates.forEach((raw, index) => {
+        const item = exact(raw, ['id', 'original', 'start', 'end', 'canonical', 'extension', 'state', 'issues'], 'Phone candidate');
+        const start = integer(item.start, 'Phone span start', previousEnd, length), end = integer(item.end, 'Phone span end', start + 1, length);
+        if (item.id !== `phone-${index + 1}` || typeof item.original !== 'string' || item.original.length !== end - start || item.original.length > MAX_INTAKE_PHONE_CHARACTERS)
+            throw new TypeError('Phone candidate span is inconsistent.');
+        const parsed = phoneCandidateValue(item.original);
+        if (item.canonical !== parsed.canonical || item.extension !== parsed.extension || item.state !== parsed.state || JSON.stringify(item.issues) !== JSON.stringify(parsed.issues))
+            throw new TypeError('Phone candidate interpretation is inconsistent.');
+        previousEnd = end;
+    });
+}

package/packages/investigation/intake-report.mjs

@@ -15,5 +15,6 @@ export async function createIntakeReport(bytes, kind, reviewedAt) {
         source: { kind, digestSha256: await sha256ArtifactBytes(bytes), byteLength: bytes.byteLength },
         coverage: { state: 'reviewed', reviewedParts: 0, unreviewedAttachments: 0, rejectedLinks: 0, boundsReached: [] },
         identities: [], authenticationClaims: [], authenticationReview: { headers: [], omittedHeaders: 0 }, messageParts: [],
-        links: [], actionHints: [], identityRecovery: { reportedActions: [], nextSteps: [] } };
+        links: [], indicators: [], indicatorCoverage: { state: 'not_reviewed', candidatesReviewed: 0 }, distributionContext: null,
+        actionHints: [], identityRecovery: { reportedActions: [], nextSteps: [] } };
 }