@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/lib/domain-control-manifest.mjs

@@ -0,0 +1,382 @@
+import { createHash } from 'node:crypto';
+import { domainToASCII } from 'node:url';
+import { canonicalArtifactJson } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { exactKeys } from "./bounded-contract-normalizers.mjs";
+export const DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA = 'whoisleuth.domain-control-manifest-input';
+export const DOMAIN_CONTROL_MANIFEST_SCHEMA = 'whoisleuth.domain-control-manifest';
+export const DOMAIN_CONTROL_MANIFEST_VERSION = 1;
+export const DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA = 'whoisleuth.domain-control-review-input';
+export const DOMAIN_CONTROL_REVIEW_SCHEMA = 'whoisleuth.domain-control-review';
+export const DOMAIN_CONTROL_REVIEW_VERSION = 1;
+export const MAX_DOMAIN_CONTROL_ENTRIES = 100;
+export const MAX_DOMAIN_CONTROL_RECORDS = 32;
+const MANIFEST_KEYS = new Set(['schema', 'version', 'generatedAt', 'expiresAt', 'entries', 'limitations', 'integrity']);
+const MANIFEST_ENTRY_KEYS = new Set(['domain', 'nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock', 'renewalReviewAt', 'note']);
+const MANIFEST_INTEGRITY_KEYS = new Set(['algorithm', 'canonicalization', 'digestSha256']);
+const MANIFEST_INPUT_KEYS = new Set(['schema', 'version', 'expiresAt', 'entries']);
+const REVIEW_INPUT_KEYS = new Set(['schema', 'version', 'manifest', 'observations']);
+const OBSERVATION_KEYS = new Set(['domain', 'fields']);
+const OBSERVATION_FIELDS = new Set(['nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock']);
+const OBSERVATION_FIELD_KEYS = new Set(['state', 'values', 'source', 'observedAt']);
+const DOMAIN_CONTROL_LIMITATIONS = Object.freeze([
+    'This analyst-authored manifest records intended domain-control state. It does not collect evidence or change registrar, DNS, mail, or certificate configuration.',
+    'Empty desired fields are unconfigured rather than claims that a record should be absent.',
+]);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function boundedText(value, maximum = 300) {
+    if (typeof value !== 'string' || value.length > maximum * 4 || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    return value.replace(/\s+/gu, ' ').trim().slice(0, maximum) || null;
+}
+function timestamp(value) {
+    const text = boundedText(value, 64);
+    if (!text)
+        return null;
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function domain(value) {
+    const text = boundedText(value, 253)?.toLowerCase().replace(/\.$/u, '');
+    if (!text)
+        return null;
+    const ascii = domainToASCII(text);
+    if (!ascii || ascii.length > 253 || ascii.split('.').some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label)))
+        return null;
+    return ascii;
+}
+function hostnameList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.slice(0, MAX_DOMAIN_CONTROL_RECORDS * 4)
+            .map(domain)
+            .filter((item) => item !== null))]
+        .sort()
+        .slice(0, MAX_DOMAIN_CONTROL_RECORDS);
+}
+function textList(value, maximum = 300) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.slice(0, MAX_DOMAIN_CONTROL_RECORDS * 4)
+            .map((item) => boundedText(item, maximum)?.toLowerCase() ?? null)
+            .filter((item) => item !== null))]
+        .sort()
+        .slice(0, MAX_DOMAIN_CONTROL_RECORDS);
+}
+function spkiFingerprint(value) {
+    const text = boundedText(value, 64)?.toLowerCase();
+    return text && /^[a-f0-9]{64}$/u.test(text) ? text : null;
+}
+function normalizeEntry(value) {
+    const source = record(value);
+    const normalizedDomain = domain(source?.domain);
+    if (!source || !normalizedDomain)
+        return null;
+    const registrarLock = source.registrarLock === 'required' || source.registrarLock === 'not_required'
+        ? source.registrarLock
+        : null;
+    return Object.freeze({
+        domain: normalizedDomain,
+        nameservers: Object.freeze(hostnameList(source.nameservers)),
+        ds: Object.freeze(textList(source.ds, 500)),
+        mx: Object.freeze(hostnameList(source.mx)),
+        caa: Object.freeze(textList(source.caa, 500)),
+        tlsIssuer: boundedText(source.tlsIssuer, 300)?.toLowerCase() ?? null,
+        tlsSpkiSha256: spkiFingerprint(source.tlsSpkiSha256),
+        registrarLock,
+        renewalReviewAt: timestamp(source.renewalReviewAt),
+        note: boundedText(source.note, 500),
+    });
+}
+function unsignedManifest(value) {
+    return value;
+}
+function integrityDigest(value) {
+    return `sha256:${createHash('sha256').update(canonicalArtifactJson(value)).digest('hex')}`;
+}
+export function buildDomainControlManifest(input, generatedAtValue = new Date().toISOString()) {
+    const source = record(input);
+    if (!source || source.schema !== DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA || source.version !== 1) {
+        throw new TypeError(`Domain control manifest input must use ${DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(source, MANIFEST_INPUT_KEYS, 'Domain control manifest input');
+    const generatedAt = timestamp(generatedAtValue);
+    const expiresAt = timestamp(source.expiresAt);
+    if (!generatedAt || !expiresAt || Date.parse(expiresAt) <= Date.parse(generatedAt)) {
+        throw new TypeError('Domain control manifest expiry must be a valid time after generation.');
+    }
+    if (!Array.isArray(source.entries) || source.entries.length < 1 || source.entries.length > MAX_DOMAIN_CONTROL_ENTRIES) {
+        throw new TypeError(`Domain control manifest input must contain between 1 and ${MAX_DOMAIN_CONTROL_ENTRIES} entries.`);
+    }
+    const entries = source.entries.map((entry, index) => {
+        exactKeys(entry, MANIFEST_ENTRY_KEYS, `Domain control manifest input entry ${index + 1}`);
+        return normalizeEntry(entry);
+    });
+    if (entries.some((entry) => entry === null))
+        throw new TypeError('Domain control manifest contains an invalid entry.');
+    const normalizedEntries = entries;
+    const domains = new Set(normalizedEntries.map((entry) => entry.domain));
+    if (domains.size !== normalizedEntries.length)
+        throw new TypeError('Domain control manifest entries must use unique domains.');
+    const base = Object.freeze({
+        schema: DOMAIN_CONTROL_MANIFEST_SCHEMA,
+        version: DOMAIN_CONTROL_MANIFEST_VERSION,
+        generatedAt,
+        expiresAt,
+        entries: Object.freeze([...normalizedEntries].sort((left, right) => left.domain.localeCompare(right.domain))),
+        limitations: DOMAIN_CONTROL_LIMITATIONS,
+    });
+    return Object.freeze({
+        ...base,
+        integrity: Object.freeze({
+            algorithm: 'SHA-256',
+            canonicalization: 'sorted-json-v1',
+            digestSha256: integrityDigest(unsignedManifest(base)),
+        }),
+    });
+}
+export function verifyDomainControlManifest(value) {
+    const source = record(value);
+    const integrity = record(source?.integrity);
+    if (!source
+        || source.schema !== DOMAIN_CONTROL_MANIFEST_SCHEMA
+        || source.version !== DOMAIN_CONTROL_MANIFEST_VERSION
+        || !Array.isArray(source.entries)
+        || source.entries.length < 1
+        || source.entries.length > MAX_DOMAIN_CONTROL_ENTRIES
+        || !Array.isArray(source.limitations)
+        || source.limitations.length !== DOMAIN_CONTROL_LIMITATIONS.length
+        || source.limitations.some((limitation, index) => limitation !== DOMAIN_CONTROL_LIMITATIONS[index])
+        || !integrity
+        || integrity.algorithm !== 'SHA-256'
+        || integrity.canonicalization !== 'sorted-json-v1'
+        || typeof integrity.digestSha256 !== 'string'
+        || !/^sha256:[a-f0-9]{64}$/u.test(integrity.digestSha256)) {
+        throw new TypeError('Domain control manifest has an unsupported or malformed structure.');
+    }
+    exactKeys(source, MANIFEST_KEYS, 'Domain control manifest');
+    exactKeys(integrity, MANIFEST_INTEGRITY_KEYS, 'Domain control manifest integrity');
+    for (const [index, entry] of source.entries.entries()) {
+        exactKeys(entry, MANIFEST_ENTRY_KEYS, `Domain control manifest entry ${index + 1}`);
+    }
+    const generatedAt = timestamp(source.generatedAt);
+    const expiresAt = timestamp(source.expiresAt);
+    const entries = source.entries.map(normalizeEntry);
+    if (!generatedAt || !expiresAt || Date.parse(expiresAt) <= Date.parse(generatedAt) || entries.some((entry) => entry === null)) {
+        throw new TypeError('Domain control manifest has invalid normalised content.');
+    }
+    const normalizedEntries = entries;
+    if (new Set(normalizedEntries.map((entry) => entry.domain)).size !== normalizedEntries.length) {
+        throw new TypeError('Domain control manifest entries must use unique domains.');
+    }
+    const { integrity: _integrity, ...unsigned } = source;
+    const canonical = Object.freeze({
+        schema: DOMAIN_CONTROL_MANIFEST_SCHEMA,
+        version: DOMAIN_CONTROL_MANIFEST_VERSION,
+        generatedAt,
+        expiresAt,
+        entries: Object.freeze([...normalizedEntries].sort((left, right) => left.domain.localeCompare(right.domain))),
+        limitations: DOMAIN_CONTROL_LIMITATIONS,
+    });
+    let suppliedCanonical;
+    try {
+        suppliedCanonical = canonicalArtifactJson(unsigned);
+    }
+    catch {
+        throw new TypeError('Domain control manifest has invalid normalised content.');
+    }
+    if (suppliedCanonical !== canonicalArtifactJson(canonical)) {
+        throw new TypeError('Domain control manifest must use its canonical normalised content.');
+    }
+    if (`sha256:${createHash('sha256').update(suppliedCanonical).digest('hex')}` !== integrity.digestSha256) {
+        throw new TypeError('Domain control manifest failed its SHA-256 integrity check.');
+    }
+    return source;
+}
+function fieldValues(field, value) {
+    if (field === 'nameservers' || field === 'mx')
+        return hostnameList(value);
+    if (field === 'tlsSpkiSha256') {
+        const normalized = Array.isArray(value) ? value.map(spkiFingerprint).filter(Boolean) : [spkiFingerprint(value)].filter(Boolean);
+        return [...new Set(normalized)].sort().slice(0, MAX_DOMAIN_CONTROL_RECORDS);
+    }
+    if (field === 'registrarLock') {
+        const values = Array.isArray(value) ? value : [value];
+        return [...new Set(values.filter((item) => item === 'required' || item === 'not_required'))];
+    }
+    return textList(Array.isArray(value) ? value : [value], 500);
+}
+function normalizeObservation(value) {
+    const source = record(value);
+    const normalizedDomain = domain(source?.domain);
+    const rawFields = record(source?.fields);
+    if (!source || !normalizedDomain || !rawFields)
+        return null;
+    exactKeys(source, OBSERVATION_KEYS, 'Domain control observation');
+    exactKeys(rawFields, OBSERVATION_FIELDS, 'Domain control observation fields');
+    const fields = {};
+    for (const field of ['nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock']) {
+        const raw = record(rawFields[field]);
+        if (!raw)
+            continue;
+        exactKeys(raw, OBSERVATION_FIELD_KEYS, `Domain control observation field ${field}`);
+        const state = raw.state;
+        if (state !== 'observed' && state !== 'partial' && state !== 'unavailable' && state !== 'unsupported')
+            return null;
+        const sourceLabel = boundedText(raw.source, 120);
+        if (!sourceLabel)
+            return null;
+        fields[field] = Object.freeze({
+            state,
+            values: Object.freeze(fieldValues(field, raw.values)),
+            source: sourceLabel,
+            observedAt: timestamp(raw.observedAt),
+        });
+    }
+    return Object.freeze({ domain: normalizedDomain, fields: Object.freeze(fields) });
+}
+function desiredValues(entry, field) {
+    if (field === 'tlsIssuer')
+        return entry.tlsIssuer ? [entry.tlsIssuer] : [];
+    if (field === 'tlsSpkiSha256')
+        return entry.tlsSpkiSha256 ? [entry.tlsSpkiSha256] : [];
+    if (field === 'registrarLock')
+        return entry.registrarLock ? [entry.registrarLock] : [];
+    return [...entry[field]];
+}
+function compareField(entry, observation, field) {
+    const desired = desiredValues(entry, field);
+    if (!desired.length)
+        return Object.freeze({
+            field, state: 'not_configured', desired: Object.freeze([]), observed: Object.freeze([]), source: null, observedAt: null,
+            explanation: 'No desired value was configured for this field.',
+        });
+    const evidence = observation?.fields[field];
+    if (!evidence)
+        return Object.freeze({
+            field, state: 'unavailable', desired: Object.freeze(desired), observed: Object.freeze([]), source: null, observedAt: null,
+            explanation: 'No separately attributed observation was supplied for this field.',
+        });
+    if (evidence.state !== 'observed')
+        return Object.freeze({
+            field,
+            state: evidence.state,
+            desired: Object.freeze(desired),
+            observed: evidence.values,
+            source: evidence.source,
+            observedAt: evidence.observedAt,
+            explanation: evidence.state === 'partial'
+                ? 'The supplied observation was partial, so a difference is inconclusive.'
+                : `The supplied source reported this field as ${evidence.state}.`,
+        });
+    const aligned = desired.length === evidence.values.length && desired.every((item, index) => item === evidence.values[index]);
+    return Object.freeze({
+        field,
+        state: aligned ? 'aligned' : 'drift',
+        desired: Object.freeze(desired),
+        observed: evidence.values,
+        source: evidence.source,
+        observedAt: evidence.observedAt,
+        explanation: aligned
+            ? 'The complete supplied observation matches the desired value.'
+            : 'The complete supplied observation differs from the desired value.',
+    });
+}
+function renewalComparison(entry, now) {
+    if (!entry.renewalReviewAt)
+        return Object.freeze({
+            field: 'renewalReviewAt', state: 'not_configured', desired: Object.freeze([]), observed: Object.freeze([]), source: null, observedAt: null,
+            explanation: 'No renewal review date was configured.',
+        });
+    const due = Date.parse(entry.renewalReviewAt) <= Date.parse(now);
+    return Object.freeze({
+        field: 'renewalReviewAt', state: due ? 'due' : 'aligned', desired: Object.freeze([entry.renewalReviewAt]), observed: Object.freeze([]), source: null, observedAt: null,
+        explanation: due ? 'The configured renewal review date is due.' : 'The configured renewal review date is still in the future.',
+    });
+}
+export function reviewDomainControlManifest(input, generatedAtValue = new Date().toISOString()) {
+    const source = record(input);
+    if (!source || source.schema !== DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA || source.version !== 1) {
+        throw new TypeError(`Domain control review input must use ${DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(source, REVIEW_INPUT_KEYS, 'Domain control review input');
+    const generatedAt = timestamp(generatedAtValue);
+    if (!generatedAt)
+        throw new TypeError('Domain control review time is invalid.');
+    const manifest = verifyDomainControlManifest(source.manifest);
+    if (!Array.isArray(source.observations) || source.observations.length > MAX_DOMAIN_CONTROL_ENTRIES * 2) {
+        throw new TypeError('Domain control observations must be a bounded array.');
+    }
+    const observations = source.observations.map(normalizeObservation);
+    if (observations.some((item) => item === null))
+        throw new TypeError('Domain control review contains an invalid observation.');
+    const normalizedObservations = observations;
+    if (new Set(normalizedObservations.map((item) => item.domain)).size !== normalizedObservations.length) {
+        throw new TypeError('Domain control observations must use unique domains.');
+    }
+    const observationMap = new Map(normalizedObservations.map((item) => [item.domain, item]));
+    const fields = ['nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock'];
+    const domains = manifest.entries.map((entry) => {
+        const observation = observationMap.get(entry.domain) ?? null;
+        const comparisons = [...fields.map((field) => compareField(entry, observation, field)), renewalComparison(entry, generatedAt)];
+        const state = comparisons.some((item) => item.state === 'drift' || item.state === 'due')
+            ? 'drift'
+            : comparisons.some((item) => item.state === 'partial' || item.state === 'unavailable' || item.state === 'unsupported')
+                ? 'partial'
+                : 'aligned';
+        return Object.freeze({ domain: entry.domain, state, comparisons: Object.freeze(comparisons) });
+    });
+    const comparisons = domains.flatMap((item) => item.comparisons);
+    const counts = Object.fromEntries(['aligned', 'drift', 'partial', 'unavailable', 'unsupported', 'not_configured', 'due']
+        .map((state) => [state, comparisons.filter((item) => item.state === state).length]));
+    const expired = Date.parse(manifest.expiresAt) <= Date.parse(generatedAt);
+    return Object.freeze({
+        schema: DOMAIN_CONTROL_REVIEW_SCHEMA,
+        version: DOMAIN_CONTROL_REVIEW_VERSION,
+        generatedAt,
+        state: expired ? 'expired' : domains.some((item) => item.state === 'drift') ? 'drift' : domains.some((item) => item.state === 'partial') ? 'partial' : 'aligned',
+        manifest: Object.freeze({
+            generatedAt: manifest.generatedAt,
+            expiresAt: manifest.expiresAt,
+            digestSha256: manifest.integrity.digestSha256,
+            expired,
+        }),
+        counts: Object.freeze(counts),
+        domains: Object.freeze(domains),
+        ignoredObservationCount: normalizedObservations.filter((item) => !manifest.entries.some((entry) => entry.domain === item.domain)).length,
+        limitations: Object.freeze([
+            'This local review compares analyst-authored desired state with separately supplied observations and performs no collection or configuration change.',
+            'Only complete observations can produce drift. Partial, unavailable, unsupported, or missing evidence remains inconclusive.',
+            'A valid manifest digest or signature establishes file integrity, not the correctness of the desired state or supplied observations.',
+        ]),
+    });
+}
+export function formatDomainControlResult(value) {
+    if (value.schema === DOMAIN_CONTROL_MANIFEST_SCHEMA) {
+        return [
+            'Domain control manifest',
+            `Domains  ${value.entries.length}`,
+            `Expires  ${value.expiresAt}`,
+            `Digest   ${value.integrity.digestSha256}`,
+            '',
+            'The manifest records desired state only and performs no collection or configuration change.',
+            '',
+        ].join('\n');
+    }
+    return [
+        'Domain control review',
+        `State    ${value.state}`,
+        `Domains  ${value.domains.length}`,
+        `Drift    ${value.counts.drift ?? 0}`,
+        `Partial  ${(value.counts.partial ?? 0) + (value.counts.unavailable ?? 0) + (value.counts.unsupported ?? 0)}`,
+        `Due      ${value.counts.due ?? 0}`,
+        '',
+        ...value.domains.map((item) => `${item.domain}  ${item.state}`),
+        '',
+        ...value.limitations.map((item) => `Limitation: ${item}`),
+        '',
+    ].join('\n');
+}

package/lib/domain-posture.mjs

@@ -5,6 +5,7 @@ import { promises as dns } from 'node:dns';
 import { fetchRdapRecord } from "./rdap.mjs";
 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 { parseSpfRecords, parseDmarcRecords, parseMtaStsDnsRecords, parseMtaStsPolicy, parseTlsRptRecords, parseBimiRecords, parseDkimRecords, } from "./domain-posture-parsers.mjs";
 import { buildExternalDependencies, expandSpfPolicy, validateDmarcExternalReporting, } from "./domain-posture-analysis.mjs";
@@ -93,7 +94,7 @@ function spfCheck(query, expansion) {
     const parsed = parseSpfRecords(query.records);
     if (parsed.records.length === 0) {
         return check('spf', 'SPF', 'warning', 'No SPF policy published', {
-            remediation: 'Publish one SPF TXT record that authorizes every legitimate sender and ends in -all once verified.',
+            remediation: 'Publish one SPF TXT record that authorises every legitimate sender and ends in -all once verified.',
         });
     }
     if (!parsed.valid) {
@@ -118,7 +119,7 @@ function spfCheck(query, expansion) {
         ...parsed.issues,
     ];
     if (parsed.terminalPolicy === 'pass') {
-        return check('spf', 'SPF', 'danger', 'Policy authorizes every sender (+all)', {
+        return check('spf', 'SPF', 'danger', 'Policy authorises every sender (+all)', {
             detail: details.join(' '), records: parsed.records,
             remediation: 'Replace +all with an explicit sender allowlist and a restrictive terminal policy.',
         });
@@ -142,7 +143,7 @@ function spfCheck(query, expansion) {
     return check('spf', 'SPF', 'warning', `Policy ends in ${parsed.terminalPolicy || 'an unknown result'}`, {
         detail: details.join(' '), records: parsed.records,
         remediation: parsed.terminalPolicy === 'softfail'
-            ? 'Move from ~all to -all after confirming every legitimate sending service is authorized.'
+            ? 'Move from ~all to -all after confirming every legitimate sending service is authorised.'
             : 'Add a restrictive -all terminal policy after confirming every legitimate sending service.',
     });
 }
@@ -197,7 +198,7 @@ function dmarcCheck(query, authorizations = []) {
         return check('dmarc', 'DMARC', 'warning', `Enforced at p=${parsed.policy}; external reporting authorization is incomplete`, {
             detail: `${details.join(' ')} ${unresolvedExternal.map((authorization) => `${authorization.destination}: ${authorization.state}.`).join(' ')}`,
             records: parsed.records,
-            remediation: 'Publish the required external reporting authorization record or remove the unavailable destination.',
+            remediation: 'Publish the required external reporting authorisation record or remove the unavailable destination.',
         });
     }
     if (!parsed.aggregateReporting) {
@@ -251,7 +252,7 @@ function dnssecCheck(input) {
 function dnssecDelegationConsistencyCheck(input, registry) {
     if (registry.error) {
         return check('dnssec_delegation_consistency', 'DNSSEC delegation consistency', 'info', 'Registry evidence is unavailable', {
-            detail: 'DNSSEC delegation and retained DS records could not be compared because normalized registry evidence was unavailable.',
+            detail: 'DNSSEC delegation and retained DS records could not be compared because normalised registry evidence was unavailable.',
         });
     }
     if (input.error) {
@@ -273,7 +274,7 @@ function dnssecDelegationConsistencyCheck(input, registry) {
     }
     if (registry.dsDataTruncated) {
         return check('dnssec_delegation_consistency', 'DNSSEC delegation consistency', 'info', 'Retained DS evidence is incomplete', {
-            detail: 'The normalized registry response reported truncated DS data, so apparent disagreement is inconclusive.',
+            detail: 'The normalised registry response reported truncated DS data, so apparent disagreement is inconclusive.',
         });
     }
     if (value === 'signed' && !hasDsRecords) {
@@ -413,7 +414,7 @@ function bimiCheck(query, dmarcQuery) {
         && (dmarc.legacyPct === null || dmarc.legacyPct === 100);
     if (!enforcementReady) {
         return check('bimi', 'BIMI', 'warning', 'Record exists but DMARC is not BIMI-ready', {
-            detail: 'BIMI display generally requires enforced DMARC for the organizational domain and subdomains. Mailbox providers apply additional requirements.',
+            detail: 'BIMI display generally requires enforced DMARC for the organisational domain and subdomains. Mailbox providers apply additional requirements.',
             records: parsed.records,
             remediation: 'Enforce DMARC at quarantine or reject for the domain and subdomains before relying on BIMI.',
         });
@@ -533,7 +534,7 @@ function registrationLockCheck(registry) {
     const statuses = registry.statuses.map((status) => status.toLowerCase().replace(/[^a-z]/gu, ''));
     if (statuses.length === 0) {
         return check('registration_lock', 'Registration controls', 'info', 'Registry lock state is unavailable', {
-            detail: 'No normalized EPP status was returned. This does not describe registrar account security.',
+            detail: 'No normalised EPP status was returned. This does not describe registrar account security.',
         });
     }
     const transferLocks = statuses.filter((status) => ['clienttransferprohibited', 'servertransferprohibited'].includes(status));
@@ -608,7 +609,7 @@ async function fetchMtaStsPolicy(domain) {
         const url = `https://mta-sts.${domain}/.well-known/mta-sts.txt`;
         const res = await safeFetch(url, {
             signal: controller.signal,
-            headers: { 'User-Agent': 'Mozilla/5.0 (compatible; WHOISleuth-Posture/1.0)', Accept: 'text/plain' },
+            headers: whoisleuthRequestHeaders({ Accept: 'text/plain' }),
         });
         if (!res.ok) {
             // Not reading this body - release it explicitly instead of leaving an
@@ -705,7 +706,7 @@ async function checkDomainPosture(domain, { dkimSelectors = [], retiredDkimSelec
             nameservers: [],
             dsRecordCount: 0,
             dsDataTruncated: false,
-            error: rdap && 'error' in rdap ? rdap.error : 'RDAP did not return normalized domain evidence.',
+            error: rdap && 'error' in rdap ? rdap.error : 'RDAP did not return normalised domain evidence.',
         };
     const externalDependencies = buildExternalDependencies({
         domain,

package/lib/encrypted-dns-contract.mjs

@@ -0,0 +1,81 @@
+const ENCRYPTED_DNS_CONTRACT_SCHEMA = 'whoisleuth.encrypted-dns-adapter';
+const ENCRYPTED_DNS_CONTRACT_VERSION = 1;
+const DNS_TYPES = new Set(['A', 'AAAA', 'CAA', 'CNAME', 'DNSKEY', 'DS', 'HTTPS', 'MX', 'NS', 'RRSIG', 'SOA', 'SVCB', 'TLSA', 'TXT']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function httpsUrl(value) {
+    if (typeof value !== 'string' || value.length > 2048)
+        return null;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !url.username && !url.password ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeEncryptedDnsAdapter(value) {
+    const source = record(value);
+    if (!source)
+        throw new TypeError('Encrypted DNS adapter must be an object.');
+    const id = typeof source.id === 'string' && /^[a-z][a-z0-9-]{0,47}$/u.test(source.id) ? source.id : null;
+    const label = typeof source.label === 'string' && source.label.length <= 80 && !/[\u0000-\u001f\u007f]/u.test(source.label)
+        ? source.label.trim()
+        : null;
+    const endpoint = httpsUrl(source.endpoint);
+    const termsUrl = httpsUrl(source.termsUrl);
+    const privacyUrl = httpsUrl(source.privacyUrl);
+    const reviewedAt = typeof source.reviewedAt === 'string' && Number.isFinite(Date.parse(source.reviewedAt))
+        ? new Date(source.reviewedAt).toISOString()
+        : null;
+    const method = source.method === 'GET' || source.method === 'POST' ? source.method : null;
+    const representation = source.representation === 'dns-json' || source.representation === 'dns-wire'
+        ? source.representation
+        : null;
+    const retention = source.queryRetention;
+    const maxResponseBytes = Number(source.maxResponseBytes);
+    const timeoutMs = Number(source.timeoutMs);
+    if (!id || !label || !endpoint || !termsUrl || !privacyUrl || !reviewedAt || !method || !representation
+        || !['none', 'limited', 'provider_defined', 'unknown'].includes(String(retention))
+        || !Number.isInteger(maxResponseBytes) || maxResponseBytes < 1024 || maxResponseBytes > 2 * 1024 * 1024
+        || !Number.isInteger(timeoutMs) || timeoutMs < 250 || timeoutMs > 15_000) {
+        throw new TypeError('Encrypted DNS adapter did not satisfy the bounded privacy and transport contract.');
+    }
+    return Object.freeze({
+        id,
+        label,
+        endpoint,
+        method,
+        representation,
+        termsUrl,
+        privacyUrl,
+        reviewedAt,
+        queryRetention: retention,
+        maxResponseBytes,
+        timeoutMs,
+    });
+}
+function planEncryptedDnsQuery(adapter, input) {
+    const name = typeof input.name === 'string' ? input.name.trim().toLowerCase().replace(/\.$/u, '') : '';
+    const type = typeof input.type === 'string' ? input.type.trim().toUpperCase() : '';
+    if (!name || name.length > 253 || !/^[a-z0-9._-]+$/u.test(name) || !DNS_TYPES.has(type)) {
+        throw new TypeError('Encrypted DNS query name or record type was invalid or unsupported.');
+    }
+    return Object.freeze({
+        schema: ENCRYPTED_DNS_CONTRACT_SCHEMA,
+        version: ENCRYPTED_DNS_CONTRACT_VERSION,
+        state: 'approval_required',
+        adapter: Object.freeze({ id: adapter.id, label: adapter.label, endpoint: adapter.endpoint }),
+        query: Object.freeze({ name, type }),
+        disclosure: Object.freeze({
+            target: name,
+            recipient: new URL(adapter.endpoint).hostname,
+            queryRetention: adapter.queryRetention,
+        }),
+        limitation: 'This plan does not execute a request. Provider availability, answer authority, validation, filtering, retention, and regional behaviour remain untested.',
+    });
+}
+export { ENCRYPTED_DNS_CONTRACT_SCHEMA, ENCRYPTED_DNS_CONTRACT_VERSION, normalizeEncryptedDnsAdapter, planEncryptedDnsQuery, };

package/lib/evidence-export.mjs

@@ -1,7 +1,9 @@
 import { compareRdapPublications, compareRegistrySources } from "./registry-comparison.mjs";
 import { buildRegistryInsights } from "./registry-insights.mjs";
+import { WHOISLEUTH_SOURCE_REPOSITORY_URL } from "./project-metadata.mjs";
+import { normalizeBoundedSemanticVersion } from "./semantic-version.mjs";
 export const LOOKUP_EVIDENCE_SCHEMA = 'whoisleuth.lookup-evidence';
-export const LOOKUP_EVIDENCE_SCHEMA_VERSION = 23;
+export const LOOKUP_EVIDENCE_SCHEMA_VERSION = 24;
 const REGISTRAR_RDAP_STATUSES = new Set([
     'success', 'partial', 'error', 'unsupported', 'not_found', 'skipped', 'disabled',
 ]);
@@ -37,6 +39,14 @@ function boundedTimestamp(value) {
     const time = Date.parse(text);
     return Number.isFinite(time) ? new Date(time).toISOString() : null;
 }
+function boundedSemanticVersion(value) {
+    try {
+        return normalizeBoundedSemanticVersion(value, 'Evidence application');
+    }
+    catch {
+        return null;
+    }
+}
 function boundedEndpoint(value) {
     const text = boundedString(value, 2048);
     if (!text)
@@ -359,7 +369,7 @@ function registrarPublicationComparison(body, registryParsed) {
     });
 }
 export function buildLookupEvidence(response, options = {}) {
-    const { generatedAt = new Date().toISOString(), idnAnalysis = null } = options;
+    const { generatedAt = new Date().toISOString(), idnAnalysis = null, applicationVersion = null } = options;
     const body = recordOrNull(response) || {};
     const rdap = recordOrNull(body.rdap);
     const whois = recordOrNull(body.whois);
@@ -389,7 +399,11 @@ export function buildLookupEvidence(response, options = {}) {
         schema: LOOKUP_EVIDENCE_SCHEMA,
         schemaVersion: LOOKUP_EVIDENCE_SCHEMA_VERSION,
         generatedAt,
-        application: { name: 'WHOISleuth' },
+        application: {
+            name: 'WHOISleuth',
+            version: boundedSemanticVersion(applicationVersion),
+            projectUrl: WHOISLEUTH_SOURCE_REPOSITORY_URL,
+        },
         query: {
             submitted: body.query || null,
             type: body.type || null,

package/lib/evidence-report-markdown.mjs

@@ -38,7 +38,7 @@ function formatLookupEvidenceMarkdown(document, options = {}) {
     lines.push('', '## Registry-source comparison');
     appendFields(lines, report.comparison.health);
     if (!report.comparison.fields.length) {
-        lines.push('- No comparable normalized fields were published.');
+        lines.push('- No comparable normalised fields were published.');
     }
     else {
         for (const field of report.comparison.fields) {

package/lib/evidence-report.mjs

@@ -89,6 +89,7 @@ function reportField(label, value, fallback = 'Not reported') {
 }
 function buildLookupEvidenceReport(document, options = {}) {
     const report = objectOrEmpty(document);
+    const application = objectOrEmpty(report.application);
     const query = objectOrEmpty(report.query);
     const diagnostics = objectOrEmpty(report.diagnostics);
     const rdapDiagnostics = objectOrEmpty(diagnostics.rdap);
@@ -300,6 +301,8 @@ function buildLookupEvidenceReport(document, options = {}) {
         notice: 'Human-readable summary. The versioned JSON export remains the full-fidelity evidence package; raw RDAP JSON and WHOIS response bodies are deliberately omitted here.',
         metadata: [
             reportField('Generated', report.generatedAt),
+            reportField('Generator', application.version ? `${application.name || 'WHOISleuth'} ${application.version}` : application.name || 'WHOISleuth'),
+            reportField('Project', application.projectUrl),
             reportField('Report contract', `${cleanReportText(report.schema)} v${cleanReportText(report.schemaVersion)}`),
         ],
         query: [
@@ -375,7 +378,7 @@ function buildLookupEvidenceReport(document, options = {}) {
             ...registryAccessFields,
         ],
         limitations: [
-            'This report summarizes point-in-time observations and registry publications. It does not prove ownership, activity, availability, or maliciousness.',
+            'This report summarises point-in-time observations and registry publications. It does not prove ownership, activity, availability, or maliciousness.',
             'Missing, skipped, partial, unsupported, or failed sources are inconclusive rather than negative evidence.',
             'The Risk score is a versioned heuristic review priority, not a probability or determination of maliciousness. Review its listed factors and the underlying source states.',
             'Raw registry payloads and full WHOIS referral responses are available only in the JSON evidence package and may contain public contact data.',