@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/lib/domain-change-review.mjs

@@ -1,12 +1,16 @@
 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 DOMAIN_CHANGE_INPUT_SCHEMA = 'whoisleuth.domain-change.input';
+export const DOMAIN_CHANGE_INPUT_VERSION = 2;
+export const SUPPORTED_DOMAIN_CHANGE_INPUT_VERSIONS = Object.freeze([1, DOMAIN_CHANGE_INPUT_VERSION]);
 export const DOMAIN_CHANGE_REVIEW_SCHEMA = 'whoisleuth.domain-change.review';
-export const DOMAIN_CHANGE_REVIEW_VERSION = 1;
+export const DOMAIN_CHANGE_REVIEW_VERSION = 3;
 export const MAX_DOMAIN_CHANGE_VANTAGES = 16;
 export const MAX_DOMAIN_CHANGE_RECORDS = 500;
 const ROOT_KEYS = new Set(['schema', 'version', 'domain', 'authoritySnapshots', 'resolverSnapshots', 'acmeDependencies', 'certificate', 'hsts']);
 const SNAPSHOT_KEYS = new Set(['label', 'source', 'state', 'observedAt', 'records']);
+const COVERED_SNAPSHOT_KEYS = new Set([...SNAPSHOT_KEYS, 'queries']);
 const RECORD_KEYS = new Set(['owner', 'type', 'value', 'ttl']);
 const ACME_KEYS = new Set(['method', 'owner', 'target', 'provider', 'state']);
 const CERTIFICATE_KEYS = new Set(['state', 'observedAt', 'currentSpkiSha256', 'plannedSpkiSha256', 'mustStaple', 'ocspStapled', 'embeddedSctCount']);
@@ -61,13 +65,14 @@ function normaliseRecord(value, apex, label) {
             : (() => { throw new TypeError(`${label}.ttl is outside its supported range.`); })();
     return Object.freeze({ owner: owner(input.owner, apex, `${label}.owner`), type, ttl, ...normaliseValue(type, input.value, `${label}.value`) });
 }
-function normaliseSnapshots(value, apex, label) {
+function normaliseSnapshots(value, apex, label, legacy) {
     if (!Array.isArray(value) || value.length > MAX_DOMAIN_CHANGE_VANTAGES)
         throw new TypeError(`${label} must contain no more than ${MAX_DOMAIN_CHANGE_VANTAGES} snapshots.`);
     let totalRecords = 0;
+    let totalQueries = 0;
     const snapshots = value.map((raw, index) => {
         const item = requireRecord(raw, `${label}[${index}]`);
-        exactKeys(item, SNAPSHOT_KEYS, `${label}[${index}]`);
+        exactKeys(item, legacy ? SNAPSHOT_KEYS : COVERED_SNAPSHOT_KEYS, `${label}[${index}]`);
         const state = evidenceState(item.state, `${label}[${index}].state`);
         if (!Array.isArray(item.records))
             throw new TypeError(`${label}[${index}].records must be an array.`);
@@ -77,29 +82,43 @@ function normaliseSnapshots(value, apex, label) {
         const records = item.records.map((recordValue, recordIndex) => normaliseRecord(recordValue, apex, `${label}[${index}].records[${recordIndex}]`));
         if (state === 'unavailable' && records.length)
             throw new TypeError(`${label}[${index}] cannot contain records when unavailable.`);
+        const queries = normaliseDnsQueryCoverage(item.queries, {
+            legacy, label: `${label}[${index}].queries`, maximum: MAX_DOMAIN_CHANGE_RECORDS - totalQueries, state, records,
+            owner: (value, path) => owner(value, apex, path),
+            type: (value, path) => {
+                const type = text(value, path, 16).toUpperCase();
+                if (!TYPES.has(type))
+                    throw new TypeError(`${path} is unsupported.`);
+                return type;
+            },
+        });
+        totalQueries += queries.length;
         return Object.freeze({
             label: text(item.label, `${label}[${index}].label`, 120),
             source: text(item.source, `${label}[${index}].source`, 240),
             state,
             observedAt: timestamp(item.observedAt, `${label}[${index}].observedAt`),
             records: Object.freeze(records),
+            queries,
         });
     });
     if (new Set(snapshots.map((item) => item.label.toLowerCase())).size !== snapshots.length)
         throw new TypeError(`${label} labels must be unique.`);
     return Object.freeze(snapshots);
 }
+function snapshotProvenance(snapshot) {
+    return Object.freeze({ label: snapshot.label, source: snapshot.source, state: snapshot.state, observedAt: snapshot.observedAt, queries: snapshot.queries });
+}
 function recordMatrix(snapshots) {
-    const keys = [...new Set(snapshots.flatMap((snapshot) => snapshot.records.map((item) => `${item.owner}\u0000${item.type}`)))].sort();
+    const keys = [...new Set(snapshots.flatMap((snapshot) => snapshot.queries.map((item) => `${item.owner}\u0000${item.type}`)))].sort();
     return Object.freeze(keys.map((key) => {
         const [recordOwner, type] = key.split('\u0000');
         const observations = snapshots.map((snapshot) => {
             const matches = snapshot.records.filter((item) => item.owner === recordOwner && item.type === type);
             const ttls = matches.map((item) => item.ttl).filter((ttl) => ttl !== null);
             return Object.freeze({
-                label: snapshot.label,
-                source: snapshot.source,
-                state: snapshot.state,
+                label: snapshot.label, source: snapshot.source, observedAt: snapshot.observedAt,
+                state: dnsQueryState(snapshot.queries, recordOwner, type),
                 values: Object.freeze([...new Set(matches.map((item) => item.value))].sort()),
                 ttlRange: ttls.length ? Object.freeze({
                     minimum: Math.min(...ttls),
@@ -112,13 +131,14 @@ function recordMatrix(snapshots) {
         return Object.freeze({
             owner: recordOwner,
             type,
-            state: complete.length < 2 ? 'insufficient' : signatures.size === 1 ? 'aligned' : 'different',
+            state: complete.length < 2 || complete.length !== observations.length ? 'insufficient' : signatures.size === 1 ? 'aligned' : 'different',
             observations: Object.freeze(observations),
         });
     }));
 }
 function reviewDnssecAutomation(matrix) {
-    const automation = matrix.filter((row) => row.type === 'CDS' || row.type === 'CDNSKEY' || row.type === 'CSYNC');
+    const automation = matrix.filter((row) => ['CDS', 'CDNSKEY', 'CSYNC'].includes(row.type)
+        && row.observations.some((item) => item.values.length > 0));
     const byType = (type) => automation.find((row) => row.type === type);
     const cds = byType('CDS');
     const cdnskey = byType('CDNSKEY');
@@ -200,7 +220,7 @@ function normaliseCertificate(value) {
 }
 function reviewCertificate(certificate) {
     if (!certificate)
-        return Object.freeze({ state: 'not_supplied', continuity: 'unknown', findings: Object.freeze([]) });
+        return Object.freeze({ state: 'not_supplied', observedAt: null, continuity: 'unknown', findings: Object.freeze([]) });
     const continuity = !certificate.currentSpkiSha256 || !certificate.plannedSpkiSha256
         ? 'unknown'
         : certificate.currentSpkiSha256 === certificate.plannedSpkiSha256 ? 'retained' : 'changes';
@@ -210,7 +230,7 @@ function reviewCertificate(certificate) {
         ...(certificate.embeddedSctCount === 0
             ? ['No embedded certificate-transparency timestamp was observed; this does not establish that the certificate was not logged by another mechanism.'] : []),
     ];
-    return Object.freeze({ state: certificate.state, continuity, findings: Object.freeze(findings) });
+    return Object.freeze({ state: certificate.state, observedAt: certificate.observedAt, continuity, findings: Object.freeze(findings) });
 }
 function normaliseHsts(value) {
     if (value === null || value === undefined)
@@ -236,12 +256,12 @@ function serviceInventory(snapshots) {
 }
 export function reviewDomainChange(inputRaw, generatedAtValue = new Date().toISOString()) {
     const input = requireRecord(inputRaw, 'Domain change input');
-    if (input.schema !== DOMAIN_CHANGE_INPUT_SCHEMA || input.version !== 1)
-        throw new TypeError(`Domain change input must use ${DOMAIN_CHANGE_INPUT_SCHEMA} version 1.`);
+    if (input.schema !== DOMAIN_CHANGE_INPUT_SCHEMA || !SUPPORTED_DOMAIN_CHANGE_INPUT_VERSIONS.includes(input.version))
+        throw new TypeError(`Domain change input must use ${DOMAIN_CHANGE_INPUT_SCHEMA} version 1 or ${DOMAIN_CHANGE_INPUT_VERSION}.`);
     exactKeys(input, ROOT_KEYS, 'Domain change input');
     const apex = domain(input.domain, 'domain');
-    const authoritySnapshots = normaliseSnapshots(input.authoritySnapshots ?? [], apex, 'authoritySnapshots');
-    const resolverSnapshots = normaliseSnapshots(input.resolverSnapshots ?? [], apex, 'resolverSnapshots');
+    const authoritySnapshots = normaliseSnapshots(input.authoritySnapshots ?? [], apex, 'authoritySnapshots', input.version === 1);
+    const resolverSnapshots = normaliseSnapshots(input.resolverSnapshots ?? [], apex, 'resolverSnapshots', input.version === 1);
     const authorityMatrix = recordMatrix(authoritySnapshots);
     const resolverMatrix = recordMatrix(resolverSnapshots);
     const acmeDependencies = normaliseAcme(input.acmeDependencies ?? [], apex);
@@ -285,6 +305,10 @@ export function reviewDomainChange(inputRaw, generatedAtValue = new Date().toISO
         generatedAt: timestamp(generatedAtValue, 'generatedAt'),
         domain: apex,
         state: reviewRequired ? 'review' : 'ready',
+        sourceObservations: Object.freeze({
+            authorities: Object.freeze(authoritySnapshots.map(snapshotProvenance)),
+            resolvers: Object.freeze(resolverSnapshots.map(snapshotProvenance)),
+        }),
         authoritativeRecordMatrix: authorityMatrix,
         resolverDivergenceMatrix: resolverMatrix,
         dnssecAutomation: reviewDnssecAutomation(authorityMatrix),
@@ -299,7 +323,7 @@ export function reviewDomainChange(inputRaw, generatedAtValue = new Date().toISO
         limitations: Object.freeze([
             'This local review uses only analyst-supplied observations and makes no DNS, HTTP, certificate, certificate-authority, preload-list, or provider request.',
             'Different observations can reflect propagation, caching, split-horizon DNS, resolver policy, or collection timing; they do not establish misconfiguration by themselves.',
-            'Partial or unavailable evidence is never treated as record absence. TXT values are represented only by SHA-256 digests.',
+            'Only an explicitly observed query can establish an empty answer. Unqueried, partial and unavailable record types are not absence; legacy inputs establish scope only for supplied records. TXT values are represented only by SHA-256 digests.',
             'DNSSEC automation readiness describes CDS, CDNSKEY, and CSYNC publication consistency; it does not validate a cryptographic chain or authorise a registry-side change.',
             'HSTS preload state is an analyst-supplied, source-attributed observation and must be refreshed against the nominated source before a change.',
         ]),