@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/cli/network-arguments.mjs

@@ -0,0 +1,51 @@
+import {} from "./command-argument-grammar.mjs";
+import { commandDefaultText } from "./command-reference.mjs";
+import { NETWORK_COMMAND_DEFINITIONS } from "./network-command-definitions.mjs";
+import { terminalOptions, jsonOutput, parseOutput, singleInputAction, } from "./argument-values.mjs";
+function parsePostureArguments(parsed) {
+    const mailProfile = parsed.optionValue('--mail-profile') ?? commandDefaultText('posture', '--mail-profile');
+    return {
+        action: 'posture',
+        domain: parsed.positionalValue('domain'),
+        output: parseOutput(parsed, NETWORK_COMMAND_DEFINITIONS.posture),
+        selectorText: parsed.optionValue('--selectors'),
+        retiredSelectorText: parsed.optionValue('--retired-selectors'),
+        mailProfile: mailProfile === 'defensive-no-mail'
+            ? 'defensive_no_mail'
+            : mailProfile,
+        ownedDomain: parsed.hasOption('--owned-domain'),
+        ...(parsed.hasOption('--include-inherited-dns') ? { includeInheritedDns: true } : {}),
+        ...terminalOptions(parsed),
+    };
+}
+function parseDnssecValidateArguments(parsed) {
+    return {
+        action: 'dnssec-validate',
+        target: parsed.positionalValue('domain'),
+        resolver: parsed.optionValue('--resolver'),
+        trustAnchorSource: parsed.optionValue('--trust-anchor'),
+        ownedOrAuthorized: true,
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    };
+}
+function parseMailTransportArguments(parsed) {
+    return {
+        action: 'mail-transport',
+        source: parsed.positionalValue('source'),
+        resolver: parsed.optionValue('--resolver'),
+        trustAnchorSource: parsed.optionValue('--trust-anchor'),
+        ownedOrAuthorized: true,
+        activeProbeAcknowledged: true,
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    };
+}
+export const NETWORK_ARGUMENT_PARSERS = Object.freeze({
+    'ct-search': (parsed) => singleInputAction('ct-search', parsed, 'keyword'),
+    posture: parsePostureArguments,
+    http: (parsed) => singleInputAction('http', parsed, 'domain'),
+    tls: (parsed) => singleInputAction('tls', parsed, 'hostname'),
+    'dnssec-validate': parseDnssecValidateArguments,
+    'mail-transport': parseMailTransportArguments,
+});

package/cli/network-command-definitions.mjs

@@ -0,0 +1,130 @@
+import { positional, OPTIONAL_FILE_POSITIONAL, constraint, EMPTY_CONSTRAINTS, commandSeed } from "./command-definition.mjs";
+export const NETWORK_COMMAND_DEFINITIONS = Object.freeze({
+    "ct-search": commandSeed({
+        reference: {
+            description: 'Search certificate-transparency observations for one bounded keyword.',
+            example: 'whoisleuth ct-search "example brand" --json',
+            boundary: 'Certificate observations do not prove website activity, registration ownership, or malicious intent.',
+        },
+        collection: { scope: 'Accepts one bounded search keyword and queries the fixed certificate-transparency source.' },
+        summary: 'Search certificate observations',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('keyword', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.ct-search']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    posture: commandSeed({
+        reference: {
+            description: 'Review bounded DNS mail, delegation, and domain-control posture.',
+            example: 'whoisleuth posture example.test --mail-profile standard --json',
+            boundary: 'Missing or failed DNS observations remain inconclusive. --include-inherited-dns adds inherited policy and reporting-boundary reviews within 32 additional TXT queries and ten seconds, plus a direct parent-delegation sample. No message is sent and receiver enforcement is not inferred.',
+        },
+        collection: { scope: 'Accepts one domain and performs bounded RDAP, DNS, and conditional MTA-STS HTTPS requests. --include-inherited-dns separately adds ancestor and reporting-destination DMARC questions and direct DNS/TCP to sampled parent servers.' },
+        summary: 'Review DNS and mail posture',
+        options: ['--selectors', '--retired-selectors', '--mail-profile', '--include-inherited-dns', '--json', '--sarif', '--owned-domain', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('domain', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: Object.freeze([
+            constraint({ kind: 'mutually_exclusive', options: ['--json', '--sarif'] }),
+            constraint({ kind: 'requires_all', option: '--sarif', requiredOptions: ['--owned-domain'] }),
+        ]),
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.posture']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    http: commandSeed({
+        reference: {
+            description: 'Inspect one homepage request, redirects, and bounded response metadata.',
+            example: 'whoisleuth http example.test --json',
+            boundary: 'Requests use the shared public-address and redirect guards. Fixed content-coding and cache-policy metadata describes only the selected response, excludes raw header values, and does not prove caching, transfer savings, performance, privacy, or safety. This is not a rendered browser or vulnerability scan.',
+        },
+        collection: { scope: 'Accepts one domain and follows only the bounded SSRF-guarded homepage redirect workflow.' },
+        summary: 'Inspect one homepage request',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('domain', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.http']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    tls: commandSeed({
+        reference: {
+            description: 'Inspect one hostname certificate through a bounded TLS connection.',
+            example: 'whoisleuth tls example.test --json',
+            boundary: 'One observed connection is point-in-time evidence and does not establish every address, edge, or historical certificate.',
+        },
+        collection: { scope: 'Accepts one public hostname and opens one bounded certificate connection.' },
+        summary: 'Inspect one TLS connection',
+        options: ['--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('hostname', 'text', 0, 1, [], 'argv_or_stdin')]),
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.tls']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "dnssec-validate": commandSeed({
+        reference: {
+            description: 'Cryptographically validate one authorised DNSSEC chain from a supplied trust anchor through one selected public resolver.',
+            example: 'whoisleuth dnssec-validate example.test --resolver "$PUBLIC_RESOLVER_IP" --trust-anchor anchor.json --owned-or-authorized --json',
+            boundary: 'This isolated action is never invoked by Lookup, Bulk, monitoring, or recipes. It caps DNS queries, aliases, delegations, bytes, and duration; transport and validation failures remain separate, and secure is not a general safety verdict.',
+        },
+        collection: { scope: 'Accepts one authorised domain, one public resolver IP, and one local trust-anchor file; DNS-over-TCP validation is capped at 32 queries and 15 seconds.' },
+        summary: 'Validate an authorised DNSSEC chain',
+        options: ['--resolver', '--trust-anchor', '--owned-or-authorized', '--json', '--quiet', '--no-color'],
+        positionals: Object.freeze([positional('domain', 'text', 1, 1)]),
+        constraints: Object.freeze([
+            constraint({ kind: 'required', options: ['--resolver', '--trust-anchor', '--owned-or-authorized'] }),
+        ]),
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.dnssec-chain-validation', 'whoisleuth.dnssec-trust-anchor']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "mail-transport": commandSeed({
+        reference: {
+            description: 'Review selected authorised MX endpoints, DNSSEC-qualified TLSA evidence, SMTP capabilities, and optional STARTTLS certificates.',
+            example: 'whoisleuth mail-transport selected-mx.json --resolver "$PUBLIC_RESOLVER_IP" --trust-anchor anchor.json --owned-or-authorized --active-probe --json',
+            boundary: 'This isolated action probes at most three selected MX hosts sequentially, reports selection, public revalidation, connection, and address authentication separately, sends only EHLO and optional STARTTLS, never retries, and performs no authentication, relay, recipient, mailbox, catch-all, or message test. If a DANE-TA TLSA usage 2 association is published, active collection retains only the leaf certificate and leaves that comparison partial without certificate-path construction and trust-anchor path validation. SMTP relay PKIX-TA usage 0 and PKIX-EE usage 1 records remain unsupported and cannot complete SMTP DANE assurance; a separate usage 3 match remains eligible.',
+        },
+        collection: { scope: 'Accepts at most three selected authorised MX hosts, uses one public resolver, and performs sequential bounded SMTP connections with no retries.' },
+        summary: 'Review selected authorised SMTP transports',
+        options: ['--resolver', '--trust-anchor', '--owned-or-authorized', '--active-probe', '--json', '--quiet', '--no-color'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'required', options: ['--resolver', '--trust-anchor', '--owned-or-authorized', '--active-probe'] }),
+        ]),
+        handlerOwner: 'network',
+        networkEffect: 'always_network',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.mail-transport.input', 'whoisleuth.cli.mail-transport-review']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/network-command-runner.mjs

@@ -1,6 +1,7 @@
+import { runDiscriminatedCommandHandler, } from "./discriminated-command-handlers.mjs";
 import { fetchHomepage } from "../lib/availability.mjs";
 import { searchCertificateTransparency } from "../lib/ct-search.mjs";
-import { checkDomainPosture, normalizeAuditDomain, normalizeDkimSelectors } from "../lib/domain-posture.mjs";
+import { checkDomainPosture, normalizeAuditDomain, normalizeDkimSelectors, } from "../lib/domain-posture.mjs";
 import { collectTlsIntelligence, normalizeTlsHostname } from "../lib/tls-intelligence.mjs";
 import { MAX_DNSSEC_TRUST_ANCHOR_BYTES, formatDnssecChainReport, validateDnssecChain, } from "../lib/dnssec-chain-validation.mjs";
 import { MAX_MAIL_TRANSPORT_INPUT_BYTES, collectMailTransportReview, formatMailTransportReview, } from "../lib/smtp-transport-review.mjs";
@@ -11,9 +12,10 @@ import { buildHttpProbeResult } from "./http.mjs";
 import { normalizePostureSelectors } from "./posture.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { buildPostureSarif } from "./ci-report.mjs";
-async function runNetworkCommand(args, dependencies, context) {
-    if (args.action === 'ct-search') {
-        const keyword = args.keyword || await context.readSingleInput();
+const networkCommandHandlers = {
+    'ct-search': async (args, dependencies, context) => {
+        context.setFailureLabel('Certificate Transparency search');
+        const keyword = args.keyword || (await context.readSingleInput());
         if (!keyword)
             throw new CliUsageError('ct-search requires one keyword as an argument or on stdin.');
         const search = dependencies.searchCertificateTransparency || searchCertificateTransparency;
@@ -25,9 +27,10 @@ async function runNetworkCommand(args, dependencies, context) {
                 : context.terminal(formatTerminalCtSearch(document), args.color));
         }
         return EXIT_CODES.SUCCESS;
-    }
-    if (args.action === 'posture') {
-        const requestedDomain = args.domain || await context.readSingleInput();
+    },
+    posture: async (args, dependencies, context) => {
+        context.setFailureLabel('Domain posture audit');
+        const requestedDomain = args.domain || (await context.readSingleInput());
         if (!requestedDomain)
             throw new CliUsageError('posture requires one domain as an argument or on stdin.');
         const normalizeDomain = dependencies.normalizeAuditDomain || normalizeAuditDomain;
@@ -56,9 +59,10 @@ async function runNetworkCommand(args, dependencies, context) {
                     : context.terminal(formatTerminalPosture(document), args.color));
         }
         return EXIT_CODES.SUCCESS;
-    }
-    if (args.action === 'http') {
-        const requestedDomain = args.domain || await context.readSingleInput();
+    },
+    http: async (args, dependencies, context) => {
+        context.setFailureLabel('HTTP probe');
+        const requestedDomain = args.domain || (await context.readSingleInput());
         if (!requestedDomain)
             throw new CliUsageError('http requires one domain as an argument or on stdin.');
         const normalizeDomain = dependencies.normalizeAuditDomain || normalizeAuditDomain;
@@ -74,8 +78,9 @@ async function runNetworkCommand(args, dependencies, context) {
                 : context.terminal(formatTerminalHttp(document), args.color));
         }
         return EXIT_CODES.SUCCESS;
-    }
-    if (args.action === 'dnssec-validate') {
+    },
+    'dnssec-validate': async (args, dependencies, context) => {
+        context.setFailureLabel('DNSSEC chain validation');
         let anchorInput;
         try {
             anchorInput = dependencies.readTrustAnchorInput
@@ -103,8 +108,9 @@ async function runNetworkCommand(args, dependencies, context) {
         return report.state === 'secure' || report.state === 'insecure'
             ? EXIT_CODES.SUCCESS
             : EXIT_CODES.PARTIAL_FAILURE;
-    }
-    if (args.action === 'mail-transport') {
+    },
+    'mail-transport': async (args, dependencies, context) => {
+        context.setFailureLabel('Mail transport review');
         let input;
         let anchorInput;
         try {
@@ -150,22 +156,28 @@ async function runNetworkCommand(args, dependencies, context) {
                 : context.terminal(formatMailTransportReview(review), args.color));
         }
         return review.runState === 'complete' ? EXIT_CODES.SUCCESS : EXIT_CODES.PARTIAL_FAILURE;
-    }
-    const requestedHostname = args.hostname || await context.readSingleInput();
-    if (!requestedHostname)
-        throw new CliUsageError('tls requires one hostname as an argument or on stdin.');
-    const normalizeHostname = dependencies.normalizeTlsHostname || normalizeTlsHostname;
-    const hostname = normalizeHostname(requestedHostname);
-    if (!hostname)
-        throw new CliUsageError('tls requires a valid DNS hostname, not an IP address.');
-    const collect = dependencies.collectTlsIntelligence || collectTlsIntelligence;
-    const result = await context.withProgress('Inspecting the current TLS connection', () => collect(hostname));
-    const document = buildCliTlsDocument(requestedHostname, result, context.now());
-    if (!args.quiet) {
-        context.writeStdout(args.output === 'json'
-            ? formatJsonDocument(document)
-            : context.terminal(formatTerminalTls(document), args.color));
-    }
-    return EXIT_CODES.SUCCESS;
+    },
+    tls: async (args, dependencies, context) => {
+        context.setFailureLabel('TLS evidence collection');
+        const requestedHostname = args.hostname || (await context.readSingleInput());
+        if (!requestedHostname)
+            throw new CliUsageError('tls requires one hostname as an argument or on stdin.');
+        const normalizeHostname = dependencies.normalizeTlsHostname || normalizeTlsHostname;
+        const hostname = normalizeHostname(requestedHostname);
+        if (!hostname)
+            throw new CliUsageError('tls requires a valid DNS hostname, not an IP address.');
+        const collect = dependencies.collectTlsIntelligence || collectTlsIntelligence;
+        const result = await context.withProgress('Inspecting the current TLS connection', () => collect(hostname));
+        const document = buildCliTlsDocument(requestedHostname, result, context.now());
+        if (!args.quiet) {
+            context.writeStdout(args.output === 'json'
+                ? formatJsonDocument(document)
+                : context.terminal(formatTerminalTls(document), args.color));
+        }
+        return EXIT_CODES.SUCCESS;
+    },
+};
+async function runNetworkCommand(args, dependencies, context) {
+    return runDiscriminatedCommandHandler(networkCommandHandlers, args, dependencies, context);
 }
 export { runNetworkCommand };

package/cli/offline-evidence-review.mjs

@@ -1,5 +1,7 @@
 import { Buffer } from 'node:buffer';
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { CONTEXT_INPUT_SCHEMAS, reviewContextInput } from "../packages/investigation/context-review.mjs";
+import { CONTEXT_REVIEW_KINDS } from "../packages/contracts/context-review.mjs";
 import { normalizeEncryptedDnsAdapter, planEncryptedDnsQuery, } from "../lib/encrypted-dns-contract.mjs";
 import { validateDnssecEvidence } from "../lib/dnssec-evidence-validation.mjs";
 import { reviewDomainChange } from "../lib/domain-change-review.mjs";
@@ -15,7 +17,7 @@ import { reviewDnsConvergence } from "../lib/dns-convergence-review.mjs";
 import { compareTrustStoreEvidence } from "../lib/trust-store-comparison.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
-import { LOCAL_MMDB_QUERY_SCHEMA, reviewLocalMmdb } from "./local-mmdb-review.mjs";
+import { LOCAL_MMDB_QUERY_SCHEMA, LOCAL_MMDB_QUERY_VERSION, LOCAL_MMDB_REVIEW_SCHEMA, LOCAL_MMDB_REVIEW_VERSION, reviewLocalMmdb } from "./local-mmdb-review.mjs";
 const OFFLINE_EVIDENCE_REVIEW_SCHEMA = 'whoisleuth.cli.offline-evidence-review';
 const OFFLINE_EVIDENCE_REVIEW_VERSION = 1;
 const MAX_OFFLINE_EVIDENCE_INPUT_BYTES = 16 * 1024 * 1024;
@@ -43,16 +45,24 @@ function parseInput(value) {
         throw new CliUsageError('Offline evidence review requires one valid bounded JSON document without duplicate keys.');
     }
     const document = record(parsed);
-    if (document.version !== 1 || typeof document.schema !== 'string') {
+    if (typeof document.schema !== 'string' || document.version !== 1
+        && !(document.schema === LOCAL_MMDB_QUERY_SCHEMA && document.version === LOCAL_MMDB_QUERY_VERSION)) {
         throw new CliUsageError('Offline evidence review requires a supported versioned input schema.');
     }
     return document;
 }
 function buildOfflineEvidenceReview(value, generatedAt = new Date().toISOString()) {
     const input = parseInput(value);
+    if (input.schema === LOCAL_MMDB_QUERY_SCHEMA)
+        throw new CliUsageError('Local MMDB review requires --mmdb <database-file>.');
     let kind;
     let result;
-    if (input.schema === RDAP_SEARCH_INPUT_SCHEMA) {
+    if (CONTEXT_INPUT_SCHEMAS.includes(input.schema)) {
+        const review = reviewContextInput(input, generatedAt);
+        kind = review.kind;
+        result = review;
+    }
+    else if (input.schema === RDAP_SEARCH_INPUT_SCHEMA) {
         kind = 'rdap_search';
         const request = record(input.request);
         const help = normalizeRdapSearchHelp(input.help);
@@ -163,7 +173,7 @@ async function buildOfflineEvidenceReviewWithLocalResources(value, generatedAt =
         version: OFFLINE_EVIDENCE_REVIEW_VERSION,
         generatedAt,
         kind: 'geoip',
-        result: await reviewLocalMmdb(input, options.mmdbPath),
+        result: await reviewLocalMmdb(input, options.mmdbPath, generatedAt),
         limitations: Object.freeze([
             'The review is local and uses only the supplied query metadata and analyst-supplied database. It does not transmit the address or refresh the database.',
         ]),
@@ -171,6 +181,9 @@ async function buildOfflineEvidenceReviewWithLocalResources(value, generatedAt =
 }
 function formatOfflineEvidenceReview(document) {
     const result = record(document.result);
+    if (document.kind === 'geoip' && result.schema === LOCAL_MMDB_REVIEW_SCHEMA && result.version !== LOCAL_MMDB_REVIEW_VERSION) {
+        throw new CliUsageError('Offline evidence review does not support this MMDB result version.');
+    }
     const gate = record(result.gate);
     const counts = record(result.counts);
     const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
@@ -191,7 +204,16 @@ function formatOfflineEvidenceReview(document) {
         `Kind   ${document.kind.replaceAll('_', ' ')}`,
         `State  ${state.replaceAll('_', ' ')}`,
     ];
-    if (document.kind === 'rdap_search') {
+    if (CONTEXT_REVIEW_KINDS.includes(document.kind)) {
+        lines.push(safeTerminalValue(result.summary, ''));
+        for (const item of Array.isArray(result.observations) ? result.observations : []) {
+            const row = record(item);
+            lines.push('', `${safeTerminalValue(row.label, 'Observation')} [${safeTerminalValue(row.state, 'unknown')}]`, `  ${safeTerminalValue(row.detail, '')}`, `  Source: ${safeTerminalValue(row.source, '')} · ${safeTerminalValue(row.observedAt, 'time unknown')}`);
+        }
+        for (const step of Array.isArray(result.nextSteps) ? result.nextSteps : [])
+            lines.push(`Next: ${safeTerminalValue(step, '')}`);
+    }
+    else if (document.kind === 'rdap_search') {
         const help = record(result.help);
         const plan = record(result.plan);
         const responseInspection = record(result.responseInspection);
@@ -200,6 +222,17 @@ function formatOfflineEvidenceReview(document) {
         if (result.responseInspection !== null)
             lines.push(`Result ${String(responseInspection.state ?? 'invalid').replaceAll('_', ' ')}`);
     }
+    else if (document.kind === 'geoip' && result.schema === LOCAL_MMDB_REVIEW_SCHEMA && result.version === LOCAL_MMDB_REVIEW_VERSION) {
+        const database = record(result.database), metadata = record(database.metadata), binaryFormat = record(metadata.binaryFormat);
+        const freshness = record(result.freshness), policy = record(freshness.policy), source = record(result.source), match = record(result.match);
+        lines.push(`Outcome ${safeTerminalValue(result.reason, 'unknown').replaceAll('_', ' ')}`, `Coverage ${safeTerminalValue(result.completeness, 'unavailable')}`, `Database SHA-256 ${safeTerminalValue(database.sha256, 'unavailable')}`, `Database bytes ${safeTerminalValue(database.byteLength, 'unavailable')}`, `Intrinsic type ${safeTerminalValue(metadata.databaseType, 'unavailable')}`, `Built ${safeTerminalValue(metadata.builtAt, 'unavailable')}`, `Binary format ${safeTerminalValue(binaryFormat.major, '?')}.${safeTerminalValue(binaryFormat.minor, '?')} · IP version ${safeTerminalValue(metadata.ipVersion, '?')}`, `Freshness ${safeTerminalValue(freshness.state, 'unknown')} · checked ${safeTerminalValue(freshness.checkedAt, 'unknown')}`, `Age policy ${safeTerminalValue(policy.maxAgeDays, '?')} days · ${safeTerminalValue(policy.rationale, '')}`, `Declared source ${safeTerminalValue(source.label, 'unknown')} · version ${safeTerminalValue(source.version, 'unknown')} · licence ${safeTerminalValue(source.license, 'unknown')}`);
+        if (result.match !== null) {
+            lines.push(`Matched network ${safeTerminalValue(match.network, 'unknown')}`, `Country ${safeTerminalValue(match.countryCode, 'unknown')} · region ${safeTerminalValue(match.region, 'unknown')} · city ${safeTerminalValue(match.city, 'unknown')}`, `ASN ${safeTerminalValue(match.asn, 'unknown')} · network label ${safeTerminalValue(match.asName, 'unknown')}`);
+        }
+    }
+    else if (document.kind === 'geoip') {
+        lines.push('Intrinsic MMDB freshness is not assessed by this result. A version-2 MMDB query can assess a selected local database against an explicit age policy.');
+    }
     else if (document.kind === 'zone_intent') {
         const desired = record(result.desired);
         lines.push(`Desired ${listLength(desired.records)}`);

package/cli/posture.mjs

@@ -1,4 +1,4 @@
-import { CliUsageError } from "./arguments.mjs";
+import { CliUsageError } from "./errors.mjs";
 const MAX_POSTURE_SELECTORS = 10;
 function normalizePostureSelectors(raw, normalizeSelectors) {
     if (raw === null || raw === undefined || raw === '')

package/cli/registry-fixture-scaffold.mjs

@@ -14,7 +14,7 @@ export function buildRegistryFixtureScaffold(profileIdInput, suffixInput, scenar
         throw new TypeError('Scenario must be registered, not_found, or inconclusive.');
     const matchingProfiles = registryCompatibilityMatrix().filter((item) => item.id === profileId);
     if (!matchingProfiles.length)
-        throw new TypeError('The capability profile is not present in the registry catalogue.');
+        throw new TypeError('The capability profile is not present in the registry catalogue. Run registry-support <suffix> --json to find its profile ID.');
     const profile = matchingProfiles.find((item) => item.suffixes.includes(suffix));
     if (!profile)
         throw new TypeError(`The capability profile does not cover .${suffix}.`);

package/cli/retained-artifact-diff.mjs

@@ -9,6 +9,7 @@ import { parseBoundedJsonObject } from "./bounded-json.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { buildCliLookupDiff, formatCliLookupDiff } from "./lookup-diff.mjs";
 import { SAVED_LOOKUP_SCHEMA } from "./saved-lookup.mjs";
+import { safeTerminalValue } from "./formatters/terminal-shared.mjs";
 import { CLI_COMPARISON_LEDGER_SCHEMA, CLI_COMPARISON_LEDGER_VERSION, MAX_RETAINED_ARTIFACT_DIFF_BYTES, } from "../packages/contracts/offline-comparison.mjs";
 export { CLI_COMPARISON_LEDGER_SCHEMA, CLI_COMPARISON_LEDGER_VERSION, MAX_RETAINED_ARTIFACT_DIFF_BYTES };
 const BULK_ROOT_KEYS = new Set(['schema', 'version', 'generatedAt', 'sessions', 'limitations']);
@@ -354,22 +355,22 @@ export function formatCliRetainedArtifactDiff(document) {
         return formatCliLookupDiff(document);
     const lines = [
         'Retained artifact comparison ledger',
-        `Family           ${document.artifactFamily.replaceAll('_', ' ')}`,
-        `Left             ${document.left.label} · ${document.left.id}`,
-        `Right            ${document.right.label} · ${document.right.id}`,
+        `Family           ${safeTerminalValue(document.artifactFamily).replaceAll('_', ' ')}`,
+        `Left             ${safeTerminalValue(document.left.label)} · ${safeTerminalValue(document.left.id)}`,
+        `Right            ${safeTerminalValue(document.right.label)} · ${safeTerminalValue(document.right.id)}`,
         `Candidates       ${document.index.counts.retained}`,
         `Exact rows       ${document.details.rows.length} of ${document.details.totalRows}`,
         '',
     ];
     for (const row of document.details.rows) {
-        lines.push(`${row.entityId} · ${row.field} [${row.state.replaceAll('_', ' ')}]`);
-        lines.push(`  Earlier: ${row.earlier.value ?? 'not retained'} · ${row.earlier.sourceState}`);
-        lines.push(`  Later:   ${row.later.value ?? 'not retained'} · ${row.later.sourceState}`);
+        lines.push(`${safeTerminalValue(row.entityId)} · ${safeTerminalValue(row.field)} [${safeTerminalValue(row.state).replaceAll('_', ' ')}]`);
+        lines.push(`  Earlier: ${safeTerminalValue(row.earlier.value, 'not retained')} · ${safeTerminalValue(row.earlier.sourceState)}`);
+        lines.push(`  Later:   ${safeTerminalValue(row.later.value, 'not retained')} · ${safeTerminalValue(row.later.sourceState)}`);
     }
     if (document.details.omissions.detailRows)
         lines.push(`Omitted exact rows: ${document.details.omissions.detailRows}`);
     lines.push('', 'Limitations:');
     for (const limitation of document.limitations)
-        lines.push(`  - ${limitation}`);
+        lines.push(`  - ${safeTerminalValue(limitation)}`);
     return `${lines.join('\n')}\n`;
 }

package/cli/review-arguments.mjs

@@ -0,0 +1,131 @@
+import {} from "./command-argument-grammar.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { CLI_CASE_OPERATIONS, CLI_INDICATOR_OPERATIONS } from "./command-reference.mjs";
+import { terminalOptions, jsonOutput, parseTwoFileComparisonArguments, singleInputAction, } from "./argument-values.mjs";
+function parseVerifyArtifactArguments(parsed) {
+    if (parsed.hasOption('--folder') && parsed.positionalValue('source'))
+        throw new CliUsageError('--folder selects its own input; do not also supply a file or stdin marker.');
+    return {
+        action: 'verify-artifact',
+        source: parsed.positionalValue('source'),
+        passphraseSource: parsed.optionValue('--passphrase-file'),
+        manifestSource: parsed.optionValue('--manifest'),
+        manifestEntryId: parsed.optionValue('--manifest-entry'),
+        ...(parsed.hasOption('--package') ? { package: true } : {}),
+        ...(parsed.hasOption('--bagit') ? { bagit: true } : {}),
+        ...(parsed.optionValue('--folder') ? { folder: parsed.optionValue('--folder') } : {}),
+        output: jsonOutput(parsed),
+        strictExit: parsed.hasOption('--strict-exit'),
+        ...terminalOptions(parsed),
+    };
+}
+function parseCaseArguments(parsed) {
+    const operation = parsed.positionalValue('operation');
+    const source = parsed.positionalValue('source');
+    const domain = parsed.optionValue('--domain');
+    const caseId = parsed.optionValue('--case-id');
+    const title = parsed.optionValue('--title');
+    const newIncident = parsed.hasOption('--new-incident');
+    const text = parsed.optionValue('--text');
+    const noteSource = parsed.optionValue('--note-file');
+    const inputSource = parsed.optionValue('--input');
+    const expectedFileDigest = parsed.optionValue('--expect-file-digest');
+    if (source === '-' || inputSource === '-' || noteSource === '-')
+        throw new CliUsageError('Case operations require selected files, not stdin.');
+    if (operation !== 'open' && !source)
+        throw new CliUsageError(`${operation} requires a Case file.`);
+    if (operation !== 'show' && !parsed.hasOption('--output'))
+        throw new CliUsageError('Case mutations require --output; nothing was changed.');
+    if (operation === 'open' && !domain)
+        throw new CliUsageError('case open requires --domain.');
+    if (operation !== 'open' && (title || newIncident))
+        throw new CliUsageError('--title and --new-incident belong to case open.');
+    if (newIncident && (!title || caseId))
+        throw new CliUsageError('--new-incident requires a distinguishing --title and cannot select an existing --case-id.');
+    if (operation === 'note' ? text === null && !noteSource : text !== null || noteSource !== null) {
+        throw new CliUsageError('Only case note accepts and requires --text or --note-file.');
+    }
+    if (['pin', 'link', 'withdraw-link', 'assess', 'recheck'].includes(operation)
+        ? !inputSource
+        : inputSource !== null) {
+        throw new CliUsageError('Only case pin, link, withdraw-link, assess and recheck accept and require --input.');
+    }
+    if (expectedFileDigest !== null && (!source || !/^sha256:[a-f0-9]{64}$/u.test(expectedFileDigest))) {
+        throw new CliUsageError('--expect-file-digest requires a source file and sha256:<64 lowercase hexadecimal characters>.');
+    }
+    return {
+        action: 'case',
+        operation,
+        source,
+        caseId,
+        domain,
+        title,
+        newIncident,
+        text,
+        noteSource,
+        inputSource,
+        expectedFileDigest,
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    };
+}
+export const REVIEW_ARGUMENT_PARSERS = Object.freeze({
+    'verify-artifact': parseVerifyArtifactArguments,
+    'interchange-report': (parsed) => ({
+        action: 'interchange-report',
+        source: parsed.positionalValue('source'),
+        passphraseSource: parsed.optionValue('--passphrase-file'),
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    }),
+    'source-report': (parsed) => singleInputAction('source-report', parsed),
+    compare: (parsed) => singleInputAction('compare', parsed),
+    'page-compare': (parsed) => ({
+        action: 'page-compare',
+        ...parseTwoFileComparisonArguments(parsed, 'page-compare'),
+    }),
+    'mail-review': (parsed) => singleInputAction('mail-review', parsed),
+    'mail-headers': (parsed) => ({
+        ...singleInputAction('mail-headers', parsed),
+        ...(parsed.hasOption('--trusted-auth-header')
+            ? { trustedAuthHeaders: parsed.optionValues('--trusted-auth-header') }
+            : {}),
+    }),
+    intake: (parsed) => ({
+        action: 'intake',
+        kind: parsed.positionalValue('kind'),
+        reportedActions: parsed.optionValues('--reported-action'),
+        ...(parsed.hasOption('--trusted-auth-header')
+            ? { trustedAuthHeaders: parsed.optionValues('--trusted-auth-header') }
+            : {}),
+        source: parsed.positionalValue('source'),
+        output: jsonOutput(parsed),
+        strictExit: parsed.hasOption('--strict-exit'),
+        ...terminalOptions(parsed),
+    }),
+    'review-evidence': (parsed) => ({
+        action: 'review-evidence',
+        source: parsed.positionalValue('source'),
+        mmdbSource: parsed.optionValue('--mmdb'),
+        output: jsonOutput(parsed),
+        strictExit: parsed.hasOption('--strict-exit'),
+        ...terminalOptions(parsed),
+    }),
+    brief: (parsed) => singleInputAction('brief', parsed),
+    case: parseCaseArguments,
+    'indicator-set': (parsed) => ({
+        action: 'indicator-set',
+        operation: parsed.positionalValue('operation'),
+        source: parsed.positionalValue('source'),
+        output: jsonOutput(parsed),
+        ...terminalOptions(parsed),
+    }),
+    'case-pack': (parsed) => ({
+        action: 'case-pack',
+        source: parsed.positionalValue('source'),
+        output: jsonOutput(parsed),
+        audience: parsed.optionValue('--audience'),
+        reviewed: true,
+        ...terminalOptions(parsed),
+    }),
+});