@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/investigation/identity-incident-review.mjs

@@ -0,0 +1,39 @@
+import { array, enumeration, exact } from "../evidence/artifact-structure.mjs";
+import { IDENTITY_ACTIONS } from "../contracts/message-intake.mjs";
+/** Reported actions select recovery guidance; they do not establish compromise. */
+export function reviewIdentityIncident(value) {
+    const input = exact(value, ['reportedActions'], 'Identity incident review');
+    const allowed = IDENTITY_ACTIONS.map(action => action.id);
+    const reportedActions = [...new Set(array(input.reportedActions, 'Reported actions', allowed.length)
+            .map(item => enumeration(item, allowed, 'Reported action')))];
+    const has = (...actions) => actions.some(action => reportedActions.includes(action));
+    const nextSteps = [];
+    const add = (id, title, detail) => nextSteps.push({ id, title, detail });
+    if (reportedActions.length)
+        add('preserve', 'Preserve the message and sign-in timeline', 'Record the reported time and action, retain relevant account audit events and keep the original privately. Use an independently known account portal, not the supplied link.');
+    if (has('entered_password', 'approved_signin', 'entered_device_code')) {
+        add('sessions', 'Review and revoke suspicious account sessions', 'Use the identity provider’s documented response process. Review recent sign-ins, new authentication methods and registered devices; resetting a password alone may not invalidate existing sessions.');
+    }
+    if (has('entered_password'))
+        add('password', 'Change exposed and reused credentials', 'Change the affected password through a trusted route. Review other accounts where the same credential was used, without testing the supplied site.');
+    if (has('granted_consent', 'entered_device_code'))
+        add('grants', 'Review application grants and tokens', 'Identify the application/client ID in account audit records. Revoke unwanted consent and refresh tokens using the provider’s controls; check accessed mail and files and newly created inbox rules.');
+    if (has('executed_command'))
+        add('endpoint', 'Escalate for endpoint containment', 'Stop using the affected device for account recovery. Follow the organisation’s endpoint incident process, preserve the command as inert evidence and use a separate trusted device.');
+    if (has('entered_password', 'approved_signin', 'entered_device_code', 'granted_consent'))
+        add('persistence', 'Check persistence and downstream access', 'Review forwarding rules, delegates, newly authorised applications and affected data. Record the findings independently of public domain evidence.');
+    if (reportedActions.length)
+        add('followup', 'Record recovery actions and a follow-up', 'Track account recovery separately from provider reports and domain availability. A removed page does not show that an account session or application grant was revoked.');
+    return { reportedActions, nextSteps };
+}
+/** A deliberate follow-up request, never a completed recovery or compromise claim. */
+export function identityRecoveryFollowUp(reportedActions, stepId) {
+    const review = reviewIdentityIncident({ reportedActions });
+    const step = review.nextSteps.find(item => item.id === stepId);
+    if (!step)
+        throw new TypeError('Select a recommendation supported by the reported actions.');
+    return {
+        statement: `Requested follow-up: ${step.title}`,
+        rationale: `Conditional analyst request based on reported actions, not independently verified account telemetry. ${step.detail} No recovery action or independent result is established by this request.`,
+    };
+}

package/packages/investigation/incident-sequence-review.mjs

@@ -0,0 +1,58 @@
+import { CASE_PIN_COMPLETENESS } from "../cases/case-response-records.mjs";
+import { MAX_RESPONSE_VALUE_LENGTH, MAX_RESPONSE_LABEL_LENGTH, MAX_RESPONSE_LIMITATIONS, MAX_RESPONSE_LIMITATION_LENGTH } from "../contracts/case-portability.mjs";
+import { CONTEXT_REVIEW_SCHEMA, CONTEXT_REVIEW_VERSION, MAX_CONTEXT_RECORDS } from "../contracts/context-review.mjs";
+import { array, domain, enumeration, exact, HEX_DIGEST_RE, iso, text } from "../evidence/artifact-structure.mjs";
+export { INCIDENT_SEQUENCE_INPUT_SCHEMA, INCIDENT_SEQUENCE_INPUT_VERSION } from "../contracts/context-review.mjs";
+export const INCIDENT_STAGE_KINDS = ['message', 'navigation', 'identity_prompt', 'credential_entry', 'consent', 'browser_instruction', 'clipboard', 'local_execution', 'payment', 'recovery', 'other'];
+export const INCIDENT_STAGE_BASES = ['retained_observation', 'imported_record', 'reported_action'];
+export function readIncidentStages(raw) {
+    const stages = array(raw, 'Incident stages', MAX_CONTEXT_RECORDS).map(value => {
+        const row = exact(value, ['id', 'kind', 'basis', 'description', 'occurredAt', 'hostname', 'source', 'reference', 'referenceSha256', 'completeness', 'limitations'], 'Incident stage');
+        const id = text(row.id, 'Stage ID', 64);
+        if (!/^[A-Za-z0-9_-]+$/u.test(id))
+            throw new TypeError('Stage ID must be a bounded identifier.');
+        iso(row.occurredAt, 'Stage occurrence time', true);
+        if (row.hostname !== null)
+            domain(row.hostname, 'Stage hostname');
+        if (row.referenceSha256 !== null && (typeof row.referenceSha256 !== 'string' || !HEX_DIGEST_RE.test(row.referenceSha256)))
+            throw new TypeError('Stage reference digest must be hexadecimal SHA-256 or null.');
+        return { id, kind: enumeration(row.kind, INCIDENT_STAGE_KINDS, 'Stage kind'), basis: enumeration(row.basis, INCIDENT_STAGE_BASES, 'Stage basis'),
+            description: text(row.description, 'Stage description', MAX_RESPONSE_VALUE_LENGTH), occurredAt: row.occurredAt, hostname: row.hostname,
+            source: text(row.source, 'Stage source', MAX_RESPONSE_LABEL_LENGTH), reference: text(row.reference, 'Stage reference', 500), referenceSha256: row.referenceSha256,
+            completeness: enumeration(row.completeness, CASE_PIN_COMPLETENESS, 'Stage completeness'),
+            limitations: array(row.limitations, 'Stage limitations', MAX_RESPONSE_LIMITATIONS).map(item => text(item, 'Stage limitation', MAX_RESPONSE_LIMITATION_LENGTH)), };
+    });
+    if (new Set(stages.map(row => row.id)).size !== stages.length)
+        throw new TypeError('Incident stage IDs must be unique.');
+    return stages;
+}
+/** Copy the selected pin's provenance without giving it stronger assurance. */
+export function incidentStageFromPin(pin, kind, id) {
+    return readIncidentStages([{ id, kind, basis: 'retained_observation', description: pin.value, occurredAt: pin.observedAt,
+            hostname: pin.observationHostname ?? null, source: pin.source, reference: pin.id, referenceSha256: pin.importContentSha256 ?? null,
+            completeness: pin.truncated === true && pin.completeness === 'complete' ? 'partial' : pin.completeness, limitations: [...pin.limitations],
+        }])[0];
+}
+export function reviewIncidentSequence(raw, reviewedAt) {
+    iso(reviewedAt, 'Review time');
+    const stages = readIncidentStages(raw);
+    const counts = Object.fromEntries(INCIDENT_STAGE_BASES.map(basis => [basis, stages.filter(row => row.basis === basis).length]));
+    let priorTime = null, reversedTimes = 0;
+    for (const row of stages) {
+        if (row.occurredAt === null)
+            continue;
+        const time = Date.parse(row.occurredAt);
+        if (priorTime !== null && time < priorTime)
+            reversedTimes++;
+        priorTime = time;
+    }
+    return { schema: CONTEXT_REVIEW_SCHEMA, version: CONTEXT_REVIEW_VERSION, kind: 'incident_sequence', reviewedAt, title: 'Incident sequence',
+        state: !stages.length || stages.some(row => row.occurredAt === null || row.completeness !== 'complete') || reversedTimes ? 'partial' : 'reviewed',
+        summary: `Analyst-ordered stages: ${stages.length} (retained observations: ${counts.retained_observation}; imported records: ${counts.imported_record}; reported actions: ${counts.reported_action}).${reversedTimes ? ` Timestamp reversals needing review: ${reversedTimes}; the selected order was preserved.` : ''}`,
+        observations: stages.map((row, index) => ({ label: `${index + 1}. ${row.kind.replaceAll('_', ' ')} · ${row.basis.replaceAll('_', ' ')}`,
+            state: row.completeness === 'complete' ? 'reported' : 'partial', detail: `${row.description} · Source completeness: ${row.completeness}.${row.limitations.length ? ` ${row.limitations.join(' ')}` : ''}`,
+            source: `${row.source} · reference ${row.reference}${row.referenceSha256 ? ` · reference SHA-256 ${row.referenceSha256}` : ''}`, observedAt: row.occurredAt, hostname: row.hostname })),
+        nextSteps: ['Compare stages with the selected message and capture records; retain gaps and conflicting source times.', 'Use reported credential entry, consent or local execution to select the relevant account or device recovery review, separately from domain reporting.'],
+        limitations: ['Order is analyst-selected, not proof of causation or a verified attack chain. An instruction, prompt or clipboard attempt does not establish that a person followed it.', 'Sources, occurrence times and reference digests retain their supplied meaning; importing this input does not authenticate them. Unknown times are not replaced by review or save time.'],
+    };
+}

package/packages/investigation/intake-report.mjs

@@ -0,0 +1,19 @@
+import { sha256ArtifactBytes } from "../evidence/artifact-integrity.mjs";
+import { normalizeExplicitIsoTimestamp } from "../evidence/observation.mjs";
+import { MESSAGE_INTAKE_KINDS, MESSAGE_INTAKE_SCHEMA, MESSAGE_INTAKE_VERSION, MAX_MESSAGE_INTAKE_BYTES } from "../contracts/message-intake.mjs";
+export function assertMessageBytes(bytes) {
+    if (!(bytes instanceof Uint8Array) || !(bytes.buffer instanceof ArrayBuffer) || !bytes.byteLength || bytes.byteLength > MAX_MESSAGE_INTAKE_BYTES) {
+        throw new TypeError('Select one non-empty input of at most 16 MiB. No input was retained.');
+    }
+}
+export async function createIntakeReport(bytes, kind, reviewedAt) {
+    assertMessageBytes(bytes);
+    const instant = normalizeExplicitIsoTimestamp(reviewedAt);
+    if (!instant || !MESSAGE_INTAKE_KINDS.includes(kind))
+        throw new TypeError('Input review requires a supported format and a timestamp with an explicit timezone.');
+    return { schema: MESSAGE_INTAKE_SCHEMA, schemaVersion: MESSAGE_INTAKE_VERSION, reviewedAt: instant,
+        source: { kind, digestSha256: await sha256ArtifactBytes(bytes), byteLength: bytes.byteLength },
+        coverage: { state: 'reviewed', reviewedParts: 0, unreviewedAttachments: 0, rejectedLinks: 0, boundsReached: [] },
+        identities: [], authenticationClaims: [], authenticationReview: { headers: [], omittedHeaders: 0 }, messageParts: [],
+        links: [], actionHints: [], identityRecovery: { reportedActions: [], nextSteps: [] } };
+}

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

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 "../analysis/bounded-json.mjs";
+import { normalizeBoundedSemanticVersion } from "../analysis/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);
+    }
+}