@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/local-document-checkpoint.mjs

@@ -0,0 +1,170 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, realpath, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { decodeBoundedUtf8, readBoundedRegularFile } from "../lib/bounded-file.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { writePrivateFile } from "./output-file.mjs";
+function missing(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+async function canonicalPath(value, allowMissing, label) {
+    const absolute = resolve(value);
+    if (basename(absolute).endsWith('.workflow.lock'))
+        throw new CliUsageError('The .workflow.lock suffix is reserved for workflow file ownership.');
+    try {
+        const metadata = await lstat(absolute);
+        if (!metadata.isFile() || metadata.nlink !== 1) {
+            throw new CliUsageError(`${label} files must be regular files without symbolic or additional hard links.`);
+        }
+        return await realpath(absolute);
+    }
+    catch (error) {
+        if (!allowMissing || !missing(error))
+            throw error;
+        return join(await realpath(dirname(absolute)), basename(absolute));
+    }
+}
+async function snapshot(path, maximumBytes, label, signal) {
+    let before;
+    try {
+        before = await lstat(path);
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+    if (!before.isFile() || before.nlink !== 1)
+        throw new CliUsageError(`${label} files must be regular files without links.`);
+    const bytes = await readBoundedRegularFile(path, {
+        maximumBytes, label: `${label} file`, ...(signal ? { signal } : {}),
+    });
+    const after = await lstat(path);
+    if (!after.isFile() || after.nlink !== 1 || before.dev !== after.dev || before.ino !== after.ino
+        || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.size !== after.size) {
+        throw new CliUsageError(`${label} file changed while it was being read.`);
+    }
+    return {
+        identity: { device: after.dev, inode: after.ino, modified: after.mtimeMs, changed: after.ctimeMs,
+            bytes: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex') },
+        text: decodeBoundedUtf8(bytes, `${label} file`),
+    };
+}
+async function ownsLease(lease) {
+    try {
+        const current = await lstat(lease.path);
+        return current.isFile() && current.nlink === 1 && current.dev === lease.device && current.ino === lease.inode;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw error;
+    }
+}
+/** One selected document write, holding source and destination ownership until publication. */
+export async function prepareLocalDocumentWrite(options) {
+    if (![options.maximumInputBytes, options.maximumOutputBytes].every(value => Number.isSafeInteger(value) && value > 0)) {
+        throw new TypeError('Local document byte limits must be positive safe integers.');
+    }
+    const label = options.label;
+    const leases = [];
+    let released = false;
+    let published = false;
+    async function release() {
+        released = true;
+        let unresolved = 0;
+        for (const lease of leases.splice(0).reverse()) {
+            try {
+                if (await ownsLease(lease))
+                    await unlink(lease.path);
+                else
+                    unresolved += 1;
+            }
+            catch {
+                unresolved += 1;
+            }
+        }
+        return unresolved;
+    }
+    try {
+        options.signal?.throwIfAborted();
+        const destination = await canonicalPath(options.destination, true, label);
+        const source = options.source ? await canonicalPath(options.source, false, label) : null;
+        if (source === destination && options.allowSourceReplacement === false) {
+            throw new CliUsageError(`${label} review output must use a different path from its source file.`);
+        }
+        const paths = [...new Set([destination, ...(source ? [source] : [])])].sort();
+        for (const path of paths) {
+            options.signal?.throwIfAborted();
+            const leasePath = join(dirname(path), `.${basename(path)}.workflow.lock`);
+            let handle;
+            try {
+                handle = await open(leasePath, 'wx', 0o600);
+            }
+            catch (error) {
+                if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+                    throw new CliUsageError(`${label} is already locked. Wait for its owner; after an interrupted process, inspect and remove only its abandoned .workflow.lock file.`);
+                }
+                throw error;
+            }
+            try {
+                const identity = await handle.stat();
+                leases.push({ path: leasePath, device: identity.dev, inode: identity.ino });
+                await handle.writeFile(`${JSON.stringify({ pid: process.pid })}\n`, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        const snapshots = new Map();
+        let sourceInput = null;
+        for (const path of paths) {
+            const value = await snapshot(path, options.maximumInputBytes, label, options.signal);
+            if (path === source) {
+                if (!value)
+                    throw new CliUsageError(`${label} source file disappeared before it could be read.`);
+                sourceInput = value.text;
+            }
+            if (path === destination && value && !options.force) {
+                throw new CliUsageError(`${label} output already exists; use --force to replace it or choose another path.`);
+            }
+            snapshots.set(path, value?.identity ?? null);
+        }
+        async function assertUnchanged() {
+            if (released)
+                throw new CliUsageError(`${label} file ownership has already been released.`);
+            options.signal?.throwIfAborted();
+            for (const lease of leases) {
+                if (!await ownsLease(lease))
+                    throw new CliUsageError(`${label} file ownership changed; output was not published.`);
+            }
+            for (const [path, expected] of snapshots) {
+                const actual = (await snapshot(path, options.maximumInputBytes, label, options.signal))?.identity ?? null;
+                if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+                    throw new CliUsageError(`${label} changed during execution; output was not published. Review the current files before resuming.`);
+                }
+            }
+        }
+        return Object.freeze({
+            sourceInput,
+            async publish(content) {
+                if (published || released)
+                    throw new CliUsageError(`${label} file publication has already settled.`);
+                if (Buffer.byteLength(content, 'utf8') > options.maximumOutputBytes) {
+                    throw new CliUsageError(`${label} output is limited to ${options.maximumOutputBytes} bytes.`);
+                }
+                await writePrivateFile(destination, content, { force: options.force, beforePublish: assertUnchanged });
+                published = true;
+            },
+            release,
+        });
+    }
+    catch (error) {
+        const unresolved = await release();
+        if (unresolved) {
+            throw new CliUsageError(`${label} file preparation failed and lease cleanup could not be verified. Inspect the selected directory before resuming.`);
+        }
+        throw error;
+    }
+}

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 : {};
 }

package/cli/lookup-browser.mjs

@@ -1,4 +1,5 @@
 import { StringDecoder } from 'node:string_decoder';
+import { canReadInteractiveLine } from "./terminal-input.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
 import { terminalPresentation, } from "./terminal-presentation.mjs";
 import { MIN_LOOKUP_BROWSER_HEIGHT, MAX_LOOKUP_BROWSER_PANELS, MAX_LOOKUP_BROWSER_SEARCH_BYTES, MAX_LOOKUP_BROWSER_SEARCH_MATCHES, MAX_LOOKUP_BROWSER_SEARCH_SCALARS, boundedBrowserDimensions, boundedSearchText, buildLookupBrowserHelpFrame, buildLookupBrowserFrame, buildLookupBrowserPanels, buildLookupBrowserSearchFrame, buildLookupCollectionFrame, findLookupBrowserMatches, renderedPanelLineOffset, renderLookupBrowser, terminalDisplayWidth, } from "./lookup-browser-view.mjs";
@@ -10,18 +11,10 @@ const MAX_PENDING_INPUT_LENGTH = 512;
 const MAX_LOOKUP_BROWSER_INPUT_CHUNK_BYTES = 2_048;
 const COMPLETE_CSI_RE = /^\u001b\[[0-?]*[ -/]*[@-~]/u;
 function canBrowseLookup(input, output, environment = process.env) {
-    return input?.isTTY === true
-        && output?.isTTY === true
-        && typeof input.setRawMode === 'function'
-        && typeof input.resume === 'function'
-        && typeof input.pause === 'function'
-        && typeof input.on === 'function'
-        && typeof input.off === 'function'
-        && typeof output.write === 'function'
-        && !(Number.isFinite(output.columns) && Number(output.columns) < 40)
-        && !(Number.isFinite(output.rows) && Number(output.rows) < MIN_LOOKUP_BROWSER_HEIGHT)
-        && environment.TERM !== 'dumb'
-        && !environment.CI;
+    return canReadInteractiveLine(input, output, environment)
+        && !(Number.isFinite(output?.columns) && Number(output?.columns) < 40)
+        && !(Number.isFinite(output?.rows) && Number(output?.rows) < MIN_LOOKUP_BROWSER_HEIGHT)
+        && environment.TERM !== 'dumb';
 }
 function runLookupBrowserSession(options) {
     const environment = options.environment || process.env;

package/cli/lookup-command-runner.mjs

@@ -2,7 +2,7 @@ import { abortable } from "../lib/abort.mjs";
 import { classifyQuery } from "../lib/classify.mjs";
 import { runUnifiedLookup } from "../lib/lookup.mjs";
 import { plannedLookupProgressSources } from "../lib/lookup-source-progress.mjs";
-import { CliUsageError, boundedCliErrorMessage } from "./errors.mjs";
+import { CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { buildCliEvidenceExport } from "./export-evidence.mjs";
 import { formatLookupEvidenceHtml } from "./formatters/html.mjs";
@@ -17,6 +17,7 @@ import { evaluateCliFailPolicies, formatFailPolicyNotice } from "./fail-policy.m
 import { formatCliJunit } from "./ci-report.mjs";
 import { browseLookupOperation, canBrowseLookup } from "./lookup-browser.mjs";
 import { writePrivateFile } from "./output-file.mjs";
+import { prepareLookupCollectionTarget, prepareSelectedLookupUrl } from "../packages/evidence/lookup-target.mjs";
 async function runLookupCommand(args, dependencies, context) {
     const browserInput = dependencies.stdin || process.stdin;
     const browserEnvironment = dependencies.environment || process.env;
@@ -35,23 +36,31 @@ async function runLookupCommand(args, dependencies, context) {
     });
     context.setEventProgress(eventProgress);
     eventProgress.emit({ event: 'started' });
-    const query = args.query || await context.readSingleInput();
-    if (!query)
-        throw new CliUsageError('lookup requires one domain, IP address, or ASN as an argument or on stdin.');
+    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.', 'missing_input');
     const classify = dependencies.classifyQuery || classifyQuery;
     const executeLookup = dependencies.runUnifiedLookup || runUnifiedLookup;
     let classified;
+    let query;
+    let selectedUrl;
     try {
+        query = prepareLookupCollectionTarget(input);
         classified = classify(query);
+        if (args.exactUrl) {
+            if (!args.deep || classified.type !== 'domain')
+                throw new TypeError();
+            selectedUrl = prepareSelectedLookupUrl(input, classified.inputHostname);
+        }
     }
-    catch (error) {
-        throw new CliUsageError(boundedCliErrorMessage(error, 'Invalid query'));
+    catch {
+        throw new CliUsageError(args.exactUrl ? '--exact-url requires --deep and an HTTP(S) domain URL without credentials or a custom port.' : 'Invalid domain, IP address, ASN or credential-free HTTP(S) URL.');
     }
     if ((args.output === 'markdown' || args.output === 'html') && classified.type !== 'domain') {
         throw new CliUsageError('Markdown and HTML reports support domain lookups only.');
     }
     if (args.plan) {
-        const plan = buildCliLookupPlan(query, classified, args.deep);
+        const plan = buildCliLookupPlan(query, classified, args.deep, Boolean(selectedUrl));
         context.writeStdout(args.output === 'json'
             ? formatJsonDocument(plan)
             : context.terminal(formatCliLookupPlan(plan), args.color));
@@ -65,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;
@@ -79,22 +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,
-                        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) {
@@ -115,22 +121,10 @@ async function runLookupCommand(args, dependencies, context) {
         let settledSources = 0;
         let result;
         try {
-            result = await abortable(() => executeLookup(classified, args.deep
-                ? {
-                    fast: false,
-                    compact: false,
-                    ...(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();