@slicedearth/whoisleuth-cli 1.32.0

package/cli/output-file.mjs

@@ -0,0 +1,97 @@
+import { randomUUID } from 'node:crypto';
+import { unlinkSync } from 'node:fs';
+import { link, open, rename, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { CliUsageError } from "./errors.mjs";
+export const MAX_CLI_OUTPUT_BYTES = 32 * 1024 * 1024;
+const MAX_CLI_OUTPUT_PATH_LENGTH = 4096;
+const pendingOutputFiles = new Set();
+function safeOutputPath(value) {
+    if (typeof value !== 'string' || !value || value.length > MAX_CLI_OUTPUT_PATH_LENGTH) {
+        throw new CliUsageError(`Output paths are limited to ${MAX_CLI_OUTPUT_PATH_LENGTH} characters.`);
+    }
+    if (/[\x00-\x1f\x7f]/u.test(value)) {
+        throw new CliUsageError('Output paths cannot contain control characters.');
+    }
+    return resolve(value);
+}
+function createBufferedOutput() {
+    const chunks = [];
+    let bytes = 0;
+    return Object.freeze({
+        stream: {
+            isTTY: false,
+            columns: 80,
+            write(chunk) {
+                const value = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+                bytes += Buffer.byteLength(value, 'utf8');
+                if (bytes > MAX_CLI_OUTPUT_BYTES) {
+                    throw new CliUsageError(`Generated output is limited to ${MAX_CLI_OUTPUT_BYTES} bytes.`);
+                }
+                chunks.push(value);
+                return true;
+            },
+        },
+        value: () => chunks.join(''),
+    });
+}
+async function writePrivateFile(pathValue, content, options = {}) {
+    const target = safeOutputPath(pathValue);
+    if (Buffer.byteLength(content, 'utf8') > MAX_CLI_OUTPUT_BYTES) {
+        throw new CliUsageError(`Generated output is limited to ${MAX_CLI_OUTPUT_BYTES} bytes.`);
+    }
+    const directory = dirname(target);
+    const temporary = join(directory, `.${basename(target)}.${process.pid}.${randomUUID()}.tmp`);
+    let temporaryCreated = false;
+    try {
+        const handle = await open(temporary, 'wx', 0o600);
+        temporaryCreated = true;
+        pendingOutputFiles.add(temporary);
+        try {
+            await handle.writeFile(content, { encoding: 'utf8' });
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        if (options.force) {
+            await rename(temporary, target);
+            temporaryCreated = false;
+        }
+        else {
+            try {
+                await link(temporary, target);
+            }
+            catch (error) {
+                const code = error && typeof error === 'object' && 'code' in error ? error.code : null;
+                if (code === 'EEXIST') {
+                    throw new CliUsageError(options.existingFileMessage || `Output file already exists: ${target}. Use --force to replace it.`);
+                }
+                throw error;
+            }
+            await unlink(temporary);
+            temporaryCreated = false;
+        }
+        return target;
+    }
+    finally {
+        if (temporaryCreated)
+            await unlink(temporary).catch(() => { });
+        pendingOutputFiles.delete(temporary);
+    }
+}
+function cleanupPendingOutputFilesSync() {
+    for (const path of pendingOutputFiles) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // A second interrupt is an emergency exit. Best-effort cleanup must not
+            // delay it or replace the analyst-requested exit status.
+        }
+        finally {
+            pendingOutputFiles.delete(path);
+        }
+    }
+}
+export { cleanupPendingOutputFilesSync, createBufferedOutput, writePrivateFile };

package/cli/page-compare.mjs

@@ -0,0 +1,123 @@
+import { buildBulkComparisonEvidence } from "../lib/bulk-comparison-evidence.mjs";
+import { createPageBaseline } from "../frontend/src/lib/analysis/page-baseline.js";
+import { comparePageBaselines } from "../frontend/src/lib/analysis/page-similarity.js";
+import { CliUsageError } from "./errors.mjs";
+import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+export const CLI_PAGE_COMPARE_SCHEMA = 'whoisleuth.cli.page-compare';
+export const CLI_PAGE_COMPARE_VERSION = 2;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.flatMap((candidate) => typeof candidate === 'string' ? [candidate] : []))].sort().slice(0, 20);
+}
+function setComparison(left, right) {
+    if (!left.length || !right.length)
+        return 'unavailable';
+    const shared = left.filter((value) => right.includes(value));
+    if (shared.length === left.length && shared.length === right.length)
+        return 'equal';
+    return shared.length ? 'overlap' : 'different';
+}
+function scalarComparison(left, right) {
+    if (!left || !right)
+        return 'unavailable';
+    return left === right ? 'equal' : 'different';
+}
+function comparisonContext(document) {
+    const availability = record(document.availability);
+    const pageBaseline = createPageBaseline(document.registrableDomain, availability);
+    if (!pageBaseline) {
+        throw new CliUsageError(`${document.registrableDomain} does not contain a complete, supported static page-identity observation. Run a deep lookup and save its JSON output first.`);
+    }
+    return {
+        availability,
+        pageBaseline,
+        compact: buildBulkComparisonEvidence(availability),
+    };
+}
+function buildCliPageComparison(leftText, rightText, generatedAt = new Date().toISOString()) {
+    const leftDocument = parseSavedLookupDocument(leftText, { label: 'Left page-comparison input' });
+    const rightDocument = parseSavedLookupDocument(rightText, { label: 'Right page-comparison input' });
+    if (leftDocument.registrableDomain === rightDocument.registrableDomain) {
+        throw new CliUsageError('Page comparison requires lookup documents for two different domains.');
+    }
+    const left = comparisonContext(leftDocument);
+    const right = comparisonContext(rightDocument);
+    const page = comparePageBaselines(left.pageBaseline, right.pageBaseline);
+    if (!page)
+        throw new CliUsageError('The static page observations could not be compared.');
+    const leftTechnology = stringList(left.compact.technology.ids);
+    const rightTechnology = stringList(right.compact.technology.ids);
+    const sharedTechnology = leftTechnology.filter((id) => rightTechnology.includes(id));
+    const technologyUsable = ['success', 'partial'].includes(left.compact.technology.state)
+        && ['success', 'partial'].includes(right.compact.technology.state);
+    const tlsUsable = ['success', 'partial'].includes(left.compact.tls.state)
+        && ['success', 'partial'].includes(right.compact.tls.state);
+    return {
+        schema: CLI_PAGE_COMPARE_SCHEMA,
+        version: CLI_PAGE_COMPARE_VERSION,
+        generatedAt,
+        left: {
+            domain: leftDocument.registrableDomain,
+            observedAt: left.pageBaseline.observedAt,
+            complete: left.pageBaseline.complete,
+        },
+        right: {
+            domain: rightDocument.registrableDomain,
+            observedAt: right.pageBaseline.observedAt,
+            complete: right.pageBaseline.complete,
+        },
+        page,
+        technology: {
+            state: technologyUsable ? setComparison(leftTechnology, rightTechnology) : 'unavailable',
+            leftSourceState: left.compact.technology.state,
+            rightSourceState: right.compact.technology.state,
+            leftIds: leftTechnology,
+            rightIds: rightTechnology,
+            sharedIds: sharedTechnology,
+            partial: left.compact.technology.truncated || right.compact.technology.truncated
+                || left.compact.technology.state === 'partial' || right.compact.technology.state === 'partial',
+        },
+        tls: {
+            leftSourceState: left.compact.tls.state,
+            rightSourceState: right.compact.tls.state,
+            issuer: {
+                state: tlsUsable ? scalarComparison(left.compact.tls.issuerLabel, right.compact.tls.issuerLabel) : 'unavailable',
+                left: left.compact.tls.issuerLabel,
+                right: right.compact.tls.issuerLabel,
+            },
+            publicKey: {
+                state: tlsUsable ? scalarComparison(left.compact.tls.spkiSha256, right.compact.tls.spkiSha256) : 'unavailable',
+                leftSha256: left.compact.tls.spkiSha256,
+                rightSha256: right.compact.tls.spkiSha256,
+            },
+        },
+        limitations: [
+            'This comparison is offline and uses only bounded static page, favicon, technology, and TLS evidence retained in two saved deep lookups.',
+            'A partial, missing, or unavailable component is never interpreted as an observed difference or absence.',
+            'Matching components are investigative relationships and do not establish copying, common ownership, control, intent, safety, or maliciousness.',
+            'Static page collection does not execute JavaScript and can differ from a rendered browser capture.',
+        ],
+    };
+}
+function formatCliPageComparison(document) {
+    const lines = [
+        'Static page comparison',
+        `Left             ${document.left.domain}`,
+        `Right            ${document.right.domain}`,
+        `Page evidence    ${document.page.partial ? 'Partial' : 'Complete'}`,
+        '',
+        'Page identity',
+    ];
+    for (const component of document.page.components) {
+        lines.push(`${component.label.padEnd(18)} ${component.outcome}`);
+    }
+    lines.push('', 'Technology', `Relationship     ${document.technology.state}`, `Shared           ${document.technology.sharedIds.join(', ') || 'None observed'}`, `Left             ${document.technology.leftIds.join(', ') || 'Unavailable'}`, `Right            ${document.technology.rightIds.join(', ') || 'Unavailable'}`, '', 'TLS', `Issuer           ${document.tls.issuer.state}`, `Public key       ${document.tls.publicKey.state}`, '', 'Limitations:');
+    for (const limitation of document.limitations)
+        lines.push(`  - ${limitation}`);
+    return `${lines.join('\n')}\n`;
+}
+export { buildCliPageComparison, formatCliPageComparison };

package/cli/posture.mjs

@@ -0,0 +1,20 @@
+import { CliUsageError } from "./arguments.mjs";
+const MAX_POSTURE_SELECTORS = 10;
+function normalizePostureSelectors(raw, normalizeSelectors) {
+    if (raw === null || raw === undefined || raw === '')
+        return [];
+    const tokens = String(raw).split(',').map((value) => value.trim());
+    if (tokens.some((value) => !value)) {
+        throw new CliUsageError('--selectors cannot contain empty entries.');
+    }
+    const canonical = [...new Set(tokens.map((value) => value.toLowerCase().replace(/^\.+|\.+$/g, '')))];
+    if (canonical.length > MAX_POSTURE_SELECTORS) {
+        throw new CliUsageError(`--selectors supports at most ${MAX_POSTURE_SELECTORS} unique selectors.`);
+    }
+    const normalized = normalizeSelectors(tokens);
+    if (normalized.length !== canonical.length || normalized.some((value, index) => value !== canonical[index])) {
+        throw new CliUsageError('--selectors contains an invalid DKIM selector.');
+    }
+    return normalized;
+}
+export { MAX_POSTURE_SELECTORS, normalizePostureSelectors };

package/cli/progress-events.mjs

@@ -0,0 +1,53 @@
+export const CLI_PROGRESS_EVENT_SCHEMA = 'whoisleuth.cli.progress';
+export const CLI_PROGRESS_EVENT_VERSION = 1;
+const MAX_CLI_PROGRESS_EVENTS = 2_100;
+const MAX_CLI_PROGRESS_EVENT_DETAIL_LENGTH = 120;
+function text(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value
+        .replace(/[\x00-\x1f\x7f]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, MAX_CLI_PROGRESS_EVENT_DETAIL_LENGTH);
+    return normalized || null;
+}
+function integer(value, minimum, maximum) {
+    return Number.isSafeInteger(value) && Number(value) >= minimum && Number(value) <= maximum
+        ? Number(value)
+        : null;
+}
+function createCliProgressEvents(stream, options) {
+    const enabled = options.enabled === true && Boolean(stream);
+    const now = options.now || (() => new Date().toISOString());
+    let sequence = 0;
+    return Object.freeze({
+        enabled,
+        emit(fields) {
+            if (!enabled || !stream || sequence >= MAX_CLI_PROGRESS_EVENTS)
+                return;
+            const source = text(fields.source);
+            const state = text(fields.state);
+            const reason = text(fields.reason);
+            const index = integer(fields.index, 0, 10_000);
+            const exitCode = integer(fields.exitCode, 0, 255);
+            const document = {
+                schema: CLI_PROGRESS_EVENT_SCHEMA,
+                version: CLI_PROGRESS_EVENT_VERSION,
+                sequence,
+                generatedAt: now(),
+                command: options.command,
+                event: fields.event,
+                ...(source ? { source } : {}),
+                ...(state ? { state } : {}),
+                ...(reason ? { reason } : {}),
+                ...(index !== null ? { index } : {}),
+                ...(typeof fields.ok === 'boolean' ? { ok: fields.ok } : {}),
+                ...(exitCode !== null ? { exitCode } : {}),
+            };
+            stream.write(`${JSON.stringify(document)}\n`);
+            sequence += 1;
+        },
+    });
+}
+export { createCliProgressEvents };

package/cli/progress.mjs

@@ -0,0 +1,56 @@
+import { terminalPresentation, tone, } from "./terminal-presentation.mjs";
+const PROGRESS_FRAMES = Object.freeze(['◐', '◓', '◑', '◒']);
+const MAX_PROGRESS_MESSAGE_LENGTH = 160;
+function safeProgressMessage(value) {
+    return String(value || 'Working')
+        .replace(/[\u0000-\u001f\u007f]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, MAX_PROGRESS_MESSAGE_LENGTH) || 'Working';
+}
+function createTerminalProgress(stream, options) {
+    const environment = options.environment || process.env;
+    const presentation = terminalPresentation(stream, options.color, environment);
+    const enabled = options.enabled
+        && presentation.interactive
+        && environment.WHOISLEUTH_NO_PROGRESS !== '1';
+    const now = options.now || Date.now;
+    let startedAt = 0;
+    let frame = 0;
+    let message = '';
+    let timer = null;
+    function render() {
+        if (!enabled || !stream)
+            return;
+        const elapsedSeconds = Math.max(0, Math.floor((now() - startedAt) / 1000));
+        const marker = tone(PROGRESS_FRAMES[frame % PROGRESS_FRAMES.length] || '·', 'accent', presentation.color);
+        const elapsed = tone(`${elapsedSeconds}s`, 'dim', presentation.color);
+        stream.write(`\r\u001b[2K${marker} ${message} · ${elapsed}`);
+        frame += 1;
+    }
+    function start(nextMessage) {
+        if (!enabled || timer)
+            return;
+        startedAt = now();
+        message = safeProgressMessage(nextMessage);
+        render();
+        timer = setInterval(render, 250);
+        timer.unref?.();
+    }
+    function update(nextMessage) {
+        if (!enabled)
+            return;
+        message = safeProgressMessage(nextMessage);
+        render();
+    }
+    function stop() {
+        if (!enabled || !stream)
+            return;
+        if (timer)
+            clearInterval(timer);
+        timer = null;
+        stream.write('\r\u001b[2K');
+    }
+    return Object.freeze({ enabled, start, update, stop });
+}
+export { createTerminalProgress, safeProgressMessage, };

package/cli/registry-access.mjs

@@ -0,0 +1,3 @@
+// Compatibility re-export for CLI consumers. Registry access labels are also
+// used by the shared readable evidence report.
+export * from "../lib/registry-access.mjs";

package/cli/registry-support.mjs

@@ -0,0 +1,120 @@
+import { registryStandardsCoverageSnapshot, } from "../lib/registry-capabilities.mjs";
+const REGISTRY_SUPPORT_SCHEMA = 'whoisleuth.cli.registry-support';
+const REGISTRY_SUPPORT_SCHEMA_VERSION = 2;
+const REGISTRY_STANDARDS_COVERAGE_SCHEMA = 'whoisleuth.registry-standards-coverage';
+const MAX_REGISTRY_SUPPORT_TEXT_LENGTH = 2048;
+const MAX_REGISTRY_SUPPORT_REFERENCES = 20;
+const MAX_REGISTRY_SUPPORT_REFERENCE_LENGTH = 2048;
+function boundedText(value, fallback = 'unknown', maximum = MAX_REGISTRY_SUPPORT_TEXT_LENGTH) {
+    if (typeof value !== 'string')
+        return fallback;
+    const normalized = value
+        .replace(/[\x00-\x1f\x7f]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maximum);
+    return normalized || fallback;
+}
+function boundedList(values, kind) {
+    if (!Array.isArray(values))
+        return [];
+    const output = [];
+    for (const value of values.slice(0, MAX_REGISTRY_SUPPORT_REFERENCES)) {
+        const text = boundedText(value, '', MAX_REGISTRY_SUPPORT_REFERENCE_LENGTH);
+        if (!text)
+            continue;
+        if (kind === 'token' && !/^[a-z0-9][a-z0-9_-]{0,127}$/i.test(text))
+            continue;
+        if (kind === 'file' && (text.startsWith('/') || text.includes('..') || !/^[a-z0-9_./-]+$/i.test(text)))
+            continue;
+        if (kind === 'url') {
+            try {
+                const url = new URL(text);
+                if (url.protocol !== 'https:' || url.username || url.password)
+                    continue;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!output.includes(text))
+            output.push(text);
+    }
+    return output;
+}
+function boundedCount(value, maximum = 100000) {
+    return Number.isSafeInteger(value) && Number(value) >= 0
+        ? Math.min(Number(value), maximum)
+        : 0;
+}
+function projectStandardsCoverage(snapshot) {
+    const counts = snapshot?.counts || {};
+    return {
+        schema: REGISTRY_STANDARDS_COVERAGE_SCHEMA,
+        version: boundedCount(snapshot?.version, 1000),
+        verifiedAt: boundedText(snapshot?.verifiedAt, 'unknown', 32),
+        rootZoneVersion: boundedText(snapshot?.sources?.rootZoneVersion, 'unknown', 64),
+        rdapBootstrapPublication: boundedText(snapshot?.sources?.rdapBootstrapPublication, 'unknown', 64),
+        genericAndRestricted: {
+            total: boundedCount(counts.generic) + boundedCount(counts.genericRestricted),
+            rdapCovered: boundedCount(counts.genericAndRestrictedRdapCovered),
+        },
+        sponsored: {
+            total: boundedCount(counts.sponsored),
+            rdapCovered: boundedCount(counts.sponsoredRdapCovered),
+        },
+        infrastructure: {
+            total: boundedCount(counts.infrastructure),
+            rdapCovered: boundedCount(counts.infrastructureRdapCovered),
+        },
+        interpretation: boundedText(snapshot?.interpretation),
+    };
+}
+function buildRegistrySupportDocument(requestedInput, capability, catalogueVersion, generatedAt = new Date().toISOString(), standardsSnapshot = registryStandardsCoverageSnapshot()) {
+    const suffix = boundedText(capability.suffixes?.[0], '', 63).toLowerCase();
+    if (!suffix || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(suffix)) {
+        throw new TypeError('Registry capability did not provide a valid suffix.');
+    }
+    return {
+        schema: REGISTRY_SUPPORT_SCHEMA,
+        version: REGISTRY_SUPPORT_SCHEMA_VERSION,
+        generatedAt: boundedText(generatedAt, '', 64),
+        requestedInput: boundedText(requestedInput, '', 253),
+        suffix,
+        catalogueVersion: Number.isSafeInteger(catalogueVersion) && catalogueVersion > 0 ? catalogueVersion : 0,
+        standardsCoverage: projectStandardsCoverage(standardsSnapshot),
+        profile: {
+            id: boundedText(capability.id, 'unknown', 128),
+            explicitSuffixProfile: capability.explicitSuffixProfile === true,
+            registryClass: boundedText(capability.registryClass, 'unknown', 64),
+            coverageState: boundedText(capability.coverageState, 'unknown', 64),
+            rdap: {
+                discovery: boundedText(capability.rdapDiscovery, 'unknown', 64),
+                accessProfile: boundedText(capability.rdapAccessProfile, 'unknown', 128),
+            },
+            whois: {
+                discovery: boundedText(capability.whoisDiscovery, 'unknown', 64),
+                accessProfile: boundedText(capability.whoisAccessProfile, 'unknown', 128),
+                queryProfile: boundedText(capability.whoisQueryProfile, 'unknown', 128),
+                queryScope: boundedText(capability.whoisQueryScope, 'unknown', 64),
+                encodingProfile: boundedText(capability.whoisEncodingProfile, 'unknown', 64),
+                parserProfile: boundedText(capability.whoisParserProfile, 'unknown', 128),
+            },
+            fallbackProfile: capability.fallbackProfile
+                ? boundedText(capability.fallbackProfile, 'unknown', 128)
+                : null,
+        },
+        verification: {
+            fixtureScenarios: boundedList(capability.fixtureScenarios, 'token'),
+            files: boundedList(capability.verificationFiles, 'file'),
+            documentationUrls: boundedList(capability.documentationUrls, 'url'),
+        },
+        limitation: boundedText(capability.limitation),
+        interpretation: {
+            authority: 'context_only',
+            liveReachability: 'not_tested',
+            statement: 'Catalogue coverage does not test current live reachability or decide registration, availability, ownership, safety, or maliciousness.',
+        },
+    };
+}
+export { MAX_REGISTRY_SUPPORT_REFERENCE_LENGTH, MAX_REGISTRY_SUPPORT_REFERENCES, MAX_REGISTRY_SUPPORT_TEXT_LENGTH, REGISTRY_STANDARDS_COVERAGE_SCHEMA, REGISTRY_SUPPORT_SCHEMA, REGISTRY_SUPPORT_SCHEMA_VERSION, buildRegistrySupportDocument, projectStandardsCoverage, };