@slicedearth/whoisleuth-cli 2.2.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

@@ -17,8 +17,10 @@ const REVIEW_INLINE_COMMANDS = Object.freeze([
     'compare',
     'page-compare',
     'mail-review',
+    'mail-headers',
     'review-evidence',
     'brief',
+    'case',
     'case-pack',
 ]);
 const ASSURANCE_INLINE_COMMANDS = Object.freeze([

package/cli/input.mjs

@@ -1,6 +1,46 @@
 import { Buffer } from 'node:buffer';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
 import { decodeBoundedUtf8, readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 import { CliUsageError } from "./errors.mjs";
+function headerEnd(bytes) {
+    for (let index = 0; index < bytes.length - 1; index += 1) {
+        if (bytes[index] === 0x0a && bytes[index + 1] === 0x0a)
+            return index;
+        if (index < bytes.length - 3
+            && bytes[index] === 0x0d && bytes[index + 1] === 0x0a
+            && bytes[index + 2] === 0x0d && bytes[index + 3] === 0x0a)
+            return index;
+    }
+    return -1;
+}
+function decodeHeaderStorage(storage, length, maximumBytes, label) {
+    const end = headerEnd(storage.subarray(0, length));
+    if ((end < 0 && length > maximumBytes) || end > maximumBytes) {
+        throw new CliUsageError(`${label} is limited to ${maximumBytes} bytes before the message body.`);
+    }
+    return decodeBoundedUtf8(storage.subarray(0, end < 0 ? length : end), label);
+}
+function appendUntilHeaderEnd(storage, offset, input) {
+    let nextOffset = offset;
+    for (const byte of input) {
+        if (nextOffset >= storage.length)
+            return Object.freeze({ offset: nextOffset, complete: false });
+        storage[nextOffset] = byte;
+        nextOffset += 1;
+        const lfBoundary = nextOffset >= 2
+            && storage[nextOffset - 2] === 0x0a
+            && storage[nextOffset - 1] === 0x0a;
+        const crlfBoundary = nextOffset >= 4
+            && storage[nextOffset - 4] === 0x0d
+            && storage[nextOffset - 3] === 0x0a
+            && storage[nextOffset - 2] === 0x0d
+            && storage[nextOffset - 1] === 0x0a;
+        if (lfBoundary || crlfBoundary)
+            return Object.freeze({ offset: nextOffset, complete: true });
+    }
+    return Object.freeze({ offset: nextOffset, complete: false });
+}
 function abortError(signal) {
     return signal.reason instanceof Error
         ? signal.reason
@@ -60,3 +100,79 @@ export async function readCliTextInput(source, stdin, options) {
         options.signal?.removeEventListener('abort', onAbort);
     }
 }
+/**
+ * Read only the RFC-style header block from a selected regular file or stdin.
+ * The fixed retained allocation includes delimiter look-ahead but accumulates
+ * only bytes through the first header/body boundary. A regular file may be
+ * larger than the header limit while parsing stays tied to the admitted prefix.
+ */
+export async function readCliHeaderInput(source, stdin, options) {
+    if (!Number.isSafeInteger(options.maximumBytes) || options.maximumBytes < 1 || options.maximumBytes > 1024 * 1024) {
+        throw new TypeError('Header input has an invalid byte boundary.');
+    }
+    if (options.signal?.aborted)
+        throw abortError(options.signal);
+    const storage = Buffer.allocUnsafe(options.maximumBytes + 4);
+    if (source) {
+        let handle;
+        try {
+            handle = await open(source, constants.O_RDONLY | constants.O_NONBLOCK);
+            const before = await handle.stat();
+            if (!before.isFile())
+                throw new CliUsageError(`${options.label} must be a regular file.`);
+            let offset = 0;
+            let complete = false;
+            const chunk = Buffer.allocUnsafe(Math.min(4 * 1024, storage.length));
+            while (offset < storage.length && !complete) {
+                if (options.signal?.aborted)
+                    throw abortError(options.signal);
+                const result = await handle.read(chunk, 0, Math.min(chunk.length, storage.length - offset), null);
+                if (result.bytesRead === 0)
+                    break;
+                ({ offset, complete } = appendUntilHeaderEnd(storage, offset, chunk.subarray(0, result.bytesRead)));
+            }
+            chunk.fill(0);
+            const after = await handle.stat();
+            if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+                throw new CliUsageError(`${options.label} changed while it was being read.`);
+            }
+            return decodeHeaderStorage(storage, offset, options.maximumBytes, options.label);
+        }
+        catch (error) {
+            if (error instanceof CliUsageError || options.signal?.aborted)
+                throw error;
+            const message = error instanceof Error ? error.message : `${options.label} could not be read.`;
+            throw new CliUsageError(message);
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    if (!stdin || stdin.isTTY)
+        return '';
+    let offset = 0;
+    const onAbort = () => {
+        if ('destroy' in stdin && typeof stdin.destroy === 'function')
+            stdin.destroy(abortError(options.signal));
+    };
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for await (const chunk of stdin) {
+            if (options.signal?.aborted)
+                throw abortError(options.signal);
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const retained = appendUntilHeaderEnd(storage, offset, bytes);
+            offset = retained.offset;
+            if (retained.complete)
+                break;
+            if (offset >= storage.length)
+                break;
+        }
+        if (options.signal?.aborted)
+            throw abortError(options.signal);
+        return decodeHeaderStorage(storage, offset, options.maximumBytes, options.label);
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+    }
+}

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'
@@ -198,6 +194,19 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
 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.'
+        : !report.artifact.versionSupported
+            ? 'Use a WHOISleuth release that supports this exact version, or re-export it with its last supported release.'
+            : !report.verification.assuranceSatisfied
+                ? 'Do not import or share this artefact yet; run verify-artifact and resolve the reported structure or integrity failure.'
+                : report.compatibility.fullyImportable === false
+                    ? 'Review unsupported, blocked, skipped or pruned records before selecting any import.'
+                    : browser?.import === 'supported'
+                        ? 'Open the browser import preview and review the proposed additions and updates before applying them.'
+                        : cli?.read === 'supported'
+                            ? 'Use the declared offline CLI reader; browser import is not supported for this artefact.'
+                            : 'Retain the verification result and use only the operations declared above.';
     return [
         'Interchange fidelity report',
         `Recognised     ${report.recognised ? 'yes' : 'no'}`,
@@ -219,6 +228,7 @@ export function formatInterchangeFidelityReport(report) {
         '',
         `Preserved      ${report.compatibility.preservedFieldGroups.join(', ') || 'none declared'}`,
         `Excluded       ${report.compatibility.excludedFieldGroups.join(', ') || 'none declared'}`,
+        `Next action    ${nextAction}`,
         '',
         ...report.limitations.map((item) => `Limitation: ${item}`),
         '',

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}`;
+}