@slicedearth/whoisleuth-cli 1.36.1 → 1.39.1

package/lib/certificate-extension-profile.mjs

@@ -0,0 +1,71 @@
+// Narrow X.509 extension parsing for fields unavailable through Node's native
+// X509Certificate API. Raw certificates and extension locations are never
+// retained; malformed extensions fail soft and leave an explicit partial flag.
+import 'reflect-metadata';
+import { CertificatePolicyExtension, CRLDistributionPointsExtension, X509Certificate, } from '@peculiar/x509';
+export const MAX_CERTIFICATE_POLICIES = 16;
+export const MAX_CRL_DISTRIBUTION_POINTS = 32;
+function emptyProfile(partial = false) {
+    return Object.freeze({
+        certificatePolicies: Object.freeze({ oids: Object.freeze([]), truncated: false }),
+        crlDistributionPoints: Object.freeze({ total: 0, http: 0, https: 0, ldap: 0, other: 0, truncated: false }),
+        parsed: false,
+        partial,
+    });
+}
+function distributionUris(extension) {
+    const uris = [];
+    for (const point of extension.distributionPoints.slice(0, MAX_CRL_DISTRIBUTION_POINTS + 1)) {
+        for (const name of point.distributionPoint?.fullName ?? []) {
+            if (typeof name.uniformResourceIdentifier === 'string')
+                uris.push(name.uniformResourceIdentifier);
+        }
+    }
+    return uris;
+}
+export function parseCertificateExtensionProfile(raw) {
+    if (!Buffer.isBuffer(raw) || raw.length === 0 || raw.length > 256 * 1024)
+        return emptyProfile();
+    try {
+        const encoded = Uint8Array.from(raw).buffer;
+        const certificate = new X509Certificate(encoded);
+        const policies = certificate.getExtension(CertificatePolicyExtension)?.policies ?? [];
+        const crlExtension = certificate.getExtension(CRLDistributionPointsExtension);
+        const uris = crlExtension ? distributionUris(crlExtension) : [];
+        const retainedPolicies = [...new Set(policies.filter((oid) => /^\d+(?:\.\d+)+$/u.test(oid)))]
+            .slice(0, MAX_CERTIFICATE_POLICIES);
+        const retainedUris = uris.slice(0, MAX_CRL_DISTRIBUTION_POINTS);
+        const schemes = { http: 0, https: 0, ldap: 0, other: 0 };
+        for (const uri of retainedUris) {
+            let protocol = '';
+            try {
+                protocol = new URL(uri).protocol.toLowerCase();
+            }
+            catch { /* counted as other */ }
+            if (protocol === 'http:')
+                schemes.http += 1;
+            else if (protocol === 'https:')
+                schemes.https += 1;
+            else if (protocol === 'ldap:' || protocol === 'ldaps:')
+                schemes.ldap += 1;
+            else
+                schemes.other += 1;
+        }
+        return Object.freeze({
+            certificatePolicies: Object.freeze({
+                oids: Object.freeze(retainedPolicies),
+                truncated: policies.length > retainedPolicies.length,
+            }),
+            crlDistributionPoints: Object.freeze({
+                total: retainedUris.length,
+                ...schemes,
+                truncated: uris.length > retainedUris.length,
+            }),
+            parsed: true,
+            partial: policies.length > retainedPolicies.length || uris.length > retainedUris.length,
+        });
+    }
+    catch {
+        return emptyProfile(true);
+    }
+}

package/lib/credential-surface-profile.mjs

@@ -18,7 +18,7 @@ function analyzeCredentialSurfaceProfile(input = {}) {
     const partial = truncated || unclassifiedActions > 0;
     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 recognized purpose.',
+        '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.',
     ];

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, };

package/lib/domain-control-manifest.mjs

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { domainToASCII } from 'node:url';
 import { canonicalArtifactJson } from "../frontend/src/lib/analysis/artifact-integrity.js";
+import { exactKeys } from "./bounded-contract-normalizers.mjs";
 export const DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA = 'whoisleuth.domain-control-manifest-input';
 export const DOMAIN_CONTROL_MANIFEST_SCHEMA = 'whoisleuth.domain-control-manifest';
 export const DOMAIN_CONTROL_MANIFEST_VERSION = 1;
@@ -9,6 +10,18 @@ export const DOMAIN_CONTROL_REVIEW_SCHEMA = 'whoisleuth.domain-control-review';
 export const DOMAIN_CONTROL_REVIEW_VERSION = 1;
 export const MAX_DOMAIN_CONTROL_ENTRIES = 100;
 export const MAX_DOMAIN_CONTROL_RECORDS = 32;
+const MANIFEST_KEYS = new Set(['schema', 'version', 'generatedAt', 'expiresAt', 'entries', 'limitations', 'integrity']);
+const MANIFEST_ENTRY_KEYS = new Set(['domain', 'nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock', 'renewalReviewAt', 'note']);
+const MANIFEST_INTEGRITY_KEYS = new Set(['algorithm', 'canonicalization', 'digestSha256']);
+const MANIFEST_INPUT_KEYS = new Set(['schema', 'version', 'expiresAt', 'entries']);
+const REVIEW_INPUT_KEYS = new Set(['schema', 'version', 'manifest', 'observations']);
+const OBSERVATION_KEYS = new Set(['domain', 'fields']);
+const OBSERVATION_FIELDS = new Set(['nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock']);
+const OBSERVATION_FIELD_KEYS = new Set(['state', 'values', 'source', 'observedAt']);
+const DOMAIN_CONTROL_LIMITATIONS = Object.freeze([
+    'This analyst-authored manifest records intended domain-control state. It does not collect evidence or change registrar, DNS, mail, or certificate configuration.',
+    'Empty desired fields are unconfigured rather than claims that a record should be absent.',
+]);
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -89,6 +102,7 @@ export function buildDomainControlManifest(input, generatedAtValue = new Date().
     if (!source || source.schema !== DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA || source.version !== 1) {
         throw new TypeError(`Domain control manifest input must use ${DOMAIN_CONTROL_MANIFEST_INPUT_SCHEMA} version 1.`);
     }
+    exactKeys(source, MANIFEST_INPUT_KEYS, 'Domain control manifest input');
     const generatedAt = timestamp(generatedAtValue);
     const expiresAt = timestamp(source.expiresAt);
     if (!generatedAt || !expiresAt || Date.parse(expiresAt) <= Date.parse(generatedAt)) {
@@ -97,7 +111,10 @@ export function buildDomainControlManifest(input, generatedAtValue = new Date().
     if (!Array.isArray(source.entries) || source.entries.length < 1 || source.entries.length > MAX_DOMAIN_CONTROL_ENTRIES) {
         throw new TypeError(`Domain control manifest input must contain between 1 and ${MAX_DOMAIN_CONTROL_ENTRIES} entries.`);
     }
-    const entries = source.entries.map(normalizeEntry);
+    const entries = source.entries.map((entry, index) => {
+        exactKeys(entry, MANIFEST_ENTRY_KEYS, `Domain control manifest input entry ${index + 1}`);
+        return normalizeEntry(entry);
+    });
     if (entries.some((entry) => entry === null))
         throw new TypeError('Domain control manifest contains an invalid entry.');
     const normalizedEntries = entries;
@@ -110,10 +127,7 @@ export function buildDomainControlManifest(input, generatedAtValue = new Date().
         generatedAt,
         expiresAt,
         entries: Object.freeze([...normalizedEntries].sort((left, right) => left.domain.localeCompare(right.domain))),
-        limitations: Object.freeze([
-            'This analyst-authored manifest records intended domain-control state. It does not collect evidence or change registrar, DNS, mail, or certificate configuration.',
-            'Empty desired fields are unconfigured rather than claims that a record should be absent.',
-        ]),
+        limitations: DOMAIN_CONTROL_LIMITATIONS,
     });
     return Object.freeze({
         ...base,
@@ -134,6 +148,8 @@ export function verifyDomainControlManifest(value) {
         || source.entries.length < 1
         || source.entries.length > MAX_DOMAIN_CONTROL_ENTRIES
         || !Array.isArray(source.limitations)
+        || source.limitations.length !== DOMAIN_CONTROL_LIMITATIONS.length
+        || source.limitations.some((limitation, index) => limitation !== DOMAIN_CONTROL_LIMITATIONS[index])
         || !integrity
         || integrity.algorithm !== 'SHA-256'
         || integrity.canonicalization !== 'sorted-json-v1'
@@ -141,18 +157,41 @@ export function verifyDomainControlManifest(value) {
         || !/^sha256:[a-f0-9]{64}$/u.test(integrity.digestSha256)) {
         throw new TypeError('Domain control manifest has an unsupported or malformed structure.');
     }
+    exactKeys(source, MANIFEST_KEYS, 'Domain control manifest');
+    exactKeys(integrity, MANIFEST_INTEGRITY_KEYS, 'Domain control manifest integrity');
+    for (const [index, entry] of source.entries.entries()) {
+        exactKeys(entry, MANIFEST_ENTRY_KEYS, `Domain control manifest entry ${index + 1}`);
+    }
     const generatedAt = timestamp(source.generatedAt);
     const expiresAt = timestamp(source.expiresAt);
     const entries = source.entries.map(normalizeEntry);
     if (!generatedAt || !expiresAt || Date.parse(expiresAt) <= Date.parse(generatedAt) || entries.some((entry) => entry === null)) {
-        throw new TypeError('Domain control manifest has invalid normalized content.');
+        throw new TypeError('Domain control manifest has invalid normalised content.');
     }
     const normalizedEntries = entries;
     if (new Set(normalizedEntries.map((entry) => entry.domain)).size !== normalizedEntries.length) {
         throw new TypeError('Domain control manifest entries must use unique domains.');
     }
     const { integrity: _integrity, ...unsigned } = source;
-    if (integrityDigest(unsigned) !== integrity.digestSha256) {
+    const canonical = Object.freeze({
+        schema: DOMAIN_CONTROL_MANIFEST_SCHEMA,
+        version: DOMAIN_CONTROL_MANIFEST_VERSION,
+        generatedAt,
+        expiresAt,
+        entries: Object.freeze([...normalizedEntries].sort((left, right) => left.domain.localeCompare(right.domain))),
+        limitations: DOMAIN_CONTROL_LIMITATIONS,
+    });
+    let suppliedCanonical;
+    try {
+        suppliedCanonical = canonicalArtifactJson(unsigned);
+    }
+    catch {
+        throw new TypeError('Domain control manifest has invalid normalised content.');
+    }
+    if (suppliedCanonical !== canonicalArtifactJson(canonical)) {
+        throw new TypeError('Domain control manifest must use its canonical normalised content.');
+    }
+    if (`sha256:${createHash('sha256').update(suppliedCanonical).digest('hex')}` !== integrity.digestSha256) {
         throw new TypeError('Domain control manifest failed its SHA-256 integrity check.');
     }
     return source;
@@ -176,11 +215,14 @@ function normalizeObservation(value) {
     const rawFields = record(source?.fields);
     if (!source || !normalizedDomain || !rawFields)
         return null;
+    exactKeys(source, OBSERVATION_KEYS, 'Domain control observation');
+    exactKeys(rawFields, OBSERVATION_FIELDS, 'Domain control observation fields');
     const fields = {};
     for (const field of ['nameservers', 'ds', 'mx', 'caa', 'tlsIssuer', 'tlsSpkiSha256', 'registrarLock']) {
         const raw = record(rawFields[field]);
         if (!raw)
             continue;
+        exactKeys(raw, OBSERVATION_FIELD_KEYS, `Domain control observation field ${field}`);
         const state = raw.state;
         if (state !== 'observed' && state !== 'partial' && state !== 'unavailable' && state !== 'unsupported')
             return null;
@@ -260,6 +302,7 @@ export function reviewDomainControlManifest(input, generatedAtValue = new Date()
     if (!source || source.schema !== DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA || source.version !== 1) {
         throw new TypeError(`Domain control review input must use ${DOMAIN_CONTROL_REVIEW_INPUT_SCHEMA} version 1.`);
     }
+    exactKeys(source, REVIEW_INPUT_KEYS, 'Domain control review input');
     const generatedAt = timestamp(generatedAtValue);
     if (!generatedAt)
         throw new TypeError('Domain control review time is invalid.');