@slicedearth/whoisleuth-cli 1.47.4 → 2.0.0

package/cli/domain-control-monitor.mjs

@@ -1,17 +1,28 @@
 import { classifyQuery } from "../lib/classify.mjs";
 import { scanBoundedJson } from "../lib/bounded-json.mjs";
-import { buildDomainControlFlightRecorder, } from "../lib/domain-control-flight-recorder.mjs";
-import { verifyDomainControlManifest } from "../lib/domain-control-manifest.mjs";
+import { buildDomainControlFlightRecorder, validateDomainControlFlightRecorderDocument, } from "../lib/domain-control-flight-recorder.mjs";
+import { DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA, DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION, } from "../packages/contracts/domain-control-flight-recorder.mjs";
+import { DOMAIN_CONTROL_REVIEW_SCHEMA, DOMAIN_CONTROL_REVIEW_VERSION, CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_VERSION, } from "../packages/contracts/domain-control-review.mjs";
+import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, CLI_DOMAIN_CONTROL_MONITOR_VERSION, DOMAIN_CONTROL_MONITOR_COLLECTION_KEYS, DOMAIN_CONTROL_MONITOR_FAILURE_CATEGORIES, DOMAIN_CONTROL_MONITOR_FAILURE_KEYS, DOMAIN_CONTROL_MONITOR_LIMITATIONS, DOMAIN_CONTROL_MONITOR_MANIFEST_KEYS, DOMAIN_CONTROL_MONITOR_ROOT_KEYS, MAX_DOMAIN_CONTROL_MONITOR_CONCURRENCY, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS as CONTRACT_MAX_DOMAIN_CONTROL_MONITOR_DOMAINS, MAX_DOMAIN_CONTROL_MONITOR_ERROR_LENGTH, MAX_DOMAIN_CONTROL_MONITOR_FAILURES, MAX_DOMAIN_CONTROL_MONITOR_INPUT_BYTES, MAX_DOMAIN_CONTROL_MONITOR_JSON_CONTAINER_ITEMS, MAX_DOMAIN_CONTROL_MONITOR_JSON_DEPTH, MAX_DOMAIN_CONTROL_MONITOR_JSON_KEYS, MAX_DOMAIN_CONTROL_MONITOR_JSON_VALUES, MIN_DOMAIN_CONTROL_MONITOR_CONCURRENCY, MIN_DOMAIN_CONTROL_MONITOR_DOMAINS, } from "../packages/contracts/domain-control-monitor.mjs";
+import { validateDomainControlReviewDocument, verifyDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
+import { requireDomainName, requireIsoTimestamp } from "../lib/bounded-contract-normalizers.mjs";
 import { buildCliLookupDocument } from "./formatters/json.mjs";
 import { buildCliDomainControlReview, } from "./domain-control-observations.mjs";
-import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
-export const CLI_DOMAIN_CONTROL_MONITOR_SCHEMA = 'whoisleuth.cli.domain-control-monitor';
-export const CLI_DOMAIN_CONTROL_MONITOR_VERSION = 1;
-export const MAX_DOMAIN_CONTROL_MONITOR_DOMAINS = 20;
+import { CliUsageError } from "./errors.mjs";
+export { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, CLI_DOMAIN_CONTROL_MONITOR_VERSION };
+export const MAX_DOMAIN_CONTROL_MONITOR_DOMAINS = CONTRACT_MAX_DOMAIN_CONTROL_MONITOR_DOMAINS;
 function parseMonitorJson(input, label) {
     const normalized = input.replace(/^\uFEFF/u, '');
+    if (Buffer.byteLength(input, 'utf8') > MAX_DOMAIN_CONTROL_MONITOR_INPUT_BYTES) {
+        throw new CliUsageError(`${label} exceeds the ${MAX_DOMAIN_CONTROL_MONITOR_INPUT_BYTES}-byte limit.`);
+    }
     try {
-        scanBoundedJson(normalized);
+        scanBoundedJson(normalized, {
+            maximumDepth: MAX_DOMAIN_CONTROL_MONITOR_JSON_DEPTH,
+            maximumKeys: MAX_DOMAIN_CONTROL_MONITOR_JSON_KEYS,
+            maximumValues: MAX_DOMAIN_CONTROL_MONITOR_JSON_VALUES,
+            maximumContainerItems: MAX_DOMAIN_CONTROL_MONITOR_JSON_CONTAINER_ITEMS,
+        });
         return JSON.parse(normalized);
     }
     catch (cause) {
@@ -25,32 +36,187 @@ function parseMonitorJson(input, label) {
         throw new CliUsageError(`${label} must satisfy the bounded JSON structure contract.`);
     }
 }
-function previousSnapshot(input) {
-    if (!input)
+function exactMonitorRecord(value, keys, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new CliUsageError(`${label} must use its exact object fields.`);
+    }
+    const record = value;
+    const actualKeys = Object.keys(record);
+    if (actualKeys.length !== keys.length || actualKeys.some((key) => !keys.includes(key))) {
+        throw new CliUsageError(`${label} must use its exact object fields.`);
+    }
+    return record;
+}
+function monitorInteger(value, minimum, maximum, label) {
+    if (!Number.isSafeInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+        throw new CliUsageError(`${label} must be an integer from ${minimum} to ${maximum}.`);
+    }
+    return Number(value);
+}
+function previousSnapshot(input, currentGeneratedAt) {
+    if (input === null)
         return { observations: [] };
     const parsed = parseMonitorJson(input, 'Previous monitor snapshot');
-    const root = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-    if (root.schema !== CLI_DOMAIN_CONTROL_MONITOR_SCHEMA || root.version !== CLI_DOMAIN_CONTROL_MONITOR_VERSION || !Array.isArray(root.observations)) {
+    const root = exactMonitorRecord(parsed, DOMAIN_CONTROL_MONITOR_ROOT_KEYS, 'Previous monitor snapshot');
+    if (root.schema !== CLI_DOMAIN_CONTROL_MONITOR_SCHEMA || root.version !== CLI_DOMAIN_CONTROL_MONITOR_VERSION) {
         throw new CliUsageError(`Previous monitor snapshot must use ${CLI_DOMAIN_CONTROL_MONITOR_SCHEMA} version ${CLI_DOMAIN_CONTROL_MONITOR_VERSION}.`);
     }
-    const validated = buildDomainControlFlightRecorder({
-        schema: 'whoisleuth.domain-control-flight-recorder.input', version: 1, observations: root.observations, approvedWindows: [],
-    });
-    void validated;
-    return { observations: root.observations };
+    let previousGeneratedAt;
+    try {
+        previousGeneratedAt = requireIsoTimestamp(root.generatedAt, 'Previous monitor snapshot generatedAt');
+    }
+    catch {
+        throw new CliUsageError('Previous monitor snapshot generatedAt must be a valid ISO 8601 timestamp.');
+    }
+    if (Date.parse(previousGeneratedAt) >= Date.parse(currentGeneratedAt)) {
+        throw new CliUsageError('Previous monitor snapshot must precede the current monitor run.');
+    }
+    const manifest = exactMonitorRecord(root.manifest, DOMAIN_CONTROL_MONITOR_MANIFEST_KEYS, 'Previous monitor snapshot manifest');
+    if (typeof manifest.digestSha256 !== 'string'
+        || !/^sha256:[a-f0-9]{64}$/u.test(manifest.digestSha256)
+        || typeof manifest.expiresAt !== 'string') {
+        throw new CliUsageError('Previous monitor snapshot manifest is invalid.');
+    }
+    try {
+        requireIsoTimestamp(manifest.expiresAt, 'Previous monitor snapshot manifest expiresAt');
+    }
+    catch {
+        throw new CliUsageError('Previous monitor snapshot manifest expiresAt must be a valid ISO 8601 timestamp.');
+    }
+    if (Date.parse(manifest.expiresAt) <= Date.parse(previousGeneratedAt)) {
+        throw new CliUsageError('Previous monitor snapshot manifest must have been unexpired when the checkpoint was generated.');
+    }
+    const collection = exactMonitorRecord(root.collection, DOMAIN_CONTROL_MONITOR_COLLECTION_KEYS, 'Previous monitor snapshot collection');
+    const requested = monitorInteger(collection.requested, MIN_DOMAIN_CONTROL_MONITOR_DOMAINS, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS, 'Previous monitor snapshot requested count');
+    const succeeded = monitorInteger(collection.succeeded, MIN_DOMAIN_CONTROL_MONITOR_DOMAINS, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS, 'Previous monitor snapshot succeeded count');
+    const failed = monitorInteger(collection.failed, 0, MAX_DOMAIN_CONTROL_MONITOR_FAILURES, 'Previous monitor snapshot failed count');
+    if (requested !== succeeded + failed || !Array.isArray(collection.failures) || collection.failures.length !== failed) {
+        throw new CliUsageError('Previous monitor snapshot collection counts are inconsistent.');
+    }
+    const failureDomains = new Set();
+    const failureDomainOrder = [];
+    for (const [index, failureValue] of collection.failures.entries()) {
+        const failure = exactMonitorRecord(failureValue, DOMAIN_CONTROL_MONITOR_FAILURE_KEYS, `Previous monitor snapshot failure ${index + 1}`);
+        let failureDomain;
+        try {
+            failureDomain = requireDomainName(failure.domain, `Previous monitor snapshot failure ${index + 1} domain`);
+        }
+        catch {
+            throw new CliUsageError(`Previous monitor snapshot failure ${index + 1} domain is invalid.`);
+        }
+        if (failureDomain !== failure.domain
+            || failureDomains.has(failureDomain)
+            || typeof failure.error !== 'string'
+            || !DOMAIN_CONTROL_MONITOR_FAILURE_CATEGORIES.includes(failure.error)
+            || failure.error.length > MAX_DOMAIN_CONTROL_MONITOR_ERROR_LENGTH) {
+            throw new CliUsageError(`Previous monitor snapshot failure ${index + 1} is invalid.`);
+        }
+        failureDomains.add(failureDomain);
+        failureDomainOrder.push(failureDomain);
+    }
+    if (!Array.isArray(root.observations)
+        || root.observations.length !== succeeded
+        || root.observations.length < MIN_DOMAIN_CONTROL_MONITOR_DOMAINS
+        || root.observations.length > MAX_DOMAIN_CONTROL_MONITOR_DOMAINS) {
+        throw new CliUsageError('Previous monitor snapshot observations are inconsistent with its collection summary.');
+    }
+    let review;
+    let flightRecorder;
+    try {
+        review = validateDomainControlReviewDocument(root.review);
+    }
+    catch {
+        throw new CliUsageError(`Previous monitor snapshot review must use the exact ${DOMAIN_CONTROL_REVIEW_SCHEMA} version ${DOMAIN_CONTROL_REVIEW_VERSION} contract.`);
+    }
+    try {
+        flightRecorder = validateDomainControlFlightRecorderDocument(root.flightRecorder);
+    }
+    catch {
+        throw new CliUsageError(`Previous monitor snapshot flight recorder must use the exact ${DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA} version ${DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION} contract.`);
+    }
+    if (!Array.isArray(root.limitations)
+        || root.limitations.length !== DOMAIN_CONTROL_MONITOR_LIMITATIONS.length
+        || root.limitations.some((value, index) => value !== DOMAIN_CONTROL_MONITOR_LIMITATIONS[index])) {
+        throw new CliUsageError('Previous monitor snapshot limitations are invalid.');
+    }
+    try {
+        buildDomainControlFlightRecorder({
+            schema: DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA,
+            version: DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION,
+            observations: root.observations,
+            approvedWindows: [],
+        }, previousGeneratedAt);
+    }
+    catch {
+        throw new CliUsageError('Previous monitor snapshot observations must use the exact bounded flight-recorder input contract.');
+    }
+    const observations = root.observations;
+    const observationDomainOrder = observations.map((observation) => observation.domain);
+    const observationDomains = new Set(observationDomainOrder);
+    const requestedDomains = review.domains.slice(0, requested).map((item) => item.domain);
+    const expectedObservationDomains = requestedDomains.filter((domain) => !failureDomains.has(domain));
+    const expectedFailureDomains = requestedDomains.filter((domain) => !observationDomains.has(domain));
+    if (review.domains.length < requested
+        || observationDomains.size !== observations.length
+        || observationDomainOrder.some((domain, index) => domain !== expectedObservationDomains[index])
+        || observationDomainOrder.length !== expectedObservationDomains.length
+        || failureDomainOrder.some((domain, index) => domain !== expectedFailureDomains[index])
+        || failureDomainOrder.length !== expectedFailureDomains.length
+        || observations.some((observation) => observation.observedAt !== previousGeneratedAt)
+        || review.domains.some((item) => item.comparisons.some((comparison) => comparison.observedAt !== null && comparison.observedAt !== previousGeneratedAt))
+        || review.generatedAt !== previousGeneratedAt
+        || review.manifest.digestSha256 !== manifest.digestSha256
+        || review.manifest.expiresAt !== manifest.expiresAt
+        || [...observationDomains].some((domain) => !review.domains.some((item) => item.domain === domain))
+        || flightRecorder.generatedAt !== previousGeneratedAt
+        || flightRecorder.observationCount < observations.length
+        || [...observationDomains].some((domain) => !flightRecorder.domains.includes(domain))) {
+        throw new CliUsageError('Previous monitor snapshot embedded documents are inconsistent with its observation projection.');
+    }
+    return { observations };
+}
+function monitorFailureMessage() {
+    return DOMAIN_CONTROL_MONITOR_FAILURE_CATEGORIES[0];
 }
 export async function runDomainControlMonitor(manifestInput, previousInput, options) {
-    const generatedAt = options.now();
+    if (!Number.isSafeInteger(options.limit)
+        || options.limit < MIN_DOMAIN_CONTROL_MONITOR_DOMAINS
+        || options.limit > MAX_DOMAIN_CONTROL_MONITOR_DOMAINS) {
+        throw new CliUsageError(`Domain-control monitor limit must be from ${MIN_DOMAIN_CONTROL_MONITOR_DOMAINS} to ${MAX_DOMAIN_CONTROL_MONITOR_DOMAINS}.`);
+    }
+    if (!Number.isSafeInteger(options.concurrency)
+        || options.concurrency < MIN_DOMAIN_CONTROL_MONITOR_CONCURRENCY
+        || options.concurrency > MAX_DOMAIN_CONTROL_MONITOR_CONCURRENCY) {
+        throw new CliUsageError(`Domain-control monitor concurrency must be from ${MIN_DOMAIN_CONTROL_MONITOR_CONCURRENCY} to ${MAX_DOMAIN_CONTROL_MONITOR_CONCURRENCY}.`);
+    }
+    let generatedAt;
+    try {
+        generatedAt = requireIsoTimestamp(options.now(), 'Domain-control monitor time');
+    }
+    catch {
+        throw new CliUsageError('Domain-control monitor time must be a valid ISO 8601 timestamp.');
+    }
     const rawManifest = parseMonitorJson(manifestInput, 'Domain-control manifest');
-    const manifest = verifyDomainControlManifest(rawManifest);
-    const previous = previousSnapshot(previousInput);
+    let manifest;
+    try {
+        manifest = verifyDomainControlManifest(rawManifest);
+    }
+    catch {
+        throw new CliUsageError('Domain-control manifest must satisfy its supported bounded integrity contract.');
+    }
+    const checkedAt = Date.parse(generatedAt);
+    if (Date.parse(manifest.expiresAt) <= checkedAt) {
+        throw new CliUsageError('Domain-control monitor requires an unexpired manifest.');
+    }
+    const previous = previousSnapshot(previousInput, generatedAt);
     const entries = manifest.entries.slice(0, Math.min(options.limit, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS));
     const lookups = new Array(entries.length);
-    const failures = [];
+    const failuresByIndex = new Array(entries.length);
     let cursor = 0;
     let completed = 0;
     const worker = async () => {
         while (cursor < entries.length) {
+            options.signal?.throwIfAborted();
             const index = cursor++;
             const entry = entries[index];
             if (!entry)
@@ -58,10 +224,14 @@ export async function runDomainControlMonitor(manifestInput, previousInput, opti
             try {
                 const classified = classifyQuery(entry.domain);
                 const result = await options.executeLookup(classified, { fast: false, compact: false, ...(options.signal ? { signal: options.signal } : {}) });
+                options.signal?.throwIfAborted();
                 lookups[index] = buildCliLookupDocument(entry.domain, classified, result, generatedAt, 'deep');
             }
-            catch (cause) {
-                failures.push({ domain: entry.domain, error: boundedCliErrorMessage(cause, 'Lookup failed') });
+            catch {
+                if (options.signal?.aborted) {
+                    throw options.signal.reason || new DOMException('Aborted', 'AbortError');
+                }
+                failuresByIndex[index] = Object.freeze({ domain: entry.domain, error: monitorFailureMessage() });
             }
             finally {
                 completed += 1;
@@ -70,16 +240,23 @@ export async function runDomainControlMonitor(manifestInput, previousInput, opti
         }
     };
     await Promise.all(Array.from({ length: Math.min(options.concurrency, Math.max(entries.length, 1)) }, worker));
+    options.signal?.throwIfAborted();
+    const failures = failuresByIndex.filter((failure) => Boolean(failure));
     const successful = lookups.filter(Boolean);
     if (!successful.length)
         throw new Error('No domain-control monitor lookup completed successfully.');
     const review = buildCliDomainControlReview(JSON.stringify({
-        schema: 'whoisleuth.cli.domain-control-review-input', version: 1, manifest, lookups: successful,
+        schema: CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA,
+        version: CLI_DOMAIN_CONTROL_REVIEW_VERSION,
+        manifest,
+        lookups: successful,
     }), generatedAt);
     const observations = review.observations;
     const flightRecorder = buildDomainControlFlightRecorder({
-        schema: 'whoisleuth.domain-control-flight-recorder.input', version: 1,
-        observations: [...previous.observations, ...observations], approvedWindows: [],
+        schema: DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA,
+        version: DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION,
+        observations: [...previous.observations, ...observations],
+        approvedWindows: [],
     }, generatedAt);
     return Object.freeze({
         schema: CLI_DOMAIN_CONTROL_MONITOR_SCHEMA,
@@ -90,11 +267,7 @@ export async function runDomainControlMonitor(manifestInput, previousInput, opti
         observations,
         review: review.review,
         flightRecorder,
-        limitations: Object.freeze([
-            'This is one bounded run, not a daemon. Scheduling and secure checkpoint retention remain operator-controlled.',
-            'The output retains compact normalised observations and errors, not raw RDAP, WHOIS, DNS, HTTP, TLS or page payloads.',
-            'A failed source or lookup remains incomplete and does not establish that a previously observed value disappeared.',
-        ]),
+        limitations: DOMAIN_CONTROL_MONITOR_LIMITATIONS,
     });
 }
 export function formatDomainControlMonitor(document) {

package/cli/domain-control-observations.mjs

@@ -1,17 +1,12 @@
 import { Buffer } from 'node:buffer';
-import { MAX_BOUNDED_JSON_DEPTH, MAX_BOUNDED_JSON_KEYS, MAX_BOUNDED_JSON_VALUES, scanBoundedJson, } from "../lib/bounded-json.mjs";
+import { scanBoundedJson, } from "../lib/bounded-json.mjs";
+import { CLI_DOMAIN_CONTROL_REVIEW_INPUT_KEYS, CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_LIMITATIONS, CLI_DOMAIN_CONTROL_REVIEW_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_VERSION, DOMAIN_CONTROL_REVIEW_VERSION, MAX_DOMAIN_CONTROL_REVIEW_INPUT_BYTES, MAX_DOMAIN_CONTROL_REVIEW_JSON_DEPTH, MAX_DOMAIN_CONTROL_REVIEW_JSON_KEYS, MAX_DOMAIN_CONTROL_REVIEW_JSON_VALUES, MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS, MIN_DOMAIN_CONTROL_REVIEW_LOOKUPS, } from "../packages/contracts/domain-control-review.mjs";
 import { DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS, } from "../lib/domain-control-flight-recorder.mjs";
 import { DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, reviewDomainControlManifest, verifyDomainControlManifest, } from "../lib/domain-control-manifest.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
-export const CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA = 'whoisleuth.cli.domain-control-review-input';
-export const CLI_DOMAIN_CONTROL_REVIEW_SCHEMA = 'whoisleuth.cli.domain-control-review';
-export const CLI_DOMAIN_CONTROL_REVIEW_VERSION = 1;
-export const MAX_DOMAIN_CONTROL_REVIEW_INPUT_BYTES = 32 * 1024 * 1024;
-export const MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS = 100;
-export const MAX_DOMAIN_CONTROL_REVIEW_JSON_DEPTH = MAX_BOUNDED_JSON_DEPTH + 2;
-export const MAX_DOMAIN_CONTROL_REVIEW_JSON_KEYS = MAX_BOUNDED_JSON_KEYS * (MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS + 1);
-export const MAX_DOMAIN_CONTROL_REVIEW_JSON_VALUES = MAX_BOUNDED_JSON_VALUES * (MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS + 1);
+export { CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_SCHEMA, CLI_DOMAIN_CONTROL_REVIEW_VERSION, MAX_DOMAIN_CONTROL_REVIEW_INPUT_BYTES, MAX_DOMAIN_CONTROL_REVIEW_JSON_DEPTH, MAX_DOMAIN_CONTROL_REVIEW_JSON_KEYS, MAX_DOMAIN_CONTROL_REVIEW_JSON_VALUES, MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS, };
+const CLI_REVIEW_INPUT_KEY_SET = new Set(CLI_DOMAIN_CONTROL_REVIEW_INPUT_KEYS);
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -165,14 +160,17 @@ export function buildCliDomainControlReview(inputText, generatedAt = new Date().
         throw new CliUsageError('Domain-control review input must be valid JSON.');
     }
     const input = record(parsed);
-    if (input.schema !== CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA || input.version !== 1 || !Array.isArray(input.lookups)) {
-        throw new CliUsageError(`Domain-control review input must use ${CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA} version 1.`);
+    if (input.schema !== CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA
+        || input.version !== CLI_DOMAIN_CONTROL_REVIEW_VERSION
+        || !Array.isArray(input.lookups)) {
+        throw new CliUsageError(`Domain-control review input must use ${CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA} version ${CLI_DOMAIN_CONTROL_REVIEW_VERSION}.`);
     }
-    if (Object.keys(input).some((key) => !new Set(['schema', 'version', 'manifest', 'lookups']).has(key))) {
+    if (Object.keys(input).some((key) => !CLI_REVIEW_INPUT_KEY_SET.has(key))) {
         throw new CliUsageError('Domain-control review input contains an unsupported field.');
     }
-    if (input.lookups.length < 1 || input.lookups.length > MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS) {
-        throw new CliUsageError('Domain-control review requires from 1 to 100 saved Lookup documents.');
+    if (input.lookups.length < MIN_DOMAIN_CONTROL_REVIEW_LOOKUPS
+        || input.lookups.length > MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS) {
+        throw new CliUsageError(`Domain-control review requires from ${MIN_DOMAIN_CONTROL_REVIEW_LOOKUPS} to ${MAX_DOMAIN_CONTROL_REVIEW_LOOKUPS} saved Lookup documents.`);
     }
     const manifest = verifyDomainControlManifest(input.manifest);
     const lookups = input.lookups.map((item, index) => parseSavedLookupDocument(JSON.stringify(item), { label: `Lookup ${index + 1}` }));
@@ -185,7 +183,7 @@ export function buildCliDomainControlReview(inputText, generatedAt = new Date().
     const observations = [...latest.values()].map(domainControlObservationFromSavedLookup);
     const review = reviewDomainControlManifest({
         schema: DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA,
-        version: 1,
+        version: DOMAIN_CONTROL_REVIEW_VERSION,
         manifest,
         observations: observations.map((item) => ({
             domain: item.domain,
@@ -225,17 +223,13 @@ export function buildCliDomainControlReview(inputText, generatedAt = new Date().
             latestDomainObservations: observations.length,
             ignoredHistoricalLookups: lookups.length - observations.length,
         }),
-        limitations: Object.freeze([
-            'The review uses only supplied saved Lookup documents and performs no request.',
-            'The newest supplied observation per domain is used for desired-state comparison; all supplied observations remain available to a separate flight-recorder review.',
-            'Raw RDAP, WHOIS, HTTP, TLS, and page payloads are not copied into this output.',
-        ]),
+        limitations: CLI_DOMAIN_CONTROL_REVIEW_LIMITATIONS,
     });
 }
 export function buildControlReviewInput(manifest, lookupDocuments) {
     return Object.freeze({
         schema: CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA,
-        version: 1,
+        version: CLI_DOMAIN_CONTROL_REVIEW_VERSION,
         manifest,
         lookups: Object.freeze(lookupDocuments),
     });

package/cli/errors.mjs

@@ -1,4 +1,6 @@
 const MAX_CLI_ERROR_MESSAGE_LENGTH = 300;
+const CLI_DEFAULT_IGNORABLE_RE = /\p{Default_Ignorable_Code_Point}/u;
+const CLI_DEFAULT_IGNORABLE_GLOBAL_RE = /\p{Default_Ignorable_Code_Point}/gu;
 class CliUsageError extends Error {
     constructor(message) {
         super(message);
@@ -12,16 +14,19 @@ function errorMessage(error) {
 }
 function boundedCliErrorMessage(error, fallback = 'Unexpected command failure') {
     return String(errorMessage(error) || error || fallback)
-        .replace(/[\x00-\x1f\x7f]+/g, ' ')
-        .replace(/[\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g, '')
+        .replace(/[\x00-\x1f\x7f-\x9f]+/g, ' ')
+        .replace(CLI_DEFAULT_IGNORABLE_GLOBAL_RE, '')
         .replace(/\s+/g, ' ')
         .trim()
         .slice(0, MAX_CLI_ERROR_MESSAGE_LENGTH) || fallback;
 }
+function hasUnsafeCliText(value) {
+    return /[\x00-\x1f\x7f-\x9f]/u.test(value) || CLI_DEFAULT_IGNORABLE_RE.test(value);
+}
 function boundedCliInputError(error, label) {
     if (error instanceof CliUsageError)
         return error;
     const safeLabel = label.replace(/[^A-Za-z0-9 ()_-]+/gu, '').trim().slice(0, 80) || 'Input';
     return new CliUsageError(`${safeLabel} could not be read as a bounded regular file.`);
 }
-export { CliUsageError, MAX_CLI_ERROR_MESSAGE_LENGTH, boundedCliErrorMessage, boundedCliInputError, };
+export { CliUsageError, MAX_CLI_ERROR_MESSAGE_LENGTH, boundedCliErrorMessage, boundedCliInputError, hasUnsafeCliText, };

package/cli/evidence-signing.mjs

@@ -1,11 +1,11 @@
 import { Buffer } from 'node:buffer';
 import { createHash, createPrivateKey, createPublicKey, sign, verify, } from 'node:crypto';
-import { canonicalArtifactJsonFor, resolveArtifactCanonicalization, SORTED_JSON_V1, SORTED_JSON_V2, } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { canonicalArtifactJsonFor, SORTED_JSON_V2, } from "../packages/evidence/artifact-integrity.mjs";
 import { hasVerifiedApplicableIntegrity, hasVerifiedArtifactStructure, MAX_OFFLINE_ARTIFACT_BYTES, verifyOfflineArtifact, } from "./artifact-verify.mjs";
 import { parseBoundedJsonObject } from "./bounded-json.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 export const SIGNED_EVIDENCE_PACKAGE_SCHEMA = 'whoisleuth.signed-evidence-package';
 export const SIGNED_EVIDENCE_PACKAGE_VERSION = 2;
-export const LEGACY_SIGNED_EVIDENCE_PACKAGE_VERSION = 1;
 export const EVIDENCE_SIGNATURE_VERIFICATION_SCHEMA = 'whoisleuth.evidence-signature-verification';
 export const EVIDENCE_SIGNATURE_VERIFICATION_VERSION = 2;
 export const EVIDENCE_SIGNATURE_ALGORITHM = 'Ed25519';
@@ -34,13 +34,10 @@ function hasExactKeys(value, expected) {
     return keys.length === expected.size && keys.every((key) => expected.has(key));
 }
 function timestamp(value) {
-    if (typeof value !== 'string' || value.length > 64) {
-        throw new TypeError('Signature time must be a valid timestamp.');
-    }
-    const parsed = Date.parse(value);
-    if (!Number.isFinite(parsed))
-        throw new TypeError('Signature time must be a valid timestamp.');
-    return new Date(parsed).toISOString();
+    const normalized = normalizeExplicitIsoTimestamp(value);
+    if (!normalized)
+        throw new TypeError('Signature time must be a valid timestamp with an explicit timezone.');
+    return normalized;
 }
 function canonicalTimestamp(value) {
     const normalized = timestamp(value);
@@ -131,7 +128,7 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
     const artifact = record(value.artifact);
     if (!hasExactKeys(value, PACKAGE_KEYS)
         || value.schema !== SIGNED_EVIDENCE_PACKAGE_SCHEMA
-        || (value.version !== LEGACY_SIGNED_EVIDENCE_PACKAGE_VERSION && value.version !== SIGNED_EVIDENCE_PACKAGE_VERSION)
+        || value.version !== SIGNED_EVIDENCE_PACKAGE_VERSION
         || !artifact
         || !signature
         || !hasExactKeys(signature, SIGNATURE_KEYS)
@@ -146,14 +143,7 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
         || !SHA256_RE.test(signature.keyIdSha256)) {
         throw new TypeError('Signed evidence package has an unsupported or malformed envelope.');
     }
-    let canonicalization;
-    try {
-        canonicalization = resolveArtifactCanonicalization(value.version, signature.canonicalization, [
-            { version: LEGACY_SIGNED_EVIDENCE_PACKAGE_VERSION, canonicalization: SORTED_JSON_V1, explicit: true },
-            { version: SIGNED_EVIDENCE_PACKAGE_VERSION, canonicalization: SORTED_JSON_V2, explicit: true },
-        ], 'Signed evidence package');
-    }
-    catch {
+    if (signature.canonicalization !== EVIDENCE_SIGNATURE_CANONICALIZATION) {
         throw new TypeError('Signed evidence package has an unsupported or malformed envelope.');
     }
     const signedAt = canonicalTimestamp(value.signedAt);
@@ -164,13 +154,13 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
     const embeddedPublicKey = importPublicKey(publicDer, 'Embedded evidence-signing public key');
     const payload = {
         schema: SIGNED_EVIDENCE_PACKAGE_SCHEMA,
-        version: value.version,
+        version: SIGNED_EVIDENCE_PACKAGE_VERSION,
         signedAt,
         artifact,
     };
     const signatureBytes = Buffer.from(signature.valueBase64, 'base64');
     if (signatureBytes.length !== 64
-        || !verify(null, payloadBytes(payload, canonicalization), embeddedPublicKey, signatureBytes)) {
+        || !verify(null, payloadBytes(payload, EVIDENCE_SIGNATURE_CANONICALIZATION), embeddedPublicKey, signatureBytes)) {
         throw new TypeError('Signed evidence package failed Ed25519 verification.');
     }
     let artifactVerification = null;

package/cli/external-observation-mapping.mjs

@@ -1,6 +1,6 @@
 import { domainToASCII } from 'node:url';
 import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
-import { EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, parseExternalFindingsDocument, } from "../frontend/src/lib/analysis/external-findings-import.js";
+import { EXTERNAL_FINDINGS_SCHEMA, EXTERNAL_FINDINGS_VERSION, EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, parseExternalFindingsDocument, } from "../packages/interchange/external-findings-import.mjs";
 export const EXTERNAL_OBSERVATION_MAPPING_SCHEMA = 'whoisleuth.external-observation-mapping';
 export const EXTERNAL_OBSERVATION_MAPPING_VERSION = 1;
 export const MAX_EXTERNAL_OBSERVATION_MAPPING_BYTES = 4 * 1024 * 1024;
@@ -135,8 +135,8 @@ export function mapExternalObservations(inputRaw) {
     }
     const truncated = selected.length < seen.size;
     const document = {
-        schema: 'whoisleuth.external-findings',
-        schemaVersion: 3,
+        schema: EXTERNAL_FINDINGS_SCHEMA,
+        schemaVersion: EXTERNAL_FINDINGS_VERSION,
         source,
         findings: selected.map((finding) => ({
             ...finding,

package/cli/formatters/json.mjs

@@ -1,5 +1,6 @@
 import { bulkDnsSummary } from "../bulk-output.mjs";
-const CLI_LOOKUP_SCHEMA = 'whoisleuth.cli.lookup';
+import { SAVED_LOOKUP_SCHEMA_VERSION, buildCliLookupDocument, } from "../saved-lookup.mjs";
+import { CLI_LOOKUP_SCHEMA } from "../../packages/contracts/cli-lookup.mjs";
 const CLI_BULK_SCHEMA = 'whoisleuth.cli.bulk';
 const CLI_BULK_ITEM_SCHEMA = 'whoisleuth.cli.bulk.item';
 const CLI_CT_SEARCH_SCHEMA = 'whoisleuth.cli.ct-search';
@@ -9,42 +10,29 @@ const CLI_POSTURE_SCHEMA = 'whoisleuth.cli.posture';
 const CLI_HTTP_SCHEMA = 'whoisleuth.cli.http';
 const CLI_TLS_SCHEMA = 'whoisleuth.cli.tls';
 const CLI_COMPARE_SCHEMA = 'whoisleuth.cli.compare';
-const CLI_LOOKUP_SCHEMA_VERSION = 1;
+const CLI_LOOKUP_SCHEMA_VERSION = SAVED_LOOKUP_SCHEMA_VERSION;
 const CLI_BULK_SCHEMA_VERSION = 3;
 const CLI_CT_SEARCH_SCHEMA_VERSION = 1;
 const CLI_DISCOVER_SCHEMA_VERSION = 2;
 const CLI_POSTURE_SCHEMA_VERSION = 1;
-const CLI_HTTP_SCHEMA_VERSION = 2;
+const CLI_HTTP_SCHEMA_VERSION = 3;
 const CLI_TLS_SCHEMA_VERSION = 1;
 const CLI_COMPARE_SCHEMA_VERSION = 3;
-function buildCliLookupDocument(query, classified, result, generatedAt = new Date().toISOString(), mode = 'fast', collectionContext = {}) {
-    const observerLabel = typeof collectionContext.observerLabel === 'string'
-        ? collectionContext.observerLabel
-        : null;
-    const vantageLabel = typeof collectionContext.vantageLabel === 'string'
-        ? collectionContext.vantageLabel
-        : null;
-    return {
-        ...result,
-        schema: CLI_LOOKUP_SCHEMA,
-        version: CLI_LOOKUP_SCHEMA_VERSION,
-        generatedAt,
-        mode: mode === 'deep' ? 'deep' : 'fast',
-        query,
-        type: classified.type,
-        inputHostname: classified.inputHostname,
-        registrableDomain: classified.registrableDomain,
-        isSubdomain: classified.isSubdomain,
-        ...((observerLabel || vantageLabel) ? {
-            collectionContext: {
-                ...(observerLabel ? { observerLabel } : {}),
-                ...(vantageLabel ? { vantageLabel } : {}),
-            },
-        } : {}),
-    };
+const TERMINAL_UNSAFE_JSON_RE = /[\u007f-\u009f\u2028\u2029]|\p{Default_Ignorable_Code_Point}/gu;
+function jsonUnicodeEscape(value) {
+    const codePoint = value.codePointAt(0);
+    if (codePoint <= 0xffff)
+        return `\\u${codePoint.toString(16).padStart(4, '0')}`;
+    const offset = codePoint - 0x10000;
+    const high = 0xd800 + (offset >> 10);
+    const low = 0xdc00 + (offset & 0x3ff);
+    return `\\u${high.toString(16).padStart(4, '0')}\\u${low.toString(16).padStart(4, '0')}`;
+}
+function terminalSafeJson(value, space) {
+    return JSON.stringify(value, null, space).replace(TERMINAL_UNSAFE_JSON_RE, jsonUnicodeEscape);
 }
 function formatJsonDocument(document) {
-    return `${JSON.stringify(document, null, 2)}\n`;
+    return `${terminalSafeJson(document, 2)}\n`;
 }
 function buildCliCtSearchDocument(keyword, result, generatedAt = new Date().toISOString()) {
     return { ...result, schema: CLI_CT_SEARCH_SCHEMA, version: CLI_CT_SEARCH_SCHEMA_VERSION, generatedAt, keyword };
@@ -83,7 +71,7 @@ function discoverJsonItem(candidate, metadata) {
 function formatDiscoverJsonLines(candidates, metadata) {
     if (!candidates.length)
         return '';
-    return `${candidates.map((candidate) => JSON.stringify(discoverJsonItem(candidate, metadata))).join('\n')}\n`;
+    return `${candidates.map((candidate) => terminalSafeJson(discoverJsonItem(candidate, metadata))).join('\n')}\n`;
 }
 function formatDiscoverDomainList(candidates) {
     const domains = [...new Set(candidates.flatMap((candidate) => (typeof candidate.domain === 'string' && candidate.domain ? [candidate.domain] : [])))];
@@ -149,7 +137,7 @@ function buildCliBulkDocument(items, metadata) {
 }
 function formatJsonLines(items, metadata) {
     return items.length
-        ? `${items.map((item) => JSON.stringify(bulkJsonItem(item, metadata))).join('\n')}\n`
+        ? `${items.map((item) => terminalSafeJson(bulkJsonItem(item, metadata))).join('\n')}\n`
         : '';
 }
-export { CLI_BULK_ITEM_SCHEMA, CLI_BULK_SCHEMA, CLI_BULK_SCHEMA_VERSION, CLI_COMPARE_SCHEMA, CLI_COMPARE_SCHEMA_VERSION, CLI_CT_SEARCH_SCHEMA, CLI_CT_SEARCH_SCHEMA_VERSION, CLI_DISCOVER_ITEM_SCHEMA, CLI_DISCOVER_SCHEMA, CLI_DISCOVER_SCHEMA_VERSION, CLI_HTTP_SCHEMA, CLI_HTTP_SCHEMA_VERSION, CLI_POSTURE_SCHEMA, CLI_POSTURE_SCHEMA_VERSION, CLI_TLS_SCHEMA, CLI_TLS_SCHEMA_VERSION, CLI_LOOKUP_SCHEMA, CLI_LOOKUP_SCHEMA_VERSION, buildCliBulkDocument, buildCliCompareDocument, buildCliCtSearchDocument, buildCliDiscoverDocument, buildCliHttpDocument, buildCliLookupDocument, buildCliPostureDocument, buildCliTlsDocument, bulkJsonItem, discoverJsonItem, formatDiscoverDomainList, formatDiscoverJsonLines, formatJsonDocument, formatJsonLines, };
+export { CLI_BULK_ITEM_SCHEMA, CLI_BULK_SCHEMA, CLI_BULK_SCHEMA_VERSION, CLI_COMPARE_SCHEMA, CLI_COMPARE_SCHEMA_VERSION, CLI_CT_SEARCH_SCHEMA, CLI_CT_SEARCH_SCHEMA_VERSION, CLI_DISCOVER_ITEM_SCHEMA, CLI_DISCOVER_SCHEMA, CLI_DISCOVER_SCHEMA_VERSION, CLI_HTTP_SCHEMA, CLI_HTTP_SCHEMA_VERSION, CLI_POSTURE_SCHEMA, CLI_POSTURE_SCHEMA_VERSION, CLI_TLS_SCHEMA, CLI_TLS_SCHEMA_VERSION, CLI_LOOKUP_SCHEMA, CLI_LOOKUP_SCHEMA_VERSION, buildCliBulkDocument, buildCliCompareDocument, buildCliCtSearchDocument, buildCliDiscoverDocument, buildCliHttpDocument, buildCliLookupDocument, buildCliPostureDocument, buildCliTlsDocument, bulkJsonItem, discoverJsonItem, formatDiscoverDomainList, formatDiscoverJsonLines, formatJsonDocument, formatJsonLines, terminalSafeJson, };