@slicedearth/whoisleuth-cli 1.45.0 → 2.0.0

package/cli/investigation-plan.mjs

@@ -1,17 +1,19 @@
 import { domainToASCII } from 'node:url';
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { INVESTIGATION_PLAN_RECIPES, RUNNABLE_INVESTIGATION_PLAN_RECIPES, cliInvocationNetworkEffect, } from "./command-reference.mjs";
 export const CLI_INVESTIGATION_PLAN_SCHEMA = 'whoisleuth.cli.investigation-plan';
 export const CLI_INVESTIGATION_PLAN_VERSION = 1;
-export const INVESTIGATION_PLAN_RECIPES = [
-    'domain-triage',
-    'lookalike-review',
-    'owned-domain-review',
-    'historical-comparison',
-];
+export const CLI_WORKFLOW_RECIPE_CATALOGUE_SCHEMA = 'whoisleuth.cli.workflow-recipe-catalogue';
+export const CLI_WORKFLOW_RECIPE_CATALOGUE_VERSION = 1;
+export { INVESTIGATION_PLAN_RECIPES, RUNNABLE_INVESTIGATION_PLAN_RECIPES };
 const RECIPES = Object.freeze({
     'domain-triage': Object.freeze({
+        id: 'domain-triage',
         label: 'New domain triage',
-        requiresDomain: true,
-        objective: 'Collect and preserve a source-aware registration, DNS, HTTP, TLS, page, and network-context review.',
+        subjectRequirement: 'domain',
+        objective: 'Collect and preserve separately attributed registration, DNS, HTTP, TLS, page, and network-context evidence.',
+        runnable: true,
+        limitations: Object.freeze(['Collection remains analyst-triggered and source limitations remain explicit.']),
         steps: (domain) => Object.freeze([
             step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
             step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Select the reviewed lookup file; the plan never guesses a path.'),
@@ -19,9 +21,12 @@ const RECIPES = Object.freeze({
         ]),
     }),
     'lookalike-review': Object.freeze({
+        id: 'lookalike-review',
         label: 'Lookalike candidate review',
-        requiresDomain: false,
+        subjectRequirement: 'brand_or_domain',
         objective: 'Generate a bounded candidate queue, collect only the selected scope, and retain a reviewed candidate lookup.',
+        runnable: true,
+        limitations: Object.freeze(['Candidate generation does not establish registration, control, intent, or maliciousness.']),
         steps: (subject) => Object.freeze([
             step('generate', 'Generate candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and suppressions before collection.'),
             step('scan', 'Collect a bounded candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Fast collection is a triage boundary; partial or inconclusive authority evidence remains explicit.'),
@@ -29,9 +34,12 @@ const RECIPES = Object.freeze({
         ]),
     }),
     'owned-domain-review': Object.freeze({
+        id: 'owned-domain-review',
         label: 'Owned domain posture review',
-        requiresDomain: true,
+        subjectRequirement: 'domain',
         objective: 'Review current passive posture and compare supplied observations with an analyst-authored control manifest.',
+        runnable: true,
+        limitations: Object.freeze(['Use only for a domain the analyst owns or is authorised to review.']),
         steps: (domain) => Object.freeze([
             step('posture', 'Collect bounded DNS posture', 'posture', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.posture', 'Review mail profile and delegation evidence before interpreting missing records.'),
             step('lookup', 'Collect supporting Deep evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain separately attributed registration, DNS, TLS, and page observations.'),
@@ -39,17 +47,160 @@ const RECIPES = Object.freeze({
         ]),
     }),
     'historical-comparison': Object.freeze({
+        id: 'historical-comparison',
         label: 'Historical observation comparison',
-        requiresDomain: true,
+        subjectRequirement: 'domain',
         objective: 'Collect a current observation and compare it with analyst-selected saved observations without merging source states.',
+        runnable: true,
+        limitations: Object.freeze(['A later observation does not retroactively refresh retained evidence.']),
         steps: (domain) => Object.freeze([
             step('current', 'Collect the current lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'A current request does not refresh or validate older provider-reported history.'),
             step('diff', 'Compare two selected observations', 'diff', ['<previous.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Equal, different, conflicting, and unavailable evidence remain separate.'),
             step('timeline', 'Build a bounded local timeline', 'timeline', ['<oldest.json>', '<newer.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-timeline', 'Choose two to twenty same-domain files in chronological scope.'),
         ]),
     }),
+    'campaign-review': Object.freeze({
+        id: 'campaign-review',
+        label: 'Campaign candidate review',
+        subjectRequirement: 'brand_or_domain',
+        objective: 'Prepare a bounded candidate set, collect a deliberately selected queue, and review retained evidence without asserting campaign attribution.',
+        runnable: false,
+        limitations: Object.freeze(['Grouping candidates is analyst triage and does not prove common ownership, control, infrastructure, or intent.']),
+        steps: (subject) => Object.freeze([
+            step('prepare', 'Prepare candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and bounded omissions before selecting a collection scope.'),
+            step('collect', 'Collect the selected candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Treat partial and inconclusive authority results as explicit outcomes.'),
+            step('review', 'Review selected retained evidence', 'review-evidence', ['<selected-evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.offline-evidence-review', 'Keep source observations separate and record any campaign grouping as analyst-authored.'),
+        ]),
+    }),
+    'certificate-anomaly': Object.freeze({
+        id: 'certificate-anomaly',
+        label: 'Certificate anomaly review',
+        subjectRequirement: 'domain',
+        objective: 'Review bounded certificate observations alongside current source-qualified domain evidence without treating issuance as proof of control or intent.',
+        runnable: false,
+        limitations: Object.freeze(['Certificate observations are separately attributed and do not establish current service control.']),
+        steps: (domain) => Object.freeze([
+            step('search', 'Collect bounded certificate observations', 'ct-search', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.ct-search', 'Review source availability, truncation, and observation timing.'),
+            step('intake', 'Normalise the selected observations', 'ct-intake', ['<certificate-events.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.ct-event-batch', 'Only selected saved observations enter the offline intake.'),
+            step('corroborate', 'Collect supporting domain evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Compare evidence families without collapsing certificate and registration identities.'),
+        ]),
+    }),
+    'registry-disagreement': Object.freeze({
+        id: 'registry-disagreement',
+        label: 'Registry disagreement review',
+        subjectRequirement: 'domain',
+        objective: 'Collect separately attributed registration evidence and review conflicting publications without selecting an arbitrary source as truth.',
+        runnable: false,
+        limitations: Object.freeze(['Only authority-aware registration evidence may decide availability; disagreement remains explicit.']),
+        steps: (domain) => Object.freeze([
+            step('collect', 'Collect source-qualified registration evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain RDAP, registrar RDAP, WHOIS, and authority states separately.'),
+            step('compare', 'Compare registry publications offline', 'compare', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.compare', 'Do not convert conflicting or unavailable publications into equivalence.'),
+            step('report', 'Prepare a target-free source report', 'source-report', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.source-reliability-report', 'The report describes source behaviour, not ownership, safety, or legal status.'),
+        ]),
+    }),
+    'evidence-handoff': Object.freeze({
+        id: 'evidence-handoff',
+        label: 'Reviewed evidence handoff',
+        subjectRequirement: 'review_label',
+        objective: 'Verify, minimise, and package analyst-selected evidence for a deliberate handoff without transmitting or submitting it.',
+        runnable: false,
+        limitations: Object.freeze(['The recipe prepares local material only; sharing remains a separate deliberate action.']),
+        steps: () => Object.freeze([
+            step('verify', 'Verify the selected artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Verification checks structure and integrity, not the truth or currency of observations.'),
+            step('package', 'Build a reviewed public Case-pack', 'case-pack', ['<cases.json>', '--audience', 'public', '--reviewed', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.case-pack', 'Review minimisation and audience projection before retaining the separate package.'),
+            step('lint', 'Review deliberate-sharing metadata', 'sharing-review', ['<package.json>', '--marking', 'clear', '--recipient-scope', 'public', '--purpose', 'reviewed evidence handoff', '--human-reviewed', '--personal-data-reviewed', '--redactions-confirmed', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.sharing-review', 'A clear lint result does not send, upload, publish, or authorise the artefact.'),
+        ]),
+    }),
+    'planned-domain-change': Object.freeze({
+        id: 'planned-domain-change',
+        label: 'Planned domain change',
+        subjectRequirement: 'domain',
+        objective: 'Review an analyst-authored desired state and prepare bounded change material without changing DNS, registry, mail, or hosted configuration.',
+        runnable: false,
+        limitations: Object.freeze(['Planning and packaging never apply, submit, schedule, or enforce a change.']),
+        steps: () => Object.freeze([
+            step('control', 'Review the desired-state manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-control-review', 'Only supplied complete observations may produce drift.'),
+            step('assure', 'Review change and recovery assumptions', 'assurance', ['<assurance-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-assurance', 'Record uncertainty, rollback dependencies, and unavailable evidence explicitly.'),
+            step('package', 'Build a reviewed change packet', 'change-packet', ['<change-packet-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'The packet is local reviewed material and performs no submission or enforcement.'),
+        ]),
+    }),
+    'post-change-verification': Object.freeze({
+        id: 'post-change-verification',
+        label: 'Post-change verification',
+        subjectRequirement: 'domain',
+        objective: 'Perform one explicit later observation and compare it with analyst-selected retained evidence after an authorised change.',
+        runnable: false,
+        limitations: Object.freeze(['This is a one-time recheck, not monitoring setup or proof that every resolver or service has converged.']),
+        steps: () => Object.freeze([
+            step('recheck', 'Run one bounded retained-manifest review', 'monitor-once', ['<manifest.json>', '--limit', '1', '--json'], 'network', 'network_disclosure', 'whoisleuth.domain-control-review', 'One later observation may remain partial, unavailable, stale, or conflicting.'),
+            step('compare', 'Compare selected before and after evidence', 'diff', ['<before.json>', '<after.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Materiality is derived from compatible retained evidence and does not infer intent.'),
+            step('record', 'Record reviewed completion material', 'change-packet', ['<post-change-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'Recording reviewed material does not submit it or start automatic monitoring.'),
+        ]),
+    }),
 });
+export const INVESTIGATION_RECIPE_REGISTRY = RECIPES;
+export const INVESTIGATION_PLAN_RECIPE_LABELS = Object.freeze(Object.fromEntries(INVESTIGATION_PLAN_RECIPES.map((recipe) => [recipe, RECIPES[recipe].label])));
+export function isRunnableInvestigationRecipe(value) {
+    return RUNNABLE_INVESTIGATION_PLAN_RECIPES.includes(value);
+}
+function recipeCatalogueEntry(recipe) {
+    const exampleSubject = recipe.subjectRequirement === 'domain' ? 'example.test' : 'Example Organisation';
+    const steps = recipe.steps(exampleSubject).map((item) => Object.freeze({
+        id: item.id,
+        label: item.label,
+        command: item.command,
+        exampleArguments: item.arguments,
+        mode: item.mode,
+        approval: item.approval,
+        produces: item.produces,
+        completion: item.completion,
+    }));
+    return Object.freeze({
+        id: recipe.id,
+        label: recipe.label,
+        objective: recipe.objective,
+        subjectRequirement: recipe.subjectRequirement,
+        runnableByWorkflowRun: recipe.runnable,
+        networkModes: Object.freeze([...new Set(steps.map((item) => item.mode))]),
+        approvals: Object.freeze([...new Set(steps.map((item) => item.approval))]),
+        steps: Object.freeze(steps),
+        limitations: recipe.limitations,
+    });
+}
+export function buildWorkflowRecipeCatalogue(recipeId = null) {
+    const selected = recipeId === null ? INVESTIGATION_PLAN_RECIPES : [recipeId];
+    return Object.freeze({
+        schema: CLI_WORKFLOW_RECIPE_CATALOGUE_SCHEMA,
+        version: CLI_WORKFLOW_RECIPE_CATALOGUE_VERSION,
+        recipes: Object.freeze(selected.map((id) => recipeCatalogueEntry(RECIPES[id]))),
+        limitations: Object.freeze([
+            'Catalogue and explanation modes are fixed metadata. They make no request, read no evidence file, and execute no step.',
+            'workflow-run remains limited to recipes explicitly marked runnable by the installed registry.',
+        ]),
+    });
+}
+export function formatWorkflowRecipeCatalogue(catalogue) {
+    return [
+        'WHOISleuth workflow recipes',
+        '',
+        ...catalogue.recipes.flatMap((recipe) => [
+            `${recipe.id} — ${recipe.label}`,
+            `  Subject: ${recipe.subjectRequirement.replaceAll('_', ' ')}`,
+            `  Workflow run: ${recipe.runnableByWorkflowRun ? 'supported' : 'plan and explanation only'}`,
+            `  ${recipe.objective}`,
+            ...recipe.steps.map((item, index) => `  ${index + 1}. ${item.label} [${item.mode}; ${item.approval.replaceAll('_', ' ')}]`),
+            ...recipe.limitations.map((item) => `  Limitation: ${item}`),
+            '',
+        ]),
+        ...catalogue.limitations.map((item) => `Limitation: ${item}`),
+        '',
+    ].join('\n');
+}
 function step(id, label, command, args, mode, approval, produces, completion) {
+    const invocationEffect = cliInvocationNetworkEffect(command, args);
+    if ((mode === 'network') !== (invocationEffect === 'network')) {
+        throw new Error(`Investigation step ${id} does not match the registered network effect for ${command}.`);
+    }
     return Object.freeze({ id, label, command, arguments: Object.freeze([...args]), mode, approval, produces, completion });
 }
 function boundedSubject(value) {
@@ -71,17 +222,17 @@ export function buildInvestigationPlan(recipeId, subjectValue, generatedAtValue
     if (!recipe)
         throw new TypeError('Investigation-plan recipe is unsupported.');
     const suppliedSubject = boundedSubject(subjectValue);
-    const subject = recipe.requiresDomain ? normalizedDomain(suppliedSubject) : suppliedSubject.toLowerCase();
+    const subject = recipe.subjectRequirement === 'domain' ? normalizedDomain(suppliedSubject) : suppliedSubject.toLowerCase();
     if (!subject)
         throw new TypeError('This investigation-plan recipe requires one valid domain.');
-    const parsedTime = Date.parse(generatedAtValue);
-    if (!Number.isFinite(parsedTime))
-        throw new TypeError('Investigation-plan generation time is invalid.');
+    const generatedAt = normalizeExplicitIsoTimestamp(generatedAtValue);
+    if (!generatedAt)
+        throw new TypeError('Investigation-plan generation time must use an explicit timezone.');
     const steps = recipe.steps(subject);
     return Object.freeze({
         schema: CLI_INVESTIGATION_PLAN_SCHEMA,
         version: CLI_INVESTIGATION_PLAN_VERSION,
-        generatedAt: new Date(parsedTime).toISOString(),
+        generatedAt,
         recipe: Object.freeze({ id: recipeId, label: recipe.label, objective: recipe.objective }),
         subject,
         execution: 'plan_only',

package/cli/investigation-run.mjs

@@ -1,6 +1,8 @@
 import { Buffer } from 'node:buffer';
-import { buildInvestigationPlan, } from "./investigation-plan.mjs";
+import { buildInvestigationPlan, isRunnableInvestigationRecipe, } from "./investigation-plan.mjs";
 import { CliUsageError } from "./errors.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
 export const CLI_INVESTIGATION_RUN_SCHEMA = 'whoisleuth.cli.investigation-run';
 export const CLI_INVESTIGATION_RUN_VERSION = 1;
 export const MAX_INVESTIGATION_RUN_BYTES = 24 * 1024 * 1024;
@@ -9,54 +11,101 @@ function boundedResult(value) {
         throw new CliUsageError(`Investigation step output is limited to ${MAX_INVESTIGATION_RUN_BYTES} bytes.`);
     }
     try {
+        scanBoundedJson(value);
         return JSON.parse(value);
     }
-    catch {
+    catch (cause) {
+        if (cause instanceof TypeError && cause.message !== 'Artefact input is not valid JSON.') {
+            throw new CliUsageError(`Investigation step output ${cause.message.replace(/^Artefact JSON /u, '')}`);
+        }
         return value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, '').slice(0, MAX_INVESTIGATION_RUN_BYTES);
     }
 }
-function parseResumeState(input, recipe, subject) {
+function resultSchema(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) && typeof value.schema === 'string'
+        ? String(value.schema)
+        : null;
+}
+function sameArguments(left, right) {
+    return Array.isArray(left)
+        && left.length === right.length
+        && left.every((value, index) => typeof value === 'string' && value === right[index]);
+}
+function parseResumeState(input, plan) {
     if (!input)
         return [];
     if (Buffer.byteLength(input, 'utf8') > MAX_INVESTIGATION_RUN_BYTES)
         throw new CliUsageError('Investigation resume state exceeds the 24 MiB limit.');
+    const normalizedInput = input.replace(/^\uFEFF/u, '');
+    try {
+        scanBoundedJson(normalizedInput);
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : '';
+        if (detail === 'Artefact input is not valid JSON.')
+            throw new CliUsageError('Investigation resume state must be valid JSON.');
+        throw new CliUsageError(detail ? `Investigation resume state ${detail.replace(/^Artefact JSON /u, '')}` : 'Investigation resume state must be valid JSON.');
+    }
     let parsed;
     try {
-        parsed = JSON.parse(input.replace(/^\uFEFF/u, ''));
+        parsed = JSON.parse(normalizedInput);
     }
     catch {
         throw new CliUsageError('Investigation resume state must be valid JSON.');
     }
     const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-    if (root.schema !== CLI_INVESTIGATION_RUN_SCHEMA || root.version !== CLI_INVESTIGATION_RUN_VERSION || root.recipe !== recipe || root.subject !== subject || !Array.isArray(root.completedSteps)) {
+    if (root.schema !== CLI_INVESTIGATION_RUN_SCHEMA || root.version !== CLI_INVESTIGATION_RUN_VERSION || root.recipe !== plan.recipe.id || root.subject !== plan.subject || !Array.isArray(root.completedSteps)) {
         throw new CliUsageError('Investigation resume state must match this versioned recipe and subject.');
     }
-    return root.completedSteps.slice(0, 16).flatMap((value) => {
-        if (!value || typeof value !== 'object' || Array.isArray(value))
-            return [];
+    if (root.completedSteps.length > plan.steps.length) {
+        throw new CliUsageError('Investigation resume state contains more steps than the installed fixed recipe.');
+    }
+    const completed = [];
+    for (const [index, value] of root.completedSteps.entries()) {
+        const planned = plan.steps[index];
+        if (!planned || !value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new CliUsageError('Investigation resume state contains a malformed or out-of-order step.');
+        }
         const item = value;
-        if (typeof item.id !== 'string' || typeof item.command !== 'string' || !Array.isArray(item.arguments) || !['offline', 'network'].includes(String(item.mode)) || !Number.isSafeInteger(item.exitCode))
-            return [];
-        return [Object.freeze({
-                id: item.id,
-                command: item.command,
-                arguments: Object.freeze(item.arguments.filter((entry) => typeof entry === 'string').slice(0, 32)),
-                mode: item.mode,
-                exitCode: Number(item.exitCode),
-                result: item.result,
-            })];
-    });
+        if (item.id !== planned.id
+            || item.command !== planned.command
+            || item.mode !== planned.mode
+            || !sameArguments(item.arguments, planned.arguments)
+            || !Number.isSafeInteger(item.exitCode)) {
+            throw new CliUsageError('Investigation resume state does not match the installed fixed recipe.');
+        }
+        const exitCode = Number(item.exitCode);
+        if (exitCode !== 0 && exitCode !== 2) {
+            if (index !== root.completedSteps.length - 1) {
+                throw new CliUsageError('A failed investigation step must be the final retained step.');
+            }
+            break;
+        }
+        if (resultSchema(item.result) !== planned.produces) {
+            throw new CliUsageError('Investigation resume state contains output from an unexpected command contract.');
+        }
+        completed.push(Object.freeze({
+            id: planned.id,
+            command: planned.command,
+            arguments: planned.arguments,
+            mode: planned.mode,
+            exitCode,
+            result: item.result,
+        }));
+    }
+    return completed;
 }
 export async function runInvestigationRecipe(recipe, subjectValue, options) {
+    if (!isRunnableInvestigationRecipe(recipe)) {
+        throw new CliUsageError('workflow-run supports only installed recipes whose exact steps satisfy the execution contract.');
+    }
     const plan = buildInvestigationPlan(recipe, subjectValue, options.generatedAt);
-    const prior = parseResumeState(options.resumeInput, recipe, plan.subject);
-    const allowedStepIds = new Set(plan.steps.map((step) => step.id));
-    if (prior.some((step) => !allowedStepIds.has(step.id)))
-        throw new CliUsageError('Investigation resume state contains a step outside the fixed recipe.');
+    const prior = parseResumeState(options.resumeInput, plan);
     const completed = [...prior];
     let state = 'complete';
     let currentStep = null;
     for (const step of plan.steps) {
+        options.signal?.throwIfAborted();
         if (completed.some((item) => item.id === step.id))
             continue;
         currentStep = step;
@@ -69,13 +118,20 @@ export async function runInvestigationRecipe(recipe, subjectValue, options) {
             break;
         }
         const result = await options.execute(step.command, step.arguments);
+        if (result.exitCode === EXIT_CODES.CANCELLED) {
+            throw options.signal?.reason || new DOMException('Cancelled', 'AbortError');
+        }
+        const parsedResult = boundedResult(result.stdout);
+        if ((result.exitCode === 0 || result.exitCode === 2) && resultSchema(parsedResult) !== step.produces) {
+            throw new CliUsageError(`Investigation step ${step.id} returned an unexpected command contract.`);
+        }
         completed.push(Object.freeze({
             id: step.id,
             command: step.command,
             arguments: step.arguments,
             mode: step.mode,
             exitCode: result.exitCode,
-            result: boundedResult(result.stdout),
+            result: parsedResult,
         }));
         if (result.exitCode !== 0 && result.exitCode !== 2) {
             state = 'step_failed';

package/cli/local-mmdb-review.mjs

@@ -1,9 +1,11 @@
-import { stat } from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
+import { open, realpath } from 'node:fs/promises';
 import { isIP } from 'node:net';
-import { open } from 'maxmind';
+import { Reader } from 'maxmind';
 import { formatIpPrefix, parseIpPrefix } from "../lib/ip-prefix.mjs";
 import { CliUsageError } from "./errors.mjs";
 export const LOCAL_MMDB_QUERY_SCHEMA = 'whoisleuth.local-mmdb-query';
+export const LOCAL_MMDB_QUERY_VERSION = 1;
 export const MAX_LOCAL_MMDB_BYTES = 512 * 1024 * 1024;
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -17,6 +19,43 @@ function names(value) {
     const source = record(value);
     return boundedText(source.en, 120);
 }
+async function readStableMmdb(databasePath) {
+    let handle = null;
+    try {
+        const resolvedPath = await realpath(databasePath);
+        handle = await open(resolvedPath, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW);
+        const before = await handle.stat();
+        if (!before.isFile() || before.size <= 0 || before.size > MAX_LOCAL_MMDB_BYTES) {
+            throw new CliUsageError(`The supplied MMDB must be a file no larger than ${MAX_LOCAL_MMDB_BYTES} bytes.`);
+        }
+        const database = Buffer.allocUnsafe(before.size);
+        let offset = 0;
+        while (offset < database.length) {
+            const { bytesRead } = await handle.read(database, offset, database.length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        const after = await handle.stat();
+        if (offset !== database.length
+            || before.dev !== after.dev
+            || before.ino !== after.ino
+            || before.size !== after.size
+            || before.mtimeMs !== after.mtimeMs
+            || before.ctimeMs !== after.ctimeMs) {
+            throw new CliUsageError('The supplied MMDB changed while it was being read.');
+        }
+        return database;
+    }
+    catch (cause) {
+        if (cause instanceof CliUsageError)
+            throw cause;
+        throw new CliUsageError('The supplied MMDB file could not be read.');
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
 export async function reviewLocalMmdb(input, databasePath) {
     const address = boundedText(input.address, 64)?.toLowerCase() ?? '';
     const sourceLabel = boundedText(input.sourceLabel, 120);
@@ -27,21 +66,13 @@ export async function reviewLocalMmdb(input, databasePath) {
     if (!sourceLabel || !databaseVersion || !license) {
         throw new CliUsageError('Local MMDB review requires bounded sourceLabel, databaseVersion, and licence metadata.');
     }
-    let info;
-    try {
-        info = await stat(databasePath);
-    }
-    catch {
-        throw new CliUsageError('The supplied MMDB file could not be read.');
-    }
-    if (!info.isFile() || info.size <= 0 || info.size > MAX_LOCAL_MMDB_BYTES) {
-        throw new CliUsageError(`The supplied MMDB must be a file no larger than ${MAX_LOCAL_MMDB_BYTES} bytes.`);
-    }
     let reader;
     try {
-        reader = await open(databasePath, { cache: { max: 1_000 } });
+        reader = new Reader(await readStableMmdb(databasePath));
     }
-    catch {
+    catch (cause) {
+        if (cause instanceof CliUsageError)
+            throw cause;
         throw new CliUsageError('The supplied file is not a readable MaxMind DB database.');
     }
     const [rawMatch, prefixLength] = reader.getWithPrefixLength(address);

package/cli/lookalike-calibration.mjs

@@ -1,4 +1,5 @@
 import { Buffer } from 'node:buffer';
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
 const LOOKALIKE_CALIBRATION_INPUT_SCHEMA = 'whoisleuth.lookalike-calibration-input';
 const LOOKALIKE_CALIBRATION_SCHEMA = 'whoisleuth.lookalike-calibration';
 const LOOKALIKE_CALIBRATION_VERSION = 1;
@@ -29,10 +30,11 @@ function buildLookalikeCalibration(raw, generatedAt = new Date().toISOString())
     }
     let parsed;
     try {
+        scanBoundedJson(raw);
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new TypeError('Lookalike calibration input must be valid JSON.');
+        throw new TypeError('Lookalike calibration input must be valid bounded JSON without duplicate keys.');
     }
     const input = record(parsed);
     if (input.schema !== LOOKALIKE_CALIBRATION_INPUT_SCHEMA || input.version !== LOOKALIKE_CALIBRATION_VERSION) {

package/cli/lookup-brief.mjs

@@ -1,4 +1,5 @@
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+import { safeTerminalValue } from "./formatters/terminal.mjs";
 export const CLI_LOOKUP_BRIEF_SCHEMA = 'whoisleuth.cli.lookup-brief';
 export const CLI_LOOKUP_BRIEF_VERSION = 2;
 function record(value) {
@@ -7,7 +8,11 @@ function record(value) {
 function text(value, maximum = 300) {
     if (typeof value !== 'string')
         return null;
-    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum);
+    const normalized = value
+        .replace(/[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, maximum);
     return normalized || null;
 }
 function sourceState(value) {
@@ -96,20 +101,20 @@ export function buildCliLookupBrief(input, generatedAt = new Date().toISOString(
 }
 export function formatCliLookupBrief(document) {
     return [
-        `Lookup brief: ${document.target}`,
-        `Observed  ${document.observedAt}`,
-        `Mode      ${document.mode}`,
+        `Lookup brief: ${safeTerminalValue(document.target)}`,
+        `Observed  ${safeTerminalValue(document.observedAt)}`,
+        `Mode      ${safeTerminalValue(document.mode)}`,
         '',
         'Verified facts',
-        ...(document.facts.length ? document.facts.map((item) => `  ${item.label}: ${item.value} (${item.source})`) : ['  No bounded fact was available.']),
+        ...(document.facts.length ? document.facts.map((item) => `  ${safeTerminalValue(item.label)}: ${safeTerminalValue(item.value)} (${safeTerminalValue(item.source)})`) : ['  No bounded fact was available.']),
         '',
         'Unknown or incomplete',
-        ...(document.unknowns.length ? document.unknowns.map((item) => `  ${item}`) : ['  No incomplete source state was identified.']),
+        ...(document.unknowns.length ? document.unknowns.map((item) => `  ${safeTerminalValue(item)}`) : ['  No incomplete source state was identified.']),
         '',
         'Recommended manual actions',
         ...document.actionPlan.flatMap((item, index) => [
-            `  ${index + 1}. ${item.action}`,
-            `     Expected outcome: ${item.expectedOutcome}`,
+            `  ${index + 1}. ${safeTerminalValue(item.action)}`,
+            `     Expected outcome: ${safeTerminalValue(item.expectedOutcome)}`,
         ]),
         '',
     ].join('\n');