@slicedearth/whoisleuth-cli 2.3.0 → 2.4.0

package/cli/formatters/terminal-technology.mjs

@@ -0,0 +1,114 @@
+import { MAX_EVIDENCE_PER_TECHNOLOGY, MAX_LIBRARY_FINDINGS, MAX_TECHNOLOGY_FINDINGS, } from "../../lib/lookup-child-profile-contract.mjs";
+import { TECHNOLOGY_EVIDENCE_ROLE_ORDER, technologyEvidenceRoles, } from "../../lib/technology-evidence-role.mjs";
+import { MAX_OBSERVATION_LIMITATIONS, readObservationTime } from "../../packages/evidence/observation.mjs";
+import { boundedTerminalList, safeTerminalValue, terminalCount, terminalRecord, titleCase } from "./terminal-shared.mjs";
+const ROLE_LABELS = {
+    observed_edge: 'Observed edge',
+    application_platform: 'App platform',
+    framework_runtime: 'Framework/run',
+    embedded_dependency: 'Embedded deps',
+};
+const SUMMARY_FINDINGS = 6;
+const SUMMARY_NAMESERVERS = 5;
+function observationLine(label, value, generatedAt) {
+    const time = readObservationTime(value, generatedAt);
+    if (!time.observedAt)
+        return `${label.padEnd(15)}Observed time unavailable`;
+    const age = time.ageDays === null ? 'age unavailable'
+        : time.ageDays === 0 ? 'less than a day old at output generation'
+            : `${time.ageDays} day${time.ageDays === 1 ? '' : 's'} old at output generation`;
+    return `${label.padEnd(15)}${time.observedAt} · ${age}`;
+}
+function appendLimitations(lines, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const limitation of value.slice(0, MAX_OBSERVATION_LIMITATIONS)) {
+        lines.push(`  Limit        ${safeTerminalValue(limitation)}`);
+    }
+}
+/** Presents admitted source records; it never collects or infers a hidden origin. */
+export function appendTechnologyLines(lines, input) {
+    const { technology, libraries, nameservers, generatedAt, detail } = input;
+    if (!technology.status && technology.source !== 'derived')
+        return;
+    const suppliedFindings = Array.isArray(technology.findings) ? technology.findings : [];
+    const findings = suppliedFindings.slice(0, MAX_TECHNOLOGY_FINDINGS).map((value) => {
+        const finding = terminalRecord(value);
+        return { finding, roles: technologyEvidenceRoles(finding) };
+    });
+    lines.push(`Technology     ${titleCase(technology.status)} · ${findings.length} indicator${findings.length === 1 ? '' : 's'}`);
+    if (suppliedFindings.length > findings.length)
+        lines.push('Technology     Additional findings exceed the admitted profile limit');
+    if (detail === 'summary')
+        return;
+    lines.push(observationLine('Tech observed', technology.observedAt, generatedAt));
+    if (detail === 'standard' && findings.length) {
+        const visible = findings.slice(0, SUMMARY_FINDINGS).map(({ finding }) => {
+            const qualifiers = [finding.category, finding.confidence ? `${safeTerminalValue(finding.confidence)} signature strength` : null]
+                .filter(Boolean).map((value) => safeTerminalValue(value));
+            return `${safeTerminalValue(finding.name, 'Unnamed indicator')}${qualifiers.length ? ` (${qualifiers.join(', ')})` : ''}`;
+        });
+        lines.push(`Indicators     ${boundedTerminalList(visible, findings.length - visible.length)}`);
+    }
+    const retainedNameservers = Array.isArray(nameservers) ? nameservers : [];
+    const visibleNameservers = retainedNameservers.slice(0, SUMMARY_NAMESERVERS).map((value) => safeTerminalValue(value));
+    lines.push(`Nameservers   ${visibleNameservers.length ? boundedTerminalList(visibleNameservers, retainedNameservers.length - visibleNameservers.length) : 'Unavailable'} · identity does not establish operator or web-host ownership`);
+    for (const role of TECHNOLOGY_EVIDENCE_ROLE_ORDER) {
+        const matching = findings.filter((item) => item.roles.includes(role));
+        const names = matching.slice(0, SUMMARY_FINDINGS).map(({ finding }) => safeTerminalValue(finding.name, 'Unnamed indicator'));
+        lines.push(`${ROLE_LABELS[role].padEnd(15)}${names.length ? boundedTerminalList(names, matching.length - names.length) : 'None retained'}`);
+    }
+    lines.push('Origin host    Not established from retained evidence');
+    if (detail === 'verbose') {
+        for (const { finding, roles } of findings) {
+            lines.push(`Indicator      ${safeTerminalValue(finding.name, 'Unnamed indicator')}`);
+            lines.push(`  Role         ${roles.map((role) => ROLE_LABELS[role]).join(', ') || 'Not retained'}`);
+            lines.push(`  Strength     ${safeTerminalValue(finding.confidence, 'Unknown')} signature strength`);
+            const suppliedEvidence = Array.isArray(finding.evidence) ? finding.evidence : [];
+            const evidence = suppliedEvidence.slice(0, MAX_EVIDENCE_PER_TECHNOLOGY);
+            if (!evidence.length)
+                lines.push('  Signal       No detailed signal was retained');
+            for (const value of evidence) {
+                const item = terminalRecord(value);
+                if (typeof item.source !== 'string' || !item.source.trim()
+                    || typeof item.description !== 'string' || !item.description.trim()) {
+                    lines.push('  Signal       Incomplete retained signal record');
+                    continue;
+                }
+                const role = TECHNOLOGY_EVIDENCE_ROLE_ORDER.find((candidate) => candidate === item.role);
+                lines.push(`  Source       ${safeTerminalValue(item.source, 'Not retained')} · ${role ? ROLE_LABELS[role] : 'Role not retained'}`);
+                lines.push(`  Signal       ${safeTerminalValue(item.description, 'Not retained')}`);
+            }
+            if (suppliedEvidence.length > evidence.length)
+                lines.push('  Limit        Additional signals exceed the admitted profile limit');
+        }
+        appendLimitations(lines, technology.limitations);
+    }
+    if (libraries.profileVersion !== 1 && libraries.profileVersion !== 2 && libraries.source !== 'derived')
+        return;
+    const suppliedLibraries = Array.isArray(libraries.findings) ? libraries.findings : [];
+    const libraryFindings = suppliedLibraries.slice(0, MAX_LIBRARY_FINDINGS).map(terminalRecord);
+    const advisoryMatches = libraryFindings.filter((finding) => terminalCount(finding.advisoryCount) > 0).length;
+    lines.push(`JS libraries   ${titleCase(libraries.status)} · ${libraryFindings.length} apparent · ${advisoryMatches} with catalogue advisory match${advisoryMatches === 1 ? '' : 'es'}`);
+    lines.push(observationLine('Lib observed', libraries.observedAt, generatedAt));
+    if (suppliedLibraries.length > libraryFindings.length)
+        lines.push('JS libraries   Additional findings exceed the admitted profile limit');
+    if (detail !== 'verbose')
+        return;
+    const catalogue = terminalRecord(libraries.catalog);
+    lines.push(`Catalogue      ${safeTerminalValue(catalogue.name, 'Component catalogue')} · ${safeTerminalValue(catalogue.version, 'Version unavailable')}`);
+    for (const library of libraryFindings) {
+        lines.push(`Library        ${safeTerminalValue(library.name, 'Unnamed library')} · ${safeTerminalValue(library.apparentVersion, 'Version unavailable')}`);
+        const methods = Array.isArray(library.detectionMethods) ? library.detectionMethods.slice(0, 4).map((value) => safeTerminalValue(value)) : [];
+        lines.push(`  Detected by  ${methods.join(', ') || 'Not retained'}`);
+        lines.push(`  Advisories   ${terminalCount(library.advisoryCount)} catalogue matches`);
+        if (library.highestSeverity)
+            lines.push(`  Severity     ${safeTerminalValue(library.highestSeverity)}`);
+        for (const [field, label] of [['advisoryIdentifiers', 'Identifier'], ['knownExploitedIdentifiers', 'Known exploited']]) {
+            const values = Array.isArray(library[field]) ? library[field] : [];
+            for (const value of values.slice(0, 16))
+                lines.push(`  ${label.padEnd(15)} ${safeTerminalValue(value)}`);
+        }
+    }
+    appendLimitations(lines, libraries.limitations);
+}

package/cli/inline-command-families.mjs

@@ -20,6 +20,7 @@ const REVIEW_INLINE_COMMANDS = Object.freeze([
     'mail-headers',
     'review-evidence',
     'brief',
+    'case',
     'case-pack',
 ]);
 const ASSURANCE_INLINE_COMMANDS = Object.freeze([

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;
@@ -123,7 +119,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'

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 "./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.');
+    }
+}