@slicedearth/whoisleuth-cli 1.39.1 → 1.45.0

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

@@ -10,6 +10,8 @@ import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { formatJsonDocument } from "./formatters/json.mjs";
 import { createCliProgressEvents } from "./progress-events.mjs";
+import { buildCollectionPreflight, formatCollectionPreflight } from "./collection-preflight.mjs";
+import { evaluateCliFailPolicies, formatFailPolicyNotice } from "./fail-policy.mjs";
 async function readAllowlist(source, dependencies, classify) {
     if (!source)
         return new Set();
@@ -40,6 +42,15 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
     if (!candidates.length)
         throw new CliUsageError('discover-scan did not generate any valid candidates to collect.');
     const queries = candidates.map((candidate) => String(candidate.domain));
+    if (args.plan) {
+        const document = buildCollectionPreflight({
+            command: 'discover-scan', targetCount: queries.length, targetLimit: args.deep ? 50 : 500,
+            deep: args.deep, concurrency: args.concurrency, output: args.output, checkpoint: false,
+            customResolvers: Boolean(args.resolverText), allowlist: Boolean(args.allowlistSource),
+        });
+        context.writeStdout(args.output === 'json' ? formatJsonDocument(document) : context.terminal(formatCollectionPreflight(document), args.color));
+        return EXIT_CODES.SUCCESS;
+    }
     const classify = dependencies.classifyQuery || classifyQuery;
     let resolverServers = [];
     if (args.resolverText) {
@@ -64,6 +75,8 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
         : null;
     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]));
+    const settledItems = new Map();
     if (completed)
         indicator.update(`Resumed ${completed} of ${queries.length} generated candidates`);
     let checkpointFailure = null;
@@ -79,12 +92,23 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
             ...(checkpoint ? { initialResults: checkpoint.initialResults } : {}),
             ...(dependencies.signal ? { signal: dependencies.signal } : {}),
             onItemSettled: (item) => {
+                const observed = {
+                    ...item,
+                    observedAt: context.now(),
+                    collectionOrigin: 'current_run',
+                };
+                settledItems.set(item.index, observed);
                 completed += 1;
                 indicator.update(`Collected ${completed} of ${queries.length} generated candidates`);
                 eventProgress.emit({ event: 'item_settled', index: item.index, ok: item.ok });
-                checkpoint?.record(item);
+                checkpoint?.record(observed);
             },
         });
+        items = items.map((item) => resumedItems.get(item.index) ?? settledItems.get(item.index) ?? {
+            ...item,
+            observedAt: null,
+            collectionOrigin: 'current_run',
+        });
     }
     finally {
         context.endProgress();
@@ -132,7 +156,10 @@ async function runDiscoveryScanCommand(args, dependencies, context) {
             context.writeStderr(`Checkpoint warning: ${boundedCliErrorMessage(checkpointFailure, 'Checkpoint could not be written')}. Completed output is still available.\n`);
         }
     }
-    const exitCode = checkpointFailure || items.some((item) => !item.ok)
+    const policyFindings = evaluateCliFailPolicies(document, args.failOn || []);
+    if (policyFindings.length && !eventProgress.enabled)
+        context.writeStderr(formatFailPolicyNotice(policyFindings));
+    const exitCode = checkpointFailure || items.some((item) => !item.ok) || policyFindings.length
         ? EXIT_CODES.PARTIAL_FAILURE
         : EXIT_CODES.SUCCESS;
     eventProgress.emit({ event: 'completed', exitCode });

package/cli/discovery-snapshot.mjs

@@ -1,13 +1,12 @@
 import { createHash } from 'node:crypto';
-import { open } from 'node:fs/promises';
-import { CliUsageError } from "./errors.mjs";
+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";
 export const CLI_DISCOVERY_SNAPSHOT_SCHEMA = 'whoisleuth.cli.discovery-snapshot';
 export const CLI_DISCOVERY_SNAPSHOT_VERSION = 1;
 export const MAX_DISCOVERY_SNAPSHOT_BYTES = 4 * 1024 * 1024;
 export const MAX_DISCOVERY_SNAPSHOT_DOMAINS = 10_000;
-const SHA256_RE = /^[a-f0-9]{64}$/u;
 function configurationDigest(configuration) {
     return createHash('sha256').update(JSON.stringify({
         seed: configuration.seed,
@@ -69,22 +68,16 @@ function parseDiscoverySnapshot(text, expectedConfigurationDigest) {
 }
 async function readExistingSnapshot(path) {
     try {
-        const handle = await open(path, 'r');
-        try {
-            const metadata = await handle.stat();
-            if (!metadata.isFile() || metadata.size > MAX_DISCOVERY_SNAPSHOT_BYTES) {
-                throw new CliUsageError(`Discovery snapshot input is limited to ${MAX_DISCOVERY_SNAPSHOT_BYTES} bytes.`);
-            }
-            return await handle.readFile({ encoding: 'utf8' });
-        }
-        finally {
-            await handle.close();
-        }
+        return await readBoundedRegularTextFile(path, {
+            maximumBytes: MAX_DISCOVERY_SNAPSHOT_BYTES,
+            label: 'Discovery snapshot input',
+            allowSymbolicLink: true,
+        });
     }
     catch (error) {
         if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
             return null;
-        throw error;
+        throw boundedCliInputError(error, 'Discovery snapshot input');
     }
 }
 async function updateDiscoverySnapshot(path, candidatesValue, configuration, generatedAt) {

package/cli/domain-control-monitor.mjs

@@ -0,0 +1,104 @@
+import { classifyQuery } from "../lib/classify.mjs";
+import { buildDomainControlFlightRecorder, } from "../lib/domain-control-flight-recorder.mjs";
+import { verifyDomainControlManifest } from "../lib/domain-control-manifest.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;
+function previousSnapshot(input) {
+    if (!input)
+        return { observations: [] };
+    let parsed;
+    try {
+        parsed = JSON.parse(input.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('Previous monitor snapshot must be valid JSON.');
+    }
+    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)) {
+        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 };
+}
+export async function runDomainControlMonitor(manifestInput, previousInput, options) {
+    const generatedAt = options.now();
+    let rawManifest;
+    try {
+        rawManifest = JSON.parse(manifestInput.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        throw new CliUsageError('Domain-control manifest must be valid JSON.');
+    }
+    const manifest = verifyDomainControlManifest(rawManifest);
+    const entries = manifest.entries.slice(0, Math.min(options.limit, MAX_DOMAIN_CONTROL_MONITOR_DOMAINS));
+    const lookups = new Array(entries.length);
+    const failures = [];
+    let cursor = 0;
+    let completed = 0;
+    const worker = async () => {
+        while (cursor < entries.length) {
+            const index = cursor++;
+            const entry = entries[index];
+            if (!entry)
+                break;
+            try {
+                const classified = classifyQuery(entry.domain);
+                const result = await options.executeLookup(classified, { fast: false, compact: false, ...(options.signal ? { signal: options.signal } : {}) });
+                lookups[index] = buildCliLookupDocument(entry.domain, classified, result, generatedAt, 'deep');
+            }
+            catch (cause) {
+                failures.push({ domain: entry.domain, error: boundedCliErrorMessage(cause, 'Lookup failed') });
+            }
+            finally {
+                completed += 1;
+                options.onSettled?.(completed, entries.length);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(options.concurrency, Math.max(entries.length, 1)) }, worker));
+    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,
+    }), generatedAt);
+    const previous = previousSnapshot(previousInput);
+    const observations = review.observations;
+    const flightRecorder = buildDomainControlFlightRecorder({
+        schema: 'whoisleuth.domain-control-flight-recorder.input', version: 1,
+        observations: [...previous.observations, ...observations], approvedWindows: [],
+    }, generatedAt);
+    return Object.freeze({
+        schema: CLI_DOMAIN_CONTROL_MONITOR_SCHEMA,
+        version: CLI_DOMAIN_CONTROL_MONITOR_VERSION,
+        generatedAt,
+        manifest: Object.freeze({ digestSha256: manifest.integrity.digestSha256, expiresAt: manifest.expiresAt }),
+        collection: Object.freeze({ requested: entries.length, succeeded: observations.length, failed: failures.length, failures: Object.freeze(failures) }),
+        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.',
+        ]),
+    });
+}
+export function formatDomainControlMonitor(document) {
+    return [
+        'One-shot domain control review',
+        `Requested    ${document.collection.requested}`,
+        `Succeeded    ${document.collection.succeeded}`,
+        `Failed       ${document.collection.failed}`,
+        `Review       ${document.review.state}`,
+        `Unexpected   ${document.flightRecorder.summary.unexpectedChanges}`,
+        '',
+    ].join('\n');
+}

package/cli/domain-control-observations.mjs

@@ -0,0 +1,235 @@
+import { Buffer } from 'node:buffer';
+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;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function state(value) {
+    const normalized = typeof value === 'string' ? value.toLowerCase() : '';
+    if (normalized === 'success' || normalized === 'complete')
+        return 'observed';
+    if (normalized === 'partial' || normalized === 'not_found')
+        return 'partial';
+    if (normalized === 'unsupported' || normalized === 'not_applicable')
+        return 'unsupported';
+    return 'unavailable';
+}
+function text(value, maximum = 500) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum);
+    return normalized || null;
+}
+function list(value, normalizer = (item) => text(item)) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.slice(0, 128).flatMap((item) => {
+            const normalized = normalizer(item);
+            return normalized ? [normalized.toLowerCase()] : [];
+        }))].sort().slice(0, 32);
+}
+function hostname(value) {
+    return text(value, 253)?.toLowerCase().replace(/\.$/u, '') ?? null;
+}
+function mxValue(value) {
+    const item = record(value);
+    const exchange = hostname(item.exchange ?? item.host ?? item.value);
+    if (!exchange)
+        return text(value);
+    const priority = Number.isSafeInteger(item.priority) && Number(item.priority) >= 0 ? Number(item.priority) : null;
+    return priority === null ? exchange : `${priority} ${exchange}`;
+}
+function caaValue(value) {
+    const item = record(value);
+    const tag = text(item.tag, 32)?.toLowerCase();
+    const recordValue = text(item.value, 500)?.toLowerCase();
+    if (!tag || !recordValue)
+        return text(value);
+    const critical = Number.isSafeInteger(item.critical) ? Number(item.critical) : Number.isSafeInteger(item.flags) ? Number(item.flags) : 0;
+    return `${critical} ${tag} ${recordValue}`;
+}
+function dsValue(value) {
+    const item = record(value);
+    const keyTag = Number.isSafeInteger(item.keyTag) ? item.keyTag : null;
+    const algorithm = Number.isSafeInteger(item.algorithm) ? item.algorithm : null;
+    const digestType = Number.isSafeInteger(item.digestType) ? item.digestType : null;
+    const digest = text(item.digest, 512)?.toLowerCase();
+    return keyTag !== null && algorithm !== null && digestType !== null && digest
+        ? `${keyTag} ${algorithm} ${digestType} ${digest}`
+        : text(value);
+}
+function field(id, source, sourceState, values) {
+    return Object.freeze({ id, source, state: sourceState, values: Object.freeze([...values].sort()) });
+}
+function diagnostic(document, key) {
+    return state(record(document.diagnostics)[key] && record(record(document.diagnostics)[key]).status);
+}
+function registryParsed(document) {
+    const rdapState = diagnostic(document, 'rdap');
+    const whoisState = diagnostic(document, 'whois');
+    const rdap = record(record(document.rdap).parsed);
+    if (rdapState === 'observed' && Object.keys(rdap).length)
+        return { parsed: rdap, source: 'Registry RDAP', sourceState: rdapState };
+    const whois = record(record(document.whois).parsed);
+    return { parsed: whois, source: 'WHOIS', sourceState: whoisState };
+}
+function lockValue(parsed) {
+    const statuses = list(parsed.statuses ?? parsed.status, (item) => text(item, 120)?.replace(/[\s_-]+/gu, '').toLowerCase() ?? null);
+    return [statuses.some((item) => item.includes('transferprohibited')) ? 'required' : 'not_required'];
+}
+function pageIdentityValue(availability) {
+    const identity = record(availability.pageIdentity);
+    const components = [
+        text(identity.bodySha256 ?? availability.pageBodySha256, 64),
+        text(identity.faviconHash ?? availability.faviconHash, 128),
+        text(identity.title ?? availability.pageTitle, 240),
+    ].filter((item) => Boolean(item));
+    return components.length ? [components.join(' | ').toLowerCase()] : [];
+}
+export function domainControlObservationFromSavedLookup(document) {
+    const availability = record(document.availability);
+    const dns = record(availability.dns);
+    const dnsRecords = record(dns.records);
+    const delegation = record(dns.delegation);
+    const delegationRecords = record(delegation.records);
+    const tls = record(availability.tls);
+    const tlsState = state(tls.status);
+    const certificate = record(tls.certificate);
+    const publicKey = record(certificate.publicKey);
+    const http = record(availability.http);
+    const httpState = state(http.status);
+    const registry = registryParsed(document);
+    const rdapParsed = record(record(document.rdap).parsed);
+    const rdapState = diagnostic(document, 'rdap');
+    const dnsState = state(dns.status);
+    const fields = [
+        field('registrar', registry.source, registry.sourceState, list([record(registry.parsed.registrar).name ?? registry.parsed.registrar], (item) => text(item, 300))),
+        field('registrar_lock', registry.source, registry.sourceState, registry.sourceState === 'observed' ? lockValue(registry.parsed) : []),
+        field('registry_dnssec', 'Registry RDAP', rdapState, list([rdapParsed.dnssec], (item) => text(item, 80))),
+        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('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))),
+        field('tls_public_key', 'TLS', tlsState, list([publicKey.fingerprintSha256 ?? tls.spkiSha256], (item) => text(item, 128))),
+        field('http_origin', 'HTTP', httpState, list([http.finalOrigin ?? availability.httpFinalOrigin], (item) => text(item, 500))),
+        field('page_identity', 'Static page identity', state(record(availability.pageIdentity).status ?? availability.pageIdentityStatus ?? http.status), pageIdentityValue(availability)),
+    ];
+    return Object.freeze({
+        domain: document.registrableDomain,
+        observedAt: document.generatedAt,
+        collectionDepth: document.mode,
+        fields: Object.freeze(fields.filter((item) => DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS.includes(item.id))),
+    });
+}
+export function buildCliDomainControlReview(inputText, generatedAt = new Date().toISOString()) {
+    if (Buffer.byteLength(inputText, 'utf8') > MAX_DOMAIN_CONTROL_REVIEW_INPUT_BYTES) {
+        throw new CliUsageError(`Domain-control review input is limited to ${MAX_DOMAIN_CONTROL_REVIEW_INPUT_BYTES} bytes.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(inputText.replace(/^\uFEFF/u, ''));
+    }
+    catch {
+        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 (Object.keys(input).some((key) => !new Set(['schema', 'version', 'manifest', 'lookups']).has(key))) {
+        throw new CliUsageError('Domain-control review input contains an unsupported field.');
+    }
+    if (input.lookups.length < 1 || input.lookups.length > 100) {
+        throw new CliUsageError('Domain-control review requires from 1 to 100 saved Lookup documents.');
+    }
+    const manifest = verifyDomainControlManifest(input.manifest);
+    const lookups = input.lookups.map((item, index) => parseSavedLookupDocument(JSON.stringify(item), { label: `Lookup ${index + 1}` }));
+    const latest = new Map();
+    for (const lookup of lookups) {
+        const current = latest.get(lookup.registrableDomain);
+        if (!current || Date.parse(lookup.generatedAt) > Date.parse(current.generatedAt))
+            latest.set(lookup.registrableDomain, lookup);
+    }
+    const observations = [...latest.values()].map(domainControlObservationFromSavedLookup);
+    const review = reviewDomainControlManifest({
+        schema: DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA,
+        version: 1,
+        manifest,
+        observations: observations.map((item) => ({
+            domain: item.domain,
+            fields: Object.fromEntries(item.fields.flatMap((candidate) => {
+                const mapping = {
+                    registry_nameservers: 'nameservers',
+                    delegation_ds: 'ds',
+                    mail_exchangers: 'mx',
+                    caa_policy: 'caa',
+                    tls_certificate: 'tlsIssuer',
+                    tls_public_key: 'tlsSpkiSha256',
+                    registrar_lock: 'registrarLock',
+                };
+                const target = mapping[candidate.id];
+                if (!target)
+                    return [];
+                const candidateValues = candidate.id === 'tls_certificate'
+                    ? list([record(record(record(latest.get(item.domain)?.availability).tls).certificate).issuer], (value) => {
+                        const issuer = record(value);
+                        const commonNames = Array.isArray(issuer.commonNames) ? issuer.commonNames : [];
+                        const organisationNames = Array.isArray(issuer.organizationNames) ? issuer.organizationNames : [];
+                        return text(commonNames[0] ?? organisationNames[0] ?? value, 300);
+                    })
+                    : candidate.values;
+                return [[target, { state: candidate.state, values: candidateValues, source: candidate.source, observedAt: item.observedAt }]];
+            })),
+        })),
+    }, generatedAt);
+    return Object.freeze({
+        schema: CLI_DOMAIN_CONTROL_REVIEW_SCHEMA,
+        version: CLI_DOMAIN_CONTROL_REVIEW_VERSION,
+        generatedAt,
+        review,
+        observations: Object.freeze(observations),
+        input: Object.freeze({
+            lookupsReceived: lookups.length,
+            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.',
+        ]),
+    });
+}
+export function buildControlReviewInput(manifest, lookupDocuments) {
+    return Object.freeze({
+        schema: CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA,
+        version: 1,
+        manifest,
+        lookups: Object.freeze(lookupDocuments),
+    });
+}
+export function formatCliDomainControlReview(document) {
+    const review = document.review;
+    return [
+        'Domain-control evidence review',
+        `State       ${review.state}`,
+        `Domains     ${review.domains.length}`,
+        `Lookups     ${document.input.lookupsReceived}`,
+        `Drift       ${review.counts.drift ?? 0}`,
+        `Incomplete  ${(review.counts.partial ?? 0) + (review.counts.unavailable ?? 0) + (review.counts.unsupported ?? 0)}`,
+        '',
+        ...review.domains.map((item) => `${item.domain}  ${item.state}`),
+        '',
+        ...document.limitations.map((item) => `Limitation: ${item}`),
+        '',
+    ].join('\n');
+}

package/cli/errors.mjs

@@ -18,4 +18,10 @@ function boundedCliErrorMessage(error, fallback = 'Unexpected command failure')
         .trim()
         .slice(0, MAX_CLI_ERROR_MESSAGE_LENGTH) || fallback;
 }
-export { CliUsageError, MAX_CLI_ERROR_MESSAGE_LENGTH, boundedCliErrorMessage };
+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, };

package/cli/evidence-command-arguments.mjs

@@ -5,6 +5,7 @@ export function parseInspectArchiveArguments(argv) {
     let search = null;
     let reveal = false;
     let requireMatch = false;
+    let expectedContentDigest = null;
     let output = 'terminal';
     let quiet = false;
     let color = true;
@@ -43,6 +44,15 @@ export function parseInspectArchiveArguments(argv) {
                 throw new CliUsageError('--require-match may be supplied only once.');
             requireMatch = true;
         }
+        else if (argument === '--expect-content-digest') {
+            if (expectedContentDigest !== null)
+                throw new CliUsageError('--expect-content-digest may be supplied only once.');
+            const value = argv[++index];
+            if (!value || !/^sha256:[a-f0-9]{64}$/u.test(value)) {
+                throw new CliUsageError('--expect-content-digest requires sha256 followed by 64 lowercase hexadecimal characters.');
+            }
+            expectedContentDigest = value;
+        }
         else if (argument === '--quiet')
             quiet = true;
         else if (argument === '--no-color')
@@ -67,6 +77,7 @@ export function parseInspectArchiveArguments(argv) {
         search,
         reveal,
         requireMatch,
+        expectedContentDigest,
         output,
         quiet,
         color,

package/cli/evidence-command-runner.mjs

@@ -71,6 +71,7 @@ export async function runEvidenceCommand(args, dependencies) {
             search: args.search,
             reveal: args.reveal,
             requireMatch: args.requireMatch,
+            expectedContentDigest: args.expectedContentDigest,
         });
         if (!args.quiet) {
             dependencies.stdout.write(args.output === 'json'