@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/investigation/context-review.mjs

@@ -0,0 +1,35 @@
+import { parseBoundedJson } from "../analysis/bounded-json.mjs";
+import { exact, text } from "../evidence/artifact-structure.mjs";
+import { readEditableCaseExport } from "../cases/case-export-input.mjs";
+import { MAX_CONTEXT_INPUT_BYTES } from "../contracts/context-review.mjs";
+import { DOMAIN_HISTORY_INPUT_SCHEMA, DOMAIN_HISTORY_INPUT_VERSION, reviewDomainHistory } from "./domain-history-review.mjs";
+import { PLATFORM_CONTINUITY_INPUT_SCHEMA, PLATFORM_CONTINUITY_INPUT_VERSION, reviewPlatformContinuity } from "./platform-continuity-review.mjs";
+import { STOREFRONT_INPUT_SCHEMA, STOREFRONT_INPUT_VERSION, reviewStorefront } from "./storefront-review.mjs";
+import { CONNECTOR_INPUT_SCHEMA, CONNECTOR_INPUT_VERSION, reviewConnectorProvenance } from "./connector-provenance-review.mjs";
+import { INCIDENT_SEQUENCE_INPUT_SCHEMA, INCIDENT_SEQUENCE_INPUT_VERSION, reviewIncidentSequence } from "./incident-sequence-review.mjs";
+export { CONTEXT_INPUT_SCHEMAS } from "../contracts/context-review.mjs";
+/** Adapters share the same explicit dispatch; each domain owns its validation. */
+export function reviewContextInput(raw, reviewedAt) {
+    const input = exact(raw, ['schema', 'version', 'evidence'], 'Context review input');
+    if (input.schema === DOMAIN_HISTORY_INPUT_SCHEMA && input.version === DOMAIN_HISTORY_INPUT_VERSION) {
+        const evidence = exact(input.evidence, ['caseExport', 'caseId', 'declarations'], 'Domain history input');
+        const caseId = text(evidence.caseId, 'Selected Case ID', 240);
+        const cases = readEditableCaseExport(JSON.stringify(evidence.caseExport));
+        const selected = cases.find(record => record.id === caseId);
+        if (!selected)
+            throw new TypeError('The selected Case is not present in this export.');
+        return reviewDomainHistory(selected, evidence.declarations, reviewedAt);
+    }
+    if (input.schema === PLATFORM_CONTINUITY_INPUT_SCHEMA && input.version === PLATFORM_CONTINUITY_INPUT_VERSION)
+        return reviewPlatformContinuity(input.evidence, reviewedAt);
+    if (input.schema === STOREFRONT_INPUT_SCHEMA && input.version === STOREFRONT_INPUT_VERSION)
+        return reviewStorefront(input.evidence, reviewedAt);
+    if (input.schema === CONNECTOR_INPUT_SCHEMA && input.version === CONNECTOR_INPUT_VERSION)
+        return reviewConnectorProvenance(input.evidence, reviewedAt);
+    if (input.schema === INCIDENT_SEQUENCE_INPUT_SCHEMA && input.version === INCIDENT_SEQUENCE_INPUT_VERSION)
+        return reviewIncidentSequence(input.evidence, reviewedAt);
+    throw new TypeError('Unsupported context review schema or version.');
+}
+export function parseContextInput(input) {
+    return parseBoundedJson(input, { label: 'Context review input', maximumBytes: MAX_CONTEXT_INPUT_BYTES });
+}

package/packages/investigation/document-intake.mjs

@@ -0,0 +1,81 @@
+import { createIntakeReport } from "./intake-report.mjs";
+import { createLinkIntake } from "./link-intake.mjs";
+import { decodeQrPixels } from "./qr-intake.mjs";
+import { sha256ArtifactBytes } from "../evidence/artifact-integrity.mjs";
+import { MAX_DOCUMENT_PARTS, MAX_DOCUMENT_TEXT_BYTES, MAX_DOCUMENT_TOTAL_IMAGE_PIXELS } from "../contracts/document-intake.mjs";
+/** The format adapters provide inert text/pixels; this owner retains provenance and links. */
+export async function createDocumentIntake(bytes, kind, reviewedAt) {
+    const base = await createIntakeReport(bytes, kind, reviewedAt), links = createLinkIntake();
+    const parts = [], notes = new Set();
+    let textBytes = 0, imagePixels = 0;
+    let state = 'reviewed', pageCount = null, reviewedPages = 0;
+    const encoder = new TextEncoder();
+    function partial(note) { if (state === 'reviewed')
+        state = 'partial'; notes.add(note); }
+    async function part(input, original) {
+        if (parts.length >= MAX_DOCUMENT_PARTS) {
+            partial('Further document parts exceed the review bound.');
+            return null;
+        }
+        const value = { ...input, id: `part-${parts.length + 1}`, parentDigestSha256: base.source.digestSha256,
+            digestSha256: await sha256ArtifactBytes(original), byteLength: original.byteLength };
+        parts.push(value);
+        return { partId: value.id, page: value.page };
+    }
+    return {
+        partial,
+        unavailable(reason, note) { state = reason; notes.add(note); },
+        pages(total, reviewed) { pageCount = total; reviewedPages = reviewed; },
+        async text(value, page, original) {
+            if (value.length > MAX_DOCUMENT_TEXT_BYTES - textBytes) {
+                partial('Further extracted text exceeds the review bound.');
+                return;
+            }
+            const encoded = encoder.encode(value);
+            textBytes += encoded.byteLength;
+            if (textBytes > MAX_DOCUMENT_TEXT_BYTES) {
+                partial('Further extracted text exceeds the review bound.');
+                return;
+            }
+            const location = await part({ kind: 'text', page, identity: original ? 'original_part_bytes' : 'extracted_text', state: 'reviewed' }, original ?? encoded);
+            if (location)
+                links.addText(value, 'document_text', location);
+        },
+        async destinations(values, page, original) {
+            const encoded = encoder.encode(JSON.stringify(values));
+            if (encoded.byteLength > MAX_DOCUMENT_TEXT_BYTES - textBytes) {
+                partial('Further document links exceed the review bound.');
+                return;
+            }
+            textBytes += encoded.byteLength;
+            const location = await part({ kind: 'links', page, identity: original ? 'original_part_bytes' : 'extracted_links', state: 'reviewed' }, original ?? encoded);
+            if (location)
+                for (const value of values)
+                    links.add(value, 'document_link', '', null, 0, location);
+        },
+        async image(image, page, original) {
+            imagePixels += image.width * image.height;
+            if (imagePixels > MAX_DOCUMENT_TOTAL_IMAGE_PIXELS) {
+                partial('Further image pixels exceed the aggregate QR review bound.');
+                return;
+            }
+            const decoded = decodeQrPixels(image);
+            const location = await part({ kind: 'image', page, identity: original ? 'original_part_bytes' : 'decoded_rgba_pixels', state: decoded.bounded || decoded.structured ? 'partial' : 'reviewed' }, original ?? new Uint8Array(image.pixels.buffer, image.pixels.byteOffset, image.pixels.byteLength));
+            if (location)
+                for (const value of decoded.texts)
+                    links.addQr(value, 'document_qr', location);
+            if (decoded.bounded || decoded.structured)
+                partial('Some QR candidates were bounded or require multi-symbol reassembly.');
+        },
+        finish() {
+            const result = links.result();
+            for (const limitation of result.limitations)
+                partial(limitation);
+            if (result.bounded)
+                partial('Further extracted links exceed the review bound.');
+            return { targets: result.targets, report: { ...base, links: result.links,
+                    coverage: { ...base.coverage, state: state === 'reviewed' ? 'reviewed' : 'partial', reviewedParts: parts.length, rejectedLinks: result.rejected },
+                    documentReview: { state, pageCount, reviewedPages, parts, notes: [...notes] } } };
+        },
+    };
+}

package/packages/investigation/docx-intake.mjs

@@ -0,0 +1,133 @@
+import { SaxesParser } from 'saxes';
+import { extractBoundedZipEntries } from "../interchange/bounded-zip-extraction.mjs";
+import { decodeEvidencePng } from "../evidence/png-pixels.mjs";
+import { createDocumentIntake } from "./document-intake.mjs";
+import { MAX_DOCUMENT_PARTS, MAX_DOCUMENT_DECODED_BYTES, MAX_DOCUMENT_TEXT_BYTES, MAX_DOCUMENT_XML_DEPTH, MAX_DOCUMENT_XML_NODES } from "../contracts/document-intake.mjs";
+import { MAX_MESSAGE_INTAKE_BYTES, MAX_INTAKE_LINKS, MAX_INTAKE_URL_LENGTH } from "../contracts/message-intake.mjs";
+const WORD_NAMESPACES = new Set(['http://schemas.openxmlformats.org/wordprocessingml/2006/main', 'http://purl.oclc.org/ooxml/wordprocessingml/main']);
+const RELATIONSHIP_NAMESPACES = new Set(['http://schemas.openxmlformats.org/package/2006/relationships', 'http://purl.oclc.org/ooxml/package/relationships']);
+const WORD_PART = /^word\/(?:document|header\d+|footer\d+|footnotes|endnotes|comments)\.xml$/u;
+const RELATIONSHIP_PART = /^word\/(?:[^/]+\/)*_rels\/[^/]+\.rels$/u;
+const MEDIA_PART = /^word\/media\/[^/]+$/u;
+function archiveKey(name) {
+    const parts = name.endsWith('/') ? name.slice(0, -1).split('/') : name.split('/');
+    if (!name || name.length > 512 || /[\\\x00-\x1f\x7f]/u.test(name) || parts.some(part => !part || part === '.' || part === '..'))
+        throw new TypeError('The document contains an unsafe archive path.');
+    return name.normalize('NFC').toLowerCase();
+}
+function xmlText(bytes) {
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe || bytes[0] === 0x3c && bytes[1] === 0 ? 'utf-16le'
+        : bytes[0] === 0xfe && bytes[1] === 0xff || bytes[0] === 0 && bytes[1] === 0x3c ? 'utf-16be' : 'utf-8';
+    return new TextDecoder(encoding, { fatal: true }).decode(bytes);
+}
+export async function reviewDocxInput(bytes, reviewedAt) {
+    const review = await createDocumentIntake(bytes, 'docx', reviewedAt);
+    if (bytes[0] === 0xd0 && bytes[1] === 0xcf) {
+        review.unavailable('unsupported', 'This is a compound document, which may be encrypted or a legacy format. Export an unencrypted DOCX copy for review.');
+        return review.finish();
+    }
+    let unsupportedParts = 0;
+    const { files } = extractBoundedZipEntries(bytes, {
+        maximumEntries: MAX_DOCUMENT_PARTS, maximumSelectedBytes: MAX_DOCUMENT_DECODED_BYTES,
+        selectedBytesExceededMessage: 'The document exceeds the decoded-byte review bound.', metadataMismatchMessage: 'The DOCX archive is encrypted, malformed or outside supported ZIP bounds.',
+        keyForName: archiveKey,
+        inspect(entry, metadata) {
+            const key = archiveKey(entry.name);
+            if (metadata.kind === 'special')
+                throw new TypeError('Document archives cannot contain special filesystem entries.');
+            const xml = entry.name === '[Content_Types].xml' || WORD_PART.test(entry.name) || RELATIONSHIP_PART.test(entry.name);
+            const png = MEDIA_PART.test(entry.name) && /\.png$/iu.test(entry.name);
+            if (entry.name.startsWith('word/embeddings/') || /(?:vbaProject\.bin|\.jpe?g|\.webp|\.svg|\.wmf|\.emf|\.gif)$/iu.test(entry.name))
+                unsupportedParts++;
+            return { key, selected: xml || png, maximumBytes: png ? MAX_MESSAGE_INTAKE_BYTES : MAX_DOCUMENT_TEXT_BYTES, exceededMessage: 'A document part exceeds the local review bound.' };
+        },
+    });
+    if (!files.has('[Content_Types].xml') || !files.has('word/document.xml'))
+        throw new TypeError('The selected archive is not a supported DOCX document.');
+    let nodes = 0, declaredMain = false, externalResources = 0;
+    function parseXml(input, callbacks) {
+        const parser = new SaxesParser({ xmlns: true });
+        let depth = 0;
+        parser.on('doctype', () => { throw new TypeError('Document XML declarations cannot define entities.'); });
+        parser.on('error', () => { throw new TypeError('A document XML part is malformed.'); });
+        parser.on('opentag', tag => {
+            if (++nodes > MAX_DOCUMENT_XML_NODES || ++depth > MAX_DOCUMENT_XML_DEPTH)
+                throw new TypeError('Document XML exceeds the structural review bound.');
+            callbacks.open?.(tag);
+        });
+        parser.on('closetag', tag => { callbacks.close?.(tag); depth--; });
+        parser.on('text', value => callbacks.text?.(value));
+        parser.on('cdata', value => callbacks.text?.(value));
+        const inputText = xmlText(input);
+        for (let offset = 0; offset < inputText.length; offset += 4096)
+            parser.write(inputText.slice(offset, offset + 4096));
+        parser.close();
+    }
+    const attr = (tag, name) => Object.values(tag.attributes).find(value => value.local === name && value.uri === '')?.value;
+    parseXml(files.get('[Content_Types].xml'), { open(tag) {
+            if (tag.local === 'Override' && tag.uri === 'http://schemas.openxmlformats.org/package/2006/content-types'
+                && attr(tag, 'PartName') === '/word/document.xml' && attr(tag, 'ContentType') === 'application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml')
+                declaredMain = true;
+        } });
+    if (!declaredMain)
+        throw new TypeError('The selected archive does not declare an ordinary DOCX document. Macro-enabled and other document types are not interpreted as DOCX.');
+    for (const [name, body] of files) {
+        if (WORD_PART.test(name)) {
+            try {
+                let text = '', textDepth = 0;
+                parseXml(body, { open(tag) { if (WORD_NAMESPACES.has(tag.uri) && ['t', 'instrText'].includes(tag.local))
+                        textDepth++; },
+                    close(tag) { if (WORD_NAMESPACES.has(tag.uri) && ['t', 'instrText'].includes(tag.local))
+                        textDepth--; if (WORD_NAMESPACES.has(tag.uri) && ['p', 'tab', 'br'].includes(tag.local))
+                        text += '\n'; },
+                    text(value) { if (textDepth) {
+                        if (text.length + value.length > MAX_DOCUMENT_TEXT_BYTES)
+                            throw new TypeError('Document text exceeds its review bound.');
+                        text += value;
+                    } } });
+                await review.text(text, null, body);
+            }
+            catch {
+                review.partial('A document text part could not be fully decoded within the XML review bounds.');
+            }
+        }
+        else if (RELATIONSHIP_PART.test(name)) {
+            try {
+                const destinations = [];
+                parseXml(body, { open(tag) {
+                        if (tag.local !== 'Relationship' || !RELATIONSHIP_NAMESPACES.has(tag.uri) || attr(tag, 'TargetMode') !== 'External')
+                            return;
+                        const type = attr(tag, 'Type'), target = attr(tag, 'Target');
+                        if (type !== 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink' && type !== 'http://purl.oclc.org/ooxml/officeDocument/relationships/hyperlink') {
+                            externalResources++;
+                            return;
+                        }
+                        if (!target || target.length > MAX_INTAKE_URL_LENGTH || destinations.length >= MAX_INTAKE_LINKS) {
+                            review.partial('Some relationship targets exceed the link review bound.');
+                            return;
+                        }
+                        destinations.push(target);
+                    } });
+                await review.destinations(destinations, null, body);
+            }
+            catch {
+                review.partial('A relationship part could not be fully decoded within the XML review bounds.');
+            }
+        }
+        else if (MEDIA_PART.test(name)) {
+            try {
+                await review.image(decodeEvidencePng(body), null, body);
+            }
+            catch {
+                review.partial('An embedded image was unsupported, malformed or outside the pixel review bounds.');
+            }
+        }
+    }
+    if (externalResources)
+        review.partial(`${externalResources} external non-link resources were declared but not requested.`);
+    if (unsupportedParts)
+        review.partial(`${unsupportedParts} embedded objects or non-PNG images were not decoded.`);
+    // Text/relationships are declarations in the selected package, not a rendered page.
+    review.partial('DOCX page layout, vector artwork, embedded objects and non-PNG images are not rendered. Link relationships can include unused declarations.');
+    return review.finish();
+}

package/packages/investigation/domain-history-review.mjs

@@ -0,0 +1,100 @@
+import { caseEvidenceIncomparableReasons, compareCaseEvidence } from "../cases/case-evidence-model.mjs";
+import { domainTransitionReview } from "./domain-transition-review.mjs";
+import { MAX_CASE_EVIDENCE_PINS, MAX_EVIDENCE_SNAPSHOTS_PER_CASE } from "../contracts/case-portability.mjs";
+import { array, domain, enumeration, exact, iso, text } from "../evidence/artifact-structure.mjs";
+import { CONTEXT_REVIEW_SCHEMA, CONTEXT_REVIEW_VERSION, MAX_CONTEXT_RECORDS } from "../contracts/context-review.mjs";
+export { DOMAIN_HISTORY_INPUT_SCHEMA, DOMAIN_HISTORY_INPUT_VERSION } from "../contracts/context-review.mjs";
+export const DOMAIN_CHANGE_FAMILIES = ['registration', 'dns', 'mail', 'certificate', 'web'];
+export function readDomainHistoryDeclarations(raw) {
+    const input = exact(raw, ['expectedChanges', 'retiredDependencies'], 'Domain history declarations');
+    const expectedChanges = array(input.expectedChanges, 'Expected changes', MAX_CONTEXT_RECORDS).map(value => {
+        const item = exact(value, ['family', 'start', 'end', 'reason'], 'Expected change');
+        iso(item.start, 'Expected window start');
+        iso(item.end, 'Expected window end');
+        if (Date.parse(item.start) > Date.parse(item.end))
+            throw new TypeError('Expected change window ends before it starts.');
+        return { family: enumeration(item.family, DOMAIN_CHANGE_FAMILIES, 'Change family'), start: item.start, end: item.end, reason: text(item.reason, 'Change reason', 500) };
+    });
+    const retiredDependencies = array(input.retiredDependencies, 'Retired dependencies', MAX_CONTEXT_RECORDS).map(value => {
+        const item = exact(value, ['asset', 'dependency', 'family', 'retiredAt', 'source'], 'Retired dependency');
+        domain(item.asset, 'Owned asset');
+        domain(item.dependency, 'Dependency hostname');
+        iso(item.retiredAt, 'Retirement time');
+        return { asset: item.asset, dependency: item.dependency, family: enumeration(item.family, DOMAIN_CHANGE_FAMILIES, 'Dependency family'), retiredAt: item.retiredAt, source: text(item.source, 'Retirement source', 500) };
+    });
+    return { expectedChanges, retiredDependencies };
+}
+function family(field) {
+    if (['registrar', 'createdDate', 'expiryDate', 'availability'].includes(field))
+        return 'registration';
+    if (field === 'nameservers')
+        return 'dns';
+    if (['hasMx', 'hasSpf', 'hasDmarc'].includes(field))
+        return 'mail';
+    if (field.startsWith('http') || ['activityStatus', 'pageTitle', 'websiteProbeDetail', 'faviconMatch', 'faviconNearMatch',
+        'reusesOfficialAssets', 'hasPasswordField', 'hasExternalFormAction', 'pageBaselineMatch'].includes(field))
+        return 'web';
+    return null;
+}
+/** Input is a canonical Case from storage or the existing exact Case-export reader. */
+export function reviewDomainHistory(record, declarations, reviewedAt) {
+    iso(reviewedAt, 'Review time');
+    const declared = readDomainHistoryDeclarations(declarations);
+    const related = (hostname) => hostname === record.domain || hostname.endsWith(`.${record.domain}`);
+    if (declared.retiredDependencies.some(row => !related(row.asset) && !related(row.dependency)))
+        throw new TypeError('A retired dependency must involve this Case domain or one of its hostnames.');
+    array(record.evidenceHistory, 'Case evidence history', MAX_EVIDENCE_SNAPSHOTS_PER_CASE);
+    array(record.evidencePins, 'Case evidence pins', MAX_CASE_EVIDENCE_PINS);
+    const snapshots = [...record.evidenceHistory].sort((a, b) => Date.parse(a.capturedAt) - Date.parse(b.capturedAt) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const observations = [];
+    let orderedPairs = 0;
+    let limitedPairs = 0;
+    const prompts = new Set();
+    for (let index = 1; index < snapshots.length; index++) {
+        const before = snapshots[index - 1], after = snapshots[index];
+        if (before.capturedAt === after.capturedAt) {
+            observations.push({ label: 'Concurrent snapshot observations', state: 'unknown', detail: 'These records have the same observation time; their ordering is not a change sequence.', source: `${before.id} / ${after.id}`, observedAt: after.capturedAt, hostname: record.domain });
+            continue;
+        }
+        orderedPairs++;
+        const reasons = caseEvidenceIncomparableReasons(before, after);
+        if (reasons.length) {
+            limitedPairs++;
+            observations.push({ label: 'Comparison coverage', state: 'partial',
+                detail: `Some fields are not comparable: ${reasons.map(reason => ({
+                    'observation-context': 'different hostname or selected-page context',
+                    'scan-depth': 'different collection depth',
+                    'collection-quality': 'missing registration values or incomplete page/favicon collection',
+                    'risk-model': 'different or unknown risk model',
+                    'opportunity-model': 'different or unknown opportunity model',
+                })[reason]).join('; ')}. These gaps do not establish activation, disappearance or resolution.`,
+                source: `${before.source} ${before.id} → ${after.source} ${after.id}`, observedAt: after.capturedAt,
+                hostname: after.observationHostname ?? record.domain });
+        }
+        for (const change of compareCaseEvidence(before, after)) {
+            const category = family(change.field);
+            if (!category)
+                continue;
+            const prompt = domainTransitionReview(change.field, change.before, change.after);
+            if (prompt)
+                prompts.add(prompt);
+            const windows = declared.expectedChanges.filter(row => row.family === category && Date.parse(row.start) <= Date.parse(after.capturedAt) && Date.parse(row.end) >= Date.parse(before.capturedAt));
+            observations.push({ label: `${category} · ${change.label}`, state: 'changed',
+                detail: `${JSON.stringify(change.before)} → ${JSON.stringify(change.after)}${windows.length ? ` · Overlaps ${windows.length} analyst-declared expected-change window(s); not automatically approved.` : ''}`,
+                source: `${before.source} ${before.id} → ${after.source} ${after.id}`, observedAt: after.capturedAt, hostname: after.observationHostname ?? record.domain });
+        }
+    }
+    for (const pin of record.evidencePins.filter(pin => pin.certificateObservation)) {
+        observations.push({ label: `Retained certificate · ${pin.label}`, state: pin.completeness === 'complete' && pin.truncated !== true ? 'observed' : 'partial', detail: pin.value,
+            source: `${pin.source} · pin ${pin.id}`, observedAt: pin.observedAt, hostname: record.domain });
+    }
+    for (const row of declared.expectedChanges)
+        observations.push({ label: `Expected ${row.family} change`, state: 'reported', detail: `${row.start} – ${row.end} · ${row.reason}`, source: 'Analyst declaration', observedAt: null, hostname: record.domain });
+    for (const row of declared.retiredDependencies)
+        observations.push({ label: `Declared retired ${row.family} dependency`, state: 'reported', detail: `${row.asset} depended on ${row.dependency}. Check whether owned configuration still references it.`, source: row.source, observedAt: row.retiredAt, hostname: row.dependency });
+    const certificateCount = observations.filter(row => row.label.startsWith('Retained certificate')).length;
+    return { schema: CONTEXT_REVIEW_SCHEMA, version: CONTEXT_REVIEW_VERSION, kind: 'domain_history', reviewedAt, title: 'Domain history and retired dependencies', state: orderedPairs < 1 || limitedPairs > 0 ? 'partial' : 'reviewed',
+        summary: `Retained snapshots: ${snapshots.length}; time-ordered pairs: ${orderedPairs}; limited pairs: ${limitedPairs}; certificate pins: ${certificateCount}; declared retired dependencies: ${declared.retiredDependencies.length}.`, observations,
+        nextSteps: [...prompts, 'Review changed registration, DNS, mail and web evidence against declared maintenance windows.', 'Recheck owned references to retired dependencies before changing configuration; preserve evidence of legitimate transfers or rebrands.'],
+        limitations: ['This review uses retained Case evidence, not fresh collection. Missing or incompatible fields are not compared.', 'Certificate pins retain their own source and completeness; they are not equivalent to live TLS observations.', 'Changes and retired dependencies do not establish ownership transfer, malicious repurposing or takeover availability.'] };
+}

package/packages/investigation/domain-transition-review.mjs

@@ -0,0 +1,47 @@
+/** Review prompts for changes already admitted by a source-aware comparator. */
+export function domainTransitionReview(field, before, after) {
+    if (before == null || after == null)
+        return null;
+    switch (field) {
+        case 'createdDate':
+            return 'Reassess earlier relevance, exceptions and response baselines against the changed registration date. Keep the prior history; the date alone does not establish a new owner or confirmed re-registration.';
+        case 'availability':
+            return before === 'available' || after === 'available'
+                ? 'Review the dated registration observations before carrying earlier decisions into this context. An availability change does not by itself establish who controls the domain.'
+                : 'Review the registration state in its source context; sale and expiry labels do not establish deletion or a change of owner.';
+        case 'expiryDate':
+            return 'Check the reported renewal timeline. Expiry, deletion and re-registration are different events; this change does not reset earlier decisions.';
+        case 'registrar':
+        case 'registrarName':
+            return 'Review the registration source and any expected transfer. A registrar change is not evidence of new ownership.';
+        case 'nameservers':
+            return 'Compare the delegation change with expected hosting or DNS maintenance before revising relationships or response routes.';
+        case 'hasMx':
+        case 'hasNullMx':
+        case 'hasSpf':
+        case 'hasDmarc':
+            return 'Review the changed mail configuration against the watch reason. DNS configuration does not show whether messages were sent or an account was compromised.';
+        case 'hasPasswordField':
+            return after === true
+                ? 'Review the newly observed password form and its destination against the recorded concern. A login form alone is not credential theft.'
+                : 'Review the current page evidence before changing the assessment; removal of one form does not establish that the incident is resolved.';
+        case 'hasExternalFormAction':
+            return 'Check the observed form destination and legitimate service use before updating the assessment. No form was submitted by this review.';
+        case 'faviconMatch':
+        case 'faviconNearMatch':
+        case 'reusesOfficialAssets':
+        case 'pageBaselineMatch':
+            return 'Review the retained Brand comparison and legitimate shared assets. An identity match or its disappearance is not an infringement or resolution verdict.';
+        case 'activityStatus':
+            return after === 'unreachable' || after === 'no_site'
+                ? 'The website observation is inconclusive; do not treat it as disappearance or resolution. Recheck deliberately within the existing collection scope.'
+                : 'Review the changed site activity against the watch reason. A legitimate launch can change the same fields as an incident.';
+        case 'pageTitle':
+        case 'httpFinalOrigin':
+        case 'httpCrossOriginRedirect':
+        case 'faviconHash':
+            return 'Review the changed page or destination against the retained concern and expected site changes. Preserve the exact observation scope before making a Case or priority decision.';
+        default:
+            return null;
+    }
+}

package/packages/investigation/evidence-coverage-ledger.mjs

@@ -1,4 +1,5 @@
-const MAX_ENTRIES = 24;
+export const MAX_EVIDENCE_COVERAGE_ENTRIES = 24;
+const MAX_ENTRIES = MAX_EVIDENCE_COVERAGE_ENTRIES;
 const MAX_ID_LENGTH = 64;
 const MAX_LABEL_LENGTH = 120;
 const MAX_LIMITATIONS = 8;
@@ -330,6 +331,13 @@ export function buildLookupEvidenceCoverageLedger(input) {
     const providers = Array.isArray(input.threatIntelligenceProviders)
         ? input.threatIntelligenceProviders
         : [];
+    if (Array.isArray(input.threatIntelligenceWithheld) && input.threatIntelligenceWithheld.length) {
+        items.push({
+            id: 'external-withheld', label: 'Withheld external-intelligence records', category: 'external',
+            status: 'unsupported', complete: false,
+            limitations: ['Some provider data was unsupported, unbound, malformed or over-limit. Withheld records are not evidence of no findings and cannot contribute to Risk.'],
+        });
+    }
     for (const [providerIndex, providerValue] of providers.entries()) {
         if (items.length >= MAX_ENTRIES)
             break;

package/packages/investigation/har-intake.mjs

@@ -0,0 +1,68 @@
+import { parseBoundedJsonObject, boundedJsonLimitsForBytes } from "../analysis/bounded-json.mjs";
+import { parseCredentialFreeHttpUrl } from "../evidence/lookup-target.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { MAX_MESSAGE_INTAKE_BYTES, MAX_INTAKE_URL_LENGTH } from "../contracts/message-intake.mjs";
+import { MAX_HAR_ENTRIES, HAR_TIMING_PHASES } from "../contracts/har-review.mjs";
+import { createIntakeReport } from "./intake-report.mjs";
+import { createLinkIntake } from "./link-intake.mjs";
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const milliseconds = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER ? value : null;
+function mimeCategory(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return 'unknown';
+    const mime = raw.split(';', 1)[0].trim().toLowerCase();
+    if (['text/html', 'application/xhtml+xml'].includes(mime))
+        return 'html';
+    if (['text/javascript', 'application/javascript', 'application/ecmascript', 'text/ecmascript'].includes(mime))
+        return 'script';
+    if (mime === 'application/json' || mime.endsWith('+json'))
+        return 'json';
+    if (['application/xml', 'text/xml'].includes(mime) || mime.endsWith('+xml'))
+        return 'xml';
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('font/') || mime.includes('font'))
+        return 'font';
+    if (mime.startsWith('audio/') || mime.startsWith('video/'))
+        return 'media';
+    if (mime.startsWith('text/'))
+        return 'text';
+    return mime === 'application/octet-stream' ? 'binary' : 'other';
+}
+/** Retain declared request sequence, not cookies, headers, bodies or replay authority. */
+export async function reviewHarInput(bytes, reviewedAt) {
+    const base = await createIntakeReport(bytes, 'har', reviewedAt);
+    const root = parseBoundedJsonObject(new TextDecoder('utf-8', { fatal: true }).decode(bytes), { label: 'HAR input', maximumBytes: MAX_MESSAGE_INTAKE_BYTES,
+        limits: { ...boundedJsonLimitsForBytes(MAX_MESSAGE_INTAKE_BYTES), maximumContainerItems: MAX_HAR_ENTRIES } });
+    const log = record(root.log);
+    if (log.version !== '1.2' || !Array.isArray(log.entries) || log.entries.length > MAX_HAR_ENTRIES)
+        throw new TypeError('Select a HAR 1.2 archive within the entry review bound.');
+    const links = createLinkIntake(), entries = [];
+    let invalidEntries = 0;
+    for (const [index, raw] of log.entries.entries()) {
+        const entry = record(raw), request = record(entry.request), response = record(entry.response), content = record(response.content), timing = record(entry.timings);
+        if (!Object.keys(request).length || !Object.keys(response).length) {
+            invalidEntries++;
+            continue;
+        }
+        const url = parseCredentialFreeHttpUrl(request.url, MAX_INTAKE_URL_LENGTH);
+        const method = typeof request.method === 'string' ? request.method.toUpperCase() : null;
+        const resource = typeof entry._resourceType === 'string' ? entry._resourceType.toLowerCase() : null;
+        entries.push({ sequence: index + 1, startedAt: typeof entry.startedDateTime === 'string' ? normalizeExplicitIsoTimestamp(entry.startedDateTime) : null,
+            origin: url?.origin ?? null,
+            method: method === null ? 'unknown' : ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS', 'PATCH', 'CONNECT', 'TRACE'].includes(method) ? method : 'other',
+            status: typeof response.status === 'number' && Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? response.status : null,
+            durationMs: milliseconds(entry.time), mimeCategory: mimeCategory(content.mimeType),
+            timings: Object.fromEntries(HAR_TIMING_PHASES.map(phase => [phase, milliseconds(timing[phase])])),
+            resourceType: resource === null ? 'unknown' : ['document', 'script', 'stylesheet', 'image', 'font', 'media', 'xhr', 'fetch', 'ping', 'websocket'].includes(resource) ? resource : 'other',
+            reportedFailure: typeof entry._error === 'string' && Boolean(entry._error) });
+        // Queries may carry access tokens or account identifiers. Even transient
+        // destination actions from this archive contain only its origin.
+        if (url)
+            links.add(url.origin, 'har_request');
+    }
+    const extracted = links.result();
+    return { targets: extracted.targets, report: { ...base, links: extracted.links, harReview: { entries, invalidEntries },
+            coverage: { ...base.coverage, state: invalidEntries || extracted.bounded || extracted.rejected ? 'partial' : 'reviewed', reviewedParts: entries.length,
+                rejectedLinks: extracted.rejected, boundsReached: [...extracted.limitations, ...(extracted.bounded ? ['Destination list; the admitted request timeline remains available'] : [])] } } };
+}

package/packages/investigation/identity-event-intake.mjs

@@ -0,0 +1,131 @@
+import { parseBoundedJson, boundedJsonLimitsForBytes } from "../analysis/bounded-json.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { exact, exactOptional } from "../evidence/artifact-structure.mjs";
+import { MAX_MESSAGE_INTAKE_BYTES } from "../contracts/message-intake.mjs";
+import { IDENTITY_EVENTS_INPUT_SCHEMA, IDENTITY_EVENTS_INPUT_VERSION, MAX_IDENTITY_EVENTS } from "../contracts/identity-events.mjs";
+import { createIntakeReport } from "./intake-report.mjs";
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const instant = (value) => typeof value === 'string' ? normalizeExplicitIsoTimestamp(value) : null;
+const guid = (value) => typeof value === 'string' && /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/iu.test(value) ? value.toLowerCase() : null;
+function applicationId(value, provider) {
+    return provider === 'entra' ? guid(value) : typeof value === 'string' && /^0oa[a-z\d]{17}$/iu.test(value) ? value : null;
+}
+function protocol(value) {
+    switch (value) {
+        case 'oAuth2': return 'oauth2';
+        case 'deviceCode': return 'device_code';
+        case 'saml20': return 'saml';
+        case 'wsFederation': return 'ws_federation';
+        case 'ropc': return 'password_grant';
+        default: return 'unknown';
+    }
+}
+function eventKind(value) {
+    switch (value) {
+        case 'user.authentication.sso': return 'application_access';
+        case 'user.session.start': return 'session_start';
+        case 'user.authentication.auth_via_mfa':
+        case 'user.authentication.verify': return 'credential_check';
+        case 'app.oauth2.consent.grant': return 'consent';
+        default: return 'other';
+    }
+}
+/** IDs are replaced in memory; actor labels are meaningful only within this file. */
+function extractEvents(input, provider) {
+    const actors = new Map(), events = [];
+    let invalidEvents = 0;
+    const actor = (value) => {
+        if (typeof value !== 'string' || !value || value.length > 240)
+            return null;
+        let label = actors.get(value);
+        if (!label) {
+            label = `Actor ${actors.size + 1}`;
+            actors.set(value, label);
+        }
+        return label;
+    };
+    for (const [index, value] of input.entries()) {
+        const row = record(value);
+        if (provider === 'entra') {
+            if (!Object.hasOwn(row, 'createdDateTime') || !Object.hasOwn(row, 'status')) {
+                invalidEvents++;
+                continue;
+            }
+            const app = applicationId(row.appId, provider), code = record(row.status).errorCode;
+            events.push({ sequence: index + 1, actorLabel: actor(row.userId), applicationIds: app ? [app] : [], tenantId: guid(row.resourceTenantId),
+                // A client category (for example Browser) is not an authentication protocol.
+                protocol: protocol(row.authenticationProtocol), kind: 'sign_in', occurredAt: instant(row.createdDateTime),
+                result: typeof code === 'number' && Number.isSafeInteger(code) && code >= 0 ? code === 0 ? 'success' : 'failure' : 'unknown' });
+        }
+        else {
+            if (typeof row.eventType !== 'string' || !Object.hasOwn(row, 'published')) {
+                invalidEvents++;
+                continue;
+            }
+            const targets = Array.isArray(row.target) ? row.target : [];
+            const apps = targets.filter(target => record(target).type === 'AppInstance').map(target => applicationId(record(target).id, provider)).filter((id) => id !== null);
+            const outcome = record(row.outcome).result;
+            events.push({ sequence: index + 1, actorLabel: actor(record(row.actor).id), applicationIds: [...new Set(apps)], tenantId: null,
+                protocol: 'unknown', kind: eventKind(row.eventType), occurredAt: instant(row.published),
+                result: outcome === 'SUCCESS' ? 'success' : outcome === 'FAILURE' ? 'failure' : outcome === 'DENY' ? 'denied' : outcome === 'CHALLENGE' ? 'challenge' : 'unknown' });
+        }
+    }
+    return { events, invalidEvents };
+}
+export function readIdentityMatchScope(raw, provider) {
+    const source = exact(raw, ['applicationId', 'tenantId', 'actorLabel', 'startedAt', 'endedAt'], 'Identity comparison scope');
+    const app = applicationId(source.applicationId, provider), tenant = source.tenantId === null ? null : guid(source.tenantId);
+    const start = instant(source.startedAt), end = instant(source.endedAt);
+    if (!app || !start || !end || Date.parse(end) < Date.parse(start) || source.tenantId !== null && !tenant
+        || source.actorLabel !== null && (typeof source.actorLabel !== 'string' || !/^Actor [1-9]\d{0,4}$/u.test(source.actorLabel))) {
+        throw new TypeError('Select a valid application ID, explicit-timezone interval, and optional retained tenant or file-local actor label.');
+    }
+    return { applicationId: app, tenantId: tenant, actorLabel: source.actorLabel, startedAt: start, endedAt: end };
+}
+/** Exact supplied-field corroboration, not a causal or account-compromise judgement. */
+export function compareIdentityEvents(review, rawScope) {
+    const scope = readIdentityMatchScope(rawScope, review.provider);
+    const compare = (selected, supplied) => selected === null ? 'not_selected' : supplied === null ? 'unavailable' : selected === supplied ? 'matched' : 'different';
+    return { ...review, comparison: { scope, events: review.events.map(event => {
+                const application = !event.applicationIds.length ? 'unavailable' : event.applicationIds.includes(scope.applicationId) ? 'matched' : 'different';
+                const tenant = compare(scope.tenantId, event.tenantId), actor = compare(scope.actorLabel, event.actorLabel);
+                const time = !event.occurredAt ? 'unavailable' : Date.parse(event.occurredAt) >= Date.parse(scope.startedAt) && Date.parse(event.occurredAt) <= Date.parse(scope.endedAt) ? 'matched' : 'different';
+                const fields = [application, tenant, actor, time];
+                return { sequence: event.sequence, application, tenant, actor, time,
+                    state: fields.includes('different') ? 'different' : fields.includes('unavailable') ? 'incomplete' : 'matched' };
+            }) } };
+}
+export async function reviewIdentityEventInput(bytes, reviewedAt) {
+    const base = await createIntakeReport(bytes, 'identity', reviewedAt);
+    const parsed = parseBoundedJson(new TextDecoder('utf-8', { fatal: true }).decode(bytes), { label: 'Identity event input', maximumBytes: MAX_MESSAGE_INTAKE_BYTES,
+        limits: { ...boundedJsonLimitsForBytes(MAX_MESSAGE_INTAKE_BYTES), maximumContainerItems: MAX_IDENTITY_EVENTS } });
+    const root = record(parsed);
+    let provider, input, match = null;
+    if (Object.hasOwn(root, 'schema')) {
+        exactOptional(root, ['schema', 'version', 'provider', 'events'], ['match'], 'Identity event input');
+        if (root.schema !== IDENTITY_EVENTS_INPUT_SCHEMA || root.version !== IDENTITY_EVENTS_INPUT_VERSION || !['entra', 'okta'].includes(String(root.provider)))
+            throw new TypeError('Unsupported identity event input schema, version or provider.');
+        provider = root.provider;
+        input = root.events;
+        match = root.match ?? null;
+    }
+    else if (Array.isArray(parsed)) {
+        provider = 'okta';
+        input = parsed;
+    }
+    else {
+        provider = 'entra';
+        input = root.value;
+    }
+    if (!Array.isArray(input) || input.length > MAX_IDENTITY_EVENTS)
+        throw new TypeError('Select a sign-in value array, a System Log array, or a versioned identity event input.');
+    const extracted = extractEvents(input, provider);
+    if (input.length && !extracted.events.length)
+        throw new TypeError('No supported identity event records were found.');
+    let identityEventReview = { provider, ...extracted, sourceHasMore: typeof root['@odata.nextLink'] === 'string' && Boolean(root['@odata.nextLink']), comparison: null };
+    if (match !== null)
+        identityEventReview = compareIdentityEvents(identityEventReview, match);
+    return { targets: [], report: { ...base, identityEventReview, coverage: { ...base.coverage,
+                state: identityEventReview.invalidEvents || identityEventReview.sourceHasMore ? 'partial' : 'reviewed', reviewedParts: identityEventReview.events.length,
+                boundsReached: identityEventReview.sourceHasMore ? ['The selected export declares another page; it was not requested'] : [] } } };
+}