@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/lib/ct-search.mjs

@@ -8,13 +8,13 @@
 // Express server and the Netlify Functions.
 import { parse } from 'tldts';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { normalizeCtQuery } from "./ct-query.mjs";
+import { normalizeCtQuery } from "../packages/analysis/ct-query.mjs";
 import { safeFetch, readTextCapped } from "./safe-fetch.mjs";
 import { whoisleuthRequestHeaders } from "./outbound-identity.mjs";
 import { createObservation } from "../packages/evidence/observation.mjs";
-import { isValidAsciiHostname } from "./hostname.mjs";
+import { isValidAsciiHostname } from "../packages/contracts/domain-name.mjs";
 import { normalizeCtTimestamp } from "../packages/evidence/observation.mjs";
-import { MAX_CT_RESPONSE_CERTIFICATE_GROUPS, MAX_CT_RESPONSE_DOMAINS_PER_GROUP, MAX_CT_RESPONSE_HOSTNAMES_PER_GROUP, MAX_CT_RESPONSE_HOSTNAMES_PER_MATCH, MAX_CT_RESPONSE_RESULTS, MAX_CT_RESPONSE_TIMESTAMP_LENGTH, } from "./ct-response-bounds.mjs";
+import { MAX_CT_RESPONSE_CERTIFICATE_GROUPS, MAX_CT_RESPONSE_DOMAINS_PER_GROUP, MAX_CT_RESPONSE_HOSTNAMES_PER_GROUP, MAX_CT_RESPONSE_HOSTNAMES_PER_MATCH, MAX_CT_RESPONSE_RESULTS, MAX_CT_RESPONSE_TIMESTAMP_LENGTH, } from "../packages/analysis/ct-response-bounds.mjs";
 const CRT_SH_TIMEOUT_MS = 20000;
 const MAX_RESULTS = MAX_CT_RESPONSE_RESULTS;
 // crt.sh's response size scales with how many certificates ever matched the
@@ -38,6 +38,27 @@ const RETRY_DELAY_MS = 1500;
 // delay before a status-code retry above), so this caps the worst case at
 // two attempts (~40s) instead of stacking on top of MAX_RETRIES.
 const MAX_TIMEOUT_RETRIES = 1;
+const COLLECTION_ERRORS = {
+    CT_TIMEOUT: [504, 'Certificate search timed out. Try a narrower keyword or try again later.'],
+    CT_OVERLOADED: [503, 'Certificate search is temporarily overloaded. Try again later.'],
+    CT_QUERY_TOO_BROAD: [422, 'Certificate search returned too many results. Try a narrower keyword.'],
+    CT_INVALID_RESPONSE: [502, 'Certificate search returned invalid UTF-8 or an unexpected response format (expected a JSON array). Try again later.'],
+    CT_UPSTREAM_ERROR: [502, 'Certificate search could not retrieve a response from its source. Try again later.'],
+};
+export class CtCollectionError extends Error {
+    code;
+    constructor(code) {
+        super(COLLECTION_ERRORS[code][1]);
+        this.code = code;
+        this.name = 'CtCollectionError';
+    }
+}
+/** Only this finite collection vocabulary may cross an HTTP error boundary. */
+export function ctCollectionErrorResponse(error) {
+    return error instanceof CtCollectionError
+        ? { statusCode: COLLECTION_ERRORS[error.code][0], body: { error: COLLECTION_ERRORS[error.code][1], errorCode: error.code } }
+        : null;
+}
 // Row-count defense: a hostile or malformed response could fit a very large
 // number of tiny rows into the 5 MB byte cap and impose excessive
 // iteration/set overhead after parsing. Legitimate responses under the byte
@@ -75,61 +96,76 @@ function normalizeHostname(raw) {
 function delay(ms, signal) {
     return sleep(ms, undefined, signal ? { signal } : {});
 }
-async function fetchCrtSh(keyword, attempt = 0, dependencies = {}) {
+async function fetchCrtSh(keyword, dependencies = {}) {
     dependencies.signal?.throwIfAborted();
     const fetcher = dependencies.fetcher || safeFetch;
     const wait = dependencies.delay || delay;
-    const controller = new AbortController();
-    const signal = dependencies.signal ? AbortSignal.any([dependencies.signal, controller.signal]) : controller.signal;
-    const timeout = setTimeout(() => controller.abort(), CRT_SH_TIMEOUT_MS);
-    try {
-        let res;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        dependencies.signal?.throwIfAborted();
+        const controller = new AbortController();
+        const signal = dependencies.signal ? AbortSignal.any([dependencies.signal, controller.signal]) : controller.signal;
+        const timeout = setTimeout(() => controller.abort(), CRT_SH_TIMEOUT_MS);
+        let retryDelay = 0;
         try {
-            res = await fetcher(`https://crt.sh/?q=${encodeURIComponent(keyword)}&output=json`, {
+            const res = await fetcher(`https://crt.sh/?q=${encodeURIComponent(keyword)}&output=json`, {
                 headers: whoisleuthRequestHeaders({ Accept: 'application/json' }),
                 signal,
             }, 0);
-        }
-        catch (err) {
-            dependencies.signal?.throwIfAborted();
-            if (!(err instanceof Error) || err.name !== 'AbortError')
-                throw err;
-            if (attempt < MAX_TIMEOUT_RETRIES)
-                return fetchCrtSh(keyword, attempt + 1, dependencies);
-            throw new Error(`crt.sh took too long to respond (>${CRT_SH_TIMEOUT_MS / 1000}s per attempt, ${attempt + 1} attempts) - ` +
-                "it can be slow for broad search terms or under heavy load; try a narrower keyword or try again shortly.");
-        }
-        if (!res.ok) {
-            // Not reading this body - release it explicitly instead of leaving an
-            // unconsumed stream (and the connection it's tied to) open until
-            // undici's own idle-timeout eventually notices.
-            await res.body?.cancel().catch(() => { });
-            if (RETRYABLE_STATUSES.has(res.status) && attempt < MAX_RETRIES) {
-                await wait(RETRY_DELAY_MS * (attempt + 1), dependencies.signal);
-                dependencies.signal?.throwIfAborted();
-                return fetchCrtSh(keyword, attempt + 1, dependencies);
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => { });
+                if (RETRYABLE_STATUSES.has(res.status) && attempt < MAX_RETRIES) {
+                    retryDelay = RETRY_DELAY_MS * (attempt + 1);
+                }
+                else {
+                    throw new CtCollectionError(RETRYABLE_STATUSES.has(res.status) || res.status === 429 ? 'CT_OVERLOADED' : 'CT_UPSTREAM_ERROR');
+                }
+            }
+            else {
+                let text;
+                try {
+                    const body = await readTextCapped(res, CRT_SH_MAX_BYTES, { fatalUtf8: true });
+                    signal.throwIfAborted();
+                    if (body.truncated)
+                        throw new CtCollectionError('CT_QUERY_TOO_BROAD');
+                    text = body.text;
+                }
+                catch (error) {
+                    // Preserve transport/deadline failures for the attempt retry below.
+                    if (error instanceof TypeError && !signal.aborted) {
+                        throw new CtCollectionError('CT_INVALID_RESPONSE');
+                    }
+                    throw error;
+                }
+                let data;
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    throw new CtCollectionError('CT_INVALID_RESPONSE');
+                }
+                if (!Array.isArray(data))
+                    throw new CtCollectionError('CT_INVALID_RESPONSE');
+                if (data.length > MAX_CT_ROWS)
+                    throw new CtCollectionError('CT_QUERY_TOO_BROAD');
+                return data;
             }
-            throw new Error(RETRYABLE_STATUSES.has(res.status)
-                ? `crt.sh is temporarily overloaded (${res.status} after ${attempt + 1} attempts) - it's a free public service that intermittently struggles under load; try again in a moment.`
-                : `crt.sh returned ${res.status}`);
-        }
-        const { text, truncated } = await readTextCapped(res, CRT_SH_MAX_BYTES, { fatalUtf8: true });
-        signal.throwIfAborted();
-        if (truncated) {
-            throw new Error(`crt.sh returned more than ${CRT_SH_MAX_BYTES / (1024 * 1024)}MB of results for "${keyword}" - try a narrower/more specific keyword.`);
         }
-        const data = JSON.parse(text);
-        if (!Array.isArray(data)) {
-            throw new Error('crt.sh returned an unexpected response format (expected a JSON array).');
+        catch (error) {
+            dependencies.signal?.throwIfAborted();
+            if (!controller.signal.aborted && (!(error instanceof Error) || error.name !== 'AbortError'))
+                throw error;
+            if (attempt >= MAX_TIMEOUT_RETRIES)
+                throw new CtCollectionError('CT_TIMEOUT');
         }
-        if (data.length > MAX_CT_ROWS) {
-            throw new Error(`crt.sh returned too many rows (${data.length}) for "${keyword}" - try a narrower keyword.`);
+        finally {
+            // End this attempt before delay/retry: body reads share the same deadline
+            // as headers, and earlier timers cannot fire during a later attempt.
+            clearTimeout(timeout);
         }
-        return data;
-    }
-    finally {
-        clearTimeout(timeout);
+        if (retryDelay)
+            await wait(retryDelay, dependencies.signal);
     }
+    throw new CtCollectionError('CT_UPSTREAM_ERROR');
 }
 // ---------------------------------------------------------------------------
 // Certificate identity
@@ -485,7 +521,7 @@ async function searchCertificateTransparency(keyword, dependencies = {}) {
             }),
         };
     }
-    const data = await fetchCrtSh(trimmed, 0, dependencies);
+    const data = await fetchCrtSh(trimmed, dependencies);
     const summary = summarizeCtResults(data);
     return {
         certCount: data.length,

package/lib/dmarc-discovery.mjs

@@ -0,0 +1,62 @@
+import { isValidAsciiHostname } from "../packages/contracts/domain-name.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { parseDmarcRecords } from "./domain-posture-parsers.mjs";
+export function requireDmarcDomain(domain) {
+    if (typeof domain !== 'string' || domain.length > 253 || !isValidAsciiHostname(domain) || domain !== domain.toLowerCase()) {
+        throw new TypeError('The additional DNS review requires a normalised domain.');
+    }
+}
+export function dmarcPolicyObservation(owner, observation) {
+    const records = observation.records;
+    let bytes = 0;
+    const admitted = Array.isArray(records) && records.length <= 64 && records.every(raw => {
+        const parts = typeof raw === 'string' ? [raw] : raw;
+        return Array.isArray(parts) && parts.length <= 256 && parts.every(part => {
+            if (typeof part !== 'string' || part.length > 4096)
+                return false;
+            bytes += Buffer.byteLength(part, 'utf8');
+            return bytes <= 65_536;
+        });
+    });
+    const parsed = parseDmarcRecords(admitted ? records : []);
+    const unavailable = Boolean(observation.error) || !admitted;
+    const psd = parsed.tags.psd?.toLowerCase() ?? 'u';
+    const valid = !unavailable && parsed.valid && ['u', 'n', 'y'].includes(psd);
+    const incomplete = unavailable || (!valid && parsed.records.length === 1);
+    const state = unavailable ? 'unavailable' : valid ? 'observed' : parsed.records.length ? 'invalid' : 'not found';
+    const description = valid
+        ? `p=${parsed.policy}; sp=${parsed.subdomainPolicy}; np=${parsed.nonexistentSubdomainPolicy}; psd=${psd}; test=${parsed.testMode ? 'yes' : 'no'}`
+        : state;
+    const time = typeof observation.observedAt === 'string' && observation.observedAt.length <= 64
+        ? normalizeExplicitIsoTimestamp(observation.observedAt) : null;
+    return { owner, parsed, psd, valid, unavailable, incomplete,
+        record: `Recursive DNS TXT _dmarc.${owner} · ${time ?? 'time unavailable'} · ${description}` };
+}
+/** RFC 9989 sections 4.10–4.10.2: at most eight owners, never PSL inference. */
+export async function walkDmarcTree(domain, exact, resolve, purpose) {
+    requireDmarcDomain(domain);
+    const rows = [dmarcPolicyObservation(domain, exact)];
+    const first = rows[0];
+    const labels = domain.split('.');
+    let next = labels.length >= 8 ? labels.slice(-7) : labels.slice(1);
+    const policyOnly = purpose === 'policy' && first.valid;
+    if (!policyOnly && !first.unavailable && !(first.valid && ['n', 'y'].includes(first.psd))) {
+        while (next.length) {
+            const owner = next.join('.');
+            const row = dmarcPolicyObservation(owner, await resolve(`_dmarc.${owner}`));
+            rows.push(row);
+            if (row.unavailable || (row.valid && ['n', 'y'].includes(row.psd)))
+                break;
+            next = next.slice(1);
+        }
+    }
+    const available = rows.filter(row => row.valid);
+    const boundary = available.find(row => row.psd === 'n' || (row.psd === 'y' && row.owner !== domain));
+    const incomplete = rows.some(row => row.incomplete);
+    // An exact policy alone does not establish the organisational boundary.
+    const organisationalDomain = incomplete || (policyOnly && !['n', 'y'].includes(first.psd)) ? null
+        : boundary?.psd === 'y'
+            ? labels.slice(-(boundary.owner.split('.').length + 1)).join('.')
+            : boundary?.owner ?? available.at(-1)?.owner ?? domain;
+    return { rows, available, boundary, incomplete, organisationalDomain };
+}

package/lib/dns-convergence-review.mjs

@@ -1,14 +1,18 @@
 import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
 import { normaliseRdata } from "./zone-intent-review.mjs";
+import { dnsQueryState, normaliseDnsQueryCoverage } from "./dns-query-coverage.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 DNS_CONVERGENCE_INPUT_VERSION = 2;
+export const SUPPORTED_DNS_CONVERGENCE_INPUT_VERSIONS = Object.freeze([1, DNS_CONVERGENCE_INPUT_VERSION]);
+export const DNS_CONVERGENCE_REVIEW_VERSION = 2;
 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 COVERED_SNAPSHOT_KEYS = new Set([...SNAPSHOT_KEYS, 'queries']);
 const RECORD_KEYS = new Set(['owner', 'type', 'value', 'ttl']);
 function type(value, label) {
     const candidate = requireBoundedString(value, label, 16).toUpperCase();
@@ -83,8 +87,8 @@ function expectedRows(value, apex) {
 }
 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.`);
+    if (input.schema !== DNS_CONVERGENCE_INPUT_SCHEMA || !SUPPORTED_DNS_CONVERGENCE_INPUT_VERSIONS.includes(input.version)) {
+        throw new TypeError(`DNS convergence input must use ${DNS_CONVERGENCE_INPUT_SCHEMA} version 1 or ${DNS_CONVERGENCE_INPUT_VERSION}.`);
     }
     exactKeys(input, ROOT_KEYS, 'DNS convergence input');
     const apex = requireDomainName(input.domain, 'domain');
@@ -93,9 +97,10 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
         throw new TypeError(`snapshots must contain between 2 and ${MAX_DNS_CONVERGENCE_SNAPSHOTS} entries.`);
     }
     let recordCount = 0;
+    let queryCount = 0;
     const snapshots = input.snapshots.map((raw, index) => {
         const item = requireRecord(raw, `snapshots[${index}]`);
-        exactKeys(item, SNAPSHOT_KEYS, `snapshots[${index}]`);
+        exactKeys(item, input.version === 1 ? SNAPSHOT_KEYS : COVERED_SNAPSHOT_KEYS, `snapshots[${index}]`);
         if (!Array.isArray(item.records))
             throw new TypeError(`snapshots[${index}].records must be an array.`);
         recordCount += item.records.length;
@@ -104,12 +109,20 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
         const observationState = state(item.state, `snapshots[${index}].state`);
         if (observationState === 'unavailable' && item.records.length)
             throw new TypeError(`snapshots[${index}] cannot contain records when unavailable.`);
+        const records = Object.freeze(item.records.map((entry, recordIndex) => record(entry, apex, `snapshots[${index}].records[${recordIndex}]`)));
+        const queries = normaliseDnsQueryCoverage(item.queries, {
+            legacy: input.version === 1, label: `snapshots[${index}].queries`,
+            maximum: MAX_DNS_CONVERGENCE_RECORDS - queryCount, state: observationState, records,
+            owner: (value, label) => owner(value, apex, label), type,
+        });
+        queryCount += queries.length;
         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}]`))),
+            records,
+            queries,
         });
     }).sort((left, right) => left.observedAt.localeCompare(right.observedAt) || left.observer.localeCompare(right.observer));
     const observers = [...new Set(snapshots.map((item) => item.observer))];
@@ -118,7 +131,7 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
     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}`)),
+            ...snapshots.flatMap((item) => item.queries.map((entry) => `${entry.owner}\u0000${entry.type}`)),
         ])].sort();
     const rows = keys.map((key) => {
         const [recordOwner = '', recordType = ''] = key.split('\u0000');
@@ -134,7 +147,7 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
                 observer: snapshot.observer,
                 source: snapshot.source,
                 observedAt: snapshot.observedAt,
-                state: snapshot.state,
+                state: dnsQueryState(snapshot.queries, recordOwner, recordType),
                 values: Object.freeze(values),
                 cacheUntil,
             });
@@ -178,7 +191,7 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
             '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.',
+            'Only an explicitly observed query can establish an empty answer. Unqueried, partial and unavailable record types are never interpreted as absence; legacy inputs establish scope only for their supplied records.',
         ]),
     });
 }

package/lib/dns-delegation-health.mjs

@@ -6,7 +6,7 @@ import { promises as dns } from 'node:dns';
 import * as net from 'node:net';
 import { createObservation } from "../packages/evidence/observation.mjs";
 import { normalizeResolverMxRecord } from "../packages/evidence/domain-control-runtime.mjs";
-import { isValidAsciiHostname } from "./hostname.mjs";
+import { isValidAsciiHostname } from "../packages/contracts/domain-name.mjs";
 import { isPrivateAddress } from "./safe-fetch.mjs";
 const DNS_DELEGATION_HEALTH_VERSION = 1;
 const MAX_AUTHORITIES = 4;
@@ -465,8 +465,10 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
             .filter((primary) => primary !== null))];
     const soaSerialConflict = soaSerials.length > 1;
     const soaPrimaryConflict = soaPrimaries.length > 1;
-    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 glueInventoryComplete = (parentStatus === 'success' && parentNameservers.length > 0 && parentQuery.truncated !== true)
+        || (registry.nameservers.length > 0 && !registry.truncated);
+    const inBailiwick = eligibleAuthorities.filter((nameserver) => (nameserver === domain || nameserver.endsWith(`.${domain}`)));
+    const unobservedGlue = 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);
@@ -507,11 +509,13 @@ async function collectDnsDelegationHealth(domainValue, parentQueryValue, options
                 : soaPrimaryConflict
                     ? 'Authoritative servers published different SOA primary nameservers'
                     : 'Observed authority SOA serials and primary nameservers agree', retainedSoa.map((entry) => (`${entry.nameserver}: serial ${entry.soa.serial ?? 'unavailable'}, primary ${entry.soa.nsname ?? 'unavailable'}, refresh ${entry.soa.refresh ?? 'unavailable'}, retry ${entry.soa.retry ?? 'unavailable'}, expire ${entry.soa.expire ?? 'unavailable'}`)).join(' | ') || 'No complete SOA observation was available.', 'Confirm zone propagation and the intended SOA primary before relying on a DNS change or secondary-server state.'),
-        finding('in_bailiwick_glue', 'In-bailiwick glue', !inBailiwick.length ? 'healthy' : missingGlue.length ? 'warning' : 'healthy', !inBailiwick.length
-            ? 'No in-bailiwick nameserver requires registry glue'
-            : missingGlue.length
-                ? 'Registry glue was not observed for every in-bailiwick nameserver'
-                : 'Registry publication includes observed glue for each in-bailiwick nameserver', missingGlue.length ? `Missing observed glue: ${missingGlue.join(', ')}.` : `In-bailiwick nameservers: ${inBailiwick.join(', ') || 'none'}.`, 'Publish current A and AAAA glue at the registry for every in-bailiwick nameserver.'),
+        finding('in_bailiwick_glue', 'In-bailiwick glue', !glueInventoryComplete || unobservedGlue.length ? 'unknown' : 'healthy', !glueInventoryComplete
+            ? 'The delegated nameserver inventory is unavailable or incomplete'
+            : !inBailiwick.length
+                ? 'No in-bailiwick nameserver requires registry glue'
+                : unobservedGlue.length
+                    ? 'Registry address publication does not establish glue for every in-bailiwick nameserver'
+                    : 'Registry publication includes observed glue for each in-bailiwick nameserver', unobservedGlue.length ? `No address publication retained for: ${unobservedGlue.join(', ')}. Optional RDAP address fields and recursive NS answers do not establish that parent-zone glue is absent.` : `In-bailiwick nameservers: ${inBailiwick.join(', ') || 'none'}.`, 'Verify parent-zone glue with the registry or DNS operator before deciding whether an update is needed.'),
         finding('dnssec_delegation', 'DNSSEC delegation publication', dnssecMismatch ? 'warning'
             : registry.delegationSigned === null && registry.dsRecordCount === 0 ? 'unknown' : 'healthy', dnssecMismatch
             ? 'Registry DNSSEC fields are internally inconsistent'

package/lib/dns-inheritance-review.mjs

@@ -1,20 +1,16 @@
 import { promises as dns } from 'node:dns';
 import { parse as parseDomain } from 'tldts';
-import { parseDmarcRecords } from "./domain-posture-parsers.mjs";
+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 "./hostname.mjs";
-import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.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']);
-function requireDomain(domain) {
-    if (typeof domain !== 'string' || domain.length > 253 || !isValidAsciiHostname(domain) || domain !== domain.toLowerCase()) {
-        throw new TypeError('The additional DNS review requires a normalised domain.');
-    }
-}
 /** Explicit query parameter; malformed opt-ins never broaden collection. */
 export function parseInheritedDnsSelection(value) {
     if (value === undefined || value === '')
@@ -26,53 +22,11 @@ export function parseInheritedDnsSelection(value) {
 function check(id, label, status, summary, detail, records) {
     return { id, label, status, summary, detail, records, remediation: '' };
 }
-function policyObservation(owner, observation) {
-    const records = observation.records;
-    let bytes = 0;
-    const admitted = Array.isArray(records) && records.length <= 64 && records.every(raw => {
-        const parts = typeof raw === 'string' ? [raw] : raw;
-        return Array.isArray(parts) && parts.length <= 256 && parts.every(part => {
-            if (typeof part !== 'string' || part.length > 4096)
-                return false;
-            bytes += Buffer.byteLength(part, 'utf8');
-            return bytes <= 65_536;
-        });
-    });
-    const parsed = parseDmarcRecords(admitted ? records : []);
-    const unavailable = Boolean(observation.error) || !admitted;
-    const valid = !unavailable && parsed.valid && ['u', 'n', 'y'].includes(parsed.tags.psd?.toLowerCase() ?? 'u');
-    const state = unavailable ? 'unavailable' : valid ? 'observed' : parsed.records.length ? 'invalid' : 'not found';
-    const description = valid
-        ? `p=${parsed.policy}; sp=${parsed.subdomainPolicy}; np=${parsed.nonexistentSubdomainPolicy}; psd=${parsed.tags.psd?.toLowerCase() ?? 'u'}; test=${parsed.testMode ? 'yes' : 'no'}`
-        : state;
-    const time = typeof observation.observedAt === 'string' && observation.observedAt.length <= 64
-        ? normalizeExplicitIsoTimestamp(observation.observedAt) : null;
-    return { owner, parsed, valid, unavailable, record: `Recursive DNS TXT _dmarc.${owner} · ${time ?? 'time unavailable'} · ${description}` };
-}
 /** RFC 9989 sections 4.10–4.10.2; at most eight owners including the exact name. */
 export async function reviewInheritedDmarc(domain, exact, resolve) {
-    requireDomain(domain);
-    const rows = [policyObservation(domain, exact)];
-    const labels = domain.split('.');
-    let next = labels.length >= 8 ? labels.slice(-7) : labels.slice(1);
-    if (!rows[0].valid && !rows[0].unavailable) {
-        while (next.length) {
-            const owner = next.join('.');
-            const row = policyObservation(owner, await resolve(`_dmarc.${owner}`));
-            rows.push(row);
-            if (row.unavailable || (row.valid && ['n', 'y'].includes(row.parsed.tags.psd?.toLowerCase() ?? '')))
-                break;
-            next = next.slice(1);
-        }
-    }
-    const available = rows.filter(row => row.valid);
+    const { rows, available, boundary, incomplete, organisationalDomain } = await walkDmarcTree(domain, exact, resolve, 'policy');
     const explicit = rows[0].valid ? rows[0] : null;
-    const boundary = available.find(row => row.parsed.tags.psd?.toLowerCase() === 'n' || row.parsed.tags.psd?.toLowerCase() === 'y');
-    const organisational = boundary?.parsed.tags.psd?.toLowerCase() === 'y'
-        ? domain.split('.').slice(-(boundary.owner.split('.').length + 1)).join('.')
-        : boundary?.owner ?? available.at(-1)?.owner ?? null;
-    const selected = explicit ?? available.find(row => row.owner === organisational) ?? (boundary?.parsed.tags.psd?.toLowerCase() === 'y' ? boundary : null);
-    const incomplete = rows.some(row => row.unavailable || (!row.valid && row.parsed.records.length === 1));
+    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.';
@@ -90,7 +44,7 @@ function nameservers(value) {
     return names.every(name => name.length <= 253 && isValidAsciiHostname(name)) ? [...new Set(names)].sort() : null;
 }
 export async function reviewParentDelegation(domain, recursive, dependencies, signal) {
-    requireDomain(domain);
+    requireDmarcDomain(domain);
     const parsed = parseDomain(domain, { allowPrivateDomains: false });
     const child = parsed.domain;
     const parent = parsed.publicSuffix;
@@ -175,8 +129,8 @@ export async function reviewParentDelegation(domain, recursive, dependencies, si
     }
     return finish();
 }
-export async function collectDnsInheritanceChecks(domain, exact, recursive, options = {}, injected) {
-    requireDomain(domain);
+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;
@@ -188,10 +142,13 @@ export async function collectDnsInheritanceChecks(domain, exact, recursive, opti
         resolve4: (name) => resolver.resolve4(name), resolve6: (name) => resolver.resolve6(name),
         exchange: defaultTcpExchange, now: () => new Date(),
     };
-    const resolve = async (owner) => {
+    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() };
         }
@@ -200,17 +157,50 @@ export async function collectDnsInheritanceChecks(domain, exact, recursive, opti
             return { records: [], error: MISSING.has(String(error?.code)) ? null : 'DNS observation unavailable.', observedAt: dependencies.now().toISOString() };
         }
     };
-    const operations = [reviewInheritedDmarc(domain, exact, resolve), reviewParentDelegation(domain, recursive, dependencies, signal)];
+    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 {
-        return await Promise.all(operations);
-    }
-    catch {
+        const [policy, parent, reporting] = await Promise.allSettled(operations);
         options.signal?.throwIfAborted();
-        const settled = await Promise.allSettled(operations);
-        return settled.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 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 {
-        await Promise.allSettled(operations);
         signal.removeEventListener('abort', cancel);
         cancel();
     }

package/lib/dns-intelligence.mjs

@@ -1,5 +1,5 @@
 // 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';
@@ -11,7 +11,8 @@ 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 "./registrable-domain.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;
@@ -24,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'];
@@ -386,7 +386,7 @@ 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); });
     });
 }
@@ -396,6 +396,7 @@ async function query(factory, normalize, timeoutMs) {
         const unusable = !normalized.records.length && (normalized.truncated || normalized.discarded > 0);
         return {
             status: unusable ? 'error' : normalized.records.length ? 'success' : 'not_found',
+            detail: unusable ? 'invalid_response' : normalized.records.length ? 'records' : 'empty_answer',
             records: normalized.records,
             error: unusable ? 'The returned record family could not be retained completely; absence is unknown.' : null,
             truncated: normalized.truncated,
@@ -403,9 +404,9 @@ async function query(factory, normalize, timeoutMs) {
         };
     }
     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) {
@@ -683,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,