@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/lib/credential-form-attribution.mjs

@@ -0,0 +1,136 @@
+import { classifyStaticCredentialInput, staticControlDisabled, MAX_STATIC_FORMS, MAX_STATIC_INPUTS, } from "./static-html-analysis.mjs";
+import { CREDENTIAL_CATEGORY_NAMES, MAX_FORM_DESTINATIONS, } from "../packages/evidence/credential-form-attribution.mjs";
+const attribute = (element, name) => element.attributes.find(item => item.name === name)?.value;
+/** HTML Auto buttons submit only without command attributes or a select parent. */
+export function staticControlIsSubmitter(element, parent) {
+    const type = (attribute(element, 'type') ?? '').toLowerCase();
+    if (element.name === 'input')
+        return type === 'submit' || type === 'image';
+    if (element.name !== 'button')
+        return false;
+    if (type === 'submit')
+        return true;
+    if (type === 'button' || type === 'reset')
+        return false;
+    return attribute(element, 'command') === undefined && attribute(element, 'commandfor') === undefined
+        && !(parent?.html && parent.name === 'select');
+}
+// Uses the existing bounded, inert-template-free tree. IDs and control values
+// are transient association inputs; only ordinal forms and fixed categories
+// leave this projection.
+export function attributeCredentialForms(analysis, documentUrl, sourceTruncated = false) {
+    const elements = analysis.elements;
+    const firstId = new Map();
+    const firstLegends = new Map();
+    let firstUncertainId = Number.POSITIVE_INFINITY;
+    const formIndices = [];
+    let complete = !sourceTruncated && !analysis.inputLimitReached && !analysis.tagLimitReached && !analysis.forms.truncated;
+    for (const [index, element] of elements.entries()) {
+        if (element.attributesTruncated && attribute(element, 'id') === undefined)
+            firstUncertainId = Math.min(firstUncertainId, index);
+        const id = attribute(element, 'id');
+        if (id !== undefined && id.length <= 4096 && !firstId.has(id))
+            firstId.set(id, index);
+        if (element.html && element.name === 'form') {
+            if (formIndices.length < MAX_STATIC_FORMS)
+                formIndices.push(index);
+            else
+                complete = false;
+        }
+        if (element.html && element.name === 'legend' && element.parent !== null && !firstLegends.has(element.parent))
+            firstLegends.set(element.parent, index);
+    }
+    const ancestor = (index, name) => {
+        for (let parent = elements[index]?.parent ?? null; parent !== null; parent = elements[parent]?.parent ?? null) {
+            const element = elements[parent];
+            if (element.html && element.name === name)
+                return parent;
+        }
+        return null;
+    };
+    const owner = (index) => {
+        const element = elements[index];
+        if (element.attributesTruncated)
+            return null;
+        for (let parent = element.parent; parent !== null; parent = elements[parent]?.parent ?? null) {
+            if (elements[parent]?.name === 'fieldset' && elements[parent]?.attributesTruncated)
+                return null;
+        }
+        const explicit = attribute(element, 'form');
+        if (explicit !== undefined) {
+            const selected = firstId.get(explicit);
+            // A clipped earlier ID could shadow this form in the browser's first-ID
+            // lookup. Do not attribute its controls to the later retained match.
+            return selected !== undefined && selected < firstUncertainId && elements[selected]?.html && elements[selected]?.name === 'form' ? selected : null;
+        }
+        return ancestor(index, 'form');
+    };
+    const destination = (form, submitter) => {
+        const method = (submitter && attribute(submitter, 'formmethod')) ?? attribute(form, 'method') ?? 'get';
+        if (method.toLowerCase() === 'dialog')
+            return { relationship: 'no_submission', origin: null };
+        if (form.attributesTruncated || submitter?.attributesTruncated)
+            return { relationship: 'unknown', origin: null };
+        const action = (submitter && attribute(submitter, 'formaction')) ?? attribute(form, 'action');
+        if (action !== undefined && (action.length > 4096 || /[\u0000-\u001f\u007f]/u.test(action)))
+            return { relationship: 'unknown', origin: null };
+        try {
+            const source = new URL(documentUrl);
+            // Missing/empty actions use the document URL, not the <base> URL.
+            if (action?.trim() && analysis.baseHrefState === 'invalid')
+                return { relationship: 'unknown', origin: null };
+            const target = new URL(action?.trim() || documentUrl, analysis.effectiveBaseUrl ?? documentUrl);
+            if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.origin.length > 320)
+                return { relationship: 'unknown', origin: null };
+            return { relationship: target.origin === source.origin ? 'same_origin' : 'external', origin: target.origin };
+        }
+        catch {
+            return { relationship: 'unknown', origin: null };
+        }
+    };
+    const forms = formIndices.map((index, ordinal) => ({
+        index: ordinal + 1,
+        categories: Object.fromEntries(CREDENTIAL_CATEGORY_NAMES.map(name => [name, 0])),
+        destinations: [destination(elements[index])],
+    }));
+    const formRows = new Map(formIndices.map((index, ordinal) => [index, forms[ordinal]]));
+    let unassociatedInputs = 0;
+    let controls = 0;
+    for (const [index, element] of elements.entries()) {
+        if (!element.html || !['input', 'button'].includes(element.name))
+            continue;
+        if (++controls > MAX_STATIC_INPUTS) {
+            complete = false;
+            break;
+        }
+        if (staticControlDisabled(elements, index, firstLegends))
+            continue;
+        const categories = element.name === 'input' ? classifyStaticCredentialInput(element.attributes) : { values: [], truncated: false };
+        if (categories.truncated || element.attributesTruncated)
+            complete = false;
+        const ownerIndex = owner(index);
+        const row = ownerIndex === null ? undefined : formRows.get(ownerIndex);
+        if (categories.values.length) {
+            if (!row) {
+                unassociatedInputs++;
+                complete = false;
+            }
+            else
+                for (const category of categories.values)
+                    row.categories[category]++;
+        }
+        const submitter = staticControlIsSubmitter(element, element.parent === null ? undefined : elements[element.parent]);
+        if (row && ownerIndex !== null && submitter && (attribute(element, 'formaction') !== undefined || attribute(element, 'formmethod') !== undefined)) {
+            const next = destination(elements[ownerIndex], element);
+            if (!row.destinations.some(value => value.relationship === next.relationship && value.origin === next.origin)) {
+                if (row.destinations.length >= MAX_FORM_DESTINATIONS)
+                    complete = false;
+                else
+                    row.destinations.push(next);
+            }
+        }
+    }
+    if (forms.some(form => form.destinations.some(value => value.relationship === 'unknown')))
+        complete = false;
+    return { forms, unassociatedInputs, complete };
+}

package/lib/credential-surface-profile.mjs

@@ -5,22 +5,25 @@
 // never enter this profile.
 import { createObservation } from "../packages/evidence/observation.mjs";
 import { CREDENTIAL_SURFACE_PROFILE_VERSION } from "./lookup-child-profile-contract.mjs";
+import { attributeCredentialForms } from "./credential-form-attribution.mjs";
 import { MAX_STATIC_FORMS, MAX_STATIC_INPUTS, analyzeStaticHtml, } from "./static-html-analysis.mjs";
 function analyzeCredentialSurfaceProfile(input = {}) {
     const htmlAnalysis = input.htmlAnalysis ?? analyzeStaticHtml(input.html, { baseUrl: input.baseUrl });
     const forms = htmlAnalysis.forms;
+    const formAttribution = input.formAttribution ?? attributeCredentialForms(htmlAnalysis, typeof input.baseUrl === 'string' ? input.baseUrl : '', input.sourceTruncated === true);
     const sourceTruncated = input.sourceTruncated === true;
     const truncated = sourceTruncated
         || htmlAnalysis.inputLimitReached
         || htmlAnalysis.tagLimitReached
         || forms.truncated;
     const unclassifiedActions = forms.actions.unclassified;
-    const partial = truncated || unclassifiedActions > 0;
+    const partial = truncated || unclassifiedActions > 0 || !formAttribution.complete;
     const limitations = [
         'Static input categories use only bounded type and autocomplete declarations; JavaScript-rendered, non-semantic, disabled, and hidden controls are not classified.',
         'Category counts can overlap when one input declares more than one recognised purpose.',
         'External submission can be legitimate and does not establish phishing, unsafe handling, ownership, intent, or maliciousness.',
-        'No field names, values, labels, placeholders, complete action URLs, paths, queries, fragments, or arbitrary attributes are retained.',
+        'Only form ordinals, input-purpose counts and declared destination origins are retained; no field names, values, labels, placeholders, URL paths, queries or fragments.',
+        'Declared destinations, including submitter overrides, are not observed submissions. Script-created or changed forms are not evaluated.',
     ];
     if (sourceTruncated || htmlAnalysis.inputLimitReached) {
         limitations.push('The captured homepage body was truncated, so credential-surface evidence may be incomplete.');
@@ -36,6 +39,7 @@ function analyzeCredentialSurfaceProfile(input = {}) {
     }
     return {
         credentialSurfaceVersion: CREDENTIAL_SURFACE_PROFILE_VERSION,
+        formAttribution,
         ...createObservation({
             status: partial ? 'partial' : 'success',
             observedAt: input.observedAt,

package/lib/ct-query.mjs

@@ -1,27 +1,2 @@
-const MAX_CT_QUERY_LENGTH = 200;
-const CT_QUERY_ERROR_CODE = 'INVALID_CT_QUERY';
-const CT_QUERY_ERROR_MESSAGE = `Certificate Transparency query must be at most ${MAX_CT_QUERY_LENGTH} characters and contain no control or invisible formatting characters.`;
-const UNSAFE_QUERY_CHARACTER_RE = /[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/u;
-class CtQueryError extends Error {
-    code = CT_QUERY_ERROR_CODE;
-    constructor() {
-        super(CT_QUERY_ERROR_MESSAGE);
-        this.name = 'CtQueryError';
-    }
-}
-function normalizeCtQuery(value) {
-    if (value === undefined || value === null)
-        return '';
-    if (typeof value !== 'string'
-        || value.length > MAX_CT_QUERY_LENGTH
-        || UNSAFE_QUERY_CHARACTER_RE.test(value)) {
-        throw new CtQueryError();
-    }
-    return value.trim();
-}
-function isCtQueryError(value) {
-    return value instanceof Error
-        && 'code' in value
-        && value.code === CT_QUERY_ERROR_CODE;
-}
-export { CT_QUERY_ERROR_CODE, CT_QUERY_ERROR_MESSAGE, CtQueryError, isCtQueryError, MAX_CT_QUERY_LENGTH, normalizeCtQuery, };
+// Retained public import; the runtime-neutral implementation lives in the domain layer.
+export * from "../packages/analysis/ct-query.mjs";

package/lib/ct-response-bounds.mjs

@@ -1,9 +1,2 @@
-// Shared response-contract bounds for certificate-log search. The collector
-// and browser normalizer import these values so a valid backend response is
-// not accidentally clipped by a stale client-side mirror.
-export const MAX_CT_RESPONSE_RESULTS = 500;
-export const MAX_CT_RESPONSE_HOSTNAMES_PER_MATCH = 50;
-export const MAX_CT_RESPONSE_TIMESTAMP_LENGTH = 64;
-export const MAX_CT_RESPONSE_CERTIFICATE_GROUPS = 100;
-export const MAX_CT_RESPONSE_DOMAINS_PER_GROUP = 20;
-export const MAX_CT_RESPONSE_HOSTNAMES_PER_GROUP = 30;
+// Retained public import; the runtime-neutral implementation lives in the domain layer.
+export * from "../packages/analysis/ct-response-bounds.mjs";

package/lib/ct-search.mjs

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

package/lib/dmarc-discovery.mjs

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

package/lib/dns-convergence-review.mjs

@@ -1,14 +1,18 @@
 import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
 import { normaliseRdata } from "./zone-intent-review.mjs";
+import { dnsQueryState, normaliseDnsQueryCoverage } from "./dns-query-coverage.mjs";
 export const DNS_CONVERGENCE_INPUT_SCHEMA = 'whoisleuth.dns-convergence.input';
 export const DNS_CONVERGENCE_REVIEW_SCHEMA = 'whoisleuth.dns-convergence.review';
-export const DNS_CONVERGENCE_REVIEW_VERSION = 1;
+export const DNS_CONVERGENCE_INPUT_VERSION = 2;
+export const SUPPORTED_DNS_CONVERGENCE_INPUT_VERSIONS = Object.freeze([1, DNS_CONVERGENCE_INPUT_VERSION]);
+export const DNS_CONVERGENCE_REVIEW_VERSION = 2;
 export const MAX_DNS_CONVERGENCE_SNAPSHOTS = 100;
 export const MAX_DNS_CONVERGENCE_RECORDS = 2_000;
 const RECORD_TYPES = new Set(['A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NS', 'SOA', 'SRV', 'SVCB', 'HTTPS', 'TLSA', 'TXT']);
 const ROOT_KEYS = new Set(['schema', 'version', 'domain', 'expected', 'snapshots']);
 const EXPECTED_KEYS = new Set(['owner', 'type', 'values']);
 const SNAPSHOT_KEYS = new Set(['observer', 'source', 'observedAt', 'state', 'records']);
+const COVERED_SNAPSHOT_KEYS = new Set([...SNAPSHOT_KEYS, 'queries']);
 const RECORD_KEYS = new Set(['owner', 'type', 'value', 'ttl']);
 function type(value, label) {
     const candidate = requireBoundedString(value, label, 16).toUpperCase();
@@ -83,8 +87,8 @@ function expectedRows(value, apex) {
 }
 export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toISOString()) {
     const input = requireRecord(inputRaw, 'DNS convergence input');
-    if (input.schema !== DNS_CONVERGENCE_INPUT_SCHEMA || input.version !== 1) {
-        throw new TypeError(`DNS convergence input must use ${DNS_CONVERGENCE_INPUT_SCHEMA} version 1.`);
+    if (input.schema !== DNS_CONVERGENCE_INPUT_SCHEMA || !SUPPORTED_DNS_CONVERGENCE_INPUT_VERSIONS.includes(input.version)) {
+        throw new TypeError(`DNS convergence input must use ${DNS_CONVERGENCE_INPUT_SCHEMA} version 1 or ${DNS_CONVERGENCE_INPUT_VERSION}.`);
     }
     exactKeys(input, ROOT_KEYS, 'DNS convergence input');
     const apex = requireDomainName(input.domain, 'domain');
@@ -93,9 +97,10 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
         throw new TypeError(`snapshots must contain between 2 and ${MAX_DNS_CONVERGENCE_SNAPSHOTS} entries.`);
     }
     let recordCount = 0;
+    let queryCount = 0;
     const snapshots = input.snapshots.map((raw, index) => {
         const item = requireRecord(raw, `snapshots[${index}]`);
-        exactKeys(item, SNAPSHOT_KEYS, `snapshots[${index}]`);
+        exactKeys(item, input.version === 1 ? SNAPSHOT_KEYS : COVERED_SNAPSHOT_KEYS, `snapshots[${index}]`);
         if (!Array.isArray(item.records))
             throw new TypeError(`snapshots[${index}].records must be an array.`);
         recordCount += item.records.length;
@@ -104,12 +109,20 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
         const observationState = state(item.state, `snapshots[${index}].state`);
         if (observationState === 'unavailable' && item.records.length)
             throw new TypeError(`snapshots[${index}] cannot contain records when unavailable.`);
+        const records = Object.freeze(item.records.map((entry, recordIndex) => record(entry, apex, `snapshots[${index}].records[${recordIndex}]`)));
+        const queries = normaliseDnsQueryCoverage(item.queries, {
+            legacy: input.version === 1, label: `snapshots[${index}].queries`,
+            maximum: MAX_DNS_CONVERGENCE_RECORDS - queryCount, state: observationState, records,
+            owner: (value, label) => owner(value, apex, label), type,
+        });
+        queryCount += queries.length;
         return Object.freeze({
             observer: requireBoundedString(item.observer, `snapshots[${index}].observer`, 120),
             source: requireBoundedString(item.source, `snapshots[${index}].source`, 240),
             observedAt: requireIsoTimestamp(item.observedAt, `snapshots[${index}].observedAt`),
             state: observationState,
-            records: Object.freeze(item.records.map((entry, recordIndex) => record(entry, apex, `snapshots[${index}].records[${recordIndex}]`))),
+            records,
+            queries,
         });
     }).sort((left, right) => left.observedAt.localeCompare(right.observedAt) || left.observer.localeCompare(right.observer));
     const observers = [...new Set(snapshots.map((item) => item.observer))];
@@ -118,7 +131,7 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
     const latestByObserver = observers.map((observer) => snapshots.filter((item) => item.observer === observer).at(-1));
     const keys = [...new Set([
             ...expected.map((item) => `${item.owner}\u0000${item.type}`),
-            ...snapshots.flatMap((item) => item.records.map((entry) => `${entry.owner}\u0000${entry.type}`)),
+            ...snapshots.flatMap((item) => item.queries.map((entry) => `${entry.owner}\u0000${entry.type}`)),
         ])].sort();
     const rows = keys.map((key) => {
         const [recordOwner = '', recordType = ''] = key.split('\u0000');
@@ -134,7 +147,7 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
                 observer: snapshot.observer,
                 source: snapshot.source,
                 observedAt: snapshot.observedAt,
-                state: snapshot.state,
+                state: dnsQueryState(snapshot.queries, recordOwner, recordType),
                 values: Object.freeze(values),
                 cacheUntil,
             });
@@ -178,7 +191,7 @@ export function reviewDnsConvergence(inputRaw, generatedAtValue = new Date().toI
             'This local workbench compares only supplied observations and makes no DNS request.',
             'Resolver differences can reflect caches, split-horizon policy, interception, collection timing, or propagation; they do not establish which value is authoritative.',
             'Cache-until times are simple observation-time plus supplied TTL projections and do not reveal actual cache age, refresh behaviour, or resolver policy.',
-            'Partial and unavailable snapshots remain incomplete and are never interpreted as record absence.',
+            'Only an explicitly observed query can establish an empty answer. Unqueried, partial and unavailable record types are never interpreted as absence; legacy inputs establish scope only for their supplied records.',
         ]),
     });
 }