@slicedearth/whoisleuth-cli 1.32.0

package/cli/discovery-scan.mjs

@@ -0,0 +1,325 @@
+import { createHash } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { runBulkLookups } from "./bulk.mjs";
+import { REGISTERED_STATES, availabilityState, bulkDnsSummary } from "./bulk-output.mjs";
+import { cliCsvCell } from "./csv.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const CLI_DISCOVERY_SCAN_SCHEMA = 'whoisleuth.cli.discovery-scan';
+export const CLI_DISCOVERY_SCAN_ITEM_SCHEMA = 'whoisleuth.cli.discovery-scan.item';
+export const CLI_DISCOVERY_SCAN_VERSION = 1;
+export const MAX_DISCOVERY_SCAN_ALLOWLIST_BYTES = 64 * 1024;
+export const MAX_DISCOVERY_SCAN_ALLOWLIST_ITEMS = 500;
+const MAX_DISCOVERY_SCAN_RELATIONSHIPS = 200;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function boundedText(value, maximum = 500) {
+    return typeof value === 'string'
+        ? value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        : '';
+}
+async function readDiscoveryScanListBounded(stream, limit = MAX_DISCOVERY_SCAN_ALLOWLIST_BYTES) {
+    if (!stream || stream.isTTY)
+        return '';
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limit)
+            throw new CliUsageError(`Discovery scan allowlists are limited to ${limit} bytes.`);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseDiscoveryScanAllowlist(text, classifyQuery) {
+    if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > MAX_DISCOVERY_SCAN_ALLOWLIST_BYTES) {
+        throw new CliUsageError(`Discovery scan allowlists are limited to ${MAX_DISCOVERY_SCAN_ALLOWLIST_BYTES} bytes.`);
+    }
+    const values = new Set();
+    for (const line of text.replace(/^\uFEFF/u, '').split(/\r?\n/u)) {
+        const value = line.trim();
+        if (!value || value.startsWith('#'))
+            continue;
+        if (value.length > 253 || /[\u0000-\u001f\u007f]/u.test(value)) {
+            throw new CliUsageError('Discovery scan allowlists contain an invalid or overlong value.');
+        }
+        let classified;
+        try {
+            classified = classifyQuery(value);
+        }
+        catch {
+            throw new CliUsageError(`Discovery scan allowlist value "${boundedText(value, 80)}" is not a domain.`);
+        }
+        if (classified.type !== 'domain')
+            throw new CliUsageError('Discovery scan allowlists may contain domains only.');
+        values.add(classified.registrableDomain || classified.value);
+        if (values.size > MAX_DISCOVERY_SCAN_ALLOWLIST_ITEMS) {
+            throw new CliUsageError(`Discovery scan allowlists are limited to ${MAX_DISCOVERY_SCAN_ALLOWLIST_ITEMS} unique domains.`);
+        }
+    }
+    return values;
+}
+function normalizedCandidate(candidate) {
+    const domain = boundedText(candidate.domain, 253).toLowerCase();
+    const source = boundedText(candidate.source, 253).toLowerCase();
+    const tld = boundedText(candidate.tld, 63).toLowerCase();
+    const mutationTypes = Array.isArray(candidate.mutationTypes)
+        ? [...new Set(candidate.mutationTypes.flatMap((value) => {
+                const normalized = boundedText(value, 80);
+                return normalized ? [normalized] : [];
+            }))].slice(0, 20)
+        : [];
+    return { domain, source, tld, mutationTypes };
+}
+function reviewFor(item, domain, allowlist) {
+    const state = availabilityState(item) || 'unknown';
+    const dns = bulkDnsSummary(item);
+    const reasons = [];
+    let lane;
+    if (allowlist.has(domain)) {
+        lane = 'suppressed';
+        reasons.push('The domain matches the analyst-supplied allowlist. Evidence is retained but deprioritized.');
+    }
+    else if (!item.ok || state === 'unknown') {
+        lane = 'retry';
+        reasons.push('Collection failed or authoritative registration evidence remained inconclusive.');
+    }
+    else if (state === 'available') {
+        lane = 'acquisition_review';
+        reasons.push('Authoritative lookup evidence reported the candidate as available at collection time.');
+    }
+    else {
+        lane = 'investigate';
+        reasons.push(REGISTERED_STATES.has(state)
+            ? 'Registration evidence indicates that the candidate is registered or in a registered lifecycle state.'
+            : 'The observed state warrants analyst review before any conclusion.');
+    }
+    if (dns.hasNullMx === true)
+        reasons.push('A null MX record was observed, indicating that the domain does not accept mail under the published policy.');
+    else if (dns.mx.length)
+        reasons.push('One or more MX records were observed; mail capability requires separate passive review.');
+    return { lane, reasons, state };
+}
+function buildScanItem(candidate, item, allowlist, relationshipIds = []) {
+    const normalized = normalizedCandidate(candidate);
+    const review = reviewFor(item, normalized.domain, allowlist);
+    const result = item.ok ? record(item.result) : {};
+    return {
+        schema: CLI_DISCOVERY_SCAN_ITEM_SCHEMA,
+        version: CLI_DISCOVERY_SCAN_VERSION,
+        domain: normalized.domain,
+        source: normalized.source,
+        tld: normalized.tld,
+        mutationTypes: normalized.mutationTypes,
+        ok: item.ok,
+        availabilityState: review.state,
+        confidence: item.ok ? boundedText(record(result.availability).confidence, 40) || 'unknown' : 'unknown',
+        dnsSummary: bulkDnsSummary(item),
+        review: { lane: review.lane, reasons: review.reasons },
+        relationshipIds: [...relationshipIds],
+        ...(item.ok ? {
+            availability: result.availability,
+            diagnostics: result.diagnostics,
+        } : { error: item.error }),
+    };
+}
+function relationshipId(type, value) {
+    return `rel-${createHash('sha256').update(`${type}\n${value}`).digest('hex').slice(0, 16)}`;
+}
+function buildRelationships(candidates, items) {
+    const groups = new Map();
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        const candidate = candidates[index];
+        if (!item || !candidate || !item.ok)
+            continue;
+        const domain = normalizedCandidate(candidate).domain;
+        const dns = bulkDnsSummary(item);
+        const observations = [
+            ...dns.a.map((value) => ['address', value]),
+            ...dns.aaaa.map((value) => ['address', value]),
+            ...dns.ns.map((value) => ['nameserver', value.toLowerCase().replace(/\.$/u, '')]),
+            ...dns.mx.map((value) => ['mail_server', value.replace(/^\d+\s+/u, '').toLowerCase().replace(/\.$/u, '')]),
+        ];
+        for (const [type, value] of observations) {
+            if (!value)
+                continue;
+            const key = `${type}\n${value}`;
+            const group = groups.get(key) || { type, value, domains: new Set() };
+            group.domains.add(domain);
+            groups.set(key, group);
+        }
+    }
+    return [...groups.values()]
+        .filter((group) => group.domains.size >= 2)
+        .sort((left, right) => right.domains.size - left.domains.size
+        || left.type.localeCompare(right.type) || left.value.localeCompare(right.value))
+        .slice(0, MAX_DISCOVERY_SCAN_RELATIONSHIPS)
+        .map((group) => ({
+        id: relationshipId(group.type, group.value),
+        type: group.type,
+        value: group.value,
+        domains: [...group.domains].sort(),
+        domainCount: group.domains.size,
+    }));
+}
+function selectedByFilter(item, filter) {
+    if (filter === 'all')
+        return true;
+    if (filter === 'registered')
+        return REGISTERED_STATES.has(item.availabilityState);
+    if (filter === 'inconclusive')
+        return !item.ok || item.availabilityState === 'unknown';
+    if (filter === 'acquisition')
+        return item.review.lane === 'acquisition_review';
+    return item.review.lane === 'suppressed';
+}
+function coverageSummary(results) {
+    const states = {};
+    const lanes = {};
+    const tlds = {};
+    for (const item of results) {
+        states[item.availabilityState] = (states[item.availabilityState] ?? 0) + 1;
+        lanes[item.review.lane] = (lanes[item.review.lane] ?? 0) + 1;
+        const tld = tlds[item.tld] || { total: 0, available: 0, registered: 0, inconclusive: 0 };
+        tld.total += 1;
+        if (item.availabilityState === 'available')
+            tld.available += 1;
+        else if (REGISTERED_STATES.has(item.availabilityState))
+            tld.registered += 1;
+        else
+            tld.inconclusive += 1;
+        tlds[item.tld] = tld;
+    }
+    return { states, reviewLanes: lanes, tlds };
+}
+function buildDiscoveryScanDocument(candidates, items, metadata, allowlist, snapshot = null) {
+    if (candidates.length !== items.length)
+        throw new TypeError('Discovery candidates and lookup results must align.');
+    const relationships = buildRelationships(candidates, items);
+    const relationshipIdsByDomain = new Map();
+    for (const relationship of relationships) {
+        for (const domain of relationship.domains) {
+            const ids = relationshipIdsByDomain.get(domain) || [];
+            ids.push(relationship.id);
+            relationshipIdsByDomain.set(domain, ids);
+        }
+    }
+    const allResults = candidates.map((candidate, index) => {
+        const domain = normalizedCandidate(candidate).domain;
+        const item = items[index];
+        if (!item)
+            throw new TypeError('Discovery scan result alignment failed.');
+        return buildScanItem(candidate, item, allowlist, relationshipIdsByDomain.get(domain) || []);
+    });
+    const results = allResults.filter((item) => selectedByFilter(item, metadata.filter));
+    return {
+        schema: CLI_DISCOVERY_SCAN_SCHEMA,
+        version: CLI_DISCOVERY_SCAN_VERSION,
+        generatedAt: metadata.generatedAt,
+        seed: metadata.seed,
+        mode: metadata.deep ? 'deep' : 'fast',
+        generation: {
+            preset: metadata.preset,
+            keyboardLayout: metadata.keyboardLayout,
+            tlds: [...metadata.tlds],
+            mutationFamilies: [...metadata.mutationFamilies],
+            generatedCandidateCount: metadata.generatedCandidateCount,
+            selectedCandidateCount: metadata.selectedCandidateCount,
+            scanLimit: metadata.scanLimit,
+        },
+        collection: {
+            chunkSize: metadata.chunkSize,
+            concurrency: metadata.concurrency,
+            resolver: metadata.resolverServers.length ? 'analyst_selected' : 'system_default',
+            resolverServers: [...metadata.resolverServers],
+        },
+        filter: metadata.filter,
+        summary: {
+            collected: allResults.length,
+            matched: results.length,
+            succeeded: allResults.filter((item) => item.ok).length,
+            failed: allResults.filter((item) => !item.ok).length,
+            suppressed: allResults.filter((item) => item.review.lane === 'suppressed').length,
+        },
+        coverage: coverageSummary(allResults),
+        relationships,
+        results,
+        ...(snapshot ? { snapshot } : {}),
+        nextActions: [
+            'Deep-collect only the candidates selected for review before comparing page, mail, certificate, or technology evidence.',
+            'Confirm an available result again at the authoritative registration source before considering defensive acquisition.',
+            'Treat shared infrastructure as a pivot lead only; it does not establish ownership, control, intent, safety, or maliciousness.',
+            'Keep analyst assertions and external enforcement decisions separate from these observed and derived results.',
+        ],
+        limitations: [
+            'Candidate mutations are leads, not findings. Selection order is deterministic and bounded by the requested scan limit.',
+            'Failed, partial, rate-limited, and unavailable sources remain inconclusive and are not interpreted as absence or safety.',
+            'The allowlist changes review priority only. It does not remove collected evidence or assert that a domain is benign.',
+            'Relationship groups use exact bounded DNS observations from this run and can include common shared infrastructure.',
+        ],
+    };
+}
+async function runDiscoveryScanChunks(queries, options) {
+    if (!Number.isSafeInteger(options.chunkSize) || options.chunkSize < 1 || options.chunkSize > 100) {
+        throw new TypeError('Discovery scan chunk size is invalid.');
+    }
+    const output = new Array(queries.length);
+    for (const initial of options.initialResults || [])
+        output[initial.index] = initial;
+    for (let start = 0; start < queries.length; start += options.chunkSize) {
+        options.signal?.throwIfAborted();
+        const chunkQueries = queries.slice(start, start + options.chunkSize);
+        const initialResults = (options.initialResults || [])
+            .filter((item) => item.index >= start && item.index < start + chunkQueries.length)
+            .map((item) => ({ ...item, index: item.index - start }));
+        const chunk = await runBulkLookups([...chunkQueries], {
+            ...options,
+            initialResults,
+            onItemSettled: (item) => options.onItemSettled?.({ ...item, index: item.index + start }),
+        });
+        for (const item of chunk)
+            output[item.index + start] = { ...item, index: item.index + start };
+    }
+    return output;
+}
+function formatDiscoveryScanJsonLines(document) {
+    return document.results.length
+        ? `${document.results.map((item) => JSON.stringify({ ...item, generatedAt: document.generatedAt })).join('\n')}\n`
+        : '';
+}
+function formatDiscoveryScanCsv(document) {
+    const header = ['domain', 'availability', 'confidence', 'review_lane', 'mutation_types', 'a', 'aaaa', 'ns', 'mx', 'relationship_ids', 'error'];
+    const rows = document.results.map((item) => [
+        item.domain, item.availabilityState, item.confidence, item.review.lane, item.mutationTypes,
+        item.dnsSummary.a, item.dnsSummary.aaaa, item.dnsSummary.ns, item.dnsSummary.mx,
+        item.relationshipIds, 'error' in item ? item.error : '',
+    ].map(cliCsvCell).join(','));
+    return `${[header.join(','), ...rows].join('\n')}\n`;
+}
+function formatDiscoveryScanDomains(document) {
+    return document.results.length ? `${document.results.map((item) => item.domain).join('\n')}\n` : '';
+}
+function formatTerminalDiscoveryScan(document) {
+    const lines = [
+        'Supervised candidate scan',
+        `Seed             ${document.seed}`,
+        `Mode             ${document.mode}`,
+        `Generated        ${document.generation.generatedCandidateCount}`,
+        `Collected        ${document.summary.collected}`,
+        `Matched          ${document.summary.matched}`,
+        `Source failures  ${document.summary.failed}`,
+        `Relationships    ${document.relationships.length}`,
+        '',
+        'Review queue',
+    ];
+    for (const item of document.results.slice(0, 200)) {
+        lines.push(`${item.domain.padEnd(42)} ${item.availabilityState.padEnd(13)} ${item.review.lane}`);
+    }
+    if (document.results.length > 200)
+        lines.push(`... ${document.results.length - 200} additional results omitted from terminal display; use --json, --jsonl, or --csv.`);
+    lines.push('', 'Next actions:', ...document.nextActions.map((item) => `  - ${item}`));
+    return `${lines.join('\n')}\n`;
+}
+export { buildDiscoveryScanDocument, formatDiscoveryScanCsv, formatDiscoveryScanDomains, formatDiscoveryScanJsonLines, formatTerminalDiscoveryScan, parseDiscoveryScanAllowlist, readDiscoveryScanListBounded, runDiscoveryScanChunks, };

package/cli/discovery-snapshot.mjs

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { CliUsageError } from "./errors.mjs";
+import { writePrivateFile } from "./output-file.mjs";
+import { isValidAsciiDomainName } from "../lib/hostname.mjs";
+export const CLI_DISCOVERY_SNAPSHOT_SCHEMA = 'whoisleuth.cli.discovery-snapshot';
+export const CLI_DISCOVERY_SNAPSHOT_VERSION = 1;
+export const MAX_DISCOVERY_SNAPSHOT_BYTES = 4 * 1024 * 1024;
+export const MAX_DISCOVERY_SNAPSHOT_DOMAINS = 10_000;
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+function configurationDigest(configuration) {
+    return createHash('sha256').update(JSON.stringify({
+        seed: configuration.seed,
+        preset: configuration.preset,
+        keyboardLayout: configuration.keyboardLayout,
+        tlds: [...configuration.tlds],
+        mutationFamilies: [...configuration.mutationFamilies],
+        dictionaryDigestSha256: configuration.dictionaryDigestSha256,
+    })).digest('hex');
+}
+function normalizedDomains(value) {
+    if (!Array.isArray(value) || value.length > MAX_DISCOVERY_SNAPSHOT_DOMAINS) {
+        throw new CliUsageError(`Discovery snapshots support at most ${MAX_DISCOVERY_SNAPSHOT_DOMAINS} candidates.`);
+    }
+    const output = new Set();
+    for (const candidate of value) {
+        if (!isValidAsciiDomainName(candidate, { requireDot: true, requireLowercase: true })) {
+            throw new CliUsageError('Discovery snapshot contains an invalid candidate domain.');
+        }
+        output.add(candidate);
+    }
+    return [...output].sort();
+}
+function parseDiscoverySnapshot(text, expectedConfigurationDigest) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_DISCOVERY_SNAPSHOT_BYTES) {
+        throw new CliUsageError(`Discovery snapshot input is limited to ${MAX_DISCOVERY_SNAPSHOT_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('Discovery snapshot must be valid JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new CliUsageError('Discovery snapshot must be one JSON object.');
+    }
+    const value = parsed;
+    if (value.schema !== CLI_DISCOVERY_SNAPSHOT_SCHEMA || value.version !== CLI_DISCOVERY_SNAPSHOT_VERSION) {
+        throw new CliUsageError(`Discovery snapshot must use ${CLI_DISCOVERY_SNAPSHOT_SCHEMA} version ${CLI_DISCOVERY_SNAPSHOT_VERSION}.`);
+    }
+    if (value.configurationDigestSha256 !== expectedConfigurationDigest) {
+        throw new CliUsageError('Discovery snapshot configuration does not match this run. Choose another state file or restore the original discovery controls.');
+    }
+    if (typeof value.generatedAt !== 'string' || !Number.isFinite(Date.parse(value.generatedAt))) {
+        throw new CliUsageError('Discovery snapshot collection time is invalid.');
+    }
+    const candidates = normalizedDomains(value.candidates);
+    if (value.candidateCount !== candidates.length)
+        throw new CliUsageError('Discovery snapshot candidate count is inconsistent.');
+    return {
+        schema: CLI_DISCOVERY_SNAPSHOT_SCHEMA,
+        version: CLI_DISCOVERY_SNAPSHOT_VERSION,
+        generatedAt: new Date(value.generatedAt).toISOString(),
+        configurationDigestSha256: expectedConfigurationDigest,
+        candidateCount: candidates.length,
+        candidates,
+    };
+}
+async function readExistingSnapshot(path) {
+    try {
+        const handle = await open(path, 'r');
+        try {
+            const metadata = await handle.stat();
+            if (!metadata.isFile() || metadata.size > MAX_DISCOVERY_SNAPSHOT_BYTES) {
+                throw new CliUsageError(`Discovery snapshot input is limited to ${MAX_DISCOVERY_SNAPSHOT_BYTES} bytes.`);
+            }
+            return await handle.readFile({ encoding: 'utf8' });
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function updateDiscoverySnapshot(path, candidatesValue, configuration, generatedAt) {
+    if (!path || path.length > 1024 || /[\u0000-\u001f\u007f]/u.test(path)) {
+        throw new CliUsageError('Discovery snapshot path must be bounded text without control characters.');
+    }
+    const candidates = normalizedDomains(candidatesValue);
+    const digest = configurationDigest(configuration);
+    const existingText = await readExistingSnapshot(path);
+    const previous = existingText === null ? null : parseDiscoverySnapshot(existingText, digest);
+    const previousSet = new Set(previous?.candidates ?? []);
+    const currentSet = new Set(candidates);
+    const added = candidates.filter((domain) => !previousSet.has(domain));
+    const removed = [...previousSet].filter((domain) => !currentSet.has(domain));
+    const document = {
+        schema: CLI_DISCOVERY_SNAPSHOT_SCHEMA,
+        version: CLI_DISCOVERY_SNAPSHOT_VERSION,
+        generatedAt: new Date(generatedAt).toISOString(),
+        configurationDigestSha256: digest,
+        candidateCount: candidates.length,
+        candidates,
+    };
+    const content = `${JSON.stringify(document, null, 2)}\n`;
+    if (Buffer.byteLength(content, 'utf8') > MAX_DISCOVERY_SNAPSHOT_BYTES) {
+        throw new CliUsageError(`Discovery snapshot output is limited to ${MAX_DISCOVERY_SNAPSHOT_BYTES} bytes.`);
+    }
+    await writePrivateFile(path, content, {
+        force: previous !== null,
+        existingFileMessage: 'Discovery snapshot already exists and could not be replaced.',
+    });
+    return {
+        baselineCreated: previous === null,
+        previousGeneratedAt: previous?.generatedAt ?? null,
+        previousCandidateCount: previous?.candidateCount ?? 0,
+        currentCandidateCount: candidates.length,
+        added,
+        removed,
+        unchanged: candidates.filter((domain) => previousSet.has(domain)).length,
+        limitations: [
+            'This local snapshot compares generated candidate names only and makes no network request.',
+            'Added or removed candidates can reflect changed generation controls, dictionaries, or software versions rather than registration activity.',
+            'The state file contains candidate domains and should be handled as analyst workspace data.',
+        ],
+    };
+}
+export { configurationDigest, parseDiscoverySnapshot, updateDiscoverySnapshot };

package/cli/discovery-workflow.mjs

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { DEFAULT_DISCOVERY_TLDS, MAX_DISCOVERY_DICTIONARY_BYTES, normalizeDiscoveryTlds, readDiscoveryDictionaryBounded, } from "./discover.mjs";
+import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
+async function generateDiscoveryCandidates(args, dependencies, context) {
+    const seed = args.seed || await context.readSingleInput();
+    if (!seed)
+        throw new CliUsageError('discover requires one brand label or domain as an argument or on stdin.');
+    const loadGenerator = dependencies.loadTyposquatGenerator || (() => import("../lib/typosquat-generator.mjs"));
+    const generator = await loadGenerator();
+    const tlds = normalizeDiscoveryTlds(args.tldText || DEFAULT_DISCOVERY_TLDS.join(','), generator.MAX_GENERATION_TLDS);
+    const requestedFamilies = args.familyText
+        ? [...new Set(args.familyText.split(',').map((value) => value.trim()).filter(Boolean))]
+        : [];
+    const mutationFamilies = args.preset === 'custom'
+        ? generator.normalizeMutationFamilyIds(requestedFamilies)
+        : [];
+    if (args.preset === 'custom'
+        && (!mutationFamilies.length || mutationFamilies.length !== requestedFamilies.length)) {
+        throw new CliUsageError(`--families requires one or more supported IDs: ${generator.MUTATION_FAMILY_IDS.join(', ')}.`);
+    }
+    let dictionaryText = '';
+    if (args.dictionarySource) {
+        if (args.preset === 'custom'
+            && !mutationFamilies.includes('dictionary')
+            && !mutationFamilies.includes('dictionary_token_replacement')) {
+            throw new CliUsageError('--dictionary requires a dictionary mutation family.');
+        }
+        try {
+            dictionaryText = dependencies.readDiscoveryDictionary
+                ? await dependencies.readDiscoveryDictionary(args.dictionarySource)
+                : await readDiscoveryDictionaryBounded(createReadStream(args.dictionarySource, { highWaterMark: MAX_DISCOVERY_DICTIONARY_BYTES }), MAX_DISCOVERY_DICTIONARY_BYTES);
+        }
+        catch (error) {
+            if (error instanceof CliUsageError)
+                throw error;
+            throw new CliUsageError(`Could not read discovery dictionary: ${boundedCliErrorMessage(error, 'Input could not be read')}`);
+        }
+        const normalizedDictionary = generator.normalizeCustomDictionaryTerms(dictionaryText);
+        if (!normalizedDictionary.values.length) {
+            throw new CliUsageError('The discovery dictionary did not contain any valid terms.');
+        }
+    }
+    const result = generator.generateTyposquatCandidateSet(seed, tlds, {
+        preset: args.preset,
+        keyboardLayout: args.keyboardLayout,
+        dictionaryTerms: dictionaryText,
+        ...(args.preset === 'custom' ? { mutationTypes: mutationFamilies } : {}),
+    });
+    if (!result.inputValid) {
+        throw new CliUsageError('discover requires a valid brand label or domain with one suffix label.');
+    }
+    const normalizedDictionary = generator.normalizeCustomDictionaryTerms(dictionaryText);
+    const metadata = {
+        generatedAt: context.now(),
+        seed,
+        preset: args.preset,
+        keyboardLayout: args.keyboardLayout,
+        tlds,
+        mutationFamilies,
+        dictionaryTermCount: normalizedDictionary.values.length,
+        rejectedDictionaryTermCount: normalizedDictionary.rejectedCount,
+    };
+    return {
+        generator,
+        result,
+        metadata,
+        dictionaryDigestSha256: dictionaryText
+            ? createHash('sha256').update(dictionaryText).digest('hex')
+            : null,
+    };
+}
+export { generateDiscoveryCandidates };

package/cli/doctor.mjs

@@ -0,0 +1,137 @@
+import { resolvePublicAddresses } from "../lib/safe-fetch.mjs";
+import { withTimeout } from "../lib/abort.mjs";
+import { whoisQuery } from "../lib/whois-transport.mjs";
+const DOCTOR_SCHEMA = 'whoisleuth.cli.doctor';
+const DOCTOR_VERSION = 1;
+const MINIMUM_NODE_MAJOR = 24;
+const NETWORK_HOST = 'whois.iana.org';
+const NETWORK_QUERY = 'example.com';
+const NETWORK_TIMEOUT_MS = 6_000;
+const MAX_DOCTOR_DETAIL_LENGTH = 180;
+function boundedDetail(value, fallback) {
+    return String(value || fallback)
+        .replace(/[\u0000-\u001f\u007f]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, MAX_DOCTOR_DETAIL_LENGTH) || fallback;
+}
+function parseNodeMajor(version) {
+    const major = Number(version.split('.')[0]);
+    return Number.isSafeInteger(major) && major >= 0 ? major : 0;
+}
+async function buildDoctorReport(options) {
+    const nodeVersion = boundedDetail(options.nodeVersion || process.versions.node, 'unknown');
+    const nodeSupported = parseNodeMajor(nodeVersion) >= MINIMUM_NODE_MAJOR;
+    const checks = [
+        Object.freeze({
+            id: 'runtime',
+            label: 'Node runtime',
+            state: nodeSupported ? 'pass' : 'partial',
+            detail: nodeSupported
+                ? `Node ${nodeVersion} satisfies the supported Node ${MINIMUM_NODE_MAJOR}+ runtime.`
+                : `Node ${nodeVersion} is below the supported Node ${MINIMUM_NODE_MAJOR}+ runtime.`,
+        }),
+        Object.freeze({
+            id: 'platform',
+            label: 'Platform',
+            state: 'pass',
+            detail: `${boundedDetail(options.platform || process.platform, 'unknown')} · ${boundedDetail(options.architecture || process.arch, 'unknown')}`,
+        }),
+        Object.freeze({
+            id: 'terminal',
+            label: 'Terminal presentation',
+            state: 'pass',
+            detail: options.presentation.interactive
+                ? `Interactive terminal detected at ${options.presentation.width || 'unknown'} columns; semantic colour ${options.presentation.color ? 'enabled' : 'disabled'}.`
+                : 'Non-interactive output detected; colour, wrapping, and transient progress are disabled.',
+        }),
+        Object.freeze({
+            id: 'offline_features',
+            label: 'Offline features',
+            state: 'pass',
+            detail: 'Help, completion, registry coverage, lookalike generation, archive inspection, comparison, export, and signature verification are available without network access.',
+        }),
+    ];
+    if (!options.network) {
+        checks.push(Object.freeze({
+            id: 'network',
+            label: 'Network checks',
+            state: 'skipped',
+            detail: 'Not requested. Run doctor --network to test bounded public DNS and WHOIS connectivity.',
+        }));
+    }
+    else {
+        const resolve = options.resolveAddresses || resolvePublicAddresses;
+        const query = options.queryWhois || whoisQuery;
+        const networkTimeoutMs = Number.isSafeInteger(options.networkTimeoutMs)
+            && Number(options.networkTimeoutMs) >= 1
+            && Number(options.networkTimeoutMs) <= NETWORK_TIMEOUT_MS
+            ? Number(options.networkTimeoutMs)
+            : NETWORK_TIMEOUT_MS;
+        try {
+            const addresses = await withTimeout(() => resolve(NETWORK_HOST), networkTimeoutMs, `Public DNS check timed out after ${networkTimeoutMs} ms.`);
+            checks.push(Object.freeze({
+                id: 'public_dns',
+                label: 'Public DNS',
+                state: addresses.length > 0 ? 'pass' : 'partial',
+                detail: addresses.length > 0
+                    ? `${addresses.length} public address${addresses.length === 1 ? '' : 'es'} validated; addresses were not retained.`
+                    : 'The fixed diagnostic host returned no validated public addresses.',
+            }));
+        }
+        catch (error) {
+            checks.push(Object.freeze({
+                id: 'public_dns',
+                label: 'Public DNS',
+                state: 'partial',
+                detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'Public DNS check failed.'),
+            }));
+        }
+        try {
+            const response = await query(NETWORK_HOST, NETWORK_QUERY, {
+                timeoutMs: Math.max(1, networkTimeoutMs - 1_000),
+                totalDeadlineMs: networkTimeoutMs,
+            });
+            checks.push(Object.freeze({
+                id: 'whois_transport',
+                label: 'WHOIS transport',
+                state: response.trim() ? 'pass' : 'partial',
+                detail: response.trim()
+                    ? 'A bounded port 43 response was received; response content was not retained.'
+                    : 'The fixed diagnostic query returned an empty response.',
+            }));
+        }
+        catch (error) {
+            checks.push(Object.freeze({
+                id: 'whois_transport',
+                label: 'WHOIS transport',
+                state: 'partial',
+                detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'WHOIS transport check failed.'),
+            }));
+        }
+    }
+    const state = checks.some((check) => check.state === 'partial') ? 'partial' : 'pass';
+    return Object.freeze({
+        schema: DOCTOR_SCHEMA,
+        version: DOCTOR_VERSION,
+        generatedAt: options.generatedAt,
+        cliVersion: options.version,
+        state,
+        networkRequested: options.network,
+        checks: Object.freeze(checks),
+    });
+}
+function formatDoctorReport(report) {
+    const lines = [
+        'Runtime:',
+        `CLI version    ${report.cliVersion}`,
+        `Overall        ${report.state === 'pass' ? 'Pass' : 'Partial'}`,
+        '',
+    ];
+    for (const check of report.checks) {
+        lines.push(`[${check.state.toUpperCase()}] ${check.label}`);
+        lines.push(`  Detail       ${check.detail}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export { buildDoctorReport, formatDoctorReport, };