@slicedearth/whoisleuth-cli 2.3.0 → 2.4.0

package/packages/investigation/investigation-capsule.mjs

@@ -1,7 +1,8 @@
+import { LOOKUP_EVIDENCE_SCHEMA } from "../contracts/lookup-evidence.mjs";
 import { canonicalArtifactJsonV2, sha256ArtifactDigestV2, SORTED_JSON_V2, } from "../evidence/artifact-integrity.mjs";
 import { LOOKUP_ASSET_GRAPH_SCHEMA, } from "./lookup-asset-graph.mjs";
 import { LOOKUP_INVESTIGATION_BRIEF_SCHEMA, LOOKUP_INVESTIGATION_BRIEF_VERSION, } from "./lookup-investigation-brief.mjs";
-import { INVESTIGATION_CAPSULE_ANALYST_RECORDS_SCHEMA, INVESTIGATION_CAPSULE_ANALYST_RECORDS_VERSION, INVESTIGATION_CAPSULE_SCHEMA, INVESTIGATION_CAPSULE_VERSION, PUBLIC_INVESTIGATION_CAPSULE_VERSION, SUPPORTED_INVESTIGATION_CAPSULE_VERSIONS, } from "../contracts/investigation-portability.mjs";
+import { INVESTIGATION_CAPSULE_ANALYST_RECORDS_SCHEMA, INVESTIGATION_CAPSULE_ANALYST_RECORDS_VERSION, INVESTIGATION_CAPSULE_SCHEMA, INVESTIGATION_CAPSULE_VERSION, PUBLIC_INVESTIGATION_CAPSULE_VERSION, SUPPORTED_INVESTIGATION_CAPSULE_VERSIONS, investigationCapsuleContracts, } from "../contracts/investigation-portability.mjs";
 export { INVESTIGATION_CAPSULE_ANALYST_RECORDS_SCHEMA, INVESTIGATION_CAPSULE_ANALYST_RECORDS_VERSION, INVESTIGATION_CAPSULE_SCHEMA, INVESTIGATION_CAPSULE_VERSION, PUBLIC_INVESTIGATION_CAPSULE_VERSION, SUPPORTED_INVESTIGATION_CAPSULE_VERSIONS, };
 function safeVersion(value) {
     return typeof value === 'string' && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(value)
@@ -45,7 +46,21 @@ function analystProjection(record) {
         })),
     };
 }
+/** Links admitted projections; this does not authenticate their observations. */
+export function investigationCapsuleProjectionsMatch(target, brief, graph) {
+    const targets = graph.nodes.filter((node) => node.kind === 'target');
+    return target.value === brief.target && target.type === brief.targetType
+        && targets.length === 1 && targets[0]?.id === graph.targetId
+        && targets[0]?.label === target.value
+        && brief.relationships.nodes === graph.nodes.length
+        && brief.relationships.edges === graph.edges.length
+        && brief.relationships.truncated === graph.truncated;
+}
 export async function buildInvestigationCapsule(input) {
+    const target = { value: input.brief.target, type: input.brief.targetType };
+    if (!investigationCapsuleProjectionsMatch(target, input.brief, input.graph)) {
+        throw new TypeError('The investigation brief and graph must describe the same target and retained relationships.');
+    }
     const analystRecords = input.includeAnalystRecords ? analystProjection(input.caseRecord) : null;
     const [evidenceDigest, briefDigest, graphDigest, analystRecordsDigest] = await Promise.all([
         sha256ArtifactDigestV2(input.lookupEvidence),
@@ -60,7 +75,7 @@ export async function buildInvestigationCapsule(input) {
         schemaVersion: INVESTIGATION_CAPSULE_VERSION,
         generatedAt: iso(input.generatedAt),
         application: { name: 'WHOISleuth', version: safeVersion(input.applicationVersion) },
-        target: { value: input.brief.target, type: input.brief.targetType },
+        target,
         sourceContracts: [
             { id: 'lookup-evidence', schema: evidenceSchema, version: evidenceVersion, digest: evidenceDigest, embedded: false },
             { id: 'investigation-brief', schema: LOOKUP_INVESTIGATION_BRIEF_SCHEMA, version: LOOKUP_INVESTIGATION_BRIEF_VERSION, digest: briefDigest, embedded: true },
@@ -100,11 +115,24 @@ export async function buildInvestigationCapsule(input) {
         },
     };
 }
+/** Cross-file linkage after the caller has bounded and hashed the source file.
+ * This is neither a source-format validator nor an authenticity decision. */
+export function investigationCapsuleSourceIdentity(target, reference, source) {
+    const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    const expected = object(reference);
+    const capsuleTarget = object(target);
+    const sourceQuery = object(source.query);
+    const validReference = expected?.id === 'lookup-evidence' && expected.embedded === false;
+    const schema = validReference && expected.schema === LOOKUP_EVIDENCE_SCHEMA && expected.schema === source.schema;
+    const version = validReference && Number.isSafeInteger(expected.version) && expected.version === source.version;
+    const targetMatches = typeof capsuleTarget?.value === 'string' && capsuleTarget.value.length > 0
+        && capsuleTarget.value === sourceQuery?.submitted && capsuleTarget.type === sourceQuery.type;
+    const contentDigest = validReference && typeof source.digest === 'string' && /^sha256:[a-f0-9]{64}$/u.test(source.digest) && expected.digest === source.digest;
+    return Object.freeze({ schema, version, target: targetMatches, contentDigest, linked: schema && version && targetMatches && contentDigest });
+}
 export async function verifyInvestigationCapsule(capsule) {
-    const current = capsule.schemaVersion === INVESTIGATION_CAPSULE_VERSION;
-    const publicVersion = capsule.schemaVersion === PUBLIC_INVESTIGATION_CAPSULE_VERSION;
     const integrityRecord = capsule.integrity;
-    if ((!current && !publicVersion)
+    if (!investigationCapsuleContracts(capsule.schemaVersion)
         || integrityRecord.canonicalization !== SORTED_JSON_V2
         || integrityRecord.scope !== 'capsule excluding integrity') {
         return { valid: false, brief: false, graph: false, analystRecords: null, whole: false };

package/packages/investigation/investigation-manifest.mjs

@@ -0,0 +1,200 @@
+import { boundedJsonLimitsForBytes, parseBoundedJson, parseBoundedJsonObject } from "../../lib/bounded-json.mjs";
+import { normalizeBoundedSemanticVersion } from "../../lib/semantic-version.mjs";
+import { canonicalArtifactJsonV2, sha256ArtifactBytes, sha256ArtifactDigestV2, SORTED_JSON_V2 } from "../evidence/artifact-integrity.mjs";
+import { array, digest, enumeration, exact, fail, integer, iso, strings, text, validateIntegrity } from "../evidence/artifact-structure.mjs";
+import { SELECTED_FILE_MEDIA_TYPES as INVESTIGATION_FILE_MEDIA_TYPES } from "../contracts/selected-file-limits.mjs";
+import { MAX_INVESTIGATION_MANIFEST_ARTIFACTS, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES } from "../contracts/investigation-package-limits.mjs";
+export { MAX_INVESTIGATION_MANIFEST_ARTIFACTS, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, INVESTIGATION_FILE_MEDIA_TYPES };
+export const INVESTIGATION_MANIFEST_SCHEMA = 'whoisleuth.investigation-manifest';
+export const INVESTIGATION_MANIFEST_VERSION = 3;
+export const SUPPORTED_INVESTIGATION_MANIFEST_VERSIONS = [2, INVESTIGATION_MANIFEST_VERSION];
+// Independently bounds the path-free metadata, not the selected file content.
+import { MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES } from "../contracts/investigation-package-limits.mjs";
+export { MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES } from "../contracts/investigation-package-limits.mjs";
+/** A filename suggests a declaration only; it never validates file contents. */
+export function investigationFileMediaType(name) {
+    const extension = name.toLowerCase().split('.').at(-1);
+    switch (extension) {
+        case 'json': return 'application/json';
+        case 'png': return 'image/png';
+        case 'jpg':
+        case 'jpeg': return 'image/jpeg';
+        case 'webp': return 'image/webp';
+        case 'gif': return 'image/gif';
+        case 'pdf': return 'application/pdf';
+        default: return 'application/octet-stream';
+    }
+}
+function sourceDeclaration(source) {
+    const identity = source?.identity ?? null;
+    const observedAt = source?.observedAt ?? null;
+    if (identity !== null)
+        text(identity, 'Artefact source identity', 240);
+    iso(observedAt, 'Artefact source observation time', true);
+    return Object.freeze({ identity, observedAt });
+}
+export function investigationJsonMetadata(content, maximumBytes = MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES) {
+    const value = parseBoundedJson(content, {
+        label: 'Manifest artefact', maximumBytes,
+        limits: boundedJsonLimitsForBytes(maximumBytes),
+    });
+    const object = value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    let schema = null;
+    // Arbitrary valid JSON remains packageable. An unusable schema declaration
+    // is not copied into metadata; the exact source bytes still retain it.
+    if (typeof object?.schema === 'string') {
+        try {
+            schema = text(object.schema, 'Artefact schema', 160);
+        }
+        catch { /* Unknown marker; not source-format admission. */ }
+    }
+    const candidate = object?.version ?? object?.schemaVersion;
+    const version = Number.isSafeInteger(candidate) && Number(candidate) > 0 && Number(candidate) <= 1_000 ? Number(candidate) : null;
+    return { value, object, schema, version };
+}
+export async function prepareInvestigationManifest(input, generatedAt, applicationVersionValue) {
+    if (!Array.isArray(input.artifacts) || input.artifacts.length < 1 || input.artifacts.length > MAX_INVESTIGATION_MANIFEST_ARTIFACTS) {
+        throw new TypeError(`A manifest requires between 1 and ${MAX_INVESTIGATION_MANIFEST_ARTIFACTS} artefacts.`);
+    }
+    iso(generatedAt, 'Manifest generatedAt');
+    const workflow = text(input.workflow, 'Manifest workflow', 160);
+    const applicationVersion = normalizeBoundedSemanticVersion(applicationVersionValue, 'Application');
+    const configurationDigestSha256 = input.configurationDigestSha256;
+    if (configurationDigestSha256 !== null)
+        digest(configurationDigestSha256, 'configurationDigestSha256');
+    let totalBytes = 0;
+    // Capture all mutable bytes and declarations before the first asynchronous
+    // digest. The package writer uses these same owned bytes, not the caller's view.
+    const selected = input.artifacts.map((artifact, index) => {
+        if (typeof artifact.content !== 'string' && !(artifact.content instanceof Uint8Array))
+            throw new TypeError(`Artefact ${index + 1} requires text or bytes.`);
+        if (artifact.content.length > MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES || artifact.content.length > MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES - totalBytes) {
+            throw new TypeError('Manifest artefacts exceed the per-file or combined limit.');
+        }
+        const bytes = typeof artifact.content === 'string' ? new TextEncoder().encode(artifact.content) : new Uint8Array(artifact.content);
+        if (bytes.byteLength < 1 || bytes.byteLength > MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES)
+            throw new TypeError(`Artefact ${index + 1} must be between 1 byte and ${MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES} bytes.`);
+        if (bytes.byteLength > MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES - totalBytes)
+            throw new TypeError('Manifest artefacts exceed the combined limit.');
+        totalBytes += bytes.byteLength;
+        const mediaType = enumeration(artifact.mediaType ?? (typeof artifact.content === 'string' ? 'application/json' : 'application/octet-stream'), INVESTIGATION_FILE_MEDIA_TYPES, 'Artefact media type');
+        return { bytes, mediaType, source: sourceDeclaration(artifact.source) };
+    });
+    const artifacts = [];
+    for (const [index, file] of selected.entries()) {
+        const metadata = file.mediaType === 'application/json'
+            ? investigationJsonMetadata(new TextDecoder('utf-8', { fatal: true }).decode(file.bytes)) : null;
+        artifacts.push(Object.freeze({
+            sequence: index + 1, id: `artifact-${index + 1}`,
+            schema: metadata?.schema ?? null, version: metadata?.version ?? null,
+            byteLength: file.bytes.byteLength,
+            contentDigestSha256: await sha256ArtifactBytes(file.bytes),
+            canonicalDigestSha256: metadata ? await sha256ArtifactDigestV2(metadata.value) : null,
+            mediaType: file.mediaType, source: file.source,
+        }));
+    }
+    const unsigned = Object.freeze({
+        schema: INVESTIGATION_MANIFEST_SCHEMA, version: INVESTIGATION_MANIFEST_VERSION,
+        generatedAt, application: Object.freeze({ name: 'WHOISleuth', version: applicationVersion }),
+        workflow, audience: 'private',
+        configuration: Object.freeze({ digestSha256: configurationDigestSha256 }),
+        artifacts: Object.freeze(artifacts),
+        steps: Object.freeze(artifacts.map((artifact) => Object.freeze({
+            sequence: artifact.sequence, artifactId: artifact.id, contentDigestSha256: artifact.contentDigestSha256,
+            action: 'packaged', occurredAt: generatedAt,
+        }))),
+        summary: Object.freeze({ artifactCount: artifacts.length, totalBytes }),
+        limitations: Object.freeze([
+            'Selected file bytes are unchanged and are not automatically redacted. Review their contents before sharing; original filenames and paths are not retained.',
+            'Source identities, observation times and media types are declarations, not independently authenticated evidence. Missing source times remain unknown.',
+            'Packaging events use the local clock. They do not establish earlier custody, a trusted timestamp, a signature, source accuracy or current validity.',
+            'Digests establish content identity. JSON parsing and declared schema metadata do not establish that a source format is supported or its claims are true.',
+        ]),
+    });
+    const manifest = Object.freeze({ ...unsigned, integrity: Object.freeze({
+            algorithm: 'SHA-256', canonicalization: SORTED_JSON_V2,
+            digestSha256: await sha256ArtifactDigestV2(unsigned),
+        }) });
+    if (new TextEncoder().encode(canonicalArtifactJsonV2(manifest)).byteLength > MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES)
+        throw new TypeError('Investigation manifest metadata exceeds its byte limit.');
+    return Object.freeze({ manifest, contents: Object.freeze(selected.map((file) => file.bytes)) });
+}
+export async function buildInvestigationManifest(input, generatedAt, applicationVersion) {
+    return (await prepareInvestigationManifest(input, generatedAt, applicationVersion)).manifest;
+}
+export function validateInvestigationManifest(value) {
+    const version = integer(value.version, 'Investigation manifest version', 2, INVESTIGATION_MANIFEST_VERSION);
+    const current = version === INVESTIGATION_MANIFEST_VERSION;
+    const root = exact(value, ['schema', 'version', 'generatedAt', 'application', 'workflow', 'configuration', 'artifacts', 'steps', 'summary', 'limitations', 'integrity', ...(current ? ['audience'] : [])], 'Investigation manifest');
+    if (root.schema !== INVESTIGATION_MANIFEST_SCHEMA)
+        fail('Investigation manifest schema');
+    iso(root.generatedAt, 'Investigation manifest generatedAt');
+    const application = exact(root.application, ['name', 'version'], 'Investigation manifest application');
+    if (application.name !== (current ? 'WHOISleuth' : 'WHOISleuth CLI'))
+        fail('Investigation manifest application');
+    normalizeBoundedSemanticVersion(application.version, 'Application');
+    text(root.workflow, 'Investigation manifest workflow', 160);
+    if (current && root.audience !== 'private')
+        fail('Investigation manifest audience');
+    const configuration = exact(root.configuration, ['digestSha256'], 'Investigation manifest configuration');
+    if (configuration.digestSha256 !== null)
+        digest(configuration.digestSha256, 'Investigation manifest configuration');
+    const maximumFiles = current ? MAX_INVESTIGATION_MANIFEST_ARTIFACTS : 16;
+    const maximumFileBytes = current ? MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES : 16 * 1024 * 1024;
+    const maximumTotalBytes = current ? MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES : 32 * 1024 * 1024;
+    const artifacts = array(root.artifacts, 'Investigation manifest artifacts', maximumFiles, 1);
+    const steps = array(root.steps, 'Investigation manifest steps', maximumFiles, 1);
+    if (steps.length !== artifacts.length)
+        fail('Investigation manifest step count');
+    let totalBytes = 0;
+    for (const [index, candidate] of artifacts.entries()) {
+        const item = exact(candidate, ['sequence', 'id', 'schema', 'version', 'byteLength', 'contentDigestSha256', 'canonicalDigestSha256', ...(current ? ['mediaType', 'source'] : [])], `Investigation manifest artifact ${index + 1}`);
+        if (integer(item.sequence, 'Investigation manifest artifact sequence', 1, artifacts.length) !== index + 1 || item.id !== `artifact-${index + 1}`)
+            fail('Investigation manifest artifact order');
+        if (item.schema !== null)
+            text(item.schema, 'Investigation manifest artifact schema', 160);
+        if (item.version !== null)
+            integer(item.version, 'Investigation manifest artifact version', 1, 1_000);
+        totalBytes += integer(item.byteLength, 'Investigation manifest artifact bytes', 1, maximumFileBytes);
+        digest(item.contentDigestSha256, 'Investigation manifest content digest');
+        const mediaType = current ? enumeration(item.mediaType, INVESTIGATION_FILE_MEDIA_TYPES, 'Artefact media type') : 'application/json';
+        if (mediaType === 'application/json')
+            digest(item.canonicalDigestSha256, 'Investigation manifest canonical digest');
+        else if (item.canonicalDigestSha256 !== null || item.schema !== null || item.version !== null)
+            fail('Opaque artefact JSON metadata');
+        if (current) {
+            const source = exact(item.source, ['identity', 'observedAt'], 'Artefact source');
+            if (source.identity !== null)
+                text(source.identity, 'Artefact source identity', 240);
+            iso(source.observedAt, 'Artefact source observation time', true);
+        }
+        const step = exact(steps[index], ['sequence', 'artifactId', 'contentDigestSha256', ...(current ? ['action', 'occurredAt'] : [])], `Investigation manifest step ${index + 1}`);
+        if (step.sequence !== item.sequence || step.artifactId !== item.id || step.contentDigestSha256 !== item.contentDigestSha256)
+            fail('Investigation manifest step linkage');
+        if (current && (step.action !== 'packaged' || step.occurredAt !== root.generatedAt))
+            fail('Investigation manifest packaging event');
+    }
+    const summary = exact(root.summary, ['artifactCount', 'totalBytes'], 'Investigation manifest summary');
+    if (integer(summary.artifactCount, 'Investigation manifest artifact count', 1, maximumFiles) !== artifacts.length
+        || integer(summary.totalBytes, 'Investigation manifest total bytes', 1, maximumTotalBytes) !== totalBytes)
+        fail('Investigation manifest summary');
+    strings(root.limitations, 'Investigation manifest limitations', 8, 600);
+    validateIntegrity(root.integrity, 'Investigation manifest integrity', root.version, version);
+}
+export async function readInvestigationManifest(raw) {
+    const value = parseBoundedJsonObject(raw, { label: 'Investigation manifest', maximumBytes: MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES });
+    validateInvestigationManifest(value);
+    const { integrity, ...unsigned } = value;
+    if (await sha256ArtifactDigestV2(unsigned) !== integrity.digestSha256)
+        throw new TypeError('Investigation manifest failed its integrity check.');
+    return value;
+}
+export function formatInvestigationManifest(manifest) {
+    const lines = ['Investigation manifest', `Workflow       ${manifest.workflow}`, `Tool version   ${manifest.application.version}`,
+        `Artifacts      ${manifest.summary.artifactCount}`, `Total bytes    ${manifest.summary.totalBytes}`,
+        `Configuration  ${manifest.configuration.digestSha256 ?? 'not supplied'}`, `Integrity      ${manifest.integrity.digestSha256}`, '', 'Ordered artefacts:'];
+    for (const artifact of manifest.artifacts)
+        lines.push(`  ${artifact.sequence}. ${artifact.schema ?? (artifact.canonicalDigestSha256 ? 'unversioned JSON' : 'opaque file')}${artifact.version ? ` v${artifact.version}` : ''} · ${artifact.contentDigestSha256}`);
+    lines.push('', 'No source file paths or artefact contents are retained in this manifest.', '');
+    return lines.join('\n');
+}

package/packages/investigation/investigation-package-crypto.mjs

@@ -0,0 +1,98 @@
+import { WORKSPACE_ARCHIVE_PBKDF2_ITERATIONS } from "../contracts/case-portability.mjs";
+import { ENCRYPTED_INVESTIGATION_PACKAGE_MAGIC, ENCRYPTED_INVESTIGATION_PACKAGE_VERSION, ENCRYPTED_INVESTIGATION_PACKAGE_HEADER_BYTES, MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES, MAX_INVESTIGATION_PACKAGE_BYTES, hasEncryptedInvestigationPackagePrefix, } from "../contracts/investigation-package-limits.mjs";
+import { arrayBuffer, assertPassphrase, cryptoProvider, deriveArchiveKey } from "../evidence/passphrase-encryption.mjs";
+import { inspectInvestigationPackage } from "./investigation-package.mjs";
+const VERSION_OFFSET = ENCRYPTED_INVESTIGATION_PACKAGE_MAGIC.length;
+const ITERATIONS_OFFSET = VERSION_OFFSET + 1;
+const SALT_OFFSET = ITERATIONS_OFFSET + 4;
+const IV_OFFSET = SALT_OFFSET + 16;
+const LENGTH_OFFSET = IV_OFFSET + 12;
+const HEADER_BYTES = ENCRYPTED_INVESTIGATION_PACKAGE_HEADER_BYTES;
+const TAG_BYTES = 16;
+function boundedSnapshot(input, maximum) {
+    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer)
+        || input.byteLength < 22 || input.byteLength > maximum)
+        throw new TypeError('Evidence package exceeds its input byte limit or uses shared memory.');
+    return new Uint8Array(input);
+}
+/** Fixed-width binary metadata. No targets, file identities or source claims are exposed. */
+export function inspectEncryptedInvestigationPackage(input) {
+    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer) || !hasEncryptedInvestigationPackagePrefix(input)
+        || input.byteLength < HEADER_BYTES + TAG_BYTES + 22 || input.byteLength > MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES) {
+        throw new TypeError('The encrypted evidence package is malformed or exceeds its byte limit.');
+    }
+    if (input[VERSION_OFFSET] !== ENCRYPTED_INVESTIGATION_PACKAGE_VERSION)
+        throw new TypeError('Unsupported encrypted evidence package version. No file was decrypted.');
+    const header = input.slice(0, HEADER_BYTES);
+    const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+    if (view.getUint32(ITERATIONS_OFFSET) !== WORKSPACE_ARCHIVE_PBKDF2_ITERATIONS)
+        throw new TypeError('Unsupported encrypted evidence package key-derivation parameters.');
+    const plaintextBytes = view.getUint32(LENGTH_OFFSET);
+    if (plaintextBytes < 22 || plaintextBytes > MAX_INVESTIGATION_PACKAGE_BYTES
+        || input.byteLength !== HEADER_BYTES + plaintextBytes + TAG_BYTES)
+        throw new TypeError('Encrypted evidence package length does not match its declaration.');
+    return Object.freeze({ version: ENCRYPTED_INVESTIGATION_PACKAGE_VERSION, plaintextBytes, ciphertextBytes: plaintextBytes + TAG_BYTES });
+}
+/** Encrypt an independently verified package, never a partly accepted archive. */
+export async function encryptInvestigationPackage(input, passphrase, provider) {
+    const plaintext = boundedSnapshot(input, MAX_INVESTIGATION_PACKAGE_BYTES);
+    let secret = null;
+    try {
+        secret = assertPassphrase(passphrase);
+        const inspected = await inspectInvestigationPackage(plaintext);
+        if (!inspected.identityVerified)
+            throw new TypeError('The evidence package contains an unverified file. Nothing was encrypted.');
+        const crypto = cryptoProvider(provider);
+        const salt = crypto.getRandomValues(new Uint8Array(16)), iv = crypto.getRandomValues(new Uint8Array(12));
+        const header = new Uint8Array(HEADER_BYTES), view = new DataView(header.buffer);
+        header.set(new TextEncoder().encode(ENCRYPTED_INVESTIGATION_PACKAGE_MAGIC));
+        header[VERSION_OFFSET] = ENCRYPTED_INVESTIGATION_PACKAGE_VERSION;
+        view.setUint32(ITERATIONS_OFFSET, WORKSPACE_ARCHIVE_PBKDF2_ITERATIONS);
+        header.set(salt, SALT_OFFSET);
+        header.set(iv, IV_OFFSET);
+        view.setUint32(LENGTH_OFFSET, plaintext.byteLength);
+        const key = await deriveArchiveKey(crypto, secret, salt, ['encrypt']);
+        const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: arrayBuffer(iv), additionalData: header, tagLength: TAG_BYTES * 8 }, key, plaintext);
+        const output = new Uint8Array(HEADER_BYTES + encrypted.byteLength);
+        output.set(header);
+        output.set(new Uint8Array(encrypted), HEADER_BYTES);
+        return output;
+    }
+    finally {
+        secret?.fill(0);
+        plaintext.fill(0);
+    }
+}
+/** Authenticate all container bytes before passing the plaintext to the ZIP reader. */
+export async function decryptInvestigationPackage(input, passphrase, provider) {
+    const snapshot = boundedSnapshot(input, MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES);
+    let secret = null;
+    let plaintext = null;
+    try {
+        const metadata = inspectEncryptedInvestigationPackage(snapshot);
+        secret = assertPassphrase(passphrase);
+        const crypto = cryptoProvider(provider);
+        try {
+            const key = await deriveArchiveKey(crypto, secret, snapshot.slice(SALT_OFFSET, IV_OFFSET), ['decrypt']);
+            plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: snapshot.slice(IV_OFFSET, LENGTH_OFFSET),
+                additionalData: snapshot.slice(0, HEADER_BYTES), tagLength: TAG_BYTES * 8 }, key, snapshot.slice(HEADER_BYTES)));
+        }
+        catch {
+            throw new Error('The package passphrase is incorrect or the encrypted file is corrupted.');
+        }
+        if (plaintext.byteLength !== metadata.plaintextBytes)
+            throw new TypeError('Decrypted evidence package length is invalid.');
+        const review = await inspectInvestigationPackage(plaintext);
+        if (!review.identityVerified)
+            throw new TypeError('The decrypted package contains an unverified file. No evidence was accepted.');
+        return { bytes: plaintext, review, ciphertextBytes: metadata.ciphertextBytes };
+    }
+    catch (cause) {
+        plaintext?.fill(0);
+        throw cause;
+    }
+    finally {
+        secret?.fill(0);
+        snapshot.fill(0);
+    }
+}

package/packages/investigation/investigation-package.mjs

@@ -0,0 +1,200 @@
+import { zipSync } from 'fflate';
+import { MAX_INVESTIGATION_PACKAGE_ENTRIES, MAX_INVESTIGATION_PACKAGE_BYTES } from "../contracts/investigation-package-limits.mjs";
+export { MAX_INVESTIGATION_PACKAGE_ENTRIES, MAX_INVESTIGATION_PACKAGE_BYTES } from "../contracts/investigation-package-limits.mjs";
+import { extractBoundedZipEntries } from "../interchange/bounded-zip-extraction.mjs";
+import { canonicalArtifactJsonV2, sha256ArtifactBytes, sha256ArtifactDigestV2 } from "../evidence/artifact-integrity.mjs";
+import { INVESTIGATION_CAPSULE_SCHEMA, investigationCapsuleSourceIdentity } from "./investigation-capsule.mjs";
+import { matchCaptureArtifacts, readWebCaptureManifest } from "../interchange/web-capture-import.mjs";
+import { MAX_WEB_CAPTURE_MANIFEST_BYTES, WEB_CAPTURE_MANIFEST_SCHEMA } from "../contracts/web-capture.mjs";
+import { MAX_INVESTIGATION_MANIFEST_ARTIFACTS, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, investigationJsonMetadata, prepareInvestigationManifest, readInvestigationManifest, } from "./investigation-manifest.mjs";
+export const INVESTIGATION_PACKAGE_MANIFEST_PATH = 'manifest.json';
+const MANIFEST_PATH = INVESTIGATION_PACKAGE_MANIFEST_PATH;
+const MAX_PACKAGE_ENTRIES = MAX_INVESTIGATION_PACKAGE_ENTRIES;
+export function investigationPackageEntryPath(id) {
+    const match = /^artifact-([1-9]\d{0,2})$/u.exec(id);
+    if (!match || Number(match[1]) > MAX_INVESTIGATION_MANIFEST_ARTIFACTS)
+        throw new TypeError('Invalid investigation package entry identity.');
+    return `artifacts/${id}`;
+}
+export function investigationPackagePath(name) {
+    if (typeof name !== 'string')
+        throw new TypeError('Investigation package entry paths must be strings.');
+    if (name === MANIFEST_PATH)
+        return name;
+    if (!name.startsWith('artifacts/') || investigationPackageEntryPath(name.slice('artifacts/'.length)) !== name)
+        throw new TypeError('Investigation package contains an unexpected entry path.');
+    return name;
+}
+export async function prepareInvestigationPackageEntries(input, generatedAt, applicationVersion) {
+    const prepared = await prepareInvestigationManifest(input, generatedAt, applicationVersion);
+    const files = new Map();
+    files.set(MANIFEST_PATH, new TextEncoder().encode(canonicalArtifactJsonV2(prepared.manifest)));
+    for (const [index, item] of prepared.manifest.artifacts.entries())
+        files.set(investigationPackageEntryPath(item.id), prepared.contents[index]);
+    return Object.freeze({ manifest: prepared.manifest, files });
+}
+/** Capture a directory selection before hashing; no caller-owned bytes survive. */
+function capturePackageEntries(input) {
+    if (!(input instanceof Map) || input.size < 2 || input.size > MAX_PACKAGE_ENTRIES)
+        throw new TypeError('Investigation package has an invalid entry count.');
+    const files = new Map();
+    let total = 0;
+    for (const [name, bytes] of input) {
+        investigationPackagePath(name);
+        const maximum = name === MANIFEST_PATH ? MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES : MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES;
+        if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > maximum)
+            throw new TypeError('Investigation package entry exceeds its byte limit.');
+        if (name !== MANIFEST_PATH) {
+            if (bytes.byteLength > MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES - total)
+                throw new TypeError('Investigation package exceeds its combined byte limit.');
+            total += bytes.byteLength;
+        }
+        files.set(name, new Uint8Array(bytes));
+    }
+    if (!files.has(MANIFEST_PATH))
+        throw new TypeError('Investigation package is missing its manifest.');
+    return files;
+}
+/** A stable container representation, independent of directory listing order. */
+export function encodeInvestigationPackageEntries(input) {
+    const captured = capturePackageEntries(input);
+    const files = Object.create(null);
+    for (const name of [...captured.keys()].sort())
+        files[name] = captured.get(name);
+    // Stored entries avoid re-compressing images and large JSON while retaining
+    // exact source bytes. The reader also admits independently bounded deflate.
+    const bytes = zipSync(files, { level: 0, mtime: new Date(1980, 0, 1) });
+    if (bytes.byteLength > MAX_INVESTIGATION_PACKAGE_BYTES)
+        throw new TypeError('Investigation package exceeds its byte limit.');
+    return bytes;
+}
+export async function buildInvestigationPackage(input, generatedAt, applicationVersion) {
+    const prepared = await prepareInvestigationPackageEntries(input, generatedAt, applicationVersion);
+    return Object.freeze({ manifest: prepared.manifest, bytes: encodeInvestigationPackageEntries(prepared.files) });
+}
+export async function inspectInvestigationPackage(input) {
+    if (!(input instanceof Uint8Array) || input.byteLength < 22 || input.byteLength > MAX_INVESTIGATION_PACKAGE_BYTES)
+        throw new TypeError(`Investigation package input must fit within ${MAX_INVESTIGATION_PACKAGE_BYTES} bytes.`);
+    // The bounded reader verifies local/central identity and every selected CRC.
+    // All entries are selected: an unverified trailing file cannot hide in a pack.
+    const extracted = extractBoundedZipEntries(input, {
+        maximumEntries: MAX_PACKAGE_ENTRIES,
+        maximumSelectedBytes: MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES + MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES,
+        selectedBytesExceededMessage: 'Investigation package exceeds its inflated byte limit.',
+        metadataMismatchMessage: 'Investigation package ZIP metadata or CRC is invalid.',
+        keyForName: investigationPackagePath,
+        inspect(info) {
+            const key = investigationPackagePath(info.name);
+            const maximumBytes = key === MANIFEST_PATH ? MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES : MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES;
+            if (info.originalSize < 1 || info.originalSize > maximumBytes)
+                throw new TypeError('Investigation package entry exceeds its byte limit.');
+            return { key, selected: true, maximumBytes, exceededMessage: 'Investigation package entry exceeds its inflated byte limit.' };
+        },
+    });
+    return inspectOwnedPackageEntries(extracted.files);
+}
+export async function inspectInvestigationPackageEntries(input) {
+    return inspectOwnedPackageEntries(capturePackageEntries(input));
+}
+async function inspectOwnedPackageEntries(files) {
+    const manifestBytes = files.get(MANIFEST_PATH);
+    if (!manifestBytes)
+        throw new TypeError('Investigation package is missing its manifest.');
+    const manifest = await readInvestigationManifest(new TextDecoder('utf-8', { fatal: true }).decode(manifestBytes));
+    if (files.size !== manifest.artifacts.length + 1)
+        throw new TypeError('Investigation package has missing or unlisted files.');
+    const entries = [];
+    const contents = new Map();
+    const captureDeclarations = new Map();
+    const jsonSources = new Map();
+    for (const entry of manifest.artifacts) {
+        const content = files.get(investigationPackageEntryPath(entry.id));
+        if (!content)
+            throw new TypeError('Investigation package is missing a declared file.');
+        const isJson = !('mediaType' in entry) || entry.mediaType === 'application/json';
+        const byteLength = content.byteLength === entry.byteLength;
+        const rawDigest = await sha256ArtifactBytes(content) === entry.contentDigestSha256;
+        let canonicalDigest = isJson ? false : null;
+        let schema = isJson ? false : null;
+        let version = isJson ? false : null;
+        let issue = null;
+        let interpretation = isJson ? 'not_checked' : 'opaque';
+        if (isJson) {
+            try {
+                const metadata = investigationJsonMetadata(new TextDecoder('utf-8', { fatal: true }).decode(content));
+                canonicalDigest = await sha256ArtifactDigestV2(metadata.value) === entry.canonicalDigestSha256;
+                schema = metadata.schema === entry.schema;
+                version = metadata.version === entry.version;
+                if (!metadata.object)
+                    interpretation = 'unsupported_json_value';
+                if (metadata.object && byteLength && rawDigest && canonicalDigest && schema && version) {
+                    if (metadata.schema === WEB_CAPTURE_MANIFEST_SCHEMA) {
+                        try {
+                            if (content.byteLength > MAX_WEB_CAPTURE_MANIFEST_BYTES)
+                                throw new TypeError('Capture manifest is oversized.');
+                            captureDeclarations.set(entry.id, readWebCaptureManifest(metadata.object).artifacts);
+                        }
+                        catch {
+                            captureDeclarations.set(entry.id, null);
+                        }
+                    }
+                    const query = metadata.object.query;
+                    const queryObject = query && typeof query === 'object' && !Array.isArray(query) ? query : null;
+                    jsonSources.set(entry.id, {
+                        schema: metadata.schema, version: metadata.version, digest: entry.canonicalDigestSha256,
+                        query: queryObject ? { submitted: queryObject.submitted, type: queryObject.type } : null,
+                        target: metadata.schema === INVESTIGATION_CAPSULE_SCHEMA ? metadata.object.target : null,
+                        references: metadata.schema === INVESTIGATION_CAPSULE_SCHEMA ? metadata.object.sourceContracts : null,
+                    });
+                }
+            }
+            catch {
+                issue = 'The declared JSON file is not valid bounded UTF-8 JSON.';
+            }
+        }
+        const verified = byteLength && rawDigest && canonicalDigest !== false && schema !== false && version !== false;
+        entries.push(Object.freeze({ entry, state: verified ? 'identity_verified' : 'rejected',
+            checks: Object.freeze({ byteLength, rawDigest, canonicalDigest, schema, version }),
+            interpretation,
+            issue: issue ?? (verified ? null : 'File content does not match its manifest identity.'),
+        }));
+        // Rejected bytes remain in the selected archive but cannot be used by an
+        // importing caller as if they had passed identity verification.
+        if (verified)
+            contents.set(entry.id, content);
+    }
+    const links = [];
+    const captureManifests = [...captureDeclarations].map(([entryId, declarations]) => {
+        if (!declarations)
+            return { entryId, state: 'rejected', artifacts: [] };
+        const artifacts = matchCaptureArtifacts(declarations, entries
+            .filter(candidate => candidate.entry.id !== entryId && candidate.state === 'identity_verified')
+            .map(candidate => ({ id: candidate.entry.id, bytes: candidate.entry.byteLength, sha256: candidate.entry.contentDigestSha256 })));
+        return { entryId, state: artifacts.every(artifact => artifact.state === 'matched') ? 'matched' : 'missing_attachments', artifacts };
+    });
+    for (const [id, capsule] of jsonSources) {
+        if (capsule.schema !== INVESTIGATION_CAPSULE_SCHEMA)
+            continue;
+        const references = Array.isArray(capsule.references) && capsule.references.length <= 4
+            ? capsule.references.filter((item) => item && typeof item === 'object' && item.id === 'lookup-evidence') : [];
+        if (references.length !== 1) {
+            links.push({ capsuleEntryId: id, sourceEntryId: null, state: 'mismatch' });
+            continue;
+        }
+        const reference = references[0];
+        const candidates = [...jsonSources].filter(([otherId, source]) => otherId !== id && source.schema === reference.schema && source.digest === reference.digest);
+        if (candidates.length !== 1) {
+            const state = candidates.length > 1 ? 'ambiguous' : [...jsonSources.values()].some((source) => source.schema === reference.schema) ? 'mismatch' : 'missing';
+            links.push({ capsuleEntryId: id, sourceEntryId: null, state });
+            continue;
+        }
+        const [sourceEntryId, source] = candidates[0];
+        const identity = investigationCapsuleSourceIdentity(capsule.target, reference, source);
+        links.push({ capsuleEntryId: id, sourceEntryId, state: identity.linked ? 'linked' : 'mismatch' });
+    }
+    return Object.freeze({ manifest, entries: Object.freeze(entries), contents, links: Object.freeze(links), captureManifests: Object.freeze(captureManifests),
+        identityVerified: entries.every((entry) => entry.state === 'identity_verified'),
+        storageEffect: 'none',
+        signatureTrust: 'not_checked', timestampAssurance: 'not_checked', factualAccuracy: 'not_established',
+    });
+}

package/packages/investigation/lookup-asset-graph-inputs.mjs

@@ -0,0 +1,38 @@
+/** Counts describe the projection input, not the collector's upstream universe. */
+export function createGraphInputReader() {
+    const coverage = new Map();
+    function values(id, value, maximum, normalise, identity) {
+        const input = Array.isArray(value) ? value : [];
+        const inspected = Math.min(input.length, maximum * 4);
+        const result = [];
+        const seen = new Set();
+        let invalid = 0;
+        let duplicates = 0;
+        let omitted = 0;
+        for (let index = 0; index < inspected; index += 1) {
+            const item = normalise(input[index]);
+            if (item === null) {
+                invalid += 1;
+                continue;
+            }
+            const key = identity?.(item);
+            if (key !== undefined && seen.has(key)) {
+                duplicates += 1;
+                continue;
+            }
+            if (key !== undefined)
+                seen.add(key);
+            if (result.length === maximum) {
+                omitted += 1;
+                continue;
+            }
+            result.push(item);
+        }
+        coverage.set(id, { id, supplied: input.length, inspected, admitted: result.length, invalid, duplicates, omitted });
+        return result;
+    }
+    return { values, coverage };
+}
+export function graphInputIsIncomplete(row) {
+    return row.supplied > row.inspected || row.invalid > 0 || row.omitted > 0;
+}