@slicedearth/whoisleuth-cli 1.36.1 → 1.43.0

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/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,
@@ -92,7 +103,7 @@ export function parseSignArtifactArguments(argv) {
         else if (source === null)
             source = argument;
         else
-            throw new CliUsageError('sign-artifact accepts one optional JSON file. Otherwise pipe one artifact on stdin.');
+            throw new CliUsageError('sign-artifact accepts one optional JSON file. Otherwise pipe one artefact on stdin.');
     }
     if (!privateKeySource)
         throw new CliUsageError('sign-artifact requires --private-key-file.');

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'
@@ -80,9 +81,9 @@ export async function runEvidenceCommand(args, dependencies) {
         return EXIT_CODES.SUCCESS;
     }
     if (args.action === 'sign-artifact') {
-        const input = await readArtifact(args.source, 'Evidence artifact input', dependencies);
+        const input = await readArtifact(args.source, 'Evidence artefact input', dependencies);
         if (!input.trim()) {
-            throw new CliUsageError('sign-artifact requires one reviewed artifact file or an artifact on stdin.');
+            throw new CliUsageError('sign-artifact requires one reviewed artefact file or an artefact on stdin.');
         }
         const privateKey = await readKey(args.privateKeySource, 'Private key file', dependencies.readPrivateKeyFile);
         const signed = await signEvidencePackage(input, privateKey, dependencies.now ? dependencies.now() : new Date().toISOString());

package/cli/evidence-signing.mjs

@@ -100,10 +100,10 @@ function payloadBytes(payload) {
     return Buffer.from(canonicalArtifactJson(payload), 'utf8');
 }
 async function signableArtifact(raw) {
-    const artifact = parseObject(raw, 'Evidence artifact');
+    const artifact = parseObject(raw, 'Evidence artefact');
     const verification = await verifyOfflineArtifact(raw);
-    if (!['case_response_packet', 'signed_review_artifact'].includes(verification.artifact.kind)) {
-        throw new TypeError('Only reviewed response packets and supported review manifests can be signed.');
+    if (!['case_response_packet', 'investigation_capsule', 'signed_review_artifact'].includes(verification.artifact.kind)) {
+        throw new TypeError('Only reviewed response packets, investigation capsules, and supported review manifests can be signed.');
     }
     return { artifact, verification };
 }
@@ -193,7 +193,7 @@ export async function verifyEvidencePackageSignature(raw, trustedPublicKeyPem) {
             trustedPublicKeyPem
                 ? 'The signature and supplied public key match; recipient trust still depends on obtaining that public key through an authenticated channel.'
                 : 'The signature is internally valid for the embedded public key, but signer identity was not authenticated because no trusted public key was supplied.',
-            'The signature authenticates the canonical sorted-JSON content, not the original whitespace, indentation, or object-key order of the serialized file.',
+            'The signature authenticates the canonical sorted-JSON content, not the original whitespace, indentation, or object-key order of the serialised file.',
             'A valid signature proves the canonical package content has not changed since signing; it does not establish that the retained observations or analyst statements are accurate.',
             'WHOISleuth does not generate, store, recover, rotate, or publish signing keys.',
         ]),

package/cli/external-observation-mapping.mjs

@@ -0,0 +1,162 @@
+import { domainToASCII } from 'node:url';
+import { exactKeys, requireBoundedString, requireIsoTimestamp, requireRecord, } from "../lib/bounded-contract-normalizers.mjs";
+import { EXTERNAL_FINDING_CATEGORIES, MAX_EXTERNAL_FINDINGS, MAX_EXTERNAL_FINDINGS_PER_DOMAIN, MAX_EXTERNAL_FINDING_DOMAINS, parseExternalFindingsDocument, } from "../frontend/src/lib/analysis/external-findings-import.js";
+export const EXTERNAL_OBSERVATION_MAPPING_SCHEMA = 'whoisleuth.external-observation-mapping';
+export const EXTERNAL_OBSERVATION_MAPPING_VERSION = 1;
+export const MAX_EXTERNAL_OBSERVATION_MAPPING_BYTES = 4 * 1024 * 1024;
+export const MAX_EXTERNAL_OBSERVATION_RECORDS = 500;
+const ROOT_KEYS = new Set(['schema', 'version', 'source', 'profile', 'records']);
+const SOURCE_KEYS = new Set(['name', 'reference', 'collectedAt']);
+const PROFILE_KEYS = new Set([
+    'id', 'version', 'domainField', 'summaryField', 'observedAtField', 'referenceField',
+    'completenessField', 'category', 'evidenceClass', 'limitations',
+]);
+const PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*){0,7}$/u;
+const FORBIDDEN_PATH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+const COMPLETENESS = new Set(['complete', 'inconclusive', 'partial', 'unknown']);
+const CATEGORIES = new Set(EXTERNAL_FINDING_CATEGORIES);
+function optionalText(value, label, maximum) {
+    if (value === undefined || value === null || value === '')
+        return null;
+    return requireBoundedString(value, label, maximum);
+}
+function path(value, label, optional = false) {
+    if (optional && (value === undefined || value === null || value === ''))
+        return null;
+    const candidate = requireBoundedString(value, label, 200);
+    if (!PATH_RE.test(candidate) || candidate.split('.').some((segment) => FORBIDDEN_PATH_SEGMENTS.has(segment))) {
+        throw new TypeError(`${label} must be a safe bounded dotted field path.`);
+    }
+    return candidate;
+}
+function readPath(value, fieldPath) {
+    let current = value;
+    for (const segment of fieldPath.split('.')) {
+        if (!current || typeof current !== 'object' || Array.isArray(current))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function domain(value, label) {
+    const supplied = requireBoundedString(value, label, 253).trim().toLowerCase().replace(/^\*\./u, '').replace(/\.$/u, '');
+    const ascii = domainToASCII(supplied).toLowerCase();
+    if (!ascii || ascii.length > 253 || !ascii.includes('.') || ascii.split('.').some((part) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(part))) {
+        throw new TypeError(`${label} must resolve to a valid DNS name.`);
+    }
+    return ascii;
+}
+function limitations(value) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.length > 8)
+        throw new TypeError('profile.limitations must contain no more than 8 entries.');
+    return Object.freeze([...new Set(value.map((entry, index) => requireBoundedString(entry, `profile.limitations[${index}]`, 240)))]);
+}
+export function mapExternalObservations(inputRaw) {
+    const input = requireRecord(inputRaw, 'External observation mapping');
+    if (input.schema !== EXTERNAL_OBSERVATION_MAPPING_SCHEMA || input.version !== EXTERNAL_OBSERVATION_MAPPING_VERSION) {
+        throw new TypeError(`External observation mapping must use ${EXTERNAL_OBSERVATION_MAPPING_SCHEMA} version ${EXTERNAL_OBSERVATION_MAPPING_VERSION}.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'External observation mapping');
+    const sourceInput = requireRecord(input.source, 'source');
+    exactKeys(sourceInput, SOURCE_KEYS, 'source');
+    const profileInput = requireRecord(input.profile, 'profile');
+    exactKeys(profileInput, PROFILE_KEYS, 'profile');
+    const profile = Object.freeze({
+        id: requireBoundedString(profileInput.id, 'profile.id', 80),
+        version: Number(profileInput.version),
+        domainField: path(profileInput.domainField, 'profile.domainField'),
+        summaryField: path(profileInput.summaryField, 'profile.summaryField'),
+        observedAtField: path(profileInput.observedAtField, 'profile.observedAtField'),
+        referenceField: path(profileInput.referenceField, 'profile.referenceField', true),
+        completenessField: path(profileInput.completenessField, 'profile.completenessField', true),
+        category: profileInput.category,
+        evidenceClass: profileInput.evidenceClass,
+        limitations: limitations(profileInput.limitations),
+    });
+    if (!Number.isSafeInteger(profile.version) || profile.version < 1 || profile.version > 1_000)
+        throw new TypeError('profile.version is invalid.');
+    if (typeof profile.category !== 'string' || !CATEGORIES.has(profile.category))
+        throw new TypeError('profile.category is unsupported.');
+    if (profile.evidenceClass !== 'deployment_observation' && profile.evidenceClass !== 'provider_report')
+        throw new TypeError('profile.evidenceClass is unsupported.');
+    if (!Array.isArray(input.records) || input.records.length < 1 || input.records.length > MAX_EXTERNAL_OBSERVATION_RECORDS) {
+        throw new TypeError(`records must contain between 1 and ${MAX_EXTERNAL_OBSERVATION_RECORDS} entries.`);
+    }
+    const source = Object.freeze({
+        name: requireBoundedString(sourceInput.name, 'source.name', 80),
+        reference: optionalText(sourceInput.reference, 'source.reference', 500),
+        collectedAt: sourceInput.collectedAt === null || sourceInput.collectedAt === undefined
+            ? null
+            : requireIsoTimestamp(sourceInput.collectedAt, 'source.collectedAt'),
+    });
+    const candidates = input.records.map((record, index) => {
+        const domainValue = domain(readPath(record, profile.domainField), `records[${index}].${profile.domainField}`);
+        const summary = requireBoundedString(readPath(record, profile.summaryField), `records[${index}].${profile.summaryField}`, 900);
+        const observedAt = requireIsoTimestamp(readPath(record, profile.observedAtField), `records[${index}].${profile.observedAtField}`);
+        const completenessValue = profile.completenessField ? readPath(record, profile.completenessField) : 'unknown';
+        if (typeof completenessValue !== 'string' || !COMPLETENESS.has(completenessValue)) {
+            throw new TypeError(`records[${index}] completeness is unsupported.`);
+        }
+        return Object.freeze({
+            domain: domainValue,
+            category: profile.category,
+            evidenceClass: profile.evidenceClass,
+            summary,
+            observedAt,
+            completeness: completenessValue,
+            limitations: profile.limitations,
+            reference: profile.referenceField
+                ? optionalText(readPath(record, profile.referenceField), `records[${index}].${profile.referenceField}`, 500)
+                : null,
+            structuredObservation: null,
+        });
+    }).sort((left, right) => left.domain.localeCompare(right.domain) || left.observedAt.localeCompare(right.observedAt) || left.summary.localeCompare(right.summary));
+    const selected = [];
+    const seen = new Set();
+    const domainCounts = new Map();
+    const domains = new Set();
+    for (const finding of candidates) {
+        const key = `${finding.domain}\u0000${finding.category}\u0000${finding.summary}\u0000${finding.observedAt}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (!domains.has(finding.domain) && domains.size >= MAX_EXTERNAL_FINDING_DOMAINS)
+            continue;
+        const count = domainCounts.get(finding.domain) ?? 0;
+        if (count >= MAX_EXTERNAL_FINDINGS_PER_DOMAIN)
+            continue;
+        if (selected.length >= MAX_EXTERNAL_FINDINGS)
+            continue;
+        domains.add(finding.domain);
+        domainCounts.set(finding.domain, count + 1);
+        selected.push(finding);
+    }
+    const truncated = selected.length < seen.size;
+    const document = {
+        schema: 'whoisleuth.external-findings',
+        schemaVersion: 3,
+        source,
+        findings: selected.map((finding) => ({
+            ...finding,
+            limitations: [
+                ...finding.limitations,
+                `Mapped locally with declarative profile ${profile.id} version ${profile.version}; the profile does not verify the upstream field semantics.`,
+                ...(truncated ? ['The supplied records exceeded the browser import boundary; only the first deterministic bounded findings were retained.'] : []),
+            ].slice(0, 8),
+        })),
+    };
+    return parseExternalFindingsDocument(document);
+}
+export function formatExternalObservationMapping(document) {
+    return [
+        'External observation mapping',
+        `Source    ${document.source.name}`,
+        `Findings  ${document.findings.length}`,
+        `Domains   ${new Set(document.findings.map((finding) => finding.domain)).size}`,
+        '',
+        'The JSON form can be deliberately imported through the Console external-findings workflow.',
+        '',
+    ].join('\n');
+}

package/cli/fail-policy.mjs

@@ -0,0 +1,64 @@
+import { lookupStrictExitFindings } from "./strict-exit.mjs";
+import { CliUsageError } from "./errors.mjs";
+export const CLI_FAIL_POLICIES = ['source-failure', 'inconclusive', 'danger', 'material-drift'];
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+export function parseCliFailPolicies(value) {
+    if (typeof value !== 'string' || !value || value.length > 100)
+        throw new CliUsageError('--fail-on requires a comma-separated policy list.');
+    const policies = [...new Set(value.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean))];
+    if (!policies.length || policies.some((item) => !CLI_FAIL_POLICIES.includes(item))) {
+        throw new CliUsageError(`--fail-on supports: ${CLI_FAIL_POLICIES.join(', ')}.`);
+    }
+    return policies;
+}
+function availabilityStates(document) {
+    const direct = String(record(document.availability).state || '').toLowerCase();
+    const results = Array.isArray(document.results) ? document.results : [];
+    const resultStates = results.flatMap((value) => {
+        const item = record(value);
+        const state = item.availabilityState ?? record(item.availability).state;
+        return typeof state === 'string' ? [state.toLowerCase()] : [];
+    });
+    return [direct, ...resultStates].filter(Boolean);
+}
+export function evaluateCliFailPolicies(document, policies) {
+    const root = record(document);
+    const findings = [];
+    for (const policy of policies) {
+        if (policy === 'source-failure') {
+            const resultDocuments = Array.isArray(root.results) ? root.results.map(record).filter((item) => Object.keys(record(item.diagnostics)).length) : [];
+            const sourceFindings = Object.keys(record(root.diagnostics)).length
+                ? lookupStrictExitFindings(root)
+                : resultDocuments.flatMap((item) => lookupStrictExitFindings(item));
+            const collection = record(root.collection);
+            const summary = record(root.summary);
+            const failed = Number(collection.failed ?? summary.failed ?? 0);
+            if (sourceFindings.length || failed > 0)
+                findings.push({ policy, reason: `${sourceFindings.length + failed} failed or incomplete collection state(s)` });
+        }
+        else if (policy === 'inconclusive') {
+            const count = availabilityStates(root).filter((state) => ['unknown', 'inconclusive', 'partial', 'unavailable'].includes(state)).length;
+            if (count)
+                findings.push({ policy, reason: `${count} authority or availability state(s) remained inconclusive` });
+        }
+        else if (policy === 'danger') {
+            const risk = Number(record(root.risk).score ?? root.riskScore);
+            const severity = String(root.severity || record(root.review).severity || '').toLowerCase();
+            if ((Number.isFinite(risk) && risk >= 70) || severity === 'danger' || severity === 'critical') {
+                findings.push({ policy, reason: Number.isFinite(risk) ? `risk score ${risk} met the 70 review threshold` : `explicit ${severity} severity was present` });
+            }
+        }
+        else {
+            const summary = record(record(root.flightRecorder).summary);
+            const unexpected = Number(summary.unexpectedChanges ?? 0);
+            if (unexpected > 0)
+                findings.push({ policy, reason: `${unexpected} unexpected complete observation change(s)` });
+        }
+    }
+    return findings;
+}
+export function formatFailPolicyNotice(findings) {
+    return `Failure policy matched: ${findings.map((item) => `${item.policy} (${item.reason})`).join('; ')}.\n`;
+}

package/cli/formatters/html.mjs

@@ -12,7 +12,7 @@ function renderGroups(groups) {
 }
 function renderComparison(comparison) {
     if (!comparison.fields.length)
-        return '<p class="empty">No comparable normalized fields were published.</p>';
+        return '<p class="empty">No comparable normalised fields were published.</p>';
     const rows = comparison.fields.map((field) => `<tr><th scope="row">${escapeHtml(field.label)}</th><td><span class="status">${escapeHtml(field.status)}</span></td><td>${escapeHtml(field.rdap)}</td><td>${escapeHtml(field.whois)}</td></tr>`).join('');
     const omitted = comparison.omitted
         ? `<p class="omission">${escapeHtml(comparison.omitted)} additional comparison fields omitted.</p>`
@@ -66,4 +66,4 @@ function formatLookupEvidenceHtml(document) {
 </html>
 `;
 }
-export { escapeHtml, formatLookupEvidenceHtml };
+export { formatLookupEvidenceHtml };

package/cli/formatters/json.mjs

@@ -17,7 +17,13 @@ const CLI_POSTURE_SCHEMA_VERSION = 1;
 const CLI_HTTP_SCHEMA_VERSION = 1;
 const CLI_TLS_SCHEMA_VERSION = 1;
 const CLI_COMPARE_SCHEMA_VERSION = 3;
-function buildCliLookupDocument(query, classified, result, generatedAt = new Date().toISOString(), mode = 'fast') {
+function buildCliLookupDocument(query, classified, result, generatedAt = new Date().toISOString(), mode = 'fast', collectionContext = {}) {
+    const observerLabel = typeof collectionContext.observerLabel === 'string'
+        ? collectionContext.observerLabel
+        : null;
+    const vantageLabel = typeof collectionContext.vantageLabel === 'string'
+        ? collectionContext.vantageLabel
+        : null;
     return {
         schema: CLI_LOOKUP_SCHEMA,
         version: CLI_LOOKUP_SCHEMA_VERSION,
@@ -28,6 +34,12 @@ function buildCliLookupDocument(query, classified, result, generatedAt = new Dat
         inputHostname: classified.inputHostname,
         registrableDomain: classified.registrableDomain,
         isSubdomain: classified.isSubdomain,
+        ...((observerLabel || vantageLabel) ? {
+            collectionContext: {
+                ...(observerLabel ? { observerLabel } : {}),
+                ...(vantageLabel ? { vantageLabel } : {}),
+            },
+        } : {}),
         ...result,
     };
 }

package/cli/formatters/terminal.mjs

@@ -593,7 +593,7 @@ function formatTerminalCompare(document) {
     }
     lines.push('');
     if (!fields.length) {
-        lines.push('Neither source published a comparable normalized field.');
+        lines.push('Neither source published a comparable normalised field.');
     }
     else {
         for (const value of fields) {
@@ -613,7 +613,7 @@ function formatTerminalCompare(document) {
         const publicationDifferences = publicationFields.length - (Number(publicationCounts.equivalent) || 0);
         lines.push('', 'Registry / registrar RDAP publication', `Registry RDAP  ${comparisonStatusLabel(registryHealth.status)}`, `Registrar RDAP ${comparisonStatusLabel(registrarHealth.status)}`, `Compared       ${safeTerminalValue(publicationFields.length, '0')} field${publicationFields.length === 1 ? '' : 's'}`, `Equivalent     ${safeTerminalValue(publicationCounts.equivalent, '0')}`, `Differences    ${safeTerminalValue(publicationDifferences, '0')}`, '');
         if (!publicationFields.length) {
-            lines.push('Neither RDAP publication exposed a comparable normalized field.');
+            lines.push('Neither RDAP publication exposed a comparable normalised field.');
         }
         else {
             for (const value of publicationFields) {
@@ -635,6 +635,7 @@ function formatTerminalRiskCalibration(document) {
     const bands = terminalRecord(summary.scoreBands);
     const thresholds = Array.isArray(document.thresholds) ? document.thresholds : [];
     const records = Array.isArray(document.records) ? document.records : [];
+    const comparison = terminalRecord(document.modelComparison);
     const visible = records.slice(0, MAX_RISK_CALIBRATION_TERMINAL_RECORDS);
     const lines = [
         `Risk model     v${safeTerminalValue(document.riskModelVersion)}`,
@@ -648,7 +649,10 @@ function formatTerminalRiskCalibration(document) {
     ];
     for (const value of thresholds) {
         const threshold = terminalRecord(value);
-        lines.push(`${String(safeTerminalValue(threshold.threshold)).padStart(3)}+  TP ${safeTerminalValue(threshold.truePositive, '0')}  FP ${safeTerminalValue(threshold.falsePositive, '0')}  TN ${safeTerminalValue(threshold.trueNegative, '0')}  FN ${safeTerminalValue(threshold.falseNegative, '0')}  precision ${safeTerminalValue(threshold.precision)}  recall ${safeTerminalValue(threshold.recall)}`);
+        lines.push(`${String(safeTerminalValue(threshold.threshold)).padStart(3)}+  TP ${safeTerminalValue(threshold.truePositive, '0')}  FP ${safeTerminalValue(threshold.falsePositive, '0')}  TN ${safeTerminalValue(threshold.trueNegative, '0')}  FN ${safeTerminalValue(threshold.falseNegative, '0')}  precision ${safeTerminalValue(threshold.precision)}  recall ${safeTerminalValue(threshold.recall)}  F1 ${safeTerminalValue(threshold.f1)}`);
+    }
+    if (comparison.available === true) {
+        lines.push('', `Model comparison  v${safeTerminalValue(comparison.previousModelVersion)} → v${safeTerminalValue(comparison.currentModelVersion)} · ${safeTerminalValue(comparison.scoresChanged, '0')} score changes · ${safeTerminalValue(comparison.thresholdClassificationsChanged, '0')} review-band changes`);
     }
     lines.push('', 'Records');
     for (const value of visible) {