@slicedearth/whoisleuth-cli 1.45.0 → 1.47.4

package/cli/artifact-verify.mjs

@@ -1,20 +1,26 @@
 import { Buffer } from 'node:buffer';
-import { CASE_RESPONSE_PACKET_SCHEMA, CASE_RESPONSE_PACKET_VERSION, verifyCaseResponsePacketIntegrity, } from "../frontend/src/lib/analysis/case-response-packet.js";
+import { createHash } from 'node:crypto';
+import { parseBoundedJsonObject } from "./bounded-json.mjs";
+import { validateInvestigationCapsuleStructure, validateLookupEvidenceArtifactStructure, validateOfflineArtifactStructure, validateSignedDigestArtifactStructure, } from "./artifact-structure.mjs";
+import { CASE_RESPONSE_PACKET_SCHEMA, CASE_RESPONSE_PACKET_VERSION, LEGACY_CASE_RESPONSE_PACKET_VERSION, verifyCaseResponsePacketIntegrity, } from "../frontend/src/lib/analysis/case-response-packet.js";
 import { ACQUISITION_DECISION_PACKET_SCHEMA, ACQUISITION_DECISION_PACKET_VERSION, } from "../frontend/src/lib/analysis/acquisition-decision-packet.js";
-import { BULK_DOMAIN_COMPARISON_SCHEMA, BULK_DOMAIN_COMPARISON_VERSION, } from "../frontend/src/lib/analysis/bulk-domain-comparison.js";
-import { BULK_MAIL_EXPOSURE_SCHEMA, BULK_MAIL_EXPOSURE_VERSION, } from "../frontend/src/lib/analysis/bulk-mail-exposure.js";
+import { LOOKUP_CLAIM_PASSPORT_SCHEMA, LOOKUP_CLAIM_PASSPORT_VERSION, } from "../frontend/src/lib/analysis/lookup-claim-passport.js";
+import { BULK_DOMAIN_COMPARISON_SCHEMA, BULK_DOMAIN_COMPARISON_EXPORT_VERSION, } from "../frontend/src/lib/analysis/bulk-domain-comparison.js";
+import { BULK_MAIL_EXPOSURE_SCHEMA, BULK_MAIL_EXPOSURE_EXPORT_VERSION, } from "../frontend/src/lib/analysis/bulk-mail-exposure.js";
 import { BULK_REVIEW_MANIFEST_SCHEMA, BULK_REVIEW_MANIFEST_VERSION, } from "../frontend/src/lib/analysis/bulk-review-export.js";
 import { decryptWorkspaceArchive, inspectEncryptedWorkspaceArchive, isEncryptedWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive-crypto.js";
-import { WORKSPACE_ARCHIVE_SCHEMA, readWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive.js";
-import { sha256ArtifactDigest } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { WORKSPACE_ARCHIVE_SCHEMA, previewWorkspaceArchive, readWorkspaceArchive, } from "../frontend/src/lib/analysis/workspace-archive.js";
+import { canonicalArtifactJsonFor, resolveArtifactCanonicalization, sha256ArtifactDigestFor, SORTED_JSON_V1, SORTED_JSON_V2, } from "../frontend/src/lib/analysis/artifact-integrity.js";
 import { SAVED_LOOKUP_SCHEMA, SAVED_LOOKUP_SCHEMA_VERSION, parseSavedLookupDocument, } from "./saved-lookup.mjs";
 import { DOMAIN_CONTROL_MANIFEST_SCHEMA, DOMAIN_CONTROL_MANIFEST_VERSION, verifyDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
+import { DOMAIN_CONTROL_PASSPORT_VERSION } from "../frontend/src/lib/analysis/domain-control-manifest-core.js";
 import { DOMAIN_CHANGE_PACKET_SCHEMA, DOMAIN_CHANGE_PACKET_VERSION, } from "../lib/domain-change-packet.mjs";
-import { INVESTIGATION_CAPSULE_SCHEMA, INVESTIGATION_CAPSULE_VERSION, verifyInvestigationCapsule, } from "../frontend/src/lib/analysis/investigation-capsule.js";
+import { INVESTIGATION_CAPSULE_SCHEMA, INVESTIGATION_CAPSULE_VERSION, LEGACY_INVESTIGATION_CAPSULE_VERSION, verifyInvestigationCapsule, } from "../frontend/src/lib/analysis/investigation-capsule.js";
 import { INVESTIGATION_MANIFEST_SCHEMA, INVESTIGATION_MANIFEST_VERSION, } from "./investigation-manifest.mjs";
-import { CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, verifyCliCasePack, } from "./case-pack.mjs";
+import { CLI_CASE_PACK_SCHEMA, verifyCliCasePack, } from "./case-pack.mjs";
+import { LOOKUP_EVIDENCE_PORTABLE_MAX_BYTES, LOOKUP_EVIDENCE_SCHEMA, SUPPORTED_LOOKUP_EVIDENCE_SCHEMA_VERSIONS, } from "../lib/evidence-export.mjs";
 export const OFFLINE_ARTIFACT_VERIFICATION_SCHEMA = 'whoisleuth.offline-artifact-verification';
-export const OFFLINE_ARTIFACT_VERIFICATION_VERSION = 1;
+export const OFFLINE_ARTIFACT_VERIFICATION_VERSION = 3;
 export const MAX_OFFLINE_ARTIFACT_BYTES = 15 * 1024 * 1024;
 export const MAX_OFFLINE_PASSPHRASE_FILE_BYTES = 1024;
 export class UnsupportedOfflineArtifactError extends TypeError {
@@ -25,13 +31,24 @@ export class UnsupportedOfflineArtifactError extends TypeError {
     }
 }
 const SIGNED_ARTIFACT_VERSIONS = Object.freeze({
-    [ACQUISITION_DECISION_PACKET_SCHEMA]: new Set([ACQUISITION_DECISION_PACKET_VERSION]),
-    [BULK_DOMAIN_COMPARISON_SCHEMA]: new Set([BULK_DOMAIN_COMPARISON_VERSION]),
-    [BULK_MAIL_EXPOSURE_SCHEMA]: new Set([BULK_MAIL_EXPOSURE_VERSION]),
-    [BULK_REVIEW_MANIFEST_SCHEMA]: new Set([BULK_REVIEW_MANIFEST_VERSION]),
-    [DOMAIN_CONTROL_MANIFEST_SCHEMA]: new Set([DOMAIN_CONTROL_MANIFEST_VERSION]),
-    [DOMAIN_CHANGE_PACKET_SCHEMA]: new Set([DOMAIN_CHANGE_PACKET_VERSION]),
-    [INVESTIGATION_MANIFEST_SCHEMA]: new Set([INVESTIGATION_MANIFEST_VERSION]),
+    [ACQUISITION_DECISION_PACKET_SCHEMA]: new Set([1, ACQUISITION_DECISION_PACKET_VERSION]),
+    [LOOKUP_CLAIM_PASSPORT_SCHEMA]: new Set([LOOKUP_CLAIM_PASSPORT_VERSION]),
+    [BULK_DOMAIN_COMPARISON_SCHEMA]: new Set([3, BULK_DOMAIN_COMPARISON_EXPORT_VERSION]),
+    [BULK_MAIL_EXPOSURE_SCHEMA]: new Set([1, BULK_MAIL_EXPOSURE_EXPORT_VERSION]),
+    [BULK_REVIEW_MANIFEST_SCHEMA]: new Set([1, BULK_REVIEW_MANIFEST_VERSION]),
+    [DOMAIN_CONTROL_MANIFEST_SCHEMA]: new Set([DOMAIN_CONTROL_PASSPORT_VERSION, DOMAIN_CONTROL_MANIFEST_VERSION]),
+    [DOMAIN_CHANGE_PACKET_SCHEMA]: new Set([1, DOMAIN_CHANGE_PACKET_VERSION]),
+    [INVESTIGATION_MANIFEST_SCHEMA]: new Set([1, INVESTIGATION_MANIFEST_VERSION]),
+});
+const SIGNED_ARTIFACT_CANONICALIZATION = Object.freeze({
+    [ACQUISITION_DECISION_PACKET_SCHEMA]: [{ version: 1, canonicalization: SORTED_JSON_V1, explicit: false }, { version: ACQUISITION_DECISION_PACKET_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [LOOKUP_CLAIM_PASSPORT_SCHEMA]: [{ version: LOOKUP_CLAIM_PASSPORT_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [BULK_DOMAIN_COMPARISON_SCHEMA]: [{ version: 3, canonicalization: SORTED_JSON_V1, explicit: false }, { version: BULK_DOMAIN_COMPARISON_EXPORT_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [BULK_MAIL_EXPOSURE_SCHEMA]: [{ version: 1, canonicalization: SORTED_JSON_V1, explicit: false }, { version: BULK_MAIL_EXPOSURE_EXPORT_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [BULK_REVIEW_MANIFEST_SCHEMA]: [{ version: 1, canonicalization: SORTED_JSON_V1, explicit: false }, { version: BULK_REVIEW_MANIFEST_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [DOMAIN_CONTROL_MANIFEST_SCHEMA]: [{ version: DOMAIN_CONTROL_PASSPORT_VERSION, canonicalization: SORTED_JSON_V1, explicit: true }, { version: DOMAIN_CONTROL_MANIFEST_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [DOMAIN_CHANGE_PACKET_SCHEMA]: [{ version: 1, canonicalization: SORTED_JSON_V1, explicit: false }, { version: DOMAIN_CHANGE_PACKET_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
+    [INVESTIGATION_MANIFEST_SCHEMA]: [{ version: 1, canonicalization: SORTED_JSON_V1, explicit: false }, { version: INVESTIGATION_MANIFEST_VERSION, canonicalization: SORTED_JSON_V2, explicit: true }],
 });
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
@@ -39,23 +56,32 @@ function record(value) {
         : null;
 }
 function parseJson(raw) {
-    if (typeof raw !== 'string')
-        throw new TypeError('Artefact input must be UTF-8 JSON text.');
-    const bytes = Buffer.byteLength(raw, 'utf8');
-    if (bytes === 0 || bytes > MAX_OFFLINE_ARTIFACT_BYTES) {
-        throw new TypeError(`Artifact input must be between 1 byte and ${MAX_OFFLINE_ARTIFACT_BYTES} bytes.`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new TypeError('Artefact input is not valid JSON.');
-    }
-    const value = record(parsed);
-    if (!value)
-        throw new TypeError('Artefact input must contain one JSON object.');
-    return value;
+    return parseBoundedJsonObject(raw, { maximumBytes: MAX_OFFLINE_ARTIFACT_BYTES });
+}
+export function hasVerifiedArtifactStructure(report) {
+    return report.checks.structure === 'verified';
+}
+export function hasVerifiedApplicableIntegrity(report) {
+    return report.checks.contentIntegrity === 'verified'
+        && (report.checks.contentIntegrityScope === 'whole_artifact'
+            || report.checks.contentIntegrityScope === 'embedded_projections');
+}
+export function hasVerifiedWholeArtifactIntegrity(report) {
+    return report.checks.contentIntegrity === 'verified'
+        && report.checks.contentIntegrityScope === 'whole_artifact';
+}
+export function offlineArtifactSatisfiesAssurance(report, requirement) {
+    if (!hasVerifiedArtifactStructure(report))
+        return false;
+    if (requirement === 'structure')
+        return true;
+    if (requirement === 'applicable_integrity')
+        return hasVerifiedApplicableIntegrity(report);
+    return hasVerifiedWholeArtifactIntegrity(report);
+}
+export function isCompleteOfflineArtifactVerification(report) {
+    return (report.state === 'verified' || report.state === 'structure_valid')
+        && (report.manifestIdentity === null || report.manifestIdentity.state === 'identity_verified');
 }
 function artifactVersion(value) {
     const declared = value.version ?? value.schemaVersion;
@@ -70,7 +96,17 @@ function artifactVersion(value) {
 function inputBytes(raw) {
     return Buffer.byteLength(raw, 'utf8');
 }
-function archiveReport(raw, archive, encrypted, ciphertextBytes) {
+async function archiveReport(raw, source, archive, encrypted, ciphertextBytes) {
+    const preview = await previewWorkspaceArchive(source, {});
+    const readySectionCount = preview.sections.filter((section) => section.status === 'ready').length;
+    const unsupportedSectionCount = preview.sections.filter((section) => section.status === 'unsupported').length;
+    const blockedSectionCount = preview.sections.filter((section) => section.status === 'blocked').length;
+    const skippedRecordCount = preview.sections.reduce((sum, section) => sum + section.skipped, 0);
+    const prunedRecordCount = preview.sections.reduce((sum, section) => sum + (section.pruned ?? 0), 0);
+    const fullyImportable = unsupportedSectionCount === 0
+        && blockedSectionCount === 0
+        && skippedRecordCount === 0
+        && prunedRecordCount === 0;
     return Object.freeze({
         schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
         version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
@@ -80,10 +116,10 @@ function archiveReport(raw, archive, encrypted, ciphertextBytes) {
             version: archive.sourceVersion,
         }),
         state: 'verified',
-        valid: true,
         checks: Object.freeze({
             structure: 'verified',
             contentIntegrity: 'verified',
+            contentIntegrityScope: 'whole_artifact',
             authenticatedEncryption: encrypted ? 'verified' : 'not_applicable',
         }),
         summary: Object.freeze({
@@ -91,9 +127,18 @@ function archiveReport(raw, archive, encrypted, ciphertextBytes) {
             sectionCount: archive.sections.length,
             recordCount: archive.sections.reduce((sum, section) => sum + section.recordCount, 0),
             ciphertextBytes,
+            readySectionCount,
+            unsupportedSectionCount,
+            blockedSectionCount,
+            skippedRecordCount,
+            prunedRecordCount,
+            fullyImportable,
         }),
         limitations: Object.freeze([
             'Verification checks the retained file against its declared versioned integrity contract; it does not establish that the original observations were accurate or remain current.',
+            ...(!fullyImportable
+                ? ['One or more integrity-valid archive sections cannot be imported completely by this version. Inspect the archive before selecting data to restore.']
+                : []),
         ]),
     });
 }
@@ -102,6 +147,7 @@ async function verifySignedArtifact(raw, value, schema, version) {
     if (!supported?.has(version)) {
         throw new UnsupportedOfflineArtifactError('This signed review-artifact schema or version is not supported.');
     }
+    validateSignedDigestArtifactStructure(schema, value);
     const integrity = record(value.integrity);
     if (!integrity
         || integrity.algorithm !== 'SHA-256'
@@ -109,8 +155,9 @@ async function verifySignedArtifact(raw, value, schema, version) {
         || !/^sha256:[a-f0-9]{64}$/u.test(integrity.digestSha256)) {
         throw new TypeError('The signed review artefact has a missing or malformed integrity envelope.');
     }
+    const canonicalization = resolveArtifactCanonicalization(version, integrity.canonicalization, SIGNED_ARTIFACT_CANONICALIZATION[schema] ?? [], 'Signed review artefact');
     const { integrity: _integrity, ...unsigned } = value;
-    if (await sha256ArtifactDigest(unsigned) !== integrity.digestSha256) {
+    if (await sha256ArtifactDigestFor(unsigned, canonicalization) !== integrity.digestSha256) {
         throw new TypeError('The signed review artefact failed its SHA-256 integrity check.');
     }
     if (schema === DOMAIN_CONTROL_MANIFEST_SCHEMA)
@@ -120,10 +167,10 @@ async function verifySignedArtifact(raw, value, schema, version) {
         version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
         artifact: Object.freeze({ kind: 'signed_review_artifact', schema, version }),
         state: 'verified',
-        valid: true,
         checks: Object.freeze({
             structure: 'verified',
             contentIntegrity: 'verified',
+            contentIntegrityScope: 'whole_artifact',
             authenticatedEncryption: 'not_applicable',
         }),
         summary: Object.freeze({
@@ -137,7 +184,7 @@ async function verifySignedArtifact(raw, value, schema, version) {
         ]),
     });
 }
-export async function verifyOfflineArtifact(raw, options = {}) {
+async function verifyOfflineArtifactCore(raw, options = {}) {
     const value = parseJson(raw);
     const casePackPacket = record(value.packet);
     if (casePackPacket?.schema === CLI_CASE_PACK_SCHEMA) {
@@ -148,13 +195,13 @@ export async function verifyOfflineArtifact(raw, options = {}) {
             artifact: Object.freeze({
                 kind: 'cli_case_pack',
                 schema: CLI_CASE_PACK_SCHEMA,
-                version: CLI_CASE_PACK_VERSION,
+                version: Number(casePackPacket.version),
             }),
             state: 'verified',
-            valid: true,
             checks: Object.freeze({
                 structure: 'verified',
                 contentIntegrity: 'verified',
+                contentIntegrityScope: 'whole_artifact',
                 authenticatedEncryption: 'not_applicable',
             }),
             summary: Object.freeze({
@@ -180,10 +227,10 @@ export async function verifyOfflineArtifact(raw, options = {}) {
                     version: artifactVersion(value),
                 }),
                 state: 'envelope_valid',
-                valid: true,
                 checks: Object.freeze({
                     structure: 'verified',
                     contentIntegrity: 'not_checked',
+                    contentIntegrityScope: 'not_checked',
                     authenticatedEncryption: 'not_checked',
                 }),
                 summary: Object.freeze({
@@ -200,17 +247,18 @@ export async function verifyOfflineArtifact(raw, options = {}) {
         }
         const decrypted = await decryptWorkspaceArchive(value, options.passphrase);
         const archive = await readWorkspaceArchive(decrypted);
-        return archiveReport(raw, archive, true, inspected.ciphertextBytes);
+        return archiveReport(raw, decrypted, archive, true, inspected.ciphertextBytes);
     }
     const schema = typeof value.schema === 'string' ? value.schema : '';
     const version = artifactVersion(value);
     if (schema === WORKSPACE_ARCHIVE_SCHEMA) {
-        return archiveReport(raw, await readWorkspaceArchive(value), false, null);
+        return archiveReport(raw, value, await readWorkspaceArchive(value), false, null);
     }
     if (schema === CASE_RESPONSE_PACKET_SCHEMA) {
-        if (version !== CASE_RESPONSE_PACKET_VERSION) {
+        if (version !== LEGACY_CASE_RESPONSE_PACKET_VERSION && version !== CASE_RESPONSE_PACKET_VERSION) {
             throw new UnsupportedOfflineArtifactError('This case-response packet version is not supported.');
         }
+        validateOfflineArtifactStructure(schema, value);
         const integrity = record(value.integrity);
         if (!integrity || !await verifyCaseResponsePacketIntegrity(value)) {
             throw new TypeError('The case-response packet failed its manifest integrity check.');
@@ -220,10 +268,10 @@ export async function verifyOfflineArtifact(raw, options = {}) {
             version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
             artifact: Object.freeze({ kind: 'case_response_packet', schema, version }),
             state: 'verified',
-            valid: true,
             checks: Object.freeze({
                 structure: 'verified',
                 contentIntegrity: 'verified',
+                contentIntegrityScope: 'whole_artifact',
                 authenticatedEncryption: 'not_applicable',
             }),
             summary: Object.freeze({
@@ -238,21 +286,23 @@ export async function verifyOfflineArtifact(raw, options = {}) {
         });
     }
     if (schema === INVESTIGATION_CAPSULE_SCHEMA) {
-        if (version !== INVESTIGATION_CAPSULE_VERSION) {
+        if (version !== LEGACY_INVESTIGATION_CAPSULE_VERSION && version !== INVESTIGATION_CAPSULE_VERSION) {
             throw new UnsupportedOfflineArtifactError('This investigation-capsule version is not supported.');
         }
+        validateInvestigationCapsuleStructure(value);
         const verification = await verifyInvestigationCapsule(value);
         if (!verification.valid)
             throw new TypeError('The investigation capsule failed its embedded projection integrity checks.');
+        const current = version === INVESTIGATION_CAPSULE_VERSION;
         return Object.freeze({
             schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
             version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
             artifact: Object.freeze({ kind: 'investigation_capsule', schema, version }),
-            state: 'verified',
-            valid: true,
+            state: current ? 'verified' : 'integrity_valid',
             checks: Object.freeze({
                 structure: 'verified',
                 contentIntegrity: 'verified',
+                contentIntegrityScope: current ? 'whole_artifact' : 'embedded_projections',
                 authenticatedEncryption: 'not_applicable',
             }),
             summary: Object.freeze({
@@ -262,11 +312,45 @@ export async function verifyOfflineArtifact(raw, options = {}) {
                 ciphertextBytes: null,
             }),
             limitations: Object.freeze([
-                'The embedded brief, graph, and optional analyst-record projections match their declared digests; the linked Lookup evidence is not embedded and must be verified separately.',
+                ...(current
+                    ? ['The whole capsule matches its declared digest, including metadata and the linked source-contract projection digests. The non-embedded Lookup evidence remains linked by digest and must be retained separately.']
+                    : ['The embedded brief, graph, and optional analyst-record projections match their declared digests. Capsule metadata and the linked Lookup evidence are outside those projection digests and must not be treated as whole-file integrity verified.']),
                 'Digest verification detects changed content but does not authenticate the analyst, signer, collection source, or truth of retained observations and assertions.',
             ]),
         });
     }
+    if (schema === LOOKUP_EVIDENCE_SCHEMA) {
+        if (!SUPPORTED_LOOKUP_EVIDENCE_SCHEMA_VERSIONS.some((candidate) => candidate === version)) {
+            throw new UnsupportedOfflineArtifactError('This Lookup-evidence document version is not supported.');
+        }
+        if (inputBytes(raw) > LOOKUP_EVIDENCE_PORTABLE_MAX_BYTES) {
+            throw new TypeError('Lookup-evidence documents are limited to 5 MiB for browser-compatible verification.');
+        }
+        validateLookupEvidenceArtifactStructure(value);
+        return Object.freeze({
+            schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
+            version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+            artifact: Object.freeze({ kind: 'lookup_evidence', schema, version }),
+            state: 'structure_valid',
+            checks: Object.freeze({
+                structure: 'verified',
+                contentIntegrity: 'not_checked',
+                contentIntegrityScope: 'not_applicable',
+                authenticatedEncryption: 'not_applicable',
+            }),
+            summary: Object.freeze({
+                inputBytes: inputBytes(raw),
+                sectionCount: null,
+                recordCount: null,
+                ciphertextBytes: null,
+            }),
+            limitations: Object.freeze([
+                `Lookup-evidence schema ${version} matches its bounded browser-importable structural contract, but this export format has no embedded checksum or signature. Structural validity does not prove that its evidence is accurate, current, or unchanged since collection.`,
+                'Use an integrity-verified investigation manifest and an exact manifest-entry identity check when retained-file byte identity must be established.',
+                'The export may contain raw registry RDAP publication data, normalised WHOIS values, and bounded contact details; review it before sharing.',
+            ]),
+        });
+    }
     if (schema === SAVED_LOOKUP_SCHEMA) {
         if (version !== SAVED_LOOKUP_SCHEMA_VERSION) {
             throw new UnsupportedOfflineArtifactError('This saved Lookup document version is not supported.');
@@ -277,10 +361,10 @@ export async function verifyOfflineArtifact(raw, options = {}) {
             version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
             artifact: Object.freeze({ kind: 'saved_lookup', schema, version }),
             state: 'structure_valid',
-            valid: true,
             checks: Object.freeze({
                 structure: 'verified',
                 contentIntegrity: 'not_checked',
+                contentIntegrityScope: 'not_applicable',
                 authenticatedEncryption: 'not_applicable',
             }),
             summary: Object.freeze({
@@ -296,6 +380,84 @@ export async function verifyOfflineArtifact(raw, options = {}) {
     }
     return verifySignedArtifact(raw, value, schema, version);
 }
+function rawContentDigest(raw) {
+    return `sha256:${createHash('sha256').update(raw, 'utf8').digest('hex')}`;
+}
+function artifactMetadata(value) {
+    const declaredVersion = value.version ?? value.schemaVersion;
+    return Object.freeze({
+        schema: typeof value.schema === 'string' ? value.schema : null,
+        version: Number.isSafeInteger(declaredVersion) && Number(declaredVersion) >= 1 && Number(declaredVersion) <= 1_000
+            ? Number(declaredVersion)
+            : null,
+    });
+}
+async function verifyManifestIdentity(artifactRaw, manifestRaw, entryId) {
+    const manifestReport = await verifyOfflineArtifactCore(manifestRaw);
+    if (manifestReport.artifact.schema !== INVESTIGATION_MANIFEST_SCHEMA
+        || manifestReport.artifact.kind !== 'signed_review_artifact'
+        || manifestReport.state !== 'verified'
+        || manifestReport.checks.contentIntegrity !== 'verified'
+        || manifestReport.checks.contentIntegrityScope !== 'whole_artifact') {
+        throw new TypeError('The selected manifest is not a fully integrity-verified investigation manifest.');
+    }
+    const manifest = parseJson(manifestRaw);
+    const entries = Array.isArray(manifest.artifacts) ? manifest.artifacts : [];
+    const entry = entries.find((candidate) => record(candidate)?.id === entryId);
+    const item = record(entry);
+    if (!item)
+        throw new TypeError('The requested investigation manifest entry was not found.');
+    const artifactValue = parseJson(artifactRaw);
+    const metadata = artifactMetadata(artifactValue);
+    const manifestVersion = artifactVersion(manifest);
+    const canonicalization = manifestVersion === 1 ? SORTED_JSON_V1 : SORTED_JSON_V2;
+    const actualByteLength = inputBytes(artifactRaw);
+    const expectedByteLength = Number(item.byteLength);
+    const checks = Object.freeze({
+        manifestIntegrity: 'verified',
+        byteLength: actualByteLength === expectedByteLength ? 'verified' : 'mismatch',
+        rawContentDigest: rawContentDigest(artifactRaw) === item.contentDigestSha256 ? 'verified' : 'mismatch',
+        canonicalDigest: rawContentDigest(canonicalArtifactJsonFor(artifactValue, canonicalization)) === item.canonicalDigestSha256 ? 'verified' : 'mismatch',
+        schema: metadata.schema === item.schema ? 'verified' : 'mismatch',
+        version: metadata.version === item.version ? 'verified' : 'mismatch',
+    });
+    const exact = checks.byteLength === 'verified'
+        && checks.rawContentDigest === 'verified'
+        && checks.canonicalDigest === 'verified'
+        && checks.schema === 'verified'
+        && checks.version === 'verified';
+    const canonicalOnly = !exact
+        && checks.canonicalDigest === 'verified'
+        && checks.schema === 'verified'
+        && checks.version === 'verified';
+    const state = exact
+        ? 'identity_verified'
+        : canonicalOnly
+            ? 'canonical_match_only'
+            : 'mismatch';
+    return Object.freeze({
+        state,
+        manifest: Object.freeze({ schema: INVESTIGATION_MANIFEST_SCHEMA, version: manifestVersion, entryId }),
+        checks,
+        expectedByteLength,
+        actualByteLength,
+        limitations: Object.freeze([
+            ...(state === 'identity_verified'
+                ? ['The selected artefact matches the manifest entry byte-for-byte and by canonical JSON, schema, and version.']
+                : state === 'canonical_match_only'
+                    ? ['Canonical JSON, schema, and version match, but the retained UTF-8 bytes or byte length differ from the manifest entry. This is not exact retained-file identity.']
+                    : ['One or more manifest identity checks differ. This artefact is not the exact retained file identified by the selected manifest entry.']),
+            'Manifest identity does not establish that the retained observations were accurate, complete, authorised, or remain current.',
+        ]),
+    });
+}
+export async function verifyOfflineArtifact(raw, options = {}) {
+    const report = await verifyOfflineArtifactCore(raw, options);
+    const manifestIdentity = options.manifest
+        ? await verifyManifestIdentity(raw, options.manifest.raw, options.manifest.entryId)
+        : null;
+    return Object.freeze({ ...report, manifestIdentity });
+}
 export function formatOfflineArtifactVerification(report) {
     const lines = [
         'WHOISleuth offline artefact verification',
@@ -303,6 +465,7 @@ export function formatOfflineArtifactVerification(report) {
         `State: ${report.state}`,
         `Structure: ${report.checks.structure}`,
         `Content integrity: ${report.checks.contentIntegrity}`,
+        `Content integrity scope: ${report.checks.contentIntegrityScope}`,
         `Authenticated encryption: ${report.checks.authenticatedEncryption}`,
         `Input bytes: ${report.summary.inputBytes}`,
     ];
@@ -312,6 +475,36 @@ export function formatOfflineArtifactVerification(report) {
         lines.push(`Records: ${report.summary.recordCount}`);
     if (report.summary.ciphertextBytes !== null)
         lines.push(`Ciphertext bytes: ${report.summary.ciphertextBytes}`);
+    if (report.summary.readySectionCount !== undefined && report.summary.readySectionCount !== null) {
+        lines.push(`Import-ready sections: ${report.summary.readySectionCount}`);
+    }
+    if (report.summary.unsupportedSectionCount !== undefined && report.summary.unsupportedSectionCount !== null) {
+        lines.push(`Unsupported sections: ${report.summary.unsupportedSectionCount}`);
+    }
+    if (report.summary.blockedSectionCount !== undefined && report.summary.blockedSectionCount !== null) {
+        lines.push(`Blocked sections: ${report.summary.blockedSectionCount}`);
+    }
+    if (report.summary.skippedRecordCount !== undefined && report.summary.skippedRecordCount !== null) {
+        lines.push(`Skipped records: ${report.summary.skippedRecordCount}`);
+    }
+    if (report.summary.prunedRecordCount !== undefined && report.summary.prunedRecordCount !== null) {
+        lines.push(`Pruned records: ${report.summary.prunedRecordCount}`);
+    }
+    if (report.summary.fullyImportable !== undefined && report.summary.fullyImportable !== null) {
+        lines.push(`Importability: ${report.summary.fullyImportable ? 'complete' : 'partial'}`);
+    }
+    if (report.manifestIdentity) {
+        lines.push(`Manifest identity: ${report.manifestIdentity.state}`);
+        lines.push(`Manifest entry: ${report.manifestIdentity.manifest.entryId}`);
+        lines.push(`Manifest integrity: ${report.manifestIdentity.checks.manifestIntegrity}`);
+        lines.push(`Exact bytes: ${report.manifestIdentity.checks.rawContentDigest}`);
+        lines.push(`Byte length: ${report.manifestIdentity.checks.byteLength}`);
+        lines.push(`Canonical JSON: ${report.manifestIdentity.checks.canonicalDigest}`);
+        lines.push(`Schema identity: ${report.manifestIdentity.checks.schema}`);
+        lines.push(`Version identity: ${report.manifestIdentity.checks.version}`);
+        for (const limitation of report.manifestIdentity.limitations)
+            lines.push(`Manifest limitation: ${limitation}`);
+    }
     for (const limitation of report.limitations)
         lines.push(`Limitation: ${limitation}`);
     return `${lines.join('\n')}\n`;

package/cli/bounded-json.mjs

@@ -0,0 +1 @@
+export { MAX_BOUNDED_JSON_DEPTH, MAX_BOUNDED_JSON_KEYS, MAX_BOUNDED_JSON_VALUES, parseBoundedJsonObject, scanBoundedJson, } from "../lib/bounded-json.mjs";

package/cli/bulk-checkpoint.mjs

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { open } from 'node:fs/promises';
+import { lstat } from 'node:fs/promises';
 import { recordOrNull } from "../lib/bounded-contract-normalizers.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 import { boundedCliInputError, CliUsageError } from "./errors.mjs";
@@ -143,8 +143,7 @@ async function readCheckpointFile(path) {
 }
 async function checkpointFileExists(path) {
     try {
-        const handle = await open(path, 'r');
-        await handle.close();
+        await lstat(path);
         return true;
     }
     catch (error) {

package/cli/bulk-command-runner.mjs

@@ -1,8 +1,7 @@
-import { createReadStream } from 'node:fs';
 import { classifyQuery } from "../lib/classify.mjs";
 import { runUnifiedLookup } from "../lib/lookup.mjs";
 import { createBulkCheckpointWriter } from "./bulk-checkpoint.mjs";
-import { MAX_BULK_INPUT_BYTES, parseBulkQueries, readTextStreamBounded, runBulkLookups, } from "./bulk.mjs";
+import { MAX_BULK_INPUT_BYTES, parseBulkQueries, runBulkLookups, } from "./bulk.mjs";
 import { formatBulkCsv, formatBulkDomainList, formatBulkQueryList, selectBulkItems } from "./bulk-output.mjs";
 import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
@@ -24,9 +23,7 @@ async function runBulkCommand(args, dependencies, context) {
     try {
         input = dependencies.readBulkInput
             ? await dependencies.readBulkInput(args.source)
-            : await readTextStreamBounded(args.source
-                ? createReadStream(args.source, { highWaterMark: 64 * 1024 })
-                : dependencies.stdin || process.stdin, MAX_BULK_INPUT_BYTES, dependencies.signal);
+            : await context.readInput(args.source, MAX_BULK_INPUT_BYTES, 'Bulk input');
     }
     catch (error) {
         if (error instanceof CliUsageError)