@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/cli/domain-control-observations.mjs

@@ -1,12 +1,21 @@
 import { Buffer } from 'node:buffer';
-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 { latestObservationCohort } from "../packages/evidence/latest-observations.mjs";
+import { canonicalCaaRecord, canonicalDsRecord, canonicalMxRecord, canonicalDomainControlRecords, canonicalPostureRecords } from "../packages/evidence/domain-control-runtime.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { postureTransferRestriction } from "../packages/evidence/domain-posture-context.mjs";
+import { MAX_DOMAIN_CONTROL_INPUT_RECORDS, PUBLIC_DOMAIN_CONTROL_MANIFEST_VERSION } from "../packages/contracts/domain-control-manifest.mjs";
+import { scanBoundedJson, } from "../packages/analysis/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, PUBLIC_CLI_DOMAIN_CONTROL_REVIEW_VERSION, SUPPORTED_CLI_DOMAIN_CONTROL_REVIEW_VERSIONS, 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 { MAX_FLIGHT_RECORDER_VALUES, mergeConcurrentDomainControlFields, } 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 { 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);
+export const DOMAIN_CONTROL_REVIEW_SOURCE_FIELDS = Object.freeze({
+    registry_nameservers: 'nameservers', delegation_ds: 'ds', mail_exchangers: 'mx', caa_policy: 'caa',
+    tls_certificate: 'tlsIssuer', tls_public_key: 'tlsSpkiSha256', registrar_lock: 'registrarLock',
+});
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
@@ -21,116 +30,147 @@ function state(value) {
     return 'unavailable';
 }
 function text(value, maximum = 500) {
-    if (typeof value !== 'string')
+    if (typeof value !== 'string' || value.length > maximum || /[\u0000-\u001f\u007f]/u.test(value))
         return null;
-    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum);
+    const normalized = value.trim();
     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 sourceClock(...values) {
+    const declared = values.filter((value) => value !== undefined && value !== null);
+    const times = declared.map(normalizeExplicitIsoTimestamp);
+    return times.length && times.every((time) => time !== null && time === times[0]) ? times[0] : null;
+}
+function sourceState(value) {
+    const result = state(value.status);
+    return result === 'observed' && (value.complete === false || value.truncated === true) ? 'partial' : result;
+}
+function dnsRecordState(dns, name) {
+    const query = record(record(dns.diagnostics)[name]);
+    if (!Object.keys(query).length)
+        return sourceState(dns);
+    const values = record(dns.records)[name];
+    const contradictoryAbsence = query.status === 'not_found' && Array.isArray(values) && values.length > 0;
+    if ((query.status === 'success' || query.status === 'not_found') && query.truncated === false && query.discarded === 0
+        && !contradictoryAbsence && (query.error === undefined || query.error === null))
+        return 'observed';
+    return state(query.status) === 'observed' || query.status === 'not_found' ? 'partial' : state(query.status);
+}
+function field(id, source, sourceState, values, observedAt) {
+    return Object.freeze({ id, source, state: sourceState, values: Object.freeze([...values].sort()), observedAt });
+}
+function recordField(id, source, sourceState, input, normalize, observedAt) {
+    const rows = Array.isArray(input) ? input.slice(0, MAX_DOMAIN_CONTROL_INPUT_RECORDS) : [];
+    const values = new Set();
+    let invalid = Array.isArray(input) || (input === undefined && sourceState !== 'observed') ? 0 : 1;
+    for (const row of rows) {
+        let value = '';
+        try {
+            value = normalize(row);
+        }
+        catch (error) {
+            if (!(error instanceof TypeError))
+                throw error;
+        }
+        if (value)
+            values.add(value);
+        else
+            invalid += 1;
+    }
+    const sorted = [...values].sort();
+    const omitted = Math.max(0, (Array.isArray(input) ? input.length : 0) - rows.length)
+        + Math.max(0, sorted.length - MAX_FLIGHT_RECORDER_VALUES);
+    return field(id, invalid || omitted ? `${source} (${invalid} invalid; ${omitted} omitted records)` : source, sourceState === 'observed' && (invalid || omitted) ? 'partial' : sourceState, sorted.slice(0, MAX_FLIGHT_RECORDER_VALUES), observedAt);
 }
 function diagnostic(document, key) {
-    return state(record(document.diagnostics)[key] && record(record(document.diagnostics)[key]).status);
+    return sourceState(record(record(document.diagnostics)[key]));
+}
+function registryClock(document, key) {
+    const detail = record(record(document.diagnostics)[key]);
+    const publication = record(document[key]);
+    const named = key === 'rdap' ? 'fetchedAt' : 'queriedAt';
+    return sourceClock(detail.observedAt, detail[named], publication.observedAt, publication[named]);
 }
 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 };
+        return { parsed: rdap, source: 'Registry RDAP', sourceState: rdapState, observedAt: registryClock(document, 'rdap') };
     const whois = record(record(document.whois).parsed);
-    return { parsed: whois, source: 'WHOIS', sourceState: whoisState };
+    return { parsed: whois, source: 'WHOIS', sourceState: whoisState, observedAt: registryClock(document, 'whois') };
 }
 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'];
+    const input = parsed.statuses ?? parsed.status;
+    const statuses = Array.isArray(input) ? canonicalPostureRecords('registration_lock', input) : null;
+    return statuses ? postureTransferRestriction(statuses) : null;
 }
 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),
+        text(identity.bodySha256, 64),
+        text(identity.faviconHash, 128),
+        text(identity.title, 240),
     ].filter((item) => Boolean(item));
-    return components.length ? [components.join(' | ').toLowerCase()] : [];
+    return components.length ? [components.join(' | ')] : [];
 }
 export function domainControlObservationFromSavedLookup(document) {
     const availability = record(document.availability);
     const dns = record(availability.dns);
     const dnsRecords = record(dns.records);
+    const dnsAt = sourceClock(dns.observedAt, dns.checkedAt);
     const delegation = record(dns.delegation);
     const delegationRecords = record(delegation.records);
     const tls = record(availability.tls);
-    const tlsState = state(tls.status);
+    const tlsState = sourceState(tls);
+    const tlsAt = sourceClock(tls.observedAt, tls.checkedAt);
     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 rdapAt = registryClock(document, 'rdap');
+    const scalar = (id, source, status, value, observedAt, maximum = 500) => recordField(id, source, status, [value], (item) => text(item, maximum) ?? '', observedAt);
+    const hostname = (value) => canonicalDomainControlRecords([value], 'nameservers')[0] ?? '';
+    const identity = record(availability.pageIdentity);
+    const identityValues = pageIdentityValue(availability);
     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), list(delegationRecords.ds, dsValue)),
-        field('mail_exchangers', 'DNS', dnsState, list(dnsRecords.mx, mxValue)),
-        field('caa_policy', 'DNS', dnsState, list(record(dns.caaPolicy).records ?? dnsRecords.caa, caaValue)),
-        field('tls_certificate', 'TLS', tlsState, list([certificate.fingerprintSha256 ?? tls.fingerprintSha256], (item) => text(item, 128))),
-        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)),
+        scalar('registrar', registry.source, registry.sourceState, record(registry.parsed.registrar).name ?? registry.parsed.registrar, registry.observedAt, 300),
+        scalar('registrar_lock', registry.source, registry.sourceState, lockValue(registry.parsed), registry.observedAt, 20),
+        scalar('registry_dnssec', 'Registry RDAP', rdapState, rdapParsed.dnssec, rdapAt, 80),
+        recordField('registry_nameservers', 'Registry RDAP', rdapState, rdapParsed.nameservers, hostname, rdapAt),
+        recordField('whois_nameservers', 'WHOIS', diagnostic(document, 'whois'), record(record(document.whois).parsed).nameservers, hostname, registryClock(document, 'whois')),
+        recordField('delegated_nameservers', 'DNS NS', dnsRecordState(dns, 'ns'), dnsRecords.ns, hostname, dnsAt),
+        recordField('delegation_ds', 'DNS delegation', Object.hasOwn(delegationRecords, 'ds') ? sourceState(delegation) : 'unsupported', delegationRecords.ds, canonicalDsRecord, sourceClock(delegation.observedAt)),
+        recordField('mail_exchangers', 'DNS MX', dnsRecordState(dns, 'mx'), dnsRecords.mx, canonicalMxRecord, dnsAt),
+        recordField('caa_policy', 'DNS CAA', dnsRecordState(dns, 'caa'), dnsRecords.caa, canonicalCaaRecord, dnsAt),
+        scalar('tls_certificate', 'TLS', tlsState, certificate.fingerprintSha256 ?? tls.fingerprintSha256, tlsAt, 128),
+        scalar('tls_public_key', 'TLS', tlsState, publicKey.fingerprintSha256 ?? tls.spkiSha256, tlsAt, 128),
+        scalar('http_origin', 'HTTP', sourceState(http), http.finalOrigin, sourceClock(http.observedAt, http.checkedAt)),
+        field('page_identity', 'Static page identity', sourceState(identity) === 'observed' && !identityValues.length ? 'partial' : sourceState(identity), identityValues, sourceClock(identity.observedAt)),
     ];
     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))),
+        domain: document.registrableDomain, capturedAt: document.generatedAt, collectionDepth: document.mode,
+        fields: Object.freeze(fields.map((item) => item.state === 'observed' && item.observedAt !== null
+            && Date.parse(item.observedAt) > Date.parse(document.generatedAt) ? Object.freeze({ ...item, state: 'partial' }) : item)),
+    });
+}
+function reviewFields(document, observation) {
+    return observation.fields.map((candidate) => {
+        if (candidate.id !== 'tls_certificate')
+            return candidate;
+        const issuer = record(record(record(document.availability).tls).certificate).issuer;
+        const value = record(issuer);
+        const commonNames = Array.isArray(value.commonNames) ? value.commonNames : [];
+        const organisationNames = Array.isArray(value.organizationNames) ? value.organizationNames : [];
+        return recordField(candidate.id, candidate.source, candidate.state, [commonNames[0] ?? organisationNames[0] ?? issuer], (item) => text(item, 300) ?? '', candidate.observedAt);
     });
 }
 export function buildCliDomainControlReview(inputText, generatedAt = new Date().toISOString()) {
+    const reviewTime = normalizeExplicitIsoTimestamp(generatedAt);
+    if (!reviewTime)
+        throw new CliUsageError('Domain-control review time must include a valid explicit timezone.');
+    generatedAt = reviewTime;
     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.`);
     }
@@ -161,7 +201,7 @@ export function buildCliDomainControlReview(inputText, generatedAt = new Date().
     }
     const input = record(parsed);
     if (input.schema !== CLI_DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA
-        || input.version !== CLI_DOMAIN_CONTROL_REVIEW_VERSION
+        || !SUPPORTED_CLI_DOMAIN_CONTROL_REVIEW_VERSIONS.some((version) => version === input.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}.`);
     }
@@ -173,42 +213,49 @@ export function buildCliDomainControlReview(inputText, generatedAt = new Date().
         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);
+    if (input.version === PUBLIC_CLI_DOMAIN_CONTROL_REVIEW_VERSION && manifest.version !== PUBLIC_DOMAIN_CONTROL_MANIFEST_VERSION) {
+        throw new CliUsageError(`Public domain-control review input version ${PUBLIC_CLI_DOMAIN_CONTROL_REVIEW_VERSION} requires manifest version ${PUBLIC_DOMAIN_CONTROL_MANIFEST_VERSION}.`);
+    }
     const lookups = input.lookups.map((item, index) => parseSavedLookupDocument(JSON.stringify(item), { label: `Lookup ${index + 1}` }));
-    const latest = new Map();
+    const byDomain = 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 group = byDomain.get(lookup.registrableDomain) ?? [];
+        group.push(lookup);
+        byDomain.set(lookup.registrableDomain, group);
     }
-    const observations = [...latest.values()].map(domainControlObservationFromSavedLookup);
+    let ignoredHistoricalLookups = 0;
+    const selected = [...byDomain.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([domain, documents]) => {
+        const cohort = latestObservationCohort(documents, (document) => document.generatedAt);
+        ignoredHistoricalLookups += cohort.superseded;
+        const captures = cohort.latest.map((document) => ({ document, observation: domainControlObservationFromSavedLookup(document) }));
+        const first = captures[0];
+        if (!first || !cohort.observedAt || cohort.undated.length)
+            throw new CliUsageError('Saved Lookup observation times could not be ordered.');
+        const mergedFields = mergeConcurrentDomainControlFields(captures.map((capture) => capture.observation.fields));
+        const futureCapture = Date.parse(cohort.observedAt) > Date.parse(generatedAt);
+        const observation = Object.freeze({
+            domain,
+            capturedAt: cohort.observedAt,
+            collectionDepth: captures.every((capture) => capture.observation.collectionDepth === first.observation.collectionDepth)
+                ? first.observation.collectionDepth : 'unknown',
+            fields: futureCapture ? mergedFields.map((field) => ({ ...field, state: 'partial' })) : mergedFields,
+        });
+        const fields = mergeConcurrentDomainControlFields(captures.map((capture) => reviewFields(capture.document, capture.observation)));
+        return { observation, reviewFields: futureCapture || observation.collectionDepth === 'unknown'
+                ? fields.map((field) => ({ ...field, state: 'partial' })) : fields };
+    });
+    const observations = selected.map((item) => item.observation);
     const review = reviewDomainControlManifest({
         schema: DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA,
         version: DOMAIN_CONTROL_REVIEW_VERSION,
         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];
+        observations: selected.map(({ observation, reviewFields: fields }) => ({
+            domain: observation.domain,
+            fields: Object.fromEntries(fields.flatMap((candidate) => {
+                const target = DOMAIN_CONTROL_REVIEW_SOURCE_FIELDS[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 }]];
+                return [[target, { state: candidate.state, values: candidate.values, source: candidate.source, observedAt: candidate.observedAt }]];
             })),
         })),
     }, generatedAt);
@@ -221,7 +268,7 @@ export function buildCliDomainControlReview(inputText, generatedAt = new Date().
         input: Object.freeze({
             lookupsReceived: lookups.length,
             latestDomainObservations: observations.length,
-            ignoredHistoricalLookups: lookups.length - observations.length,
+            ignoredHistoricalLookups,
         }),
         limitations: CLI_DOMAIN_CONTROL_REVIEW_LIMITATIONS,
     });
@@ -242,6 +289,7 @@ export function formatCliDomainControlReview(document) {
         `Domains     ${review.domains.length}`,
         `Lookups     ${document.input.lookupsReceived}`,
         `Drift       ${review.counts.drift ?? 0}`,
+        `Due         ${review.counts.due ?? 0}`,
         `Incomplete  ${(review.counts.partial ?? 0) + (review.counts.unavailable ?? 0) + (review.counts.unsupported ?? 0)}`,
         '',
         ...review.domains.map((item) => `${item.domain}  ${item.state}`),

package/cli/errors.mjs

@@ -1,10 +1,14 @@
+import { stripVTControlCharacters } from 'node:util';
+import { hasUnsafeCliText } from "../packages/contracts/cli-grammar.mjs";
 const MAX_CLI_ERROR_MESSAGE_LENGTH = 300;
-const CLI_DEFAULT_IGNORABLE_RE = /\p{Default_Ignorable_Code_Point}/u;
+const MAX_CLI_DIAGNOSTIC_BYTES = 4_096;
 const CLI_DEFAULT_IGNORABLE_GLOBAL_RE = /\p{Default_Ignorable_Code_Point}/gu;
 class CliUsageError extends Error {
-    constructor(message) {
+    reason;
+    constructor(message, reason = 'invalid_input') {
         super(message);
         this.name = 'CliUsageError';
+        this.reason = reason;
     }
 }
 function errorMessage(error) {
@@ -20,13 +24,40 @@ function boundedCliErrorMessage(error, fallback = 'Unexpected command failure')
         .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);
+// A transient stderr preview, never a checkpoint field. Bound before collecting
+// and redact request URLs and credential-shaped fields before shortening text.
+function createCliDiagnosticOutput() {
+    const chunks = [];
+    let remaining = MAX_CLI_DIAGNOSTIC_BYTES;
+    return Object.freeze({
+        stream: {
+            isTTY: false,
+            columns: 80,
+            write(chunk) {
+                if (remaining > 0 && chunk.length > 0) {
+                    const bytes = Buffer.from(chunk.slice(0, remaining), 'utf8').subarray(0, remaining);
+                    chunks.push(bytes.toString('utf8'));
+                    remaining -= bytes.byteLength;
+                }
+                return true;
+            },
+        },
+        value() {
+            const source = stripVTControlCharacters(chunks.join('')).replace(CLI_DEFAULT_IGNORABLE_GLOBAL_RE, '');
+            if (!source.trim())
+                return '';
+            const redacted = source
+                .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"']*/giu, '[URL omitted]')
+                .replace(/\b(authorization|cookie|password|passphrase|token|secret|api[-_ ]?key)\s*[:=]\s*(?:"[^"]*(?:"|$)|'[^']*(?:'|$)|[^\r\n,;]*)/giu, '$1=[omitted]')
+                .replace(/\b(?:bearer|basic)\s+[^\s,;]+/giu, '[credential omitted]');
+            return boundedCliErrorMessage(redacted);
+        },
+    });
 }
 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.`);
+    return new CliUsageError(`${safeLabel} could not be read as a bounded regular file.`, 'input_unavailable');
 }
-export { CliUsageError, MAX_CLI_ERROR_MESSAGE_LENGTH, boundedCliErrorMessage, boundedCliInputError, hasUnsafeCliText, };
+export { CliUsageError, MAX_CLI_ERROR_MESSAGE_LENGTH, boundedCliErrorMessage, boundedCliInputError, createCliDiagnosticOutput, hasUnsafeCliText, };

package/cli/evidence-arguments.mjs

@@ -0,0 +1,46 @@
+import {} from "./command-argument-grammar.mjs";
+import { CliUsageError } from "./errors.mjs";
+import { parseArchiveContentDigest } from "./archive-content-digest.mjs";
+import { terminalOptions } from "./argument-values.mjs";
+function parseInspectArchiveArguments(parsed) {
+    const expectedContentDigest = parsed.optionValue('--expect-content-digest');
+    try {
+        parseArchiveContentDigest(expectedContentDigest);
+    }
+    catch {
+        throw new CliUsageError('--expect-content-digest requires sha256:<64 lowercase hex> or sorted-json-v2:sha256:<64 lowercase hex>.');
+    }
+    return {
+        action: 'inspect-archive',
+        source: parsed.positionalValue('source'),
+        passphraseSource: parsed.optionValue('--passphrase-file'),
+        search: parsed.optionValue('--search'),
+        reveal: parsed.hasOption('--reveal'),
+        requireMatch: parsed.hasOption('--require-match'),
+        expectedContentDigest,
+        output: parsed.hasOption('--json') ? 'json' : 'terminal',
+        ...terminalOptions(parsed),
+    };
+}
+function parseSignArtifactArguments(parsed) {
+    return {
+        action: 'sign-artifact',
+        source: parsed.positionalValue('source'),
+        privateKeySource: parsed.optionValue('--private-key-file'),
+    };
+}
+function parseVerifySignatureArguments(parsed) {
+    return {
+        action: 'verify-signature',
+        source: parsed.positionalValue('source'),
+        publicKeySource: parsed.optionValue('--public-key-file'),
+        trustStoreSource: parsed.optionValue('--trust-store-file'),
+        output: parsed.hasOption('--json') ? 'json' : 'terminal',
+        ...terminalOptions(parsed),
+    };
+}
+export const EVIDENCE_ARGUMENT_PARSERS = Object.freeze({
+    'inspect-archive': parseInspectArchiveArguments,
+    'sign-artifact': parseSignArtifactArguments,
+    'verify-signature': parseVerifySignatureArguments,
+});

package/cli/evidence-command-definitions.mjs

@@ -0,0 +1,69 @@
+import { WORKSPACE_ARCHIVE_VERSION } from "../packages/contracts/case-portability.mjs";
+import { LEGACY_WORKSPACE_ARCHIVE_DESCRIPTION, LEGACY_WORKSPACE_ARCHIVE_SCOPE, OPTIONAL_FILE_POSITIONAL, constraint, EMPTY_CONSTRAINTS, commandSeed } from "./command-definition.mjs";
+export const EVIDENCE_COMMAND_DEFINITIONS = Object.freeze({
+    "inspect-archive": commandSeed({
+        reference: {
+            description: `Summarise or search one current version-${WORKSPACE_ARCHIVE_VERSION} workspace archive, with exact ${LEGACY_WORKSPACE_ARCHIVE_DESCRIPTION} support and redacted output by default.`,
+            example: 'whoisleuth inspect-archive workspace.json --search example.test --json',
+            boundary: 'Exact values require --reveal. New content comparisons use the reported sorted-json-v2:sha256 identity with --expect-content-digest; bare sha256 hashes retain their legacy locale-sensitive meaning. Retired and future archives are rejected. The archive is read locally and is never uploaded.',
+        },
+        collection: { scope: `Reads one selected bounded workspace archive v${WORKSPACE_ARCHIVE_VERSION}, retains exact ${LEGACY_WORKSPACE_ARCHIVE_SCOPE} compatibility, and redacts output by default.` },
+        summary: 'Inspect an archive locally',
+        options: ['--passphrase-file', '--search', '--require-match', '--reveal', '--expect-content-digest', '--json', '--quiet', '--no-color'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'requires_all', option: '--reveal', requiredOptions: ['--search'] }),
+            constraint({ kind: 'requires_all', option: '--require-match', requiredOptions: ['--search'] }),
+        ]),
+        handlerOwner: 'evidence',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.workspace-archive-inspection']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "sign-artifact": commandSeed({
+        reference: {
+            description: 'Sign one reviewed response packet or supported manifest with a local private key.',
+            example: 'whoisleuth sign-artifact packet.json --private-key-file analyst-private.pem',
+            boundary: 'The command never creates, stores, or transmits keys. Key custody and signer identity remain the operator\'s responsibility.',
+        },
+        collection: { scope: 'Reads one selected artefact and one local private key without transmitting either.' },
+        summary: 'Sign a reviewed artefact locally',
+        options: ['--private-key-file'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'required', options: ['--private-key-file'] }),
+        ]),
+        handlerOwner: 'evidence',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.signed-evidence-package']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    "verify-signature": commandSeed({
+        reference: {
+            description: 'Verify one signed package and report embedded-artefact assurance separately. --trust-store-file also checks an explicit local fingerprint policy and emits a signer-trust report; unknown, retired, revoked or future-reviewed entries exit 4.',
+            example: 'whoisleuth verify-signature packet.signed.json --trust-store-file trust.json --json',
+            boundary: 'A valid signature proves package consistency for the embedded key, not identity, authority or evidence accuracy. With --trust-store-file, unknown, retired, revoked or future-reviewed entries exit 4 even if --public-key-file matches. Replacement fingerprints need their own trusted entry; no signing date overrides current revocation.',
+        },
+        collection: { scope: 'Reads one selected signed package, optional local public key and explicit fingerprint trust file. No automatic trust discovery or network requests.' },
+        summary: 'Verify a signed evidence package',
+        options: ['--public-key-file', '--trust-store-file', '--json', '--quiet', '--no-color'],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: EMPTY_CONSTRAINTS,
+        handlerOwner: 'evidence',
+        networkEffect: 'offline',
+        common: false,
+        schemaIdentifiers: Object.freeze(['whoisleuth.evidence-signature-verification', 'whoisleuth.evidence-signer-trust-store', 'whoisleuth.evidence-signer-trust-report']),
+        primaryArtefacts: Object.freeze([]),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/evidence-command-runner.mjs

@@ -1,15 +1,15 @@
 import { MAX_OFFLINE_ARTIFACT_BYTES, MAX_OFFLINE_PASSPHRASE_FILE_BYTES, } from "./artifact-verify.mjs";
 import { formatArchiveInspection, inspectWorkspaceArchive, } from "./archive-inspect.mjs";
 import { MAX_SIGNING_KEY_FILE_BYTES, formatEvidenceSignatureVerification, signEvidencePackage, verifyEvidencePackageSignature, } from "./evidence-signing.mjs";
+import { commandHasOwner } from "./command-reference.mjs";
 import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { formatJsonDocument } from "./formatters/json.mjs";
 import { readCliTextInput } from "./input.mjs";
+import { assessEvidenceSignerTrust, formatSignerTrustReport, MAX_SIGNER_TRUST_STORE_BYTES } from "./signer-trust.mjs";
 import { runDiscriminatedCommandHandler } from "./discriminated-command-handlers.mjs";
 export function isEvidenceCommand(args) {
-    return args.action === 'inspect-archive'
-        || args.action === 'sign-artifact'
-        || args.action === 'verify-signature';
+    return commandHasOwner(args.action, 'evidence');
 }
 export function evidenceCommandFailureLabel(action) {
     if (action === 'inspect-archive')
@@ -18,12 +18,12 @@ export function evidenceCommandFailureLabel(action) {
         return 'Evidence signing';
     return 'Evidence signature verification';
 }
-async function readArtifact(source, label, dependencies) {
+async function readArtifact(source, label, dependencies, maximumBytes = MAX_OFFLINE_ARTIFACT_BYTES) {
     try {
         return dependencies.readArtifactInput
             ? await dependencies.readArtifactInput(source)
             : await readCliTextInput(source, dependencies.stdin, {
-                maximumBytes: MAX_OFFLINE_ARTIFACT_BYTES,
+                maximumBytes,
                 label,
                 ...(dependencies.signal ? { signal: dependencies.signal } : {}),
             });
@@ -105,12 +105,22 @@ async function runVerifySignatureCommand(args, dependencies) {
         ? await readKey(args.publicKeySource, 'Public key file', dependencies.readPublicKeyFile, dependencies)
         : null;
     const report = await verifyEvidencePackageSignature(input, publicKey);
+    let trustReport = null;
+    if (args.trustStoreSource) {
+        const trustRaw = await readArtifact(args.trustStoreSource, 'Signer trust store', dependencies, MAX_SIGNER_TRUST_STORE_BYTES);
+        try {
+            trustReport = assessEvidenceSignerTrust(report, trustRaw, dependencies.now ? dependencies.now() : new Date().toISOString());
+        }
+        catch (error) {
+            throw new CliUsageError(boundedCliErrorMessage(error, 'Invalid signer trust store.'));
+        }
+    }
     if (!args.quiet) {
         dependencies.stdout.write(args.output === 'json'
-            ? formatJsonDocument(report)
-            : formatEvidenceSignatureVerification(report));
+            ? formatJsonDocument(trustReport ?? report)
+            : trustReport ? formatSignerTrustReport(trustReport) : formatEvidenceSignatureVerification(report));
     }
-    return EXIT_CODES.SUCCESS;
+    return trustReport && trustReport.state !== 'trusted' ? EXIT_CODES.PARTIAL_FAILURE : EXIT_CODES.SUCCESS;
 }
 const EVIDENCE_COMMAND_HANDLERS = Object.freeze({
     'inspect-archive': runInspectArchiveCommand,

package/cli/evidence-signing.mjs

@@ -169,7 +169,8 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
     }
     catch { /* Signature validity remains independently reportable. */ }
     let publicKeyMatched = null;
-    if (trustedPublicKeyPem) {
+    const trustedKeySupplied = trustedPublicKeyPem !== undefined && trustedPublicKeyPem !== null;
+    if (trustedKeySupplied) {
         const trustedDer = spkiDer(importPublicKey(trustedPublicKeyPem, 'Trusted public key file'));
         publicKeyMatched = trustedDer.equals(publicDer);
         if (!publicKeyMatched)
@@ -181,7 +182,7 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
         state: 'signature_valid',
         signature: Object.freeze({
             state: 'valid',
-            signerTrust: trustedPublicKeyPem ? 'trusted_key' : 'embedded_key_only',
+            signerTrust: trustedKeySupplied ? 'trusted_key' : 'embedded_key_only',
             signedAt,
             keyIdSha256: signature.keyIdSha256,
             publicKeyMatched,
@@ -216,11 +217,11 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
         ]),
     });
 }
-export function formatEvidenceSignatureVerification(report) {
+export function formatEvidenceSignatureVerification(report, includeStandaloneTrust = true) {
     const lines = [
         'WHOISleuth evidence signature verification',
         `State: ${report.state}`,
-        `Signer trust: ${report.signature.signerTrust}`,
+        ...(includeStandaloneTrust ? [`Signer trust: ${report.signature.signerTrust}`] : []),
         `Artifact: ${report.artifact.kind} · ${report.artifact.schema ?? 'unrecognised'} v${report.artifact.version ?? 'unrecognised'}`,
         `Artifact assurance: ${report.artifact.assurance.state}`,
         `Signed: ${report.signature.signedAt}`,