@slicedearth/whoisleuth-cli 1.32.2 → 1.36.1

package/lib/dnssec-evidence-validation.mjs

@@ -0,0 +1,235 @@
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { domainToASCII } from 'node:url';
+const DNSSEC_EVIDENCE_SCHEMA = 'whoisleuth.dnssec-evidence-validation';
+const DNSSEC_EVIDENCE_VERSION = 1;
+const MAX_DNSSEC_RECORDS = 50;
+const MAX_PUBLIC_KEY_BYTES = 8192;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function integer(value, minimum, maximum) {
+    return Number.isInteger(value) && Number(value) >= minimum && Number(value) <= maximum
+        ? Number(value)
+        : null;
+}
+function ownerName(value) {
+    if (typeof value !== 'string' || value.length > 253)
+        return null;
+    const ascii = domainToASCII(value.trim().replace(/\.$/u, '').toLowerCase());
+    if (!ascii || ascii.length > 253)
+        return null;
+    const labels = ascii.split('.');
+    if (labels.some((label) => !label || label.length > 63))
+        return null;
+    return ascii;
+}
+function hexadecimal(value, length) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.replace(/\s+/gu, '').toUpperCase();
+    if (!normalized || !/^[0-9A-F]+$/u.test(normalized) || normalized.length % 2 !== 0)
+        return null;
+    if (length !== undefined && normalized.length !== length)
+        return null;
+    return normalized;
+}
+function normalizeDs(value) {
+    const source = record(value);
+    if (!source)
+        return null;
+    const keyTag = integer(source.keyTag, 0, 65_535);
+    const algorithm = integer(source.algorithm, 0, 255);
+    const digestType = integer(source.digestType, 0, 255);
+    const expectedLength = digestType === 1 ? 40 : digestType === 2 ? 64 : digestType === 4 ? 96 : undefined;
+    const digest = hexadecimal(source.digest, expectedLength);
+    return keyTag === null || algorithm === null || digestType === null || !digest
+        ? null
+        : Object.freeze({ keyTag, algorithm, digestType, digest });
+}
+function normalizeDnskey(value) {
+    const source = record(value);
+    if (!source)
+        return null;
+    const flags = integer(source.flags, 0, 65_535);
+    const protocol = integer(source.protocol, 0, 255);
+    const algorithm = integer(source.algorithm, 0, 255);
+    if (flags === null || protocol === null || algorithm === null || typeof source.publicKeyBase64 !== 'string')
+        return null;
+    if (!/^[A-Za-z0-9+/]+={0,2}$/u.test(source.publicKeyBase64) || source.publicKeyBase64.length > MAX_PUBLIC_KEY_BYTES * 2)
+        return null;
+    const decoded = Buffer.from(source.publicKeyBase64, 'base64');
+    if (!decoded.length || decoded.length > MAX_PUBLIC_KEY_BYTES || decoded.toString('base64') !== source.publicKeyBase64)
+        return null;
+    return Object.freeze({ flags, protocol, algorithm, publicKeyBase64: source.publicKeyBase64 });
+}
+function dnskeyRdata(value) {
+    const key = Buffer.from(value.publicKeyBase64, 'base64');
+    const rdata = Buffer.allocUnsafe(4 + key.length);
+    rdata.writeUInt16BE(value.flags, 0);
+    rdata[2] = value.protocol;
+    rdata[3] = value.algorithm;
+    key.copy(rdata, 4);
+    return rdata;
+}
+function dnskeyTag(rdata) {
+    let accumulator = 0;
+    for (let index = 0; index < rdata.length; index += 1) {
+        accumulator += index & 1 ? rdata[index] : rdata[index] << 8;
+    }
+    accumulator += (accumulator >> 16) & 0xffff;
+    return accumulator & 0xffff;
+}
+function ownerWire(value) {
+    const output = [];
+    for (const label of value.split('.')) {
+        const bytes = Buffer.from(label, 'ascii');
+        output.push(bytes.length, ...bytes);
+    }
+    output.push(0);
+    return Buffer.from(output);
+}
+function dsDigest(owner, dnskey, digestType) {
+    const hash = digestType === 1 ? 'sha1' : digestType === 2 ? 'sha256' : digestType === 4 ? 'sha384' : null;
+    if (!hash)
+        return null;
+    return createHash(hash).update(ownerWire(owner)).update(dnskeyRdata(dnskey)).digest('hex').toUpperCase();
+}
+function normalizeRrsig(value) {
+    const source = record(value);
+    if (!source || typeof source.inception !== 'string' || typeof source.expiration !== 'string')
+        return null;
+    const inception = Date.parse(source.inception);
+    const expiration = Date.parse(source.expiration);
+    if (!Number.isFinite(inception) || !Number.isFinite(expiration) || inception > expiration)
+        return null;
+    return Object.freeze({ inception, expiration });
+}
+function signatureTimeState(value, observedAt) {
+    if (!value.length || typeof observedAt !== 'string')
+        return 'unavailable';
+    const observed = Date.parse(observedAt);
+    if (!Number.isFinite(observed))
+        return 'unavailable';
+    let withinWindow = 0;
+    for (const item of value) {
+        if (observed >= item.inception && observed <= item.expiration)
+            withinWindow += 1;
+    }
+    if (withinWindow === value.length)
+        return 'within_window';
+    return withinWindow === 0 ? 'outside_window' : 'mixed';
+}
+function validateDnssecEvidence(input) {
+    const normalizedOwner = ownerName(input.ownerName);
+    const rawDs = Array.isArray(input.dsRecords) ? input.dsRecords : [];
+    const rawDnskeys = Array.isArray(input.dnskeyRecords) ? input.dnskeyRecords : [];
+    const rawRrsigs = Array.isArray(input.rrSigRecords) ? input.rrSigRecords : [];
+    const dsRecords = rawDs.slice(0, MAX_DNSSEC_RECORDS).map(normalizeDs).filter((item) => item !== null);
+    const dnskeys = rawDnskeys.slice(0, MAX_DNSSEC_RECORDS).map(normalizeDnskey).filter((item) => item !== null);
+    const rrsigs = rawRrsigs.slice(0, MAX_DNSSEC_RECORDS).map(normalizeRrsig).filter((item) => item !== null);
+    const rejectedCount = Math.min(rawDs.length, MAX_DNSSEC_RECORDS) - dsRecords.length
+        + Math.min(rawDnskeys.length, MAX_DNSSEC_RECORDS) - dnskeys.length
+        + Math.min(rawRrsigs.length, MAX_DNSSEC_RECORDS) - rrsigs.length;
+    const truncated = rawDs.length > MAX_DNSSEC_RECORDS
+        || rawDnskeys.length > MAX_DNSSEC_RECORDS
+        || rawRrsigs.length > MAX_DNSSEC_RECORDS;
+    const signatureState = signatureTimeState(rrsigs, input.observedAt);
+    const findings = [];
+    const limitations = [
+        'This offline review verifies supplied DS and DNSKEY relationships only. It does not retrieve or authenticate a complete chain to a configured root trust anchor.',
+        'Missing records may reflect incomplete input and are not treated as proof that DNSSEC is absent.',
+    ];
+    if (!normalizedOwner) {
+        return Object.freeze({
+            schema: DNSSEC_EVIDENCE_SCHEMA,
+            version: DNSSEC_EVIDENCE_VERSION,
+            state: 'invalid',
+            ownerName: null,
+            dsRecordCount: dsRecords.length,
+            dnskeyRecordCount: dnskeys.length,
+            rrsigRecordCount: rrsigs.length,
+            matchedDsCount: 0,
+            unsupportedDigestCount: 0,
+            rejectedCount,
+            truncated,
+            signatureTimeState: signatureState,
+            findings: Object.freeze(['The supplied owner name was invalid.']),
+            limitations: Object.freeze(limitations),
+        });
+    }
+    if (input.delegationSigned === false && dsRecords.length === 0) {
+        findings.push('The supplied delegation state was unsigned and no DS records were supplied.');
+        return Object.freeze({
+            schema: DNSSEC_EVIDENCE_SCHEMA,
+            version: DNSSEC_EVIDENCE_VERSION,
+            state: 'unsigned',
+            ownerName: normalizedOwner,
+            dsRecordCount: 0,
+            dnskeyRecordCount: dnskeys.length,
+            rrsigRecordCount: rrsigs.length,
+            matchedDsCount: 0,
+            unsupportedDigestCount: 0,
+            rejectedCount,
+            truncated,
+            signatureTimeState: signatureState,
+            findings: Object.freeze(findings),
+            limitations: Object.freeze(limitations),
+        });
+    }
+    const unsupportedDigestCount = dsRecords.filter((item) => ![1, 2, 4].includes(item.digestType)).length;
+    let matchedDsCount = 0;
+    for (const ds of dsRecords) {
+        const matched = dnskeys.some((dnskey) => {
+            if (dnskey.algorithm !== ds.algorithm)
+                return false;
+            const rdata = dnskeyRdata(dnskey);
+            return dnskeyTag(rdata) === ds.keyTag && dsDigest(normalizedOwner, dnskey, ds.digestType) === ds.digest;
+        });
+        if (matched)
+            matchedDsCount += 1;
+    }
+    const definiteConflict = input.delegationSigned === false && dsRecords.length > 0
+        || input.delegationSigned === true && dsRecords.length === 0 && !truncated
+        || signatureState === 'outside_window'
+        || (dsRecords.length > 0 && dnskeys.length > 0 && matchedDsCount === 0 && unsupportedDigestCount < dsRecords.length);
+    if (definiteConflict)
+        findings.push('The supplied delegation, signature-time, DS, or DNSKEY evidence conflicts.');
+    if (matchedDsCount > 0)
+        findings.push(`${matchedDsCount} supplied DS record(s) matched a supplied DNSKEY.`);
+    if (unsupportedDigestCount > 0)
+        findings.push(`${unsupportedDigestCount} DS digest type(s) were retained as unsupported.`);
+    if (signatureState === 'mixed')
+        findings.push('The supplied RRSIG validity windows were mixed at the observation time.');
+    if (rejectedCount > 0)
+        findings.push(`${rejectedCount} malformed record(s) were rejected.`);
+    if (truncated)
+        findings.push('The supplied record set exceeded the review bound and was truncated.');
+    const completeLocalRelationship = dsRecords.length > 0
+        && dnskeys.length > 0
+        && matchedDsCount > 0
+        && !definiteConflict
+        && rejectedCount === 0
+        && !truncated
+        && unsupportedDigestCount === 0
+        && signatureState !== 'mixed';
+    return Object.freeze({
+        schema: DNSSEC_EVIDENCE_SCHEMA,
+        version: DNSSEC_EVIDENCE_VERSION,
+        state: definiteConflict ? 'conflict' : completeLocalRelationship ? 'consistent' : 'partial',
+        ownerName: normalizedOwner,
+        dsRecordCount: dsRecords.length,
+        dnskeyRecordCount: dnskeys.length,
+        rrsigRecordCount: rrsigs.length,
+        matchedDsCount,
+        unsupportedDigestCount,
+        rejectedCount,
+        truncated,
+        signatureTimeState: signatureState,
+        findings: Object.freeze(findings),
+        limitations: Object.freeze(limitations),
+    });
+}
+export { DNSSEC_EVIDENCE_SCHEMA, DNSSEC_EVIDENCE_VERSION, MAX_DNSSEC_RECORDS, dnskeyTag, validateDnssecEvidence, };

package/lib/domain-control-manifest.mjs

@@ -0,0 +1,339 @@
+import { createHash } from 'node:crypto';
+import { domainToASCII } from 'node:url';
+import { canonicalArtifactJson } from "../frontend/src/lib/analysis/artifact-integrity.js";
+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;
+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.`);
+    }
+    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(normalizeEntry);
+    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: 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.',
+        ]),
+    });
+    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)
+        || !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.');
+    }
+    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 normalized 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;
+    if (integrityDigest(unsigned) !== 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;
+    const fields = {};
+    for (const field of ['nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock']) {
+        const raw = record(rawFields[field]);
+        if (!raw)
+            continue;
+        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.`);
+    }
+    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";
@@ -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

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 behavior remain untested.',
+    });
+}
+export { ENCRYPTED_DNS_CONTRACT_SCHEMA, ENCRYPTED_DNS_CONTRACT_VERSION, normalizeEncryptedDnsAdapter, planEncryptedDnsQuery, };