@slicedearth/whoisleuth-cli 1.32.0

package/frontend/src/lib/analysis/brand-profile-model.js

@@ -0,0 +1,421 @@
+// Pure Brand Profile normalization and storage model. The browser wrapper owns
+// persistence and downloads; this module owns schema migration, semantic field
+// bounds, import merging, and exact serialized-byte accounting.
+import { normalizeDomain } from "./case-model.js";
+import { normalizePageBaseline } from "./page-baseline.js";
+import { isInformativeFaviconHash } from "./utils.js";
+export const BRAND_PROFILE_SCHEMA = 'whoisleuth.brand-profiles';
+export const BRAND_PROFILE_SCHEMA_VERSION = 5;
+export const MAX_PROFILES = 100;
+export const MAX_PROFILE_VALUES = 200;
+export const MAX_PROFILE_VALUE_INPUTS = MAX_PROFILE_VALUES * 4;
+// Profiles share the origin's browser-storage quota with cases, campaigns,
+// watchlists, and CT history. Fail at a predictable one-megabyte boundary.
+export const MAX_PROFILE_STORE_BYTES = 1024 * 1024;
+export const MAX_PROFILE_NAME_LENGTH = 100;
+export const MAX_PROFILE_TEXT_LENGTH = 200;
+export const MAX_PROFILE_DOMAIN_LENGTH = 253;
+export const MAX_PROFILE_TLD_LENGTH = 63;
+export const MAX_DKIM_SELECTOR_LENGTH = 253;
+export const MAX_DKIM_SELECTORS = 10;
+export const MAX_PROTECTION_ATTESTATIONS = 6;
+export const MAX_DESIRED_POSTURE_BASELINES = 20;
+export const MAX_DESIRED_POSTURE_RECORDS = 32;
+export const MAX_DESIRED_POSTURE_SUPPRESSIONS = 12;
+const SAFE_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const SHA256_RE = /^[a-f0-9]{64}$/i;
+const CONTROL_RE = /[\x00-\x1f\x7f]/;
+const DNS_LABEL_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const MAIL_PROFILES = new Set(['standard', 'defensive_no_mail', 'parked']);
+export const PROTECTION_ATTESTATION_CONTROLS = Object.freeze([
+    'registrar_mfa',
+    'recovery_email_separation',
+    'registry_lock',
+    'emergency_contacts',
+    'account_audit_logging',
+    'zone_backups',
+]);
+const PROTECTION_ATTESTATION_CONTROL_SET = new Set(PROTECTION_ATTESTATION_CONTROLS);
+const PROTECTION_ATTESTATION_STATES = new Set([
+    'observed',
+    'not_observed',
+    'needs_confirmation',
+    'unavailable',
+    'not_applicable',
+]);
+const DESIRED_POSTURE_FIELDS = new Set([
+    'nameservers',
+    'ds',
+    'mx',
+    'caa',
+    'tls_issuer',
+    'tls_san_patterns',
+    'tls_spki',
+    'registrar_lock',
+    'renewal_review',
+]);
+const POSTURE_CHECK_STATUSES = new Set(['danger', 'info', 'pass', 'warning']);
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function boundedText(value, maximum = MAX_PROFILE_TEXT_LENGTH) {
+    if (typeof value !== 'string' || CONTROL_RE.test(value))
+        return '';
+    return value.slice(0, maximum * 4).replace(/\s+/g, ' ').trim().slice(0, maximum).trim();
+}
+function safeId(value) {
+    return typeof value === 'string' && SAFE_ID_RE.test(value) ? value : null;
+}
+function timestamp(value, fallback) {
+    if (typeof value === 'string' && value.length <= 64 && !CONTROL_RE.test(value)) {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return new Date(parsed).toISOString();
+    }
+    return fallback;
+}
+function normalizeTld(value) {
+    if (typeof value !== 'string' || CONTROL_RE.test(value))
+        return '';
+    const tld = value.trim().toLowerCase().replace(/^\./, '');
+    if (!tld || tld.length > MAX_PROFILE_TLD_LENGTH || !DNS_LABEL_RE.test(tld))
+        return '';
+    return tld;
+}
+function normalizeSelector(value) {
+    if (typeof value !== 'string' || CONTROL_RE.test(value))
+        return '';
+    const selector = value.trim().toLowerCase().replace(/^\.+|\.+$/g, '');
+    if (!selector || selector.length > MAX_DKIM_SELECTOR_LENGTH)
+        return '';
+    return selector.split('.').every((label) => DNS_LABEL_RE.test(label)) ? selector : '';
+}
+function normalizeList(value, normalize) {
+    if (!Array.isArray(value))
+        return [];
+    const values = [];
+    const seen = new Set();
+    for (const item of value.slice(0, MAX_PROFILE_VALUE_INPUTS)) {
+        const normalized = normalize(item);
+        if (!normalized)
+            continue;
+        const key = normalized.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        values.push(normalized);
+        if (values.length >= MAX_PROFILE_VALUES)
+            break;
+    }
+    return values;
+}
+export function normalizeProfileDomains(value) {
+    return normalizeList(value, (item) => {
+        if (typeof item !== 'string' || item.length > MAX_PROFILE_DOMAIN_LENGTH)
+            return '';
+        return normalizeDomain(item);
+    });
+}
+export function normalizeProfileTextValues(value) {
+    return normalizeList(value, (item) => boundedText(item));
+}
+export function normalizeProfileTlds(value) {
+    return normalizeList(value, normalizeTld);
+}
+export function normalizeDkimSelectors(value) {
+    return normalizeList(value, normalizeSelector).slice(0, MAX_DKIM_SELECTORS);
+}
+function normalizeMailProtectionProfile(value) {
+    return typeof value === 'string' && MAIL_PROFILES.has(value)
+        ? value
+        : 'standard';
+}
+export function normalizeProtectionAttestations(value) {
+    if (!Array.isArray(value))
+        return [];
+    const output = [];
+    const seen = new Set();
+    for (const item of value.slice(0, MAX_PROTECTION_ATTESTATIONS * 4)) {
+        const candidate = record(item);
+        if (typeof candidate.control !== 'string'
+            || !PROTECTION_ATTESTATION_CONTROL_SET.has(candidate.control)
+            || seen.has(candidate.control)
+            || typeof candidate.state !== 'string'
+            || !PROTECTION_ATTESTATION_STATES.has(candidate.state)) {
+            continue;
+        }
+        const assertedAt = timestamp(candidate.assertedAt, null);
+        if (!assertedAt)
+            continue;
+        seen.add(candidate.control);
+        output.push({
+            control: candidate.control,
+            state: candidate.state,
+            assertedAt,
+            expiresAt: timestamp(candidate.expiresAt, null),
+            note: boundedText(candidate.note),
+        });
+        if (output.length >= MAX_PROTECTION_ATTESTATIONS)
+            break;
+    }
+    return output;
+}
+function normalizeDesiredPostureRecords(value, normalizer) {
+    if (!Array.isArray(value))
+        return [];
+    const output = new Set();
+    for (const item of value.slice(0, MAX_DESIRED_POSTURE_RECORDS * 4)) {
+        const candidate = normalizer
+            ? normalizer(item)
+            : boundedText(item, 500);
+        if (candidate)
+            output.add(candidate);
+        if (output.size >= MAX_DESIRED_POSTURE_RECORDS)
+            break;
+    }
+    return [...output].sort();
+}
+function normalizeDesiredPostureObservation(value) {
+    const candidate = record(value);
+    const observedAt = timestamp(candidate.observedAt, null);
+    if (!observedAt || !Array.isArray(candidate.checks))
+        return null;
+    const checks = [];
+    const seen = new Set();
+    for (const item of candidate.checks.slice(0, 64)) {
+        const check = record(item);
+        const id = boundedText(check.id, 64);
+        if (!id
+            || seen.has(id)
+            || typeof check.status !== 'string'
+            || !POSTURE_CHECK_STATUSES.has(check.status))
+            continue;
+        seen.add(id);
+        checks.push({
+            id,
+            status: check.status,
+            records: normalizeDesiredPostureRecords(check.records),
+        });
+        if (checks.length >= 32)
+            break;
+    }
+    return checks.length ? { observedAt, checks } : null;
+}
+function normalizeTlsSanPatterns(value) {
+    if (!Array.isArray(value))
+        return [];
+    const output = new Set();
+    for (const item of value.slice(0, MAX_DESIRED_POSTURE_RECORDS * 4)) {
+        const candidate = boundedText(item, MAX_PROFILE_DOMAIN_LENGTH).toLowerCase().replace(/\.$/u, '');
+        const wildcard = candidate.startsWith('*.');
+        const normalized = normalizeDomain(wildcard ? candidate.slice(2) : candidate);
+        if (!normalized)
+            continue;
+        output.add(wildcard ? `*.${normalized}` : normalized);
+        if (output.size >= MAX_DESIRED_POSTURE_RECORDS)
+            break;
+    }
+    return [...output].sort();
+}
+export function normalizeDesiredPostureBaselines(value, officialDomains, fallbackNow = new Date().toISOString()) {
+    if (!Array.isArray(value))
+        return [];
+    const allowedDomains = new Set(officialDomains);
+    const output = [];
+    const seen = new Set();
+    const fallback = timestamp(fallbackNow, new Date(0).toISOString());
+    for (const item of value.slice(0, MAX_DESIRED_POSTURE_BASELINES * 4)) {
+        const candidate = record(item);
+        const domain = normalizeDomain(candidate.domain);
+        if (!domain || !allowedDomains.has(domain) || seen.has(domain))
+            continue;
+        const suppressions = [];
+        const suppressionFields = new Set();
+        for (const rawSuppression of (Array.isArray(candidate.suppressions) ? candidate.suppressions : [])
+            .slice(0, MAX_DESIRED_POSTURE_SUPPRESSIONS * 4)) {
+            const suppression = record(rawSuppression);
+            const field = boundedText(suppression.field, 40);
+            const reason = boundedText(suppression.reason, MAX_PROFILE_TEXT_LENGTH);
+            if (!DESIRED_POSTURE_FIELDS.has(field) || !reason || suppressionFields.has(field))
+                continue;
+            suppressionFields.add(field);
+            suppressions.push({
+                field,
+                reason,
+                expiresAt: timestamp(suppression.expiresAt, null),
+            });
+            if (suppressions.length >= MAX_DESIRED_POSTURE_SUPPRESSIONS)
+                break;
+        }
+        seen.add(domain);
+        output.push({
+            version: 1,
+            domain,
+            nameservers: normalizeDesiredPostureRecords(candidate.nameservers, (entry) => normalizeDomain(entry)),
+            ds: normalizeDesiredPostureRecords(candidate.ds),
+            mx: normalizeDesiredPostureRecords(candidate.mx),
+            caa: normalizeDesiredPostureRecords(candidate.caa),
+            tlsIssuer: boundedText(candidate.tlsIssuer, MAX_PROFILE_TEXT_LENGTH),
+            tlsSanPatterns: normalizeTlsSanPatterns(candidate.tlsSanPatterns),
+            tlsSpkiSha256: typeof candidate.tlsSpkiSha256 === 'string' && SHA256_RE.test(candidate.tlsSpkiSha256)
+                ? candidate.tlsSpkiSha256.toLowerCase()
+                : '',
+            registrarLock: ['required', 'not_required'].includes(String(candidate.registrarLock))
+                ? candidate.registrarLock
+                : 'unconfigured',
+            renewalReviewAt: timestamp(candidate.renewalReviewAt, null),
+            suppressions,
+            note: boundedText(candidate.note, MAX_PROFILE_TEXT_LENGTH),
+            previousObservation: normalizeDesiredPostureObservation(candidate.previousObservation),
+            updatedAt: timestamp(candidate.updatedAt, fallback),
+        });
+        if (output.length >= MAX_DESIRED_POSTURE_BASELINES)
+            break;
+    }
+    return output;
+}
+function normalizeFaviconHash(value) {
+    return typeof value === 'string' && SHA256_RE.test(value) ? value.toLowerCase() : '';
+}
+function normalizeFaviconPHash(value) {
+    return typeof value === 'string' && isInformativeFaviconHash(value) ? value.toLowerCase() : '';
+}
+/** Normalize one profile while retaining only known, bounded fields. */
+export function normalizeBrandProfile(raw, options = {}) {
+    const value = record(raw);
+    const existing = options.existing ? record(options.existing) : null;
+    const now = timestamp(options.nowIso, new Date().toISOString());
+    const officialDomains = normalizeProfileDomains(value.officialDomains);
+    const dkimSelectors = normalizeDkimSelectors(value.dkimSelectors);
+    const candidateBaseline = Object.prototype.hasOwnProperty.call(value, 'pageBaseline')
+        ? normalizePageBaseline(value.pageBaseline)
+        : normalizePageBaseline(existing?.pageBaseline);
+    const pageBaseline = candidateBaseline && officialDomains.includes(candidateBaseline.domain)
+        ? candidateBaseline
+        : null;
+    const profileId = safeId(existing?.id) || safeId(value.id) || (typeof options.makeId === 'function' ? safeId(options.makeId()) : null);
+    const name = boundedText(value.name, MAX_PROFILE_NAME_LENGTH);
+    if (!profileId || !name)
+        return null;
+    const createdAt = timestamp(existing?.createdAt, null) || timestamp(value.createdAt, now);
+    return {
+        id: profileId,
+        name,
+        officialDomains,
+        productNames: normalizeProfileTextValues(value.productNames),
+        tlds: normalizeProfileTlds(value.tlds),
+        approvedPartnerDomains: normalizeProfileDomains(value.approvedPartnerDomains),
+        allowlistedDomains: normalizeProfileDomains(value.allowlistedDomains),
+        allowlistedRegistrars: normalizeProfileTextValues(value.allowlistedRegistrars),
+        dkimSelectors,
+        retiredDkimSelectors: normalizeDkimSelectors(value.retiredDkimSelectors)
+            .filter((selector) => !dkimSelectors.includes(selector)),
+        mailProtectionProfile: normalizeMailProtectionProfile(value.mailProtectionProfile),
+        protectionAttestations: normalizeProtectionAttestations(value.protectionAttestations),
+        desiredPostureBaselines: normalizeDesiredPostureBaselines(value.desiredPostureBaselines, officialDomains, now),
+        trademarkOwner: boundedText(value.trademarkOwner),
+        trademarkRegistration: boundedText(value.trademarkRegistration),
+        officialFaviconHash: normalizeFaviconHash(value.officialFaviconHash),
+        officialFaviconPHash: normalizeFaviconPHash(value.officialFaviconPHash),
+        pageBaseline,
+        createdAt,
+        updatedAt: options.touch === true ? now : timestamp(value.updatedAt, createdAt),
+    };
+}
+function profileList(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    const value = record(raw);
+    return Array.isArray(value.profiles) ? value.profiles : [];
+}
+export function brandProfileStoreVersion(raw) {
+    if (Array.isArray(raw))
+        return 1;
+    const value = record(raw);
+    return typeof value.version === 'number' && Number.isFinite(value.version) && value.version > 0 ? value.version : null;
+}
+/** Normalize an internal profile collection or current stored envelope. */
+export function normalizeBrandProfileStore(raw) {
+    const byId = new Map();
+    for (const item of profileList(raw).slice(0, MAX_PROFILES * 4)) {
+        const profile = normalizeBrandProfile(item);
+        if (!profile)
+            continue;
+        const previous = byId.get(profile.id);
+        if (!previous || profile.updatedAt > previous.updatedAt)
+            byId.set(profile.id, profile);
+        if (byId.size >= MAX_PROFILES)
+            break;
+    }
+    return { version: BRAND_PROFILE_SCHEMA_VERSION, profiles: [...byId.values()] };
+}
+export function serializeBrandProfileStore(profiles) {
+    return JSON.stringify(assertBrandProfileStoreBudget(profiles));
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}
+export function assertBrandProfileStoreBudget(profiles) {
+    const store = normalizeBrandProfileStore(profiles);
+    if (byteLength(JSON.stringify(store)) > MAX_PROFILE_STORE_BYTES) {
+        throw new Error('Brand profile storage is full. Export and remove a profile before saving more.');
+    }
+    return store;
+}
+export function mergeBrandProfiles(localRaw, importedRaw, options = {}) {
+    const imported = record(importedRaw);
+    if (imported.schema !== BRAND_PROFILE_SCHEMA) {
+        throw new Error('This JSON file is not a WHOISleuth Brand Profile export.');
+    }
+    if (!Array.isArray(imported.profiles)) {
+        throw new Error('Expected a current WHOISleuth Brand Profile export.');
+    }
+    const importedVersion = brandProfileStoreVersion(importedRaw);
+    if (importedVersion !== null && importedVersion > BRAND_PROFILE_SCHEMA_VERSION) {
+        throw new Error(`This Brand Profile file uses newer schema ${importedVersion}. Update the app before importing it.`);
+    }
+    if (![2, 3, 4, BRAND_PROFILE_SCHEMA_VERSION].includes(importedVersion ?? 0)) {
+        throw new Error(`Expected a WHOISleuth Brand Profile export using schema 2, 3, 4, or ${BRAND_PROFILE_SCHEMA_VERSION}.`);
+    }
+    const local = normalizeBrandProfileStore(localRaw).profiles;
+    const byName = new Map(local.map((profile) => [profile.name.toLowerCase(), profile]));
+    const input = profileList(importedRaw);
+    let added = 0;
+    let updated = 0;
+    let skipped = Math.max(0, input.length - MAX_PROFILES * 4);
+    for (const item of input.slice(0, MAX_PROFILES * 4)) {
+        const rawName = boundedText(record(item).name, MAX_PROFILE_NAME_LENGTH);
+        const existing = rawName ? byName.get(rawName.toLowerCase()) : null;
+        const profile = normalizeBrandProfile(item, {
+            existing,
+            touch: true,
+            nowIso: options.nowIso,
+            makeId: options.makeId,
+        });
+        if (!profile) {
+            skipped++;
+            continue;
+        }
+        if (existing) {
+            byName.set(profile.name.toLowerCase(), profile);
+            updated++;
+        }
+        else if (byName.size < MAX_PROFILES) {
+            byName.set(profile.name.toLowerCase(), profile);
+            added++;
+        }
+        else
+            skipped++;
+    }
+    return { profiles: [...byName.values()], added, updated, skipped };
+}
+export function buildBrandProfileExport(profiles, nowIso = new Date().toISOString()) {
+    return {
+        schema: BRAND_PROFILE_SCHEMA,
+        version: BRAND_PROFILE_SCHEMA_VERSION,
+        exportedAt: timestamp(nowIso, new Date().toISOString()),
+        profiles: normalizeBrandProfileStore(profiles).profiles,
+    };
+}

package/frontend/src/lib/analysis/bulk-domain-comparison.js

@@ -0,0 +1,246 @@
+import { normalizeBulkSessionResult, } from "./bulk-session-model.js";
+import { sha256ArtifactDigest } from "./artifact-integrity.js";
+import { BULK_REVIEW_STALE_AFTER_DAYS } from "./bulk-retry-plan.js";
+export const BULK_DOMAIN_COMPARISON_SCHEMA = 'whoisleuth.domain-comparison';
+export const BULK_DOMAIN_COMPARISON_VERSION = 3;
+function text(value, maximum = 500) {
+    return typeof value === 'string'
+        ? value.replace(/[\u0000-\u001f\u007f]/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, maximum)
+        : '';
+}
+function timestamp(value) {
+    const normalized = text(value, 64);
+    return normalized && Number.isFinite(Date.parse(normalized))
+        ? new Date(normalized).toISOString()
+        : null;
+}
+function list(value) {
+    return [...new Set(value.map((item) => text(item, 253).toLowerCase()).filter(Boolean))]
+        .sort()
+        .slice(0, 100);
+}
+function normalized(value) {
+    if (typeof value === 'string') {
+        const normalizedText = text(value).toLowerCase();
+        return normalizedText && normalizedText !== '—' ? normalizedText : null;
+    }
+    if (typeof value === 'boolean' || typeof value === 'number' || value === null)
+        return value;
+    return list(value);
+}
+function display(value) {
+    if (value === null)
+        return 'Not observed';
+    if (typeof value === 'string') {
+        const displayText = text(value);
+        return displayText && displayText !== '—' ? displayText : 'Not observed';
+    }
+    if (typeof value === 'boolean')
+        return value ? 'Observed' : 'Not observed';
+    if (typeof value === 'number')
+        return String(value);
+    const values = [...new Set(value.map((item) => text(item, 253)).filter(Boolean))]
+        .sort((left, right) => left.localeCompare(right))
+        .slice(0, 100);
+    return values.join(', ') || 'Not observed';
+}
+function sourceState(value, sources) {
+    if (sources.length === 0) {
+        return value.sourceCoverage.length > 0 ? 'complete' : 'not_recorded';
+    }
+    for (const source of sources) {
+        const observed = value.sourceCoverage.find((item) => item.source === source);
+        if (observed)
+            return observed.state;
+    }
+    return 'not_recorded';
+}
+function unavailableSource(state) {
+    return ['error', 'partial', 'skipped', 'unavailable', 'unsupported'].includes(state);
+}
+function state(left, right, leftSourceState, rightSourceState, options = {}) {
+    if (options.retained === false)
+        return 'not_recorded';
+    if (options.conflicting)
+        return 'conflicting';
+    const leftValue = normalized(left);
+    const rightValue = normalized(right);
+    const leftMissing = leftValue === null || (Array.isArray(leftValue) && leftValue.length === 0);
+    const rightMissing = rightValue === null || (Array.isArray(rightValue) && rightValue.length === 0);
+    if (leftMissing || rightMissing) {
+        if ((leftMissing && leftSourceState === 'not_recorded')
+            || (rightMissing && rightSourceState === 'not_recorded'))
+            return 'not_recorded';
+        if ((leftMissing && unavailableSource(leftSourceState))
+            || (rightMissing && unavailableSource(rightSourceState)))
+            return 'unavailable';
+        if (leftMissing && rightMissing)
+            return 'unavailable';
+        return 'missing';
+    }
+    return JSON.stringify(leftValue) === JSON.stringify(rightValue) ? 'equal' : 'different';
+}
+function evidenceHref(value) {
+    return typeof value === 'string' && /^#bulk-result-\d{1,4}$/u.test(value) ? value : '';
+}
+function row(id, category, label, left, right, method, context, limitations = [], options = {}) {
+    return {
+        id,
+        category,
+        label,
+        left: options.retained === false ? 'Not recorded in compact Bulk evidence' : display(left),
+        right: options.retained === false ? 'Not recorded in compact Bulk evidence' : display(right),
+        state: state(left, right, context.leftSourceState, context.rightSourceState, options),
+        method: text(method, 320),
+        source: text(context.source, 80),
+        leftSourceState: context.leftSourceState,
+        rightSourceState: context.rightSourceState,
+        observedAt: context.observedAt,
+        leftEvidenceHref: context.leftEvidenceHref,
+        rightEvidenceHref: context.rightEvidenceHref,
+        limitations: limitations.map((item) => text(item, 320)).filter(Boolean).slice(0, 6),
+    };
+}
+function sourceSummary(value) {
+    return value.sourceCoverage
+        .map((item) => `${item.source}:${item.state}`)
+        .sort()
+        .slice(0, 20);
+}
+function dnsValues(value, type) {
+    if (!value.dns)
+        return [];
+    const records = value.dns.records[type];
+    return type === 'caa'
+        ? records
+            .map((item) => `${item.critical} ${item.tag} ${item.value}`)
+        : records;
+}
+function context(left, right, source, sources, observedAt, options) {
+    return {
+        source,
+        leftSourceState: sourceState(left, sources),
+        rightSourceState: sourceState(right, sources),
+        observedAt,
+        leftEvidenceHref: evidenceHref(options.leftEvidenceHref),
+        rightEvidenceHref: evidenceHref(options.rightEvidenceHref),
+    };
+}
+function comparisonEvidenceContext(left, right, family, base) {
+    const stateFor = (value) => {
+        const state = value.comparisonEvidence?.[family].state;
+        if (!state)
+            return 'not_recorded';
+        return state === 'success' ? 'complete' : state;
+    };
+    return {
+        ...base,
+        leftSourceState: stateFor(left),
+        rightSourceState: stateFor(right),
+    };
+}
+function freshness(observedAt, now) {
+    if (!observedAt)
+        return { state: 'unknown', ageDays: null };
+    const ageDays = Math.max(0, Math.floor((now - Date.parse(observedAt)) / 86_400_000));
+    return {
+        state: ageDays >= BULK_REVIEW_STALE_AFTER_DAYS ? 'stale' : 'current',
+        ageDays,
+    };
+}
+export function buildBulkDomainComparison(leftRaw, rightRaw, observedAtRaw = null, options = {}) {
+    const left = normalizeBulkSessionResult(leftRaw);
+    const right = normalizeBulkSessionResult(rightRaw);
+    if (!left || !right || left.domain === right.domain)
+        return null;
+    const observedAt = timestamp(observedAtRaw);
+    const registry = context(left, right, 'Registry and registrar evidence', ['rdap', 'availability'], observedAt, options);
+    const dns = context(left, right, 'DNS evidence', ['dns'], observedAt, options);
+    const http = context(left, right, 'HTTP and static page evidence', ['http'], observedAt, options);
+    const tls = context(left, right, 'TLS evidence', ['tls'], observedAt, options);
+    const compactTechnology = comparisonEvidenceContext(left, right, 'technology', {
+        ...http,
+        source: 'Bounded technology identifiers',
+    });
+    const compactTls = comparisonEvidenceContext(left, right, 'tls', tls);
+    const source = context(left, right, 'Recorded source coverage', [], observedAt, options);
+    const registrationConflicting = [left.availability, right.availability]
+        .some((value) => ['conflict', 'conflicting'].includes(value.toLowerCase()));
+    const rows = [
+        row('registration', 'registration', 'Registration', left.availability, right.availability, 'Authority-aware compact availability state', registry, [], { conflicting: registrationConflicting }),
+        row('registrar', 'registration', 'Registrar', left.registrar, right.registrar, 'Normalized registrar display identity', registry),
+        row('created', 'lifecycle', 'Created', left.createdDate, right.createdDate, 'Source-reported lifecycle date', registry),
+        row('expires', 'lifecycle', 'Expires', left.expiryDate, right.expiryDate, 'Source-reported lifecycle date', registry),
+        row('nameservers', 'infrastructure', 'Nameservers', left.nameservers, right.nameservers, 'Normalized exact set comparison', registry),
+        row('dns-a', 'dns', 'A records', dnsValues(left, 'a'), dnsValues(right, 'a'), 'Normalized exact retained DNS answer set', dns),
+        row('dns-aaaa', 'dns', 'AAAA records', dnsValues(left, 'aaaa'), dnsValues(right, 'aaaa'), 'Normalized exact retained DNS answer set', dns),
+        row('dns-cname', 'dns', 'CNAME records', dnsValues(left, 'cname'), dnsValues(right, 'cname'), 'Normalized exact retained DNS answer set', dns),
+        row('dns-caa', 'dns', 'CAA records', dnsValues(left, 'caa'), dnsValues(right, 'caa'), 'Normalized exact retained DNS answer set', dns),
+        row('dnssec', 'dns', 'DNSSEC state', left.dnssec, right.dnssec, 'Separately attributed compact DNSSEC observation', dns),
+        row('ip-addresses', 'infrastructure', 'Observed IP addresses', left.relationship.ipAddresses, right.relationship.ipAddresses, 'Normalized exact set comparison', dns, ['Shared hosting and CDNs are common and do not prove common control.']),
+        row('tls-source', 'certificate', 'TLS collection', tls.leftSourceState, tls.rightSourceState, 'Retained compact source-state comparison', tls),
+        row('certificate', 'certificate', 'Leaf certificate fingerprint', left.relationship.certificateFingerprint, right.relationship.certificateFingerprint, 'Exact SHA-256 comparison', tls, ['Multi-domain certificates and managed hosting are common.']),
+        row('tls-issuer', 'certificate', 'TLS issuer label', left.comparisonEvidence?.tls.issuerLabel ?? null, right.comparisonEvidence?.tls.issuerLabel ?? null, 'Normalized retained issuer-label comparison', compactTls, ['Issuer labels are certificate metadata and do not establish common ownership or control.']),
+        row('tls-spki', 'certificate', 'TLS public-key fingerprint', left.comparisonEvidence?.tls.spkiSha256 ?? null, right.comparisonEvidence?.tls.spkiSha256 ?? null, 'Exact SPKI SHA-256 comparison', compactTls, ['Public-key reuse can be an investigative lead but does not establish ownership, intent, safety, or maliciousness.']),
+        row('mail', 'mail', 'MX observed', left.hasMx, right.hasMx, 'Compact Deep DNS observation', dns),
+        row('null-mx', 'mail', 'Null MX observed', left.hasNullMx, right.hasNullMx, 'Compact Deep DNS observation', dns),
+        row('spf', 'mail', 'SPF observed', left.hasSpf, right.hasSpf, 'Compact Deep DNS observation', dns),
+        row('dmarc', 'mail', 'DMARC observed', left.hasDmarc, right.hasDmarc, 'Compact Deep DNS observation', dns),
+        row('website', 'web', 'Website activity', left.activityStatus, right.activityStatus, 'Bounded homepage observation', http),
+        row('page-title', 'identity', 'Page title', left.pageTitle, right.pageTitle, 'Normalized bounded title equality', http),
+        row('favicon', 'identity', 'Favicon fingerprint', left.faviconHash, right.faviconHash, 'Exact SHA-256 comparison', http),
+        row('tracking', 'identity', 'Tracking identifiers', left.relationship.trackingIdentifiers, right.relationship.trackingIdentifiers, 'Normalized exact set comparison', http, ['Shared identifiers are an investigative lead, not proof of ownership.']),
+        row('password-field', 'identity', 'Password field', left.hasPasswordField, right.hasPasswordField, 'Bounded static form observation', http),
+        row('phishing-language', 'identity', 'Phishing-language indicator', left.phishingLanguageMatch, right.phishingLanguageMatch, 'Bounded explainable page-language signal', http, ['A wording match is a review lead, not proof of malicious intent.']),
+        row('official-assets', 'identity', 'Official asset reuse', left.reusesOfficialAssets, right.reusesOfficialAssets, 'Configured Brand Profile comparison', http),
+        row('technology', 'technology', 'Technology identifiers', left.comparisonEvidence?.technology.ids ?? [], right.comparisonEvidence?.technology.ids ?? [], 'Normalized exact set comparison of at most 12 curated identifiers', compactTechnology, ['An unmatched identifier is not evidence that a technology is absent. Shared technologies do not establish common ownership or control.']),
+        row('source-health', 'source', 'Recorded source coverage', sourceSummary(left), sourceSummary(right), 'Source-by-source compact state comparison', source, ['A source-state difference can reflect collection conditions rather than a domain change.']),
+    ];
+    const counts = {
+        conflicting: 0,
+        different: 0,
+        equal: 0,
+        missing: 0,
+        not_recorded: 0,
+        unavailable: 0,
+    };
+    for (const comparisonRow of rows)
+        counts[comparisonRow.state] += 1;
+    return {
+        version: BULK_DOMAIN_COMPARISON_VERSION,
+        leftDomain: left.domain,
+        rightDomain: right.domain,
+        observedAt,
+        freshness: freshness(observedAt, options.now ?? Date.now()),
+        rows,
+        counts,
+        limitations: [
+            'This compares compact settled evidence already present in Bulk and makes no new request.',
+            'Missing, unavailable, and differently collected evidence remain distinct from an observed difference.',
+            'Equality does not establish common ownership, infrastructure control, intent, safety, or maliciousness.',
+        ],
+    };
+}
+export async function buildBulkDomainComparisonExport(comparisonRaw, generatedAtRaw = new Date().toISOString()) {
+    const comparison = comparisonRaw;
+    if (!comparison || comparison.version !== BULK_DOMAIN_COMPARISON_VERSION) {
+        throw new Error('Choose two settled domain results before exporting a comparison.');
+    }
+    const generatedAt = timestamp(generatedAtRaw) || new Date().toISOString();
+    const unsigned = {
+        schema: BULK_DOMAIN_COMPARISON_SCHEMA,
+        version: BULK_DOMAIN_COMPARISON_VERSION,
+        generatedAt,
+        comparison,
+    };
+    const digestSha256 = await sha256ArtifactDigest(unsigned);
+    const document = {
+        ...unsigned,
+        integrity: { algorithm: 'SHA-256', digestSha256 },
+    };
+    return {
+        document,
+        content: `${JSON.stringify(document, null, 2)}\n`,
+        filename: `whoisleuth-domain-comparison-${comparison.leftDomain}-and-${comparison.rightDomain}.json`,
+    };
+}