@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/cli/investigation-recipes.mjs

@@ -0,0 +1,177 @@
+import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA } from "../packages/contracts/domain-control-monitor.mjs";
+import { DOMAIN_CONTROL_REVIEW_SCHEMA } from "../packages/contracts/domain-control-review.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA } from "../packages/contracts/external-observation-interchange.mjs";
+import { CLI_LOOKUP_BRIEF_SCHEMA } from "../packages/contracts/cli-lookup-brief.mjs";
+export const INVESTIGATION_RECIPE_DEFINITIONS = Object.freeze({
+    'domain-triage': Object.freeze({
+        label: 'New domain triage',
+        standardInputs: Object.freeze([
+            { stepId: 'export', input: 1, sourceStepId: 'collect' },
+            { stepId: 'verify', input: 1, sourceStepId: 'export' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect and preserve separately attributed registration, DNS, HTTP, TLS, page, and network-context evidence.',
+        limitations: Object.freeze([
+            'Collection remains analyst-triggered and source limitations remain explicit.',
+            'Disposition, reviewed response actions, monitoring, and closure continue in the saved Case workspace; this CLI recipe does not submit reports.',
+        ]),
+        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', 'Reuse the collected Lookup by default, or select a different reviewed Lookup file.'),
+            step('verify', 'Verify the exported artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
+        ]),
+    }),
+    'lookalike-review': Object.freeze({
+        label: 'Lookalike candidate review',
+        subjectRequirement: 'brand_or_domain',
+        objective: 'Generate a bounded candidate queue, collect only the selected scope, and retain a reviewed candidate lookup.',
+        limitations: Object.freeze([
+            'Candidate generation does not establish registration, control, intent, or maliciousness.',
+            'Official-reference collection and page comparison require analyst-selected saved evidence; use page-compare after retaining the reference and candidate observations.',
+        ]),
+        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.'),
+            step('inspect', 'Deep-review one selected candidate', 'lookup', ['<selected-domain>', '--deep', '--json'], 'network', 'analyst_selection', 'whoisleuth.cli.lookup', 'Select a candidate deliberately; generation does not prove registration, control, intent, or maliciousness.'),
+        ]),
+    }),
+    'owned-domain-review': Object.freeze({
+        label: 'Owned domain posture review',
+        subjectRequirement: 'domain',
+        objective: 'Review current passive posture and compare supplied observations with an analyst-authored control manifest.',
+        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.'),
+            step('manifest', 'Review the domain control manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only complete supplied observations may produce drift.'),
+        ]),
+    }),
+    'historical-comparison': Object.freeze({
+        label: 'Historical observation comparison',
+        standardInputs: Object.freeze([
+            { stepId: 'diff', input: 2, sourceStepId: 'current' },
+            { stepId: 'timeline', input: 3, sourceStepId: 'current' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect a current observation and compare it with analyst-selected saved observations without merging source states.',
+        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({
+        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.',
+        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', 'Prepare a selected candidate brief', 'brief', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', CLI_LOOKUP_BRIEF_SCHEMA, 'Select a saved candidate Lookup; keep any campaign grouping analyst-authored.'),
+        ]),
+    }),
+    'certificate-anomaly': Object.freeze({
+        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.',
+        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', EXTERNAL_FINDINGS_SCHEMA, 'Select a certificate-event batch; a certificate-search report is not interchangeable with that input.'),
+            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({
+        label: 'Registry disagreement review',
+        standardInputs: Object.freeze([
+            { stepId: 'compare', input: 1, sourceStepId: 'collect' },
+            { stepId: 'report', input: 1, sourceStepId: 'collect' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect separately attributed registration evidence and review conflicting publications without selecting an arbitrary source as truth.',
+        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({
+        label: 'Reviewed evidence handoff',
+        standardInputs: Object.freeze([{ stepId: 'lint', input: 1, sourceStepId: 'package' }]),
+        subjectRequirement: 'review_label',
+        objective: 'Verify, minimise, and package analyst-selected evidence for a deliberate handoff without transmitting or submitting it.',
+        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', '--strict-exit'], '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({
+        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.',
+        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', DOMAIN_CONTROL_REVIEW_SCHEMA, '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({
+        label: 'Post-change verification',
+        subjectRequirement: 'domain',
+        objective: 'Perform one explicit later observation and compare it with analyst-selected retained evidence after an authorised change.',
+        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', CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, '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_PLAN_RECIPES = Object.freeze(Object.keys(INVESTIGATION_RECIPE_DEFINITIONS));
+export const RUNNABLE_INVESTIGATION_PLAN_RECIPES = INVESTIGATION_PLAN_RECIPES;
+function step(id, label, command, args, mode, approval, produces, completion) {
+    return Object.freeze({
+        id,
+        label,
+        command,
+        arguments: Object.freeze([...args]),
+        mode,
+        approval,
+        produces,
+        completion,
+    });
+}

package/cli/investigation-run.mjs

@@ -4,8 +4,8 @@ import { buildInvestigationPlan, isRunnableInvestigationRecipe, workflowReviewDe
 import { CliUsageError } from "./errors.mjs";
 import { hasUnsafeCliText } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
-import { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, } from "../packages/contracts/investigation-run.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_PREVIEW_SCHEMA, CLI_INVESTIGATION_PREVIEW_VERSION, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, } from "../packages/contracts/investigation-run.mjs";
 import { normalizeWorkflowBindings, validateWorkflowResult, workflowArtifactReference, workflowInputSchemas, } from "./investigation-artifacts.mjs";
 export { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, };
 const PLACEHOLDER_PATTERN = /^<[^>]+>$/u;
@@ -180,7 +180,7 @@ function validateSelectedInputs(plan, selections, bindings, completed) {
 }
 function parseResumeState(input, plan) {
     if (!input)
-        return Object.freeze({ completed: Object.freeze([]), selections: Object.freeze([]), bindings: Object.freeze([]) });
+        return Object.freeze({ completed: Object.freeze([]), selections: Object.freeze([]), bindings: Object.freeze([]), retryableStepId: null });
     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, '');
@@ -222,6 +222,7 @@ function parseResumeState(input, plan) {
         throw new CliUsageError('Investigation resume state contains more steps than the installed fixed recipe.');
     }
     const completed = [];
+    let retryableStepId = null;
     for (const [index, value] of root.completedSteps.entries()) {
         const baseStep = plan.steps[index];
         const planned = baseStep ? selectedStep(baseStep, selectionsByStep.get(baseStep.id) ?? [], bindings, completed) : null;
@@ -251,6 +252,7 @@ function parseResumeState(input, plan) {
             if (index !== root.completedSteps.length - 1) {
                 throw new CliUsageError('A failed investigation step must be the final retained step.');
             }
+            retryableStepId = planned.id;
             break;
         }
         completed.push(Object.freeze({
@@ -265,19 +267,13 @@ function parseResumeState(input, plan) {
         }));
     }
     validateSelectedInputs(plan, selections, bindings, completed);
-    return Object.freeze({ completed: Object.freeze(completed), selections, bindings });
+    return Object.freeze({ completed: Object.freeze(completed), selections, bindings, retryableStepId });
 }
-export async function runInvestigationRecipe(recipe, subjectValue, options) {
+function prepareInvestigationInvocation(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 confirmedReviews = options.confirmedReviews ?? [];
-    if (!Array.isArray(confirmedReviews) || confirmedReviews.length > plan.steps.length
-        || new Set(confirmedReviews).size !== confirmedReviews.length
-        || confirmedReviews.some(id => !plan.steps.some(step => step.id === id && workflowReviewDeclarations(step).length))) {
-        throw new CliUsageError('--confirm-review must name each selected review-declaration step at most once.');
-    }
     const prior = parseResumeState(options.resumeInput, plan);
     const suppliedSelections = normalizeInvocationSelections(plan, options.selections ?? []);
     // A complete explicit input list replaces a not-yet-run step's standard or
@@ -286,8 +282,78 @@ export async function runInvestigationRecipe(recipe, subjectValue, options) {
         && !prior.completed.some(step => step.id === selection.stepId)).map(selection => selection.stepId));
     const initialBindings = options.resumeInput === null ? workflowStandardInputs(recipe) : prior.bindings;
     const bindings = mergeBindings(plan, initialBindings.filter(binding => !explicitSteps.has(binding.stepId)), normalizeWorkflowBindings(plan, options.artifactBindings ?? []), prior.completed);
-    let selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed, bindings);
+    const selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed, bindings);
     validateSelectedInputs(plan, selections, bindings, prior.completed);
+    return { plan, prior, bindings, selections };
+}
+/** Validate exactly what execution would resume, without an executor or authority. */
+export function previewInvestigationRecipe(recipe, subjectValue, options) {
+    const { plan, prior, bindings, selections } = prepareInvestigationInvocation(recipe, subjectValue, options);
+    const selected = new Map(selections.map(item => [item.stepId, item.values]));
+    const steps = plan.steps.map(base => {
+        const retained = prior.completed.find(item => item.id === base.id);
+        const step = selectedStep(base, selected.get(base.id) ?? [], bindings, prior.completed);
+        let input = 0;
+        const inputs = base.arguments.flatMap((argument, index) => {
+            if (!PLACEHOLDER_PATTERN.test(argument))
+                return [];
+            input++;
+            const binding = bindings.find(item => item.stepId === base.id && item.input === input);
+            const source = binding ? prior.completed.find(item => item.id === binding.sourceStepId) : undefined;
+            return [{
+                    input, placeholder: argument,
+                    state: binding ? source?.artifact ? 'validated_output' : 'awaiting_output'
+                        : PLACEHOLDER_PATTERN.test(step.arguments[index]) ? 'unresolved' : 'selected_file_or_value',
+                    sourceStepId: binding?.sourceStepId ?? null,
+                    artifactId: source?.artifact?.id ?? null,
+                    value: binding ? null : PLACEHOLDER_PATTERN.test(step.arguments[index]) ? null : step.arguments[index],
+                }];
+        });
+        return {
+            id: step.id, label: step.label, command: step.command, mode: step.mode,
+            state: retained ? retained.exitCode === EXIT_CODES.PARTIAL_FAILURE ? 'retained_partial' : 'retained_complete'
+                : prior.retryableStepId === step.id ? 'retryable_failure' : 'remaining',
+            artifact: retained?.artifact ?? null, inputs,
+            networkApprovalRequired: !retained && step.mode === 'network',
+            reviewDeclarationsRequired: retained ? [] : workflowReviewDeclarations(step),
+            arguments: step.arguments,
+        };
+    });
+    return {
+        schema: CLI_INVESTIGATION_PREVIEW_SCHEMA, version: CLI_INVESTIGATION_PREVIEW_VERSION,
+        generatedAt: options.generatedAt, recipe, subject: plan.subject, steps,
+        requestsExecuted: 0, checkpointWritten: false,
+        limitations: [
+            'This preview validates retained results and connections but does not open selected input files, execute steps, or grant approvals.',
+            'Retained partial observations are reused as partial, not silently recollected. Failed steps remain retryable.',
+            'File paths and selected values are included in this local preview. Review them before sharing.',
+        ],
+    };
+}
+export function formatInvestigationPreview(document) {
+    return [
+        `Workflow preview: ${document.recipe}`, `Subject: ${document.subject}`,
+        'Offline inspection only; no requests or checkpoint writes.',
+        ...document.steps.flatMap(step => [
+            `${step.id}: ${step.state.replaceAll('_', ' ')} · ${step.label}`,
+            ...(step.artifact ? [`  Retained: ${step.artifact.schema} v${step.artifact.version} · ${step.artifact.id}`] : []),
+            ...step.inputs.map(input => `  Input ${input.input}: ${input.state.replaceAll('_', ' ')}${input.sourceStepId ? ` from ${input.sourceStepId}` : ''}${input.value ? ` · ${input.value}` : ''}`),
+            ...(step.networkApprovalRequired ? ['  Requires fresh network approval.'] : []),
+            ...(step.reviewDeclarationsRequired.length ? [`  Requires human review: ${step.reviewDeclarationsRequired.join(', ')}.`] : []),
+        ]),
+        ...document.limitations, '',
+    ].join('\n');
+}
+export async function runInvestigationRecipe(recipe, subjectValue, options) {
+    const prepared = prepareInvestigationInvocation(recipe, subjectValue, options);
+    const { plan, prior, bindings } = prepared;
+    let selections = prepared.selections;
+    const confirmedReviews = options.confirmedReviews ?? [];
+    if (!Array.isArray(confirmedReviews) || confirmedReviews.length > plan.steps.length
+        || new Set(confirmedReviews).size !== confirmedReviews.length
+        || confirmedReviews.some(id => !plan.steps.some(step => step.id === id && workflowReviewDeclarations(step).length))) {
+        throw new CliUsageError('--confirm-review must name each selected review-declaration step at most once.');
+    }
     const selectionsByStep = new Map(selections.map((item) => [item.stepId, item.values]));
     const completed = [...prior.completed];
     let state = completed.some((step) => step.exitCode === EXIT_CODES.PARTIAL_FAILURE) ? 'partial' : 'complete';

package/cli/local-mmdb-review.mjs

@@ -1,12 +1,24 @@
 import { constants as fsConstants } from 'node:fs';
 import { open, realpath } from 'node:fs/promises';
 import { isIP } from 'node:net';
+import { createHash } from 'node:crypto';
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
 import { Reader } from 'maxmind';
 import { formatIpPrefix, parseIpPrefix } from "../lib/ip-prefix.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { canonicalPublicIpAddress } from "../packages/evidence/public-address-policy.mjs";
 export const LOCAL_MMDB_QUERY_SCHEMA = 'whoisleuth.local-mmdb-query';
-export const LOCAL_MMDB_QUERY_VERSION = 1;
+export const LOCAL_MMDB_QUERY_VERSION = 2;
+export const LOCAL_MMDB_REVIEW_SCHEMA = 'whoisleuth.local-mmdb-review';
+export const LOCAL_MMDB_REVIEW_VERSION = 1;
 export const MAX_LOCAL_MMDB_BYTES = 512 * 1024 * 1024;
+export const LOCAL_MMDB_REVIEW_DEADLINE_MS = 10_000;
+export const MAX_LOCAL_MMDB_REVIEW_BYTES = 8 * 1024;
+const DAY_MS = 86_400_000;
+const LOCAL_MMDB_WORKER_KIND = 'local-mmdb-review';
+const SUPPORTED_DATABASE_TYPES = new Set(['GeoIP2-City', 'GeoLite2-City', 'GeoIP2-Country', 'GeoLite2-Country',
+    'GeoIP2-ASN', 'GeoLite2-ASN', 'GeoIP2-ISP', 'GeoIP2-Enterprise']);
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -19,16 +31,18 @@ function names(value) {
     const source = record(value);
     return boundedText(source.en, 120);
 }
-async function readStableMmdb(databasePath) {
+async function readStableMmdb(databasePath, openFile = open) {
     let handle = null;
     try {
         const resolvedPath = await realpath(databasePath);
-        handle = await open(resolvedPath, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW);
+        handle = await openFile(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);
+        // Dedicated backing storage can be transferred without copying a pooled
+        // buffer or exposing bytes outside the stable file's exact length.
+        const database = Buffer.allocUnsafeSlow(before.size);
         let offset = 0;
         while (offset < database.length) {
             const { bytesRead } = await handle.read(database, offset, database.length - offset, offset);
@@ -56,7 +70,7 @@ async function readStableMmdb(databasePath) {
         await handle?.close().catch(() => { });
     }
 }
-export async function reviewLocalMmdb(input, databasePath) {
+function prepareQuery(input, checkedAt) {
     const address = boundedText(input.address, 64)?.toLowerCase() ?? '';
     const sourceLabel = boundedText(input.sourceLabel, 120);
     const databaseVersion = boundedText(input.databaseVersion, 80);
@@ -66,15 +80,79 @@ export async function reviewLocalMmdb(input, databasePath) {
     if (!sourceLabel || !databaseVersion || !license) {
         throw new CliUsageError('Local MMDB review requires bounded sourceLabel, databaseVersion, and licence metadata.');
     }
+    if (input.version !== undefined && input.version !== 1 && input.version !== LOCAL_MMDB_QUERY_VERSION) {
+        throw new CliUsageError('Local MMDB review requires a supported query version.');
+    }
+    if (input.version !== LOCAL_MMDB_QUERY_VERSION)
+        return { version: 1, address, sourceLabel, databaseVersion, license, checkedAt: null, freshnessPolicy: null };
+    const policy = record(input.freshnessPolicy);
+    const rationale = boundedText(policy.rationale, 240);
+    const reviewedAt = normalizeExplicitIsoTimestamp(checkedAt);
+    if (!reviewedAt || !rationale || /[\u0080-\u009f]/u.test(String(policy.rationale)) || !Number.isSafeInteger(policy.maxAgeDays) || Number(policy.maxAgeDays) <= 0
+        || Number(policy.maxAgeDays) > Math.floor(Number.MAX_SAFE_INTEGER / DAY_MS)) {
+        throw new CliUsageError('Current MMDB review requires an explicit review time and freshnessPolicy with positive whole maxAgeDays and a bounded plain-text rationale.');
+    }
+    return { version: 2, address, sourceLabel, databaseVersion, license, checkedAt: reviewedAt,
+        freshnessPolicy: { maxAgeDays: Number(policy.maxAgeDays), rationale } };
+}
+/** Intrinsic metadata is separate from the analyst's declared version/licence.
+ * The policy admits age for this review, not accuracy or an update guarantee. */
+export function inspectLocalMmdbMetadata(value, byteLength, checkedAt, policy) {
+    const metadata = record(value);
+    const databaseType = boundedText(metadata.databaseType, 120);
+    const buildMs = metadata.buildEpoch instanceof Date ? metadata.buildEpoch.getTime() : NaN;
+    const reviewMs = Date.parse(normalizeExplicitIsoTimestamp(checkedAt) ?? '');
+    const integer = (candidate) => typeof candidate === 'number' && Number.isSafeInteger(candidate) && candidate >= 0;
+    if (!databaseType || metadata.databaseType !== databaseType || !Number.isSafeInteger(buildMs) || buildMs < 0 || buildMs % 1000 !== 0 || !Number.isFinite(reviewMs)
+        || !integer(metadata.binaryFormatMajorVersion) || !integer(metadata.binaryFormatMinorVersion)
+        || ![4, 6].includes(Number(metadata.ipVersion)) || typeof metadata.ipVersion !== 'number'
+        || !integer(metadata.nodeCount) || metadata.nodeCount < 1 || ![24, 28, 32].includes(Number(metadata.recordSize))
+        || typeof metadata.recordSize !== 'number' || !integer(metadata.searchTreeSize)
+        || metadata.searchTreeSize !== metadata.nodeCount * metadata.recordSize / 4 || metadata.searchTreeSize + 16 >= byteLength) {
+        return { metadata: null, ageDays: null, reason: 'invalid_metadata' };
+    }
+    const intrinsic = { databaseType, builtAt: new Date(buildMs).toISOString(),
+        binaryFormat: { major: metadata.binaryFormatMajorVersion, minor: metadata.binaryFormatMinorVersion }, ipVersion: metadata.ipVersion };
+    const ageDays = (reviewMs - buildMs) / DAY_MS;
+    const reason = metadata.binaryFormatMajorVersion !== 2 || metadata.binaryFormatMinorVersion !== 0 ? 'unsupported_format'
+        : !SUPPORTED_DATABASE_TYPES.has(databaseType) ? 'unsupported_database'
+            : ageDays < 0 ? 'future_database' : ageDays > policy.maxAgeDays ? 'stale_database' : 'admitted';
+    return { metadata: intrinsic, ageDays, reason };
+}
+const LIMITATIONS = Object.freeze([
+    'This CLI-only result comes from an analyst-supplied local MMDB file. WHOISleuth does not bundle, download, update, license, or transmit the database.',
+    'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
+    'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
+]);
+function currentResult(query, identity, admission, reason, match = null) {
+    const state = match ? reason === 'matched' ? 'matched' : 'partial' : 'unavailable';
+    return { schema: LOCAL_MMDB_REVIEW_SCHEMA, version: LOCAL_MMDB_REVIEW_VERSION, state, reason,
+        completeness: state === 'matched' ? 'complete' : state === 'partial' ? 'partial' : 'unavailable',
+        address: query.address, match, source: { label: query.sourceLabel, version: query.databaseVersion, license: query.license },
+        database: { ...identity, metadata: admission.metadata },
+        freshness: { state: admission.reason === 'stale_database' ? 'stale' : admission.reason === 'admitted' ? 'current' : 'unknown',
+            checkedAt: query.checkedAt, ageDays: admission.ageDays, policy: query.freshnessPolicy },
+        limitations: [...LIMITATIONS, 'Declared source, version and licence labels are analyst claims; intrinsic metadata and digest do not authenticate the database or verify licensing.',
+            'Freshness is checked against the explicitly justified age policy. A miss, rejected or stale database is unavailable context, not evidence of location or absence.'] };
+}
+function reviewBytes(query, database, identity) {
     let reader;
     try {
-        reader = new Reader(await readStableMmdb(databasePath));
+        reader = new Reader(database);
     }
-    catch (cause) {
-        if (cause instanceof CliUsageError)
-            throw cause;
+    catch {
+        if (query.version === 2)
+            return currentResult(query, identity, { metadata: null, ageDays: null, reason: 'invalid_metadata' }, 'invalid_database');
         throw new CliUsageError('The supplied file is not a readable MaxMind DB database.');
     }
+    const admission = query.version === 2 ? inspectLocalMmdbMetadata(reader.metadata, database.length, query.checkedAt, query.freshnessPolicy) : null;
+    if (admission && admission.reason !== 'admitted')
+        return currentResult(query, identity, admission, admission.reason);
+    if (admission && !canonicalPublicIpAddress(query.address))
+        return currentResult(query, identity, admission, 'unsupported_address');
+    if (admission && isIP(query.address) === 6 && admission.metadata?.ipVersion === 4)
+        return currentResult(query, identity, admission, 'unsupported_address_family');
+    const address = query.address;
     const [rawMatch, prefixLength] = reader.getWithPrefixLength(address);
     const match = record(rawMatch);
     const traits = record(match.traits);
@@ -84,9 +162,10 @@ export async function reviewLocalMmdb(input, databasePath) {
     const subdivision = record(subdivisions[0]);
     const city = record(match.city);
     const asnValue = match.autonomous_system_number ?? traits.autonomous_system_number;
-    const asn = typeof asnValue === 'number' && Number.isSafeInteger(asnValue) && asnValue >= 0 ? asnValue : null;
+    const asn = typeof asnValue === 'number' && Number.isSafeInteger(asnValue) && asnValue >= 0
+        && (query.version === 1 || asnValue <= 4_294_967_295) ? asnValue : null;
     const prefix = parseIpPrefix(`${address}/${prefixLength}`);
-    return Object.freeze({
+    const result = Object.freeze({
         state: rawMatch ? 'matched' : 'not_found',
         address,
         match: rawMatch ? Object.freeze({
@@ -97,11 +176,112 @@ export async function reviewLocalMmdb(input, databasePath) {
             asn,
             asName: boundedText(match.autonomous_system_organization ?? traits.autonomous_system_organization, 240),
         }) : null,
-        source: Object.freeze({ label: sourceLabel, version: databaseVersion, license }),
-        limitations: Object.freeze([
-            'This CLI-only result comes from an analyst-supplied local MMDB file. WHOISleuth does not bundle, download, update, license, or transmit the database.',
-            'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
-            'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
-        ]),
+        source: Object.freeze({ label: query.sourceLabel, version: query.databaseVersion, license: query.license }),
+        limitations: LIMITATIONS,
     });
+    if (!admission)
+        return result;
+    if (!rawMatch)
+        return currentResult(query, identity, admission, 'no_match');
+    if (!result.match || !prefix || !rawMatch || typeof rawMatch !== 'object' || Array.isArray(rawMatch))
+        return currentResult(query, identity, admission, 'invalid_record');
+    const rawCountry = country.iso_code;
+    const countryCode = boundedText(rawCountry, 2)?.toUpperCase() ?? null;
+    const projected = { ...result.match, countryCode: countryCode && /^[A-Z]{2}$/u.test(countryCode) ? countryCode : null };
+    if (![projected.countryCode, projected.region, projected.city, projected.asn, projected.asName].some(value => value !== null)) {
+        return currentResult(query, identity, admission, 'no_useful_record');
+    }
+    const invalid = rawCountry !== undefined && projected.countryCode === null
+        || asnValue !== undefined && asn === null
+        || match.country !== undefined && (!match.country || typeof match.country !== 'object' || Array.isArray(match.country))
+        || match.city !== undefined && (!match.city || typeof match.city !== 'object' || Array.isArray(match.city))
+        || match.subdivisions !== undefined && !Array.isArray(match.subdivisions)
+        || subdivision.names !== undefined && projected.region === null
+        || subdivision.iso_code !== undefined && projected.region === null
+        || city.names !== undefined && projected.city === null
+        || (match.autonomous_system_organization ?? traits.autonomous_system_organization) !== undefined && projected.asName === null;
+    return currentResult(query, identity, admission, invalid ? 'incomplete_record' : 'matched', projected);
+}
+function freezeResult(result) {
+    if (result.match)
+        Object.freeze(result.match);
+    Object.freeze(result.source);
+    Object.freeze(result.limitations);
+    if ('database' in result) {
+        if (result.database.metadata) {
+            Object.freeze(result.database.metadata.binaryFormat);
+            Object.freeze(result.database.metadata);
+        }
+        Object.freeze(result.database);
+        Object.freeze(result.freshness.policy);
+        Object.freeze(result.freshness);
+    }
+    return Object.freeze(result);
+}
+if (!isMainThread && parentPort && record(workerData).kind === LOCAL_MMDB_WORKER_KIND) {
+    const port = parentPort, request = workerData;
+    try {
+        const bytes = Buffer.from(request.bytes.buffer, request.bytes.byteOffset, request.bytes.byteLength);
+        const result = reviewBytes(request.query, bytes, request.identity);
+        if (Buffer.byteLength(JSON.stringify(result), 'utf8') > MAX_LOCAL_MMDB_REVIEW_BYTES)
+            throw new TypeError('Local result exceeds its output bound.');
+        port.postMessage({ result });
+    }
+    catch {
+        port.postMessage({ error: true });
+    }
+    finally {
+        request.bytes.fill(0);
+        port.close();
+    }
+}
+/** One disposable worker pre-empts the existing synchronous reader. It is not
+ * a sandbox and never receives a database path or inherited environment. */
+export async function reviewLocalMmdb(input, databasePath, checkedAt = new Date().toISOString(), dependencies = {}) {
+    const query = prepareQuery(input, checkedAt);
+    const deadlineMs = dependencies.deadlineMs ?? LOCAL_MMDB_REVIEW_DEADLINE_MS;
+    if (!Number.isSafeInteger(deadlineMs) || deadlineMs <= 0 || deadlineMs > LOCAL_MMDB_REVIEW_DEADLINE_MS)
+        throw new CliUsageError('Invalid local database processing deadline.');
+    const database = await readStableMmdb(databasePath, dependencies.openFile);
+    const identity = { sha256: createHash('sha256').update(database).digest('hex'), byteLength: database.length };
+    const options = { workerData: { kind: LOCAL_MMDB_WORKER_KIND, query, bytes: database, identity },
+        transferList: [database.buffer], env: {}, execArgv: [], stdout: true, stderr: true,
+        resourceLimits: { maxOldGenerationSizeMb: 64, maxYoungGenerationSizeMb: 16, stackSizeMb: 4 } };
+    let worker;
+    try {
+        worker = dependencies.createWorker ? dependencies.createWorker(options) : new Worker(new URL(import.meta.url), options);
+    }
+    catch {
+        if (database.byteLength)
+            database.fill(0);
+        if (query.version === 2)
+            return freezeResult(currentResult(query, identity, { metadata: null, ageDays: null, reason: 'invalid_metadata' }, 'processing_unavailable'));
+        throw new CliUsageError('The supplied database could not be reviewed within its format and processing bounds.');
+    }
+    worker.stdout?.resume();
+    worker.stderr?.resume();
+    try {
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (result, reason = 'processing_unavailable') => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (result)
+                    resolve(freezeResult(result));
+                else if (query.version === 2)
+                    resolve(freezeResult(currentResult(query, identity, { metadata: null, ageDays: null, reason: 'invalid_metadata' }, reason)));
+                else
+                    reject(new CliUsageError('The supplied database could not be reviewed within its format and processing bounds.'));
+            };
+            const timer = setTimeout(() => finish(undefined, 'processing_deadline'), deadlineMs);
+            worker.once('message', (reply) => reply && 'result' in reply ? finish(reply.result) : finish());
+            worker.once('error', () => finish());
+            worker.once('exit', () => finish());
+        });
+    }
+    finally {
+        await worker.terminate();
+    }
 }

package/cli/lookalike-calibration.mjs

@@ -1,5 +1,5 @@
 import { Buffer } from 'node:buffer';
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
 const LOOKALIKE_CALIBRATION_INPUT_SCHEMA = 'whoisleuth.lookalike-calibration-input';
 const LOOKALIKE_CALIBRATION_SCHEMA = 'whoisleuth.lookalike-calibration';
 const LOOKALIKE_CALIBRATION_VERSION = 1;

package/cli/lookup-brief.mjs

@@ -1,8 +1,8 @@
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
 import { compareRdapPublications, compareRegistrySources } from "../lib/registry-comparison.mjs";
-export const CLI_LOOKUP_BRIEF_SCHEMA = 'whoisleuth.cli.lookup-brief';
-export const CLI_LOOKUP_BRIEF_VERSION = 3;
+import { CLI_LOOKUP_BRIEF_SCHEMA, CLI_LOOKUP_BRIEF_VERSION } from "../packages/contracts/cli-lookup-brief.mjs";
+export { CLI_LOOKUP_BRIEF_SCHEMA, CLI_LOOKUP_BRIEF_VERSION };
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }