@slicedearth/whoisleuth-cli 1.34.0 → 1.39.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-assurance.mjs

@@ -0,0 +1,368 @@
+import { domainToASCII } from 'node:url';
+import { exactKeys } from "./bounded-contract-normalizers.mjs";
+const DOMAIN_ASSURANCE_INPUT_SCHEMA = 'whoisleuth.domain-assurance.input';
+const DOMAIN_ASSURANCE_SCHEMA = 'whoisleuth.domain-assurance';
+const DOMAIN_ASSURANCE_VERSION = 2;
+const DOMAIN_ASSURANCE_SUPPORTED_INPUT_VERSIONS = Object.freeze([1, 2]);
+const MAX_ASSURANCE_INPUT_BYTES = 2 * 1024 * 1024;
+const ROOT_KEYS = Object.freeze({
+    'planned-change': new Set(['schema', 'version', 'kind', 'domain', 'change']),
+    'recovery-dependencies': new Set(['schema', 'version', 'kind', 'assets']),
+    retirement: new Set(['schema', 'version', 'kind', 'domain', 'checks']),
+});
+const RETIREMENT_ROOT_KEYS_V2 = new Set(['schema', 'version', 'kind', 'domain', 'checks', 'customChecks']);
+const CHANGE_KEYS = new Set(['reference', 'startsAt', 'endsAt', 'milestones', 'rollbackCriteria', 'postChangeChecks']);
+const MILESTONE_KEYS = new Set(['id', 'label', 'expectedBy', 'evidenceSource', 'state', 'observedAt', 'evidenceReference']);
+const ROLLBACK_KEYS = new Set(['id', 'condition', 'owner', 'state']);
+const POST_CHANGE_CHECK_KEYS = new Set(['id', 'label', 'expectedState', 'evidenceSource', 'state', 'evidenceReference']);
+const RECOVERY_ASSET_KEYS = new Set(['domain', 'dependencies', 'readiness']);
+const RECOVERY_DEPENDENCY_KEYS = new Set(['registrar', 'dns', 'mail', 'certificate', 'recovery']);
+const RECOVERY_READINESS_KEYS = new Set(['registrarRecoveryTested', 'dnsRecoveryTested', 'recoveryMfaProtected']);
+const CUSTOM_RETIREMENT_CHECK_KEYS = new Set(['id', 'label', 'expected', 'value']);
+const CUSTOM_RETIREMENT_CHECK_ID_RE = /^[a-z][a-z0-9-]{0,63}$/u;
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Domain assurance input must be one JSON object.');
+    return value;
+}
+function text(value, field, maximum = 160) {
+    if (typeof value !== 'string')
+        throw new Error(`${field} must be text.`);
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+    if (!normalized || normalized.length > maximum)
+        throw new Error(`${field} must contain from 1 to ${maximum} characters.`);
+    return normalized;
+}
+function optionalText(value, maximum = 160) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    if (typeof value !== 'string')
+        throw new Error('Optional domain assurance labels must be text.');
+    const normalized = value.replace(/[\u0000-\u001f\u007f]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+    if (!normalized || normalized.length > maximum)
+        throw new Error(`Optional domain assurance labels are limited to ${maximum} characters.`);
+    return normalized;
+}
+function timestamp(value, field) {
+    const normalized = text(value, field, 64);
+    if (!Number.isFinite(Date.parse(normalized)))
+        throw new Error(`${field} must be an ISO-compatible timestamp.`);
+    return new Date(normalized).toISOString();
+}
+function optionalTimestamp(value, field) {
+    if (value === null || value === undefined || value === '')
+        return null;
+    return timestamp(value, field);
+}
+function domain(value, field = 'domain') {
+    const normalized = text(value, field, 253).toLowerCase().replace(/\.$/u, '');
+    let ascii;
+    try {
+        ascii = domainToASCII(normalized);
+    }
+    catch {
+        throw new Error(`${field} must be a valid domain name.`);
+    }
+    if (!ascii || !ascii.includes('.') || ascii.length > 253 || !ascii.split('.').every((labelValue) => (labelValue.length >= 1 && labelValue.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(labelValue))))
+        throw new Error(`${field} must be a valid domain name.`);
+    return ascii;
+}
+function boundedArray(value, field, minimum, maximum) {
+    if (!Array.isArray(value) || value.length < minimum || value.length > maximum) {
+        throw new Error(`${field} must contain from ${minimum} to ${maximum} items.`);
+    }
+    return value;
+}
+function nullableBoolean(value, field) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'boolean')
+        throw new Error(`${field} must be true, false, or null.`);
+    return value;
+}
+function enumValue(value, field, allowed) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new Error(`${field} must be one of: ${allowed.join(', ')}.`);
+    }
+    return value;
+}
+function reviewState(reasons, negative) {
+    if (negative)
+        return 'needs_review';
+    return reasons.length ? 'incomplete' : 'ready';
+}
+function buildPlannedChange(input) {
+    const target = domain(input.domain);
+    const change = record(input.change);
+    exactKeys(change, CHANGE_KEYS, 'change');
+    const startsAt = timestamp(change.startsAt, 'change.startsAt');
+    const endsAt = timestamp(change.endsAt, 'change.endsAt');
+    if (Date.parse(endsAt) <= Date.parse(startsAt))
+        throw new Error('change.endsAt must be later than change.startsAt.');
+    const ids = new Set();
+    const uniqueId = (value, field) => {
+        const id = text(value, field, 64);
+        if (ids.has(id))
+            throw new Error(`Domain assurance item id "${id}" is duplicated.`);
+        ids.add(id);
+        return id;
+    };
+    const milestones = boundedArray(change.milestones, 'change.milestones', 1, 24).map((raw, index) => {
+        const item = record(raw);
+        exactKeys(item, MILESTONE_KEYS, `change.milestones[${index}]`);
+        const state = enumValue(item.state, `change.milestones[${index}].state`, ['missed', 'not_checked', 'observed', 'planned']);
+        const observedAt = optionalTimestamp(item.observedAt, `change.milestones[${index}].observedAt`);
+        const evidenceReference = optionalText(item.evidenceReference, 300);
+        if ((state === 'observed' || state === 'missed') && (!observedAt || !evidenceReference)) {
+            throw new Error('Observed or missed change milestones require observedAt and evidenceReference.');
+        }
+        if ((state === 'planned' || state === 'not_checked') && (observedAt || evidenceReference)) {
+            throw new Error('Planned or unchecked change milestones cannot contain observation evidence.');
+        }
+        return {
+            id: uniqueId(item.id, `change.milestones[${index}].id`),
+            label: text(item.label, `change.milestones[${index}].label`, 180),
+            expectedBy: timestamp(item.expectedBy, `change.milestones[${index}].expectedBy`),
+            evidenceSource: text(item.evidenceSource, `change.milestones[${index}].evidenceSource`, 120),
+            state,
+            observedAt,
+            evidenceReference,
+        };
+    });
+    const rollbackCriteria = boundedArray(change.rollbackCriteria, 'change.rollbackCriteria', 1, 16).map((raw, index) => {
+        const item = record(raw);
+        exactKeys(item, ROLLBACK_KEYS, `change.rollbackCriteria[${index}]`);
+        return {
+            id: uniqueId(item.id, `change.rollbackCriteria[${index}].id`),
+            condition: text(item.condition, `change.rollbackCriteria[${index}].condition`, 240),
+            owner: text(item.owner, `change.rollbackCriteria[${index}].owner`, 120),
+            state: enumValue(item.state, `change.rollbackCriteria[${index}].state`, ['met', 'not_checked', 'not_met']),
+        };
+    });
+    const postChangeChecks = boundedArray(change.postChangeChecks, 'change.postChangeChecks', 1, 24).map((raw, index) => {
+        const item = record(raw);
+        exactKeys(item, POST_CHANGE_CHECK_KEYS, `change.postChangeChecks[${index}]`);
+        const state = enumValue(item.state, `change.postChangeChecks[${index}].state`, ['matched', 'not_checked', 'unexpected']);
+        const evidenceReference = optionalText(item.evidenceReference, 300);
+        if (state !== 'not_checked' && !evidenceReference)
+            throw new Error('Completed post-change checks require evidenceReference.');
+        if (state === 'not_checked' && evidenceReference)
+            throw new Error('Unchecked post-change checks cannot contain an evidenceReference.');
+        return {
+            id: uniqueId(item.id, `change.postChangeChecks[${index}].id`),
+            label: text(item.label, `change.postChangeChecks[${index}].label`, 180),
+            expectedState: text(item.expectedState, `change.postChangeChecks[${index}].expectedState`, 240),
+            evidenceSource: text(item.evidenceSource, `change.postChangeChecks[${index}].evidenceSource`, 120),
+            state,
+            evidenceReference,
+        };
+    });
+    const reasons = [
+        ...(milestones.some((item) => item.state === 'missed') ? ['One or more change milestones were missed.'] : []),
+        ...(milestones.some((item) => item.state === 'planned' || item.state === 'not_checked') ? ['One or more planned milestones have not been observed.'] : []),
+        ...(rollbackCriteria.some((item) => item.state === 'met') ? ['One or more rollback criteria were met.'] : []),
+        ...(rollbackCriteria.some((item) => item.state === 'not_checked') ? ['One or more rollback criteria have not been evaluated.'] : []),
+        ...(postChangeChecks.some((item) => item.state === 'unexpected') ? ['One or more post-change checks produced an unexpected result.'] : []),
+        ...(postChangeChecks.some((item) => item.state === 'not_checked') ? ['One or more post-change checks remain open.'] : []),
+    ];
+    const negative = milestones.some((item) => item.state === 'missed')
+        || rollbackCriteria.some((item) => item.state === 'met')
+        || postChangeChecks.some((item) => item.state === 'unexpected');
+    return {
+        kind: 'planned-change',
+        domain: target,
+        reference: text(change.reference, 'change.reference', 120),
+        window: { startsAt, endsAt },
+        milestones,
+        rollbackCriteria,
+        postChangeChecks,
+        review: { state: reviewState(reasons, negative), reasons },
+    };
+}
+function buildRecoveryDependencies(input) {
+    const assets = boundedArray(input.assets, 'assets', 1, 100).map((raw, index) => {
+        const item = record(raw);
+        exactKeys(item, RECOVERY_ASSET_KEYS, `assets[${index}]`);
+        const dependencies = record(item.dependencies);
+        const readiness = record(item.readiness);
+        exactKeys(dependencies, RECOVERY_DEPENDENCY_KEYS, `assets[${index}].dependencies`);
+        exactKeys(readiness, RECOVERY_READINESS_KEYS, `assets[${index}].readiness`);
+        return {
+            domain: domain(item.domain, `assets[${index}].domain`),
+            dependencies: {
+                registrar: optionalText(dependencies.registrar, 120),
+                dns: optionalText(dependencies.dns, 120),
+                mail: optionalText(dependencies.mail, 120),
+                certificate: optionalText(dependencies.certificate, 120),
+                recovery: optionalText(dependencies.recovery, 120),
+            },
+            readiness: {
+                registrarRecoveryTested: nullableBoolean(readiness.registrarRecoveryTested, `assets[${index}].readiness.registrarRecoveryTested`),
+                dnsRecoveryTested: nullableBoolean(readiness.dnsRecoveryTested, `assets[${index}].readiness.dnsRecoveryTested`),
+                recoveryMfaProtected: nullableBoolean(readiness.recoveryMfaProtected, `assets[${index}].readiness.recoveryMfaProtected`),
+            },
+        };
+    });
+    if (new Set(assets.map((asset) => asset.domain)).size !== assets.length)
+        throw new Error('Recovery dependency domains must be unique.');
+    const dependencyTypes = ['registrar', 'dns', 'mail', 'certificate', 'recovery'];
+    const concentrations = dependencyTypes.flatMap((dependencyType) => {
+        const byProvider = new Map();
+        for (const asset of assets) {
+            const provider = asset.dependencies[dependencyType];
+            if (!provider)
+                continue;
+            const key = provider.toLowerCase();
+            const group = byProvider.get(key) ?? { label: provider, domains: [] };
+            group.domains.push(asset.domain);
+            byProvider.set(key, group);
+        }
+        return [...byProvider.values()].filter(({ domains }) => domains.length > 1).map(({ label: provider, domains }) => ({
+            dependencyType,
+            provider,
+            domains: domains.sort(),
+            share: Number((domains.length / assets.length).toFixed(4)),
+        }));
+    }).sort((left, right) => right.share - left.share || left.dependencyType.localeCompare(right.dependencyType));
+    const unknownDependencies = assets.reduce((total, asset) => (total + dependencyTypes.filter((dependencyType) => asset.dependencies[dependencyType] === null).length), 0);
+    const failedReadinessChecks = assets.reduce((total, asset) => (total + Object.values(asset.readiness).filter((value) => value === false).length), 0);
+    const reasons = [
+        ...(failedReadinessChecks ? [`${failedReadinessChecks} recovery readiness check${failedReadinessChecks === 1 ? ' is' : 's are'} recorded as not ready.`] : []),
+        ...(unknownDependencies ? [`${unknownDependencies} dependency fields are not recorded.`] : []),
+        ...(assets.some((asset) => Object.values(asset.readiness).some((value) => value === null)) ? ['One or more recovery checks have not been recorded.'] : []),
+    ];
+    const negative = assets.some((asset) => Object.values(asset.readiness).some((value) => value === false));
+    return {
+        kind: 'recovery-dependencies',
+        assets,
+        concentrations,
+        unknownDependencies,
+        review: { state: reviewState(reasons, negative), reasons },
+    };
+}
+const RETIREMENT_CHECKS = Object.freeze([
+    ['autoRenewDisabled', 'Auto-renew is intentionally configured', true],
+    ['registrarLockMaintained', 'Registrar lock remains enabled', true],
+    ['websiteRetired', 'Web service is retired or intentionally redirected', true],
+    ['mailRetired', 'Mail service is retired', true],
+    ['nullMxPublished', 'Null MX is published when the domain must not receive mail', true],
+    ['spfRestrictive', 'SPF policy is intentionally restrictive', true],
+    ['dmarcReject', 'DMARC enforcement is intentionally strict', true],
+    ['certificatesReviewed', 'Active and historical certificate exposure was reviewed', true],
+    ['delegatedDnsMonitored', 'Delegated DNS remains monitored during retirement', true],
+    ['reRegistrationPrevented', 'Registration continuity or defensive renewal is planned', true],
+]);
+function buildRetirement(input, inputVersion) {
+    const checksInput = record(input.checks);
+    exactKeys(checksInput, new Set(RETIREMENT_CHECKS.map(([id]) => id)), 'checks');
+    const fixedChecks = RETIREMENT_CHECKS.map(([id, checkLabel, expected]) => {
+        const value = nullableBoolean(checksInput[id], `checks.${id}`);
+        return {
+            id,
+            label: checkLabel,
+            state: value === null ? 'not_checked' : value === expected ? 'confirmed' : 'not_confirmed',
+            expected,
+        };
+    });
+    const fixedIds = new Set(RETIREMENT_CHECKS.map(([id]) => id));
+    const customIds = new Set();
+    const customChecks = inputVersion === 2 && input.customChecks !== undefined
+        ? boundedArray(input.customChecks, 'customChecks', 0, 20).map((raw, index) => {
+            const item = record(raw);
+            exactKeys(item, CUSTOM_RETIREMENT_CHECK_KEYS, `customChecks[${index}]`);
+            const id = text(item.id, `customChecks[${index}].id`, 64);
+            if (!CUSTOM_RETIREMENT_CHECK_ID_RE.test(id)) {
+                throw new Error(`customChecks[${index}].id must use lowercase letters, digits, and hyphens and begin with a letter.`);
+            }
+            if (fixedIds.has(id) || customIds.has(id))
+                throw new Error(`Retirement check id "${id}" is duplicated.`);
+            customIds.add(id);
+            if (typeof item.expected !== 'boolean')
+                throw new Error(`customChecks[${index}].expected must be true or false.`);
+            const value = nullableBoolean(item.value, `customChecks[${index}].value`);
+            return {
+                id,
+                label: text(item.label, `customChecks[${index}].label`, 180),
+                state: value === null ? 'not_checked' : value === item.expected ? 'confirmed' : 'not_confirmed',
+                expected: item.expected,
+            };
+        })
+        : [];
+    const checks = [...fixedChecks, ...customChecks];
+    const reasons = checks.flatMap((check) => check.state === 'not_confirmed'
+        ? [`The expected retirement state for "${check.label}" is not confirmed.`]
+        : check.state === 'not_checked'
+            ? [`${check.label} has not been checked.`]
+            : []);
+    const negative = checks.some((check) => check.state === 'not_confirmed');
+    return {
+        kind: 'retirement',
+        domain: domain(input.domain),
+        checks,
+        review: { state: reviewState(reasons, negative), reasons: reasons.slice(0, 20) },
+    };
+}
+function buildDomainAssurance(inputRaw, generatedAt = new Date().toISOString()) {
+    const input = record(inputRaw);
+    if (input.schema !== DOMAIN_ASSURANCE_INPUT_SCHEMA
+        || !DOMAIN_ASSURANCE_SUPPORTED_INPUT_VERSIONS.includes(input.version)) {
+        throw new Error(`Domain assurance input must use ${DOMAIN_ASSURANCE_INPUT_SCHEMA} version 1 or ${DOMAIN_ASSURANCE_VERSION}.`);
+    }
+    const inputVersion = input.version;
+    const kind = enumValue(input.kind, 'kind', ['planned-change', 'recovery-dependencies', 'retirement']);
+    exactKeys(input, kind === 'retirement' && inputVersion === 2 ? RETIREMENT_ROOT_KEYS_V2 : ROOT_KEYS[kind], 'Domain assurance input');
+    const result = kind === 'planned-change'
+        ? buildPlannedChange(input)
+        : kind === 'recovery-dependencies'
+            ? buildRecoveryDependencies(input)
+            : buildRetirement(input, inputVersion);
+    return {
+        schema: DOMAIN_ASSURANCE_SCHEMA,
+        version: DOMAIN_ASSURANCE_VERSION,
+        generatedAt: timestamp(generatedAt, 'generatedAt'),
+        result,
+        limitations: [
+            'This review uses only analyst-supplied planning and observation metadata and makes no network request or configuration change.',
+            'Provider labels, readiness checks, and evidence references are analyst-authored assertions; they are not independently verified by this report.',
+            'A ready result means the supplied checklist is complete under this schema. It is not a guarantee of control, recovery, successful change, or safe retirement.',
+            'Do not include passwords, recovery codes, private keys, personal contact details, or other secrets in an assurance input.',
+        ],
+    };
+}
+function formatDomainAssurance(document) {
+    const { result } = document;
+    const output = [
+        'Domain assurance review',
+        `Workflow          ${result.kind.replaceAll('-', ' ')}`,
+        `State             ${result.review.state.replaceAll('_', ' ')}`,
+    ];
+    if ('domain' in result)
+        output.push(`Domain            ${result.domain}`);
+    if (result.kind === 'recovery-dependencies') {
+        output.push(`Assets            ${result.assets.length}`);
+        output.push(`Concentrations    ${result.concentrations.length}`);
+        output.push(`Unknown fields    ${result.unknownDependencies}`);
+        for (const concentration of result.concentrations) {
+            output.push(`  ${concentration.dependencyType}: ${concentration.provider} (${concentration.domains.length}/${result.assets.length})`);
+        }
+    }
+    else if (result.kind === 'planned-change') {
+        output.push(`Change reference  ${result.reference}`);
+        output.push(`Milestones        ${result.milestones.length}`);
+        output.push(`Rollback criteria ${result.rollbackCriteria.length}`);
+        output.push(`Post-change checks ${result.postChangeChecks.length}`);
+    }
+    else {
+        output.push(`Confirmed         ${result.checks.filter((check) => check.state === 'confirmed').length}/${result.checks.length}`);
+    }
+    if (result.review.reasons.length) {
+        output.push('', 'Review reasons:');
+        for (const reason of result.review.reasons)
+            output.push(`  - ${reason}`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of document.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { DOMAIN_ASSURANCE_INPUT_SCHEMA, DOMAIN_ASSURANCE_SCHEMA, DOMAIN_ASSURANCE_SUPPORTED_INPUT_VERSIONS, DOMAIN_ASSURANCE_VERSION, MAX_ASSURANCE_INPUT_BYTES, buildDomainAssurance, formatDomainAssurance, };