@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/packages/interchange/stix-indicator-export.mjs

@@ -0,0 +1,129 @@
+// Pure STIX 2.1 interchange for locally reviewed Bulk candidates. Direct
+// observations and heuristic inferences remain separate objects so consumers
+// do not mistake a Risk score for confirmed maliciousness.
+import { collectDefensiveIndicatorCandidates, defensiveIndicatorProvenance, } from "./defensive-indicator-export.mjs";
+import { STIX_INDICATOR_EXPORT_VERSION } from "../contracts/analyst-interchange.mjs";
+export { STIX_INDICATOR_EXPORT_VERSION } from "../contracts/analyst-interchange.mjs";
+export const MAX_STIX_INDICATORS = 1000;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const CONTROL_RE = /[\x00-\x1f\x7f]/;
+const WARNING = 'Heuristic finding; review before operational use because false positives are possible.';
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function isoTimestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || CONTROL_RE.test(value))
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function defaultIdFactory(type) {
+    const uuid = globalThis.crypto?.randomUUID?.();
+    if (!uuid)
+        throw new Error('Secure random identifiers are unavailable for the STIX export.');
+    return `${type}--${uuid}`;
+}
+function stixId(type, idFactory) {
+    const value = idFactory(type);
+    const prefix = `${type}--`;
+    if (typeof value !== 'string' || !value.startsWith(prefix) || !UUID_RE.test(value.slice(prefix.length))) {
+        throw new Error(`The STIX identifier factory returned an invalid ${type} identifier.`);
+    }
+    return value.toLowerCase();
+}
+export function stixIndicatorProducer(producerId, generatedAt) {
+    return {
+        type: 'identity', spec_version: '2.1', id: producerId,
+        created: generatedAt, modified: generatedAt,
+        name: 'WHOISleuth', identity_class: 'system',
+        description: 'Producer of locally generated defensive-domain observations and heuristic inferences.',
+        x_whoisleuth_export_version: STIX_INDICATOR_EXPORT_VERSION,
+        x_whoisleuth_generated_at: generatedAt,
+        x_whoisleuth_false_positive_warning: WARNING,
+    };
+}
+/** The caller owns validated candidates and either fresh or retained identities. */
+export function stixIndicatorObjects(domain, availability, provenance, generatedAt, producerId, nextId) {
+    const { observedAt, riskScore: score, riskModelVersion: modelVersion } = provenance;
+    const domainId = nextId('domain-name');
+    const observationId = nextId(observedAt ? 'observed-data' : 'note');
+    const indicatorId = nextId('indicator');
+    const observationContext = {
+        created_by_ref: producerId, created: generatedAt, modified: generatedAt,
+        x_whoisleuth_observed_at_basis: observedAt ? 'scan' : 'unknown',
+        x_whoisleuth_source: 'bulk', x_whoisleuth_availability: availability,
+        x_whoisleuth_scan_depth: provenance.scanDepth,
+    };
+    const objects = [
+        { type: 'domain-name', spec_version: '2.1', id: domainId, value: domain },
+        observedAt ? {
+            type: 'observed-data', spec_version: '2.1', id: observationId, ...observationContext,
+            first_observed: observedAt, last_observed: observedAt, number_observed: 1, object_refs: [domainId],
+            x_whoisleuth_evidence_kind: 'direct-observation',
+        } : {
+            type: 'note', spec_version: '2.1', id: observationId, ...observationContext,
+            content: 'Observation time was not retained. This candidate is supplied for heuristic review; its export time is not a sighting time.',
+            object_refs: [domainId, indicatorId], x_whoisleuth_evidence_kind: 'observation-context',
+        },
+        {
+            type: 'indicator', spec_version: '2.1', id: indicatorId,
+            created_by_ref: producerId, created: generatedAt, modified: generatedAt,
+            name: `Heuristic domain candidate: ${domain}`, description: WARNING,
+            pattern: `[domain-name:value = '${domain}']`, pattern_type: 'stix', pattern_version: '2.1',
+            valid_from: generatedAt, x_whoisleuth_validity_basis: 'export',
+            labels: ['heuristic', 'defensive-review'], x_whoisleuth_evidence_kind: 'heuristic-inference',
+            x_whoisleuth_risk_score: score,
+            ...(modelVersion === null ? {} : { x_whoisleuth_risk_model_version: modelVersion }),
+            x_whoisleuth_false_positive_warning: WARNING,
+        },
+    ];
+    if (observedAt)
+        objects.push({
+            type: 'relationship', spec_version: '2.1', id: nextId('relationship'),
+            created_by_ref: producerId, created: generatedAt, modified: generatedAt,
+            relationship_type: 'based-on', source_ref: indicatorId, target_ref: observationId,
+            description: 'The heuristic Indicator is based on the separately represented domain observation.',
+        });
+    return objects;
+}
+export function buildStixIndicatorExport(records, options = {}) {
+    const generatedAt = isoTimestamp(options.generatedAt) || new Date().toISOString();
+    const idFactory = typeof options.idFactory === 'function'
+        ? options.idFactory
+        : defaultIdFactory;
+    let collected;
+    try {
+        collected = collectDefensiveIndicatorCandidates(records, MAX_STIX_INDICATORS);
+    }
+    catch (cause) {
+        if (cause instanceof TypeError)
+            throw new TypeError('STIX indicator export requires an array of Bulk results.');
+        throw cause;
+    }
+    const usedIds = new Set();
+    const nextId = (type) => {
+        const id = stixId(type, idFactory);
+        if (usedIds.has(id))
+            throw new Error('The STIX identifier factory returned a duplicate identifier.');
+        usedIds.add(id);
+        return id;
+    };
+    const producerId = nextId('identity');
+    const objects = [stixIndicatorProducer(producerId, generatedAt)];
+    for (const { domain, source } of collected.entries) {
+        objects.push(...stixIndicatorObjects(domain, record(source).availability, defensiveIndicatorProvenance(source), generatedAt, producerId, nextId));
+    }
+    const bundle = { type: 'bundle', id: nextId('bundle'), objects };
+    return {
+        version: STIX_INDICATOR_EXPORT_VERSION,
+        format: 'stix',
+        generatedAt,
+        domains: collected.domains,
+        truncated: collected.truncated,
+        filename: `whoisleuth-defensive-domains-${generatedAt.slice(0, 10)}.stix.json`,
+        mimeType: 'application/stix+json;charset=utf-8',
+        content: `${JSON.stringify(bundle, null, 2)}\n`,
+    };
+}

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

@@ -1,7 +1,8 @@
-import { normalizeDomain } from "../cases/case-model.mjs";
-import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_SUMMARY_LENGTH, parseExternalFindingsDocument, } 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_SUMMARY_SCHEMA, WEB_CAPTURE_SUMMARY_VERSION, } from "../contracts/web-capture.mjs";
+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;
@@ -25,6 +26,7 @@ const CAPTURE_KEYS = new Set([
     'networkOrigins',
 ]);
 const MANIFEST_CAPTURE_KEYS = new Set([
+    'pageBehaviour',
     'conditions', 'observerLabel', 'vantageLabel',
     'domain',
     'capturedAt',
@@ -151,17 +153,17 @@ export function parseWebCaptureSummary(value) {
         ].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: [
-                'Imported sanitised capture summary; WHOISleuth did not collect or independently verify this observation.',
-                ...limitations,
-            ].slice(0, 8),
+            completeness: limitations.every((item) => retainedLimitations.includes(item)) ? completeness : 'partial',
+            limitations: retainedLimitations,
             reference: sourceReference,
         });
     }
@@ -230,7 +232,7 @@ export function readWebCaptureManifest(value) {
     if (!root
         || !onlyKeys(root, ROOT_KEYS)
         || root.schema !== WEB_CAPTURE_MANIFEST_SCHEMA
-        || root.schemaVersion !== WEB_CAPTURE_MANIFEST_VERSION) {
+        || !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);
@@ -270,7 +272,10 @@ export function readWebCaptureManifest(value) {
             ? capture.completeness
             : 'unknown';
         const limitations = stringList(capture.limitations, 8, 240, `Web capture manifest ${index + 1} limitations`);
-        contexts.push({ domain, observedAt, completeness: String(completeness), conditions, observerLabel, vantageLabel });
+        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.`);
@@ -334,6 +339,8 @@ export function readWebCaptureManifest(value) {
                 : '',
             ...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);
@@ -342,6 +349,9 @@ export function readWebCaptureManifest(value) {
             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,
@@ -349,11 +359,8 @@ export function readWebCaptureManifest(value) {
                 evidenceClass: 'deployment_observation',
                 summary,
                 observedAt,
-                completeness,
-                limitations: [
-                    'Imported capture metadata, not independently collected website evidence; artefact bytes and separate byte checks are not retained in these findings.',
-                    ...limitations,
-                ].slice(0, 8),
+                completeness: limitations.every((item) => retainedLimitations.includes(item)) ? completeness : 'partial',
+                limitations: retainedLimitations,
                 reference: sourceReference,
             });
         }

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

@@ -1,7 +1,11 @@
 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";
+import { parseBoundedJsonObject } from "../analysis/bounded-json.mjs";
+import { MAX_INVESTIGATION_PORTABLE_BYTES } from "../contracts/investigation-portability.mjs";
+import { array, boolean, domain, enumeration, exact, fail, iso, sameValues, strings, text as structureText, validateIntegrity } from "../evidence/artifact-structure.mjs";
 export { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION };
+export { MAX_INVESTIGATION_PORTABLE_BYTES as MAX_ACQUISITION_DECISION_PACKET_BYTES };
 export const ACQUISITION_DECISIONS = [
     'unresolved',
     'continue_manual_review',
@@ -18,6 +22,80 @@ export const ACQUISITION_MANUAL_CHECKS = [
 const DECISION_SET = new Set(ACQUISITION_DECISIONS);
 const CHECK_SET = new Set(ACQUISITION_MANUAL_CHECKS);
 const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;
+function validateAcquisitionItem(value, label) {
+    const item = exact(value, ['id', 'label', 'state', 'detail', 'provenance'], label);
+    const id = enumeration(item.id, ['availability', 'contacts', 'lifecycle', 'mail', 'nameservers', 'operations', 'policy_eligibility', 'policy_lifecycle', 'policy_transfer', 'tls', 'transfer', 'web'], label);
+    enumeration(item.state, ['authoritative', 'observed', 'review', 'unavailable'], label);
+    structureText(item.label, label, 200);
+    structureText(item.detail, label, 2_000);
+    structureText(item.provenance, label, 300);
+    return id;
+}
+export function validateAcquisitionDecisionPacketStructure(value) {
+    const root = exact(value, ['schema', 'version', 'generatedAt', 'target', 'synthetic', 'evidenceObservedAt', 'analystReview', 'evidenceReview', 'limitations', 'integrity'], 'Acquisition decision packet');
+    if (root.schema !== ACQUISITION_DECISION_PACKET_SCHEMA)
+        fail('Acquisition decision packet schema');
+    iso(root.generatedAt, 'Acquisition decision packet generatedAt');
+    domain(root.target, 'Acquisition decision packet target');
+    boolean(root.synthetic, 'Acquisition decision packet synthetic');
+    iso(root.evidenceObservedAt, 'Acquisition decision packet evidenceObservedAt', true);
+    const review = exact(root.analystReview, ['decision', 'rationale', 'reviewedChecks', 'outstandingChecks', 'state'], 'Acquisition analyst review');
+    const decision = enumeration(review.decision, ACQUISITION_DECISIONS, 'Acquisition analyst review decision');
+    structureText(review.rationale, 'Acquisition analyst review rationale', 2_000, true);
+    const reviewed = strings(review.reviewedChecks, 'Acquisition reviewed checks', ACQUISITION_MANUAL_CHECKS.length, 40);
+    const outstanding = strings(review.outstandingChecks, 'Acquisition outstanding checks', ACQUISITION_MANUAL_CHECKS.length, 40);
+    const expectedReviewed = ACQUISITION_MANUAL_CHECKS.filter((item) => reviewed.includes(item));
+    const expectedOutstanding = ACQUISITION_MANUAL_CHECKS.filter((item) => !reviewed.includes(item));
+    if (!sameValues(reviewed, expectedReviewed) || !sameValues(outstanding, expectedOutstanding))
+        fail('Acquisition analyst review checks');
+    const expectedState = decision === 'unresolved' || reviewed.length < ACQUISITION_MANUAL_CHECKS.length ? 'draft' : 'reviewed';
+    if (review.state !== expectedState)
+        fail('Acquisition analyst review state');
+    const evidence = exact(root.evidenceReview, ['version', 'label', 'state', 'items', 'transitionDependencies', 'policyChecks', 'nextSteps', 'limitations'], 'Acquisition evidence review');
+    if (evidence.version !== 2)
+        fail('Acquisition evidence review');
+    structureText(evidence.label, 'Acquisition evidence review label', 200);
+    enumeration(evidence.state, ['incomplete', 'registered', 'review_transition', 'sale_signal', 'unregistered_observation'], 'Acquisition evidence review state');
+    const expectedEvidenceIds = {
+        items: ['availability', 'lifecycle', 'transfer', 'operations', 'contacts'],
+        transitionDependencies: ['nameservers', 'web', 'mail', 'tls'],
+        policyChecks: ['policy_eligibility', 'policy_lifecycle', 'policy_transfer'],
+    };
+    for (const key of ['items', 'transitionDependencies', 'policyChecks']) {
+        const expected = expectedEvidenceIds[key];
+        const values = array(evidence[key], `Acquisition evidence review ${key}`, expected.length, expected.length);
+        const ids = values.map((item, index) => validateAcquisitionItem(item, `Acquisition evidence review ${key}[${index}]`));
+        if (!sameValues(ids, expected))
+            fail(`Acquisition evidence review ${key}`);
+    }
+    strings(evidence.nextSteps, 'Acquisition next steps', 6, 600);
+    strings(evidence.limitations, 'Acquisition evidence limitations', 12, 600);
+    strings(root.limitations, 'Acquisition limitations', 8, 600);
+    validateIntegrity(root.integrity, 'Acquisition integrity', root.version, ACQUISITION_DECISION_PACKET_VERSION);
+}
+function freezePacket(value) {
+    if (value && typeof value === 'object') {
+        for (const item of Object.values(value))
+            freezePacket(item);
+        Object.freeze(value);
+    }
+}
+/** Validate the existing supported format and full canonical digest before preview. */
+export async function readAcquisitionDecisionPacket(raw, expected) {
+    const value = parseBoundedJsonObject(raw, { label: 'Acquisition decision packet', maximumBytes: MAX_INVESTIGATION_PORTABLE_BYTES });
+    if (value.schema !== ACQUISITION_DECISION_PACKET_SCHEMA)
+        fail('Acquisition decision packet schema');
+    validateAcquisitionDecisionPacketStructure(value);
+    const { integrity, ...unsigned } = value;
+    if (await sha256ArtifactDigestV2(unsigned) !== integrity.digestSha256) {
+        throw new TypeError('The acquisition decision packet failed its integrity check.');
+    }
+    if (value.target !== target(expected.target) || value.synthetic !== expected.synthetic) {
+        throw new TypeError('This packet belongs to a different target or demonstration context. The current review is unchanged.');
+    }
+    freezePacket(value);
+    return value;
+}
 function text(value, maximum) {
     return typeof value === 'string'
         ? value.replace(CONTROL_CHARACTERS, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)

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, DOMAIN_HISTORY_LEGACY_INPUT_VERSION } 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 || input.version === DOMAIN_HISTORY_LEGACY_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, input.version);
+    }
+    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 });
+}