@slicedearth/whoisleuth-cli 2.2.0 → 2.3.0

package/cli/completion.mjs

@@ -266,7 +266,7 @@ fi
 `;
 }
 function fishCompletion() {
-    const commandLines = CLI_COMMANDS.map((command) => (`complete -c whoisleuth -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command]}'`));
+    const commandLines = CLI_COMMANDS.map((command) => (`__whoisleuth_add_command '${command}' '${COMMAND_DESCRIPTIONS[command]}'`));
     const optionGroups = new Map();
     for (const definition of CLI_COMMAND_REGISTRY) {
         for (const option of definition.grammar.options) {
@@ -373,6 +373,9 @@ function __whoisleuth_command_is
     test (count \$words) -ge 2; or return 1
     contains -- \$words[2] $argv
 end
+function __whoisleuth_add_command
+    complete -c whoisleuth -n '__fish_use_subcommand' -a \$argv[1] -d \$argv[2]
+end
 function __whoisleuth_integer_values
     set -l value $argv[1]
     while test $value -le $argv[2]
@@ -434,6 +437,7 @@ end
 complete -c whoisleuth -f
 ${[HELP_META_ACTION, VERSION_META_ACTION].map((action) => (`complete -c whoisleuth -n '__fish_use_subcommand' -s ${shortMetaAlias(action).slice(1)} -l ${longMetaAlias(action).slice(2)}`)).join('\n')}
 ${commandLines.join('\n')}
+functions -e __whoisleuth_add_command
 ${positionalEnumLines.join('\n')}
 complete -c whoisleuth -n '__whoisleuth_file_position' -F
 ${optionLines.join('\n')}

package/cli/discovery-observation-snapshot.mjs

@@ -84,7 +84,11 @@ function normalizeObservation(value) {
             return null;
         const latestRegistrationState = item.latestRegistrationState;
         const latestDnsState = item.latestDnsState;
+        const collectionOrigin = item.collectionOrigin === undefined
+            ? 'current_run'
+            : item.collectionOrigin;
         if (!['observed', 'unavailable'].includes(String(latestRegistrationState))
+            || !['current_run', 'resumed_checkpoint'].includes(String(collectionOrigin))
             || typeof latestDnsState !== 'string' || !latestDnsState || latestDnsState.length > 40
             || /[\u0000-\u001f\u007f]/u.test(latestDnsState))
             return null;
@@ -96,6 +100,7 @@ function normalizeObservation(value) {
             registrationObservedAt,
             dnsObservedAt,
             latestAttemptAt: normalizedTimestamp(item.latestAttemptAt, 'Discovery latest-attempt time') ?? '',
+            collectionOrigin: collectionOrigin,
             latestAttemptState: item.latestAttemptState,
             latestRegistrationState: latestRegistrationState,
             latestDnsState,
@@ -167,6 +172,13 @@ async function readExisting(path) {
     }
 }
 function currentAttempt(domain, item, previous, generatedAt, deep) {
+    const suppliedObservedAt = item.observedAt === null || item.observedAt === undefined
+        ? null
+        : normalizedTimestamp(item.observedAt, 'Discovery checkpoint observation time');
+    if (item.collectionOrigin === 'resumed_checkpoint' && !suppliedObservedAt) {
+        throw new CliUsageError('Discovery resume requires a valid observation time for retained checkpoint evidence.');
+    }
+    const attemptAt = suppliedObservedAt ?? generatedAt;
     const availability = item.ok ? record(record(item.result).availability) : {};
     const currentAvailabilityState = availabilityState(item) || 'unknown';
     const registrationObserved = item.ok && currentAvailabilityState !== 'unknown';
@@ -177,9 +189,9 @@ function currentAttempt(domain, item, previous, generatedAt, deep) {
     const dns = dnsComplete || (dnsRetainable && !previousDnsRetainable)
         ? currentDns
         : previousDnsRetainable ? previous.dns : currentDns;
-    const registrationObservedAt = registrationObserved ? generatedAt : previous?.registrationObservedAt ?? null;
+    const registrationObservedAt = registrationObserved ? attemptAt : previous?.registrationObservedAt ?? null;
     const dnsObservedAt = dnsComplete || (dnsRetainable && !previousDnsRetainable)
-        ? generatedAt
+        ? attemptAt
         : previous?.dnsObservedAt ?? null;
     const unavailableComponents = [];
     if (!registrationObserved)
@@ -204,7 +216,8 @@ function currentAttempt(domain, item, previous, generatedAt, deep) {
             observedAt: latestObservedAt(registrationObservedAt, dnsObservedAt),
             registrationObservedAt,
             dnsObservedAt,
-            latestAttemptAt: generatedAt,
+            latestAttemptAt: attemptAt,
+            collectionOrigin: item.collectionOrigin ?? 'current_run',
             latestAttemptState: attemptState,
             latestRegistrationState: registrationObserved ? 'observed' : 'unavailable',
             latestDnsState: deep ? currentDns.status : 'not_requested',

package/cli/discovery-scan-command-runner.mjs

@@ -62,6 +62,9 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
     const classify = dependencies.classifyQuery || classifyQuery;
     const allowlist = await readAllowlist(args.allowlistSource, dependencies, context, classify);
     const checkpointWriter = dependencies.createBulkCheckpointWriter || createBulkCheckpointWriter;
+    const collectionContext = resolverServers.length
+        ? { dnsResolver: 'analyst_selected', resolverServers: [...resolverServers] }
+        : { dnsResolver: 'system_default', resolverServers: [] };
     const checkpoint = args.checkpoint
         ? await checkpointWriter({
             path: args.checkpoint,
@@ -72,6 +75,20 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
             ...(dependencies.now ? { now: dependencies.now } : {}),
         })
         : null;
+    for (const item of checkpoint?.initialResults ?? []) {
+        const retainedContext = item.collectionContext;
+        const contextMatches = retainedContext
+            ? retainedContext.dnsResolver === collectionContext.dnsResolver
+                && retainedContext.resolverServers.length === collectionContext.resolverServers.length
+                && retainedContext.resolverServers.every((server, index) => server === collectionContext.resolverServers[index])
+            : collectionContext.dnsResolver === 'system_default';
+        if (!contextMatches) {
+            throw new CliUsageError('Bulk checkpoint collection context does not match the current DNS resolver selection.');
+        }
+        if (item.observedAt === null || item.observedAt === undefined) {
+            throw new CliUsageError('Discovery resume requires an observation time for every retained checkpoint result.');
+        }
+    }
     const indicator = context.beginProgress(`Collecting 0 of ${queries.length} generated candidates`);
     let completed = checkpoint?.initialResults.length || 0;
     const resumedItems = new Map((checkpoint?.initialResults ?? []).map((item) => [item.index, item]));
@@ -95,6 +112,7 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
                     ...item,
                     observedAt: context.now(),
                     collectionOrigin: 'current_run',
+                    collectionContext,
                 };
                 settledItems.set(item.index, observed);
                 completed += 1;
@@ -107,6 +125,7 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
             ...item,
             observedAt: null,
             collectionOrigin: 'current_run',
+            collectionContext,
         });
     }
     finally {

package/cli/discovery-scan.mjs

@@ -125,6 +125,12 @@ function buildScanItem(candidate, item, allowlist, relationshipIds = []) {
         dnsSummary: bulkDnsSummary(item),
         review: { lane: review.lane, reasons: review.reasons },
         relationshipIds: [...relationshipIds],
+        observedAt: item.observedAt ?? null,
+        collectionOrigin: item.collectionOrigin ?? 'current_run',
+        collectionContext: item.collectionContext ?? {
+            dnsResolver: 'system_default',
+            resolverServers: [],
+        },
         ...(item.ok ? {
             availability: result.availability,
             diagnostics: result.diagnostics,

package/cli/domain-control-observations.mjs

@@ -115,7 +115,7 @@ export function domainControlObservationFromSavedLookup(document) {
         field('registry_nameservers', 'Registry RDAP', rdapState, list(rdapParsed.nameservers, hostname)),
         field('whois_nameservers', 'WHOIS', diagnostic(document, 'whois'), list(record(record(document.whois).parsed).nameservers, hostname)),
         field('delegated_nameservers', 'DNS', dnsState, list(dnsRecords.ns, hostname)),
-        field('delegation_ds', 'DNS delegation', state(delegation.status ?? dns.status), list(delegationRecords.ds ?? rdapParsed.dsData, dsValue)),
+        field('delegation_ds', 'DNS delegation', state(delegation.status), list(delegationRecords.ds, dsValue)),
         field('mail_exchangers', 'DNS', dnsState, list(dnsRecords.mx, mxValue)),
         field('caa_policy', 'DNS', dnsState, list(record(dns.caaPolicy).records ?? dnsRecords.caa, caaValue)),
         field('tls_certificate', 'TLS', tlsState, list([certificate.fingerprintSha256 ?? tls.fingerprintSha256], (item) => text(item, 128))),

package/cli/inline-command-families.mjs

@@ -17,6 +17,7 @@ const REVIEW_INLINE_COMMANDS = Object.freeze([
     'compare',
     'page-compare',
     'mail-review',
+    'mail-headers',
     'review-evidence',
     'brief',
     'case-pack',

package/cli/input.mjs

@@ -1,6 +1,46 @@
 import { Buffer } from 'node:buffer';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
 import { decodeBoundedUtf8, readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
 import { CliUsageError } from "./errors.mjs";
+function headerEnd(bytes) {
+    for (let index = 0; index < bytes.length - 1; index += 1) {
+        if (bytes[index] === 0x0a && bytes[index + 1] === 0x0a)
+            return index;
+        if (index < bytes.length - 3
+            && bytes[index] === 0x0d && bytes[index + 1] === 0x0a
+            && bytes[index + 2] === 0x0d && bytes[index + 3] === 0x0a)
+            return index;
+    }
+    return -1;
+}
+function decodeHeaderStorage(storage, length, maximumBytes, label) {
+    const end = headerEnd(storage.subarray(0, length));
+    if ((end < 0 && length > maximumBytes) || end > maximumBytes) {
+        throw new CliUsageError(`${label} is limited to ${maximumBytes} bytes before the message body.`);
+    }
+    return decodeBoundedUtf8(storage.subarray(0, end < 0 ? length : end), label);
+}
+function appendUntilHeaderEnd(storage, offset, input) {
+    let nextOffset = offset;
+    for (const byte of input) {
+        if (nextOffset >= storage.length)
+            return Object.freeze({ offset: nextOffset, complete: false });
+        storage[nextOffset] = byte;
+        nextOffset += 1;
+        const lfBoundary = nextOffset >= 2
+            && storage[nextOffset - 2] === 0x0a
+            && storage[nextOffset - 1] === 0x0a;
+        const crlfBoundary = nextOffset >= 4
+            && storage[nextOffset - 4] === 0x0d
+            && storage[nextOffset - 3] === 0x0a
+            && storage[nextOffset - 2] === 0x0d
+            && storage[nextOffset - 1] === 0x0a;
+        if (lfBoundary || crlfBoundary)
+            return Object.freeze({ offset: nextOffset, complete: true });
+    }
+    return Object.freeze({ offset: nextOffset, complete: false });
+}
 function abortError(signal) {
     return signal.reason instanceof Error
         ? signal.reason
@@ -60,3 +100,79 @@ export async function readCliTextInput(source, stdin, options) {
         options.signal?.removeEventListener('abort', onAbort);
     }
 }
+/**
+ * Read only the RFC-style header block from a selected regular file or stdin.
+ * The fixed retained allocation includes delimiter look-ahead but accumulates
+ * only bytes through the first header/body boundary. A regular file may be
+ * larger than the header limit while parsing stays tied to the admitted prefix.
+ */
+export async function readCliHeaderInput(source, stdin, options) {
+    if (!Number.isSafeInteger(options.maximumBytes) || options.maximumBytes < 1 || options.maximumBytes > 1024 * 1024) {
+        throw new TypeError('Header input has an invalid byte boundary.');
+    }
+    if (options.signal?.aborted)
+        throw abortError(options.signal);
+    const storage = Buffer.allocUnsafe(options.maximumBytes + 4);
+    if (source) {
+        let handle;
+        try {
+            handle = await open(source, constants.O_RDONLY | constants.O_NONBLOCK);
+            const before = await handle.stat();
+            if (!before.isFile())
+                throw new CliUsageError(`${options.label} must be a regular file.`);
+            let offset = 0;
+            let complete = false;
+            const chunk = Buffer.allocUnsafe(Math.min(4 * 1024, storage.length));
+            while (offset < storage.length && !complete) {
+                if (options.signal?.aborted)
+                    throw abortError(options.signal);
+                const result = await handle.read(chunk, 0, Math.min(chunk.length, storage.length - offset), null);
+                if (result.bytesRead === 0)
+                    break;
+                ({ offset, complete } = appendUntilHeaderEnd(storage, offset, chunk.subarray(0, result.bytesRead)));
+            }
+            chunk.fill(0);
+            const after = await handle.stat();
+            if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+                throw new CliUsageError(`${options.label} changed while it was being read.`);
+            }
+            return decodeHeaderStorage(storage, offset, options.maximumBytes, options.label);
+        }
+        catch (error) {
+            if (error instanceof CliUsageError || options.signal?.aborted)
+                throw error;
+            const message = error instanceof Error ? error.message : `${options.label} could not be read.`;
+            throw new CliUsageError(message);
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    if (!stdin || stdin.isTTY)
+        return '';
+    let offset = 0;
+    const onAbort = () => {
+        if ('destroy' in stdin && typeof stdin.destroy === 'function')
+            stdin.destroy(abortError(options.signal));
+    };
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for await (const chunk of stdin) {
+            if (options.signal?.aborted)
+                throw abortError(options.signal);
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const retained = appendUntilHeaderEnd(storage, offset, bytes);
+            offset = retained.offset;
+            if (retained.complete)
+                break;
+            if (offset >= storage.length)
+                break;
+        }
+        if (options.signal?.aborted)
+            throw abortError(options.signal);
+        return decodeHeaderStorage(storage, offset, options.maximumBytes, options.label);
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+    }
+}

package/cli/interchange-report.mjs

@@ -198,6 +198,19 @@ export async function buildInterchangeFidelityReport(raw, options = {}) {
 export function formatInterchangeFidelityReport(report) {
     const browser = report.compatibility.browser;
     const cli = report.compatibility.cli;
+    const nextAction = !report.recognised
+        ? 'Choose a supported WHOISleuth export and run verify-artifact before trying to import it.'
+        : !report.artifact.versionSupported
+            ? 'Use a WHOISleuth release that supports this exact version, or re-export it with its last supported release.'
+            : !report.verification.assuranceSatisfied
+                ? 'Do not import or share this artefact yet; run verify-artifact and resolve the reported structure or integrity failure.'
+                : report.compatibility.fullyImportable === false
+                    ? 'Review unsupported, blocked, skipped or pruned records before selecting any import.'
+                    : browser?.import === 'supported'
+                        ? 'Open the browser import preview and review the proposed additions and updates before applying them.'
+                        : cli?.read === 'supported'
+                            ? 'Use the declared offline CLI reader; browser import is not supported for this artefact.'
+                            : 'Retain the verification result and use only the operations declared above.';
     return [
         'Interchange fidelity report',
         `Recognised     ${report.recognised ? 'yes' : 'no'}`,
@@ -219,6 +232,7 @@ export function formatInterchangeFidelityReport(report) {
         '',
         `Preserved      ${report.compatibility.preservedFieldGroups.join(', ') || 'none declared'}`,
         `Excluded       ${report.compatibility.excludedFieldGroups.join(', ') || 'none declared'}`,
+        `Next action    ${nextAction}`,
         '',
         ...report.limitations.map((item) => `Limitation: ${item}`),
         '',

package/cli/lookalike-calibration.mjs

@@ -6,7 +6,9 @@ const LOOKALIKE_CALIBRATION_VERSION = 1;
 const MAX_LOOKALIKE_CALIBRATION_BYTES = 2 * 1024 * 1024;
 const MAX_LOOKALIKE_CALIBRATION_RECORDS = 5_000;
 const MIN_LOOKALIKE_CALIBRATION_SAMPLE = 20;
-const DISPOSITIONS = ['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action'];
+// Version 1 intentionally admits reviewed Case dispositions only. This local
+// schema remains an independent compatibility decision from the live Case model.
+const DISPOSITIONS = Object.freeze(['suspicious', 'confirmed_abuse', 'false_positive', 'expected', 'closed_no_action']);
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -22,7 +24,10 @@ function ratio(value, total) {
     return total ? Number((value / total).toFixed(4)) : 0;
 }
 function emptyCounts() {
-    return { suspicious: 0, confirmed_abuse: 0, false_positive: 0, expected: 0, closed_no_action: 0 };
+    const counts = {};
+    for (const disposition of DISPOSITIONS)
+        counts[disposition] = 0;
+    return counts;
 }
 function buildLookalikeCalibration(raw, generatedAt = new Date().toISOString()) {
     if (Buffer.byteLength(raw, 'utf8') > MAX_LOOKALIKE_CALIBRATION_BYTES) {

package/cli/lookup-brief.mjs

@@ -111,8 +111,10 @@ export function buildCliLookupBrief(input, generatedAt = new Date().toISOString(
     const facts = [
         ['registration-state', 'Registration state', availability.state, availabilitySource.id],
         ['registrar', 'Registrar', record(preferred.registrar).name ?? preferred.registrar, preferredRegistrationSource.id],
-        ['created', 'Created', record(preferred.lifecycle).createdIso ?? preferred.createdDateIso, preferredRegistrationSource.id],
-        ['expires', 'Expires', record(preferred.lifecycle).expiryIso ?? preferred.expiryDateIso, preferredRegistrationSource.id],
+        ['created', 'Created', record(preferred.lifecycle).createdDateIso
+                ?? record(preferred.lifecycle).createdIso ?? preferred.createdDateIso, preferredRegistrationSource.id],
+        ['expires', 'Expires', record(preferred.lifecycle).expiryDateIso
+                ?? record(preferred.lifecycle).expiryIso ?? preferred.expiryDateIso, preferredRegistrationSource.id],
         ['name-servers', 'Name servers', joinedText(preferred.nameservers), preferredRegistrationSource.id],
         ['website-activity', 'Website activity', availability.activityStatus, httpSource.id],
         ['page-title', 'Page title', availability.pageTitle, httpSource.id],

package/cli/lookup-browser-view.mjs

@@ -2,7 +2,7 @@ import { formatTerminalLookup, safeTerminalValue } from "./formatters/terminal.m
 import { presentTerminalOutput, wrapTerminalOutput, } from "./terminal-presentation.mjs";
 const MIN_LOOKUP_BROWSER_HEIGHT = 12;
 const MAX_LOOKUP_BROWSER_HEIGHT = 80;
-const MAX_LOOKUP_BROWSER_PANELS = 9;
+const MAX_LOOKUP_BROWSER_PANELS = 16;
 const MAX_LOOKUP_BROWSER_SEARCH_BYTES = 256;
 const MAX_LOOKUP_BROWSER_SEARCH_SCALARS = 80;
 const MAX_LOOKUP_BROWSER_SEARCH_MATCHES = 256;