@slicedearth/whoisleuth-cli 1.39.1 → 1.43.0

package/lib/domain-change-review.mjs

@@ -0,0 +1,307 @@
+import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
+import { normaliseRdata } from "./zone-intent-review.mjs";
+export const DOMAIN_CHANGE_INPUT_SCHEMA = 'whoisleuth.domain-change.input';
+export const DOMAIN_CHANGE_REVIEW_SCHEMA = 'whoisleuth.domain-change.review';
+export const DOMAIN_CHANGE_REVIEW_VERSION = 1;
+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 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']);
+const HSTS_KEYS = new Set(['state', 'observedAt', 'header', 'preloadState', 'source']);
+const TYPES = new Set(['A', 'AAAA', 'CAA', 'CDNSKEY', 'CDS', 'CNAME', 'CSYNC', 'HTTPS', 'MX', 'NS', 'SRV', 'SVCB', 'TLSA', 'TXT']);
+function text(value, label, maximum = 500) {
+    return requireBoundedString(value, label, maximum);
+}
+function optionalText(value, label, maximum = 500) {
+    return value === null || value === undefined || value === '' ? null : text(value, label, maximum);
+}
+function timestamp(value, label) {
+    return requireIsoTimestamp(value, label);
+}
+function domain(value, label) {
+    return requireDomainName(value, label);
+}
+function owner(value, apex, label) {
+    const raw = text(value, label, 253).toLowerCase().replace(/\.$/u, '');
+    const candidate = raw === '@' ? apex : raw;
+    if (candidate.startsWith('*.'))
+        return `*.${domain(candidate.slice(2), label)}`;
+    const service = candidate.split('.');
+    if (candidate.length > 253 || service.some((part) => !/^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/u.test(part))) {
+        throw new TypeError(`${label} must be a valid DNS owner name.`);
+    }
+    return candidate;
+}
+function evidenceState(value, label) {
+    if (value !== 'observed' && value !== 'partial' && value !== 'unavailable')
+        throw new TypeError(`${label} is unsupported.`);
+    return value;
+}
+function normaliseValue(type, value, label) {
+    const raw = text(value, label, 16_384);
+    const normalised = normaliseRdata(type, raw, null);
+    return {
+        value: normalised.value,
+        treatment: normalised.valueTreatment,
+    };
+}
+function normaliseRecord(value, apex, label) {
+    const input = requireRecord(value, label);
+    exactKeys(input, RECORD_KEYS, label);
+    const type = text(input.type, `${label}.type`, 16).toUpperCase();
+    if (!TYPES.has(type))
+        throw new TypeError(`${label}.type is unsupported.`);
+    const ttl = input.ttl === undefined || input.ttl === null
+        ? null
+        : Number.isSafeInteger(input.ttl) && Number(input.ttl) >= 0 && Number(input.ttl) <= 0x7fff_ffff
+            ? Number(input.ttl)
+            : (() => { 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) {
+    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;
+    const snapshots = value.map((raw, index) => {
+        const item = requireRecord(raw, `${label}[${index}]`);
+        exactKeys(item, 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.`);
+        totalRecords += item.records.length;
+        if (totalRecords > MAX_DOMAIN_CHANGE_RECORDS)
+            throw new TypeError(`Domain change review is limited to ${MAX_DOMAIN_CHANGE_RECORDS} records.`);
+        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.`);
+        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),
+        });
+    });
+    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 recordMatrix(snapshots) {
+    const keys = [...new Set(snapshots.flatMap((snapshot) => snapshot.records.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,
+                values: Object.freeze([...new Set(matches.map((item) => item.value))].sort()),
+                ttlRange: ttls.length ? Object.freeze({
+                    minimum: Math.min(...ttls),
+                    maximum: Math.max(...ttls),
+                }) : null,
+            });
+        });
+        const complete = observations.filter((item) => item.state === 'observed');
+        const signatures = new Set(complete.map((item) => JSON.stringify(item.values)));
+        return Object.freeze({
+            owner: recordOwner,
+            type,
+            state: complete.length < 2 ? '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 byType = (type) => automation.find((row) => row.type === type);
+    const cds = byType('CDS');
+    const cdnskey = byType('CDNSKEY');
+    const csync = byType('CSYNC');
+    const conflicts = automation.filter((row) => row.state === 'different');
+    const partial = automation.some((row) => row.observations.some((observation) => observation.state !== 'observed'));
+    return Object.freeze({
+        state: !automation.length ? 'not_observed'
+            : conflicts.length ? 'conflict'
+                : partial ? 'partial'
+                    : 'review_ready',
+        cdsObserved: Boolean(cds),
+        cdnskeyObserved: Boolean(cdnskey),
+        csyncObserved: Boolean(csync),
+        conflictingTypes: Object.freeze(conflicts.map((row) => row.type)),
+        detail: !automation.length
+            ? 'No CDS, CDNSKEY, or CSYNC record was supplied.'
+            : conflicts.length
+                ? `Complete authority observations differ for ${conflicts.map((row) => row.type).join(', ')}.`
+                : partial
+                    ? 'Automation records were supplied, but at least one authority observation is partial or unavailable.'
+                    : 'Supplied complete authority observations agree for the observed automation records.',
+    });
+}
+function normaliseAcme(value, apex) {
+    if (!Array.isArray(value) || value.length > 64)
+        throw new TypeError('acmeDependencies must contain no more than 64 entries.');
+    return Object.freeze(value.map((raw, index) => {
+        const item = requireRecord(raw, `acmeDependencies[${index}]`);
+        exactKeys(item, ACME_KEYS, `acmeDependencies[${index}]`);
+        const method = item.method;
+        if (method !== 'dns-01' && method !== 'http-01' && method !== 'tls-alpn-01')
+            throw new TypeError(`acmeDependencies[${index}].method is unsupported.`);
+        const state = item.state;
+        if (state !== 'confirmed' && state !== 'partial' && state !== 'unknown')
+            throw new TypeError(`acmeDependencies[${index}].state is unsupported.`);
+        return Object.freeze({
+            method,
+            owner: owner(item.owner, apex, `acmeDependencies[${index}].owner`),
+            target: optionalText(item.target, `acmeDependencies[${index}].target`, 253),
+            provider: optionalText(item.provider, `acmeDependencies[${index}].provider`, 120),
+            state,
+        });
+    }));
+}
+function normaliseCertificate(value) {
+    if (value === null || value === undefined)
+        return null;
+    const item = requireRecord(value, 'certificate');
+    exactKeys(item, CERTIFICATE_KEYS, 'certificate');
+    const state = evidenceState(item.state, 'certificate.state');
+    const digest = (candidate, label) => {
+        const supplied = optionalText(candidate, label, 80);
+        if (supplied && !/^[a-f0-9]{64}$/iu.test(supplied))
+            throw new TypeError(`${label} must be a SHA-256 hexadecimal digest.`);
+        return supplied?.toLowerCase() ?? null;
+    };
+    const nullableBoolean = (candidate, label) => {
+        if (candidate === null || candidate === undefined)
+            return null;
+        if (typeof candidate !== 'boolean')
+            throw new TypeError(`${label} must be true, false, or null.`);
+        return candidate;
+    };
+    const embeddedSctCount = item.embeddedSctCount === null || item.embeddedSctCount === undefined
+        ? null
+        : Number.isSafeInteger(item.embeddedSctCount) && Number(item.embeddedSctCount) >= 0 && Number(item.embeddedSctCount) <= 100
+            ? Number(item.embeddedSctCount)
+            : (() => { throw new TypeError('certificate.embeddedSctCount is outside its supported range.'); })();
+    return Object.freeze({
+        state,
+        observedAt: timestamp(item.observedAt, 'certificate.observedAt'),
+        currentSpkiSha256: digest(item.currentSpkiSha256, 'certificate.currentSpkiSha256'),
+        plannedSpkiSha256: digest(item.plannedSpkiSha256, 'certificate.plannedSpkiSha256'),
+        mustStaple: nullableBoolean(item.mustStaple, 'certificate.mustStaple'),
+        ocspStapled: nullableBoolean(item.ocspStapled, 'certificate.ocspStapled'),
+        embeddedSctCount,
+    });
+}
+function reviewCertificate(certificate) {
+    if (!certificate)
+        return Object.freeze({ state: 'not_supplied', continuity: 'unknown', findings: Object.freeze([]) });
+    const continuity = !certificate.currentSpkiSha256 || !certificate.plannedSpkiSha256
+        ? 'unknown'
+        : certificate.currentSpkiSha256 === certificate.plannedSpkiSha256 ? 'retained' : 'changes';
+    const findings = [
+        ...(certificate.mustStaple === true && certificate.ocspStapled !== true
+            ? ['The certificate requires OCSP stapling, but stapled-response evidence was not confirmed.'] : []),
+        ...(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) });
+}
+function normaliseHsts(value) {
+    if (value === null || value === undefined)
+        return null;
+    const item = requireRecord(value, 'hsts');
+    exactKeys(item, HSTS_KEYS, 'hsts');
+    const preloadState = item.preloadState;
+    if (preloadState !== 'listed' && preloadState !== 'not_listed' && preloadState !== 'unavailable')
+        throw new TypeError('hsts.preloadState is unsupported.');
+    return Object.freeze({
+        state: evidenceState(item.state, 'hsts.state'),
+        observedAt: timestamp(item.observedAt, 'hsts.observedAt'),
+        header: optionalText(item.header, 'hsts.header', 1_024),
+        preloadState,
+        source: text(item.source, 'hsts.source', 240),
+    });
+}
+function serviceInventory(snapshots) {
+    return Object.freeze(snapshots.flatMap((snapshot) => snapshot.records
+        .filter((item) => item.type === 'SRV')
+        .map((item) => Object.freeze({ owner: item.owner, value: item.value, source: snapshot.source, state: snapshot.state, observedAt: snapshot.observedAt })))
+        .sort((left, right) => left.owner.localeCompare(right.owner) || left.value.localeCompare(right.value)));
+}
+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.`);
+    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 authorityMatrix = recordMatrix(authoritySnapshots);
+    const resolverMatrix = recordMatrix(resolverSnapshots);
+    const acmeDependencies = normaliseAcme(input.acmeDependencies ?? [], apex);
+    const certificate = normaliseCertificate(input.certificate);
+    const hsts = normaliseHsts(input.hsts);
+    const certificateReview = reviewCertificate(certificate);
+    const differentAuthorityRows = authorityMatrix.filter((row) => row.state === 'different');
+    const differentResolverRows = resolverMatrix.filter((row) => row.state === 'different');
+    const insufficientAuthorityRows = authorityMatrix.filter((row) => row.state === 'insufficient');
+    const insufficientResolverRows = resolverMatrix.filter((row) => row.state === 'insufficient');
+    const observedAuthorityCount = authoritySnapshots.filter((item) => item.state === 'observed').length;
+    const observedResolverCount = resolverSnapshots.filter((item) => item.state === 'observed').length;
+    const incompleteVantages = [...authoritySnapshots, ...resolverSnapshots].filter((item) => item.state !== 'observed');
+    const gateReasons = [
+        ...(observedAuthorityCount < 2
+            ? ['At least two complete authority observations are required before a domain change can be marked ready.'] : []),
+        ...(!authorityMatrix.length
+            ? ['No comparable authority record evidence was supplied.'] : []),
+        ...differentAuthorityRows.map((row) => `Authority observations differ for ${row.owner} ${row.type}.`),
+        ...insufficientAuthorityRows.map((row) => `Authority evidence is insufficient for ${row.owner} ${row.type}.`),
+        ...(resolverSnapshots.length > 0 && observedResolverCount < 2
+            ? ['Supplied resolver evidence requires at least two complete observations.'] : []),
+        ...differentResolverRows.map((row) => `Resolver observations differ for ${row.owner} ${row.type}.`),
+        ...insufficientResolverRows.map((row) => `Resolver evidence is insufficient for ${row.owner} ${row.type}.`),
+        ...incompleteVantages.map((item) => `${item.label} evidence is ${item.state}.`),
+        ...acmeDependencies.filter((item) => item.state !== 'confirmed').map((item) => `${item.method} dependency for ${item.owner} is ${item.state}.`),
+        ...(certificate && certificate.state !== 'observed'
+            ? [`Certificate evidence is ${certificate.state}.`] : []),
+        ...(certificate?.state === 'observed' && certificateReview.continuity === 'unknown'
+            ? ['Certificate continuity cannot be reviewed without both current and planned public-key fingerprints.'] : []),
+        ...certificateReview.findings,
+        ...(hsts && hsts.state !== 'observed'
+            ? [`HSTS evidence is ${hsts.state}.`] : []),
+        ...(hsts?.state === 'observed' && hsts.preloadState === 'unavailable'
+            ? ['HSTS preload evidence is unavailable.'] : []),
+    ];
+    const reviewRequired = gateReasons.length > 0;
+    return Object.freeze({
+        schema: DOMAIN_CHANGE_REVIEW_SCHEMA,
+        version: DOMAIN_CHANGE_REVIEW_VERSION,
+        generatedAt: timestamp(generatedAtValue, 'generatedAt'),
+        domain: apex,
+        state: reviewRequired ? 'review' : 'ready',
+        authoritativeRecordMatrix: authorityMatrix,
+        resolverDivergenceMatrix: resolverMatrix,
+        dnssecAutomation: reviewDnssecAutomation(authorityMatrix),
+        acmeDependencies,
+        certificate: certificateReview,
+        services: serviceInventory([...authoritySnapshots, ...resolverSnapshots]),
+        hsts,
+        gate: Object.freeze({
+            pass: !reviewRequired,
+            reasons: Object.freeze(gateReasons),
+        }),
+        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.',
+            '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.',
+        ]),
+    });
+}

package/lib/domain-control-flight-recorder.mjs

@@ -0,0 +1,268 @@
+import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
+export const DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA = 'whoisleuth.domain-control-flight-recorder.input';
+export const DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA = 'whoisleuth.domain-control-flight-recorder';
+export const DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION = 1;
+export const MAX_FLIGHT_RECORDER_OBSERVATIONS = 200;
+export const MAX_FLIGHT_RECORDER_WINDOWS = 40;
+export const MAX_FLIGHT_RECORDER_FIELDS = 24;
+export const MAX_FLIGHT_RECORDER_VALUES = 32;
+export const DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS = [
+    'registrar',
+    'registrar_lock',
+    'registry_dnssec',
+    'registry_nameservers',
+    'whois_nameservers',
+    'delegated_nameservers',
+    'delegation_ds',
+    'mail_exchangers',
+    'caa_policy',
+    'tls_certificate',
+    'tls_public_key',
+    'http_origin',
+    'page_identity',
+];
+const ROOT_KEYS = new Set(['schema', 'version', 'observations', 'approvedWindows']);
+const OBSERVATION_KEYS = new Set(['domain', 'observedAt', 'collectionDepth', 'fields']);
+const FIELD_KEYS = new Set(['id', 'source', 'state', 'values']);
+const WINDOW_KEYS = new Set(['id', 'domain', 'startsAt', 'endsAt', 'fields', 'reason']);
+const FIELD_IDS = new Set(DOMAIN_CONTROL_FLIGHT_RECORDER_FIELDS);
+const STATES = new Set(['observed', 'partial', 'unavailable', 'unsupported']);
+const CONTROL_REPLACE_RE = /[\u0000-\u001f\u007f]+/gu;
+function text(value, label, maximum = 240) {
+    return requireBoundedString(value, label, maximum)
+        .replace(CONTROL_REPLACE_RE, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+function values(value, label) {
+    if (!Array.isArray(value) || value.length > MAX_FLIGHT_RECORDER_VALUES * 2) {
+        throw new TypeError(`${label} must contain no more than ${MAX_FLIGHT_RECORDER_VALUES * 2} bounded values.`);
+    }
+    const output = new Set();
+    for (const [index, item] of value.entries()) {
+        const normalized = text(item, `${label}[${index}]`, 500).toLowerCase();
+        if (normalized)
+            output.add(normalized);
+        if (output.size >= MAX_FLIGHT_RECORDER_VALUES)
+            break;
+    }
+    return [...output].sort();
+}
+function observation(value, index) {
+    const item = requireRecord(value, `observations[${index}]`);
+    exactKeys(item, OBSERVATION_KEYS, `observations[${index}]`);
+    if (!Array.isArray(item.fields) || item.fields.length > MAX_FLIGHT_RECORDER_FIELDS) {
+        throw new TypeError(`observations[${index}].fields must contain no more than ${MAX_FLIGHT_RECORDER_FIELDS} fields.`);
+    }
+    const seen = new Set();
+    const fields = item.fields.map((raw, fieldIndex) => {
+        const field = requireRecord(raw, `observations[${index}].fields[${fieldIndex}]`);
+        exactKeys(field, FIELD_KEYS, `observations[${index}].fields[${fieldIndex}]`);
+        if (typeof field.id !== 'string' || !FIELD_IDS.has(field.id) || seen.has(field.id)) {
+            throw new TypeError(`observations[${index}] contains an unsupported or duplicate field.`);
+        }
+        if (typeof field.state !== 'string' || !STATES.has(field.state)) {
+            throw new TypeError(`observations[${index}].fields[${fieldIndex}].state is unsupported.`);
+        }
+        seen.add(field.id);
+        return Object.freeze({
+            id: field.id,
+            source: text(field.source, `observations[${index}].fields[${fieldIndex}].source`, 120),
+            state: field.state,
+            values: Object.freeze(values(field.values, `observations[${index}].fields[${fieldIndex}].values`)),
+        });
+    }).sort((left, right) => left.id.localeCompare(right.id));
+    const collectionDepth = item.collectionDepth === 'deep' || item.collectionDepth === 'fast'
+        ? item.collectionDepth
+        : item.collectionDepth === 'unknown'
+            ? 'unknown'
+            : null;
+    if (!collectionDepth)
+        throw new TypeError(`observations[${index}].collectionDepth is unsupported.`);
+    return Object.freeze({
+        domain: requireDomainName(item.domain, `observations[${index}].domain`),
+        observedAt: requireIsoTimestamp(item.observedAt, `observations[${index}].observedAt`),
+        collectionDepth,
+        fields: Object.freeze(fields),
+    });
+}
+function approvedWindow(value, index) {
+    const item = requireRecord(value, `approvedWindows[${index}]`);
+    exactKeys(item, WINDOW_KEYS, `approvedWindows[${index}]`);
+    if (!Array.isArray(item.fields) || item.fields.length < 1 || item.fields.length > MAX_FLIGHT_RECORDER_FIELDS) {
+        throw new TypeError(`approvedWindows[${index}].fields must contain from 1 to ${MAX_FLIGHT_RECORDER_FIELDS} fields.`);
+    }
+    const fields = [...new Set(item.fields.map((field) => {
+            if (typeof field !== 'string' || !FIELD_IDS.has(field)) {
+                throw new TypeError(`approvedWindows[${index}] contains an unsupported field.`);
+            }
+            return field;
+        }))].sort();
+    const startsAt = requireIsoTimestamp(item.startsAt, `approvedWindows[${index}].startsAt`);
+    const endsAt = requireIsoTimestamp(item.endsAt, `approvedWindows[${index}].endsAt`);
+    if (Date.parse(endsAt) <= Date.parse(startsAt)) {
+        throw new TypeError(`approvedWindows[${index}].endsAt must be later than startsAt.`);
+    }
+    return Object.freeze({
+        id: text(item.id, `approvedWindows[${index}].id`, 64),
+        domain: requireDomainName(item.domain, `approvedWindows[${index}].domain`),
+        startsAt,
+        endsAt,
+        fields: Object.freeze(fields),
+        reason: text(item.reason, `approvedWindows[${index}].reason`, 400),
+    });
+}
+function sameValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function matchingWindow(windows, domain, field, observedAt) {
+    const time = Date.parse(observedAt);
+    return windows.find((window) => (window.domain === domain
+        && window.fields.includes(field)
+        && Date.parse(window.startsAt) <= time
+        && time <= Date.parse(window.endsAt))) ?? null;
+}
+export function buildDomainControlFlightRecorder(inputRaw, generatedAtValue = new Date().toISOString()) {
+    const input = requireRecord(inputRaw, 'Domain control flight-recorder input');
+    if (input.schema !== DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA || input.version !== 1) {
+        throw new TypeError(`Domain control flight-recorder input must use ${DOMAIN_CONTROL_FLIGHT_RECORDER_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'Domain control flight-recorder input');
+    if (!Array.isArray(input.observations)
+        || input.observations.length < 1
+        || input.observations.length > MAX_FLIGHT_RECORDER_OBSERVATIONS) {
+        throw new TypeError(`Domain control flight-recorder input must contain from 1 to ${MAX_FLIGHT_RECORDER_OBSERVATIONS} observations.`);
+    }
+    if (!Array.isArray(input.approvedWindows) || input.approvedWindows.length > MAX_FLIGHT_RECORDER_WINDOWS) {
+        throw new TypeError(`approvedWindows must contain no more than ${MAX_FLIGHT_RECORDER_WINDOWS} entries.`);
+    }
+    const observations = input.observations.map(observation)
+        .sort((left, right) => Date.parse(left.observedAt) - Date.parse(right.observedAt) || left.domain.localeCompare(right.domain));
+    const windows = input.approvedWindows.map(approvedWindow);
+    if (new Set(windows.map((window) => window.id)).size !== windows.length) {
+        throw new TypeError('Approved change-window ids must be unique.');
+    }
+    const generatedAt = requireIsoTimestamp(generatedAtValue, 'generatedAt');
+    const latest = new Map();
+    const events = [];
+    for (const item of observations) {
+        for (const field of item.fields) {
+            const key = `${item.domain}\u0000${field.id}`;
+            const previous = latest.get(key);
+            latest.set(key, field);
+            if (!previous) {
+                if (field.state !== 'observed')
+                    continue;
+                events.push(Object.freeze({
+                    id: `${item.domain}:${field.id}:${item.observedAt}`,
+                    domain: item.domain,
+                    field: field.id,
+                    observedAt: item.observedAt,
+                    kind: 'first_observation',
+                    state: 'observed',
+                    before: Object.freeze([]),
+                    after: field.values,
+                    source: field.source,
+                    approvedWindow: null,
+                    explanation: 'The first complete value for this source-attributed field was retained.',
+                }));
+                continue;
+            }
+            const window = matchingWindow(windows, item.domain, field.id, item.observedAt);
+            if (previous.state === 'observed' && field.state === 'observed') {
+                if (sameValues(previous.values, field.values))
+                    continue;
+                events.push(Object.freeze({
+                    id: `${item.domain}:${field.id}:${item.observedAt}`,
+                    domain: item.domain,
+                    field: field.id,
+                    observedAt: item.observedAt,
+                    kind: 'observed_change',
+                    state: 'observed',
+                    before: previous.values,
+                    after: field.values,
+                    source: field.source,
+                    approvedWindow: window ? Object.freeze({ id: window.id, reason: window.reason }) : null,
+                    explanation: window
+                        ? 'A complete observed value changed during an analyst-approved change window. The evidence is retained and labelled expected rather than removed.'
+                        : 'Two complete source-attributed observations contain different values.',
+                }));
+            }
+            else if (previous.state !== 'observed' && field.state === 'observed') {
+                events.push(Object.freeze({
+                    id: `${item.domain}:${field.id}:${item.observedAt}`,
+                    domain: item.domain,
+                    field: field.id,
+                    observedAt: item.observedAt,
+                    kind: 'recovered',
+                    state: 'observed',
+                    before: Object.freeze([]),
+                    after: field.values,
+                    source: field.source,
+                    approvedWindow: null,
+                    explanation: 'Collection returned a complete value after an earlier incomplete source state.',
+                }));
+            }
+            else if (previous.state === 'observed' && field.state !== 'observed') {
+                events.push(Object.freeze({
+                    id: `${item.domain}:${field.id}:${item.observedAt}`,
+                    domain: item.domain,
+                    field: field.id,
+                    observedAt: item.observedAt,
+                    kind: 'collection_change',
+                    state: 'partial',
+                    before: previous.values,
+                    after: Object.freeze([]),
+                    source: field.source,
+                    approvedWindow: null,
+                    explanation: `The source became ${field.state}; this is a collection-quality change, not evidence that the prior value disappeared.`,
+                }));
+            }
+        }
+    }
+    const domains = [...new Set(observations.map((item) => item.domain))].sort();
+    const observedChanges = events.filter((event) => event.kind === 'observed_change');
+    const collectionChanges = events.filter((event) => event.kind === 'collection_change');
+    return Object.freeze({
+        schema: DOMAIN_CONTROL_FLIGHT_RECORDER_SCHEMA,
+        version: DOMAIN_CONTROL_FLIGHT_RECORDER_VERSION,
+        generatedAt,
+        domains: Object.freeze(domains),
+        observationCount: observations.length,
+        events: Object.freeze(events),
+        summary: Object.freeze({
+            firstObservations: events.filter((event) => event.kind === 'first_observation').length,
+            observedChanges: observedChanges.length,
+            approvedChanges: observedChanges.filter((event) => event.approvedWindow !== null).length,
+            unexpectedChanges: observedChanges.filter((event) => event.approvedWindow === null).length,
+            collectionChanges: collectionChanges.length,
+            recoveredSources: events.filter((event) => event.kind === 'recovered').length,
+        }),
+        limitations: Object.freeze([
+            'The flight recorder compares only supplied bounded observations and performs no collection or configuration change.',
+            'Source fields remain separate. A collection failure, partial result, unsupported source, or missing field never becomes evidence that a prior value disappeared.',
+            'Approved windows label expected timing but do not delete evidence or establish that a change was authorised, successful, safe, or complete.',
+            'Observed changes can reflect publication lag or different collection conditions and require analyst review.',
+        ]),
+    });
+}
+export function formatDomainControlFlightRecorder(document) {
+    const lines = [
+        'Domain-control flight recorder',
+        `Domains             ${document.domains.length}`,
+        `Observations        ${document.observationCount}`,
+        `Unexpected changes  ${document.summary.unexpectedChanges}`,
+        `Approved changes    ${document.summary.approvedChanges}`,
+        `Collection changes  ${document.summary.collectionChanges}`,
+        '',
+    ];
+    for (const event of document.events.filter((item) => item.kind !== 'first_observation')) {
+        lines.push(`${event.observedAt}  ${event.domain}  ${event.field.replaceAll('_', ' ')}  ${event.kind.replaceAll('_', ' ')}`);
+        lines.push(`  ${event.explanation}`);
+    }
+    if (!document.events.some((item) => item.kind !== 'first_observation')) {
+        lines.push('No retained transition was available between the supplied observations.');
+    }
+    lines.push('', ...document.limitations.map((item) => `Limitation: ${item}`), '');
+    return lines.join('\n');
+}