@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/intake-command.mjs

@@ -0,0 +1,107 @@
+import { readBoundedRegularFile } from "../lib/bounded-file.mjs";
+import { MAX_MESSAGE_INTAKE_BYTES, MESSAGE_INTAKE_INPUTS } from "../packages/contracts/message-intake.mjs";
+import { reviewSelectedInputInWorker } from "./selected-input-worker.mjs";
+import { reviewIdentityIncident } from "../packages/investigation/identity-incident-review.mjs";
+import { selectReceiverTrust, authenticationHeaderLabel } from "../packages/investigation/mail-authentication-review.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { formatJsonDocument } from "./formatters/json.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+export function formatMessageIntake(report) {
+    const lines = [`Offline ${report.source.kind} intake`, `Review: ${report.coverage.state} · Extracted links: ${report.links.length} · Reviewed parts: ${report.coverage.reviewedParts}`,
+        `Source: ${report.source.digestSha256} · ${report.source.byteLength} bytes`];
+    for (const identity of report.identities)
+        lines.push(`Part ${identity.part} ${identity.role.replaceAll('_', ' ')}: ${identity.domain}`);
+    for (const header of report.authenticationReview.headers) {
+        lines.push(`${authenticationHeaderLabel(header)} · ${header.state} · receiver trust: ${header.receiverTrust.replaceAll('_', ' ')}`);
+        for (const claim of header.claims)
+            lines.push(`  ${claim.method}/${claim.methodVersion}: ${claim.result} (${claim.state})${claim.domains.map(value => ` · ${value.property}=${value.domain}`).join('')}${claim.duplicateProperties.length ? ` · ambiguous properties: ${claim.duplicateProperties.join(', ')}` : ''}`);
+        if (header.duplicateOf)
+            lines.push(`  Duplicate of header ${header.duplicateOf} in this part.`);
+        lines.push(...header.issues.map(issue => `  ${issue}`));
+    }
+    for (const link of report.links) {
+        lines.push(`${link.id}: ${link.origin} · ${link.source.replaceAll('_', ' ')}${link.parentId ? ` · supplied inside ${link.parentId}` : ''}`);
+        if (link.displayedHostname)
+            lines.push(`  Displayed: ${link.displayedHostname} · ${link.displayedDestination.replaceAll('_', ' ')}`);
+        if (link.authorisation) {
+            lines.push(`  Authorisation: ${link.authorisation.kind.replaceAll('_', ' ')} · client ${link.authorisation.clientId ?? 'not retained or ambiguous'}`);
+            if (link.authorisation.scopes.length)
+                lines.push(`  Requested scopes: ${link.authorisation.scopes.join(', ')}`);
+            if (link.authorisation.redirectOrigin)
+                lines.push(`  Supplied return origin: ${link.authorisation.redirectOrigin}`);
+            if (link.authorisation.duplicateParameters.length)
+                lines.push(`  Ambiguous parameters: ${link.authorisation.duplicateParameters.join(', ')}`);
+        }
+    }
+    if (report.actionHints.length)
+        lines.push(`Review wording: ${report.actionHints.map(value => value.replaceAll('_', ' ')).join(', ')}`);
+    if (report.documentReview) {
+        lines.push(`Document coverage: ${report.documentReview.state} · pages ${report.documentReview.reviewedPages}/${report.documentReview.pageCount ?? 'not a paginated review'}`);
+        for (const part of report.documentReview.parts)
+            lines.push(`  ${part.id}${part.page ? ` · page ${part.page}` : ''} · ${part.kind} · ${part.identity} · ${part.digestSha256}`);
+        lines.push(...report.documentReview.notes);
+    }
+    if (report.harReview) {
+        lines.push('Recorded HTTP sequence (not replayed)');
+        for (const entry of report.harReview.entries)
+            lines.push(`  ${entry.sequence}. ${entry.startedAt ?? 'time unavailable'} · ${entry.method} ${entry.origin ?? 'origin unavailable'} · status ${entry.status ?? 'unavailable'} · ${entry.mimeCategory} · ${entry.durationMs === null ? 'duration unavailable' : `${entry.durationMs} ms`}`);
+        if (report.harReview.invalidEntries)
+            lines.push(`Invalid request records omitted: ${report.harReview.invalidEntries}`);
+    }
+    if (report.identityEventReview) {
+        const review = report.identityEventReview;
+        const matches = new Map(review.comparison?.events.map(event => [event.sequence, event]));
+        lines.push(`Selected identity events: ${review.provider} · ${review.events.length} records · ${review.invalidEvents} invalid records omitted`);
+        for (const event of review.events) {
+            const match = matches.get(event.sequence);
+            lines.push(`  ${event.sequence}. ${event.occurredAt ?? 'time unavailable'} · ${event.actorLabel ?? 'actor unavailable'} · ${event.kind} · ${event.result}`, `    applications ${event.applicationIds.join(', ') || 'unavailable'} · resource tenant ${event.tenantId ?? 'unavailable'} · protocol ${event.protocol}`);
+            if (match)
+                lines.push(`    comparison ${match.state}: application ${match.application}, tenant ${match.tenant}, actor ${match.actor}, time ${match.time}`);
+        }
+        lines.push('Actor labels are file-local. Matching supplied fields does not establish account compromise.');
+    }
+    for (const step of report.identityRecovery.nextSteps)
+        lines.push(`Account response — ${step.title}: ${step.detail}`);
+    if (report.coverage.unreviewedAttachments)
+        lines.push(`Unreviewed attachments: ${report.coverage.unreviewedAttachments}`);
+    if (report.coverage.rejectedLinks)
+        lines.push(`Unsupported link values: ${report.coverage.rejectedLinks}`);
+    if (report.coverage.boundsReached.length)
+        lines.push(`Partial analysis: ${report.coverage.boundsReached.join('; ')}`);
+    if (report.source.kind === 'qr' && !report.coverage.reviewedParts)
+        lines.push('No QR text was decoded. This does not establish that the image contains no QR symbol.');
+    lines.push('Exact paths, queries, fragments and original message content are not included. Link relationships and authorisation parameters are supplied claims, not proof of a completed redirect or account compromise.');
+    return `${lines.join('\n')}\n`;
+}
+export async function runIntakeCommand(args, dependencies, context) {
+    context.setFailureLabel('Message intake');
+    if (MESSAGE_INTAKE_INPUTS[args.kind].binary && (!args.source || args.source === '-'))
+        throw new CliUsageError('Binary intake requires a selected file; binary stdin is not accepted.');
+    let bytes;
+    if (dependencies.readBinaryArtifactInput && args.source && args.source !== '-')
+        bytes = await dependencies.readBinaryArtifactInput(args.source);
+    else if (args.source && args.source !== '-')
+        bytes = await readBoundedRegularFile(args.source, { maximumBytes: MAX_MESSAGE_INTAKE_BYTES, minimumBytes: 1, label: 'Selected input', ...(dependencies.signal ? { signal: dependencies.signal } : {}) });
+    else
+        bytes = new TextEncoder().encode(await context.readInput(args.source, MAX_MESSAGE_INTAKE_BYTES, 'Selected input'));
+    try {
+        const result = await reviewSelectedInputInWorker(bytes, args.kind, context.now(), dependencies.signal);
+        let authenticationReview;
+        try {
+            authenticationReview = selectReceiverTrust(result.report.authenticationReview, args.trustedAuthHeaders ?? []);
+        }
+        catch (cause) {
+            if (cause instanceof TypeError)
+                throw new CliUsageError(cause.message);
+            throw cause;
+        }
+        const report = { ...result.report, authenticationReview, identityRecovery: reviewIdentityIncident({ reportedActions: args.reportedActions }) };
+        dependencies.signal?.throwIfAborted();
+        if (!args.quiet)
+            context.writeStdout(args.output === 'json' ? formatJsonDocument(report) : context.terminal(formatMessageIntake(report), args.color));
+        return args.strictExit && report.coverage.state === 'partial' ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
+    }
+    finally {
+        bytes.fill(0);
+    }
+}

package/cli/interactive-launcher.mjs

@@ -1,171 +1,13 @@
 import { classifyQuery, isDirectLookupTarget } from "../lib/classify.mjs";
-import { StringDecoder } from 'node:string_decoder';
-import { boundedCliErrorMessage, CliUsageError, hasUnsafeCliText } from "./errors.mjs";
+import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import { INVESTIGATION_PLAN_RECIPE_LABELS, INVESTIGATION_PLAN_RECIPES, } from "./investigation-plan.mjs";
 import { buildCliLookupPlan, formatCliLookupPlan } from "./lookup-plan.mjs";
 import { canBrowseLookup, } from "./lookup-browser.mjs";
-const MAX_INTERACTIVE_ANSWER_SCALARS = 1_024;
-const MAX_INTERACTIVE_ANSWER_BYTES = 4_096;
+import { MAX_INTERACTIVE_ANSWER_BYTES, MAX_INTERACTIVE_ANSWER_SCALARS, boundedInteractiveAnswer, readBoundedInteractiveLine } from "./terminal-input.mjs";
 function canLaunchInteractiveCli(input, output, environment = process.env) {
     return input?.isTTY === true
         && canBrowseLookup(input, output, environment);
 }
-function boundedInteractiveAnswer(value) {
-    const supplied = typeof value === 'string' ? value : '';
-    if (Buffer.byteLength(supplied, 'utf8') > MAX_INTERACTIVE_ANSWER_BYTES
-        || Array.from(supplied).length > MAX_INTERACTIVE_ANSWER_SCALARS
-        || hasUnsafeCliText(supplied)) {
-        throw new CliUsageError('Interactive input must be bounded text without control characters.');
-    }
-    return supplied.trim();
-}
-function abortError() {
-    return new DOMException('Aborted', 'AbortError');
-}
-function readBoundedInteractiveLine(prompt, options) {
-    const { input, output, signal } = options;
-    if (signal?.aborted)
-        return Promise.reject(signal.reason || abortError());
-    const previousRaw = input.isRaw === true;
-    const wasPaused = input.isPaused?.() === true;
-    let receivedBytes = 0;
-    let receivedScalars = 0;
-    let settled = false;
-    let characters = [];
-    const decoder = new StringDecoder('utf8');
-    return new Promise((resolve, reject) => {
-        const cleanup = () => {
-            let failure = null;
-            const attempt = (operation) => {
-                try {
-                    operation();
-                }
-                catch (error) {
-                    failure ||= error instanceof Error ? error : new Error('Interactive terminal cleanup failed.');
-                }
-            };
-            attempt(() => input.off?.('data', onData));
-            attempt(() => input.off?.('end', onEnd));
-            attempt(() => signal?.removeEventListener('abort', onAbort));
-            attempt(() => input.setRawMode?.(previousRaw));
-            if (wasPaused)
-                attempt(() => input.pause?.());
-            return failure;
-        };
-        const finish = (value, error) => {
-            if (settled)
-                return;
-            settled = true;
-            const cleanupFailure = cleanup();
-            characters = [];
-            if (error && cleanupFailure) {
-                reject(new AggregateError([error, cleanupFailure], `${error.message}; terminal cleanup also failed: ${cleanupFailure.message}`));
-            }
-            else if (error || cleanupFailure)
-                reject(error || cleanupFailure);
-            else
-                resolve(value || '');
-        };
-        const rejectUsage = () => finish(undefined, new CliUsageError('Interactive input must be bounded text without control characters.'));
-        const onData = (chunk) => {
-            if (settled)
-                return;
-            let rawChunk;
-            if (Buffer.isBuffer(chunk)) {
-                if (chunk.length > MAX_INTERACTIVE_ANSWER_BYTES - receivedBytes) {
-                    rejectUsage();
-                    return;
-                }
-                rawChunk = chunk;
-            }
-            else {
-                const supplied = String(chunk ?? '');
-                if (supplied.length > MAX_INTERACTIVE_ANSWER_BYTES - receivedBytes
-                    || Buffer.byteLength(supplied, 'utf8') > MAX_INTERACTIVE_ANSWER_BYTES - receivedBytes) {
-                    rejectUsage();
-                    return;
-                }
-                rawChunk = Buffer.from(supplied, 'utf8');
-            }
-            receivedBytes += rawChunk.length;
-            const value = decoder.write(rawChunk);
-            receivedScalars += Array.from(value).length;
-            if (receivedBytes > MAX_INTERACTIVE_ANSWER_BYTES
-                || receivedScalars > MAX_INTERACTIVE_ANSWER_SCALARS
-                || value.includes('\ufffd')) {
-                rejectUsage();
-                return;
-            }
-            for (const character of value) {
-                if (character === '\r' || character === '\n') {
-                    try {
-                        output.write('\n');
-                    }
-                    catch (error) {
-                        finish(undefined, error instanceof Error ? error : new Error('Interactive terminal output failed.'));
-                        return;
-                    }
-                    finish(characters.join(''));
-                    return;
-                }
-                if (character === '\u0003' || character === '\u0004' || character === '\u001b') {
-                    finish(undefined, abortError());
-                    return;
-                }
-                if (character === '\u0008' || character === '\u007f') {
-                    if (characters.length) {
-                        characters.pop();
-                        try {
-                            output.write('\b \b');
-                        }
-                        catch (error) {
-                            finish(undefined, error instanceof Error ? error : new Error('Interactive terminal output failed.'));
-                            return;
-                        }
-                    }
-                    continue;
-                }
-                if (hasUnsafeCliText(character)) {
-                    rejectUsage();
-                    return;
-                }
-                characters.push(character);
-                try {
-                    output.write(character);
-                }
-                catch (error) {
-                    finish(undefined, error instanceof Error ? error : new Error('Interactive terminal output failed.'));
-                    return;
-                }
-            }
-        };
-        const onEnd = () => {
-            const remainder = decoder.end();
-            if (remainder)
-                rejectUsage();
-            else
-                finish(undefined, abortError());
-        };
-        const onAbort = () => finish(undefined, signal?.reason instanceof Error ? signal.reason : abortError());
-        try {
-            output.write(prompt);
-            input.on?.('data', onData);
-            input.on?.('end', onEnd);
-            signal?.addEventListener('abort', onAbort, { once: true });
-            if (signal?.aborted) {
-                onAbort();
-                return;
-            }
-            input.setRawMode?.(true);
-            if (settled)
-                return;
-            input.resume?.();
-        }
-        catch (error) {
-            finish(undefined, error instanceof Error ? error : new Error('Interactive terminal input failed.'));
-        }
-    });
-}
 async function launchInteractiveCli(options) {
     const environment = options.environment || process.env;
     if (!canLaunchInteractiveCli(options.input, options.output, environment)) {

package/cli/interchange-report.mjs

@@ -1,12 +1,11 @@
 import { Buffer } from 'node:buffer';
 import { INTERCHANGE_ARTIFACT_CONTRACTS, } from "../lib/interchange-fidelity-registry.mjs";
-import { offlineArtifactSatisfiesAssurance, verifyOfflineArtifact, } from "./artifact-verify.mjs";
+import { offlineArtifactSatisfiesAssurance, MAX_OFFLINE_ARTIFACT_BYTES, parseOfflineArtifactJson, verifyOfflineArtifact, } from "./artifact-verify.mjs";
 import { mergeBrandProfiles, } from "../packages/workspace/brand-profile-model.mjs";
-import { parseBoundedJsonObject } from "./bounded-json.mjs";
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 export const INTERCHANGE_FIDELITY_REPORT_SCHEMA = 'whoisleuth.interchange-fidelity-report';
 export const INTERCHANGE_FIDELITY_REPORT_VERSION = 2;
-export const MAX_INTERCHANGE_REPORT_BYTES = 15 * 1024 * 1024;
+export const MAX_INTERCHANGE_REPORT_BYTES = MAX_OFFLINE_ARTIFACT_BYTES;
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -19,10 +18,7 @@ function parseInput(raw) {
     if (bytes < 1 || bytes > MAX_INTERCHANGE_REPORT_BYTES) {
         throw new TypeError(`Interchange input must be between 1 byte and ${MAX_INTERCHANGE_REPORT_BYTES} bytes.`);
     }
-    return parseBoundedJsonObject(raw.replace(/^\uFEFF/u, ''), {
-        label: 'Interchange input',
-        maximumBytes: MAX_INTERCHANGE_REPORT_BYTES,
-    });
+    return parseOfflineArtifactJson(raw.replace(/^\uFEFF/u, ''));
 }
 function nestedRecord(value, path) {
     let current = value;
@@ -93,6 +89,7 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
             }),
             limitations: Object.freeze([
                 'The file did not match a registered interchange contract. Its supplied schema text and contents are not echoed.',
+                'This is an import/export compatibility catalogue, not the complete verifier inventory. verify-artifact may support this file independently.',
                 'This report makes no request and does not establish that evidence is accurate, current, complete, or safe to share.',
             ]),
         });
@@ -123,7 +120,7 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
             }
             else {
                 const verification = await verifyOfflineArtifact(raw, { passphrase: options.passphrase ?? null });
-                verificationState = verification.state;
+                verificationState = verification.state === 'partial' ? 'not_verified' : verification.state;
                 assuranceSatisfied = contract.requiredAssurance === 'whole_integrity'
                     ? offlineArtifactSatisfiesAssurance(verification, 'whole_integrity')
                     : contract.requiredAssurance === 'applicable_integrity'
@@ -189,6 +186,7 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
             blockedSectionCount, prunedRecordCount,
         }),
         limitations: Object.freeze([
+            ...(contract.id === 'lookup_evidence' ? ['CLI read support means offline verification and packaging. brief, export, compare, registry-doctor and source-report require a saved CLI Lookup, not this browser evidence export.'] : []),
             'Compatibility describes declared field groups and supported operations, not byte-for-byte equality or evidence truth.',
             'The report emits only registered metadata, counts, and fixed field-group identifiers. Targets, notes, contacts, passphrases, and evidence values are not included.',
             'A verified integrity envelope detects file changes but does not establish author identity, source accuracy, currency, completeness, or sharing authority.',
@@ -199,7 +197,7 @@ export function formatInterchangeFidelityReport(report) {
     const browser = report.compatibility.browser;
     const cli = report.compatibility.cli;
     const nextAction = !report.recognised
-        ? 'Choose a supported WHOISleuth export and run verify-artifact before trying to import it.'
+        ? 'Run verify-artifact for independent verification support. Import/export compatibility is not registered here.'
         : !report.artifact.versionSupported
             ? 'Use a WHOISleuth release that supports this exact version, or re-export it with its last supported release.'
             : !report.verification.assuranceSatisfied
@@ -213,7 +211,7 @@ export function formatInterchangeFidelityReport(report) {
                             : 'Retain the verification result and use only the operations declared above.';
     return [
         'Interchange fidelity report',
-        `Recognised     ${report.recognised ? 'yes' : 'no'}`,
+        `Interchange contract ${report.recognised ? 'registered' : 'not registered'}`,
         `Artifact       ${report.artifact.id ?? 'unrecognised'}`,
         `Version        ${report.artifact.version ?? 'unavailable'}${report.artifact.versionSupported ? '' : ' (unsupported)'}`,
         `Verification   ${report.verification.state}`,

package/cli/investigation-artifacts.mjs

@@ -0,0 +1,176 @@
+import { createHash } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { CLI_LOOKUP_SCHEMA, CLI_LOOKUP_VERSION } from "../packages/contracts/cli-lookup.mjs";
+import { DOMAIN_CONTROL_REVIEW_SCHEMA, DOMAIN_CONTROL_REVIEW_VERSION } from "../packages/contracts/domain-control-review.mjs";
+import { canonicalArtifactJsonV2 } from "../packages/evidence/artifact-integrity.mjs";
+import { validateDomainControlReviewDocument } from "../lib/domain-control-manifest.mjs";
+import { LOOKUP_EVIDENCE_SCHEMA, LOOKUP_EVIDENCE_SCHEMA_VERSION, serializeLookupEvidence } from "../lib/evidence-export.mjs";
+import { OFFLINE_ARTIFACT_VERIFICATION_SCHEMA, OFFLINE_ARTIFACT_VERIFICATION_VERSION } from "./artifact-verify.mjs";
+import { validateLookupEvidenceArtifactStructure } from "./artifact-validation/lookup-evidence.mjs";
+import { CLI_DISCOVERY_SCAN_SCHEMA, CLI_DISCOVERY_SCAN_VERSION } from "./discovery-scan.mjs";
+import { CLI_DISCOVER_SCHEMA, CLI_DISCOVER_SCHEMA_VERSION, CLI_POSTURE_SCHEMA, CLI_POSTURE_SCHEMA_VERSION, CLI_CT_SEARCH_SCHEMA, CLI_CT_SEARCH_SCHEMA_VERSION, CLI_COMPARE_SCHEMA, CLI_COMPARE_SCHEMA_VERSION, } from "./formatters/json.mjs";
+import { CLI_LOOKUP_BRIEF_SCHEMA, CLI_LOOKUP_BRIEF_VERSION } from "../packages/contracts/cli-lookup-brief.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, parseExternalFindingsDocument } from "../packages/interchange/external-findings-import.mjs";
+import { SOURCE_RELIABILITY_REPORT_SCHEMA, SOURCE_RELIABILITY_REPORT_VERSION } from "./source-reliability.mjs";
+import { CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, verifyCliCasePack } from "./case-pack.mjs";
+import { SHARING_REVIEW_SCHEMA, SHARING_REVIEW_VERSION } from "./sharing-review.mjs";
+import { DOMAIN_ASSURANCE_SCHEMA, DOMAIN_ASSURANCE_VERSION } from "../lib/domain-assurance.mjs";
+import { DOMAIN_CHANGE_PACKET_SCHEMA, DOMAIN_CHANGE_PACKET_VERSION } from "../lib/domain-change-packet.mjs";
+import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, CLI_DOMAIN_CONTROL_MONITOR_VERSION } from "../packages/contracts/domain-control-monitor.mjs";
+import { CLI_LOOKUP_DIFF_SCHEMA, CLI_LOOKUP_DIFF_VERSION } from "./lookup-diff.mjs";
+import { CLI_LOOKUP_TIMELINE_SCHEMA, CLI_LOOKUP_TIMELINE_VERSION } from "./lookup-timeline.mjs";
+import { normalizeCliLookupDocument } from "./saved-lookup.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { MAX_INVESTIGATION_RUN_SELECTIONS } from "../packages/contracts/investigation-run.mjs";
+// This is a fixed-recipe boundary, not a general command or format registry.
+// Non-reusable reports have their envelope checked; reusable evidence also
+// passes its existing input validator before it can enter another command.
+export function validateWorkflowResult(step, result, retained) {
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        throw new TypeError('Expected a JSON document.');
+    const value = result;
+    let schema;
+    let version;
+    switch (step.command) {
+        case 'lookup':
+            schema = CLI_LOOKUP_SCHEMA;
+            version = CLI_LOOKUP_VERSION;
+            normalizeCliLookupDocument(value, { label: 'Workflow Lookup result' });
+            break;
+        case 'export':
+            schema = LOOKUP_EVIDENCE_SCHEMA;
+            version = LOOKUP_EVIDENCE_SCHEMA_VERSION;
+            validateLookupEvidenceArtifactStructure(value);
+            serializeLookupEvidence(value);
+            break;
+        case 'domain-control':
+            schema = DOMAIN_CONTROL_REVIEW_SCHEMA;
+            version = DOMAIN_CONTROL_REVIEW_VERSION;
+            validateDomainControlReviewDocument(value);
+            break;
+        case 'case-pack':
+            schema = CLI_CASE_PACK_SCHEMA;
+            version = CLI_CASE_PACK_VERSION;
+            verifyCliCasePack(value);
+            break;
+        case 'ct-search':
+            schema = CLI_CT_SEARCH_SCHEMA;
+            version = CLI_CT_SEARCH_SCHEMA_VERSION;
+            break;
+        case 'ct-intake':
+            schema = EXTERNAL_FINDINGS_SCHEMA;
+            version = EXTERNAL_FINDINGS_VERSION;
+            parseExternalFindingsDocument(value);
+            break;
+        case 'brief':
+            schema = CLI_LOOKUP_BRIEF_SCHEMA;
+            version = CLI_LOOKUP_BRIEF_VERSION;
+            break;
+        case 'compare':
+            schema = CLI_COMPARE_SCHEMA;
+            version = CLI_COMPARE_SCHEMA_VERSION;
+            break;
+        case 'source-report':
+            schema = SOURCE_RELIABILITY_REPORT_SCHEMA;
+            version = SOURCE_RELIABILITY_REPORT_VERSION;
+            break;
+        case 'sharing-review':
+            schema = SHARING_REVIEW_SCHEMA;
+            version = SHARING_REVIEW_VERSION;
+            break;
+        case 'assurance':
+            schema = DOMAIN_ASSURANCE_SCHEMA;
+            version = DOMAIN_ASSURANCE_VERSION;
+            break;
+        case 'change-packet':
+            schema = DOMAIN_CHANGE_PACKET_SCHEMA;
+            version = DOMAIN_CHANGE_PACKET_VERSION;
+            break;
+        case 'monitor-once':
+            schema = CLI_DOMAIN_CONTROL_MONITOR_SCHEMA;
+            version = CLI_DOMAIN_CONTROL_MONITOR_VERSION;
+            break;
+        case 'discover':
+            schema = CLI_DISCOVER_SCHEMA;
+            version = CLI_DISCOVER_SCHEMA_VERSION;
+            break;
+        case 'discover-scan':
+            schema = CLI_DISCOVERY_SCAN_SCHEMA;
+            version = CLI_DISCOVERY_SCAN_VERSION;
+            break;
+        case 'posture':
+            schema = CLI_POSTURE_SCHEMA;
+            version = CLI_POSTURE_SCHEMA_VERSION;
+            break;
+        case 'verify-artifact':
+            schema = OFFLINE_ARTIFACT_VERIFICATION_SCHEMA;
+            version = OFFLINE_ARTIFACT_VERIFICATION_VERSION;
+            break;
+        case 'diff':
+            schema = CLI_LOOKUP_DIFF_SCHEMA;
+            version = CLI_LOOKUP_DIFF_VERSION;
+            break;
+        case 'timeline':
+            schema = CLI_LOOKUP_TIMELINE_SCHEMA;
+            version = CLI_LOOKUP_TIMELINE_VERSION;
+            break;
+        default: throw new TypeError('This command has no fixed-workflow output contract.');
+    }
+    const envelope = step.command === 'case-pack' ? value.packet : value;
+    const actualVersion = step.command === 'export' || step.command === 'ct-intake' ? value.schemaVersion : envelope.version;
+    // Only existing format validators admit historical versions. Report-only
+    // steps use the same output versions as the latest public checkpoint writer.
+    const historicalReader = retained && ['lookup', 'export', 'domain-control'].includes(step.command);
+    if (envelope.schema !== schema || schema !== step.produces
+        || (!historicalReader && actualVersion !== version) || !Number.isSafeInteger(actualVersion)) {
+        throw new TypeError('Unsupported workflow output schema or version.');
+    }
+    const id = `sha256:${createHash('sha256').update(canonicalArtifactJsonV2(value)).digest('hex')}`;
+    return Object.freeze({ id, schema, version: Number(actualVersion) });
+}
+export function normalizeWorkflowBindings(plan, value) {
+    if (!Array.isArray(value) || value.length > MAX_INVESTIGATION_RUN_SELECTIONS) {
+        throw new CliUsageError(`Workflow artefact bindings are limited to ${MAX_INVESTIGATION_RUN_SELECTIONS}.`);
+    }
+    const slots = new Set();
+    const bindings = value.map((raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)
+            || !isDeepStrictEqual(Object.keys(raw).sort(), ['input', 'sourceStepId', 'stepId'])) {
+            throw new CliUsageError('Workflow artefact bindings must identify a step, input number and earlier source step.');
+        }
+        const item = raw;
+        const destinationIndex = plan.steps.findIndex((step) => step.id === item.stepId);
+        const sourceIndex = plan.steps.findIndex((step) => step.id === item.sourceStepId);
+        const step = plan.steps[destinationIndex];
+        const source = plan.steps[sourceIndex];
+        const input = Number(item.input);
+        const expected = step ? workflowInputSchemas(step.command) : [];
+        const slot = `${destinationIndex}:${input}`;
+        if (!step || !source || sourceIndex >= destinationIndex || !expected.includes(source.produces)
+            || typeof item.input !== 'number' || !Number.isSafeInteger(input) || input < 1
+            || input > step.arguments.filter((argument) => /^<[^>]+>$/u.test(argument)).length || slots.has(slot)) {
+            throw new CliUsageError('Workflow artefact binding does not match a compatible earlier output and file input in the fixed recipe.');
+        }
+        slots.add(slot);
+        return Object.freeze({ stepId: step.id, input, sourceStepId: source.id });
+    });
+    return Object.freeze(bindings.sort((left, right) => plan.steps.findIndex((step) => step.id === left.stepId) - plan.steps.findIndex((step) => step.id === right.stepId)
+        || left.input - right.input));
+}
+/** Compatible file inputs in the installed recipes, not general CLI pipelines. */
+export function workflowInputSchemas(command) {
+    switch (command) {
+        case 'export':
+        case 'diff':
+        case 'timeline':
+        case 'compare':
+        case 'source-report':
+        case 'brief': return [CLI_LOOKUP_SCHEMA];
+        case 'verify-artifact': return [LOOKUP_EVIDENCE_SCHEMA];
+        case 'sharing-review': return [CLI_CASE_PACK_SCHEMA];
+        default: return [];
+    }
+}
+export function workflowArtifactReference(artifact) {
+    return `workflow-artifact:${artifact.id}`;
+}

package/cli/investigation-checkpoint.mjs

@@ -0,0 +1,10 @@
+import { MAX_INVESTIGATION_RUN_BYTES } from "../packages/contracts/investigation-run.mjs";
+import { prepareLocalDocumentWrite } from "./local-document-checkpoint.mjs";
+/** Preserve the workflow checkpoint interface and shared on-disk lease convention. */
+export async function prepareInvestigationCheckpoint(options) {
+    const checkpoint = await prepareLocalDocumentWrite({
+        ...options, source: options.resumeSource, label: 'Workflow state',
+        maximumInputBytes: MAX_INVESTIGATION_RUN_BYTES, maximumOutputBytes: MAX_INVESTIGATION_RUN_BYTES,
+    });
+    return Object.freeze({ resumeInput: checkpoint.sourceInput, publish: checkpoint.publish, release: checkpoint.release });
+}

package/cli/investigation-folder.mjs

@@ -0,0 +1,114 @@
+import { lstat, mkdir, opendir, realpath } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { readBoundedRegularFileWithin } from "../lib/bounded-file.mjs";
+import { writePrivateFile } from "./output-file.mjs";
+import { INVESTIGATION_PACKAGE_MANIFEST_PATH, MAX_INVESTIGATION_PACKAGE_ENTRIES, investigationPackagePath, prepareInvestigationPackageEntries, } from "../packages/investigation/investigation-package.mjs";
+import { MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES, } from "../packages/investigation/investigation-manifest.mjs";
+export function selectedEvidenceDirectory(value) {
+    if (typeof value !== 'string' || !value || value === '-' || value.length > 4096 || /[\x00-\x1f\x7f]/u.test(value))
+        throw new TypeError('Select one bounded local folder path.');
+    return resolve(value);
+}
+export async function evidenceDirectoryIdentity(path) {
+    const value = await lstat(path);
+    if (!value.isDirectory() || value.isSymbolicLink())
+        throw new TypeError('Evidence folders must be ordinary directories, not symbolic links.');
+    return { device: value.dev, inode: value.ino, modified: value.mtimeMs, changed: value.ctimeMs };
+}
+/** Enumerate only the two declared levels; never walk an arbitrary source tree. */
+export async function readInvestigationFolder(value, signal) {
+    signal?.throwIfAborted();
+    const selected = selectedEvidenceDirectory(value);
+    const before = await evidenceDirectoryIdentity(selected), root = await realpath(selected);
+    const paths = [];
+    let nestedIdentity = null;
+    const directory = await opendir(root);
+    for await (const entry of directory) {
+        signal?.throwIfAborted();
+        if (entry.name === 'artifacts' && entry.isDirectory()) {
+            const nested = join(root, 'artifacts');
+            nestedIdentity = await evidenceDirectoryIdentity(nested);
+            for await (const file of await opendir(nested)) {
+                signal?.throwIfAborted();
+                if (!file.isFile())
+                    throw new TypeError('Evidence folder entries must be regular files.');
+                if (paths.length >= MAX_INVESTIGATION_PACKAGE_ENTRIES)
+                    throw new TypeError('Evidence folder has too many entries.');
+                paths.push(investigationPackagePath(`artifacts/${file.name}`));
+            }
+        }
+        else if (entry.name === INVESTIGATION_PACKAGE_MANIFEST_PATH && entry.isFile()) {
+            if (paths.length >= MAX_INVESTIGATION_PACKAGE_ENTRIES)
+                throw new TypeError('Evidence folder has too many entries.');
+            paths.push(entry.name);
+        }
+        else
+            throw new TypeError('Evidence folders contain only manifest.json and the declared artifacts directory.');
+    }
+    if (!nestedIdentity || !paths.includes(INVESTIGATION_PACKAGE_MANIFEST_PATH) || paths.length < 2)
+        throw new TypeError('Evidence folder is incomplete.');
+    const files = new Map();
+    let total = 0;
+    for (const name of paths.sort()) {
+        signal?.throwIfAborted();
+        const manifest = name === INVESTIGATION_PACKAGE_MANIFEST_PATH;
+        const maximumBytes = manifest ? MAX_INVESTIGATION_MANIFEST_DOCUMENT_BYTES : Math.min(MAX_INVESTIGATION_MANIFEST_ARTIFACT_BYTES, MAX_INVESTIGATION_MANIFEST_TOTAL_BYTES - total);
+        const bytes = await readBoundedRegularFileWithin(root, name, { maximumBytes, minimumBytes: 1, label: 'Evidence folder entry', ...(signal ? { signal } : {}) });
+        if (!manifest)
+            total += bytes.byteLength;
+        files.set(name, bytes);
+    }
+    const unchanged = (left, right) => left.device === right.device && left.inode === right.inode && left.modified === right.modified && left.changed === right.changed;
+    if (await realpath(selected) !== root || !unchanged(before, await evidenceDirectoryIdentity(selected))
+        || !unchanged(nestedIdentity, await evidenceDirectoryIdentity(join(root, 'artifacts'))))
+        throw new TypeError('Evidence folder changed while it was read.');
+    signal?.throwIfAborted();
+    return files;
+}
+/** Never replace an existing folder. The manifest is published only after files. */
+export async function writeInvestigationFolder(value, input, generatedAt, version, signal) {
+    const prepared = await prepareInvestigationPackageEntries(input, generatedAt, version);
+    await writePreparedEvidenceFolder(value, prepared.files, 'artifacts', INVESTIGATION_PACKAGE_MANIFEST_PATH, signal);
+    return prepared.manifest;
+}
+/** Only first-party, generated layouts may use this fresh-directory writer. */
+export async function writePreparedEvidenceFolder(value, files, payloadDirectory, completionFile, signal) {
+    const target = selectedEvidenceDirectory(value);
+    if (!files.has(completionFile) || !/^[a-z0-9.-]+$/u.test(completionFile)
+        || [...files.keys()].some(path => path !== `${payloadDirectory}/` && !/^[a-z0-9.-]+$/u.test(path) && !new RegExp(`^${payloadDirectory}/artifact-[1-9][0-9]{0,2}$`, 'u').test(path)))
+        throw new TypeError('The generated evidence folder layout is invalid.');
+    signal?.throwIfAborted();
+    try {
+        await mkdir(target, { mode: 0o700 });
+    }
+    catch {
+        throw new TypeError('The output folder must not already exist, and its parent must be writable. Existing files were not replaced.');
+    }
+    try {
+        const root = await realpath(target), identity = await evidenceDirectoryIdentity(target);
+        await mkdir(join(root, payloadDirectory), { mode: 0o700 });
+        const artifactsIdentity = await evidenceDirectoryIdentity(join(root, payloadDirectory));
+        const checkLocation = async () => {
+            signal?.throwIfAborted();
+            const current = await evidenceDirectoryIdentity(target), nested = await evidenceDirectoryIdentity(join(root, payloadDirectory));
+            if (await realpath(target) !== root || current.device !== identity.device || current.inode !== identity.inode
+                || nested.device !== artifactsIdentity.device || nested.inode !== artifactsIdentity.inode
+                || await realpath(join(root, payloadDirectory)) !== join(root, payloadDirectory))
+                throw new TypeError('Evidence output folder changed.');
+        };
+        for (const [name, content] of files) {
+            if (name === completionFile || name.endsWith('/'))
+                continue;
+            await checkLocation();
+            await writePrivateFile(join(root, name), content, { beforePublish: checkLocation });
+        }
+        await checkLocation();
+        await writePrivateFile(join(root, completionFile), files.get(completionFile), { beforePublish: checkLocation });
+        await checkLocation();
+    }
+    catch {
+        // Retain only this newly created partial output for deliberate inspection;
+        // recursive cleanup could remove unrelated files added by another process.
+        throw new TypeError('The new evidence folder could not be completed or confirmed. It may contain private partial output; inspect or remove it before choosing a new destination. Existing folders were not replaced.');
+    }
+}