@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/cli/artifact-verify.mjs

@@ -1,24 +1,25 @@
 import { Buffer } from 'node:buffer';
 import { createHash } from 'node:crypto';
-import { parseBoundedJsonObject } from "./bounded-json.mjs";
+import { readEditableCaseExport } from "../packages/cases/case-export-input.mjs";
+import { boundedJsonLimitsForBytes, parseBoundedJsonObject } from "./bounded-json.mjs";
 import { validateInvestigationCapsuleStructure, validateLookupEvidenceArtifactStructure, validateOfflineArtifactStructure, validateSignedDigestArtifactStructure, } from "./offline-artifact-validation.mjs";
 import { verifyCaseResponsePacketIntegrity, } from "../packages/cases/case-response-packet.mjs";
 import { CASE_PORTABILITY_VERIFIER_DISPATCH, CASE_RESPONSE_PACKET_VERSION, CASE_RESPONSE_PACKET_SCHEMA, CLI_CASE_PACK_VERSION, CLI_CASE_PACK_SCHEMA, } from "../packages/contracts/case-portability.mjs";
 import { ACQUISITION_DECISION_PACKET_SCHEMA, BULK_DOMAIN_COMPARISON_SCHEMA, BULK_MAIL_EXPOSURE_SCHEMA, BULK_REVIEW_MANIFEST_SCHEMA, LOOKUP_CLAIM_PASSPORT_SCHEMA, LOOKUP_CLAIM_PASSPORT_VERSION, SUPPORTED_ACQUISITION_DECISION_PACKET_VERSIONS, SUPPORTED_BULK_DOMAIN_COMPARISON_EXPORT_VERSIONS, SUPPORTED_BULK_MAIL_EXPOSURE_EXPORT_VERSIONS, SUPPORTED_BULK_REVIEW_MANIFEST_VERSIONS, } from "../packages/contracts/investigation-portability.mjs";
-import { decryptWorkspaceArchive, inspectEncryptedWorkspaceArchive, isEncryptedWorkspaceArchive, } from "../packages/workspace/workspace-archive-crypto.mjs";
-import { WORKSPACE_ARCHIVE_SCHEMA, previewWorkspaceArchive, readWorkspaceArchive, } from "../packages/workspace/workspace-archive.mjs";
+import { decryptWorkspaceArchiveWithMetadata, inspectEncryptedWorkspaceArchive, isEncryptedWorkspaceArchive, MAX_ENCRYPTED_WORKSPACE_ARCHIVE_BYTES, } from "../packages/workspace/workspace-archive-crypto.mjs";
+import { WORKSPACE_ARCHIVE_SCHEMA, prepareWorkspaceArchive, readWorkspaceArchive, } from "../packages/workspace/workspace-archive.mjs";
 import { canonicalArtifactJsonFor, resolveArtifactCanonicalization, sha256ArtifactDigestFor, SORTED_JSON_V2, } from "../packages/evidence/artifact-integrity.mjs";
 import { SAVED_LOOKUP_SCHEMA, SUPPORTED_SAVED_LOOKUP_SCHEMA_VERSIONS, parseCliLookupDocument, } from "./saved-lookup.mjs";
 import { DOMAIN_CONTROL_MANIFEST_SCHEMA, verifyDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
-import { DOMAIN_CONTROL_MANIFEST_CANONICALIZATION_ROUTES, } from "../packages/contracts/domain-control-manifest.mjs";
-import { DOMAIN_CHANGE_PACKET_SCHEMA, DOMAIN_CHANGE_PACKET_VERSION, } from "../lib/domain-change-packet.mjs";
+import { DOMAIN_CONTROL_MANIFEST_CANONICALIZATION_ROUTES, MAX_DOMAIN_CONTROL_MANIFEST_BYTES, } from "../packages/contracts/domain-control-manifest.mjs";
+import { DOMAIN_CHANGE_PACKET_SCHEMA, SUPPORTED_DOMAIN_CHANGE_PACKET_VERSIONS, } from "../lib/domain-change-packet.mjs";
 import { INVESTIGATION_CAPSULE_SCHEMA, SUPPORTED_INVESTIGATION_CAPSULE_VERSIONS, verifyInvestigationCapsule, } from "../packages/investigation/investigation-capsule.mjs";
-import { INVESTIGATION_MANIFEST_SCHEMA, INVESTIGATION_MANIFEST_VERSION, } from "./investigation-manifest.mjs";
+import { INVESTIGATION_MANIFEST_SCHEMA, SUPPORTED_INVESTIGATION_MANIFEST_VERSIONS, } from "./investigation-manifest.mjs";
 import { 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 = 3;
-export const MAX_OFFLINE_ARTIFACT_BYTES = 15 * 1024 * 1024;
+export const OFFLINE_ARTIFACT_VERIFICATION_VERSION = 4;
+export const MAX_OFFLINE_ARTIFACT_BYTES = Math.max(MAX_DOMAIN_CONTROL_MANIFEST_BYTES, MAX_ENCRYPTED_WORKSPACE_ARCHIVE_BYTES);
 export const MAX_OFFLINE_PASSPHRASE_FILE_BYTES = 1024;
 export class UnsupportedOfflineArtifactError extends TypeError {
     code = 'unsupported_artifact';
@@ -41,8 +42,8 @@ const SIGNED_ARTIFACT_ROUTES = Object.freeze({
     [BULK_MAIL_EXPOSURE_SCHEMA]: currentCanonicalizationRoutes(SUPPORTED_BULK_MAIL_EXPOSURE_EXPORT_VERSIONS),
     [BULK_REVIEW_MANIFEST_SCHEMA]: currentCanonicalizationRoutes(SUPPORTED_BULK_REVIEW_MANIFEST_VERSIONS),
     [DOMAIN_CONTROL_MANIFEST_SCHEMA]: DOMAIN_CONTROL_MANIFEST_CANONICALIZATION_ROUTES,
-    [DOMAIN_CHANGE_PACKET_SCHEMA]: currentCanonicalizationRoutes([DOMAIN_CHANGE_PACKET_VERSION]),
-    [INVESTIGATION_MANIFEST_SCHEMA]: currentCanonicalizationRoutes([INVESTIGATION_MANIFEST_VERSION]),
+    [DOMAIN_CHANGE_PACKET_SCHEMA]: currentCanonicalizationRoutes(SUPPORTED_DOMAIN_CHANGE_PACKET_VERSIONS),
+    [INVESTIGATION_MANIFEST_SCHEMA]: currentCanonicalizationRoutes(SUPPORTED_INVESTIGATION_MANIFEST_VERSIONS),
 });
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
@@ -83,8 +84,16 @@ function rejectUnsupportedCasePortabilityVersion(label, version, currentVersion)
     }
     throw new UnsupportedOfflineArtifactError(`This ${label} version is malformed or unsupported; no data was changed.`);
 }
-function parseJson(raw) {
-    return parseBoundedJsonObject(raw, { maximumBytes: MAX_OFFLINE_ARTIFACT_BYTES });
+export function parseOfflineArtifactJson(raw) {
+    const value = parseBoundedJsonObject(raw, {
+        maximumBytes: MAX_OFFLINE_ARTIFACT_BYTES,
+        limits: boundedJsonLimitsForBytes(MAX_OFFLINE_ARTIFACT_BYTES),
+    });
+    if (value.schema !== WORKSPACE_ARCHIVE_SCHEMA && !isEncryptedWorkspaceArchive(value)
+        && Buffer.byteLength(raw, 'utf8') > MAX_DOMAIN_CONTROL_MANIFEST_BYTES) {
+        throw new TypeError(`Non-workspace artefacts are limited to ${MAX_DOMAIN_CONTROL_MANIFEST_BYTES} bytes.`);
+    }
+    return value;
 }
 export function hasVerifiedArtifactStructure(report) {
     return report.checks.structure === 'verified';
@@ -92,6 +101,7 @@ export function hasVerifiedArtifactStructure(report) {
 export function hasVerifiedApplicableIntegrity(report) {
     return report.checks.contentIntegrity === 'verified'
         && (report.checks.contentIntegrityScope === 'whole_artifact'
+            || report.checks.contentIntegrityScope === 'manifest_and_files'
             || report.checks.contentIntegrityScope === 'embedded_projections');
 }
 export function hasVerifiedWholeArtifactIntegrity(report) {
@@ -108,6 +118,9 @@ export function offlineArtifactSatisfiesAssurance(report, requirement) {
     return hasVerifiedWholeArtifactIntegrity(report);
 }
 export function isCompleteOfflineArtifactVerification(report) {
+    if (report.artifact.kind === 'bagit')
+        return report.state === 'integrity_valid' && report.bagit?.state === 'valid'
+            && report.checks.structure === 'verified' && report.checks.contentIntegrity === 'verified';
     return (report.state === 'verified' || report.state === 'structure_valid')
         && (report.manifestIdentity === null || report.manifestIdentity.state === 'identity_verified');
 }
@@ -124,8 +137,7 @@ function artifactVersion(value) {
 function inputBytes(raw) {
     return Buffer.byteLength(raw, 'utf8');
 }
-async function archiveReport(raw, source, archive, encrypted, ciphertextBytes) {
-    const preview = await previewWorkspaceArchive(source, {});
+function archiveReport(raw, archive, preview, encrypted, ciphertextBytes) {
     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;
@@ -172,6 +184,24 @@ async function archiveReport(raw, source, archive, encrypted, ciphertextBytes) {
         ]),
     });
 }
+async function verifyWorkspaceArchiveValue(raw, value, passphrase) {
+    const encrypted = isEncryptedWorkspaceArchive(value);
+    if (encrypted && !passphrase) {
+        throw new TypeError('Encrypted archive inspection requires a separate passphrase file.');
+    }
+    if (!encrypted)
+        artifactVersion(value);
+    const decrypted = encrypted ? await decryptWorkspaceArchiveWithMetadata(value, passphrase) : null;
+    const source = decrypted ? decrypted.archive : value;
+    const prepared = await prepareWorkspaceArchive(source);
+    const archive = prepared.read();
+    const report = archiveReport(raw, archive, prepared.preview({}), encrypted, decrypted?.ciphertextBytes ?? null);
+    return { archive, report, encrypted };
+}
+/** Verify an archive once and retain its sections for bounded offline inspection. */
+export async function verifyOfflineWorkspaceArchive(raw, options = {}) {
+    return verifyWorkspaceArchiveValue(raw, parseOfflineArtifactJson(raw), options.passphrase);
+}
 async function verifySignedArtifact(raw, value, schema, version) {
     const routes = SIGNED_ARTIFACT_ROUTES[schema] ?? [];
     if (!routes.some((route) => route.version === version)) {
@@ -215,7 +245,7 @@ async function verifySignedArtifact(raw, value, schema, version) {
     });
 }
 async function verifyOfflineArtifactCore(raw, options = {}) {
-    const value = parseJson(raw);
+    const value = parseOfflineArtifactJson(raw);
     const casePortabilityVerifier = selectCasePortabilityVerifier(value);
     if (casePortabilityVerifier?.id === 'cli-case-pack') {
         const casePackVersion = casePortabilityVersion(casePortabilityVerifier, value);
@@ -249,9 +279,24 @@ async function verifyOfflineArtifactCore(raw, options = {}) {
             ]),
         });
     }
+    if (value.schema === undefined && Array.isArray(value.cases)) {
+        const cases = readEditableCaseExport(raw);
+        return Object.freeze({
+            schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA, version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+            artifact: Object.freeze({ kind: 'case_export', schema: null, version: artifactVersion(value) }),
+            state: 'structure_valid',
+            checks: Object.freeze({ structure: 'verified', contentIntegrity: 'not_checked', contentIntegrityScope: 'not_applicable', authenticatedEncryption: 'not_applicable' }),
+            summary: Object.freeze({ inputBytes: inputBytes(raw), sectionCount: 1, recordCount: cases.length, ciphertextBytes: null }),
+            limitations: Object.freeze([
+                'The ordinary Case export matches its exact supported structure without repairing or removing retained records. It has no embedded checksum or signature.',
+                'Original-file references do not include original bytes. Verify a selected evidence package to check which references have matching bytes.',
+                'The Case includes private analyst content. Structural validity does not authenticate its author or establish factual accuracy, currentness or response authority.',
+            ]),
+        });
+    }
     if (isEncryptedWorkspaceArchive(value)) {
-        const inspected = inspectEncryptedWorkspaceArchive(value);
         if (!options.passphrase) {
+            const inspected = inspectEncryptedWorkspaceArchive(value);
             return Object.freeze({
                 schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA,
                 version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
@@ -279,14 +324,12 @@ async function verifyOfflineArtifactCore(raw, options = {}) {
                 ]),
             });
         }
-        const decrypted = await decryptWorkspaceArchive(value, options.passphrase);
-        const archive = await readWorkspaceArchive(decrypted);
-        return archiveReport(raw, decrypted, archive, true, inspected.ciphertextBytes);
+        return (await verifyWorkspaceArchiveValue(raw, value, options.passphrase)).report;
     }
     const schema = typeof value.schema === 'string' ? value.schema : '';
     const version = artifactVersion(value);
     if (schema === WORKSPACE_ARCHIVE_SCHEMA) {
-        return archiveReport(raw, value, await readWorkspaceArchive(value), false, null);
+        return (await verifyWorkspaceArchiveValue(raw, value)).report;
     }
     if (casePortabilityVerifier?.id === 'case-response-packet') {
         if (!supportsCasePortabilityVersion(casePortabilityVerifier, version)) {
@@ -432,13 +475,13 @@ async function verifyManifestIdentity(artifactRaw, manifestRaw, entryId) {
         || manifestReport.checks.contentIntegrityScope !== 'whole_artifact') {
         throw new TypeError('The selected manifest is not a fully integrity-verified investigation manifest.');
     }
-    const manifest = parseJson(manifestRaw);
+    const manifest = parseOfflineArtifactJson(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 artifactValue = parseOfflineArtifactJson(artifactRaw);
     const metadata = artifactMetadata(artifactValue);
     const actualByteLength = inputBytes(artifactRaw);
     const expectedByteLength = Number(item.byteLength);
@@ -466,7 +509,7 @@ async function verifyManifestIdentity(artifactRaw, manifestRaw, entryId) {
             : 'mismatch';
     return Object.freeze({
         state,
-        manifest: Object.freeze({ schema: INVESTIGATION_MANIFEST_SCHEMA, version: INVESTIGATION_MANIFEST_VERSION, entryId }),
+        manifest: Object.freeze({ schema: INVESTIGATION_MANIFEST_SCHEMA, version: manifestReport.artifact.version, entryId }),
         checks,
         expectedByteLength,
         actualByteLength,
@@ -490,8 +533,9 @@ export async function verifyOfflineArtifact(raw, options = {}) {
 export function formatOfflineArtifactVerification(report) {
     const lines = [
         'WHOISleuth offline artefact verification',
-        `Artifact: ${report.artifact.kind} · ${report.artifact.schema} v${report.artifact.version}`,
+        `Artifact: ${report.artifact.kind} · ${report.artifact.schema ?? 'no schema identifier'} v${report.artifact.version}`,
         `State: ${report.state}`,
+        'Automation: use --strict-exit for exit 4 on incomplete verification; default exit 0 means the report was produced.',
         `Structure: ${report.checks.structure}`,
         `Content integrity: ${report.checks.contentIntegrity}`,
         `Content integrity scope: ${report.checks.contentIntegrityScope}`,
@@ -534,6 +578,28 @@ export function formatOfflineArtifactVerification(report) {
         for (const limitation of report.manifestIdentity.limitations)
             lines.push(`Manifest limitation: ${limitation}`);
     }
+    if (report.bagit) {
+        const bag = report.bagit;
+        lines.push(`BagIt: ${bag.state}`, `Payload: ${bag.entries.length} files; ${bag.payloadBytes} present bytes`, `Tag checksums: ${bag.verifiedTagFiles} of ${bag.tagFiles} tag files checked`, `Fetch declarations: ${bag.fetchEntries}; ${bag.fetchMissing} files missing; no requests made`, `Unsupported manifests: ${bag.unsupportedManifests}`);
+        for (const entry of bag.entries)
+            lines.push(`${entry.id}: ${entry.state} · ${entry.byteLength ?? 'unknown'} bytes`);
+        for (const issue of bag.issues)
+            lines.push(`BagIt issue: ${issue}`);
+    }
+    if (report.package) {
+        lines.push(`Package bytes: ${report.package.digestSha256}`, 'Storage: unchanged; inspection only', 'Audience: private; review selected file contents before sharing', 'Signature trust: not checked', 'Trusted timestamp: not checked', 'Factual accuracy: not established');
+        for (const entry of report.package.entries)
+            lines.push(`${entry.id}: ${entry.state} · ${entry.byteLength} bytes · ${entry.mediaType}${entry.issue ? ` · ${entry.issue}` : ''}`);
+        for (const link of report.package.links)
+            lines.push(`Source link ${link.capsuleEntryId}: ${link.state}${link.sourceEntryId ? ` (${link.sourceEntryId})` : ''}`);
+        for (const capture of report.package.captureManifests) {
+            lines.push(`Capture manifest ${capture.entryId}: ${capture.state}`);
+            for (const artifact of capture.artifacts)
+                lines.push(`Capture ${artifact.capture} ${artifact.kind}: ${artifact.state}${artifact.matchingIds.length ? ` (${artifact.matchingIds.join(', ')})` : ''}`);
+        }
+        for (const item of report.package.caseFiles)
+            lines.push(`Case files ${item.entryId} (${item.caseCount} Case${item.caseCount === 1 ? '' : 's'}): ${item.matched} of ${item.references} references matched; ${item.missing} missing`);
+    }
     for (const limitation of report.limitations)
         lines.push(`Limitation: ${limitation}`);
     return `${lines.join('\n')}\n`;

package/cli/assurance-command-runner.mjs

@@ -1,4 +1,9 @@
 import { Buffer } from 'node:buffer';
+import { readBoundedRegularFile } from "../lib/bounded-file.mjs";
+import { buildInvestigationPackage } from "../packages/investigation/investigation-package.mjs";
+import { encryptInvestigationPackage } from "../packages/investigation/investigation-package-crypto.mjs";
+import { writeInvestigationFolder, writePreparedEvidenceFolder } from "./investigation-folder.mjs";
+import { buildInvestigationBagIt, prepareInvestigationBagIt } from "../packages/investigation/investigation-bagit.mjs";
 import { scanBoundedJson } from "../lib/bounded-json.mjs";
 import { MAX_ASSURANCE_INPUT_BYTES, buildDomainAssurance, formatDomainAssurance, } from "../lib/domain-assurance.mjs";
 import { MAX_DOMAIN_CHANGE_PACKET_INPUT_BYTES, buildDomainChangePacket, formatDomainChangePacket, } from "../lib/domain-change-packet.mjs";
@@ -12,7 +17,7 @@ import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { MAX_EXTERNAL_OBSERVATION_MAPPING_BYTES, formatExternalObservationMapping, mapExternalObservations, } from "./external-observation-mapping.mjs";
 import { formatJsonDocument } from "./formatters/json.mjs";
-import { MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, buildInvestigationManifest, formatInvestigationManifest, } from "./investigation-manifest.mjs";
+import { MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, buildInvestigationManifest, formatInvestigationManifest, investigationFileMediaType, } from "./investigation-manifest.mjs";
 import { buildOpenAssetModelBridge, formatOpenAssetModelBridge, } from "./open-asset-model-bridge.mjs";
 import { ASSURANCE_INLINE_COMMANDS } from "./inline-command-families.mjs";
 import { MAX_SHARING_REVIEW_BYTES, buildSharingReview, formatSharingReview, } from "./sharing-review.mjs";
@@ -23,6 +28,15 @@ async function runManifestCommand(args, dependencies, context) {
     let totalBytes = 0;
     try {
         for (const source of args.sources) {
+            if (args.package || args.folder) {
+                const content = dependencies.readBinaryArtifactInput ? await dependencies.readBinaryArtifactInput(source)
+                    : await readBoundedRegularFile(source, { maximumBytes: MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, minimumBytes: 1, label: 'Package artefact input', ...(dependencies.signal ? { signal: dependencies.signal } : {}) });
+                if (content.byteLength > MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES - totalBytes)
+                    throw new CliUsageError('Package artefacts exceed the combined byte limit.');
+                totalBytes += content.byteLength;
+                artifacts.push({ content, mediaType: investigationFileMediaType(source) });
+                continue;
+            }
             const content = dependencies.readDiffInput
                 ? await dependencies.readDiffInput(source)
                 : await context.readInput(source, MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, 'Manifest artefact input');
@@ -40,11 +54,32 @@ async function runManifestCommand(args, dependencies, context) {
     }
     let document;
     try {
-        document = await buildInvestigationManifest({
+        if (args.package) {
+            const built = await (args.bagit ? buildInvestigationBagIt : buildInvestigationPackage)({ workflow: args.workflow, configurationDigestSha256: args.configurationDigestSha256, artifacts }, context.now(), context.packageVersion);
+            dependencies.signal?.throwIfAborted();
+            if (!context.writeBinaryOutput)
+                throw new CliUsageError('Package output requires an explicit file destination.');
+            const output = args.passphraseSource
+                ? await encryptInvestigationPackage(built.bytes, await context.readPassphraseSource(args.passphraseSource))
+                : built.bytes;
+            dependencies.signal?.throwIfAborted();
+            context.writeBinaryOutput(output);
+            return EXIT_CODES.SUCCESS;
+        }
+        const input = {
             workflow: args.workflow,
             configurationDigestSha256: args.configurationDigestSha256,
             artifacts,
-        }, context.now(), context.packageVersion);
+        };
+        if (args.bagit && args.folder) {
+            const prepared = await prepareInvestigationBagIt(input, context.now(), context.packageVersion);
+            await writePreparedEvidenceFolder(args.folder, prepared.files, 'data', 'tagmanifest-sha512.txt', dependencies.signal);
+            document = prepared.manifest;
+        }
+        else
+            document = args.folder
+                ? await writeInvestigationFolder(args.folder, input, context.now(), context.packageVersion, dependencies.signal)
+                : await buildInvestigationManifest(input, context.now(), context.packageVersion);
     }
     catch (error) {
         throw new CliUsageError(boundedCliErrorMessage(error, 'Investigation manifest input is invalid'));
@@ -52,7 +87,7 @@ async function runManifestCommand(args, dependencies, context) {
     if (!args.quiet) {
         context.writeStdout(args.output === 'json'
             ? formatJsonDocument(document)
-            : context.terminal(formatInvestigationManifest(document), args.color));
+            : context.terminal(`${args.folder ? 'Created a new private evidence folder.\n' : ''}${formatInvestigationManifest(document)}`, args.color));
     }
     return EXIT_CODES.SUCCESS;
 }

package/cli/bagit-folder.mjs

@@ -0,0 +1,57 @@
+import { lstat, opendir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readBoundedRegularFileWithin } from "../lib/bounded-file.mjs";
+import { assertBagItSelection, bagItPath, bagItEntryMaximum, MAX_BAGIT_ENTRIES } from "../packages/interchange/bagit.mjs";
+import { selectedEvidenceDirectory, evidenceDirectoryIdentity } from "./investigation-folder.mjs";
+/** Bounded recursive enumeration; no symbolic links, special files or writes. */
+export async function readBagItFolder(value, signal) {
+    const selected = selectedEvidenceDirectory(value);
+    const identity = await evidenceDirectoryIdentity(selected), root = await realpath(selected);
+    const directories = new Map([['', identity]]);
+    const entries = [];
+    const visit = async (relative) => {
+        signal?.throwIfAborted();
+        const path = join(root, relative);
+        if (await realpath(path) !== path)
+            throw new TypeError('BagIt directories must not contain symbolic links.');
+        for await (const item of await opendir(path)) {
+            signal?.throwIfAborted();
+            if (entries.length >= MAX_BAGIT_ENTRIES)
+                throw new TypeError('BagIt exceeds its entry limit.');
+            const name = `${relative ? `${relative}/` : ''}${item.name}`;
+            bagItPath(item.isDirectory() ? `${name}/` : name);
+            const stat = await lstat(join(root, name));
+            if (item.isDirectory() && stat.isDirectory() && !stat.isSymbolicLink()) {
+                directories.set(name, await evidenceDirectoryIdentity(join(root, name)));
+                entries.push({ path: `${name}/`, byteLength: 0 });
+                await visit(name);
+            }
+            else if (item.isFile() && stat.isFile() && !stat.isSymbolicLink()) {
+                if (stat.size > bagItEntryMaximum(name))
+                    throw new TypeError('BagIt entry exceeds its byte limit.');
+                entries.push({ path: name, byteLength: stat.size });
+            }
+            else
+                throw new TypeError('BagIt entries must be ordinary files and directories, not symbolic links or special files.');
+        }
+    };
+    await visit('');
+    assertBagItSelection(entries);
+    const files = new Map();
+    for (const entry of entries) {
+        signal?.throwIfAborted();
+        files.set(entry.path, entry.path.endsWith('/') ? new Uint8Array() : await readBoundedRegularFileWithin(root, entry.path, {
+            maximumBytes: bagItEntryMaximum(entry.path), minimumBytes: 0, expectedBytes: entry.byteLength,
+            label: 'BagIt file', ...(signal ? { signal } : {}),
+        }));
+    }
+    for (const [path, before] of directories) {
+        signal?.throwIfAborted();
+        const currentPath = path ? join(root, path) : selected;
+        const after = await evidenceDirectoryIdentity(currentPath);
+        if (await realpath(currentPath) !== join(root, path) || before.device !== after.device || before.inode !== after.inode
+            || before.modified !== after.modified || before.changed !== after.changed)
+            throw new TypeError('BagIt folder changed while it was read.');
+    }
+    return files;
+}

package/cli/bagit-review.mjs

@@ -0,0 +1,23 @@
+import { inspectBagItEntries, readBagItZip } from "../packages/interchange/bagit.mjs";
+import { OFFLINE_ARTIFACT_VERIFICATION_SCHEMA, OFFLINE_ARTIFACT_VERIFICATION_VERSION } from "./artifact-verify.mjs";
+export async function verifyOfflineBagIt(input) {
+    const files = input instanceof Uint8Array ? readBagItZip(input) : input;
+    const zipBytes = input instanceof Uint8Array ? input.byteLength : null;
+    const { review, inputBytes } = await inspectBagItEntries(files);
+    return {
+        schema: OFFLINE_ARTIFACT_VERIFICATION_SCHEMA, version: OFFLINE_ARTIFACT_VERIFICATION_VERSION,
+        artifact: { kind: 'bagit', schema: null, version: '1.0' },
+        state: review.state === 'valid' ? 'integrity_valid' : 'partial',
+        checks: { structure: review.complete ? 'verified' : 'failed',
+            contentIntegrity: review.state === 'valid' ? 'verified' : review.state === 'invalid' ? 'failed' : 'not_checked',
+            contentIntegrityScope: 'manifest_and_files', authenticatedEncryption: 'not_applicable' },
+        summary: { inputBytes: zipBytes ?? inputBytes,
+            sectionCount: null, recordCount: review.entries.length, ciphertextBytes: null },
+        manifestIdentity: null, bagit: review,
+        limitations: [
+            'BagIt verifies declared file checksums, not payload schemas, factual accuracy, source identity, signatures or trusted timestamps.',
+            'Tag files without a checksum are not integrity-checked. No file is imported, executed or fetched; fetch.txt locations and original paths are omitted from this report.',
+            'This bounded reader supports BagIt 1.0, UTF-8 text tags, SHA-256 and SHA-512, portable relative paths and the selected-file byte limits. Other encodings, algorithms and unsafe or platform-ambiguous paths are not silently accepted.',
+        ],
+    };
+}

package/cli/bounded-json.mjs

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

package/cli/bulk-checkpoint.mjs

@@ -54,6 +54,24 @@ function normalizeCompactResult(value) {
         return null;
     return result;
 }
+function normalizeCollectionContext(value) {
+    if (value === undefined)
+        return undefined;
+    const context = recordOrNull(value);
+    if (!context || Object.keys(context).some((key) => !['dnsResolver', 'resolverServers'].includes(key)))
+        return null;
+    const resolverServers = context.resolverServers;
+    if (!Array.isArray(resolverServers) || resolverServers.length > 3
+        || resolverServers.some((server) => typeof server !== 'string' || !server || server.length > 45))
+        return null;
+    if (context.dnsResolver === 'system_default' && resolverServers.length === 0) {
+        return { dnsResolver: 'system_default', resolverServers: [] };
+    }
+    if (context.dnsResolver === 'analyst_selected' && resolverServers.length > 0) {
+        return { dnsResolver: 'analyst_selected', resolverServers: [...resolverServers] };
+    }
+    return null;
+}
 function normalizeCheckpointResult(value, queries, classifyQuery) {
     const item = recordOrNull(value);
     const index = item?.index;
@@ -67,10 +85,16 @@ function normalizeCheckpointResult(value, queries, classifyQuery) {
         : normalizedTimestamp(item.observedAt) ?? undefined;
     if (observedAt === undefined)
         return null;
+    const collectionContext = normalizeCollectionContext(item.collectionContext);
+    if (collectionContext === null)
+        return null;
     if (item.ok === false) {
         if (typeof item.error !== 'string' || !item.error || item.error.length > 300)
             return null;
-        return { index: Number(index), query, ok: false, error: item.error, observedAt };
+        return {
+            index: Number(index), query, ok: false, error: item.error, observedAt,
+            ...(collectionContext ? { collectionContext } : {}),
+        };
     }
     const result = normalizeCompactResult(item.result);
     if (item.ok !== true || !result)
@@ -79,7 +103,10 @@ function normalizeCheckpointResult(value, queries, classifyQuery) {
     const storedClassified = recordOrNull(item.classified);
     if (storedClassified?.type !== classified.type || storedClassified.value !== classified.value)
         return null;
-    return { index: Number(index), query, ok: true, classified, result, observedAt };
+    return {
+        index: Number(index), query, ok: true, classified, result, observedAt,
+        ...(collectionContext ? { collectionContext } : {}),
+    };
 }
 function parseBulkCheckpoint(text, options) {
     if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > MAX_BULK_CHECKPOINT_BYTES) {
@@ -214,8 +241,10 @@ async function createBulkCheckpointWriter(options) {
         }
     }
     function scheduleWrite() {
+        if (writeFailure)
+            return;
         dirty = true;
-        if (activeWrite || writeFailure)
+        if (activeWrite)
             return;
         const pending = drainWrites();
         activeWrite = pending;
@@ -250,6 +279,8 @@ async function createBulkCheckpointWriter(options) {
         },
         async flush() {
             while (activeWrite || dirty) {
+                if (writeFailure && !activeWrite)
+                    break;
                 if (!activeWrite)
                     scheduleWrite();
                 if (activeWrite)

package/cli/bulk-command-runner.mjs

@@ -113,6 +113,8 @@ async function runBulkCommand(args, dependencies, context) {
             context.writeStdout(formatJsonLines(selectedItems, metadata));
         else if (args.output === 'csv')
             context.writeStdout(formatBulkCsv(selectedItems));
+        else if (args.output === 'csv_metadata')
+            context.writeStdout(formatBulkCsv(selectedItems, selectedDocument));
         else if (args.output === 'domains')
             context.writeStdout(formatBulkDomainList(selectedItems));
         else if (args.output === 'queries')

package/cli/bulk-output.mjs

@@ -1,6 +1,25 @@
 import { cliCsvCell } from "./csv.mjs";
+import { lookupDiagnosticStates } from "../lib/lookup-diagnostics.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 const REGISTERED_STATES = new Set(['expiring', 'for_sale', 'registered']);
 const MAX_DNS_VALUES_PER_TYPE = 100;
+const BULK_CSV_METADATA_COLUMNS = Object.freeze([
+    'source_schema', 'source_version', 'observed_at', 'report_generated_at',
+    'collection_origin', 'scan_mode', 'diagnostics_version', 'source_health',
+]);
+function bulkCsvMetadataValues(item, metadata) {
+    const diagnostics = record(item.diagnostics);
+    return [
+        metadata.schema,
+        metadata.version,
+        normalizeExplicitIsoTimestamp(item.observedAt) ?? 'unknown',
+        normalizeExplicitIsoTimestamp(metadata.generatedAt) ?? 'unknown',
+        item.collectionOrigin === 'current_run' || item.collectionOrigin === 'resumed_checkpoint' ? item.collectionOrigin : 'unknown',
+        metadata.mode,
+        Number.isSafeInteger(diagnostics.version) && Number(diagnostics.version) > 0 ? diagnostics.version : 'unknown',
+        JSON.stringify(lookupDiagnosticStates(item.diagnostics)),
+    ];
+}
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -78,12 +97,18 @@ function bulkDnsSummary(item) {
 function booleanCell(value) {
     return value === null ? 'unknown' : value ? 'observed' : 'not_observed';
 }
-function formatBulkCsv(items) {
+function formatBulkCsv(items, metadata) {
+    if (metadata && metadata.results.length !== items.length)
+        throw new TypeError('CSV metadata does not match the selected result count.');
     const header = [
         'query', 'domain', 'outcome', 'availability', 'confidence', 'dns_status',
         'a', 'aaaa', 'ns', 'mx', 'null_mx', 'spf', 'dmarc', 'error',
+        ...(metadata ? BULK_CSV_METADATA_COLUMNS : []),
     ];
-    const rows = items.map((item) => {
+    const rows = items.map((item, index) => {
+        const retained = metadata?.results[index];
+        if (metadata && (!retained || retained.index !== item.index || retained.query !== item.query))
+            throw new TypeError('CSV metadata does not match the selected result identity.');
         const availability = item.ok ? record(record(item.result).availability) : {};
         const dns = bulkDnsSummary(item);
         return [
@@ -101,6 +126,7 @@ function formatBulkCsv(items) {
             booleanCell(dns.hasSpf),
             booleanCell(dns.hasDmarc),
             item.ok ? '' : item.error,
+            ...(metadata && retained ? bulkCsvMetadataValues(retained, metadata) : []),
         ].map(cliCsvCell).join(',');
     });
     return `${[header.join(','), ...rows].join('\n')}\n`;
@@ -114,4 +140,4 @@ function formatBulkDomainList(items) {
 function formatBulkQueryList(items) {
     return items.length ? `${items.map((item) => item.query).join('\n')}\n` : '';
 }
-export { REGISTERED_STATES, availabilityState, bulkDnsSummary, formatBulkCsv, formatBulkDomainList, formatBulkQueryList, selectBulkItems, };
+export { REGISTERED_STATES, BULK_CSV_METADATA_COLUMNS, availabilityState, bulkDnsSummary, bulkCsvMetadataValues, formatBulkCsv, formatBulkDomainList, formatBulkQueryList, selectBulkItems, };