@slicedearth/whoisleuth-cli 1.47.4 → 2.0.0

package/cli/config-profile.mjs

@@ -2,12 +2,14 @@ import { Buffer } from 'node:buffer';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { CliUsageError } from "./errors.mjs";
+import { cliMetaActionForInvocation } from "./command-reference.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
 export const CLI_CONFIG_SCHEMA = 'whoisleuth.cli.config';
 export const CLI_CONFIG_VERSION = 1;
 export const MAX_CLI_CONFIG_BYTES = 64 * 1024;
 const SAFE_BOOLEAN_DEFAULTS = new Set(['--no-color', '--summary', '--verbose', '--fast']);
-const SAFE_VALUE_DEFAULTS = new Set(['--concurrency', '--observer', '--vantage']);
+const SAFE_VALUE_DEFAULTS = new Set(['--concurrency', '--observer', '--palette', '--vantage']);
 const OPTION_GROUPS = Object.freeze({
     '--no-color': 'colour',
     '--summary': 'detail',
@@ -15,6 +17,7 @@ const OPTION_GROUPS = Object.freeze({
     '--fast': 'scan',
     '--concurrency': 'concurrency',
     '--observer': 'observer',
+    '--palette': 'colour',
     '--vantage': 'vantage',
 });
 function validProfileName(value) {
@@ -54,6 +57,9 @@ function validateProfileArguments(value) {
         if (argument === '--concurrency' && (!/^\d+$/u.test(next) || Number(next) < 1 || Number(next) > 8)) {
             throw new CliUsageError('CLI profile concurrency must be an integer from 1 to 8.');
         }
+        if (argument === '--palette' && !['auto', 'light', 'dark'].includes(next)) {
+            throw new CliUsageError('CLI profile palette must be auto, light, or dark.');
+        }
         groups.add(group);
         validated.push(argument, next);
     }
@@ -62,12 +68,14 @@ function validateProfileArguments(value) {
 function parseProfileDocument(input) {
     if (Buffer.byteLength(input, 'utf8') > MAX_CLI_CONFIG_BYTES)
         throw new CliUsageError('CLI configuration is limited to 64 KiB.');
+    const normalized = input.replace(/^\uFEFF/u, '');
     let parsed;
     try {
-        parsed = JSON.parse(input.replace(/^\uFEFF/u, ''));
+        scanBoundedJson(normalized);
+        parsed = JSON.parse(normalized);
     }
     catch {
-        throw new CliUsageError('CLI configuration must be valid JSON.');
+        throw new CliUsageError('CLI configuration must be valid bounded JSON without duplicate keys.');
     }
     const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
     if (root.schema !== CLI_CONFIG_SCHEMA || root.version !== CLI_CONFIG_VERSION || !root.profiles || typeof root.profiles !== 'object' || Array.isArray(root.profiles)) {
@@ -109,6 +117,8 @@ function suppliedGroups(argumentsList) {
     return groups;
 }
 export async function resolveCliProfileArguments(argv, options = {}) {
+    if (cliMetaActionForInvocation(argv))
+        return [...argv];
     // registry-scaffold owns --profile as the capability template to generate.
     // Do not reinterpret it as a global CLI-default profile.
     if (argv[0] === 'registry-scaffold') {

package/cli/discover.mjs

@@ -1,4 +1,5 @@
 import { Buffer } from 'node:buffer';
+import { decodeBoundedUtf8 } from "../lib/bounded-file.mjs";
 import { CliUsageError } from "./arguments.mjs";
 const DEFAULT_DISCOVERY_TLDS = Object.freeze(['com', 'net', 'org']);
 const MAX_DISCOVERY_TLD_TEXT_LENGTH = 1024;
@@ -16,7 +17,12 @@ async function readDiscoveryDictionaryBounded(stream, limit = MAX_DISCOVERY_DICT
             throw new CliUsageError(`Discovery dictionary input is limited to ${limit} bytes.`);
         chunks.push(buffer);
     }
-    return Buffer.concat(chunks).toString('utf8');
+    try {
+        return decodeBoundedUtf8(Buffer.concat(chunks), 'Discovery dictionary input');
+    }
+    catch (cause) {
+        throw new CliUsageError(cause instanceof Error ? cause.message : 'Discovery dictionary input must contain valid UTF-8 text.');
+    }
 }
 function normalizeDiscoveryTlds(raw, maximum) {
     if (!Number.isSafeInteger(maximum) || maximum < 1) {

package/cli/discovery-observation-snapshot.mjs

@@ -4,11 +4,12 @@ import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
 import { isValidAsciiDomainName } from "../lib/hostname.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 export const CLI_DISCOVERY_OBSERVATION_SCHEMA = 'whoisleuth.cli.discovery-observation-snapshot';
 export const CLI_DISCOVERY_OBSERVATION_VERSION = 2;
 export const MAX_DISCOVERY_OBSERVATION_BYTES = 8 * 1024 * 1024;
 const MAX_DISCOVERY_OBSERVATIONS = 500;
-const SUPPORTED_DISCOVERY_OBSERVATION_VERSIONS = new Set([1, CLI_DISCOVERY_OBSERVATION_VERSION]);
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -25,10 +26,10 @@ function normalizedTimestamp(value, label, optional = false) {
     if (typeof value !== 'string' || value.length > 64 || /[\u0000-\u001f\u007f]/u.test(value)) {
         throw new CliUsageError(`${label} is invalid.`);
     }
-    const parsed = Date.parse(value);
-    if (!Number.isFinite(parsed))
-        throw new CliUsageError(`${label} is invalid.`);
-    return new Date(parsed).toISOString();
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    if (normalized)
+        return normalized;
+    throw new CliUsageError(`${label} is invalid.`);
 }
 function latestObservedAt(registrationObservedAt, dnsObservedAt) {
     if (!registrationObservedAt)
@@ -64,32 +65,25 @@ function normalizeDns(value) {
         hasDmarc: nullableBoolean(dns.hasDmarc),
     };
 }
-function normalizeObservation(value, version) {
+function normalizeObservation(value) {
     const item = record(value);
     const dns = normalizeDns(item.dns);
     try {
-        const validAttemptStates = version === 1 ? ['error', 'success'] : ['error', 'partial', 'success'];
         if (!dns
-            || !validAttemptStates.includes(String(item.latestAttemptState))
+            || !['error', 'partial', 'success'].includes(String(item.latestAttemptState))
             || typeof item.availabilityState !== 'string' || !item.availabilityState || item.availabilityState.length > 40
             || /[\u0000-\u001f\u007f]/u.test(item.availabilityState)
             || typeof item.confidence !== 'string' || !item.confidence || item.confidence.length > 40
             || /[\u0000-\u001f\u007f]/u.test(item.confidence))
             return null;
-        const legacyObservedAt = normalizedTimestamp(item.observedAt, 'Discovery observation time', version >= 2);
-        const registrationObservedAt = version === 1
-            ? item.availabilityState === 'unknown' ? null : legacyObservedAt
-            : normalizedTimestamp(item.registrationObservedAt, 'Discovery registration observation time', true);
-        const dnsObservedAt = version === 1
-            ? ['partial', 'success'].includes(dns.status) ? legacyObservedAt : null
-            : normalizedTimestamp(item.dnsObservedAt, 'Discovery DNS observation time', true);
+        const declaredObservedAt = normalizedTimestamp(item.observedAt, 'Discovery observation time', true);
+        const registrationObservedAt = normalizedTimestamp(item.registrationObservedAt, 'Discovery registration observation time', true);
+        const dnsObservedAt = normalizedTimestamp(item.dnsObservedAt, 'Discovery DNS observation time', true);
         const observedAt = latestObservedAt(registrationObservedAt, dnsObservedAt);
-        if (version >= 2 && legacyObservedAt !== observedAt)
+        if (declaredObservedAt !== observedAt)
             return null;
-        const latestRegistrationState = version === 1
-            ? registrationObservedAt ? 'observed' : 'unavailable'
-            : item.latestRegistrationState;
-        const latestDnsState = version === 1 ? dns.status : item.latestDnsState;
+        const latestRegistrationState = item.latestRegistrationState;
+        const latestDnsState = item.latestDnsState;
         if (!['observed', 'unavailable'].includes(String(latestRegistrationState))
             || typeof latestDnsState !== 'string' || !latestDnsState || latestDnsState.length > 40
             || /[\u0000-\u001f\u007f]/u.test(latestDnsState))
@@ -118,28 +112,30 @@ function parseObservationSnapshot(text, expectedDigest) {
     if (Buffer.byteLength(text, 'utf8') > MAX_DISCOVERY_OBSERVATION_BYTES) {
         throw new CliUsageError(`Discovery observation snapshots are limited to ${MAX_DISCOVERY_OBSERVATION_BYTES} bytes.`);
     }
+    const normalizedInput = text.replace(/^\uFEFF/u, '');
     let parsed;
     try {
-        parsed = JSON.parse(text.replace(/^\uFEFF/u, ''));
+        scanBoundedJson(normalizedInput);
+        parsed = JSON.parse(normalizedInput);
     }
     catch {
-        throw new CliUsageError('Discovery observation snapshot must be valid JSON.');
+        throw new CliUsageError('Discovery observation snapshot must be valid bounded JSON without duplicate keys.');
     }
     const document = record(parsed);
     const version = typeof document.version === 'number' && Number.isSafeInteger(document.version)
         ? document.version
         : 0;
-    if (document.schema !== CLI_DISCOVERY_OBSERVATION_SCHEMA || !SUPPORTED_DISCOVERY_OBSERVATION_VERSIONS.has(version)) {
-        throw new CliUsageError(`Discovery observation snapshot must use ${CLI_DISCOVERY_OBSERVATION_SCHEMA} version 1 or ${CLI_DISCOVERY_OBSERVATION_VERSION}.`);
+    if (document.schema !== CLI_DISCOVERY_OBSERVATION_SCHEMA || version !== CLI_DISCOVERY_OBSERVATION_VERSION) {
+        throw new CliUsageError(`Discovery observation snapshot must use ${CLI_DISCOVERY_OBSERVATION_SCHEMA} version ${CLI_DISCOVERY_OBSERVATION_VERSION}.`);
     }
     if (document.configurationDigestSha256 !== expectedDigest) {
         throw new CliUsageError('Discovery observation snapshot does not match this candidate set, scan mode, or resolver selection.');
     }
-    if (typeof document.generatedAt !== 'string' || !Number.isFinite(Date.parse(document.generatedAt))
-        || !Array.isArray(document.observations) || document.observations.length > MAX_DISCOVERY_OBSERVATIONS) {
+    if (!Array.isArray(document.observations) || document.observations.length > MAX_DISCOVERY_OBSERVATIONS) {
         throw new CliUsageError('Discovery observation snapshot metadata is invalid.');
     }
-    const observations = document.observations.map((item) => normalizeObservation(item, version));
+    const generatedAt = normalizedTimestamp(document.generatedAt, 'Discovery snapshot generation time') ?? '';
+    const observations = document.observations.map((item) => normalizeObservation(item));
     if (observations.some((item) => item === null) || document.observationCount !== observations.length) {
         throw new CliUsageError('Discovery observation snapshot contains invalid evidence.');
     }
@@ -150,7 +146,7 @@ function parseObservationSnapshot(text, expectedDigest) {
     return {
         schema: CLI_DISCOVERY_OBSERVATION_SCHEMA,
         version: CLI_DISCOVERY_OBSERVATION_VERSION,
-        generatedAt: normalizedTimestamp(document.generatedAt, 'Discovery snapshot generation time') ?? '',
+        generatedAt,
         configurationDigestSha256: expectedDigest,
         observationCount: normalized.length,
         observations: normalized,

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

@@ -34,6 +34,15 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
     });
     context.setEventProgress(eventProgress);
     eventProgress.emit({ event: 'started' });
+    let resolverServers = [];
+    if (args.resolverText) {
+        try {
+            resolverServers = normalizeSelectedDnsResolvers(args.resolverText);
+        }
+        catch (error) {
+            throw new CliUsageError(boundedCliErrorMessage(error, 'Invalid DNS resolver selection'));
+        }
+    }
     const { metadata: generationMetadata, result } = await generateDiscoveryCandidates(args, dependencies, context);
     const candidates = result.candidates
         .filter((candidate) => typeof candidate.domain === 'string' && candidate.domain.length > 0)
@@ -51,15 +60,6 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
         return EXIT_CODES.SUCCESS;
     }
     const classify = dependencies.classifyQuery || classifyQuery;
-    let resolverServers = [];
-    if (args.resolverText) {
-        try {
-            resolverServers = normalizeSelectedDnsResolvers(args.resolverText);
-        }
-        catch (error) {
-            throw new CliUsageError(boundedCliErrorMessage(error, 'Invalid DNS resolver selection'));
-        }
-    }
     const allowlist = await readAllowlist(args.allowlistSource, dependencies, context, classify);
     const checkpointWriter = dependencies.createBulkCheckpointWriter || createBulkCheckpointWriter;
     const checkpoint = args.checkpoint

package/cli/discovery-scan.mjs

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto';
 import { Buffer } from 'node:buffer';
+import { decodeBoundedUtf8 } from "../lib/bounded-file.mjs";
 import { runBulkLookups } from "./bulk.mjs";
 import { REGISTERED_STATES, availabilityState, bulkDnsSummary } from "./bulk-output.mjs";
 import { cliCsvCell } from "./csv.mjs";
 import { CliUsageError } from "./errors.mjs";
+import { terminalSafeJson } from "./formatters/json.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;
@@ -30,7 +32,12 @@ async function readDiscoveryScanListBounded(stream, limit = MAX_DISCOVERY_SCAN_A
             throw new CliUsageError(`Discovery scan allowlists are limited to ${limit} bytes.`);
         chunks.push(buffer);
     }
-    return Buffer.concat(chunks).toString('utf8');
+    try {
+        return decodeBoundedUtf8(Buffer.concat(chunks), 'Discovery scan allowlist');
+    }
+    catch (cause) {
+        throw new CliUsageError(cause instanceof Error ? cause.message : 'Discovery scan allowlist must contain valid UTF-8 text.');
+    }
 }
 function parseDiscoveryScanAllowlist(text, classifyQuery) {
     if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > MAX_DISCOVERY_SCAN_ALLOWLIST_BYTES) {
@@ -232,7 +239,10 @@ function buildDiscoveryScanDocument(candidates, items, metadata, allowlist, snap
         collection: {
             chunkSize: metadata.chunkSize,
             concurrency: metadata.concurrency,
-            resolver: metadata.resolverServers.length ? 'analyst_selected' : 'system_default',
+            resolver: metadata.resolverServers.length ? 'mixed' : 'system_default',
+            dnsResolver: metadata.resolverServers.length ? 'analyst_selected' : 'system_default',
+            registryEndpointResolution: 'system_default',
+            serviceAddressResolution: 'system_default',
             resolverServers: [...metadata.resolverServers],
         },
         filter: metadata.filter,
@@ -258,6 +268,9 @@ function buildDiscoveryScanDocument(candidates, items, metadata, allowlist, snap
             '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.',
+            ...(metadata.resolverServers.length
+                ? ['The analyst-selected resolver applies to DNS record and delegation evidence only. Registry, WHOIS, HTTP, redirect, favicon, and TLS endpoint address resolution remains system-default and is reported separately.']
+                : []),
         ],
     };
 }
@@ -286,7 +299,7 @@ async function runDiscoveryScanChunks(queries, options) {
 }
 function formatDiscoveryScanJsonLines(document) {
     return document.results.length
-        ? `${document.results.map((item) => JSON.stringify({ ...item, generatedAt: document.generatedAt })).join('\n')}\n`
+        ? `${document.results.map((item) => terminalSafeJson({ ...item, generatedAt: document.generatedAt })).join('\n')}\n`
         : '';
 }
 function formatDiscoveryScanCsv(document) {
@@ -311,6 +324,7 @@ function formatTerminalDiscoveryScan(document) {
         `Matched          ${document.summary.matched}`,
         `Source failures  ${document.summary.failed}`,
         `Relationships    ${document.relationships.length}`,
+        `Resolution       ${document.collection.resolver === 'mixed' ? 'mixed (selected DNS; system service addresses)' : 'system default'}`,
         '',
         'Review queue',
     ];

package/cli/discovery-snapshot.mjs

@@ -3,6 +3,8 @@ import { boundedCliInputError, CliUsageError } from "./errors.mjs";
 import { writePrivateFile } from "./output-file.mjs";
 import { isValidAsciiDomainName } from "../lib/hostname.mjs";
 import { readBoundedRegularTextFile } from "../lib/bounded-file.mjs";
+import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.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;
@@ -30,16 +32,24 @@ function normalizedDomains(value) {
     }
     return [...output].sort();
 }
+function normalizedTimestamp(value) {
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    if (!normalized)
+        throw new CliUsageError('Discovery snapshot collection time is invalid.');
+    return normalized;
+}
 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.`);
     }
+    const normalized = text.replace(/^\uFEFF/u, '');
     let parsed;
     try {
-        parsed = JSON.parse(text.replace(/^\uFEFF/u, ''));
+        scanBoundedJson(normalized);
+        parsed = JSON.parse(normalized);
     }
     catch {
-        throw new CliUsageError('Discovery snapshot must be valid JSON.');
+        throw new CliUsageError('Discovery snapshot must be valid bounded JSON without duplicate keys.');
     }
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new CliUsageError('Discovery snapshot must be one JSON object.');
@@ -51,16 +61,14 @@ function parseDiscoverySnapshot(text, expectedConfigurationDigest) {
     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 generatedAt = normalizedTimestamp(value.generatedAt);
     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(),
+        generatedAt,
         configurationDigestSha256: expectedConfigurationDigest,
         candidateCount: candidates.length,
         candidates,
@@ -95,7 +103,7 @@ async function updateDiscoverySnapshot(path, candidatesValue, configuration, gen
     const document = {
         schema: CLI_DISCOVERY_SNAPSHOT_SCHEMA,
         version: CLI_DISCOVERY_SNAPSHOT_VERSION,
-        generatedAt: new Date(generatedAt).toISOString(),
+        generatedAt: normalizedTimestamp(generatedAt),
         configurationDigestSha256: digest,
         candidateCount: candidates.length,
         candidates,