@slicedearth/whoisleuth-cli 2.3.0 → 2.4.0

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-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, };

package/cli/case-command.mjs

@@ -0,0 +1,195 @@
+import { createHash } from 'node:crypto';
+import { boundedJsonLimitsForBytes, parseBoundedJsonObject } from "../lib/bounded-json.mjs";
+import { canonicalArtifactJsonV2 } from "../packages/evidence/artifact-integrity.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { MAX_CASE_CHECKPOINT_FACTS, MAX_CASE_OBJECTIVE_LENGTH, MAX_CASE_STORE_BYTES, MAX_EDITABLE_CASE_INPUT_BYTES, MAX_NOTE_LENGTH, MAX_RESPONSE_RATIONALE_LENGTH, MAX_RESPONSE_VALUE_LENGTH } from "../packages/contracts/case-portability.mjs";
+import { readEditableCaseExport } from "../packages/cases/case-export-input.mjs";
+import { createCaseIncident, openOrCreateCase, recordCaseConclusion, recordCaseRecheckOutcome, updateCase } from "../packages/cases/case-record-operations.mjs";
+import { buildCaseExport, serializeCaseStore } from "../packages/cases/case-storage-model.mjs";
+import { appendCaseEvidencePin } from "../packages/cases/case-response-model.mjs";
+import { readCaseRecheckAnswerContext } from "../packages/cases/case-recheck-model.mjs";
+import { dispositionLabel, statusLabel } from "../packages/cases/case-record-decisions.mjs";
+import { normalizeDomain } from "../packages/cases/case-record-core.mjs";
+import { safeTerminalValue } from "./formatters/terminal.mjs";
+import { CliUsageError } from "./errors.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+function fields(input, allowed, label) {
+    if (Object.keys(input).some(key => !allowed.includes(key)))
+        throw new CliUsageError(`${label} contains an unsupported field.`);
+}
+function prose(input, maximum, label) {
+    if (typeof input !== 'string' || !input.trim() || input.trim().length > maximum
+        || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(input)) {
+        throw new CliUsageError(`${label} must contain 1–${maximum} characters without unsafe control characters.`);
+    }
+    return input.trim();
+}
+function selection(cases, args, required) {
+    const domain = args.domain === null ? null : normalizeDomain(args.domain);
+    if (args.domain !== null && !domain)
+        throw new CliUsageError('Select a valid Case domain.');
+    const selected = cases.filter(record => (!args.caseId || record.id === args.caseId) && (!domain || record.domain === domain));
+    if ((args.caseId || domain || required) && selected.length === 0)
+        throw new CliUsageError('The selected Case is not present in this file.');
+    if (required && selected.length !== 1)
+        throw new CliUsageError('Select exactly one Case with --case-id; no arbitrary Case was chosen.');
+    return selected;
+}
+function pin(input, now) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new CliUsageError('An evidence pin must be a JSON object.');
+    const raw = input;
+    if (Object.hasOwn(raw, 'id') || Object.hasOwn(raw, 'createdAt'))
+        throw new CliUsageError('New pin identity and creation time are allocated by the Case operation.');
+    const normal = appendCaseEvidencePin([], raw, now)[0];
+    // Validate the supplied subset against the domain result, without duplicating
+    // its field inventory or accepting silent truncation/default substitution.
+    for (const [key, value] of Object.entries(raw)) {
+        if (!Object.hasOwn(normal, key) || canonicalArtifactJsonV2(value) !== canonicalArtifactJsonV2(normal[key])) {
+            throw new CliUsageError(`Pin field ${safeTerminalValue(key)} is not canonical or exceeds its bound. Use explicit ISO timestamps and supported values; no pin was saved.`);
+        }
+    }
+    return raw;
+}
+function retainExistingEntries(before, after) {
+    const pairs = [
+        [before.notes, after.notes], [before.evidenceHistory, after.evidenceHistory], [before.evidencePins, after.evidencePins],
+        [before.decisions, after.decisions], [before.actions, after.actions], [before.assertions, after.assertions],
+        [before.manualTrail, after.manualTrail], [before.sightings, after.sightings],
+        [before.observedEffects.reviews, after.observedEffects.reviews], [before.closures.records, after.closures.records],
+        [before.branches ?? [], after.branches ?? []], [before.attachments ?? [], after.attachments ?? []],
+    ];
+    for (const [prior, next] of pairs) {
+        const retained = new Set(next.map(value => canonicalArtifactJsonV2(value)));
+        if (prior.some(value => !retained.has(canonicalArtifactJsonV2(value)))) {
+            throw new CliUsageError('The operation would remove or alter earlier retained evidence. Export a smaller working set or review it in the console; nothing was written.');
+        }
+    }
+}
+function mutate(cases, args, input, note, now) {
+    if (args.operation === 'open') {
+        const title = args.title === null ? undefined : prose(args.title, MAX_CASE_OBJECTIVE_LENGTH, 'Incident title');
+        const result = args.newIncident
+            ? createCaseIncident(cases, { domain: args.domain, title }, now)
+            : openOrCreateCase(cases, { domain: args.domain, ...(title ? { title } : {}) }, now, args.caseId ? { caseId: args.caseId } : {});
+        if (!result.created && title && title !== result.record.title)
+            throw new CliUsageError('The selected Case already exists with another title. Use --new-incident for a separate investigation.');
+        return result.cases;
+    }
+    const current = selection(cases, args, true)[0];
+    let result;
+    if (args.operation === 'note') {
+        result = updateCase(cases, current.id, { note: prose(note, MAX_NOTE_LENGTH, 'Case note') }, now);
+    }
+    else if (args.operation === 'pin') {
+        result = updateCase(cases, current.id, { evidencePin: pin(input, now) }, now);
+    }
+    else if (args.operation === 'assess') {
+        if (!input)
+            throw new CliUsageError('An assessment requires JSON input.');
+        fields(input, ['disposition', 'reviewReasonCode', 'summary', 'rationale', 'evidence'], 'Assessment');
+        if (!Array.isArray(input.evidence) || !input.evidence.length || input.evidence.length > MAX_CASE_CHECKPOINT_FACTS) {
+            throw new CliUsageError(`Select 1–${MAX_CASE_CHECKPOINT_FACTS} evidence facts for the assessment.`);
+        }
+        const evidence = input.evidence.map(value => {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                throw new CliUsageError('Each assessment fact needs a pin and stance.');
+            fields(value, ['pin', 'pinId', 'stance'], 'Assessment evidence');
+            if (!['supports', 'contradicts', 'unresolved'].includes(value.stance))
+                throw new CliUsageError('Use supports, contradicts or unresolved for each evidence stance.');
+            if (Object.hasOwn(value, 'pin') === Object.hasOwn(value, 'pinId'))
+                throw new CliUsageError('Select one new pin or one retained pinId for each assessment fact.');
+            return Object.hasOwn(value, 'pinId') ? { pinId: value.pinId, stance: value.stance } : { pin: pin(value.pin, now), stance: value.stance };
+        });
+        const summary = prose(input.summary, MAX_RESPONSE_VALUE_LENGTH, 'Assessment summary');
+        const rationale = prose(input.rationale, MAX_RESPONSE_RATIONALE_LENGTH, 'Assessment rationale');
+        result = recordCaseConclusion(cases, current.id, { disposition: input.disposition, reviewReasonCode: input.reviewReasonCode, summary, rationale, evidence }, now);
+        if (result.record.decisions.at(-1)?.summary !== summary || result.record.decisions.at(-1)?.rationale !== rationale) {
+            throw new CliUsageError('Assessment text needs canonical single-line values; no assessment was written.');
+        }
+    }
+    else if (args.operation === 'recheck') {
+        if (!input)
+            throw new CliUsageError('A recheck requires JSON input.');
+        fields(input, ['state', 'observedAt', 'completeness', 'comparisonSummary', 'source', 'followUpAt', 'limitations', 'collectionDepth', 'recheck', 'observationHostname'], 'Recheck');
+        const recheck = readCaseRecheckAnswerContext(input.recheck);
+        if (input.state === 'not_reproduced' && !recheck) {
+            throw new CliUsageError('Not reproduced requires a saved recheck question and confirmed comparable conditions. Import the planned Case or record unavailable for a limited observation.');
+        }
+        const summary = prose(input.comparisonSummary, MAX_RESPONSE_VALUE_LENGTH, 'Comparison summary');
+        result = recordCaseRecheckOutcome(cases, current.id, {
+            ...input, state: input.state, observedAt: input.observedAt, completeness: input.completeness,
+            comparisonSummary: summary, source: input.source, ...(recheck ? { recheck } : {}),
+        }, now);
+        const review = result.record.observedEffects.reviews.at(-1);
+        const comparison = result.record.evidencePins.find(value => value.id === review.evidencePinId);
+        const projected = { state: review.state, observedAt: review.observedAt, completeness: review.completeness,
+            comparisonSummary: comparison.value, source: review.source, followUpAt: review.followUpAt,
+            limitations: review.limitations, collectionDepth: comparison.collectionDepth,
+            ...(review.recheck ? { recheck: review.recheck } : {}),
+            ...(comparison.observationHostname ? { observationHostname: comparison.observationHostname } : {}),
+        };
+        for (const [key, value] of Object.entries(input)) {
+            if (canonicalArtifactJsonV2(value) !== canonicalArtifactJsonV2(projected[key]))
+                throw new CliUsageError(`Recheck field ${safeTerminalValue(key)} would be repaired or truncated; nothing was written.`);
+        }
+    }
+    else
+        throw new CliUsageError('Select a supported Case mutation.');
+    retainExistingEntries(current, result.record);
+    return result.cases;
+}
+function formatCases(cases, digest) {
+    const lines = ['Local Case review', `File digest  ${digest}`, `Cases        ${cases.length}`, ''];
+    for (const record of cases) {
+        lines.push(`Case ${safeTerminalValue(record.id)} · ${safeTerminalValue(record.title || record.domain)}`, `Domain       ${safeTerminalValue(record.domain)}`, `Status       ${statusLabel(record.status)}`, `Disposition  ${dispositionLabel(record.disposition)} (analyst assessment)`, `Updated      ${record.updatedAt}`);
+        for (const note of record.notes)
+            lines.push(`Note ${note.createdAt}`, safeTerminalValue(note.body, '—', MAX_NOTE_LENGTH));
+        for (const pin of record.evidencePins)
+            lines.push(`Pin ${safeTerminalValue(pin.id)} · ${safeTerminalValue(pin.label)}`, safeTerminalValue(pin.value, '—', MAX_RESPONSE_VALUE_LENGTH), `  Source ${safeTerminalValue(pin.source)} · ${safeTerminalValue(pin.observedAt, 'time unavailable')} · ${pin.completeness}`);
+        for (const decision of record.decisions)
+            lines.push(`Assessment ${decision.createdAt}`, safeTerminalValue(decision.summary, '—', MAX_RESPONSE_VALUE_LENGTH), safeTerminalValue(decision.rationale, '—', MAX_RESPONSE_RATIONALE_LENGTH));
+        for (const review of record.observedEffects.reviews)
+            lines.push(`Recheck ${safeTerminalValue(review.observedAt, 'time unavailable')} · ${review.state} · ${review.completeness} · ${safeTerminalValue(review.source)}`);
+        lines.push(`Other retained records: ${record.evidenceHistory.length} snapshots, ${record.actions.length} actions, ${record.assertions.length} assertions, ${record.attachments?.length ?? 0} file references.`, '');
+    }
+    lines.push('Use --json for the full Case export. Attached file bytes remain separate. This command makes no request.', '');
+    return lines.join('\n');
+}
+export async function runCaseCommand(args, dependencies, context) {
+    context.setFailureLabel('Local Case operation');
+    try {
+        const raw = args.source ? dependencies.caseFileInput ?? await context.readInput(args.source, MAX_EDITABLE_CASE_INPUT_BYTES, 'Case file') : null;
+        const digest = raw === null ? null : `sha256:${createHash('sha256').update(raw).digest('hex')}`;
+        if (args.expectedFileDigest && args.expectedFileDigest !== digest)
+            throw new CliUsageError('The Case file differs from the reviewed file digest. Nothing was written.');
+        const cases = raw === null ? [] : readEditableCaseExport(raw);
+        const now = normalizeExplicitIsoTimestamp(context.now());
+        if (!now)
+            throw new CliUsageError('A valid current timestamp is required.');
+        if (args.operation === 'show') {
+            const selected = selection(cases, args, false);
+            context.writeStdout(args.output === 'json' ? `${JSON.stringify(buildCaseExport(selected, now))}\n` : context.terminal(formatCases(selected, digest), args.color));
+            return EXIT_CODES.SUCCESS;
+        }
+        const input = args.inputSource ? parseBoundedJsonObject(await context.readInput(args.inputSource, MAX_EDITABLE_CASE_INPUT_BYTES, 'Case operation input'), {
+            maximumBytes: MAX_EDITABLE_CASE_INPUT_BYTES, limits: boundedJsonLimitsForBytes(MAX_CASE_STORE_BYTES), label: 'Case operation input',
+        }) : null;
+        const note = args.noteSource ? await context.readInput(args.noteSource, MAX_NOTE_LENGTH * 4 + 4, 'Case note') : args.text;
+        const next = mutate(cases, args, input, note, now);
+        if (Buffer.byteLength(serializeCaseStore(next)) > MAX_CASE_STORE_BYTES)
+            throw new CliUsageError('The updated Case store exceeds its byte budget. No evidence was pruned and nothing was written.');
+        const output = `${JSON.stringify(buildCaseExport(next, now))}\n`;
+        // Apply the same strict admission to our output before atomic publication.
+        readEditableCaseExport(output);
+        dependencies.signal?.throwIfAborted();
+        context.writeStdout(output);
+        return EXIT_CODES.SUCCESS;
+    }
+    catch (cause) {
+        dependencies.signal?.throwIfAborted();
+        if (cause instanceof CliUsageError)
+            throw cause;
+        throw new CliUsageError(cause instanceof Error ? cause.message : 'The Case operation could not be completed.');
+    }
+}

package/cli/case-pack.mjs

@@ -1,12 +1,13 @@
 import { createHash } from 'node:crypto';
 import { Buffer } from 'node:buffer';
 import { canonicalArtifactJson, canonicalArtifactJsonV2, SORTED_JSON_V2, } from "../packages/evidence/artifact-integrity.mjs";
-import { buildCaseReport } from "../packages/cases/case-report.mjs";
+import { buildCaseReport, buildCaseReportVerificationProjection } from "../packages/cases/case-report.mjs";
 import { WHOISLEUTH_APPLICATION_VERSION } from "../lib/application-version.mjs";
 import { assertBoundedJsonStructure, scanBoundedJson } from "../lib/bounded-json.mjs";
-import { assertCaseBrandProfileIds, CASE_AUDIENCE_SENSITIVE_FIELD_NAMES, CASE_RECORD_FIELD_NAMES, caseAudienceExclusions, normalizeDomain, normalizeCaseStore, projectCaseForAudience, safeId, } from "../packages/cases/case-model.mjs";
-import { CASE_REPORT_SCHEMA, CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, CLI_CASE_PACK_CURRENT_REDACTION_KEYS, CLI_CASE_PACK_PUBLIC_REPORT_KEYS, CLI_CASE_PACK_INTEGRITY_KEYS as INTEGRITY_KEYS, CLI_CASE_PACK_LIMITATIONS as PACKET_LIMITATIONS, CLI_CASE_PACK_PACKET_KEYS as PACKET_KEYS, CLI_CASE_PACK_REPORT_KEYS as REPORT_KEYS, CLI_CASE_PACK_ROOT_KEYS as ROOT_KEYS, MAX_CASE_IMPORT_BYTES, MAX_CASE_PACK_CASES, MAX_CASE_PACK_INPUT_BYTES, PUBLIC_CASE_SCHEMA_VERSION, caseReportVersionMatchesCase, } from "../packages/contracts/case-portability.mjs";
+import { assertCaseBrandProfileIds, CASE_AUDIENCE_SENSITIVE_FIELD_NAMES, caseAudienceExclusions, normalizeDomain, normalizeCaseStore, projectCaseForAudience, safeId, } from "../packages/cases/case-model.mjs";
+import { CASE_REPORT_SCHEMA, CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, INCIDENT_CASE_SCHEMA_VERSION, CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, CLI_CASE_PACK_INPUT_CASE_VERSIONS, CLI_CASE_PACK_CURRENT_REDACTION_KEYS, CLI_CASE_PACK_PUBLIC_REPORT_KEYS, CLI_CASE_PACK_INTEGRITY_KEYS as INTEGRITY_KEYS, CLI_CASE_PACK_LIMITATIONS as PACKET_LIMITATIONS, CLI_CASE_PACK_PACKET_KEYS as PACKET_KEYS, CLI_CASE_PACK_REPORT_KEYS as REPORT_KEYS, CLI_CASE_PACK_ROOT_KEYS as ROOT_KEYS, MAX_CASE_IMPORT_BYTES, MAX_CASE_PACK_CASES, MAX_CASE_PACK_INPUT_BYTES, PUBLIC_CASE_SCHEMA_VERSION, PUBLISHED_V2_3_CASE_SCHEMA_VERSION, caseReportVersionMatchesCase, } from "../packages/contracts/case-portability.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { canonicalCaseExportProjection as canonicalPackProjection } from "../packages/cases/case-export-input.mjs";
 export { CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, MAX_CASE_PACK_CASES, MAX_CASE_PACK_INPUT_BYTES, };
 const MAX_CASE_PACK_REFERENCE_SCAN_DEPTH = 64;
 function record(value) {
@@ -125,7 +126,7 @@ function canonicalValuesMatch(left, right) {
         return false;
     }
 }
-function assertCanonicalCaseIdentities(cases, label) {
+function assertCanonicalCaseIdentities(cases, label, caseVersion) {
     const ids = new Set();
     const domains = new Set();
     for (const value of cases) {
@@ -136,23 +137,20 @@ function assertCanonicalCaseIdentities(cases, label) {
             || typeof item.domain !== 'string'
             || normalizeDomain(item.domain) !== item.domain
             || ids.has(item.id)
-            || domains.has(item.domain)) {
+            || (caseVersion < INCIDENT_CASE_SCHEMA_VERSION && domains.has(item.domain))) {
             throw new TypeError(`${label} contains a missing, unsafe, non-canonical, or duplicate Case identity.`);
         }
         ids.add(item.id);
         domains.add(item.domain);
     }
 }
-function assertCurrentCaseProjection(rawCases, normalised, label) {
-    const requiredFields = new Set(CASE_RECORD_FIELD_NAMES);
+function assertCurrentCaseProjection(rawCases, normalised, label, caseVersion = CASE_SCHEMA_VERSION) {
     if (rawCases.length !== normalised.length || rawCases.some((item, index) => {
         const raw = record(item);
         return !raw
-            || Object.keys(raw).length !== requiredFields.size
-            || Object.keys(raw).some((key) => !requiredFields.has(key))
             || !canonicalValuesMatch(raw, normalised[index]);
     })) {
-        throw new TypeError(`${label} contains a schema ${CASE_SCHEMA_VERSION} Case that would be repaired, truncated, or otherwise changed during normalisation.`);
+        throw new TypeError(`${label} contains a schema ${caseVersion} Case that would be repaired, truncated, or otherwise changed during normalisation.`);
     }
 }
 /** Historical packs keep their immutable wire shape, so only their retained audience guarantees are checked here. */
@@ -196,17 +194,17 @@ function assertLegacyAudienceFields(value, normalised, audience) {
         }
     }
 }
-function assertCurrentAudienceProjection(value, normalised, audience) {
-    const expected = projectCaseForAudience(normalised, audience);
-    for (const field of CASE_RECORD_FIELD_NAMES) {
+function assertCurrentAudienceProjection(value, normalised, audience, caseVersion) {
+    const expected = canonicalPackProjection([projectCaseForAudience(normalised, audience)], caseVersion)[0];
+    for (const field of Object.keys(expected)) {
         if (!canonicalValuesMatch(value[field], expected[field])) {
             throw new TypeError(`The CLI case pack contains ${field} excluded by its audience or transformed incorrectly.`);
         }
     }
 }
-function assertAudienceProjection(value, normalised, audience, currentSchema) {
+function assertAudienceProjection(value, normalised, audience, currentSchema, caseVersion) {
     if (currentSchema)
-        assertCurrentAudienceProjection(value, normalised, audience);
+        assertCurrentAudienceProjection(value, normalised, audience, caseVersion);
     else
         assertLegacyAudienceFields(value, normalised, audience);
 }
@@ -217,11 +215,11 @@ function assertCurrentReportProjection(report, rawCase) {
     if (typeof report.generatedAt !== 'string') {
         throw new TypeError('The CLI case pack contains an invalid or mismatched Case report.');
     }
-    const expected = buildCaseReport(rawCase, {
+    const expected = buildCaseReportVerificationProjection(rawCase, {
         applicationVersion: reportApplicationVersion(report),
         includeNotes: false,
         generatedAt: report.generatedAt,
-    }).json;
+    }, report.schemaVersion);
     if (!canonicalValuesMatch(report, expected)) {
         throw new TypeError('The CLI case pack contains an invalid or mismatched Case report projection.');
     }
@@ -241,17 +239,18 @@ export function buildCliCasePack(input, options, generatedAt = new Date().toISOS
         throw new CliUsageError('Case-pack input must be valid bounded JSON without duplicate keys.');
     }
     const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-    if (Number.isSafeInteger(root.version) && root.version < CASE_SCHEMA_VERSION) {
-        throw new CliUsageError(`Case schema ${String(root.version)} is retired. Export it as schema ${CASE_SCHEMA_VERSION} with the last broad-reader release before packaging; no data was changed.`);
+    const supportedInput = CLI_CASE_PACK_INPUT_CASE_VERSIONS.some((version) => version === root.version);
+    if (Number.isSafeInteger(root.version) && root.version < CASE_SCHEMA_VERSION && !supportedInput) {
+        throw new CliUsageError(`Case schema ${String(root.version)} cannot be packaged directly. This command accepts schemas ${CLI_CASE_PACK_INPUT_CASE_VERSIONS.join(', ')}. Use a supported Case import to create a current export first; no data was changed.`);
     }
     if (Number.isSafeInteger(root.version) && root.version > CASE_SCHEMA_VERSION) {
         throw new CliUsageError(`Case schema ${String(root.version)} is newer than the supported schema ${CASE_SCHEMA_VERSION}; no data was changed.`);
     }
-    if (root.version !== CASE_SCHEMA_VERSION || !Array.isArray(root.cases)) {
-        throw new CliUsageError(`Case-pack input must be a well-formed WHOISleuth Case schema ${CASE_SCHEMA_VERSION} export.`);
+    if (!supportedInput || !Array.isArray(root.cases)) {
+        throw new CliUsageError(`Case-pack input must be a well-formed WHOISleuth Case export with schema ${CLI_CASE_PACK_INPUT_CASE_VERSIONS.join(' or ')}.`);
     }
     try {
-        assertCanonicalCaseIdentities(root.cases, 'Case-pack input');
+        assertCanonicalCaseIdentities(root.cases, 'Case-pack input', root.version);
         for (const item of root.cases) {
             const rawCase = record(item);
             if (!rawCase || !Object.hasOwn(rawCase, 'brandProfileIds'))
@@ -275,7 +274,7 @@ export function buildCliCasePack(input, options, generatedAt = new Date().toISOS
         throw new CliUsageError(`Case packs are limited to ${MAX_CASE_PACK_CASES} reviewed cases. Export a smaller selected set so no case is silently omitted.`);
     }
     try {
-        assertCurrentCaseProjection(root.cases, normalised, 'Case-pack input');
+        assertCurrentCaseProjection(root.cases, canonicalPackProjection(normalised, root.version), 'Case-pack input', root.version);
     }
     catch (cause) {
         throw new CliUsageError(cause instanceof Error ? cause.message : `Case-pack schema ${CASE_SCHEMA_VERSION} input is not exact.`);
@@ -313,7 +312,7 @@ export function buildCliCasePack(input, options, generatedAt = new Date().toISOS
         }),
     });
     if (Buffer.byteLength(JSON.stringify(document), 'utf8') > MAX_CASE_IMPORT_BYTES) {
-        throw new CliUsageError('The generated case pack exceeds the browser 2 MiB import limit. Select fewer cases or a more restrictive audience so no evidence is silently omitted.');
+        throw new CliUsageError(`The generated case pack exceeds the browser import limit of ${MAX_CASE_IMPORT_BYTES} bytes. Select fewer cases or a more restrictive audience so no evidence is silently omitted.`);
     }
     return document;
 }
@@ -382,15 +381,16 @@ export function verifyCliCasePack(input) {
         || !stringListsMatch(redactionManifest.excluded, caseAudienceExclusions(audience, root.version))) {
         throw new TypeError('The CLI case pack has an invalid audience redaction manifest.');
     }
-    assertCanonicalCaseIdentities(root.cases, 'The CLI case pack');
+    assertCanonicalCaseIdentities(root.cases, 'The CLI case pack', root.version);
     const normalised = normalizeCaseStore(root).cases;
     if (normalised.length !== root.cases.length) {
         throw new TypeError('The CLI case pack contains an invalid case collection.');
     }
-    const currentCaseSchema = root.version === CASE_SCHEMA_VERSION;
+    const currentCaseSchema = root.version >= PUBLISHED_V2_3_CASE_SCHEMA_VERSION;
+    const projected = canonicalPackProjection(normalised, root.version);
     if (currentCaseSchema)
-        assertCurrentCaseProjection(root.cases, normalised, 'The CLI case pack');
-    const normalisedByDomain = new Map(normalised.map((item) => [item.domain, item]));
+        assertCurrentCaseProjection(root.cases, projected, 'The CLI case pack', root.version);
+    const normalisedById = new Map(projected.map((item) => [item.id, item]));
     const caseReferenceLists = [];
     const reportReferenceLists = [];
     for (let index = 0; index < root.cases.length; index += 1) {
@@ -401,17 +401,18 @@ export function verifyCliCasePack(input) {
             || !report
             || !reportCase
             || typeof rawCase.domain !== 'string'
+            || typeof rawCase.id !== 'string'
             || report.schema !== CASE_REPORT_SCHEMA
             || !caseReportVersionMatchesCase(root.version, report.schemaVersion)
             || reportCase.id !== rawCase.id
             || reportCase.domain !== rawCase.domain
-            || !normalisedByDomain.has(rawCase.domain)) {
+            || !normalisedById.has(rawCase.id)) {
             throw new TypeError('The CLI case pack contains an invalid or mismatched Case report.');
         }
-        const normalisedCase = normalisedByDomain.get(rawCase.domain);
+        const normalisedCase = normalisedById.get(rawCase.id);
         if (!normalisedCase)
             throw new TypeError('The CLI case pack contains an invalid Case projection.');
-        assertAudienceProjection(rawCase, normalisedCase, audience, currentCaseSchema);
+        assertAudienceProjection(rawCase, normalisedCase, audience, currentCaseSchema, root.version);
         try {
             if (!Object.hasOwn(rawCase, 'brandProfileIds') || !Object.hasOwn(reportCase, 'brandProfileIds'))
                 throw new Error('missing');
@@ -423,6 +424,13 @@ export function verifyCliCasePack(input) {
         }
         if (currentCaseSchema)
             assertCurrentReportProjection(report, normalisedCase);
+        else {
+            assertLegacyAudienceFields(reportCase, normalisedCase, audience);
+            const response = record(report.analystResponse);
+            if (!response)
+                throw new TypeError('The CLI case pack contains an invalid analyst-response report.');
+            assertLegacyAudienceFields(response, normalisedCase, audience);
+        }
     }
     const omitted = redactionManifest.brandProfileReferencesOmitted;
     if (!Object.hasOwn(redactionManifest, 'brandProfileReferencesOmitted')

package/cli/command-argument-grammar.mjs

@@ -28,6 +28,10 @@ function parseTokens(command, argv) {
     const positionals = [];
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
+        if (argument === '--') {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
         if (!argument.startsWith('-')) {
             positionals.push(argument);
             continue;