@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/lib/domain-posture.mjs

@@ -7,6 +7,10 @@ import { nonEmptyErrorMessage } from "./error-detail.mjs";
 import { safeFetch, readTextCapped } from "./safe-fetch.mjs";
 import { whoisleuthRequestHeaders } from "./outbound-identity.mjs";
 import { classifyMxRecords } from "./dns-mx.mjs";
+import { collectDnsInheritanceReview } from "./dns-inheritance-review.mjs";
+import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
+import { DOMAIN_POSTURE_COMPARISON_VERSION, MAX_POSTURE_CHECK_RECORDS, POSTURE_CHECK_SOURCES } from "../packages/evidence/domain-posture-context.mjs";
+import { canonicalPostureRecords } from "../packages/evidence/domain-control-runtime.mjs";
 import { parseSpfRecords, parseDmarcRecords, parseMtaStsDnsRecords, parseMtaStsPolicy, parseTlsRptRecords, parseBimiRecords, parseDkimRecords, } from "./domain-posture-parsers.mjs";
 import { buildExternalDependencies, expandSpfPolicy, validateDmarcExternalReporting, } from "./domain-posture-analysis.mjs";
 const DNS_TIMEOUT_MS = 6000;
@@ -88,14 +92,23 @@ function withTimeout(promise, label, timeoutMs = DNS_TIMEOUT_MS, timers = {
     });
 }
 async function resolveDns(label, factory, timeoutMs = DNS_TIMEOUT_MS, timers) {
+    const completed = (result) => {
+        let observedAt = null;
+        try {
+            const at = timers?.now?.();
+            observedAt = at instanceof Date && Number.isFinite(at.getTime()) ? at.toISOString() : null;
+        }
+        catch { /* Unknown source time remains explicit. */ }
+        return { ...result, observedAt };
+    };
     try {
-        return { records: await withTimeout(factory(), label, timeoutMs, timers), error: null };
+        return completed({ records: await withTimeout(factory(), label, timeoutMs, timers), error: null });
     }
     catch (err) {
         const error = errorRecord(err);
         if (typeof error.code === 'string' && MISSING_DNS_CODES.has(error.code))
-            return { records: [], error: null };
-        return { records: [], error: nonEmptyErrorMessage(err, String(err)) };
+            return completed({ records: [], error: null });
+        return completed({ records: [], error: nonEmptyErrorMessage(err, String(err)) });
     }
 }
 function check(id, label, status, summary, { detail = '', records = [], remediation = '' } = {}) {
@@ -189,11 +202,18 @@ function dmarcCheck(query, authorizations = []) {
         parsed.failureReporting ? 'Failure reporting is configured.' : 'No failure reporting destination is configured.',
         ...parsed.issues,
     ];
-    const external = authorizations.filter((authorization) => authorization.state !== 'self');
-    const unresolvedExternal = external.filter((authorization) => authorization.state !== 'authorized');
-    if (external.length > 0) {
-        details.push(`${external.length} external reporting destination${external.length === 1 ? '' : 's'} checked; `
-            + `${unresolvedExternal.length} could not be authorized.`);
+    const unresolvedExternal = authorizations.filter((authorization) => !['self', 'authorized'].includes(authorization.state));
+    const intendedDestinations = parsed.aggregateDestinations.length + parsed.failureDestinations.length;
+    const omittedDestinations = Math.max(0, intendedDestinations - authorizations.length);
+    if (omittedDestinations) {
+        details.push(`Reporting authorisation coverage: ${authorizations.length} of ${intendedDestinations} destinations reviewed; ${omittedDestinations} not checked within the bounded collection. Omitted destinations are not assumed authorised.`);
+    }
+    if (authorizations.length > 0) {
+        details.push(`${authorizations.length} reporting destination${authorizations.length === 1 ? '' : 's'} reviewed; `
+            + `${unresolvedExternal.length} need further evidence.`);
+    }
+    if (unresolvedExternal.some(item => item.state === 'unavailable')) {
+        details.push('An unknown organisational boundary or unavailable query does not establish a missing authorisation requirement.');
     }
     if (parsed.testMode) {
         return check('dmarc', 'DMARC', 'warning', 'Policy is in test mode (t=y)', {
@@ -213,11 +233,11 @@ function dmarcCheck(query, authorizations = []) {
             remediation: 'Set sp and np to quarantine or reject unless weaker subdomain treatment is intentional.',
         });
     }
-    if (unresolvedExternal.length > 0) {
-        return check('dmarc', 'DMARC', 'warning', `Enforced at p=${parsed.policy}; external reporting authorization is incomplete`, {
+    if (unresolvedExternal.length > 0 || omittedDestinations > 0) {
+        return check('dmarc', 'DMARC', 'warning', `Enforced at p=${parsed.policy}; reporting authorisation is incomplete`, {
             detail: `${details.join(' ')} ${unresolvedExternal.map((authorization) => `${authorization.destination}: ${authorization.state}.`).join(' ')}`,
             records: parsed.records,
-            remediation: 'Publish the required external reporting authorisation record or remove the unavailable destination.',
+            remediation: 'Review unresolved destinations and their organisational boundaries, then confirm any required external reporting authorisation before relying on delivery.',
         });
     }
     if (!parsed.aggregateReporting) {
@@ -332,7 +352,11 @@ function matchesMtaPattern(host, pattern) {
     const normalizedPattern = String(pattern || '').toLowerCase().replace(/\.+$/, '');
     if (normalizedPattern.startsWith('*.')) {
         const suffix = normalizedPattern.slice(1);
-        return normalizedHost.endsWith(suffix) && normalizedHost.length > suffix.length;
+        if (!normalizedHost.endsWith(suffix))
+            return false;
+        const label = normalizedHost.slice(0, -suffix.length);
+        // MTA-STS permits a wildcard for exactly one leftmost DNS label.
+        return /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label);
     }
     return normalizedHost === normalizedPattern;
 }
@@ -565,10 +589,11 @@ function defensiveMailProfileCheck(profile, input) {
 function registrationLockCheck(registry) {
     if (registry.error)
         return queryFailureCheck('registration_lock', 'Registration controls', registry.error);
-    const statuses = registry.statuses.map((status) => status.toLowerCase().replace(/[^a-z]/gu, ''));
+    const statuses = canonicalPostureRecords('registration_lock', registry.statuses) ?? [];
     if (statuses.length === 0) {
         return check('registration_lock', 'Registration controls', 'info', 'Registry lock state is unavailable', {
             detail: 'No normalised EPP status was returned. This does not describe registrar account security.',
+            records: registry.statuses,
         });
     }
     const transferLocks = statuses.filter((status) => ['clienttransferprohibited', 'servertransferprohibited'].includes(status));
@@ -635,11 +660,36 @@ function buildPostureReport(domain, input) {
         ...(input.registry && input.nameservers ? [nameserverCheck(input.nameservers, input.registry)] : []),
     ];
     const summary = { pass: 0, warning: 0, danger: 0, info: 0 };
-    for (const item of checks)
+    for (const item of checks) {
         summary[item.status] += 1;
+        const source = POSTURE_CHECK_SOURCES[item.id];
+        const query = item.id === 'nameservers' ? input.nameservers : item.id === 'mx' ? input.mx : item.id === 'caa' ? input.caa : undefined;
+        const registry = item.id === 'registration_lock' ? input.registry : undefined;
+        if (!source || (!query && !registry))
+            continue;
+        const omittedRecords = Math.max(0, item.records.length - MAX_POSTURE_CHECK_RECORDS);
+        const records = item.records.slice(0, MAX_POSTURE_CHECK_RECORDS);
+        const error = query?.error ?? registry?.error;
+        const retained = canonicalPostureRecords(item.id, records);
+        const rawRecords = query?.records ?? registry?.statuses ?? [];
+        const raw = item.id === 'caa'
+            ? canonicalPostureRecords(item.id, rawRecords.map((record) => record && typeof record === 'object' ? caaDisplay(record) : record))
+            : canonicalPostureRecords(item.id, rawRecords);
+        const complete = !error && omittedRecords === 0 && retained !== null && raw !== null
+            && retained.length === raw.length && retained.every((value, index) => value === raw[index])
+            && (!registry || (registry.statusesComplete === true && records.length > 0));
+        item.sourceContext = {
+            version: DOMAIN_POSTURE_COMPARISON_VERSION, source,
+            observedAt: normalizeExplicitIsoTimestamp(query?.observedAt ?? registry?.observedAt),
+            state: error ? 'unavailable' : complete ? 'complete' : 'partial',
+            omittedRecords: complete ? 0 : omittedRecords || null,
+        };
+        item.records = records;
+    }
     return { domain, summary, checks };
 }
-async function fetchMtaStsPolicy(domain, fetcher = safeFetch) {
+async function fetchMtaStsPolicy(domain, fetcher = safeFetch, signal) {
+    signal?.throwIfAborted();
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), POLICY_TIMEOUT_MS);
     try {
@@ -648,7 +698,7 @@ async function fetchMtaStsPolicy(domain, fetcher = safeFetch) {
         // following HTTP redirects for policy discovery. A zero-hop safe fetch
         // also keeps the returned body bound to the required policy host/path.
         const res = await fetcher(url, {
-            signal: controller.signal,
+            signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal,
             headers: whoisleuthRequestHeaders({ Accept: 'text/plain' }),
         }, 0);
         if (res.status !== 200) {
@@ -659,11 +709,13 @@ async function fetchMtaStsPolicy(domain, fetcher = safeFetch) {
             return { text: '', contentType: res.headers.get('content-type'), error: `Policy endpoint returned HTTP ${res.status}.` };
         }
         const body = await readTextCapped(res, MAX_POLICY_BYTES);
+        signal?.throwIfAborted();
         if (body.truncated)
             return { text: '', contentType: res.headers.get('content-type'), error: `Policy exceeds ${MAX_POLICY_BYTES} bytes.` };
         return { text: body.text, contentType: res.headers.get('content-type'), error: null };
     }
     catch (err) {
+        signal?.throwIfAborted();
         return {
             text: '',
             contentType: null,
@@ -676,17 +728,8 @@ async function fetchMtaStsPolicy(domain, fetcher = safeFetch) {
         clearTimeout(timeout);
     }
 }
-async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelectors = [], mailProtectionProfile = 'standard', } = {}, dependencies = {
-    resolveTxt: (name) => dns.resolveTxt(name),
-    resolveMx: (name) => dns.resolveMx(name),
-    resolveNs: (name) => dns.resolveNs(name),
-    resolveCaa: (name) => dns.resolveCaa(name),
-    fetchRdapRecord,
-    fetchMtaStsPolicy: (name) => fetchMtaStsPolicy(name),
-    now: () => new Date(),
-    setTimer: (callback, milliseconds) => setTimeout(callback, milliseconds),
-    clearTimer: (handle) => clearTimeout(handle),
-}) {
+async function collectDomainPosture(domain, { dkimSelectors = [], retiredDkimSelectors = [], mailProtectionProfile = 'standard', includeInheritedDns, signal, }, dependencies) {
+    signal?.throwIfAborted();
     const normalizedDomain = normalizeAuditDomain(domain);
     if (!normalizedDomain)
         throw new Error('Invalid domain name for posture audit.');
@@ -717,10 +760,11 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
                 ...await resolveDns(`TXT ${selector}._domainkey.${domain}`, () => dependencies.resolveTxt(`${selector}._domainkey.${domain}`), DNS_TIMEOUT_MS, dependencies),
             })),
         ]),
-        dependencies.fetchRdapRecord('domain', domain).catch((err) => ({
+        dependencies.fetchRdapRecord('domain', domain, signal ? { signal } : {}).catch((err) => ({
             error: nonEmptyErrorMessage(err, String(err)),
         })),
     ]);
+    signal?.throwIfAborted();
     const parsedMtaDns = mtaStsDns.error ? null : parseMtaStsDnsRecords(mtaStsDns.records);
     const enrichmentStartedAt = dependencies.now();
     if (!(enrichmentStartedAt instanceof Date) || !Number.isFinite(enrichmentStartedAt.getTime())) {
@@ -728,6 +772,7 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
     }
     const enrichmentDeadline = enrichmentStartedAt.getTime() + POSTURE_ENRICHMENT_DEADLINE_MS;
     const resolveEnrichmentTxt = (name) => {
+        signal?.throwIfAborted();
         const observedAt = dependencies.now();
         if (!(observedAt instanceof Date) || !Number.isFinite(observedAt.getTime())) {
             return Promise.resolve({ records: [], error: 'The bounded posture-enrichment clock was unavailable.' });
@@ -737,11 +782,22 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
             return Promise.resolve({ records: [], error: 'The bounded posture-enrichment deadline was reached.' });
         return resolveDns(`TXT ${name}`, () => dependencies.resolveTxt(name), Math.min(DNS_TIMEOUT_MS, remaining), dependencies);
     };
-    const [mtaStsPolicy, spfExpansion, dmarcAuthorizations] = await Promise.all([
-        parsedMtaDns?.valid ? dependencies.fetchMtaStsPolicy(domain) : Promise.resolve(null),
+    const enrichment = [
+        parsedMtaDns?.valid ? dependencies.fetchMtaStsPolicy(domain, signal) : Promise.resolve(null),
         expandSpfPolicy(domain, spf, resolveEnrichmentTxt),
-        validateDmarcExternalReporting(domain, dmarc, resolveEnrichmentTxt),
-    ]);
+        includeInheritedDns === true
+            ? (dependencies.collectDnsInheritanceReview
+                ? dependencies.collectDnsInheritanceReview(domain, dmarc, nameservers, signal ? { signal } : {})
+                : Promise.reject(new TypeError('The explicit DNS review collector is unavailable.')))
+            : validateDmarcExternalReporting(domain, dmarc, resolveEnrichmentTxt)
+                .then(dmarcAuthorizations => ({ checks: [], dmarcAuthorizations })),
+    ];
+    // A rejected policy request must not release the operation's capacity while
+    // other started enrichment collectors are still settling.
+    const [mtaStsPolicy, spfExpansion, dnsReview] = await Promise.all(enrichment)
+        .finally(() => Promise.allSettled(enrichment));
+    const { dmarcAuthorizations, checks: inheritanceChecks } = dnsReview;
+    signal?.throwIfAborted();
     const dnssec = !rdap
         ? { value: null, error: 'RDAP did not return a domain record.' }
         : 'error' in rdap
@@ -758,6 +814,8 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
             dsRecordCount: parsedDomain.dsData.length,
             dsDataTruncated: parsedDomain.dsDataTruncated,
             error: null,
+            observedAt: normalizeExplicitIsoTimestamp(rdap && !('error' in rdap) ? rdap.fetchedAt : null),
+            statusesComplete: parsedDomain.statusesTruncated === false && parsedDomain.serverTruncated === false,
         }
         : {
             statuses: [],
@@ -794,6 +852,10 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
     if (!(checkedAt instanceof Date) || !Number.isFinite(checkedAt.getTime())) {
         throw new TypeError('Domain-posture completion time must be valid.');
     }
+    for (const item of inheritanceChecks) {
+        report.checks.push(item);
+        report.summary[item.status] += 1;
+    }
     return {
         ...report,
         checkedAt: checkedAt.toISOString(),
@@ -805,4 +867,30 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
         externalDependencies,
     };
 }
+async function checkDomainPosture(domain, options = {}, dependencies) {
+    options.signal?.throwIfAborted();
+    // Cancelling one audit must never cancel another audit's resolver.
+    const resolver = dependencies ? null : new dns.Resolver();
+    const cancel = () => resolver?.cancel();
+    options.signal?.addEventListener('abort', cancel, { once: true });
+    try {
+        options.signal?.throwIfAborted();
+        return await collectDomainPosture(domain, options, dependencies ?? {
+            resolveTxt: name => resolver.resolveTxt(name),
+            resolveMx: name => resolver.resolveMx(name),
+            resolveNs: name => resolver.resolveNs(name),
+            resolveCaa: name => resolver.resolveCaa(name),
+            fetchRdapRecord,
+            fetchMtaStsPolicy: (name, signal) => fetchMtaStsPolicy(name, safeFetch, signal),
+            now: () => new Date(),
+            setTimer: (callback, milliseconds) => setTimeout(callback, milliseconds),
+            clearTimer: handle => clearTimeout(handle),
+            collectDnsInheritanceReview,
+        });
+    }
+    finally {
+        options.signal?.removeEventListener('abort', cancel);
+        cancel();
+    }
+}
 export { normalizeAuditDomain, normalizeDkimSelectors, normalizeMailProtectionProfile, matchesMtaPattern, fetchMtaStsPolicy, buildPostureReport, checkDomainPosture, };