@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/lib/dns-inheritance-review.mjs

@@ -0,0 +1,207 @@
+import { promises as dns } from 'node:dns';
+import { parse as parseDomain } from 'tldts';
+import { validateDmarcExternalReporting } from "./domain-posture-analysis.mjs";
+import { requireDmarcDomain, walkDmarcTree } from "./dmarc-discovery.mjs";
+import { buildDnssecQuery, DNS_TYPE_NS, normalizeResolverEndpoint, parseDnssecResponse } from "./dnssec-chain-validation.mjs";
+import { defaultTcpExchange } from "./service-binding-dns.mjs";
+import { isValidAsciiHostname } from "../packages/contracts/domain-name.mjs";
+const MAX_PARENT_SERVERS = 2;
+const MAX_NS = 16;
+const QUERY_TIMEOUT_MS = 2200;
+const REVIEW_TIMEOUT_MS = 10_000;
+export const MAX_DMARC_REVIEW_QUERIES = 32;
+const MISSING = new Set(['ENODATA', 'ENOTFOUND', 'ENONAME']);
+/** Explicit query parameter; malformed opt-ins never broaden collection. */
+export function parseInheritedDnsSelection(value) {
+    if (value === undefined || value === '')
+        return undefined;
+    if (value === '1')
+        return true;
+    throw new TypeError('includeInheritedDns must be 1 when requested.');
+}
+function check(id, label, status, summary, detail, records) {
+    return { id, label, status, summary, detail, records, remediation: '' };
+}
+/** RFC 9989 sections 4.10–4.10.2; at most eight owners including the exact name. */
+export async function reviewInheritedDmarc(domain, exact, resolve) {
+    const { rows, available, boundary, incomplete, organisationalDomain } = await walkDmarcTree(domain, exact, resolve, 'policy');
+    const explicit = rows[0].valid ? rows[0] : null;
+    const selected = explicit ?? available.find(row => row.owner === organisationalDomain) ?? (boundary?.psd === 'y' ? boundary : null);
+    const summary = incomplete ? 'Inherited policy could not be determined from the collected records.'
+        : selected ? `${selected.owner === domain ? 'Exact-name' : 'Inherited'} policy published at _dmarc.${selected.owner}.`
+            : 'No applicable DMARC policy was found in the completed tree walk.';
+    const detail = !incomplete && selected
+        ? selected.owner === domain
+            ? `Published policy: ${selected.parsed.policy}. Test mode: ${selected.parsed.testMode ? 'yes' : 'no'}.`
+            : `For an existing name: ${selected.parsed.subdomainPolicy}. For a nonexistent name: ${selected.parsed.nonexistentSubdomainPolicy}. Test mode: ${selected.parsed.testMode ? 'yes' : 'no'}. Name existence is not inferred from this review.`
+        : 'Invalid or unavailable records do not establish absence or a usable inherited policy.';
+    return check('dmarc_inheritance', 'Inherited DMARC policy', incomplete || !selected ? 'warning' : 'info', summary, `${detail} Discovery follows RFC 9989 with at most eight owners. This is publication evidence, not message authentication or a guarantee of receiver behaviour.`, rows.map(row => row.record));
+}
+function nameservers(value) {
+    if (!Array.isArray(value) || value.length > MAX_NS)
+        return null;
+    const names = value.map(raw => typeof raw === 'string' && raw.length <= 254 ? raw.toLowerCase().replace(/\.$/u, '') : '');
+    return names.every(name => name.length <= 253 && isValidAsciiHostname(name)) ? [...new Set(names)].sort() : null;
+}
+export async function reviewParentDelegation(domain, recursive, dependencies, signal) {
+    requireDmarcDomain(domain);
+    const parsed = parseDomain(domain, { allowPrivateDomains: false });
+    const child = parsed.domain;
+    const parent = parsed.publicSuffix;
+    const records = [];
+    let referrals = 0;
+    let differs = false;
+    let parentDiffers = false;
+    let firstReferral = null;
+    let incomplete = false;
+    const observed = recursive.error || domain !== child ? null : nameservers(recursive.records);
+    const finish = () => check('parent_delegation', 'Direct parent delegation', differs || parentDiffers || incomplete || !referrals ? 'warning' : 'info', parentDiffers ? 'Sampled parent servers returned different delegation referrals.'
+        : differs ? 'Parent referral and recursive nameserver observations differ.'
+            : referrals ? `${referrals} parent server${referrals === 1 ? '' : 's'} returned a delegation referral for ${child}.`
+                : 'No direct parent referral was established.', `Registration-domain scope: ${child ?? 'unavailable'}; parent candidate: ${parent ?? 'unavailable'}. At most two discovered parent servers are queried over pinned public-address DNS/TCP, without recursion. This is a sample, not full delegation or DNSSEC validation.${incomplete ? ' Some discovery or direct observations were unavailable or incomplete.' : ''}${!observed ? ' No complete same-scope recursive comparison is available.' : ''}`, records);
+    if (!child || !parent || child === parent)
+        return finish();
+    signal?.throwIfAborted();
+    let discovered;
+    try {
+        discovered = nameservers(await dependencies.resolveNs(parent));
+    }
+    catch {
+        signal?.throwIfAborted();
+        incomplete = true;
+        return finish();
+    }
+    if (!discovered?.length) {
+        incomplete = true;
+        return finish();
+    }
+    records.push(`Recursive DNS NS ${parent} · ${dependencies.now().toISOString()} · ${discovered.length} discovered; ${Math.min(MAX_PARENT_SERVERS, discovered.length)} selected.`);
+    for (const server of discovered.slice(0, MAX_PARENT_SERVERS)) {
+        signal?.throwIfAborted();
+        const resolutions = await Promise.allSettled([dependencies.resolve4(server), dependencies.resolve6(server)]);
+        signal?.throwIfAborted();
+        const failed = resolutions.some(result => result.status === 'fulfilled'
+            ? !Array.isArray(result.value) || result.value.length > 16
+            : !MISSING.has(String(result.reason?.code)));
+        if (failed) {
+            incomplete = true;
+            records.push(`${server}: public-address discovery unavailable or rejected.`);
+            continue;
+        }
+        const addresses = resolutions.flatMap(result => result.status === 'fulfilled' ? result.value : []);
+        const endpoints = addresses.map(normalizeResolverEndpoint);
+        if (!addresses.length || endpoints.some(endpoint => !endpoint)) {
+            incomplete = true;
+            records.push(`${server}: public-address discovery unavailable or rejected.`);
+            continue;
+        }
+        const endpoint = endpoints.filter((value) => value !== null)
+            .sort((a, b) => a.address < b.address ? -1 : a.address > b.address ? 1 : 0)[0];
+        const query = buildDnssecQuery(child, DNS_TYPE_NS);
+        query.writeUInt16BE(0, 2); // No recursion or authenticated-data assertion is requested.
+        try {
+            const responseBytes = await dependencies.exchange(query, endpoint, { timeoutMs: QUERY_TIMEOUT_MS, ...(signal ? { signal } : {}) });
+            signal?.throwIfAborted();
+            if (responseBytes.byteLength > 65_535)
+                throw new RangeError('The DNS response exceeds the wire limit.');
+            const response = parseDnssecResponse(responseBytes, { transactionId: query.readUInt16BE(0), name: child, type: DNS_TYPE_NS });
+            const referred = nameservers(response.records.filter(row => row.section === 'authority' && row.owner === child && row.type === DNS_TYPE_NS && row.class === 1)
+                .flatMap(row => row.data.kind === 'NS' ? [row.data.name] : []));
+            records.push(`Direct DNS/TCP ${server} [${endpoint.address}] · ${dependencies.now().toISOString()} · ${child} NS · response ${response.rcode}.`);
+            if (response.rcode !== 0 || !referred?.length) {
+                incomplete = true;
+                continue;
+            }
+            referrals += 1;
+            if (firstReferral && JSON.stringify(firstReferral) !== JSON.stringify(referred))
+                parentDiffers = true;
+            firstReferral ??= referred;
+            for (const name of referred)
+                records.push(`${server} authority section: ${child} NS ${name}`);
+            if (observed && JSON.stringify(observed) !== JSON.stringify(referred))
+                differs = true;
+        }
+        catch {
+            signal?.throwIfAborted();
+            incomplete = true;
+            records.push(`${server}: bounded direct referral query failed.`);
+        }
+    }
+    return finish();
+}
+export async function collectDnsInheritanceReview(domain, exact, recursive, options = {}, injected) {
+    requireDmarcDomain(domain);
+    options.signal?.throwIfAborted();
+    const timeout = AbortSignal.timeout(REVIEW_TIMEOUT_MS);
+    const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    const resolver = injected ? null : new dns.Resolver({ timeout: QUERY_TIMEOUT_MS, tries: 1 });
+    const cancel = () => resolver?.cancel();
+    signal.addEventListener('abort', cancel, { once: true });
+    const dependencies = injected ?? {
+        resolveTxt: (name) => resolver.resolveTxt(name), resolveNs: (name) => resolver.resolveNs(name),
+        resolve4: (name) => resolver.resolve4(name), resolve6: (name) => resolver.resolve6(name),
+        exchange: defaultTcpExchange, now: () => new Date(),
+    };
+    let questions = 0;
+    const cache = new Map([[`_dmarc.${domain}`, Promise.resolve(exact)]]);
+    const query = async (owner) => {
+        signal.throwIfAborted();
+        if (owner.length > 253)
+            return { records: [], error: 'The DNS question exceeds the name limit.' };
+        questions += 1;
+        try {
+            return { records: await dependencies.resolveTxt(owner), error: null, observedAt: dependencies.now().toISOString() };
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            return { records: [], error: MISSING.has(String(error?.code)) ? null : 'DNS observation unavailable.', observedAt: dependencies.now().toISOString() };
+        }
+    };
+    const resolve = (owner) => {
+        options.signal?.throwIfAborted();
+        const existing = cache.get(owner);
+        if (existing)
+            return existing;
+        if (questions >= MAX_DMARC_REVIEW_QUERIES)
+            return Promise.resolve({ records: [], error: 'The shared DMARC query budget was reached.' });
+        const pending = query(owner);
+        cache.set(owner, pending);
+        return pending;
+    };
+    const organisations = new Map();
+    const boundaryRecords = new Map();
+    const boundaryResults = new Map();
+    const resolveOrganisationalDomain = (owner) => {
+        const existing = organisations.get(owner);
+        if (existing)
+            return existing;
+        const pending = (async () => {
+            const walk = await walkDmarcTree(owner, await resolve(`_dmarc.${owner}`), resolve, 'organisation');
+            for (const row of walk.rows)
+                if (cache.has(`_dmarc.${row.owner}`))
+                    boundaryRecords.set(row.owner, row.record);
+            boundaryResults.set(owner, `${owner}: organisational domain ${walk.organisationalDomain ?? 'unknown'}.`);
+            return walk.organisationalDomain;
+        })();
+        organisations.set(owner, pending);
+        return pending;
+    };
+    const operations = [
+        reviewInheritedDmarc(domain, exact, resolve),
+        reviewParentDelegation(domain, recursive, dependencies, signal),
+        validateDmarcExternalReporting(domain, exact, resolve, resolveOrganisationalDomain),
+    ];
+    try {
+        const [policy, parent, reporting] = await Promise.allSettled(operations);
+        options.signal?.throwIfAborted();
+        const checks = [policy, parent].map((result, index) => result.status === 'fulfilled' ? result.value : check(index === 0 ? 'dmarc_inheritance' : 'parent_delegation', index === 0 ? 'Inherited DMARC policy' : 'Direct parent delegation', 'warning', 'The additional review could not complete.', 'No absence or effective-policy conclusion is available from the incomplete review.', []));
+        const dmarcAuthorizations = reporting.status === 'fulfilled' ? reporting.value : [];
+        if (organisations.size)
+            checks.push(check('dmarc_reporting_boundaries', 'DMARC reporting boundaries', reporting.status === 'rejected' || dmarcAuthorizations.some(item => !['self', 'authorized'].includes(item.state)) ? 'warning' : 'info', 'Reporting destinations were reviewed using DNS-derived organisational boundaries.', `${questions} additional DMARC TXT questions used; the shared limit is ${MAX_DMARC_REVIEW_QUERIES} within ten seconds. Each tree walk examines at most eight owners. Unavailable boundaries remain unknown; a missing optional authorisation record does not establish a configuration error.`, [...boundaryResults.values(), ...boundaryRecords.values()]));
+        return { checks, dmarcAuthorizations };
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        cancel();
+    }
+}

package/lib/dns-intelligence.mjs

@@ -1,15 +1,18 @@
 // Bounded DNS evidence for investigative deep scans. This collector keeps
-// authoritative absence distinct from resolver failure, preserves only record
+// resolver-reported negative answers distinct from failures, preserves only record
 // types that aid domain triage, and never treats shared infrastructure as proof
 // of common ownership or maliciousness.
 import { promises as dns } from 'node:dns';
 import * as net from 'node:net';
 import { classifyMxRecords } from "./dns-mx.mjs";
+import { normalizeResolverMxRecord } from "../packages/evidence/domain-control-runtime.mjs";
 import { collectDnsDelegationHealth, skippedDnsDelegationHealth, } from "./dns-delegation-health.mjs";
 import { createObservation } from "../packages/evidence/observation.mjs";
 import { MAX_LOOKUP_DNS_RECORDS_PER_TYPE, MAX_LOOKUP_REVERSE_DNS_PTR_RECORDS, } from "./lookup-network-evidence-bounds.mjs";
 import { isPrivateAddress } from "./safe-fetch.mjs";
 import { resolveServiceBindingRecords } from "./service-binding-dns.mjs";
+import { canonicalRegistrableDomain } from "../packages/analysis/registrable-domain.mjs";
+import { DNS_QUERY_OUTCOMES, dnsQueryFailureOutcome } from "../packages/evidence/dns-query-outcome.mjs";
 const DNS_TIMEOUT_MS = 5000;
 const MAX_RECORDS_PER_TYPE = MAX_LOOKUP_DNS_RECORDS_PER_TYPE;
 const MAX_PTR_RECORDS = MAX_LOOKUP_REVERSE_DNS_PTR_RECORDS;
@@ -22,7 +25,6 @@ const MAX_SERVICE_ALPN_IDS = 16;
 const MAX_SERVICE_ADDRESS_HINTS = 8;
 const MAX_CAA_TREE_QUERIES = 8;
 const DNS_CONTROL_CHARACTER_RE = /[\u0000-\u001f\u007f]/u;
-const MISSING_CODES = new Set(['ENODATA', 'ENOTFOUND', 'ENONAME']);
 function skippedDnsIntelligence(detail = 'DNS intelligence is disabled by deployment policy.', { includeExtendedContext = false, includeInheritedCaa = false, } = {}) {
     const skipped = { status: 'skipped', error: null, truncated: false, discarded: 0 };
     const recordTypes = ['a', 'aaaa', 'cname', 'ns', 'mx', 'spf', 'dmarc', 'caa'];
@@ -123,7 +125,7 @@ function boundedUnique(values, limit = MAX_RECORDS_PER_TYPE) {
 }
 function normalizeAddresses(records, family) {
     const values = [];
-    let discarded = 0;
+    let discarded = Array.isArray(records) ? 0 : 1;
     for (const record of Array.isArray(records) ? records : []) {
         const value = typeof record === 'string' ? record : record && typeof record === 'object' ? record.address : null;
         if (typeof value !== 'string' || net.isIP(value) !== family)
@@ -135,7 +137,7 @@ function normalizeAddresses(records, family) {
 }
 function normalizeHostnames(records) {
     const values = [];
-    let discarded = 0;
+    let discarded = Array.isArray(records) ? 0 : 1;
     for (const record of Array.isArray(records) ? records : []) {
         const value = normalizeHostname(record);
         if (value)
@@ -147,19 +149,15 @@ function normalizeHostnames(records) {
 }
 function normalizeMx(records) {
     const byKey = new Map();
-    let discarded = 0;
+    let discarded = Array.isArray(records) ? 0 : 1;
     for (const record of Array.isArray(records) ? records : []) {
-        if (!record || typeof record !== 'object') {
-            discarded += 1;
-            continue;
-        }
-        const value = record;
-        const exchange = value.exchange === '' || value.exchange === '.' ? '' : normalizeHostname(value.exchange);
-        const priority = Number(value.priority);
-        if (exchange === null || !Number.isInteger(priority) || priority < 0 || priority > 65535) {
+        const value = normalizeResolverMxRecord(record);
+        if (!value) {
             discarded += 1;
             continue;
         }
+        const { priority } = value;
+        const exchange = value.exchange === '.' ? '' : value.exchange;
         byKey.set(`${priority}:${exchange}`, { priority, exchange });
     }
     const values = [...byKey.values()].sort((a, b) => a.priority - b.priority || a.exchange.localeCompare(b.exchange));
@@ -167,7 +165,7 @@ function normalizeMx(records) {
 }
 function normalizeTxtPolicies(records, prefix) {
     const values = [];
-    let discarded = 0;
+    let discarded = Array.isArray(records) ? 0 : 1;
     for (const chunks of Array.isArray(records) ? records : []) {
         if (!Array.isArray(chunks) || chunks.some((chunk) => typeof chunk !== 'string')) {
             discarded += 1;
@@ -185,7 +183,7 @@ function normalizeTxtPolicies(records, prefix) {
 }
 function normalizeCaa(records) {
     const byKey = new Map();
-    let discarded = 0;
+    let discarded = Array.isArray(records) ? 0 : 1;
     for (const record of Array.isArray(records) ? records : []) {
         const entry = record && typeof record === 'object' ? record : {};
         const critical = Number(entry.critical);
@@ -388,27 +386,35 @@ function normalizePtr(records) {
 }
 function withTimeout(factory, timeoutMs) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error('DNS query timed out')), timeoutMs);
+        const timer = setTimeout(() => reject(Object.assign(new Error('DNS query timed out'), { code: 'ETIMEOUT' })), timeoutMs);
         Promise.resolve().then(factory).then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
     });
 }
 async function query(factory, normalize, timeoutMs) {
     try {
         const normalized = normalize(await withTimeout(factory, timeoutMs));
+        const unusable = !normalized.records.length && (normalized.truncated || normalized.discarded > 0);
         return {
-            status: normalized.records.length ? 'success' : 'not_found',
+            status: unusable ? 'error' : normalized.records.length ? 'success' : 'not_found',
+            detail: unusable ? 'invalid_response' : normalized.records.length ? 'records' : 'empty_answer',
             records: normalized.records,
-            error: null,
+            error: unusable ? 'The returned record family could not be retained completely; absence is unknown.' : null,
             truncated: normalized.truncated,
             discarded: normalized.discarded || 0,
         };
     }
     catch (error) {
-        if (error && typeof error === 'object' && MISSING_CODES.has(String(error.code)))
-            return { status: 'not_found', records: [], error: null, truncated: false, discarded: 0 };
-        return { status: 'error', records: [], error: boundedError(error), truncated: false, discarded: 0 };
+        const detail = dnsQueryFailureOutcome(error && typeof error === 'object' ? error.code : undefined);
+        const missing = DNS_QUERY_OUTCOMES[detail].status === 'not_found';
+        return { status: missing ? 'not_found' : 'error', detail, records: [], error: missing ? null : boundedError(error), truncated: false, discarded: 0 };
     }
 }
+function completeQuery(result) {
+    return result.status !== 'error' && !result.truncated && result.discarded === 0;
+}
+function observedPresence(result) {
+    return result.records.length > 0 ? true : completeQuery(result) ? false : null;
+}
 async function collectEffectiveCaaPolicy(domain, options = {}) {
     const normalizedDomain = normalizeHostname(domain);
     const queryLimit = Math.max(1, Math.min(MAX_CAA_TREE_QUERIES, Math.floor(options.queryLimit || MAX_CAA_TREE_QUERIES)));
@@ -459,7 +465,7 @@ async function collectEffectiveCaaPolicy(domain, options = {}) {
             truncated: result.truncated,
             discarded: result.discarded,
         });
-        if (result.status === 'error') {
+        if (result.status === 'error' && !result.truncated && result.discarded === 0) {
             return {
                 ...createObservation({
                     status: index === 0 ? 'error' : 'partial',
@@ -576,6 +582,10 @@ async function collectEffectiveCaaPolicy(domain, options = {}) {
     };
 }
 async function collectDnsIntelligence(domain, options = {}) {
+    const registrationDomain = options.registrationDomain ?? domain;
+    if (options.registrationDomain !== undefined && canonicalRegistrableDomain(domain) !== registrationDomain) {
+        throw new TypeError('DNS registration context must match the hostname being observed.');
+    }
     const resolvers = options.resolvers || {};
     const includeExtendedContext = options.includeExtendedContext === true;
     const includeInheritedCaa = options.includeInheritedCaa === true;
@@ -606,8 +616,11 @@ async function collectDnsIntelligence(domain, options = {}) {
     const httpsPromise = includeExtendedContext
         ? query(invoke('resolveHttps', (value) => resolveServiceBindingRecords(value, 'HTTPS', { timeoutMs })), normalizeServiceBindings, timeoutMs)
         : Promise.resolve(null);
+    const registrationNsPromise = includeExtendedContext && registrationDomain !== domain
+        ? query(invoke('resolveNs', dns.resolveNs, registrationDomain), normalizeHostnames, timeoutMs)
+        : nsPromise;
     const delegationPromise = includeExtendedContext
-        ? nsPromise.then((parentNameservers) => collectDnsDelegationHealth(domain, parentNameservers, {
+        ? registrationNsPromise.then((parentNameservers) => collectDnsDelegationHealth(registrationDomain, parentNameservers, {
             registryEvidence: options.registryEvidence,
             resolve4: (resolvers.resolve4 || dns.resolve4),
             resolve6: (resolvers.resolve6 || dns.resolve6),
@@ -645,7 +658,8 @@ async function collectDnsIntelligence(domain, options = {}) {
         || discardedCount > 0
         || (caaPolicy !== null && caaPolicy.complete !== true)
         || (delegation !== null && delegation.status !== 'success');
-    const classifiedMx = mx.status === 'error' ? null : classifyMxRecords(mx.records);
+    const classifiedMx = classifyMxRecords(mx.records);
+    const mxComplete = completeQuery(mx);
     return {
         ...createObservation({
             status: errorCount === values.length ? 'error' : incomplete ? 'partial' : 'success',
@@ -670,6 +684,7 @@ async function collectDnsIntelligence(domain, options = {}) {
             diagnostics: {
                 ...Object.fromEntries(Object.entries(queries).map(([name, item]) => [name, {
                         status: item.status,
+                        detail: item.detail,
                         error: item.error,
                         truncated: item.truncated,
                         discarded: item.discarded,
@@ -703,11 +718,11 @@ async function collectDnsIntelligence(domain, options = {}) {
             ...(soa ? { soa: soa.records } : {}),
             ...(https ? { https: https.records } : {}),
         },
-        hasMx: classifiedMx ? classifiedMx.hasMx : null,
-        hasNullMx: classifiedMx ? classifiedMx.hasNullMx : null,
-        mxHosts: classifiedMx ? classifiedMx.mxHosts : [],
-        hasSpf: spf.status === 'error' ? null : spf.records.length > 0,
-        hasDmarc: dmarc.status === 'error' ? null : dmarc.records.length > 0,
+        hasMx: classifiedMx.hasMx ? true : mxComplete ? false : null,
+        hasNullMx: mxComplete ? classifiedMx.hasNullMx : null,
+        mxHosts: classifiedMx.mxHosts,
+        hasSpf: observedPresence(spf),
+        hasDmarc: observedPresence(dmarc),
         delegation,
         ...(caaPolicy ? { caaPolicy } : {}),
     };

package/lib/dns-mx.mjs

@@ -14,7 +14,7 @@ function classifyMxRecords(records) {
     // of configuration. Not currently used for scoring (both cases already
     // correctly score as hasMx: false); exposed for callers that want to tell
     // the two apart.
-    const hasNullMx = records.length > 0 && realRecords.length === 0;
+    const hasNullMx = records.length === 1 && records[0]?.priority === 0 && realRecords.length === 0;
     return {
         hasMx: realRecords.length > 0,
         hasNullMx,

package/lib/dns-query-coverage.mjs

@@ -0,0 +1,40 @@
+import { exactKeys, requireRecord } from "./bounded-contract-normalizers.mjs";
+const QUERY_KEYS = new Set(['owner', 'type', 'state']);
+/** A positive legacy record proves its own query scope, never another type's absence. */
+export function normaliseDnsQueryCoverage(value, options) {
+    const { label, maximum, state, records } = options;
+    if (options.legacy) {
+        return Object.freeze([...new Map(records.map((record) => [
+                `${record.owner}\u0000${record.type}`,
+                Object.freeze({ owner: record.owner, type: record.type, state }),
+            ])).values()]);
+    }
+    if (!Array.isArray(value) || value.length > maximum)
+        throw new TypeError(`${label} must contain no more than ${maximum} query outcomes.`);
+    const byKey = new Map();
+    for (const [index, raw] of value.entries()) {
+        const path = `${label}[${index}]`;
+        const item = requireRecord(raw, path);
+        exactKeys(item, QUERY_KEYS, path);
+        const owner = options.owner(item.owner, `${path}.owner`);
+        const type = options.type(item.type, `${path}.type`);
+        if (item.state !== 'observed' && item.state !== 'partial' && item.state !== 'unavailable')
+            throw new TypeError(`${path}.state is unsupported.`);
+        if ((state === 'unavailable' && item.state !== 'unavailable') || (state === 'observed' && item.state !== 'observed')) {
+            throw new TypeError(`${path}.state contradicts the snapshot state.`);
+        }
+        const key = `${owner}\u0000${type}`;
+        if (byKey.has(key))
+            throw new TypeError(`${path} duplicates an owner and type.`);
+        byKey.set(key, Object.freeze({ owner, type, state: item.state }));
+    }
+    for (const record of records) {
+        const query = byKey.get(`${record.owner}\u0000${record.type}`);
+        if (!query || query.state === 'unavailable')
+            throw new TypeError(`${label} must declare an observed or partial query for every supplied record.`);
+    }
+    return Object.freeze([...byKey.values()]);
+}
+export function dnsQueryState(queries, owner, type) {
+    return queries.find((query) => query.owner === owner && query.type === type)?.state ?? 'not_queried';
+}

package/lib/dnssec-evidence-validation.mjs

@@ -130,6 +130,9 @@ function signatureTimeState(value, observedAt) {
 }
 function validateDnssecEvidence(input) {
     const normalizedOwner = ownerName(input.ownerName);
+    const missingDs = input.dsRecords === undefined;
+    const malformedContainers = [input.dsRecords, input.dnskeyRecords, input.rrSigRecords]
+        .filter((value) => value !== undefined && !Array.isArray(value)).length;
     const rawDs = Array.isArray(input.dsRecords) ? input.dsRecords : [];
     const rawDnskeys = Array.isArray(input.dnskeyRecords) ? input.dnskeyRecords : [];
     const rawRrsigs = Array.isArray(input.rrSigRecords) ? input.rrSigRecords : [];
@@ -138,7 +141,8 @@ function validateDnssecEvidence(input) {
     const rrsigs = rawRrsigs.slice(0, MAX_DNSSEC_RECORDS).map(normalizeRrsig).filter((item) => item !== null);
     const rejectedCount = Math.min(rawDs.length, MAX_DNSSEC_RECORDS) - dsRecords.length
         + Math.min(rawDnskeys.length, MAX_DNSSEC_RECORDS) - dnskeys.length
-        + Math.min(rawRrsigs.length, MAX_DNSSEC_RECORDS) - rrsigs.length;
+        + Math.min(rawRrsigs.length, MAX_DNSSEC_RECORDS) - rrsigs.length
+        + malformedContainers;
     const truncated = rawDs.length > MAX_DNSSEC_RECORDS
         || rawDnskeys.length > MAX_DNSSEC_RECORDS
         || rawRrsigs.length > MAX_DNSSEC_RECORDS;
@@ -166,7 +170,11 @@ function validateDnssecEvidence(input) {
             limitations: Object.freeze(limitations),
         });
     }
-    const incompleteInput = rejectedCount > 0 || truncated;
+    const incompleteInput = missingDs || rejectedCount > 0 || truncated;
+    if (missingDs)
+        findings.push('No DS record collection was supplied. Omitted input is not a verified empty collection.');
+    if (malformedContainers)
+        findings.push(`${malformedContainers} record collection container(s) had an invalid type; their contents are unknown.`);
     if (input.delegationSigned === false && dsRecords.length === 0 && !incompleteInput) {
         findings.push('The supplied delegation state was unsigned and no DS records were supplied.');
         return Object.freeze({
@@ -217,7 +225,7 @@ function validateDnssecEvidence(input) {
         findings.push('The retained subset contains no usable DS record, but omitted or rejected records prevent a definitive unsigned conclusion.');
     }
     if (rejectedCount > 0)
-        findings.push(`${rejectedCount} malformed record(s) were rejected.`);
+        findings.push(`${rejectedCount} malformed record(s) or collection container(s) were rejected.`);
     if (truncated)
         findings.push('The supplied record set exceeded the review bound and was truncated.');
     const completeLocalRelationship = dsRecords.length > 0

package/lib/domain-assurance.mjs

@@ -243,7 +243,7 @@ function buildRecoveryDependencies(input) {
     };
 }
 const RETIREMENT_CHECKS = Object.freeze([
-    ['autoRenewDisabled', 'Auto-renew is intentionally configured', true],
+    ['autoRenewDisabled', 'Auto-renew is disabled as declared', true],
     ['registrarLockMaintained', 'Registrar lock remains enabled', true],
     ['websiteRetired', 'Web service is retired or intentionally redirected', true],
     ['mailRetired', 'Mail service is retired', true],

package/lib/domain-change-packet.mjs

@@ -1,11 +1,17 @@
 import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
 import { DOMAIN_ASSURANCE_INPUT_SCHEMA, buildDomainAssurance, } from "./domain-assurance.mjs";
-import { DOMAIN_CHANGE_INPUT_SCHEMA, reviewDomainChange, } from "./domain-change-review.mjs";
+import { DOMAIN_CHANGE_INPUT_SCHEMA, DOMAIN_CHANGE_REVIEW_VERSION, reviewDomainChange, } from "./domain-change-review.mjs";
 import { SORTED_JSON_V2, sha256ArtifactDigestV2 } from "../packages/evidence/artifact-integrity.mjs";
 export const DOMAIN_CHANGE_PACKET_INPUT_SCHEMA = 'whoisleuth.domain-change-packet.input';
 export const DOMAIN_CHANGE_PACKET_SCHEMA = 'whoisleuth.domain-change-packet';
 export const DOMAIN_CHANGE_PACKET_INPUT_VERSION = 1;
-export const DOMAIN_CHANGE_PACKET_VERSION = 2;
+export const DOMAIN_CHANGE_PACKET_VERSION = 4;
+export const DOMAIN_CHANGE_PACKET_REVIEW_VERSIONS = Object.freeze({
+    2: 1,
+    3: 2,
+    [DOMAIN_CHANGE_PACKET_VERSION]: DOMAIN_CHANGE_REVIEW_VERSION,
+});
+export const SUPPORTED_DOMAIN_CHANGE_PACKET_VERSIONS = Object.freeze(Object.keys(DOMAIN_CHANGE_PACKET_REVIEW_VERSIONS).map(Number));
 export const MAX_DOMAIN_CHANGE_PACKET_INPUT_BYTES = 6 * 1024 * 1024;
 const ROOT_KEYS = new Set([
     'schema',
@@ -38,16 +44,10 @@ function changeSummary(before, after) {
     const beforeRows = rows(before);
     const afterRows = rows(after);
     const keys = [...new Set([...beforeRows.keys(), ...afterRows.keys()])].sort();
-    const authorityCollectionComplete = (review) => {
-        const representative = review.authoritativeRecordMatrix[0];
-        return Boolean(representative
-            && representative.observations.length >= 2
-            && representative.observations.every((item) => item.state === 'observed'));
-    };
-    const rowEvidence = (review, row) => {
+    const rowEvidence = (row) => {
         if (!row)
             return Object.freeze({
-                state: authorityCollectionComplete(review) ? 'complete' : 'unavailable',
+                state: 'unavailable',
                 values: Object.freeze([]),
             });
         if (row.observations.some((item) => item.state !== 'observed')) {
@@ -63,13 +63,15 @@ function changeSummary(before, after) {
         });
     };
     const changed = [];
+    const reasons = keys.length > 500 ? ['The comparison exceeds 500 owner and record-type pairs.'] : [];
     for (const key of keys.slice(0, 500)) {
         const left = beforeRows.get(key);
         const right = afterRows.get(key);
         const [owner, type] = key.split('\u0000');
-        const beforeEvidence = rowEvidence(before, left);
-        const afterEvidence = rowEvidence(after, right);
+        const beforeEvidence = rowEvidence(left);
+        const afterEvidence = rowEvidence(right);
         if (beforeEvidence.state !== 'complete' || afterEvidence.state !== 'complete') {
+            reasons.push(`Comparison evidence is incomplete for ${owner} ${type}.`);
             continue;
         }
         if (JSON.stringify(beforeEvidence.values) === JSON.stringify(afterEvidence.values))
@@ -81,7 +83,7 @@ function changeSummary(before, after) {
             afterValues: afterEvidence.values,
         }));
     }
-    return Object.freeze(changed);
+    return Object.freeze({ changed: Object.freeze(changed), reasons: Object.freeze(reasons) });
 }
 export async function buildDomainChangePacket(inputRaw, generatedAtValue = new Date().toISOString()) {
     const input = record(inputRaw, 'Domain change packet input');
@@ -102,11 +104,13 @@ export async function buildDomainChangePacket(inputRaw, generatedAtValue = new D
     const preChange = reviewDomainChange(input.preChange, generatedAt);
     const postChange = reviewDomainChange(input.postChange, generatedAt);
     const assurance = buildDomainAssurance(input.assurance, generatedAt);
+    const comparison = changeSummary(preChange, postChange);
     const assuranceReasons = assurance.result.review.reasons;
     const gateReasons = Object.freeze([
         ...preChange.gate.reasons.map((reason) => `Pre-change evidence: ${reason}`),
         ...postChange.gate.reasons.map((reason) => `Post-change evidence: ${reason}`),
         ...assuranceReasons.map((reason) => `Change plan: ${reason}`),
+        ...comparison.reasons,
     ].slice(0, 100));
     const unsigned = Object.freeze({
         schema: DOMAIN_CHANGE_PACKET_SCHEMA,
@@ -117,7 +121,7 @@ export async function buildDomainChangePacket(inputRaw, generatedAtValue = new D
         state: gateReasons.length ? 'review' : 'ready',
         gate: Object.freeze({ pass: gateReasons.length === 0, reasons: gateReasons }),
         summary: Object.freeze({
-            changedAuthoritativeRecordSets: changeSummary(preChange, postChange),
+            changedAuthoritativeRecordSets: comparison.changed,
             preChangeState: preChange.state,
             postChangeState: postChange.state,
             assuranceState: assurance.result.review.state,