@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/packages/interchange/external-findings-import.mjs

@@ -1,9 +1,12 @@
 import { normalizeDomain, openOrCreateCase, updateCase, } from "../cases/case-model.mjs";
 import { canonicalRegistrableDomain } from "../../lib/registrable-domain.mjs";
 import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
-import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_IMPORT_BYTES, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, } from "../contracts/external-observation-interchange.mjs";
+import { canonicalArtifactJsonV2 } from "../evidence/artifact-integrity.mjs";
+import { sha256IdentityHex } from "../evidence/record-identity.mjs";
+import { MAX_RESPONSE_LABEL_LENGTH, MAX_RESPONSE_VALUE_LENGTH, MAX_RESPONSE_LIMITATION_LENGTH, normalizeCaseEvidencePins, normalizeCaseSightings, } from "../cases/case-response-model.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_IMPORT_BYTES, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, } from "../contracts/external-observation-interchange.mjs";
 import { hasUnsafeRetainedText } from "./retained-text.mjs";
-export { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_IMPORT_BYTES, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, };
+export { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, MAX_EXTERNAL_FINDING_DOMAINS, MAX_EXTERNAL_FINDING_LIMITATIONS, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_IMPORT_BYTES, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, };
 export const EXTERNAL_FINDING_CATEGORIES = [
     'certificate',
     'dns',
@@ -14,6 +17,7 @@ export const EXTERNAL_FINDING_CATEGORIES = [
     'registration',
     'reputation',
 ];
+export const MAX_EXTERNAL_FINDING_SUMMARY_LENGTH = 900;
 const CATEGORIES = new Set(EXTERNAL_FINDING_CATEGORIES);
 const COMPLETENESS = new Set(['complete', 'inconclusive', 'partial', 'unknown']);
 const ROOT_KEYS = new Set(['schema', 'schemaVersion', 'source', 'findings']);
@@ -82,14 +86,31 @@ function iso(value, label, optional = false) {
 function limitations(value, index) {
     if (value === undefined)
         return [];
-    if (!Array.isArray(value) || value.length > 8) {
-        throw new Error(`Finding ${index + 1} limitations must be an array with no more than 8 entries.`);
+    if (!Array.isArray(value) || value.length > MAX_EXTERNAL_FINDING_LIMITATIONS) {
+        throw new Error(`Finding ${index + 1} limitations must be an array with no more than ${MAX_EXTERNAL_FINDING_LIMITATIONS} entries.`);
     }
     const unique = new Set();
     for (const item of value)
-        unique.add(requiredText(item, 240, `Finding ${index + 1} limitation`));
+        unique.add(requiredText(item, MAX_EXTERNAL_FINDING_LIMITATION_LENGTH, `Finding ${index + 1} limitation`));
     return [...unique];
 }
+/** Keep provenance and omissions visible within the existing import bound. */
+export function retainExternalFindingLimitations(supplied, mandatory) {
+    const required = limitations(mandatory, 0);
+    const optional = limitations(supplied, 0).filter((entry) => !required.includes(entry));
+    const available = MAX_EXTERNAL_FINDING_LIMITATIONS - required.length;
+    if (optional.length <= available)
+        return Object.freeze([...required, ...optional]);
+    if (available < 1)
+        throw new TypeError('Mandatory finding limitations leave no room to disclose omitted supplied limitations.');
+    const retained = optional.slice(0, available - 1);
+    const omitted = optional.length - retained.length;
+    return Object.freeze([
+        ...required,
+        ...retained,
+        `${omitted} supplied limitation${omitted === 1 ? ' was' : 's were'} omitted to retain mandatory provenance and omission notices; review the supplied input for the remaining qualifications.`,
+    ]);
+}
 function structuredObservation(value, index) {
     if (value === undefined || value === null)
         return null;
@@ -219,7 +240,7 @@ export function parseExternalFindingsDocument(value) {
             domain,
             category: item.category,
             evidenceClass,
-            summary: requiredText(item.summary, 900, `Finding ${index + 1} summary`),
+            summary: requiredText(item.summary, MAX_EXTERNAL_FINDING_SUMMARY_LENGTH, `Finding ${index + 1} summary`),
             observedAt: iso(item.observedAt, `Finding ${index + 1} observation time`),
             completeness: item.completeness,
             limitations: limitations(item.limitations, index),
@@ -266,21 +287,19 @@ function importedSourceLabel(finding, sourceName) {
         ? `Deployment observation: ${sourceName}`
         : `Provider report: ${sourceName}`;
 }
-function existingPinKey(recordValue, finding, sourceName) {
-    const expectedLabel = `External ${finding.category} finding`;
-    const expectedValue = finding.structuredObservation?.value ?? pinValue(finding);
-    const expectedSource = importedSourceLabel(finding, sourceName);
-    const observation = finding.structuredObservation;
-    return recordValue.evidencePins.some((pin) => (pin.label === expectedLabel
-        && pin.value === expectedValue
-        && pin.source === expectedSource
-        && pin.observedAt === finding.observedAt
-        && pin.completeness === finding.completeness
-        && (!observation || (pin.field === observation.field
-            && pin.sourceSchema?.collection === 'external_observations'
-            && pin.sourceSchema.schema === observation.sourceSchema
-            && pin.sourceSchema.version === observation.sourceVersion
-            && (observation.eventId === null || pin.certificateObservation?.eventId === observation.eventId))))) ? findingKey(finding, sourceName) : '';
+function alreadyRetained(recordValue, projection) {
+    const { importContentSha256: expectedIdentity, ...expected } = projection.evidencePin;
+    return recordValue.evidencePins.some((pin) => {
+        const { id: _id, createdAt: _createdAt, importContentSha256, ...material } = pin;
+        if (importContentSha256 && importContentSha256 !== expectedIdentity)
+            return false;
+        // Older pins have no content digest. Only a complete, exact retained
+        // projection can establish duplication; a shortened prefix cannot.
+        if (!importContentSha256 && (projection.shortenedFields.length || projection.omittedLimitations))
+            return false;
+        // An imported digest alone cannot substitute for matching retained fields.
+        return canonicalArtifactJsonV2(material) === canonicalArtifactJsonV2(expected);
+    });
 }
 function structuredPinFields(finding) {
     const observation = finding.structuredObservation;
@@ -312,37 +331,41 @@ function structuredPinFields(finding) {
         certificateObservation,
     };
 }
-function mergeExternalFindingIntoCase(current, caseId, finding, source, now) {
-    const target = current.find((candidate) => candidate.id === caseId) ?? null;
-    if (!target)
-        throw new Error('The selected Case is unavailable for this finding.');
-    if (existingPinKey(target, finding, source.name)) {
-        return { cases: [...current], record: target, added: false };
-    }
-    const sourceLimitations = [
+/** Exact material retained by both the import preview and Case mutation. */
+export function externalFindingCaseProjection(finding, source) {
+    const identitySha256 = sha256IdentityHex(new TextEncoder().encode(canonicalArtifactJsonV2({
+        sourceName: source.name, sourceReference: source.reference, finding,
+    })));
+    const value = finding.structuredObservation?.value ?? pinValue(finding);
+    const sourceLabel = importedSourceLabel(finding, source.name);
+    const sourceReference = source.reference ? `Source reference: ${source.reference}` : null;
+    const shortenedFields = [
+        ...(value.length > MAX_RESPONSE_VALUE_LENGTH ? ['finding value'] : []),
+        ...(sourceLabel.length > MAX_RESPONSE_LABEL_LENGTH ? ['source label'] : []),
+        ...(sourceReference && sourceReference.length > MAX_RESPONSE_LIMITATION_LENGTH ? ['source reference'] : []),
+    ];
+    const mandatory = [
         finding.evidenceClass === 'deployment_observation'
             ? `Imported as an observation made by ${source.name}; this browser session did not collect or independently verify it.`
             : `Reported by ${source.name}; WHOISleuth did not collect or independently verify this provider finding.`,
-        ...(source.reference ? [`Source reference: ${source.reference}`] : []),
-        ...finding.limitations,
+        ...(sourceReference ? [sourceReference.length > MAX_RESPONSE_LIMITATION_LENGTH
+                ? `${sourceReference.slice(0, MAX_RESPONSE_LIMITATION_LENGTH - 13)}… [shortened]` : sourceReference] : []),
+        ...(shortenedFields.length ? [`Case storage shortened ${shortenedFields.join(', ')}. The content digest covers the complete accepted finding.`] : []),
     ];
-    const existingPinIds = new Set(target.evidencePins.map((pin) => pin.id));
-    let updated = updateCase([...current], target.id, {
-        evidencePin: {
+    const sourceLimitations = retainExternalFindingLimitations(finding.limitations, mandatory);
+    const omittedLimitations = finding.limitations.filter((item) => !sourceLimitations.includes(item)).length;
+    const pin = normalizeCaseEvidencePins([{
             ...structuredPinFields(finding),
+            importContentSha256: identitySha256,
             label: `External ${finding.category} finding`,
-            value: finding.structuredObservation?.value ?? pinValue(finding),
-            source: importedSourceLabel(finding, source.name),
+            value,
+            source: sourceLabel,
             observedAt: finding.observedAt,
             completeness: finding.completeness,
+            truncated: shortenedFields.length || omittedLimitations ? true : null,
             limitations: sourceLimitations,
-        },
-    }, now);
-    const addedPin = updated.record.evidencePins.find((pin) => !existingPinIds.has(pin.id)) ?? null;
-    if (!addedPin)
-        throw new Error('The imported finding could not be retained as Case evidence.');
-    updated = updateCase(updated.cases, target.id, {
-        sighting: {
+        }], finding.observedAt)[0];
+    const observed = normalizeCaseSightings([{
             state: finding.evidenceClass === 'deployment_observation'
                 ? 'observed_by_deployment'
                 : 'reported_by_provider',
@@ -358,9 +381,28 @@ function mergeExternalFindingIntoCase(current, caseId, finding, source, now) {
             source: source.name,
             observedAt: finding.observedAt,
             completeness: finding.completeness,
-            evidencePinId: addedPin.id,
             limitations: sourceLimitations,
-        },
+        }], finding.observedAt)[0];
+    if (!pin || !observed)
+        throw new TypeError('The finding has no valid retained Case projection.');
+    const { id: _pinId, createdAt: _pinCreatedAt, ...evidencePin } = pin;
+    const { id: _sightingId, createdAt: _sightingCreatedAt, evidencePinId: _pinReference, ...sighting } = observed;
+    return { evidencePin, sighting, identitySha256, shortenedFields, omittedLimitations };
+}
+function mergeExternalFindingIntoCase(current, caseId, finding, source, now) {
+    const target = current.find((candidate) => candidate.id === caseId) ?? null;
+    if (!target)
+        throw new Error('The selected Case is unavailable for this finding.');
+    const projection = externalFindingCaseProjection(finding, source);
+    if (alreadyRetained(target, projection))
+        return { cases: [...current], record: target, added: false };
+    const existingPinIds = new Set(target.evidencePins.map((pin) => pin.id));
+    let updated = updateCase([...current], target.id, { evidencePin: projection.evidencePin }, now);
+    const addedPin = updated.record.evidencePins.find((pin) => !existingPinIds.has(pin.id)) ?? null;
+    if (!addedPin)
+        throw new Error('The imported finding could not be retained as Case evidence.');
+    updated = updateCase(updated.cases, target.id, {
+        sighting: { ...projection.sighting, evidencePinId: addedPin.id },
     }, now);
     return { cases: updated.cases, record: updated.record, added: true };
 }
@@ -371,7 +413,6 @@ export function mergeExternalFindingsIntoCases(current, document, now = new Date
     let findingsAdded = 0;
     let duplicatesSkipped = 0;
     for (const finding of document.findings) {
-        const existing = cases.find((candidate) => candidate.domain === finding.domain) ?? null;
         const opened = openOrCreateCase(cases, { domain: finding.domain, source: 'import' }, now);
         cases = opened.cases;
         const target = cases.find((candidate) => candidate.id === opened.record.id) ?? opened.record;
@@ -382,10 +423,10 @@ export function mergeExternalFindingsIntoCases(current, document, now = new Date
             continue;
         }
         findingsAdded += 1;
-        if (existing)
-            updatedDomains.add(finding.domain);
-        else
+        if (opened.created)
             createdDomains.add(finding.domain);
+        else
+            updatedDomains.add(finding.domain);
     }
     return {
         cases,
@@ -399,7 +440,7 @@ function targetedFinding(finding, caseDomain) {
     if (finding.domain === caseDomain)
         return finding;
     const prefix = `Captured hostname ${finding.domain}. `;
-    const maximumSummaryLength = 900;
+    const maximumSummaryLength = MAX_EXTERNAL_FINDING_SUMMARY_LENGTH;
     const remaining = maximumSummaryLength - prefix.length;
     const summary = remaining > 1 && finding.summary.length > remaining
         ? `${prefix}${finding.summary.slice(0, remaining - 1).trimEnd()}…`
@@ -421,7 +462,7 @@ export function externalFindingsCaseTargets(document, caseDomain) {
 }
 /**
  * Merges already-validated external findings into one selected Case. A Case is
- * keyed to its registrable domain, while rendered captures may retain an exact
+ * identified by its immutable ID with a registrable-domain pivot, while rendered captures may retain an exact
  * hostname. Only same-domain findings are accepted, the exact hostname remains
  * explicit in the retained evidence, and this operation can never open another
  * Case as a side effect.

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

@@ -0,0 +1,382 @@
+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 { normalizeExplicitIsoTimestamp } from "../evidence/observation.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([
+    '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.`);
+        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),
+            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
+        || root.schemaVersion !== WEB_CAPTURE_MANIFEST_VERSION) {
+        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`);
+        contexts.push({ domain, observedAt, completeness: String(completeness), conditions, observerLabel, vantageLabel });
+        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),
+            ...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);
+        for (const summary of summaries) {
+            findings.push({
+                domain,
+                category: 'page',
+                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),
+                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/bulk-mail-exposure.mjs

@@ -178,7 +178,8 @@ export function buildBulkMailExposureReport(rowsRaw, options = {}) {
             ...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),

package/packages/investigation/investigation-bagit.mjs

@@ -0,0 +1,14 @@
+import { prepareBagItEntries, encodeBagItEntries } from "../interchange/bagit.mjs";
+import { prepareInvestigationPackageEntries, INVESTIGATION_PACKAGE_MANIFEST_PATH } from "./investigation-package.mjs";
+/** The existing manifest keeps source declarations; BagIt preserves the bytes. */
+export async function prepareInvestigationBagIt(input, generatedAt, version) {
+    const prepared = await prepareInvestigationPackageEntries(input, generatedAt, version);
+    const payload = new Map([...prepared.files].filter(([path]) => path !== INVESTIGATION_PACKAGE_MANIFEST_PATH)
+        .map(([path, bytes]) => [`data/${path.slice('artifacts/'.length)}`, bytes]));
+    const tags = new Map([['whoisleuth-manifest.json', prepared.files.get(INVESTIGATION_PACKAGE_MANIFEST_PATH)]]);
+    return { manifest: prepared.manifest, files: await prepareBagItEntries(payload, tags) };
+}
+export async function buildInvestigationBagIt(input, generatedAt, version) {
+    const prepared = await prepareInvestigationBagIt(input, generatedAt, version);
+    return { manifest: prepared.manifest, bytes: encodeBagItEntries(prepared.files) };
+}