@slicedearth/whoisleuth-cli 2.2.0 → 2.4.0

package/cli/output-file.mjs

@@ -3,6 +3,7 @@ import { unlinkSync } from 'node:fs';
 import { link, open, rename, unlink } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 import { CliUsageError } from "./errors.mjs";
+import { MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES } from "../packages/contracts/investigation-package-limits.mjs";
 export const MAX_CLI_OUTPUT_BYTES = 32 * 1024 * 1024;
 const MAX_CLI_OUTPUT_PATH_LENGTH = 4096;
 const pendingOutputFiles = new Map();
@@ -22,14 +23,26 @@ function safeOutputPath(value) {
     }
     return resolve(value);
 }
-function createBufferedOutput() {
+function createBufferedOutput(options = { binary: false }) {
     const chunks = [];
+    const binaryChunks = [];
     let bytes = 0;
+    const writeBinary = (chunk) => {
+        if (!options.binary || !(chunk instanceof Uint8Array))
+            throw new CliUsageError('Binary output requires an explicit package destination.');
+        if (chunk.byteLength > MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES - bytes)
+            throw new CliUsageError('Binary package output exceeds its byte limit.');
+        bytes += chunk.byteLength;
+        binaryChunks.push(new Uint8Array(chunk));
+    };
     return Object.freeze({
+        writeBinary,
         stream: {
             isTTY: false,
             columns: 80,
             write(chunk) {
+                if (options.binary)
+                    throw new CliUsageError('Binary package output cannot contain terminal text.');
                 const value = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
                 bytes += Buffer.byteLength(value, 'utf8');
                 if (bytes > MAX_CLI_OUTPUT_BYTES) {
@@ -39,14 +52,26 @@ function createBufferedOutput() {
                 return true;
             },
         },
-        value: () => chunks.join(''),
+        value: () => {
+            if (!options.binary)
+                return chunks.join('');
+            const result = new Uint8Array(bytes);
+            let offset = 0;
+            for (const chunk of binaryChunks) {
+                result.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            return result;
+        },
     });
 }
 async function writePrivateFile(pathValue, content, options = {}, operations = OUTPUT_FILE_OPERATIONS) {
     const target = safeOutputPath(pathValue);
-    if (Buffer.byteLength(content, 'utf8') > MAX_CLI_OUTPUT_BYTES) {
-        throw new CliUsageError(`Generated output is limited to ${MAX_CLI_OUTPUT_BYTES} bytes.`);
+    const maximumBytes = typeof content === 'string' ? MAX_CLI_OUTPUT_BYTES : MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES;
+    if ((typeof content === 'string' ? Buffer.byteLength(content, 'utf8') : content.byteLength) > maximumBytes) {
+        throw new CliUsageError(`Generated output is limited to ${maximumBytes} bytes.`);
     }
+    const captured = typeof content === 'string' ? content : new Uint8Array(content);
     const directory = dirname(target);
     const temporary = join(directory, `.${basename(target)}.${process.pid}.${operations.randomUUID()}.tmp`);
     let temporaryCreated = false;
@@ -59,12 +84,13 @@ async function writePrivateFile(pathValue, content, options = {}, operations = O
             settled: false,
         });
         try {
-            await handle.writeFile(content, { encoding: 'utf8' });
+            await handle.writeFile(captured, { encoding: 'utf8' });
             await handle.sync();
         }
         finally {
             await handle.close();
         }
+        await options.beforePublish?.();
         if (options.force) {
             await operations.rename(temporary, target);
             temporaryCreated = false;

package/cli/registry-doctor.mjs

@@ -189,7 +189,9 @@ function buildRegistryDoctorReport(raw, generatedAt = new Date().toISOString())
         ...sources.filter((source) => source.alignment === 'investigate').map((source) => (source.expected === 'allowed'
             ? `Review ${source.source.toUpperCase()} source health, transport attempts, and fixture coverage; the catalogue expected collection to be available.`
             : `Review the ${source.source.toUpperCase()} result and capability profile; the observed state did not match the declared access constraint.`)),
-        ...sources.filter((source) => source.alignment === 'unexpected_observation').map((source) => (`Review why ${source.source.toUpperCase()} produced normalized evidence despite the declared ${source.expected.replaceAll('_', ' ')} access profile.`)),
+        ...sources.filter((source) => source.alignment === 'unexpected_observation').map((source) => (source.source === 'rdap' && source.expected === 'unsupported'
+            ? 'Review whether the retained no-service RDAP profile needs refreshing; current bootstrap discovery may identify a newly published service.'
+            : `Review why ${source.source.toUpperCase()} produced normalized evidence despite the declared ${source.expected.replaceAll('_', ' ')} access profile.`)),
         ...sources.filter((source) => source.alignment === 'observed' && source.objectIdentifier === 'not_observed').map((source) => (`${source.source.toUpperCase()} succeeded without a retained registry object identifier; this can be a valid publication omission and should remain unknown rather than an error.`)),
     ].slice(0, 12);
     return {

package/cli/registry-support.mjs

@@ -1,7 +1,7 @@
 import { registryStandardsCoverageSnapshot, } from "../lib/registry-capabilities.mjs";
+import { REGISTRY_STANDARDS_COVERAGE_SCHEMA } from "../lib/registry-capability-catalogue.mjs";
 const REGISTRY_SUPPORT_SCHEMA = 'whoisleuth.cli.registry-support';
 const REGISTRY_SUPPORT_SCHEMA_VERSION = 4;
-const REGISTRY_STANDARDS_COVERAGE_SCHEMA = 'whoisleuth.registry-standards-coverage';
 const MAX_REGISTRY_SUPPORT_TEXT_LENGTH = 2048;
 const MAX_REGISTRY_SUPPORT_REFERENCES = 20;
 const MAX_REGISTRY_SUPPORT_REFERENCE_LENGTH = 2048;

package/cli/retained-artifact-diff.mjs

@@ -62,7 +62,7 @@ function parseBulkExport(root) {
         const rawSession = record(candidate);
         const rawResults = Array.isArray(rawSession?.results) ? rawSession.results : null;
         const rawDomains = Array.isArray(rawSession?.domains) ? rawSession.domains : null;
-        const session = normalizeBulkSession(candidate);
+        const session = normalizeBulkSession(candidate, version);
         if (!session || !rawResults || !rawDomains
             || rawResults.length > MAX_BULK_SESSION_ROWS
             || rawResults.length !== session.results.length
@@ -338,7 +338,7 @@ export function buildCliRetainedArtifactDiff(leftRaw, rightRaw, options = {}, ge
     if (left.schema === SAVED_LOOKUP_SCHEMA) {
         if (options.leftSessionId || options.rightSessionId)
             throw new CliUsageError('Saved-session selectors apply only to Bulk session exports.');
-        return buildCliLookupDiff(leftRaw, rightRaw, generatedAt);
+        return buildCliLookupDiff(leftRaw, rightRaw, generatedAt, { domainMode: 'auto' });
     }
     if (left.schema === BULK_SESSION_SCHEMA)
         return buildBulkLedger(leftRaw, rightRaw, left, right, options, generatedAt);

package/cli/review-command-runner.mjs

@@ -1,3 +1,10 @@
+import { readBoundedRegularFile } from "../lib/bounded-file.mjs";
+import { MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES } from "../packages/contracts/investigation-package-limits.mjs";
+import { verifyOfflineInvestigationFolder, verifyOfflineInvestigationPackage } from "./investigation-package-review.mjs";
+import { readInvestigationFolder } from "./investigation-folder.mjs";
+import { readBagItFolder } from "./bagit-folder.mjs";
+import { verifyOfflineBagIt } from "./bagit-review.mjs";
+import { MAX_BAGIT_ZIP_BYTES } from "../packages/interchange/bagit.mjs";
 import { MAX_OFFLINE_ARTIFACT_BYTES, formatOfflineArtifactVerification, isCompleteOfflineArtifactVerification, verifyOfflineArtifact, } from "./artifact-verify.mjs";
 import { MAX_CASE_PACK_INPUT_BYTES, buildCliCasePack, formatCliCasePack } from "./case-pack.mjs";
 import { MAX_COMPARE_INPUT_BYTES, compareLookupDocument, parseCliLookupDocument, } from "./compare.mjs";
@@ -5,7 +12,9 @@ import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { MAX_OFFLINE_EVIDENCE_INPUT_BYTES, buildOfflineEvidenceReview, buildOfflineEvidenceReviewWithLocalResources, formatOfflineEvidenceReview, } from "./offline-evidence-review.mjs";
 import { buildCliLookupBrief, formatCliLookupBrief } from "./lookup-brief.mjs";
+import { runCaseCommand } from "./case-command.mjs";
 import { MAX_MAIL_REVIEW_INPUT_BYTES, buildCliMailReview, formatCliMailReview, } from "./mail-review.mjs";
+import { MAX_MAIL_HEADER_INPUT_BYTES, buildCliMailHeaderReview, formatCliMailHeaderReview, } from "./mail-header-review.mjs";
 import { buildCliPageComparison, formatCliPageComparison } from "./page-compare.mjs";
 import { MAX_SOURCE_RELIABILITY_INPUT_BYTES, buildSourceReliabilityReport, formatSourceReliabilityReport, } from "./source-reliability.mjs";
 import { buildInterchangeFidelityReport, formatInterchangeFidelityReport, } from "./interchange-report.mjs";
@@ -16,6 +25,42 @@ import { REVIEW_INLINE_COMMANDS } from "./inline-command-families.mjs";
 import { runDiscriminatedCommandHandler } from "./discriminated-command-handlers.mjs";
 async function runVerifyArtifactCommand(args, dependencies, context) {
     context.setFailureLabel('Artefact verification');
+    if (args.folder) {
+        let files;
+        try {
+            files = await (args.bagit ? readBagItFolder : readInvestigationFolder)(args.folder, dependencies.signal);
+        }
+        catch (cause) {
+            dependencies.signal?.throwIfAborted();
+            const reason = cause instanceof TypeError ? boundedCliErrorMessage(cause) : 'The selected folder is unavailable or could not be read.';
+            throw new CliUsageError(`Could not read evidence folder: ${reason}`);
+        }
+        const report = await (args.bagit ? verifyOfflineBagIt : verifyOfflineInvestigationFolder)(files);
+        dependencies.signal?.throwIfAborted();
+        if (!args.quiet)
+            context.writeStdout(args.output === 'json' ? formatJsonDocument(report) : context.terminal(formatOfflineArtifactVerification(report), args.color));
+        return args.strictExit && !isCompleteOfflineArtifactVerification(report) ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+    }
+    if (args.package) {
+        if (!args.source || args.source === '-')
+            throw new CliUsageError('--package requires a selected ZIP file; binary stdin is not accepted.');
+        let bytes;
+        try {
+            bytes = dependencies.readBinaryArtifactInput ? await dependencies.readBinaryArtifactInput(args.source)
+                : await readBoundedRegularFile(args.source, { maximumBytes: args.bagit ? MAX_BAGIT_ZIP_BYTES : MAX_ENCRYPTED_INVESTIGATION_PACKAGE_BYTES, minimumBytes: 22, label: 'Investigation package', ...(dependencies.signal ? { signal: dependencies.signal } : {}) });
+        }
+        catch (error) {
+            if (error instanceof CliUsageError)
+                throw error;
+            throw new CliUsageError(`Could not read package input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+        }
+        const passphrase = args.passphraseSource ? await context.readPassphraseSource(args.passphraseSource) : undefined;
+        const report = args.bagit ? await verifyOfflineBagIt(bytes) : await verifyOfflineInvestigationPackage(bytes, passphrase);
+        dependencies.signal?.throwIfAborted();
+        if (!args.quiet)
+            context.writeStdout(args.output === 'json' ? formatJsonDocument(report) : context.terminal(formatOfflineArtifactVerification(report), args.color));
+        return args.strictExit && !isCompleteOfflineArtifactVerification(report) ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+    }
     let input;
     try {
         input = dependencies.readArtifactInput
@@ -180,6 +225,29 @@ async function runMailReviewCommand(args, dependencies, context) {
     }
     return EXIT_CODES.SUCCESS;
 }
+async function runMailHeadersCommand(args, dependencies, context) {
+    context.setFailureLabel('Mail-header review');
+    let input;
+    try {
+        input = dependencies.readMailHeaderInput
+            ? await dependencies.readMailHeaderInput(args.source)
+            : await context.readHeaderInput(args.source, MAX_MAIL_HEADER_INPUT_BYTES, 'Mail-header input');
+    }
+    catch (error) {
+        if (error instanceof CliUsageError)
+            throw error;
+        throw new CliUsageError(`Could not read mail-header input: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+    }
+    if (!input.trim())
+        throw new CliUsageError('mail-headers requires one message or header file, or headers on stdin.');
+    const document = buildCliMailHeaderReview(input, context.now());
+    if (!args.quiet) {
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(document)
+            : context.terminal(formatCliMailHeaderReview(document), args.color));
+    }
+    return EXIT_CODES.SUCCESS;
+}
 async function runOfflineEvidenceReviewCommand(args, dependencies, context) {
     context.setFailureLabel('Offline evidence review');
     let input;
@@ -259,8 +327,10 @@ const REVIEW_COMMAND_HANDLERS = Object.freeze({
     'compare': runCompareCommand,
     'page-compare': runPageCompareCommand,
     'mail-review': runMailReviewCommand,
+    'mail-headers': runMailHeadersCommand,
     'review-evidence': runOfflineEvidenceReviewCommand,
     'brief': runBriefOrCasePackCommand,
+    'case': runCaseCommand,
     'case-pack': runBriefOrCasePackCommand,
 });
 function runReviewCommand(args, dependencies, context) {

package/cli/risk-calibration.mjs

@@ -5,18 +5,14 @@ import { scanBoundedJson } from "../lib/bounded-json.mjs";
 import { canonicalRegistrableDomain } from "../lib/registrable-domain.mjs";
 import { ANALYST_REVIEW_REASON_VALUES, analystInteroperabilityTags } from "../lib/analyst-taxonomy.mjs";
 import { buildRiskCalibrationSummaryReport, parseRiskCalibrationSummaryReport, RISK_CALIBRATION_SUMMARY_INTERPRETATION, RISK_CALIBRATION_SUMMARY_THRESHOLDS, } from "../lib/risk-calibration-summary.mjs";
-import { MAX_RISK_CALIBRATION_ACTIVITY_LENGTH, MAX_RISK_CALIBRATION_AVAILABILITY_LENGTH, MAX_RISK_CALIBRATION_DISPOSITION_LENGTH, MAX_RISK_CALIBRATION_DOMAIN_AGE_DAYS, MAX_RISK_CALIBRATION_DOMAIN_LENGTH, MAX_RISK_CALIBRATION_FINDING_CATEGORY_LENGTH, MAX_RISK_CALIBRATION_FINDINGS_PER_PROVIDER, MAX_RISK_CALIBRATION_INPUT_BYTES, MAX_RISK_CALIBRATION_JSON_CONTAINER_ITEMS, MAX_RISK_CALIBRATION_JSON_DEPTH, MAX_RISK_CALIBRATION_JSON_KEYS, MAX_RISK_CALIBRATION_JSON_VALUES, MAX_RISK_CALIBRATION_MUTATIONS, MAX_RISK_CALIBRATION_PROVIDER_ID_LENGTH, MAX_RISK_CALIBRATION_PROVIDER_STATE_LENGTH, MAX_RISK_CALIBRATION_PROVIDERS, MAX_RISK_CALIBRATION_RECORD_ID_LENGTH, MAX_RISK_CALIBRATION_RECORDS, MAX_RISK_CALIBRATION_REVIEW_REASON_LENGTH, MAX_RISK_CALIBRATION_SCAN_DEPTH_LENGTH, MAX_RISK_CALIBRATION_STRING_LENGTH, MAX_RISK_CALIBRATION_TIMESTAMP_LENGTH, RISK_CALIBRATION_DATASET_SCHEMA, RISK_CALIBRATION_DATASET_VERSION, RISK_CALIBRATION_REPORT_SCHEMA, RISK_CALIBRATION_REPORT_VERSION, serializeRiskCalibrationSnapshot, snapshotRiskCalibrationReportForSerialization, SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS, } from "../packages/contracts/risk-calibration.mjs";
+import { MAX_RISK_CALIBRATION_ACTIVITY_LENGTH, MAX_RISK_CALIBRATION_AVAILABILITY_LENGTH, MAX_RISK_CALIBRATION_DISPOSITION_LENGTH, MAX_RISK_CALIBRATION_DOMAIN_AGE_DAYS, MAX_RISK_CALIBRATION_DOMAIN_LENGTH, MAX_RISK_CALIBRATION_FINDING_CATEGORY_LENGTH, MAX_RISK_CALIBRATION_FINDINGS_PER_PROVIDER, MAX_RISK_CALIBRATION_INPUT_BYTES, MAX_RISK_CALIBRATION_JSON_CONTAINER_ITEMS, MAX_RISK_CALIBRATION_JSON_DEPTH, MAX_RISK_CALIBRATION_JSON_KEYS, MAX_RISK_CALIBRATION_JSON_VALUES, MAX_RISK_CALIBRATION_MUTATIONS, MAX_RISK_CALIBRATION_PROVIDER_ID_LENGTH, MAX_RISK_CALIBRATION_PROVIDER_STATE_LENGTH, MAX_RISK_CALIBRATION_PROVIDERS, MAX_RISK_CALIBRATION_RECORD_ID_LENGTH, MAX_RISK_CALIBRATION_RECORDS, MAX_RISK_CALIBRATION_REVIEW_REASON_LENGTH, MAX_RISK_CALIBRATION_SCAN_DEPTH_LENGTH, MAX_RISK_CALIBRATION_STRING_LENGTH, MAX_RISK_CALIBRATION_TIMESTAMP_LENGTH, RISK_CALIBRATION_DATASET_SCHEMA, RISK_CALIBRATION_DATASET_VERSION, RISK_CALIBRATION_REPORT_SCHEMA, RISK_CALIBRATION_REPORT_VERSION, RISK_CALIBRATION_DISPOSITIONS, serializeRiskCalibrationSnapshot, snapshotRiskCalibrationReportForSerialization, SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS, } from "../packages/contracts/risk-calibration.mjs";
 import { CliUsageError } from "./arguments.mjs";
 import { RISK_MUTATION_TYPES } from "../lib/risk-scoring.mjs";
 import { THREAT_INTELLIGENCE_CONTRACT_VERSION, THREAT_INTELLIGENCE_ENVELOPE_VERSION, THREAT_INTELLIGENCE_SCHEMA, } from "../lib/threat-intelligence-types.mjs";
 export { MAX_RISK_CALIBRATION_INPUT_BYTES, MAX_RISK_CALIBRATION_RECORDS, MAX_RISK_CALIBRATION_STRING_LENGTH, RISK_CALIBRATION_DATASET_SCHEMA, RISK_CALIBRATION_DATASET_VERSION, RISK_CALIBRATION_REPORT_SCHEMA, RISK_CALIBRATION_REPORT_VERSION, SUPPORTED_RISK_CALIBRATION_DATASET_VERSIONS, } from "../packages/contracts/risk-calibration.mjs";
 export const RISK_CALIBRATION_THRESHOLDS = RISK_CALIBRATION_SUMMARY_THRESHOLDS;
 const CONTROL_RE = /[\x00-\x1f\x7f]/;
-const DISPOSITIONS = new Set([
-    'unreviewed', 'suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action',
-]);
-const POSITIVE_DISPOSITIONS = new Set(['confirmed_abuse']);
-const NEGATIVE_DISPOSITIONS = new Set(['false_positive', 'expected']);
+const DISPOSITIONS = new Set(RISK_CALIBRATION_DISPOSITIONS);
 const AVAILABILITY_STATES = new Set(['registered', 'for_sale', 'expiring', 'available', 'unknown', 'error']);
 const ACTIVITY_STATES = new Set(['active', 'parked', 'unreachable', 'no_site']);
 const BOOLEAN_FIELDS = [
@@ -26,6 +22,17 @@ const BOOLEAN_FIELDS = [
 ];
 const REVIEW_REASON_CODES = ANALYST_REVIEW_REASON_VALUES;
 const MUTATION_TYPES = new Set(RISK_MUTATION_TYPES);
+const DISPOSITION_METRIC_CLASSES = Object.freeze({
+    unreviewed: 'excluded',
+    suspicious: 'excluded',
+    confirmed_abuse: 'positive',
+    false_positive: 'negative',
+    expected: 'negative',
+    closed_no_action: 'excluded',
+});
+function isRiskCalibrationDisposition(value) {
+    return DISPOSITIONS.has(value);
+}
 function object(value, field) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new CliUsageError(`${field} must be an object.`);
@@ -214,7 +221,7 @@ export function parseRiskCalibrationDataset(text) {
         if (!isValidAsciiDomainName(domain, { requireDot: true }))
             throw new CliUsageError(`${prefix}.domain must be a valid ASCII DNS hostname, not an IP address.`);
         const analystDisposition = boundedString(record.analystDisposition, `${prefix}.analystDisposition`, MAX_RISK_CALIBRATION_DISPOSITION_LENGTH);
-        if (!DISPOSITIONS.has(analystDisposition))
+        if (!isRiskCalibrationDisposition(analystDisposition))
             throw new CliUsageError(`${prefix}.analystDisposition is unsupported.`);
         let reviewReasonCode;
         if (record.reviewReasonCode !== null && record.reviewReasonCode !== undefined) {
@@ -225,7 +232,7 @@ export function parseRiskCalibrationDataset(text) {
         return {
             id,
             domain,
-            analystDisposition: analystDisposition,
+            analystDisposition,
             ...(reviewReasonCode ? { reviewReasonCode } : {}),
             evidence: projectEvidence(record.evidence, `${prefix}.evidence`),
         };
@@ -276,9 +283,7 @@ function metricsForThreshold(records, threshold) {
         recall,
         specificity,
         falsePositiveRate: ratio(falsePositive, falsePositive + trueNegative),
-        f1: precision === null || recall === null || precision + recall === 0
-            ? null
-            : Number(((2 * precision * recall) / (precision + recall)).toFixed(4)),
+        f1: ratio(2 * truePositive, 2 * truePositive + falsePositive + falseNegative),
         balancedAccuracy: recall === null || specificity === null
             ? null
             : Number(((recall + specificity) / 2).toFixed(4)),
@@ -290,11 +295,7 @@ function metricsForThreshold(records, threshold) {
     };
 }
 function metricClass(disposition) {
-    if (POSITIVE_DISPOSITIONS.has(disposition))
-        return 'positive';
-    if (NEGATIVE_DISPOSITIONS.has(disposition))
-        return 'negative';
-    return 'excluded';
+    return DISPOSITION_METRIC_CLASSES[disposition];
 }
 function scoreBand(score) {
     if (score === null)
@@ -395,7 +396,8 @@ export function buildRiskCalibrationReport(dataset, explainRiskScore, options) {
             if (!source || !current)
                 continue;
             const previous = options.explainPreviousRiskScore(scoringEvidence(source));
-            if (previous?.score !== current.score)
+            const previousScore = previous?.score ?? null;
+            if (previousScore !== current.score)
                 scoresChanged += 1;
             if (scoreBand(previous?.score ?? null) !== current.band)
                 bandsChanged += 1;

package/cli/runner.mjs

@@ -5,7 +5,7 @@ import { HELP, commandDefinition, commandHelp, } from "./command-reference.mjs";
 import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import { evidenceCommandFailureLabel, isEvidenceCommand, runEvidenceCommand, } from "./evidence-command-runner.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
-import { readCliTextInput } from "./input.mjs";
+import { readCliHeaderInput, readCliTextInput } from "./input.mjs";
 import { INLINE_CLI_COMMANDS, runInlineCommand } from "./inline-command-runner.mjs";
 import { canLaunchInteractiveCli, launchInteractiveCli, } from "./interactive-launcher.mjs";
 import { MAX_OFFLINE_PASSPHRASE_FILE_BYTES, } from "./artifact-verify.mjs";
@@ -50,7 +50,7 @@ function usageEventReason(error) {
         return 'missing_input';
     return 'invalid_input';
 }
-async function runParsedCli(args, dependencies = {}) {
+async function runParsedCli(args, dependencies = {}, writeBinaryOutput) {
     const stdout = dependencies.stdout || process.stdout;
     const stderr = dependencies.stderr || process.stderr;
     const environment = dependencies.environment || process.env;
@@ -98,6 +98,11 @@ async function runParsedCli(args, dependencies = {}) {
             label,
             ...(dependencies.signal ? { signal: dependencies.signal } : {}),
         }));
+        const readHeaderInput = async (source, maximumBytes, label) => (readCliHeaderInput(source, dependencies.stdin || process.stdin, {
+            maximumBytes,
+            label,
+            ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+        }));
         const readPassphraseSource = async (source) => {
             let passphraseText;
             try {
@@ -123,9 +128,11 @@ async function runParsedCli(args, dependencies = {}) {
             terminal,
             presentation: (color) => terminalPresentation(stdout, color, environment, palette),
             writeStdout: (value) => write(stdout, value),
+            ...(writeBinaryOutput ? { writeBinaryOutput } : {}),
             writeStderr: (value) => write(stderr, value),
             readSingleInput,
             readInput,
+            readHeaderInput,
             readPassphraseSource,
             now: () => dependencies.now ? dependencies.now() : new Date().toISOString(),
             beginProgress,
@@ -299,15 +306,58 @@ async function runCliCommand(argv, dependencies = {}) {
     }
     if (!args.destination)
         return runParsedCli(args, dependencies);
-    const buffered = createBufferedOutput();
-    const code = await runParsedCli(args, { ...dependencies, stdout: buffered.stream });
-    if (code !== EXIT_CODES.SUCCESS && code !== EXIT_CODES.PARTIAL_FAILURE)
-        return code;
+    const buffered = createBufferedOutput({ binary: args.action === 'manifest' && args.package === true });
+    let checkpoint = null;
+    let capturedSource = null;
     try {
-        await writePrivateFile(args.destination, buffered.value(), { force: args.force === true });
+        if (args.action === 'workflow-run') {
+            const { prepareInvestigationCheckpoint } = await import("./investigation-checkpoint.mjs");
+            const workflowCheckpoint = await prepareInvestigationCheckpoint({
+                destination: args.destination, resumeSource: args.resumeSource, force: args.force === true,
+                ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+            });
+            checkpoint = workflowCheckpoint;
+            capturedSource = workflowCheckpoint.resumeInput;
+        }
+        else if (args.action === 'case') {
+            const { prepareLocalDocumentWrite } = await import("./local-document-checkpoint.mjs");
+            const { MAX_EDITABLE_CASE_INPUT_BYTES, MAX_EDITABLE_CASE_OUTPUT_BYTES } = await import("../packages/contracts/case-portability.mjs");
+            const caseCheckpoint = await prepareLocalDocumentWrite({
+                destination: args.destination, source: args.source, force: args.force === true, label: 'Case',
+                allowSourceReplacement: args.operation !== 'show',
+                maximumInputBytes: MAX_EDITABLE_CASE_INPUT_BYTES, maximumOutputBytes: MAX_EDITABLE_CASE_OUTPUT_BYTES,
+                ...(dependencies.signal ? { signal: dependencies.signal } : {}),
+            });
+            checkpoint = caseCheckpoint;
+            capturedSource = caseCheckpoint.sourceInput;
+        }
+        const code = await runParsedCli(args, {
+            ...dependencies, stdout: buffered.stream,
+            ...(args.action === 'workflow-run' && args.resumeSource && capturedSource !== null
+                ? { workflowResumeInput: capturedSource }
+                : {}),
+            ...(args.action === 'case' && capturedSource !== null ? { caseFileInput: capturedSource } : {}),
+        }, buffered.writeBinary);
+        if (code !== EXIT_CODES.SUCCESS && code !== EXIT_CODES.PARTIAL_FAILURE)
+            return code;
+        const content = buffered.value();
+        if (checkpoint) {
+            if (typeof content !== 'string')
+                throw new TypeError('Local document output must be text.');
+            await checkpoint.publish(content);
+        }
+        else
+            await writePrivateFile(args.destination, content, {
+                force: args.force === true,
+                beforePublish: async () => { dependencies.signal?.throwIfAborted(); },
+            });
         return code;
     }
     catch (error) {
+        if (isCancellation(error, dependencies.signal)) {
+            write(stderr, 'Cancelled by analyst.\n');
+            return EXIT_CODES.CANCELLED;
+        }
         if (error instanceof CliUsageError) {
             write(stderr, `Usage error: ${boundedCliErrorMessage(error, 'Output file could not be written')}\n`);
             return EXIT_CODES.USAGE;
@@ -315,6 +365,11 @@ async function runCliCommand(argv, dependencies = {}) {
         write(stderr, `Output failed: ${boundedCliErrorMessage(error, 'Output file could not be written')}\n`);
         return EXIT_CODES.LOOKUP_FAILED;
     }
+    finally {
+        if (checkpoint && await checkpoint.release() > 0) {
+            write(stderr, `${args.action === 'case' ? 'Case' : 'Workflow'} cleanup warning: File ownership changed or a lease could not be removed. Inspect the selected directory before resuming.\n`);
+        }
+    }
 }
 async function runCli(argv, dependencies = {}) {
     const stderr = dependencies.stderr || process.stderr;

package/cli/sharing-review.mjs

@@ -1,8 +1,7 @@
-import { hasVerifiedWholeArtifactIntegrity, UnsupportedOfflineArtifactError, verifyOfflineArtifact, } from "./artifact-verify.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { hasVerifiedWholeArtifactIntegrity, MAX_OFFLINE_ARTIFACT_BYTES, parseOfflineArtifactJson, UnsupportedOfflineArtifactError, verifyOfflineArtifact, } from "./artifact-verify.mjs";
 const SHARING_REVIEW_SCHEMA = 'whoisleuth.cli.sharing-review';
 const SHARING_REVIEW_VERSION = 2;
-const MAX_SHARING_REVIEW_BYTES = 15 * 1024 * 1024;
+const MAX_SHARING_REVIEW_BYTES = MAX_OFFLINE_ARTIFACT_BYTES;
 const TLP_MARKINGS = ['clear', 'green', 'amber', 'amber-strict', 'red'];
 const RECIPIENT_SCOPES = ['public', 'community', 'organization', 'named-recipients'];
 const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
@@ -31,46 +30,37 @@ function markingFromText(value) {
     return TLP_MARKINGS.includes(normalized) ? normalized : null;
 }
 function scanArtifact(root) {
-    const stack = [{ value: root, depth: 0, key: null }];
+    // The caller has already enforced the JSON byte, node, nesting and container
+    // bounds. Scan that admitted tree in full without a second, smaller prefix.
+    const stack = [{ value: root, marking: false }];
     const markings = new Set();
     let riskyKeyCount = 0;
-    let visited = 0;
-    let truncated = false;
-    while (stack.length && visited < 20_000) {
+    while (stack.length) {
         const next = stack.pop();
-        visited += 1;
-        if (next.key && RISKY_KEYS.has(normalizedKey(next.key)))
-            riskyKeyCount += 1;
         if (typeof next.value === 'string') {
-            const marking = markingFromText(next.value);
-            if (marking && (next.key === null || MARKING_KEYS.has(normalizedKey(next.key))))
-                markings.add(marking);
-            continue;
-        }
-        if (next.depth >= 12) {
-            if (next.value && typeof next.value === 'object')
-                truncated = true;
+            if (next.marking) {
+                const marking = markingFromText(next.value);
+                if (marking)
+                    markings.add(marking);
+            }
             continue;
         }
         if (Array.isArray(next.value)) {
-            for (const item of next.value.slice(0, 500))
-                stack.push({ value: item, depth: next.depth + 1, key: next.key });
-            if (next.value.length > 500)
-                truncated = true;
+            for (const value of next.value)
+                stack.push({ value, marking: next.marking });
             continue;
         }
         const valueRecord = record(next.value);
         if (!valueRecord)
             continue;
-        const entries = Object.entries(valueRecord);
-        for (const [key, value] of entries.slice(0, 500))
-            stack.push({ value, depth: next.depth + 1, key });
-        if (entries.length > 500)
-            truncated = true;
+        for (const [key, value] of Object.entries(valueRecord)) {
+            const normalized = normalizedKey(key);
+            if (RISKY_KEYS.has(normalized))
+                riskyKeyCount += 1;
+            stack.push({ value, marking: MARKING_KEYS.has(normalized) });
+        }
     }
-    if (stack.length)
-        truncated = true;
-    return { importedMarkings: [...markings], riskyKeyCount, truncated };
+    return { importedMarkings: [...markings], riskyKeyCount };
 }
 function expectedScope(marking) {
     if (marking === 'clear')
@@ -90,8 +80,7 @@ async function buildSharingReview(raw, options, generatedAt = new Date().toISOSt
     }
     let artifactValue;
     try {
-        scanBoundedJson(raw);
-        artifactValue = JSON.parse(raw);
+        artifactValue = parseOfflineArtifactJson(raw);
     }
     catch {
         throw new TypeError('Sharing review input must be valid bounded JSON without duplicate keys.');
@@ -147,8 +136,6 @@ async function buildSharingReview(raw, options, generatedAt = new Date().toISOSt
     add('recipient-scope', options.recipientScope === expectedScope(effective) ? 'pass' : 'block', 'Recipient scope', options.recipientScope === expectedScope(effective)
         ? `The recipient scope matches the effective ${tlpLabel(effective)} sharing boundary.`
         : `${tlpLabel(effective)} requires the ${expectedScope(effective)} recipient scope in this local policy.`);
-    if (scan.truncated)
-        add('scan-bounds', 'caution', 'Bounded content scan', 'The defensive key and marking scan reached a traversal bound; review the artefact manually.');
     const counts = {
         block: findings.filter((finding) => finding.state === 'block').length,
         caution: findings.filter((finding) => finding.state === 'caution').length,

package/cli/signer-trust.mjs

@@ -0,0 +1,104 @@
+import { createHash } from 'node:crypto';
+import { parseBoundedJsonObject } from "./bounded-json.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { formatEvidenceSignatureVerification } from "./evidence-signing.mjs";
+export const SIGNER_TRUST_STORE_SCHEMA = 'whoisleuth.evidence-signer-trust-store';
+export const SIGNER_TRUST_STORE_VERSION = 1;
+export const SIGNER_TRUST_REPORT_SCHEMA = 'whoisleuth.evidence-signer-trust-report';
+export const SIGNER_TRUST_REPORT_VERSION = 1;
+export const MAX_SIGNER_TRUST_STORE_BYTES = 4 * 1024 * 1024;
+export const MAX_SIGNER_TRUST_ENTRIES = 1_024;
+export const MAX_SIGNER_TRUST_LABEL_LENGTH = 160;
+export const MAX_SIGNER_TRUST_NOTE_LENGTH = 2_048;
+const FINGERPRINT = /^[a-f0-9]{64}$/u;
+const UNSAFE_TEXT = /[\x00-\x1f\x7f-\x9f\u2028\u2029]|\p{Default_Ignorable_Code_Point}/u;
+const PRIVATE_KEY_HEADER = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/u;
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function text(value, maximum, label, allowEmpty = false) {
+    if (typeof value !== 'string' || value.length > maximum || (!allowEmpty && !value.trim()) || UNSAFE_TEXT.test(value) || PRIVATE_KEY_HEADER.test(value)) {
+        throw new TypeError(`Signer trust ${label} must be single-line text of at most ${maximum} characters without hidden controls.`);
+    }
+    return value;
+}
+export function parseSignerTrustStore(raw) {
+    const value = parseBoundedJsonObject(raw, { label: 'Signer trust store', maximumBytes: MAX_SIGNER_TRUST_STORE_BYTES });
+    if (value.schema !== SIGNER_TRUST_STORE_SCHEMA || value.version !== SIGNER_TRUST_STORE_VERSION
+        || Object.keys(value).some((key) => !['schema', 'version', 'entries'].includes(key))
+        || !Array.isArray(value.entries) || value.entries.length > MAX_SIGNER_TRUST_ENTRIES) {
+        throw new TypeError(`Signer trust store must use ${SIGNER_TRUST_STORE_SCHEMA} version ${SIGNER_TRUST_STORE_VERSION} with at most ${MAX_SIGNER_TRUST_ENTRIES} entries.`);
+    }
+    const seen = new Set();
+    const entries = value.entries.map((candidate) => {
+        const entry = object(candidate);
+        if (!entry || Object.keys(entry).some((key) => !['keyIdSha256', 'label', 'status', 'updatedAt', 'note', 'successorKeyIdSha256'].includes(key))
+            || typeof entry.keyIdSha256 !== 'string' || !FINGERPRINT.test(entry.keyIdSha256)
+            || typeof entry.status !== 'string' || !['trusted', 'retired', 'revoked'].includes(entry.status)) {
+            throw new TypeError('Signer trust entry requires a SHA-256 key fingerprint and trusted, retired or revoked status.');
+        }
+        if (seen.has(entry.keyIdSha256))
+            throw new TypeError('Signer trust store contains duplicate key fingerprints.');
+        seen.add(entry.keyIdSha256);
+        const updatedAt = normalizeExplicitIsoTimestamp(entry.updatedAt);
+        if (!updatedAt)
+            throw new TypeError('Signer trust entry updatedAt requires a valid timestamp with an explicit timezone.');
+        const successor = entry.successorKeyIdSha256 ?? null;
+        if (successor !== null && (typeof successor !== 'string' || !FINGERPRINT.test(successor) || successor === entry.keyIdSha256)) {
+            throw new TypeError('Signer trust successor must be a different SHA-256 fingerprint or null.');
+        }
+        return Object.freeze({
+            keyIdSha256: entry.keyIdSha256,
+            label: text(entry.label, MAX_SIGNER_TRUST_LABEL_LENGTH, 'label'),
+            status: entry.status,
+            updatedAt,
+            note: text(entry.note === undefined ? '' : entry.note, MAX_SIGNER_TRUST_NOTE_LENGTH, 'note', true),
+            successorKeyIdSha256: successor,
+        });
+    });
+    return Object.freeze({ schema: SIGNER_TRUST_STORE_SCHEMA, version: SIGNER_TRUST_STORE_VERSION, entries: Object.freeze(entries) });
+}
+export function assessEvidenceSignerTrust(verification, trustStoreRaw, checkedAt = new Date().toISOString()) {
+    const now = normalizeExplicitIsoTimestamp(checkedAt);
+    if (!now)
+        throw new TypeError('Signer trust evaluation requires a valid timestamp with an explicit timezone.');
+    const store = parseSignerTrustStore(trustStoreRaw);
+    const entry = store.entries.find((candidate) => candidate.keyIdSha256 === verification.signature.keyIdSha256) ?? null;
+    // Signing time is self-asserted. It cannot bypass the current revocation policy,
+    // and a successor reference never makes another fingerprint trusted.
+    const state = !entry ? 'unknown' : entry.status !== 'trusted' ? entry.status
+        : Date.parse(entry.updatedAt) > Date.parse(now) ? 'review_required' : 'trusted';
+    return Object.freeze({
+        schema: SIGNER_TRUST_REPORT_SCHEMA,
+        version: SIGNER_TRUST_REPORT_VERSION,
+        state: state === 'trusted' ? 'trusted' : 'not_trusted',
+        checkedAt: now,
+        verification,
+        trust: Object.freeze({ state, storeDigestSha256: createHash('sha256').update(trustStoreRaw, 'utf8').digest('hex'), entry }),
+        limitations: Object.freeze([
+            'Trust is the current policy in the explicitly selected local file. Obtain fingerprints and revocation updates through an authenticated channel; this command does not discover or refresh them.',
+            'A label or successor reference does not authenticate a person, organisation or replacement key. A trusted fingerprint does not establish evidence accuracy, authority or collection time.',
+            'Signing time is supplied by the signer, not a trusted timestamp. Retired and revoked fingerprints remain untrusted regardless of that time.',
+            'The report includes only the matching entry and a SHA-256 digest of the exact trust-file bytes, not the file path, other entries or key files. Do not put sensitive material in labels or notes.',
+        ]),
+    });
+}
+export function formatSignerTrustReport(report) {
+    const entry = report.trust.entry;
+    return [
+        `WHOISleuth signer trust: ${report.trust.state}`,
+        `Checked: ${report.checkedAt}`,
+        `Trust-file SHA-256: ${report.trust.storeDigestSha256}`,
+        ...(entry ? [
+            `Local label: ${entry.label}`,
+            `Entry reviewed: ${entry.updatedAt}`,
+            ...(entry.note ? [`Local note: ${entry.note}`] : []),
+            ...(entry.successorKeyIdSha256 ? [`Successor reference: sha256:${entry.successorKeyIdSha256} (not a trust grant)`] : []),
+        ] : ['No matching fingerprint in the selected trust file.']),
+        '',
+        'Signature checks (separate from current trust policy)',
+        formatEvidenceSignatureVerification(report.verification, false).trimEnd(),
+        ...report.limitations.map((limitation) => `Trust limitation: ${limitation}`),
+        '',
+    ].join('\n');
+}