@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

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,24 +31,33 @@ function names(value) {
     const source = record(value);
     return boundedText(source.en, 120);
 }
-async function readStableMmdb(databasePath) {
+async function readStableMmdb(databasePath, openFile = open, signal) {
     let handle = null;
+    let database = null;
     try {
+        signal?.throwIfAborted();
         const resolvedPath = await realpath(databasePath);
-        handle = await open(resolvedPath, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW);
+        signal?.throwIfAborted();
+        handle = await openFile(resolvedPath, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK | fsConstants.O_NOFOLLOW);
+        signal?.throwIfAborted();
         const before = await handle.stat();
+        signal?.throwIfAborted();
         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.
+        database = Buffer.allocUnsafeSlow(before.size);
         let offset = 0;
         while (offset < database.length) {
             const { bytesRead } = await handle.read(database, offset, database.length - offset, offset);
+            signal?.throwIfAborted();
             if (bytesRead === 0)
                 break;
             offset += bytesRead;
         }
         const after = await handle.stat();
+        signal?.throwIfAborted();
         if (offset !== database.length
             || before.dev !== after.dev
             || before.ino !== after.ino
@@ -48,6 +69,8 @@ async function readStableMmdb(databasePath) {
         return database;
     }
     catch (cause) {
+        database?.fill(0);
+        signal?.throwIfAborted();
         if (cause instanceof CliUsageError)
             throw cause;
         throw new CliUsageError('The supplied MMDB file could not be read.');
@@ -56,7 +79,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 +89,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 +171,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 +185,126 @@ 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 { signal } = dependencies;
+    signal?.throwIfAborted();
+    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, signal);
+    if (signal?.aborted) {
+        database.fill(0);
+        signal.throwIfAborted();
+    }
+    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);
+        signal?.throwIfAborted();
+        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);
+                signal?.removeEventListener('abort', onAbort);
+                if (signal?.aborted)
+                    reject(signal.reason);
+                else 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 onAbort = () => finish();
+            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());
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+        });
+    }
+    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 : {};
 }

package/cli/lookup-command-runner.mjs

@@ -38,7 +38,7 @@ async function runLookupCommand(args, dependencies, context) {
     eventProgress.emit({ event: 'started' });
     const input = args.query || await context.readSingleInput();
     if (!input)
-        throw new CliUsageError('lookup requires one domain, IP address, or ASN as an argument or on stdin.');
+        throw new CliUsageError('lookup requires one domain, IP address, or ASN as an argument or on stdin.', 'missing_input');
     const classify = dependencies.classifyQuery || classifyQuery;
     const executeLookup = dependencies.runUnifiedLookup || runUnifiedLookup;
     let classified;
@@ -74,6 +74,18 @@ async function runLookupCommand(args, dependencies, context) {
             ...(args.vantageLabel ? { vantageLabel: args.vantageLabel } : {}),
         });
     };
+    const collect = (signal, onSourceSettled) => abortable(() => executeLookup(classified, {
+        fast: !args.deep,
+        compact: false,
+        ...(signal ? { signal } : {}),
+        ...(args.deep ? {
+            ...(selectedUrl ? { selectedUrl } : {}),
+            onSourceSettled: settlement => {
+                onSourceSettled(settlement);
+                eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
+            },
+        } : {}),
+    }), signal);
     let document;
     if (args.browse === true) {
         const browse = dependencies.browseLookupOperation || browseLookupOperation;
@@ -88,23 +100,7 @@ async function runLookupCommand(args, dependencies, context) {
             plannedSources: args.deep ? plannedLookupProgressSources(classified) : [],
             ...(dependencies.signal ? { signal: dependencies.signal } : {}),
             collect: async ({ signal, onSourceSettled }) => {
-                const result = await abortable(() => executeLookup(classified, args.deep
-                    ? {
-                        fast: false,
-                        compact: false,
-                        ...(selectedUrl ? { selectedUrl } : {}),
-                        signal,
-                        onSourceSettled: (settlement) => {
-                            onSourceSettled(settlement);
-                            eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
-                        },
-                    }
-                    : {
-                        fast: true,
-                        compact: false,
-                        signal,
-                    }), signal);
-                return buildDocument(result);
+                return buildDocument(await collect(signal, onSourceSettled));
             },
         });
         if (args.saveLookup) {
@@ -114,6 +110,7 @@ async function runLookupCommand(args, dependencies, context) {
             const save = dependencies.writePrivateFile || writePrivateFile;
             await save(args.saveLookup, serializeCliLookupDocument(document), {
                 existingFileMessage: 'Saved Lookup file already exists. Choose a new --save-lookup path or remove the existing file explicitly.',
+                beforePublish: async () => { dependencies.signal?.throwIfAborted(); },
             });
             context.writeStderr('Saved the completed private Lookup JSON. It can contain raw public registry and WHOIS responses plus target and collection context; review it before sharing.\n');
         }
@@ -125,23 +122,10 @@ async function runLookupCommand(args, dependencies, context) {
         let settledSources = 0;
         let result;
         try {
-            result = await abortable(() => executeLookup(classified, args.deep
-                ? {
-                    fast: false,
-                    compact: false,
-                    ...(selectedUrl ? { selectedUrl } : {}),
-                    ...(dependencies.signal ? { signal: dependencies.signal } : {}),
-                    onSourceSettled: (settlement) => {
-                        settledSources += 1;
-                        indicator.update(`Collected ${settledSources} source${settledSources === 1 ? '' : 's'} · ${settlement.source.replaceAll('_', ' ')} ${settlement.state}`);
-                        eventProgress.emit({ event: 'source_settled', source: settlement.source, state: settlement.state });
-                    },
-                }
-                : {
-                    fast: true,
-                    compact: false,
-                    ...(dependencies.signal ? { signal: dependencies.signal } : {}),
-                }), dependencies.signal);
+            result = await collect(dependencies.signal, settlement => {
+                settledSources += 1;
+                indicator.update(`Collected ${settledSources} source${settledSources === 1 ? '' : 's'} · ${settlement.source.replaceAll('_', ' ')} ${settlement.state}`);
+            });
         }
         finally {
             context.endProgress();

package/cli/lookup-diff.mjs

@@ -5,6 +5,7 @@ import { relationshipObservation } from "../packages/comparison/relationship-evi
 import { CliUsageError } from "./errors.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 import { lookupObservationHostname } from "../packages/evidence/lookup-target.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 export const CLI_LOOKUP_DIFF_SCHEMA = 'whoisleuth.cli.lookup-diff';
 export const CLI_LOOKUP_DIFF_VERSION = 1;
 function text(value, maximum = 300) {
@@ -198,10 +199,10 @@ function formatCliLookupDiff(document) {
     const rows = document.comparison.rows.filter((row) => row.state !== 'equal');
     const output = [
         'Domain evidence diff',
-        `Left             ${document.left.domain}`,
-        `Left observed    ${document.left.generatedAt}`,
-        `Right            ${document.right.domain}`,
-        `Right observed   ${document.right.generatedAt}`,
+        `Left             ${safeTerminalValue(document.left.domain)}`,
+        `Left observed    ${safeTerminalValue(document.left.generatedAt)}`,
+        `Right            ${safeTerminalValue(document.right.domain)}`,
+        `Right observed   ${safeTerminalValue(document.right.generatedAt)}`,
         `Changed          ${document.comparison.counts.different + document.comparison.counts.conflicting}`,
         `One-sided        ${document.comparison.counts.missing}`,
         `Unavailable      ${document.comparison.counts.unavailable + document.comparison.counts.not_recorded}`,
@@ -210,14 +211,14 @@ function formatCliLookupDiff(document) {
     if (!rows.length)
         output.push('No bounded differences were observed in the comparable fields.');
     for (const row of rows) {
-        output.push(`${row.label} [${row.state.replaceAll('_', ' ')}]`);
-        output.push(`  Left:  ${row.left}`);
-        output.push(`  Right: ${row.right}`);
-        output.push(`  Source: ${row.source}`);
+        output.push(`${safeTerminalValue(row.label)} [${safeTerminalValue(row.state).replaceAll('_', ' ')}]`);
+        output.push(`  Left:  ${safeTerminalValue(row.left)}`);
+        output.push(`  Right: ${safeTerminalValue(row.right)}`);
+        output.push(`  Source: ${safeTerminalValue(row.source)}`);
     }
     output.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        output.push(`  - ${limitation}`);
+        output.push(`  - ${safeTerminalValue(limitation)}`);
     return `${output.join('\n')}\n`;
 }
 export { buildCliLookupDiff, formatCliLookupDiff };

package/cli/lookup-plan.mjs

@@ -1,3 +1,4 @@
+import { plannedLookupSources } from "../lib/lookup-progress.mjs";
 export const CLI_LOOKUP_PLAN_SCHEMA = 'whoisleuth.cli.lookup-plan';
 export const CLI_LOOKUP_PLAN_VERSION = 1;
 const RDAP = Object.freeze({
@@ -43,20 +44,15 @@ const REVERSE_DNS = Object.freeze({
     conditional: false,
 });
 function plannedSources(classified, deep, selectedUrl) {
-    if (!deep) {
-        return Object.freeze(classified.type === 'domain' ? [RDAP, FAST_DOMAIN_EVIDENCE] : [RDAP]);
-    }
-    if (classified.type === 'domain') {
-        const domainEvidence = selectedUrl ? Object.freeze({
-            ...DEEP_DOMAIN_EVIDENCE,
-            disclosure: 'The selected URL path and query are sent to the website and followed redirects. The fragment is not sent. DNS and TLS use its hostname; registration uses the registrable domain. Saved HTTP provenance omits queries, but page-derived text may contain sensitive information.',
-        }) : DEEP_DOMAIN_EVIDENCE;
-        return Object.freeze([RDAP, WHOIS, domainEvidence, REGISTRAR_RDAP, NETWORK_CONTEXT]);
-    }
-    if (classified.type === 'ipv4' || classified.type === 'ipv6') {
-        return Object.freeze([RDAP, WHOIS, REVERSE_DNS]);
-    }
-    return Object.freeze([RDAP, WHOIS]);
+    const domainEvidence = selectedUrl && deep ? Object.freeze({
+        ...DEEP_DOMAIN_EVIDENCE,
+        disclosure: 'The selected URL path and query are sent to the website and followed redirects. The fragment is not sent. DNS and TLS use its hostname; registration uses the registrable domain. Saved HTTP provenance omits queries, but page-derived text may contain sensitive information.',
+    }) : deep ? DEEP_DOMAIN_EVIDENCE : FAST_DOMAIN_EVIDENCE;
+    const sources = {
+        rdap: RDAP, whois: WHOIS, domain_evidence: domainEvidence,
+        registrar_rdap: REGISTRAR_RDAP, network_context: NETWORK_CONTEXT, reverse_dns: REVERSE_DNS,
+    };
+    return Object.freeze(plannedLookupSources(classified.type, deep ? 'deep' : 'fast').map(id => sources[id]));
 }
 function buildCliLookupPlan(query, classified, deep, selectedUrl = false) {
     return Object.freeze({

package/cli/lookup-reconcile.mjs

@@ -2,6 +2,7 @@ import { CliUsageError } from "./errors.mjs";
 import { buildCliLookupDiff } from "./lookup-diff.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
 import { compareObservationContexts } from "../packages/comparison/capture-context.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 const CLI_LOOKUP_RECONCILIATION_SCHEMA = 'whoisleuth.cli.lookup-reconciliation';
 const CLI_LOOKUP_RECONCILIATION_VERSION = 1;
 const MAX_LOOKUP_RECONCILIATION_INPUT_BYTES = 32 * 1024 * 1024;
@@ -117,7 +118,7 @@ function formatCliLookupReconciliation(document) {
     const context = compareObservationContexts(document.observations.map(observation => ({ ...observation, observedAt: observation.generatedAt })));
     const output = [
         'Lookup observation reconciliation',
-        `Domain             ${document.domain}`,
+        `Domain             ${safeTerminalValue(document.domain)}`,
         `Observations       ${document.summary.observationCount}`,
         `Declared labels    ${context.labels}; collection independence not verified`,
         `Capture time span  ${context.time.spanMilliseconds === null ? 'unknown' : `${context.time.spanMilliseconds / 1000} seconds`}`,
@@ -125,18 +126,18 @@ function formatCliLookupReconciliation(document) {
         `Disagreement       ${document.summary.disagreement}`,
         `Non-comparable     ${document.summary.nonComparable}`,
         '',
-        ...document.observations.map((observation, index) => `Observation ${index + 1}: ${observation.generatedAt} · ${observation.mode} · observer ${observation.observerLabel ?? 'not declared'} · vantage ${observation.vantageLabel ?? 'not declared'}`),
+        ...document.observations.map((observation, index) => `Observation ${index + 1}: ${safeTerminalValue(observation.generatedAt)} · ${safeTerminalValue(observation.mode)} · observer ${safeTerminalValue(observation.observerLabel, 'not declared')} · vantage ${safeTerminalValue(observation.vantageLabel, 'not declared')}`),
         '',
     ];
     for (const field of document.fields.filter((candidate) => candidate.state !== 'agreement')) {
-        output.push(`${field.label} [${field.state.replaceAll('_', ' ')}]`);
+        output.push(`${safeTerminalValue(field.label)} [${safeTerminalValue(field.state).replaceAll('_', ' ')}]`);
         for (const value of field.values) {
-            output.push(`  Observation ${value.observation + 1}: ${value.value} (${value.sourceState.replaceAll('_', ' ')})`);
+            output.push(`  Observation ${value.observation + 1}: ${safeTerminalValue(value.value)} (${safeTerminalValue(value.sourceState).replaceAll('_', ' ')})`);
         }
     }
     output.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        output.push(`  - ${limitation}`);
+        output.push(`  - ${safeTerminalValue(limitation)}`);
     output.push('  - These selected observations do not establish worldwide availability, removal or takedown.');
     return `${output.join('\n')}\n`;
 }

package/cli/lookup-timeline.mjs

@@ -2,6 +2,7 @@ import { Buffer } from 'node:buffer';
 import { CliUsageError } from "./errors.mjs";
 import { buildCliLookupDiff } from "./lookup-diff.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 export const CLI_LOOKUP_TIMELINE_SCHEMA = 'whoisleuth.cli.lookup-timeline';
 export const CLI_LOOKUP_TIMELINE_VERSION = 1;
 export const MAX_LOOKUP_TIMELINE_OBSERVATIONS = 20;
@@ -95,10 +96,10 @@ function buildCliLookupTimeline(inputs, generatedAt = new Date().toISOString())
 function formatCliLookupTimeline(document) {
     const output = [
         'Same-domain observation timeline',
-        `Domain             ${document.domain}`,
+        `Domain             ${safeTerminalValue(document.domain)}`,
         `Observations       ${document.summary.observationCount}`,
-        `First observed     ${document.observations[0]?.generatedAt || 'Unavailable'}`,
-        `Last observed      ${document.observations.at(-1)?.generatedAt || 'Unavailable'}`,
+        `First observed     ${safeTerminalValue(document.observations[0]?.generatedAt, 'Unavailable')}`,
+        `Last observed      ${safeTerminalValue(document.observations.at(-1)?.generatedAt, 'Unavailable')}`,
         `Changed transitions ${document.summary.transitionsWithObservedChanges}`,
     ];
     for (const transition of document.transitions) {
@@ -106,18 +107,18 @@ function formatCliLookupTimeline(document) {
         const to = document.observations[transition.toObservation];
         const counts = transition.comparison.counts;
         const changedRows = transition.comparison.rows.filter((row) => (row.state === 'conflicting' || row.state === 'different' || row.state === 'missing'));
-        output.push('', `${from?.generatedAt || 'Unavailable'} to ${to?.generatedAt || 'Unavailable'}`, `  Observed changes ${counts.conflicting + counts.different}`, `  One-sided fields ${counts.missing}`, `  Unavailable      ${counts.unavailable + counts.not_recorded}`);
+        output.push('', `${safeTerminalValue(from?.generatedAt, 'Unavailable')} to ${safeTerminalValue(to?.generatedAt, 'Unavailable')}`, `  Observed changes ${counts.conflicting + counts.different}`, `  One-sided fields ${counts.missing}`, `  Unavailable      ${counts.unavailable + counts.not_recorded}`);
         if (!changedRows.length)
             output.push('  No observed field changes in comparable evidence.');
         for (const row of changedRows.slice(0, 10)) {
-            output.push(`  ${row.label} [${row.state.replaceAll('_', ' ')}]: ${row.left} -> ${row.right}`);
+            output.push(`  ${safeTerminalValue(row.label)} [${safeTerminalValue(row.state).replaceAll('_', ' ')}]: ${safeTerminalValue(row.left)} -> ${safeTerminalValue(row.right)}`);
         }
         if (changedRows.length > 10)
             output.push(`  ${changedRows.length - 10} additional changed fields omitted; use --json for the complete bounded comparison.`);
     }
     output.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        output.push(`  - ${limitation}`);
+        output.push(`  - ${safeTerminalValue(limitation)}`);
     return `${output.join('\n')}\n`;
 }
 export { buildCliLookupTimeline, formatCliLookupTimeline };