@slicedearth/whoisleuth-cli 1.47.4 → 2.0.1

package/cli/input.mjs

@@ -1,5 +1,5 @@
 import { Buffer } from 'node:buffer';
-import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
+import { decodeBoundedUtf8, readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 import { CliUsageError } from "./errors.mjs";
 function abortError(signal) {
     return signal.reason instanceof Error
@@ -49,7 +49,12 @@ export async function readCliTextInput(source, stdin, options) {
         }
         if (options.signal?.aborted)
             throw abortError(options.signal);
-        return Buffer.concat(chunks, bytes).toString('utf8');
+        try {
+            return decodeBoundedUtf8(Buffer.concat(chunks, bytes), options.label);
+        }
+        catch (cause) {
+            throw new CliUsageError(cause instanceof Error ? cause.message : `${options.label} must contain valid UTF-8 text.`);
+        }
     }
     finally {
         options.signal?.removeEventListener('abort', onAbort);

package/cli/interactive-launcher.mjs

@@ -0,0 +1,226 @@
+import { classifyQuery, isDirectLookupTarget } from "../lib/classify.mjs";
+import { StringDecoder } from 'node:string_decoder';
+import { boundedCliErrorMessage, CliUsageError, hasUnsafeCliText } 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;
+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)) {
+        throw new CliUsageError('Interactive launch requires terminal input and output.');
+    }
+    if (options.signal?.aborted)
+        throw options.signal.reason || new DOMException('Aborted', 'AbortError');
+    const question = options.question || ((prompt) => readBoundedInteractiveLine(prompt, options));
+    const ask = async (prompt) => boundedInteractiveAnswer(await question(prompt));
+    const write = (value) => options.output.write(value);
+    write([
+        'WHOISleuth interactive launch',
+        '',
+        '  1  Fast Lookup',
+        '  2  Deep Lookup',
+        '  3  Build an investigation workflow plan (offline)',
+        '  4  List commands',
+        '  q  Exit',
+        '',
+    ].join('\n'));
+    const selection = (await ask('Select: ')).toLowerCase();
+    if (selection === 'q' || selection === 'quit' || selection === 'exit' || selection === '')
+        return null;
+    if (selection === '4')
+        return ['commands'];
+    if (selection === '3') {
+        write(`\n${INVESTIGATION_PLAN_RECIPES.map((recipe, index) => `  ${index + 1}  ${INVESTIGATION_PLAN_RECIPE_LABELS[recipe]}`).join('\n')}\n\n`);
+        const recipeSelection = await ask('Workflow: ');
+        const recipe = INVESTIGATION_PLAN_RECIPES[Number(recipeSelection) - 1];
+        if (!recipe)
+            throw new CliUsageError('Choose one listed workflow number.');
+        const subject = await ask('Domain or brand subject: ');
+        if (!subject)
+            throw new CliUsageError('A workflow plan requires one domain or brand subject.');
+        return ['workflow-plan', recipe, subject];
+    }
+    if (selection !== '1' && selection !== '2')
+        throw new CliUsageError('Choose 1, 2, 3, 4, or q.');
+    const query = await ask('Domain, IP address, or ASN: ');
+    if (!isDirectLookupTarget(query)) {
+        throw new CliUsageError('Interactive Lookup requires an unambiguous domain with a recognised public suffix, public IP, or ASN.');
+    }
+    const deep = selection === '2';
+    let classified;
+    try {
+        classified = classifyQuery(query);
+    }
+    catch (error) {
+        throw new CliUsageError(boundedCliErrorMessage(error, 'Invalid Lookup target'));
+    }
+    const plan = buildCliLookupPlan(query, classified, deep);
+    write(`\n${formatCliLookupPlan(plan)}\n`);
+    const confirmed = (await ask('Start this collection and open the evidence browser? [y/N] ')).toLowerCase();
+    if (confirmed !== 'y' && confirmed !== 'yes')
+        return null;
+    return ['lookup', query, deep ? '--deep' : '--fast', '--browse'];
+}
+export { MAX_INTERACTIVE_ANSWER_BYTES, MAX_INTERACTIVE_ANSWER_SCALARS, boundedInteractiveAnswer, canLaunchInteractiveCli, launchInteractiveCli, readBoundedInteractiveLine, };

package/cli/interchange-report.mjs

@@ -1,8 +1,9 @@
 import { Buffer } from 'node:buffer';
 import { INTERCHANGE_ARTIFACT_CONTRACTS, } from "../lib/interchange-fidelity-registry.mjs";
 import { offlineArtifactSatisfiesAssurance, verifyOfflineArtifact, } from "./artifact-verify.mjs";
-import { mergeBrandProfiles } from "../frontend/src/lib/analysis/brand-profile-model.js";
+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;
@@ -45,25 +46,20 @@ function identify(value) {
     return null;
 }
 function timestamp(value) {
-    if (typeof value !== 'string' || value.length > 64 || /[\u0000-\u001f\u007f]/u.test(value)) {
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    if (!normalized)
         throw new TypeError('Interchange report time is invalid.');
-    }
-    const parsed = Date.parse(value);
-    if (!Number.isFinite(parsed))
-        throw new TypeError('Interchange report time is invalid.');
-    return new Date(parsed).toISOString();
+    return normalized;
 }
-function validateBrandProfileExport(value) {
+function validateBrandProfileExport(value, version) {
     const profiles = value.profiles;
     if (!Array.isArray(profiles) || profiles.length > 100) {
         throw new TypeError('Brand Profile export does not contain a bounded profiles collection.');
     }
-    if (typeof value.exportedAt !== 'string' || value.exportedAt.length > 64 || !Number.isFinite(Date.parse(value.exportedAt))) {
-        throw new TypeError('Brand Profile export time is invalid.');
-    }
+    const exportedAt = timestamp(value.exportedAt);
     let nextId = 0;
     const result = mergeBrandProfiles([], value, {
-        nowIso: new Date(Date.parse(value.exportedAt)).toISOString(),
+        nowIso: exportedAt,
         makeId: () => `interchange-profile-${++nextId}`,
     });
     return Object.freeze({ accepted: result.profiles.length, skipped: result.skipped });
@@ -116,7 +112,9 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
     if (supported && contract.fidelity !== 'unsupported') {
         try {
             if (contract.id === 'brand_profiles') {
-                const validation = validateBrandProfileExport(value);
+                if (version === null)
+                    throw new TypeError('Brand Profile export version is invalid.');
+                const validation = validateBrandProfileExport(value, version);
                 recordCount = validation.accepted;
                 acceptedRecordCount = validation.accepted;
                 skippedRecordCount = validation.skipped;
@@ -128,12 +126,14 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
                 verificationState = verification.state;
                 assuranceSatisfied = contract.requiredAssurance === 'whole_integrity'
                     ? offlineArtifactSatisfiesAssurance(verification, 'whole_integrity')
-                    : contract.requiredAssurance === 'structure'
-                        ? offlineArtifactSatisfiesAssurance(verification, 'structure')
-                        : contract.requiredAssurance === 'authenticated_whole_integrity'
-                            ? offlineArtifactSatisfiesAssurance(verification, 'whole_integrity')
-                                && verification.checks.authenticatedEncryption === 'verified'
-                            : false;
+                    : contract.requiredAssurance === 'applicable_integrity'
+                        ? offlineArtifactSatisfiesAssurance(verification, 'applicable_integrity')
+                        : contract.requiredAssurance === 'structure'
+                            ? offlineArtifactSatisfiesAssurance(verification, 'structure')
+                            : contract.requiredAssurance === 'authenticated_whole_integrity'
+                                ? offlineArtifactSatisfiesAssurance(verification, 'whole_integrity')
+                                    && verification.checks.authenticatedEncryption === 'verified'
+                                : false;
                 recordCount = verification.summary.recordCount;
                 sectionCount = verification.summary.sectionCount;
                 const unsupportedSections = verification.summary.unsupportedSectionCount ?? 0;

package/cli/investigation-manifest.mjs

@@ -1,6 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { createHash } from 'node:crypto';
-import { canonicalArtifactJsonV2, SORTED_JSON_V2, sha256ArtifactDigestV2, } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { canonicalArtifactJsonV2, SORTED_JSON_V2, sha256ArtifactDigestV2, } from "../packages/evidence/artifact-integrity.mjs";
 import { requireBoundedString, requireIsoTimestamp, } from "../lib/bounded-contract-normalizers.mjs";
 import { normalizeBoundedSemanticVersion } from "../lib/semantic-version.mjs";
 import { parseBoundedJsonObject } from "./bounded-json.mjs";

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,7 @@
 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;
@@ -95,12 +96,16 @@ function parseResumeState(input, plan) {
     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, 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;
@@ -113,6 +118,9 @@ 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.`);

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) {