@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/packages/investigation/bulk-mail-exposure.mjs

@@ -1,15 +1,8 @@
 import { SORTED_JSON_V2, sha256ArtifactDigestV2 } from "../evidence/artifact-integrity.mjs";
+import { PASSIVE_MAIL_INTERPRETATION, PASSIVE_MAIL_LABELS } from "../contracts/passive-mail.mjs";
 import { BULK_PROFILE_CONTEXT_MISMATCH_LIMITATION, normalizeBulkProfileContext, normalizeBulkSessionResult, } from "../workspace/bulk-session-model.mjs";
 import { BULK_MAIL_EXPOSURE_EXPORT_VERSION, BULK_MAIL_EXPOSURE_SCHEMA, BULK_MAIL_EXPOSURE_VERSION, MAX_BULK_MAIL_EXPOSURE_ROWS, } from "../contracts/investigation-portability.mjs";
 export { BULK_MAIL_EXPOSURE_EXPORT_VERSION, BULK_MAIL_EXPOSURE_SCHEMA, BULK_MAIL_EXPOSURE_VERSION, MAX_BULK_MAIL_EXPOSURE_ROWS };
-const STATE_LABELS = {
-    authenticated_mail: 'Receiving mail with SPF and DMARC',
-    evidence_incomplete: 'Mail evidence incomplete',
-    mail_auth_gap: 'Receiving mail with an authentication gap',
-    mail_auth_incomplete: 'Receiving mail with incomplete authentication evidence',
-    no_explicit_mx: 'No explicit MX observed',
-    null_mx: 'Null MX observed',
-};
 function timestamp(value) {
     if (typeof value !== 'string' || !Number.isFinite(Date.parse(value)))
         return null;
@@ -51,16 +44,16 @@ function exposureState(row) {
 }
 function stateDetail(state) {
     if (state === 'authenticated_mail') {
-        return 'An explicit receiving MX plus SPF and DMARC publications were observed.';
+        return 'Explicit MX, SPF and DMARC publications were observed.';
     }
     if (state === 'null_mx') {
         return 'A null MX explicitly declaring no inbound mail was observed.';
     }
     if (state === 'mail_auth_gap') {
-        return 'A receiving MX was observed while SPF or DMARC was observed absent.';
+        return 'An MX publication was observed while SPF or DMARC was observed absent.';
     }
     if (state === 'mail_auth_incomplete') {
-        return 'A receiving MX was observed, but SPF or DMARC collection was incomplete.';
+        return 'An MX publication was observed, but SPF or DMARC collection was incomplete.';
     }
     if (state === 'no_explicit_mx') {
         return 'DNS collection completed without an explicit MX. This is not proof that SMTP delivery is impossible.';
@@ -173,7 +166,7 @@ export function buildBulkMailExposureReport(rowsRaw, options = {}) {
         return {
             domain: item.domain,
             state,
-            label: STATE_LABELS[state],
+            label: PASSIVE_MAIL_LABELS[state],
             detail: stateDetail(state),
             ...relation(state, profile, profileSourceState, profileContextComparable, profileContextLimitation),
             mutationTypes: item.mutationTypes.slice(0, 40),
@@ -217,8 +210,9 @@ export function buildBulkMailExposureReport(rowsRaw, options = {}) {
         counts,
         profileContextUnevaluatedCount,
         limitations: [
+            PASSIVE_MAIL_INTERPRETATION,
             'This review uses compact Bulk evidence already collected and makes no additional request.',
-            'Null MX, no explicit MX, receiving mail, authentication gaps, and incomplete evidence remain separate states.',
+            'Null MX, no explicit MX, published mail policies, policy gaps, and incomplete evidence remain separate states.',
             'SMTP delivery, mailbox existence, catch-all behaviour, and message acceptance were not tested.',
         ],
     };

package/packages/investigation/capture-coverage.mjs

@@ -0,0 +1,57 @@
+import { array, boolean, enumeration, exact, integer, text } from "../evidence/artifact-structure.mjs";
+export const MAX_CAPTURE_CHANNEL_OBSERVATIONS = 500;
+export const CAPTURE_REQUEST_CHANNELS = ['navigation', 'document', 'frame', 'script', 'stylesheet', 'image', 'font', 'media', 'xhr', 'fetch', 'beacon', 'event_source', 'other'];
+export const CAPTURE_DISABLED_SURFACES = ['service_workers', 'dedicated_workers', 'shared_workers', 'websockets', 'webrtc', 'webtransport', 'downloads'];
+export function emptyCaptureCoverage() {
+    return { attempts: [], omittedAttempts: 0, disabledSurfaces: [...CAPTURE_DISABLED_SURFACES], interactions: 'not_exercised', websocketRefusals: 0, directConnectionRefusals: 0 };
+}
+export function captureCoverageIsPartial(value) {
+    return Boolean(value.omittedAttempts || value.websocketRefusals || value.directConnectionRefusals || value.attempts.some(row => row.state !== 'observed'));
+}
+export function readCaptureCoverage(raw) {
+    const value = exact(raw, ['attempts', 'omittedAttempts', 'disabledSurfaces', 'interactions', 'websocketRefusals', 'directConnectionRefusals'], 'Capture coverage');
+    const disabledSurfaces = array(value.disabledSurfaces, 'Disabled capture surfaces', CAPTURE_DISABLED_SURFACES.length).map(value => enumeration(value, CAPTURE_DISABLED_SURFACES, 'Disabled capture surface'));
+    if (new Set(disabledSurfaces).size !== CAPTURE_DISABLED_SURFACES.length)
+        throw new TypeError('Capture coverage must identify every required disabled surface.');
+    const attempts = array(value.attempts, 'Capture request attempts', MAX_CAPTURE_CHANNEL_OBSERVATIONS).map(raw => {
+        const row = exact(raw, ['position', 'channel', 'method', 'origin', 'state', 'reason', 'collectionStarted'], 'Capture request attempt');
+        const state = enumeration(row.state, ['observed', 'refused', 'unavailable'], 'Capture request state');
+        const method = enumeration(row.method, ['read', 'non_read', 'unknown'], 'Capture method category');
+        const reason = row.reason === null ? null : enumeration(row.reason, ['method', 'request_bound', 'host_bound', 'response_bound', 'shutdown', 'address_or_transport'], 'Capture request qualification');
+        boolean(row.collectionStarted, 'Collector-started flag');
+        let origin = null;
+        if (row.origin !== null) {
+            const candidate = text(row.origin, 'Capture request origin', 500), parsed = new URL(candidate);
+            if (!['http:', 'https:'].includes(parsed.protocol) || parsed.origin !== candidate || parsed.username || parsed.password)
+                throw new TypeError('Capture request coverage retains origins only.');
+            origin = candidate;
+        }
+        if (state === 'observed' && (reason !== null || method !== 'read' || !origin || row.collectionStarted !== true)
+            || state !== 'observed' && reason === null
+            || reason === 'method' && (method === 'read' || row.collectionStarted)
+            || ['request_bound', 'host_bound', 'shutdown'].includes(reason ?? '') && row.collectionStarted
+            || state === 'unavailable' && reason !== 'address_or_transport')
+            throw new TypeError('Capture request coverage has contradictory collection states.');
+        return { position: integer(row.position, 'Capture request position', 1, 1_000_000), channel: enumeration(row.channel, CAPTURE_REQUEST_CHANNELS, 'Capture request channel'),
+            method, origin, state, reason, collectionStarted: row.collectionStarted };
+    });
+    if (attempts.some((row, index) => index > 0 && row.position <= attempts[index - 1].position))
+        throw new TypeError('Capture request positions must be unique and ordered.');
+    return { attempts, omittedAttempts: integer(value.omittedAttempts, 'Omitted capture attempts', 0, 1_000_000), disabledSurfaces: [...CAPTURE_DISABLED_SURFACES],
+        interactions: enumeration(value.interactions, ['not_exercised'], 'Capture interaction coverage'),
+        websocketRefusals: integer(value.websocketRefusals, 'WebSocket refusals', 0, 1_000_000), directConnectionRefusals: integer(value.directConnectionRefusals, 'Direct-connection refusals', 0, 1_000_000) };
+}
+export function captureAttemptDescription(value) {
+    const status = value.state === 'observed' ? 'Response supplied' : value.state === 'refused' ? 'Response refused' : 'Response unavailable';
+    const reason = { method: 'non-read method', request_bound: 'request limit', host_bound: 'host limit', response_bound: 'response byte limit', shutdown: 'capture closing', address_or_transport: 'address or transport check' };
+    return `${status}${value.reason ? ` · ${reason[value.reason]}` : ''} · collector ${value.collectionStarted ? 'started' : 'not started'}`;
+}
+/** Unseen in a bounded capture is not the same as disabled or absent. */
+export function captureChannelSummary(value) {
+    return CAPTURE_REQUEST_CHANNELS.map(channel => {
+        const rows = value.attempts.filter(row => row.channel === channel);
+        return { channel, observed: rows.filter(row => row.state === 'observed').length, refused: rows.filter(row => row.state === 'refused').length,
+            unavailable: rows.filter(row => row.state === 'unavailable').length,
+            coverage: rows.length ? 'recorded' : value.omittedAttempts ? 'unknown' : 'not_observed' };
+    });
+}

package/packages/investigation/connector-provenance-review.mjs

@@ -0,0 +1,100 @@
+import { array, exact, iso, record, text } from "../evidence/artifact-structure.mjs";
+import { pageObservationOrigin } from "./page-behaviour.mjs";
+import { CONTEXT_REVIEW_SCHEMA, CONTEXT_REVIEW_VERSION, MAX_CONTEXT_RECORDS, MAX_CONTEXT_INPUT_BYTES } from "../contracts/context-review.mjs";
+import { parseBoundedJson } from "../analysis/bounded-json.mjs";
+export { CONNECTOR_INPUT_SCHEMA, CONNECTOR_INPUT_VERSION } from "../contracts/context-review.mjs";
+const KNOWN_FIELDS = new Set(['url', 'serverUrl', 'command', 'args', 'env', 'headers', 'type', 'transport', 'disabled', 'enabled', 'capabilities', 'package', 'oauth', 'auth']);
+const CAPABILITIES = ['tools', 'resources', 'prompts', 'logging', 'completions'];
+const PACKAGE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-zA-Z0-9][a-zA-Z0-9.+_-]*)?$/u;
+function countObject(value, label) {
+    if (value === undefined)
+        return 0;
+    const keys = Object.keys(record(value, label));
+    if (keys.length > MAX_CONTEXT_RECORDS)
+        throw new TypeError(`${label} exceeds the metadata bound.`);
+    return keys.length;
+}
+/** Configuration is data only. Values of arguments, environment, headers and auth are never returned. */
+export function readConnectorConfiguration(raw) {
+    const root = record(raw, 'Connector configuration');
+    const roots = ['mcpServers', 'servers'].filter(key => Object.hasOwn(root, key));
+    if (roots.length !== 1)
+        throw new TypeError('Select a configuration with exactly one mcpServers or servers object.');
+    if (Object.keys(root).some(key => !roots.includes(key)))
+        throw new TypeError('Select only the connector configuration section; unrelated settings are not reviewed.');
+    const entries = Object.entries(record(root[roots[0]], 'Connector entries'));
+    if (entries.length > MAX_CONTEXT_RECORDS)
+        throw new TypeError('Connector count exceeds the review bound.');
+    return entries.map(([name, value]) => {
+        text(name, 'Connector name', 200);
+        const item = record(value, 'Connector definition');
+        if (Object.keys(item).length > MAX_CONTEXT_RECORDS)
+            throw new TypeError('Connector definition exceeds the field bound.');
+        if (item.enabled !== undefined && typeof item.enabled !== 'boolean' || item.disabled !== undefined && typeof item.disabled !== 'boolean'
+            || item.enabled !== undefined && item.disabled !== undefined && item.enabled === item.disabled)
+            throw new TypeError('Connector enablement declarations are invalid or conflicting.');
+        const suppliedUrl = item.url ?? item.serverUrl;
+        if (item.url !== undefined && item.serverUrl !== undefined && item.url !== item.serverUrl)
+            throw new TypeError('Conflicting connector URL declarations require a deliberate selection.');
+        const origin = suppliedUrl === undefined ? null : pageObservationOrigin(suppliedUrl);
+        if (suppliedUrl !== undefined && !origin)
+            throw new TypeError('Remote connector URL must be bounded HTTP(S) without credentials.');
+        const command = item.command === undefined ? null : text(item.command, 'Local connector command', 2_000);
+        const basename = command?.split(/[\\/]/u).at(-1) ?? null;
+        const executable = basename && /^[A-Za-z0-9._-]{1,120}$/u.test(basename) ? basename : null;
+        const args = item.args === undefined ? [] : array(item.args, 'Connector arguments', MAX_CONTEXT_RECORDS).map(value => text(value, 'Connector argument', 8_192, true));
+        let packageIdentity = item.package === undefined ? null : text(item.package, 'Declared connector package', 240);
+        if (packageIdentity !== null && !PACKAGE.test(packageIdentity))
+            throw new TypeError('Declared package must be a package identity, not an executable expression or URL.');
+        if (packageIdentity === null && ['npx', 'npx.cmd', 'uvx'].includes(executable ?? '')) {
+            // Only a simple first package operand is interpreted. Complex invocations remain unknown.
+            const operands = args.filter(value => !['--yes', '-y', '--no-install'].includes(value));
+            if (operands[0] && PACKAGE.test(operands[0]))
+                packageIdentity = operands[0];
+        }
+        const capabilityObject = item.capabilities === undefined ? {} : record(item.capabilities, 'Declared capabilities');
+        if (Object.keys(capabilityObject).length > MAX_CONTEXT_RECORDS)
+            throw new TypeError('Declared capabilities exceed the bound.');
+        return { name, transport: origin && command ? 'ambiguous' : origin ? 'remote' : command ? 'local' : 'unknown', enabled: item.enabled === false || item.disabled === true ? 'disabled' : item.enabled === true || item.disabled === false ? 'enabled' : 'unknown', origin, executable, package: packageIdentity,
+            argumentCount: args.length, environmentCount: countObject(item.env, 'Environment metadata'), headerCount: countObject(item.headers, 'Header metadata'),
+            authenticationDeclared: item.auth !== undefined || item.oauth !== undefined,
+            declaredCapabilities: CAPABILITIES.filter(key => Object.hasOwn(capabilityObject, key) && capabilityObject[key] !== false && capabilityObject[key] !== null),
+            unsupportedFields: Object.keys(item).filter(key => !KNOWN_FIELDS.has(key)).length + Object.keys(capabilityObject).filter(key => !CAPABILITIES.includes(key)).length,
+            privateLocationOmitted: suppliedUrl !== undefined && new URL(suppliedUrl).href !== `${origin}/` || command !== null && command !== executable,
+        };
+    });
+}
+export function connectorProvenancePresentation(raw, reviewedAt) {
+    iso(reviewedAt, 'Review time');
+    const input = exact(raw, ['current', 'previous'], 'Connector review');
+    const current = readConnectorConfiguration(input.current), previous = input.previous === null ? null : readConnectorConfiguration(input.previous);
+    const signature = (row) => JSON.stringify([row.transport, row.enabled, row.origin, row.executable, row.package, row.argumentCount, row.environmentCount, row.headerCount, row.authenticationDeclared, row.declaredCapabilities]);
+    const observations = current.map(row => {
+        const old = previous?.find(value => value.name === row.name);
+        const changed = old ? signature(old) !== signature(row) : false;
+        return { label: `${row.name} · ${row.transport} connector`, state: row.transport === 'unknown' || row.transport === 'ambiguous' || row.unsupportedFields ? 'partial' : changed ? 'changed' : 'reported',
+            detail: `Declared enablement: ${row.enabled}. Endpoint: ${row.origin ?? 'not supplied'}; executable: ${row.executable ?? 'not retained or unknown'}; package: ${row.package ?? 'not established'}. Arguments: ${row.argumentCount}; environment entries: ${row.environmentCount}; headers: ${row.headerCount}; auth declaration ${row.authenticationDeclared ? 'present' : 'not supplied'}. Capabilities: ${row.declaredCapabilities.join(', ') || 'not declared'}. ${previous ? old ? changed ? 'Retained metadata changed.' : 'Retained metadata matches; excluded values were not compared.' : 'Newly listed connector.' : 'No earlier configuration selected.'}${row.unsupportedFields ? ` Uninterpreted fields: ${row.unsupportedFields}.` : ''}${row.privateLocationOmitted ? ' Private location detail omitted.' : ''}`,
+            source: 'Analyst-selected local configuration; declarations were not negotiated with a server', observedAt: null, hostname: row.origin ? new URL(row.origin).hostname : null };
+    });
+    for (const row of previous ?? [])
+        if (!current.some(value => value.name === row.name))
+            observations.push({ label: `${row.name} · no longer listed`, state: 'changed', detail: 'Absent from the selected current configuration; this does not establish that a process or endpoint has stopped.', source: 'Selected configuration comparison', observedAt: null, hostname: row.origin ? new URL(row.origin).hostname : null });
+    const report = { schema: CONTEXT_REVIEW_SCHEMA, version: CONTEXT_REVIEW_VERSION, kind: 'connector', reviewedAt, title: 'Connector provenance', state: !current.length || observations.some(row => row.state === 'partial') ? 'partial' : 'reviewed',
+        summary: `Configured connectors: ${current.length}${previous ? `; earlier configuration entries: ${previous.length}` : ''}. Commands were not run and endpoints were not contacted.`, observations,
+        nextSteps: ['Verify package publisher, exact version, installation source and requested privileges through a trusted source before enabling a local connector.', 'For remote connectors, investigate the endpoint domain separately and review authentication and data-sharing scope before granting access.', 'Review tool, resource and prompt capabilities against the task. Configuration declarations are not evidence of negotiated capabilities or trustworthy behaviour.'],
+        limitations: ['Arguments, local paths, environment values, header values, auth material and URL paths or queries are excluded from this report. Names and package identities remain visible; review them before sharing.', 'Matching retained metadata does not mean excluded values are unchanged. This is not code execution, a server connection, a protocol conformance test or safety certification.'] };
+    return { report, connectors: current };
+}
+export function reviewConnectorProvenance(raw, reviewedAt) {
+    return connectorProvenancePresentation(raw, reviewedAt).report;
+}
+export function reviewConnectorConfigurationText(current, previous, reviewedAt) {
+    return connectorConfigurationPresentation(current, previous, reviewedAt).report;
+}
+/** Browser presentation receives only the same minimised metadata as the report. */
+export function connectorConfigurationPresentation(current, previous, reviewedAt) {
+    if (typeof current !== 'string' || typeof previous !== 'string')
+        throw new TypeError('Select connector configuration text.');
+    const parse = (value) => parseBoundedJson(value, { label: 'Connector configuration', maximumBytes: MAX_CONTEXT_INPUT_BYTES });
+    return connectorProvenancePresentation({ current: parse(current), previous: previous.trim() ? parse(previous) : null }, reviewedAt);
+}

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