@slicedearth/whoisleuth-cli 1.39.1 → 1.43.0

package/lib/dns-convergence-review.mjs

@@ -0,0 +1,183 @@
+import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
+import { normaliseRdata } from "./zone-intent-review.mjs";
+export const DNS_CONVERGENCE_INPUT_SCHEMA = 'whoisleuth.dns-convergence.input';
+export const DNS_CONVERGENCE_REVIEW_SCHEMA = 'whoisleuth.dns-convergence.review';
+export const DNS_CONVERGENCE_REVIEW_VERSION = 1;
+export const MAX_DNS_CONVERGENCE_SNAPSHOTS = 100;
+export const MAX_DNS_CONVERGENCE_RECORDS = 2_000;
+const RECORD_TYPES = new Set(['A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NS', 'SOA', 'SRV', 'SVCB', 'HTTPS', 'TLSA', 'TXT']);
+const ROOT_KEYS = new Set(['schema', 'version', 'domain', 'expected', 'snapshots']);
+const EXPECTED_KEYS = new Set(['owner', 'type', 'values']);
+const SNAPSHOT_KEYS = new Set(['observer', 'source', 'observedAt', 'state', 'records']);
+const RECORD_KEYS = new Set(['owner', 'type', 'value', 'ttl']);
+function type(value, label) {
+    const candidate = requireBoundedString(value, label, 16).toUpperCase();
+    if (!RECORD_TYPES.has(candidate))
+        throw new TypeError(`${label} is unsupported.`);
+    return candidate;
+}
+function owner(value, apex, label) {
+    const candidate = requireBoundedString(value, label, 253).toLowerCase().replace(/\.$/u, '');
+    if (candidate === '@')
+        return apex;
+    if (candidate.length > 253 || candidate.split('.').some((part) => !/^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/u.test(part))) {
+        throw new TypeError(`${label} must be a valid DNS owner name.`);
+    }
+    return candidate;
+}
+function state(value, label) {
+    if (value !== 'observed' && value !== 'partial' && value !== 'unavailable')
+        throw new TypeError(`${label} is unsupported.`);
+    return value;
+}
+function ttl(value, label) {
+    if (value === null || value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || Number(value) < 0 || Number(value) > 0x7fff_ffff)
+        throw new TypeError(`${label} is outside its supported range.`);
+    return Number(value);
+}
+function normaliseValue(recordType, value) {
+    if (recordType !== 'SOA')
+        return normaliseRdata(recordType, value, null);
+    const fields = value.trim().split(/\s+/u);
+    if (fields.length >= 2) {
+        fields[0] = fields[0]?.toLowerCase().replace(/\.$/u, '') ?? '';
+        fields[1] = fields[1]?.toLowerCase().replace(/\.$/u, '') ?? '';
+    }
+    return { value: fields.join(' '), valueTreatment: 'normalised' };
+}
+function record(value, apex, label) {
+    const input = requireRecord(value, label);
+    exactKeys(input, RECORD_KEYS, label);
+    const recordType = type(input.type, `${label}.type`);
+    const normalised = normaliseValue(recordType, requireBoundedString(input.value, `${label}.value`, 16_384));
+    return Object.freeze({
+        owner: owner(input.owner, apex, `${label}.owner`),
+        type: recordType,
+        value: normalised.value,
+        valueTreatment: normalised.valueTreatment,
+        ttl: ttl(input.ttl, `${label}.ttl`),
+    });
+}
+function expectedRows(value, apex) {
+    if (value === null || value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || value.length > 100)
+        throw new TypeError('expected must contain no more than 100 rows.');
+    const keys = new Set();
+    return Object.freeze(value.map((raw, index) => {
+        const input = requireRecord(raw, `expected[${index}]`);
+        exactKeys(input, EXPECTED_KEYS, `expected[${index}]`);
+        const recordType = type(input.type, `expected[${index}].type`);
+        const recordOwner = owner(input.owner, apex, `expected[${index}].owner`);
+        const key = `${recordOwner}\u0000${recordType}`;
+        if (keys.has(key))
+            throw new TypeError(`expected[${index}] duplicates an owner and type.`);
+        keys.add(key);
+        if (!Array.isArray(input.values) || input.values.length > 100)
+            throw new TypeError(`expected[${index}].values must contain no more than 100 entries.`);
+        const values = [...new Set(input.values.map((entry, valueIndex) => normaliseValue(recordType, requireBoundedString(entry, `expected[${index}].values[${valueIndex}]`, 16_384)).value))].sort();
+        return Object.freeze({ owner: recordOwner, type: recordType, values: Object.freeze(values) });
+    }));
+}
+export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toISOString()) {
+    const input = requireRecord(inputRaw, 'DNS convergence input');
+    if (input.schema !== DNS_CONVERGENCE_INPUT_SCHEMA || input.version !== 1) {
+        throw new TypeError(`DNS convergence input must use ${DNS_CONVERGENCE_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'DNS convergence input');
+    const apex = requireDomainName(input.domain, 'domain');
+    const expected = expectedRows(input.expected, apex);
+    if (!Array.isArray(input.snapshots) || input.snapshots.length < 2 || input.snapshots.length > MAX_DNS_CONVERGENCE_SNAPSHOTS) {
+        throw new TypeError(`snapshots must contain between 2 and ${MAX_DNS_CONVERGENCE_SNAPSHOTS} entries.`);
+    }
+    let recordCount = 0;
+    const snapshots = input.snapshots.map((raw, index) => {
+        const item = requireRecord(raw, `snapshots[${index}]`);
+        exactKeys(item, SNAPSHOT_KEYS, `snapshots[${index}]`);
+        if (!Array.isArray(item.records))
+            throw new TypeError(`snapshots[${index}].records must be an array.`);
+        recordCount += item.records.length;
+        if (recordCount > MAX_DNS_CONVERGENCE_RECORDS)
+            throw new TypeError(`DNS convergence input is limited to ${MAX_DNS_CONVERGENCE_RECORDS} records.`);
+        const observationState = state(item.state, `snapshots[${index}].state`);
+        if (observationState === 'unavailable' && item.records.length)
+            throw new TypeError(`snapshots[${index}] cannot contain records when unavailable.`);
+        return Object.freeze({
+            observer: requireBoundedString(item.observer, `snapshots[${index}].observer`, 120),
+            source: requireBoundedString(item.source, `snapshots[${index}].source`, 240),
+            observedAt: requireIsoTimestamp(item.observedAt, `snapshots[${index}].observedAt`),
+            state: observationState,
+            records: Object.freeze(item.records.map((entry, recordIndex) => record(entry, apex, `snapshots[${index}].records[${recordIndex}]`))),
+        });
+    }).sort((left, right) => left.observedAt.localeCompare(right.observedAt) || left.observer.localeCompare(right.observer));
+    const observers = [...new Set(snapshots.map((item) => item.observer))];
+    if (observers.length < 2)
+        throw new TypeError('DNS convergence review requires at least two distinct observer labels.');
+    const latestByObserver = observers.map((observer) => snapshots.filter((item) => item.observer === observer).at(-1));
+    const keys = [...new Set([
+            ...expected.map((item) => `${item.owner}\u0000${item.type}`),
+            ...snapshots.flatMap((item) => item.records.map((entry) => `${entry.owner}\u0000${entry.type}`)),
+        ])].sort();
+    const rows = keys.map((key) => {
+        const [recordOwner = '', recordType = ''] = key.split('\u0000');
+        const expectedRow = expected.find((item) => item.owner === recordOwner && item.type === recordType);
+        const observations = latestByObserver.map((snapshot) => {
+            const matching = snapshot.records.filter((entry) => entry.owner === recordOwner && entry.type === recordType);
+            const values = [...new Set(matching.map((entry) => entry.value))].sort();
+            const ttls = matching.flatMap((entry) => entry.ttl === null ? [] : [entry.ttl]);
+            const cacheUntil = ttls.length
+                ? new Date(Date.parse(snapshot.observedAt) + Math.max(...ttls) * 1_000).toISOString()
+                : null;
+            return Object.freeze({
+                observer: snapshot.observer,
+                source: snapshot.source,
+                observedAt: snapshot.observedAt,
+                state: snapshot.state,
+                values: Object.freeze(values),
+                cacheUntil,
+            });
+        });
+        const complete = observations.filter((item) => item.state === 'observed');
+        const incomplete = observations.some((item) => item.state !== 'observed');
+        const signatures = new Set(complete.map((item) => JSON.stringify(item.values)));
+        const aligned = complete.length >= 2 && signatures.size === 1;
+        const matchesExpected = expectedRow
+            ? aligned && JSON.stringify(complete[0]?.values ?? []) === JSON.stringify(expectedRow.values)
+            : null;
+        const rowState = incomplete ? 'incomplete'
+            : complete.length < 2 ? 'insufficient'
+                : !aligned ? 'divergent'
+                    : matchesExpected === false ? 'unexpected'
+                        : 'converged';
+        return Object.freeze({
+            owner: recordOwner,
+            type: recordType,
+            state: rowState,
+            expectedValues: expectedRow?.values ?? null,
+            observations: Object.freeze(observations),
+        });
+    });
+    const reasons = Object.freeze([
+        ...rows.filter((row) => row.state !== 'converged').map((row) => `${row.owner} ${row.type} is ${row.state}.`),
+        ...latestByObserver.filter((item) => item.state !== 'observed').map((item) => `${item.observer} latest evidence is ${item.state}.`),
+    ].slice(0, 200));
+    return Object.freeze({
+        schema: DNS_CONVERGENCE_REVIEW_SCHEMA,
+        version: DNS_CONVERGENCE_REVIEW_VERSION,
+        generatedAt: requireIsoTimestamp(generatedAtValue, 'generatedAt'),
+        domain: apex,
+        state: reasons.length ? 'review' : 'converged',
+        observers: Object.freeze(observers),
+        snapshots: Object.freeze(snapshots),
+        rows: Object.freeze(rows),
+        gate: Object.freeze({ pass: reasons.length === 0, reasons }),
+        limitations: Object.freeze([
+            'This local workbench compares only supplied observations and makes no DNS request.',
+            'Resolver differences can reflect caches, split-horizon policy, interception, collection timing, or propagation; they do not establish which value is authoritative.',
+            'Cache-until times are simple observation-time plus supplied TTL projections and do not reveal actual cache age, refresh behaviour, or resolver policy.',
+            'Partial and unavailable snapshots remain incomplete and are never interpreted as record absence.',
+        ]),
+    });
+}

package/lib/dns-delegation-health.mjs

@@ -11,6 +11,7 @@ const MAX_AUTHORITIES = 4;
 const MAX_AUTHORITY_ADDRESSES = 2;
 const MAX_NAMESERVERS = 16;
 const MAX_ERROR_LENGTH = 180;
+const MAX_AUTHORITY_RECORD_VALUES = 16;
 const DNS_DELEGATION_TIMEOUT_MS = 2200;
 const LAME_CODES = new Set(['ENOTAUTH', 'EREFUSED']);
 const MAX_SOA_VALUE = 0xffff_ffff;
@@ -47,6 +48,12 @@ function publicAddress(value) {
     const normalized = value.toLowerCase();
     return net.isIP(normalized) && !isPrivateAddress(normalized) ? normalized : null;
 }
+function observedAddress(value) {
+    if (typeof value !== 'string' || value.length > 80 || /[\u0000-\u0020\u007f%]/u.test(value))
+        return null;
+    const normalised = value.toLowerCase();
+    return net.isIP(normalised) ? normalised : null;
+}
 function errorCode(error) {
     const value = record(error).code;
     return typeof value === 'string' ? value.slice(0, 40) : '';
@@ -125,6 +132,127 @@ async function defaultAuthorityQuery(input) {
         error: null,
     };
 }
+function normaliseAuthorityValueSet(type, value) {
+    const input = Array.isArray(value) ? value : [];
+    const rows = input.slice(0, 256);
+    let rejected = input.length - rows.length;
+    const values = rows.flatMap((item) => {
+        if (type === 'A' || type === 'AAAA') {
+            // Returned record data is evidence, not a transport destination. Retain
+            // syntactically valid private and reserved addresses while continuing to
+            // require public addresses for the direct nameserver connection itself.
+            const address = observedAddress(item);
+            if (address && net.isIP(address) === (type === 'A' ? 4 : 6))
+                return [address];
+            rejected += 1;
+            return [];
+        }
+        const source = record(item);
+        if (type === 'MX') {
+            const exchange = hostname(source.exchange);
+            const priority = Number(source.priority);
+            if (exchange && Number.isSafeInteger(priority) && priority >= 0 && priority <= 65_535)
+                return [`${priority} ${exchange}`];
+            rejected += 1;
+            return [];
+        }
+        const critical = Number(source.critical);
+        const properties = ['issue', 'issuewild', 'iodef'].flatMap((key) => {
+            const candidate = boundedText(source[key], 500);
+            return candidate ? [`${Number.isSafeInteger(critical) && critical >= 0 && critical <= 255 ? critical : 0} ${key} ${candidate}`] : [];
+        });
+        if (!properties.length)
+            rejected += 1;
+        return properties;
+    });
+    const unique = [...new Set(values)].sort();
+    const overflow = Math.max(0, unique.length - MAX_AUTHORITY_RECORD_VALUES);
+    return {
+        values: unique.slice(0, MAX_AUTHORITY_RECORD_VALUES),
+        truncated: overflow > 0 || input.length > rows.length,
+        discarded: rejected + overflow,
+    };
+}
+function normaliseRetainedAuthorityValues(value) {
+    const input = Array.isArray(value) ? value : [];
+    const rows = input.slice(0, 256);
+    const valid = rows.map((item) => boundedText(item, 500)).filter((item) => item !== null);
+    const unique = [...new Set(valid)].sort();
+    const overflow = Math.max(0, unique.length - MAX_AUTHORITY_RECORD_VALUES);
+    return {
+        values: unique.slice(0, MAX_AUTHORITY_RECORD_VALUES),
+        truncated: overflow > 0 || input.length > rows.length,
+        discarded: input.length - rows.length + (rows.length - valid.length) + overflow,
+    };
+}
+function normaliseAuthorityValues(type, value) {
+    return normaliseAuthorityValueSet(type, value).values;
+}
+async function defaultAuthorityRecordQuery(input) {
+    const resolver = new dns.Resolver({
+        timeout: Math.max(250, Math.min(input.timeoutMs, DNS_DELEGATION_TIMEOUT_MS)),
+        tries: 1,
+    });
+    resolver.setServers([net.isIP(input.address) === 6 ? `[${input.address}]:53` : input.address]);
+    const queries = [
+        ['A', resolver.resolve4(input.domain)],
+        ['AAAA', resolver.resolve6(input.domain)],
+        ['CAA', resolver.resolveCaa(input.domain)],
+        ['MX', resolver.resolveMx(input.domain)],
+    ];
+    return Promise.all(queries.map(async ([type, promise]) => {
+        try {
+            const response = await withTimeout(promise, input.timeoutMs);
+            const normalised = normaliseAuthorityValueSet(type, response);
+            return {
+                type,
+                state: normalised.truncated || normalised.discarded > 0
+                    ? 'partial'
+                    : normalised.values.length ? 'success' : 'not_found',
+                ...normalised,
+                error: normalised.discarded > 0 && !normalised.values.length ? 'No usable record values were retained.' : null,
+            };
+        }
+        catch (error) {
+            const code = errorCode(error);
+            const missing = code === 'ENODATA' || code === 'ENOTFOUND';
+            return {
+                type,
+                state: missing ? 'not_found' : 'error',
+                values: [],
+                error: missing ? null : errorDetail(error),
+                truncated: false,
+                discarded: 0,
+            };
+        }
+    }));
+}
+function authorityRecordMatrix(authorities) {
+    const types = ['A', 'AAAA', 'CAA', 'MX'];
+    return types.map((type) => {
+        const observations = authorities.map((authority) => {
+            const result = authority.recordSets.find((item) => item.type === type);
+            return {
+                nameserver: authority.nameserver,
+                state: result?.state ?? 'not_collected',
+                values: result?.values ?? [],
+                error: result?.error ?? null,
+                truncated: result?.truncated === true,
+                discarded: typeof result?.discarded === 'number' ? result.discarded : 0,
+            };
+        });
+        const complete = observations.filter((item) => item.state === 'success' || item.state === 'not_found');
+        const signatures = new Set(complete.map((item) => JSON.stringify(item.values)));
+        return {
+            type,
+            state: observations.some((item) => item.state === 'error' || item.state === 'partial' || item.truncated || item.discarded > 0) ? 'partial'
+                : complete.length < 2 ? 'insufficient'
+                    : observations.some((item) => item.state === 'not_collected') ? 'partial'
+                        : signatures.size === 1 ? 'aligned' : 'different',
+            observations,
+        };
+    });
+}
 function registryProjection(value) {
     const registry = record(value);
     const nameserverDetails = (Array.isArray(registry.nameserverDetails)
@@ -185,6 +313,7 @@ function skippedDnsDelegationHealth(detail = 'Authoritative delegation checks we
             truncated: false,
         },
         authorities: [],
+        recordMatrix: [],
         findings: [],
     };
 }
@@ -204,6 +333,8 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
     const resolve4 = options.resolve4 || dns.resolve4;
     const resolve6 = options.resolve6 || dns.resolve6;
     const queryAuthority = options.queryAuthority || defaultAuthorityQuery;
+    const queryAuthorityRecords = options.queryAuthorityRecords
+        ?? (options.queryAuthority ? null : defaultAuthorityRecordQuery);
     const timeoutMs = Math.max(250, Math.min(5000, Number(options.timeoutMs) || DNS_DELEGATION_TIMEOUT_MS));
     const now = options.now || Date.now;
     const started = now();
@@ -256,6 +387,47 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
         const successful = attempts.find((attempt) => attempt.state === 'success');
         const partial = attempts.find((attempt) => attempt.state === 'partial');
         const retained = successful ?? partial;
+        let recordSets = [];
+        const recordAddress = retained?.address ?? addresses[0];
+        if (queryAuthorityRecords && recordAddress) {
+            try {
+                recordSets = (await withTimeout(queryAuthorityRecords({ domain, nameserver, address: recordAddress, timeoutMs }), timeoutMs))
+                    .filter((item) => ['A', 'AAAA', 'CAA', 'MX'].includes(item.type))
+                    .slice(0, 4)
+                    .map((item) => {
+                    const normalised = normaliseRetainedAuthorityValues(item.values);
+                    const suppliedState = ['success', 'not_found', 'partial', 'error'].includes(item.state)
+                        ? item.state : 'error';
+                    const discarded = normalised.discarded + (typeof item.discarded === 'number' && Number.isSafeInteger(item.discarded) && item.discarded > 0
+                        ? Math.min(item.discarded, 10_000) : 0);
+                    const truncated = item.truncated === true || normalised.truncated;
+                    const partial = suppliedState === 'partial'
+                        || truncated
+                        || discarded > 0
+                        || (suppliedState === 'success' && normalised.values.length === 0)
+                        || (suppliedState === 'not_found' && normalised.values.length > 0);
+                    return {
+                        type: item.type,
+                        state: suppliedState === 'error' ? 'error' : partial ? 'partial' : suppliedState,
+                        values: normalised.values,
+                        error: boundedText(item.error, MAX_ERROR_LENGTH)
+                            ?? (partial && !normalised.values.length ? 'No usable record values were retained.' : null),
+                        truncated,
+                        discarded,
+                    };
+                });
+            }
+            catch (error) {
+                recordSets = ['A', 'AAAA', 'CAA', 'MX'].map((type) => ({
+                    type: type,
+                    state: 'error',
+                    values: [],
+                    error: errorDetail(error),
+                    truncated: false,
+                    discarded: 0,
+                }));
+            }
+        }
         return {
             nameserver,
             addressSource: glue.length ? 'registry_glue' : 'recursive_address',
@@ -270,6 +442,7 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
             nameservers: retained?.nameservers ?? [],
             soaPrimary: retained?.soaPrimary ?? null,
             soa: retained?.soa ?? null,
+            recordSets,
             attempts,
         };
     }));
@@ -295,6 +468,11 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
     const inBailiwick = candidates.filter((nameserver) => (nameserver === domain || nameserver.endsWith(`.${domain}`)));
     const missingGlue = inBailiwick.filter((nameserver) => (!(registry.nameserverDetails.find((item) => item.name === nameserver)?.addresses.length)));
     const dnssecMismatch = (registry.delegationSigned === true && registry.dsRecordCount === 0) || (registry.delegationSigned === false && registry.dsRecordCount > 0);
+    const recordMatrix = authorityRecordMatrix(authorities);
+    const recordCollectionAttempted = authorities.some((authority) => authority.recordSets.length > 0);
+    const recordDifferences = recordMatrix.filter((row) => row.state === 'different');
+    const recordPartial = recordMatrix.filter((row) => row.state === 'partial');
+    const recordInsufficient = recordMatrix.filter((row) => row.state === 'insufficient');
     const findings = [
         finding('parent_registry_ns', 'Parent and registry nameservers', !parentNameservers.length || !registry.nameservers.length
             ? 'unknown'
@@ -342,11 +520,20 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
                 : registry.delegationSigned
                     ? `${registry.dsRecordCount} registry DS record${registry.dsRecordCount === 1 ? '' : 's'} observed`
                     : 'Registry publication marks the delegation unsigned', `delegationSigned: ${registry.delegationSigned === null ? 'unavailable' : registry.delegationSigned}. DS records: ${registry.dsRecordCount}.`, 'Confirm the registry DS set matches the intended zone-signing keys before enabling, rotating, or removing DNSSEC.'),
+        ...(authorities.some((authority) => authority.recordSets.length) ? [finding('authority_record_consistency', 'Authoritative record consistency', recordDifferences.length ? 'warning'
+                : recordPartial.length || recordInsufficient.length ? 'unknown' : 'healthy', recordDifferences.length
+                ? `Direct authority answers differ for ${recordDifferences.map((row) => row.type).join(', ')}`
+                : recordPartial.length
+                    ? 'Extended authority record comparison is incomplete'
+                    : recordInsufficient.length
+                        ? 'Fewer than two complete authority observations were available for one or more record types'
+                        : 'Observed A, AAAA, CAA, and MX answers agree across selected authorities', recordMatrix.map((row) => `${row.type}: ${row.state}`).join(' · '), 'Review propagation timing and the intended zone values before relying on a DNS change.')] : []),
     ];
     const collectionIncomplete = parentStatus === 'error'
         || parentQuery.truncated === true
         || registry.truncated
-        || authorities.some((authority) => authority.state !== 'success');
+        || authorities.some((authority) => authority.state !== 'success')
+        || (recordCollectionAttempted && (recordPartial.length > 0 || recordInsufficient.length > 0));
     const status = !candidates.length && parentStatus === 'error'
         ? 'error'
         : collectionIncomplete ? 'partial' : 'success';
@@ -360,10 +547,13 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
             source: 'dns_delegation',
             durationMs: Math.max(0, now() - started),
             complete: !collectionIncomplete,
-            truncated: parentQuery.truncated === true || registry.truncated,
+            truncated: parentQuery.truncated === true
+                || registry.truncated
+                || (recordCollectionAttempted && recordMatrix.some((row) => row.observations.some((item) => item.truncated))),
             limitations: [
                 'The parent nameserver set is a point-in-time recursive resolver view; registry nameservers and glue come from the separately attributed RDAP publication.',
                 'Direct queries use at most four selected nameservers and two validated public addresses per nameserver.',
+                'Extended A, AAAA, CAA, and MX comparison uses only one selected validated public address per nameserver and caps each record set at sixteen values.',
                 'A direct answer does not prove global reachability, and a failed query is not evidence that the record is absent.',
                 'DNS health does not decide registration availability, ownership, control, intent, safety, or maliciousness.',
                 'The DNSSEC check compares bounded registry publication fields; it does not validate the full cryptographic chain.',
@@ -375,6 +565,8 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
                 partialAuthorityCount: partialAuthorities.length,
                 lameAuthorityCount: lameAuthorities.length,
                 unreachableAuthorityCount: unreachableAuthorities.length,
+                truncatedAuthorityRecordSetCount: recordMatrix.reduce((count, row) => (count + row.observations.filter((item) => item.truncated).length), 0),
+                discardedAuthorityRecordValueCount: recordMatrix.reduce((count, row) => (count + row.observations.reduce((sum, item) => sum + item.discarded, 0)), 0),
             },
         }),
         detail: status === 'success'
@@ -389,7 +581,8 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
         },
         registry,
         authorities,
+        recordMatrix,
         findings,
     };
 }
-export { DNS_DELEGATION_HEALTH_VERSION, DNS_DELEGATION_TIMEOUT_MS, MAX_AUTHORITIES, MAX_AUTHORITY_ADDRESSES, collectDnsDelegationHealth, skippedDnsDelegationHealth, };
+export { DNS_DELEGATION_HEALTH_VERSION, DNS_DELEGATION_TIMEOUT_MS, MAX_AUTHORITIES, MAX_AUTHORITY_ADDRESSES, collectDnsDelegationHealth, normaliseAuthorityValues, skippedDnsDelegationHealth, };

package/lib/domain-change-packet.mjs

@@ -0,0 +1,133 @@
+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 { sha256ArtifactDigest } from "../frontend/src/lib/analysis/artifact-integrity.js";
+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_VERSION = 1;
+export const MAX_DOMAIN_CHANGE_PACKET_INPUT_BYTES = 6 * 1024 * 1024;
+const ROOT_KEYS = new Set([
+    'schema',
+    'version',
+    'domain',
+    'reference',
+    'preChange',
+    'postChange',
+    'assurance',
+]);
+function record(value, label) {
+    return requireRecord(value, label);
+}
+function domainFromInput(value, label) {
+    const input = record(value, label);
+    if (input.schema !== DOMAIN_CHANGE_INPUT_SCHEMA) {
+        throw new TypeError(`${label} must use ${DOMAIN_CHANGE_INPUT_SCHEMA}.`);
+    }
+    return requireDomainName(input.domain, `${label}.domain`);
+}
+function assuranceDomain(value) {
+    const input = record(value, 'assurance');
+    if (input.schema !== DOMAIN_ASSURANCE_INPUT_SCHEMA || input.kind !== 'planned-change') {
+        throw new TypeError('assurance must contain a planned-change domain assurance input.');
+    }
+    return requireDomainName(input.domain, 'assurance.domain');
+}
+function changeSummary(before, after) {
+    const rows = (review) => new Map(review.authoritativeRecordMatrix.map((row) => [`${row.owner}\u0000${row.type}`, row]));
+    const beforeRows = rows(before);
+    const afterRows = rows(after);
+    const keys = [...new Set([...beforeRows.keys(), ...afterRows.keys()])].sort();
+    return Object.freeze(keys.slice(0, 500).flatMap((key) => {
+        const left = beforeRows.get(key);
+        const right = afterRows.get(key);
+        const leftValues = left?.observations.flatMap((item) => item.values) ?? [];
+        const rightValues = right?.observations.flatMap((item) => item.values) ?? [];
+        const beforeValues = [...new Set(leftValues)].sort();
+        const afterValues = [...new Set(rightValues)].sort();
+        if (JSON.stringify(beforeValues) === JSON.stringify(afterValues))
+            return [];
+        const [owner, type] = key.split('\u0000');
+        return [Object.freeze({
+                owner: owner ?? '',
+                type: type ?? '',
+                beforeValues: Object.freeze(beforeValues),
+                afterValues: Object.freeze(afterValues),
+            })];
+    }));
+}
+export async function buildDomainChangePacket(inputRaw, generatedAtValue = new Date().toISOString()) {
+    const input = record(inputRaw, 'Domain change packet input');
+    if (input.schema !== DOMAIN_CHANGE_PACKET_INPUT_SCHEMA || input.version !== 1) {
+        throw new TypeError(`Domain change packet input must use ${DOMAIN_CHANGE_PACKET_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'Domain change packet input');
+    const domain = requireDomainName(input.domain, 'domain');
+    const domains = [
+        domainFromInput(input.preChange, 'preChange'),
+        domainFromInput(input.postChange, 'postChange'),
+        assuranceDomain(input.assurance),
+    ];
+    if (domains.some((candidate) => candidate !== domain)) {
+        throw new TypeError('The packet, change reviews, and assurance plan must refer to the same domain.');
+    }
+    const generatedAt = requireIsoTimestamp(generatedAtValue, 'generatedAt');
+    const preChange = reviewDomainChange(input.preChange, generatedAt);
+    const postChange = reviewDomainChange(input.postChange, generatedAt);
+    const assurance = buildDomainAssurance(input.assurance, generatedAt);
+    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}`),
+    ].slice(0, 100));
+    const unsigned = Object.freeze({
+        schema: DOMAIN_CHANGE_PACKET_SCHEMA,
+        version: DOMAIN_CHANGE_PACKET_VERSION,
+        generatedAt,
+        domain,
+        reference: requireBoundedString(input.reference, 'reference', 200),
+        state: gateReasons.length ? 'review' : 'ready',
+        gate: Object.freeze({ pass: gateReasons.length === 0, reasons: gateReasons }),
+        summary: Object.freeze({
+            changedAuthoritativeRecordSets: changeSummary(preChange, postChange),
+            preChangeState: preChange.state,
+            postChangeState: postChange.state,
+            assuranceState: assurance.result.review.state,
+        }),
+        evidence: Object.freeze({ preChange, postChange, assurance }),
+        limitations: Object.freeze([
+            'This packet is assembled only from analyst-supplied observations and planning metadata and makes no network request or configuration change.',
+            'A ready result means the supplied bounded checks passed; it does not prove control, propagation completion, successful recovery, or absence of unobserved dependencies.',
+            'The integrity digest detects later changes to this packet but does not authenticate its author. Use a separately managed signing key when signer authentication is required.',
+        ]),
+    });
+    return Object.freeze({
+        ...unsigned,
+        integrity: Object.freeze({
+            algorithm: 'SHA-256',
+            digestSha256: await sha256ArtifactDigest(unsigned),
+        }),
+    });
+}
+export function formatDomainChangePacket(packet) {
+    const lines = [
+        'Domain change assurance packet',
+        `Domain             ${packet.domain}`,
+        `Reference          ${packet.reference}`,
+        `State              ${packet.state}`,
+        `Changed record sets ${packet.summary.changedAuthoritativeRecordSets.length}`,
+        `Pre-change review  ${packet.summary.preChangeState}`,
+        `Post-change review ${packet.summary.postChangeState}`,
+        `Change plan        ${packet.summary.assuranceState}`,
+        `Integrity          ${packet.integrity.digestSha256}`,
+    ];
+    if (packet.gate.reasons.length) {
+        lines.push('', 'Review reasons:');
+        for (const reason of packet.gate.reasons)
+            lines.push(`  - ${reason}`);
+    }
+    lines.push('', 'Limitations:');
+    for (const limitation of packet.limitations)
+        lines.push(`  - ${limitation}`);
+    return `${lines.join('\n')}\n`;
+}