@slicedearth/whoisleuth-cli 1.39.1 → 1.45.0

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`;
+}