@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/interchange/web-capture-import.mjs

@@ -0,0 +1,389 @@
+import { normalizeDomain } from "../evidence/domain-name.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_SUMMARY_LENGTH, parseExternalFindingsDocument, retainExternalFindingLimitations, } from "./external-findings-import.mjs";
+import { MAX_WEB_CAPTURE_DOM_DIGEST_BYTES, MAX_WEB_CAPTURE_SCREENSHOT_BYTES, WEB_CAPTURE_MANIFEST_SCHEMA, WEB_CAPTURE_MANIFEST_VERSION, WEB_CAPTURE_MANIFEST_SUPPORTED_VERSIONS, WEB_CAPTURE_SUMMARY_SCHEMA, WEB_CAPTURE_SUMMARY_VERSION, } from "../contracts/web-capture.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { readManifestPageBehaviour } from "../investigation/page-behaviour.mjs";
+import { readCaptureConditions, readObservationLabel } from "../comparison/capture-context.mjs";
+export { WEB_CAPTURE_MANIFEST_SCHEMA, WEB_CAPTURE_MANIFEST_VERSION, WEB_CAPTURE_SUMMARY_SCHEMA, WEB_CAPTURE_SUMMARY_VERSION, } from "../contracts/web-capture.mjs";
+export const MAX_WEB_CAPTURE_SUMMARIES = 50;
+export { MAX_WEB_CAPTURE_DOM_DIGEST_BYTES, MAX_WEB_CAPTURE_SCREENSHOT_BYTES } from "../contracts/web-capture.mjs";
+const MAX_CAPTURE_TECHNOLOGIES = 20;
+const MAX_CAPTURE_ORIGINS = 30;
+const SHA256_RE = /^[a-f0-9]{64}$/i;
+const PERCEPTUAL_HASH_RE = /^[a-f0-9]{16}$/i;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
+const ROOT_KEYS = new Set(['schema', 'schemaVersion', 'source', 'captures']);
+const SOURCE_KEYS = new Set(['name', 'reference', 'collectedAt']);
+const CAPTURE_KEYS = new Set([
+    'domain',
+    'capturedAt',
+    'completeness',
+    'limitations',
+    'pageTitle',
+    'finalOrigin',
+    'screenshotSha256',
+    'technologies',
+    'networkOrigins',
+]);
+const MANIFEST_CAPTURE_KEYS = new Set([
+    'pageBehaviour',
+    'conditions', 'observerLabel', 'vantageLabel',
+    'domain',
+    'capturedAt',
+    'completeness',
+    'limitations',
+    'page',
+    'requestDomains',
+    'technologies',
+    'artifacts',
+]);
+const PAGE_KEYS = new Set(['title', 'finalOrigin']);
+const ARTIFACT_KEYS = new Set(['kind', 'fileName', 'mimeType', 'sha256', 'perceptualHash', 'bytes', 'width', 'height']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function onlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function text(value, maximum, label, optional = false) {
+    if (optional && (value === undefined || value === null || value === ''))
+        return null;
+    if (typeof value !== 'string' || !value.trim() || value.length > maximum || CONTROL_RE.test(value)) {
+        throw new Error(`${label} must be bounded text without control characters.`);
+    }
+    return value.replace(/\s+/g, ' ').trim();
+}
+function timestamp(value, label, optional = false) {
+    const candidate = text(value, 64, label, optional);
+    if (candidate === null)
+        return null;
+    const normalized = normalizeExplicitIsoTimestamp(candidate);
+    if (!normalized)
+        throw new Error(`${label} must be a valid date and time with an explicit timezone.`);
+    return normalized;
+}
+function origin(value, label) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    const candidate = text(value, 500, label);
+    try {
+        const parsed = new URL(candidate ?? '');
+        if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password)
+            throw new Error();
+        if (parsed.pathname !== '/' || parsed.search || parsed.hash)
+            throw new Error();
+        return parsed.origin.toLowerCase();
+    }
+    catch {
+        throw new Error(`${label} must be an HTTP(S) origin without credentials, path, query, or fragment.`);
+    }
+}
+function stringList(value, maximumItems, maximumLength, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > maximumItems)
+        throw new Error(`${label} exceeds its item bound.`);
+    const output = new Set();
+    for (const item of value) {
+        const normalized = text(item, maximumLength, label);
+        if (normalized)
+            output.add(normalized);
+    }
+    return [...output];
+}
+export function parseWebCaptureSummary(value) {
+    const root = record(value);
+    if (!root
+        || !onlyKeys(root, ROOT_KEYS)
+        || root.schema !== WEB_CAPTURE_SUMMARY_SCHEMA
+        || root.schemaVersion !== WEB_CAPTURE_SUMMARY_VERSION) {
+        throw new Error(`Web captures must use ${WEB_CAPTURE_SUMMARY_SCHEMA} schema version ${WEB_CAPTURE_SUMMARY_VERSION}.`);
+    }
+    const source = record(root.source);
+    if (!source || !onlyKeys(source, SOURCE_KEYS))
+        throw new Error('Web captures require a bounded source object.');
+    const sourceName = text(source.name, 80, 'Capture source name');
+    const sourceReference = text(source.reference, 500, 'Capture source reference', true);
+    const sourceCollectedAt = timestamp(source.collectedAt, 'Capture source collection time', true);
+    if (!Array.isArray(root.captures) || !root.captures.length || root.captures.length > MAX_WEB_CAPTURE_SUMMARIES) {
+        throw new Error(`Web captures must contain between 1 and ${MAX_WEB_CAPTURE_SUMMARIES} summaries.`);
+    }
+    const findings = [];
+    const domainCounts = new Map();
+    for (const [index, raw] of root.captures.entries()) {
+        const capture = record(raw);
+        if (!capture || !onlyKeys(capture, CAPTURE_KEYS))
+            throw new Error(`Web capture ${index + 1} contains unsupported fields.`);
+        const domain = normalizeDomain(text(capture.domain, 253, `Web capture ${index + 1} domain`));
+        if (!domain)
+            throw new Error(`Web capture ${index + 1} domain is invalid.`);
+        const domainCount = (domainCounts.get(domain) ?? 0) + 1;
+        if (domainCount > MAX_EXTERNAL_FINDINGS_PER_DOMAIN) {
+            throw new Error(`Web captures exceed the ${MAX_EXTERNAL_FINDINGS_PER_DOMAIN}-summary per-domain limit.`);
+        }
+        domainCounts.set(domain, domainCount);
+        if (domainCounts.size > MAX_EXTERNAL_FINDING_DOMAINS) {
+            throw new Error(`Web captures exceed the ${MAX_EXTERNAL_FINDING_DOMAINS}-domain limit.`);
+        }
+        const observedAt = timestamp(capture.capturedAt, `Web capture ${index + 1} time`);
+        const completeness = ['complete', 'inconclusive', 'partial', 'unknown'].includes(String(capture.completeness))
+            ? capture.completeness
+            : 'unknown';
+        const limitations = stringList(capture.limitations, 8, 240, `Web capture ${index + 1} limitations`);
+        const pageTitle = text(capture.pageTitle, 300, `Web capture ${index + 1} title`, true);
+        const finalOrigin = origin(capture.finalOrigin, `Web capture ${index + 1} final origin`);
+        const technologies = stringList(capture.technologies, MAX_CAPTURE_TECHNOLOGIES, 80, `Web capture ${index + 1} technologies`);
+        const networkOrigins = stringList(capture.networkOrigins, MAX_CAPTURE_ORIGINS, 500, `Web capture ${index + 1} network origins`)
+            .map((item, originIndex) => origin(item, `Web capture ${index + 1} network origin ${originIndex + 1}`))
+            .filter((item) => item !== null);
+        const screenshotSha256 = capture.screenshotSha256 === undefined || capture.screenshotSha256 === null || capture.screenshotSha256 === ''
+            ? null
+            : typeof capture.screenshotSha256 === 'string' && SHA256_RE.test(capture.screenshotSha256)
+                ? capture.screenshotSha256.toLowerCase()
+                : (() => { throw new Error(`Web capture ${index + 1} screenshot digest must be SHA-256.`); })();
+        const summaries = [
+            pageTitle || finalOrigin
+                ? `Sanitised page capture${pageTitle ? ` titled "${pageTitle}"` : ''}${finalOrigin ? ` ended at origin ${finalOrigin}` : ''}.`
+                : '',
+            technologies.length ? `Observed technology labels: ${technologies.join(', ')}.` : '',
+            networkOrigins.length ? `Observed network origins: ${networkOrigins.join(', ')}.` : '',
+            screenshotSha256 ? `Screenshot SHA-256: ${screenshotSha256}.` : '',
+        ].filter(Boolean);
+        if (!summaries.length)
+            throw new Error(`Web capture ${index + 1} contains no supported summary evidence.`);
+        const retainedLimitations = retainExternalFindingLimitations(limitations, [
+            'Imported sanitised capture summary; WHOISleuth did not collect or independently verify this observation.',
+        ]);
+        findings.push({
+            domain,
+            category: technologies.length && summaries.length === 1 ? 'http' : 'page',
+            evidenceClass: 'deployment_observation',
+            summary: summaries.join(' '),
+            observedAt,
+            completeness: limitations.every((item) => retainedLimitations.includes(item)) ? completeness : 'partial',
+            limitations: retainedLimitations,
+            reference: sourceReference,
+        });
+    }
+    return parseExternalFindingsDocument({
+        schema: EXTERNAL_FINDINGS_SCHEMA,
+        schemaVersion: EXTERNAL_FINDINGS_VERSION,
+        source: { name: sourceName, reference: sourceReference, collectedAt: sourceCollectedAt },
+        findings,
+    });
+}
+function artifactName(value, label) {
+    const candidate = text(value, 120, label) ?? '';
+    if (candidate === '.'
+        || candidate === '..'
+        || candidate.includes('/')
+        || candidate.includes('\\')
+        || candidate.includes('%2f')
+        || candidate.includes('%5c')) {
+        throw new Error(`${label} must be a plain file name without a path.`);
+    }
+    return candidate;
+}
+function positiveInteger(value, maximum, label) {
+    if (!Number.isInteger(value) || Number(value) <= 0 || Number(value) > maximum) {
+        throw new Error(`${label} is outside the supported bound.`);
+    }
+    return Number(value);
+}
+function listSummaryFragments(label, values) {
+    const fragments = [];
+    let current = `${label}:`;
+    for (const value of values) {
+        const separator = current === `${label}:` ? ' ' : ', ';
+        if (`${current}${separator}${value}.`.length > MAX_EXTERNAL_FINDING_SUMMARY_LENGTH) {
+            fragments.push(`${current}.`);
+            current = `${label}: ${value}`;
+        }
+        else
+            current += `${separator}${value}`;
+    }
+    if (current !== `${label}:`)
+        fragments.push(`${current}.`);
+    return fragments;
+}
+function partitionSummary(fragments) {
+    const summaries = [];
+    let current = '';
+    for (const fragment of fragments) {
+        if (!fragment || fragment.length > MAX_EXTERNAL_FINDING_SUMMARY_LENGTH) {
+            throw new Error('Web capture metadata cannot be represented within the external-finding summary bound.');
+        }
+        const combined = current ? `${current} ${fragment}` : fragment;
+        if (combined.length > MAX_EXTERNAL_FINDING_SUMMARY_LENGTH) {
+            summaries.push(current);
+            current = fragment;
+        }
+        else
+            current = combined;
+    }
+    if (current)
+        summaries.push(current);
+    return summaries;
+}
+export function readWebCaptureManifest(value) {
+    const root = record(value);
+    if (!root
+        || !onlyKeys(root, ROOT_KEYS)
+        || root.schema !== WEB_CAPTURE_MANIFEST_SCHEMA
+        || !WEB_CAPTURE_MANIFEST_SUPPORTED_VERSIONS.includes(root.schemaVersion)) {
+        throw new Error(`Web capture manifests must use ${WEB_CAPTURE_MANIFEST_SCHEMA} schema version ${WEB_CAPTURE_MANIFEST_VERSION}.`);
+    }
+    const source = record(root.source);
+    if (!source || !onlyKeys(source, SOURCE_KEYS))
+        throw new Error('Web capture manifests require a bounded source object.');
+    const sourceName = text(source.name, 80, 'Capture source name');
+    const sourceReference = text(source.reference, 500, 'Capture source reference', true);
+    const sourceCollectedAt = timestamp(source.collectedAt, 'Capture source collection time', true);
+    if (!Array.isArray(root.captures) || !root.captures.length || root.captures.length > MAX_WEB_CAPTURE_SUMMARIES) {
+        throw new Error(`Web capture manifests must contain between 1 and ${MAX_WEB_CAPTURE_SUMMARIES} captures.`);
+    }
+    const findings = [];
+    const artifacts = [];
+    const contexts = [];
+    const domainCounts = new Map();
+    const findingCounts = new Map();
+    for (const [index, raw] of root.captures.entries()) {
+        const capture = record(raw);
+        if (!capture || !onlyKeys(capture, MANIFEST_CAPTURE_KEYS)) {
+            throw new Error(`Web capture manifest ${index + 1} contains unsupported fields or archive content.`);
+        }
+        const domain = normalizeDomain(text(capture.domain, 253, `Web capture manifest ${index + 1} domain`));
+        if (!domain)
+            throw new Error(`Web capture manifest ${index + 1} domain is invalid.`);
+        const domainCount = (domainCounts.get(domain) ?? 0) + 1;
+        if (domainCount > MAX_EXTERNAL_FINDINGS_PER_DOMAIN) {
+            throw new Error(`Web capture manifests exceed the ${MAX_EXTERNAL_FINDINGS_PER_DOMAIN}-capture per-domain limit.`);
+        }
+        domainCounts.set(domain, domainCount);
+        if (domainCounts.size > MAX_EXTERNAL_FINDING_DOMAINS) {
+            throw new Error(`Web capture manifests exceed the ${MAX_EXTERNAL_FINDING_DOMAINS}-domain limit.`);
+        }
+        const observedAt = timestamp(capture.capturedAt, `Web capture manifest ${index + 1} time`);
+        const conditions = readCaptureConditions(capture.conditions);
+        const observerLabel = readObservationLabel(capture.observerLabel), vantageLabel = readObservationLabel(capture.vantageLabel);
+        const completeness = ['complete', 'inconclusive', 'partial', 'unknown'].includes(String(capture.completeness))
+            ? capture.completeness
+            : 'unknown';
+        const limitations = stringList(capture.limitations, 8, 240, `Web capture manifest ${index + 1} limitations`);
+        const pageBehaviour = readManifestPageBehaviour(capture.pageBehaviour, root.schemaVersion);
+        if (pageBehaviour?.state === 'partial' && completeness === 'complete')
+            throw new Error('Partial page observations cannot declare a complete capture.');
+        contexts.push({ domain, observedAt, completeness: String(completeness), conditions, observerLabel, vantageLabel, pageBehaviour });
+        const page = record(capture.page);
+        if (page && !onlyKeys(page, PAGE_KEYS))
+            throw new Error(`Web capture manifest ${index + 1} page metadata contains unsupported fields.`);
+        const pageTitle = text(page?.title, 300, `Web capture manifest ${index + 1} title`, true);
+        const finalOrigin = origin(page?.finalOrigin, `Web capture manifest ${index + 1} final origin`);
+        const technologies = stringList(capture.technologies, MAX_CAPTURE_TECHNOLOGIES, 80, `Web capture manifest ${index + 1} technologies`);
+        const requestDomains = stringList(capture.requestDomains, MAX_CAPTURE_ORIGINS, 253, `Web capture manifest ${index + 1} request domains`)
+            .map((item) => normalizeDomain(item))
+            .filter((item) => Boolean(item));
+        if (!Array.isArray(capture.artifacts) || !capture.artifacts.length || capture.artifacts.length > 2) {
+            throw new Error(`Web capture manifest ${index + 1} must contain one or two artifact metadata records.`);
+        }
+        const artifactSummaries = [];
+        const kinds = new Set();
+        for (const [artifactIndex, rawArtifact] of capture.artifacts.entries()) {
+            const artifact = record(rawArtifact);
+            if (!artifact || !onlyKeys(artifact, ARTIFACT_KEYS)) {
+                throw new Error(`Web capture manifest ${index + 1} artifact ${artifactIndex + 1} contains unsupported fields.`);
+            }
+            const kind = artifact.kind === 'screenshot' || artifact.kind === 'dom_digest' ? artifact.kind : null;
+            if (!kind || kinds.has(kind))
+                throw new Error(`Web capture manifest ${index + 1} has an invalid or duplicate artifact kind.`);
+            kinds.add(kind);
+            const fileName = artifactName(artifact.fileName, `Web capture manifest ${index + 1} artifact name`);
+            const sha256 = typeof artifact.sha256 === 'string' && SHA256_RE.test(artifact.sha256)
+                ? artifact.sha256.toLowerCase()
+                : null;
+            if (!sha256)
+                throw new Error(`Web capture manifest ${index + 1} artifact digest must be SHA-256.`);
+            const mimeType = text(artifact.mimeType, 80, `Web capture manifest ${index + 1} artifact MIME type`)?.toLowerCase();
+            const maximumBytes = kind === 'screenshot' ? MAX_WEB_CAPTURE_SCREENSHOT_BYTES : MAX_WEB_CAPTURE_DOM_DIGEST_BYTES;
+            const bytes = positiveInteger(artifact.bytes, maximumBytes, `Web capture manifest ${index + 1} artifact size`);
+            if (kind === 'screenshot') {
+                if (!['image/png', 'image/jpeg', 'image/webp'].includes(mimeType || '')) {
+                    throw new Error(`Web capture manifest ${index + 1} screenshot MIME type is unsupported.`);
+                }
+                const width = positiveInteger(artifact.width, 10_000, `Web capture manifest ${index + 1} screenshot width`);
+                const height = positiveInteger(artifact.height, 10_000, `Web capture manifest ${index + 1} screenshot height`);
+                const perceptualHash = artifact.perceptualHash === undefined || artifact.perceptualHash === null || artifact.perceptualHash === ''
+                    ? null
+                    : typeof artifact.perceptualHash === 'string' && PERCEPTUAL_HASH_RE.test(artifact.perceptualHash)
+                        ? artifact.perceptualHash.toLowerCase()
+                        : (() => { throw new Error(`Web capture manifest ${index + 1} screenshot perceptual hash is unsupported.`); })();
+                artifactSummaries.push(`Screenshot ${fileName}: ${mimeType}, ${width}x${height}, ${bytes} bytes, SHA-256 ${sha256}${perceptualHash ? `, dHash ${perceptualHash}` : ''}.`);
+            }
+            else {
+                if (mimeType !== 'application/json')
+                    throw new Error(`Web capture manifest ${index + 1} DOM digest MIME type is unsupported.`);
+                if (artifact.width !== undefined || artifact.height !== undefined || artifact.perceptualHash !== undefined) {
+                    throw new Error(`Web capture manifest ${index + 1} DOM digest cannot declare image-only fields.`);
+                }
+                artifactSummaries.push(`DOM digest ${fileName}: application/json, ${bytes} bytes, SHA-256 ${sha256}.`);
+            }
+            artifacts.push({ capture: index + 1, observedAt, kind, fileName, mimeType: mimeType, sha256, bytes });
+        }
+        const summaryFragments = [
+            ...(conditions ? [`Declared capture conditions: ${conditions.browser} ${conditions.browserVersion}; viewport ${conditions.viewport.width}x${conditions.viewport.height}; scale ${conditions.deviceScaleFactor}; locale ${conditions.locale}; timezone ${conditions.timezone}; ${conditions.colourScheme}.`] : []),
+            ...(observerLabel || vantageLabel ? [`Declared observer: ${observerLabel ?? 'unknown'}; vantage: ${vantageLabel ?? 'unknown'}. These labels do not verify collection independence.`] : []),
+            pageTitle || finalOrigin
+                ? `Sanitised page capture${pageTitle ? ` titled "${pageTitle}"` : ''}${finalOrigin ? ` ended at origin ${finalOrigin}` : ''}.`
+                : '',
+            ...listSummaryFragments('Observed technology labels', technologies),
+            ...listSummaryFragments('Observed request domains', requestDomains),
+            ...(pageBehaviour ? [`Page observations: ${pageBehaviour.requests.length} navigation/script/frame responses; ${pageBehaviour.elements.length} script/frame/form elements; ${pageBehaviour.clipboardWriteAttempts} blocked Clipboard API write attempts. State: ${pageBehaviour.state}. Full observations remain in the selected manifest.`,
+                ...listSummaryFragments('Requested-action wording in body text', pageBehaviour.actionHints)] : []),
+            ...artifactSummaries,
+        ].filter(Boolean);
+        const summaries = partitionSummary(summaryFragments);
+        const priorFindingCount = findingCounts.get(domain) ?? 0;
+        if (priorFindingCount + summaries.length > MAX_EXTERNAL_FINDINGS_PER_DOMAIN) {
+            throw new Error(`Web capture manifests exceed the ${MAX_EXTERNAL_FINDINGS_PER_DOMAIN}-finding per-domain import limit after preserving bounded metadata.`);
+        }
+        findingCounts.set(domain, priorFindingCount + summaries.length);
+        const retainedLimitations = retainExternalFindingLimitations(limitations, [
+            'Imported capture metadata, not independently collected website evidence; artefact bytes and separate byte checks are not retained in these findings.',
+        ]);
+        for (const summary of summaries) {
+            findings.push({
+                domain,
+                category: 'page',
+                evidenceClass: 'deployment_observation',
+                summary,
+                observedAt,
+                completeness: limitations.every((item) => retainedLimitations.includes(item)) ? completeness : 'partial',
+                limitations: retainedLimitations,
+                reference: sourceReference,
+            });
+        }
+    }
+    const document = parseExternalFindingsDocument({
+        schema: EXTERNAL_FINDINGS_SCHEMA,
+        schemaVersion: EXTERNAL_FINDINGS_VERSION,
+        source: { name: sourceName, reference: sourceReference, collectedAt: sourceCollectedAt },
+        findings,
+    });
+    return { document, artifacts, captures: contexts };
+}
+export function parseWebCaptureManifest(value) {
+    return readWebCaptureManifest(value).document;
+}
+// Candidates must describe bytes already read and hashed by the caller. File
+// names and MIME declarations never establish identity; equal copies are all
+// reported rather than choosing an arbitrary file.
+export function matchCaptureArtifacts(artifacts, candidates) {
+    return artifacts.map(artifact => {
+        const matchingIds = candidates.filter(candidate => candidate.bytes === artifact.bytes
+            && candidate.sha256.replace(/^sha256:/u, '') === artifact.sha256)
+            .map(candidate => candidate.id);
+        return { capture: artifact.capture, kind: artifact.kind, state: matchingIds.length ? 'matched' : 'not_found', matchingIds };
+    });
+}

package/packages/investigation/acquisition-decision-packet.mjs

@@ -1,6 +1,6 @@
 import { SORTED_JSON_V2, sha256ArtifactDigestV2 } from "../evidence/artifact-integrity.mjs";
 import { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION, } from "../contracts/investigation-portability.mjs";
-import { isValidAsciiDomainName } from "../../lib/hostname.mjs";
+import { isValidAsciiDomainName } from "../contracts/domain-name.mjs";
 export { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION };
 export const ACQUISITION_DECISIONS = [
     'unresolved',

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,12 +166,13 @@ 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),
             registration: item.availability,
-            sourceCoverage: item.sourceCoverage.slice(0, 12),
+            // The published review retains source states; full source clocks stay in the workspace.
+            sourceCoverage: item.sourceCoverage.map(({ source, state }) => ({ source, state })),
             profileContextState: item.profileContext.sourceState,
             profileContextLimitation,
             limitations: rowLimitations(item, state, profileSourceState, profileContextComparable, profileContextLimitation),
@@ -216,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);
+}