@slicedearth/whoisleuth-cli 1.32.0

package/lib/evidence-report.mjs

@@ -0,0 +1,391 @@
+import { registryAccessProfileLabel } from "./registry-access.mjs";
+const MAX_REPORT_VALUE_LENGTH = 300;
+const MAX_REPORT_LIST_ITEMS = 50;
+const MAX_REPORT_COMPARISON_FIELDS = 20;
+const MAX_REPORT_RISK_FACTORS = 20;
+function objectOrEmpty(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function cleanReportText(value, fallback = 'Not reported') {
+    if (value === null || value === undefined || value === '')
+        return fallback;
+    const text = String(value)
+        .replace(/[\x00-\x1f\x7f]+/g, ' ')
+        .replace(/[\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, MAX_REPORT_VALUE_LENGTH);
+    return text || fallback;
+}
+function displayLabel(value) {
+    return cleanReportText(value, 'Unknown')
+        .replace(/[_-]+/g, ' ')
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function yesNoUnknown(value) {
+    if (value === true)
+        return 'Yes';
+    if (value === false)
+        return 'No';
+    return 'Unknown';
+}
+function riskReport(value) {
+    const source = objectOrEmpty(value);
+    const score = Number.isInteger(source.score) && Number(source.score) >= 0 && Number(source.score) <= 100
+        ? Number(source.score)
+        : null;
+    const modelVersion = Number.isInteger(source.modelVersion)
+        && Number(source.modelVersion) > 0
+        && Number(source.modelVersion) <= 10_000
+        ? Number(source.modelVersion)
+        : null;
+    const factors = (Array.isArray(source.factors) ? source.factors : [])
+        .slice(0, MAX_REPORT_RISK_FACTORS)
+        .map((value) => {
+        const factor = objectOrEmpty(value);
+        const label = cleanReportText(factor.label, '');
+        const deltaValue = factor.delta ?? factor.points;
+        const delta = Number.isInteger(deltaValue) && Math.abs(Number(deltaValue)) <= 100
+            ? Number(deltaValue)
+            : null;
+        if (!label || delta === null)
+            return null;
+        return `${label} (${delta > 0 ? '+' : ''}${delta})`;
+    })
+        .filter((value) => value !== null);
+    return { score, modelVersion, factors };
+}
+function listText(value) {
+    if (!Array.isArray(value) || !value.length)
+        return 'Not reported';
+    const candidates = value
+        .slice(0, MAX_REPORT_LIST_ITEMS)
+        .map((item) => cleanReportText(item).slice(0, 120));
+    const retained = [];
+    for (const candidate of candidates) {
+        const next = [...retained, candidate].join(', ');
+        // Reserve enough room for the omission suffix so it is never hidden by
+        // the per-value display boundary.
+        if (next.length > MAX_REPORT_VALUE_LENGTH - 40)
+            break;
+        retained.push(candidate);
+    }
+    const omitted = value.length - retained.length;
+    return `${retained.join(', ')}${omitted > 0 ? ` (and ${omitted} more)` : ''}`;
+}
+function entityName(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const entity = value;
+    return entity.name || entity.org || entity.handle || null;
+}
+function lifecycleValue(parsed, field) {
+    const source = objectOrEmpty(parsed);
+    const lifecycle = objectOrEmpty(source.lifecycle);
+    return lifecycle[`${field}Iso`] || lifecycle[field] || source[`${field}Iso`] || source[field] || null;
+}
+function reportField(label, value, fallback = 'Not reported') {
+    return { label, value: cleanReportText(value, fallback) };
+}
+function buildLookupEvidenceReport(document, options = {}) {
+    const report = objectOrEmpty(document);
+    const query = objectOrEmpty(report.query);
+    const diagnostics = objectOrEmpty(report.diagnostics);
+    const rdapDiagnostics = objectOrEmpty(diagnostics.rdap);
+    const whoisDiagnostics = objectOrEmpty(diagnostics.whois);
+    const availabilityDiagnostics = objectOrEmpty(diagnostics.availability);
+    const registrarRdapDiagnostics = objectOrEmpty(rdapDiagnostics.registrar);
+    const registryAccess = objectOrEmpty(diagnostics.registryAccess);
+    const sources = objectOrEmpty(report.sources);
+    const rdap = objectOrEmpty(sources.rdap);
+    const whois = objectOrEmpty(sources.whois);
+    const networkContext = objectOrEmpty(sources.network);
+    const networkEndpoint = objectOrEmpty(networkContext.endpoint);
+    const networkRdap = objectOrEmpty(networkContext.rdap);
+    const networkRegistration = objectOrEmpty(networkContext.network);
+    const rdapParsed = objectOrEmpty(rdap.parsed);
+    const whoisParsed = objectOrEmpty(whois.parsed);
+    const analysis = objectOrEmpty(report.analysis);
+    const availability = objectOrEmpty(analysis.availability);
+    const comparison = objectOrEmpty(analysis.registryComparison);
+    const registryInsights = objectOrEmpty(analysis.registryInsights);
+    const registryLifecycle = objectOrEmpty(registryInsights.lifecycle);
+    const registryLocks = objectOrEmpty(registryLifecycle.locks);
+    const contactDisclosure = objectOrEmpty(registryInsights.contactDisclosure);
+    const registryDisclosure = objectOrEmpty(contactDisclosure.registryRdap);
+    const whoisDisclosure = objectOrEmpty(contactDisclosure.whois);
+    const registryReconciliation = objectOrEmpty(registryInsights.reconciliation);
+    const registryPublications = Array.isArray(registryInsights.publications)
+        ? registryInsights.publications.map(objectOrEmpty)
+        : [];
+    const comparisonHealth = objectOrEmpty(comparison.sourceHealth);
+    const rdapComparisonHealth = objectOrEmpty(comparisonHealth.rdap);
+    const whoisComparisonHealth = objectOrEmpty(comparisonHealth.whois);
+    const registrarComparison = objectOrEmpty(analysis.registrarPublicationComparison);
+    const registrarComparisonHealth = objectOrEmpty(registrarComparison.sourceHealth);
+    const registryPublicationHealth = objectOrEmpty(registrarComparisonHealth.registry);
+    const registrarPublicationHealth = objectOrEmpty(registrarComparisonHealth.registrar);
+    const registrarRdap = objectOrEmpty(options.registrarRdap);
+    const registrarRdapParsed = objectOrEmpty(registrarRdap.parsed);
+    const dns = objectOrEmpty(availability.dns);
+    const dnsRecords = objectOrEmpty(dns.records);
+    const soa = objectOrEmpty(Array.isArray(dnsRecords.soa) ? dnsRecords.soa[0] : null);
+    const http = objectOrEmpty(availability.http);
+    const httpResponse = objectOrEmpty(http.response);
+    const tls = objectOrEmpty(availability.tls);
+    const tlsAuthorization = objectOrEmpty(tls.authorization);
+    const tlsHostname = objectOrEmpty(tls.hostname);
+    const tlsValidity = objectOrEmpty(tls.validity);
+    const tlsCertificate = objectOrEmpty(tls.certificate);
+    const risk = riskReport(options.risk);
+    const titleTarget = query.registrableDomain || query.submitted || 'Unknown domain';
+    const registryAccessSuffix = [5, 6, 7, 8].includes(Number(diagnostics.version)) && registryAccess.authority === 'context_only'
+        && typeof registryAccess.suffix === 'string'
+        ? cleanReportText(registryAccess.suffix, '')
+        : '';
+    const registryAccessFields = registryAccessSuffix ? [
+        reportField('Registry access suffix', `.${registryAccessSuffix}`),
+        reportField('WHOIS access', registryAccessProfileLabel(registryAccess.whoisAccessProfile)),
+        reportField('RDAP access', registryAccessProfileLabel(registryAccess.rdapAccessProfile)),
+        reportField('Registry access note', registryAccess.limitation),
+    ] : [];
+    const groups = {
+        registryRdap: {
+            title: 'Registry RDAP',
+            fields: [
+                reportField('Source status', displayLabel(rdapDiagnostics.status || rdap.status)),
+                reportField('Endpoint', rdap.endpoint),
+                reportField('HTTP status', rdap.httpStatus),
+                reportField('Fetched', rdap.fetchedAt),
+                reportField('Domain', rdapParsed.domain),
+                reportField('Registry object ID', rdapParsed.handle),
+                reportField('Registrar', entityName(rdapParsed.registrar)),
+                reportField('Registrar IANA ID', rdapParsed.registrarIanaId),
+                reportField('Created', lifecycleValue(rdapParsed, 'createdDate')),
+                reportField('Expires', lifecycleValue(rdapParsed, 'expiryDate')),
+                reportField('Last updated', lifecycleValue(rdapParsed, 'updatedDate')),
+                reportField('DNSSEC', rdapParsed.dnssec),
+                reportField('Statuses', listText(rdapParsed.statuses)),
+                reportField('Name servers', listText(rdapParsed.nameservers)),
+                reportField('Server-declared truncation', yesNoUnknown(rdapParsed.serverTruncated)),
+            ],
+        },
+        registrarRdap: {
+            title: 'Registrar RDAP',
+            fields: [
+                reportField('Source status', displayLabel(registrarRdapDiagnostics.status || registrarRdap.status)),
+                reportField('Endpoint', registrarRdap.endpoint),
+                reportField('Transport', displayLabel(registrarRdap.transportSecurity)),
+                reportField('HTTP status', registrarRdap.upstreamStatus),
+                reportField('Fetched', registrarRdap.fetchedAt),
+                reportField('Domain', registrarRdapParsed.domain),
+                reportField('Registrar', entityName(registrarRdapParsed.registrar)),
+                reportField('Registrar IANA ID', registrarRdapParsed.registrarIanaId),
+                reportField('Created', lifecycleValue(registrarRdapParsed, 'createdDate')),
+                reportField('Expires', lifecycleValue(registrarRdapParsed, 'expiryDate')),
+                reportField('Last updated', lifecycleValue(registrarRdapParsed, 'updatedDate')),
+                reportField('DNSSEC', registrarRdapParsed.dnssec),
+                reportField('Statuses', listText(registrarRdapParsed.statuses)),
+                reportField('Name servers', listText(registrarRdapParsed.nameservers)),
+                reportField('Server-declared truncation', yesNoUnknown(registrarRdapParsed.serverTruncated)),
+            ],
+        },
+        whois: {
+            title: 'WHOIS',
+            fields: [
+                reportField('Source status', displayLabel(whoisDiagnostics.status || whois.status)),
+                reportField('Queried', whois.queriedAt),
+                reportField('Authoritative hop', whois.authoritativeHop),
+                reportField('Failed hop', whois.failedHop),
+                reportField('Domain', whoisParsed.domainName),
+                reportField('Registry object ID', whoisParsed.registryDomainId),
+                reportField('Registrar', entityName(whoisParsed.registrar)),
+                reportField('Registrar IANA ID', whoisParsed.registrarIanaId),
+                reportField('Created', lifecycleValue(whoisParsed, 'createdDate')),
+                reportField('Expires', lifecycleValue(whoisParsed, 'expiryDate')),
+                reportField('Last updated', lifecycleValue(whoisParsed, 'updatedDate')),
+                reportField('DNSSEC', whoisParsed.dnssec),
+                reportField('Statuses', listText(whoisParsed.statuses)),
+                reportField('Name servers', listText(whoisParsed.nameservers)),
+            ],
+        },
+        dns: {
+            title: 'DNS and mail',
+            fields: [
+                reportField('DNS status', displayLabel(dns.status)),
+                reportField('Observed', dns.observedAt),
+                reportField('Name servers', listText(availability.nameservers)),
+                reportField('MX hosts', listText(availability.mxHosts)),
+                reportField('SOA primary server', soa.nsname),
+                reportField('SOA hostmaster', soa.hostmaster),
+                reportField('SOA serial', soa.serial),
+                reportField('SOA refresh', soa.refresh),
+                reportField('SOA retry', soa.retry),
+                reportField('SOA expire', soa.expire),
+                reportField('SOA minimum TTL', soa.minttl),
+            ],
+        },
+        website: {
+            title: 'Website',
+            fields: [
+                reportField('Probe status', displayLabel(http.status || availability.websiteProbeStatus)),
+                reportField('Observed', http.observedAt),
+                reportField('Final URL', http.finalUrl),
+                reportField('HTTP response', httpResponse.status),
+                reportField('Content type', httpResponse.contentType),
+                reportField('Redirects', http.redirectCount),
+                reportField('Page title', availability.pageTitle),
+                reportField('Password field observed', yesNoUnknown(availability.hasPasswordField)),
+            ],
+        },
+        tls: {
+            title: 'TLS',
+            fields: [
+                reportField('TLS status', displayLabel(tls.status)),
+                reportField('Observed', tls.observedAt),
+                reportField('Protocol', tls.protocol),
+                reportField('Runtime trust', yesNoUnknown(tlsAuthorization.authorized)),
+                reportField('Hostname match', yesNoUnknown(tlsHostname.matches)),
+                reportField('Certificate validity', displayLabel(tlsValidity.status)),
+                reportField('Certificate fingerprint', tlsCertificate.fingerprintSha256),
+            ],
+        },
+        networkRegistration: {
+            title: 'Observed network registration',
+            fields: [
+                reportField('Source status', displayLabel(networkContext.status)),
+                reportField('Selected address', networkEndpoint.address),
+                reportField('Selected from', displayLabel(networkEndpoint.selectedFrom)),
+                reportField('IP RDAP endpoint', networkRdap.endpoint),
+                reportField('IP RDAP fetched', networkRdap.fetchedAt),
+                reportField('Registered network', networkRegistration.name),
+                reportField('Network holder', networkRegistration.holder),
+                reportField('Network handle', networkRegistration.handle),
+                reportField('CIDR ranges', listText(networkRegistration.cidrs)),
+                reportField('Address range', networkRegistration.startAddress && networkRegistration.endAddress
+                    ? `${networkRegistration.startAddress} to ${networkRegistration.endAddress}` : null),
+                reportField('Country', networkRegistration.country),
+                reportField('Network type', networkRegistration.networkType),
+                reportField('RDAP database updated', networkRegistration.databaseUpdatedAt),
+                reportField('Complete response', yesNoUnknown(networkContext.complete)),
+                reportField('Truncated response', yesNoUnknown(networkContext.truncated)),
+                reportField('Limitations', listText(networkContext.limitations)),
+            ],
+        },
+    };
+    const comparisonFields = Array.isArray(comparison.fields)
+        ? comparison.fields.slice(0, MAX_REPORT_COMPARISON_FIELDS).map((value) => {
+            const item = objectOrEmpty(value);
+            return {
+                label: cleanReportText(item.label),
+                status: displayLabel(item.status),
+                rdap: cleanReportText(item.rdapDisplay),
+                whois: cleanReportText(item.whoisDisplay),
+            };
+        })
+        : [];
+    const registrarComparisonFields = Array.isArray(registrarComparison.fields)
+        ? registrarComparison.fields.slice(0, MAX_REPORT_COMPARISON_FIELDS).map((value) => {
+            const item = objectOrEmpty(value);
+            return {
+                label: cleanReportText(item.label),
+                status: displayLabel(item.status),
+                registry: cleanReportText(item.registryDisplay),
+                registrar: cleanReportText(item.registrarDisplay),
+            };
+        })
+        : [];
+    return {
+        title: cleanReportText(titleTarget),
+        notice: 'Human-readable summary. The versioned JSON export remains the full-fidelity evidence package; raw RDAP JSON and WHOIS response bodies are deliberately omitted here.',
+        metadata: [
+            reportField('Generated', report.generatedAt),
+            reportField('Report contract', `${cleanReportText(report.schema)} v${cleanReportText(report.schemaVersion)}`),
+        ],
+        query: [
+            reportField('Submitted', query.submitted),
+            reportField('Type', displayLabel(query.type)),
+            reportField('Input hostname', query.inputHostname),
+            reportField('Registrable domain', query.registrableDomain),
+            reportField('Subdomain input', yesNoUnknown(query.isSubdomain)),
+        ],
+        assessment: [
+            reportField('Availability', displayLabel(availability.state)),
+            reportField('Confidence', displayLabel(availability.confidence)),
+            reportField('Risk score', risk.score === null ? null : `${risk.score}/100`),
+            reportField('Risk model', risk.modelVersion === null ? null : `v${risk.modelVersion}`),
+            reportField('Risk factors', risk.factors.length ? listText(risk.factors) : risk.score === null ? null : 'None observed'),
+            reportField('Detail', availability.detail),
+            reportField('Website activity', displayLabel(availability.activityStatus)),
+            reportField('Website observation', availability.websiteProbeDetail),
+            reportField('Deep scan complete', yesNoUnknown(availability.deepScanComplete)),
+            reportField('MX observed', yesNoUnknown(availability.hasMx)),
+            reportField('SPF observed', yesNoUnknown(availability.hasSpf)),
+            reportField('DMARC observed', yesNoUnknown(availability.hasDmarc)),
+        ],
+        registryGroups: [
+            groups.registryRdap,
+            ...(Object.keys(registrarRdap).length ? [groups.registrarRdap] : []),
+            groups.whois,
+        ],
+        registryInterpretation: registryInsights.version === 1 ? [
+            reportField('Lifecycle', displayLabel(registryLifecycle.label)),
+            reportField('Raw lifecycle statuses', listText(registryLifecycle.rawStatuses)),
+            reportField('Client registration lock observed', yesNoUnknown(registryLocks.client)),
+            reportField('Server registration lock observed', yesNoUnknown(registryLocks.server)),
+            reportField('Registry RDAP disclosure', displayLabel(registryDisclosure.state)),
+            reportField('WHOIS disclosure', displayLabel(whoisDisclosure.state)),
+            reportField('Reconciliation', displayLabel(registryReconciliation.state)),
+            reportField('Reconciliation summary', registryReconciliation.summary),
+            reportField('Complete publications', registryPublications.filter((item) => item.state === 'complete').length),
+            reportField('Partial publications', registryPublications.filter((item) => item.state === 'partial').length),
+            reportField('Unavailable publications', registryPublications.filter((item) => item.state === 'unavailable').length),
+            reportField('Published escalation routes', Array.isArray(registryInsights.abuseRouting) ? registryInsights.abuseRouting.length : 0),
+            reportField('Interpretation limit', contactDisclosure.limitation),
+        ] : [],
+        comparison: {
+            health: [
+                reportField('RDAP health', displayLabel(rdapComparisonHealth.status)),
+                reportField('WHOIS health', displayLabel(whoisComparisonHealth.status)),
+            ],
+            fields: comparisonFields,
+            omitted: Math.max(0, (Array.isArray(comparison.fields) ? comparison.fields.length : 0) - comparisonFields.length),
+        },
+        registrarComparison: {
+            health: [
+                reportField('Registry RDAP health', displayLabel(registryPublicationHealth.status)),
+                reportField('Registrar RDAP health', displayLabel(registrarPublicationHealth.status)),
+            ],
+            fields: registrarComparisonFields,
+            omitted: Math.max(0, (Array.isArray(registrarComparison.fields) ? registrarComparison.fields.length : 0) - registrarComparisonFields.length),
+        },
+        networkGroups: [
+            groups.dns,
+            groups.website,
+            groups.tls,
+            ...(networkContext.contextVersion === 1 ? [groups.networkRegistration] : []),
+        ],
+        diagnostics: [
+            reportField('Diagnostics version', diagnostics.version),
+            reportField('RDAP', displayLabel(rdapDiagnostics.status)),
+            reportField('Registrar RDAP', displayLabel(registrarRdapDiagnostics.status)),
+            reportField('WHOIS', displayLabel(whoisDiagnostics.status)),
+            reportField('Availability', displayLabel(availabilityDiagnostics.status)),
+            ...(networkContext.contextVersion === 1 ? [reportField('Observed network context', displayLabel(networkContext.status))] : []),
+            ...registryAccessFields,
+        ],
+        limitations: [
+            'This report summarizes point-in-time observations and registry publications. It does not prove ownership, activity, availability, or maliciousness.',
+            'Missing, skipped, partial, unsupported, or failed sources are inconclusive rather than negative evidence.',
+            'The Risk score is a versioned heuristic review priority, not a probability or determination of maliciousness. Review its listed factors and the underlying source states.',
+            'Raw registry payloads and full WHOIS referral responses are available only in the JSON evidence package and may contain public contact data.',
+            ...(networkContext.contextVersion === 1 ? [
+                'Observed network registration describes one point-in-time public endpoint. It may identify an edge or shared network rather than the origin host and does not prove control, ownership, intent, or maliciousness.',
+            ] : []),
+            ...(registryAccessFields.length ? [
+                'Registry access constraints describe collection reachability only. They do not decide registration, availability, ownership, safety, or maliciousness.',
+            ] : []),
+        ],
+    };
+}
+export { MAX_REPORT_COMPARISON_FIELDS, MAX_REPORT_LIST_ITEMS, MAX_REPORT_RISK_FACTORS, MAX_REPORT_VALUE_LENGTH, buildLookupEvidenceReport, cleanReportText, };

package/lib/external-intelligence-risk.mjs

@@ -0,0 +1,108 @@
+// Converts already-returned, separately attributed external observations into
+// a conservative Risk contribution. Unknown providers and lone publisher
+// families never contribute. Two adapters operated by the same publisher are
+// deliberately one corroboration source, even when their datasets differ.
+export const EXTERNAL_INTELLIGENCE_CALIBRATION_VERSION = 1;
+export const EXTERNAL_INTELLIGENCE_RECENT_DAYS = 90;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MAX_CLOCK_SKEW_MS = DAY_MS;
+const MAX_PROVIDERS = 10;
+const MAX_FINDINGS_PER_PROVIDER = 100;
+const POSITIVE_STATES = new Set(['success', 'partial']);
+const QUALIFYING_CATEGORIES = new Set(['phishing', 'malware']);
+// Only built-in provider IDs can affect the built-in score. The two community
+// malware datasets share one publisher family and therefore cannot corroborate
+// one another by themselves.
+const PUBLISHER_FAMILIES = Object.freeze({
+    urlscan_search: 'archived-scan-publisher',
+    urlhaus_host: 'community-malware-publisher',
+    threatfox_domain_ioc: 'community-malware-publisher',
+});
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function timestamp(value) {
+    if (typeof value !== 'string' || value.length > 64 || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function providerEvidence(value) {
+    const provider = record(value);
+    const identity = record(provider?.provider);
+    const observation = record(provider?.observation);
+    const providerId = typeof identity?.id === 'string' ? identity.id : '';
+    const publisherFamily = Object.hasOwn(PUBLISHER_FAMILIES, providerId)
+        ? PUBLISHER_FAMILIES[providerId]
+        : null;
+    if (!publisherFamily
+        || typeof provider?.state !== 'string'
+        || !POSITIVE_STATES.has(provider.state)
+        || !Array.isArray(provider.findings))
+        return null;
+    const observedAt = timestamp(observation?.observedAt);
+    let latestFindingAt = null;
+    let qualifyingFindings = 0;
+    for (const item of provider.findings.slice(0, MAX_FINDINGS_PER_PROVIDER)) {
+        const finding = record(item);
+        if (!finding || typeof finding.category !== 'string' || !QUALIFYING_CATEGORIES.has(finding.category))
+            continue;
+        qualifyingFindings += 1;
+        const candidate = timestamp(finding.lastObservedAt) ?? timestamp(finding.firstObservedAt);
+        if (candidate !== null && (latestFindingAt === null || candidate > latestFindingAt))
+            latestFindingAt = candidate;
+    }
+    if (!qualifyingFindings)
+        return null;
+    let ageDays = null;
+    if (observedAt !== null && latestFindingAt !== null && latestFindingAt <= observedAt + MAX_CLOCK_SKEW_MS) {
+        ageDays = Math.max(0, Math.floor((observedAt - latestFindingAt) / DAY_MS));
+    }
+    return {
+        providerId,
+        publisherFamily,
+        qualifyingFindings,
+        lastObservedAt: latestFindingAt === null ? null : new Date(latestFindingAt).toISOString(),
+        ageDays,
+        recent: ageDays !== null && ageDays <= EXTERNAL_INTELLIGENCE_RECENT_DAYS,
+    };
+}
+export function calibrateExternalIntelligenceRisk(value) {
+    const envelope = record(value);
+    const providers = Array.isArray(envelope?.providers) ? envelope.providers.slice(0, MAX_PROVIDERS) : [];
+    const byProvider = new Map();
+    for (const item of providers) {
+        const evidence = providerEvidence(item);
+        if (!evidence || byProvider.has(evidence.providerId))
+            continue;
+        byProvider.set(evidence.providerId, evidence);
+    }
+    const sources = [...byProvider.values()].sort((a, b) => a.providerId.localeCompare(b.providerId));
+    const publisherFamilies = new Set(sources.map((source) => source.publisherFamily));
+    const recentPublisherFamilies = new Set(sources.filter((source) => source.recent).map((source) => source.publisherFamily));
+    const knownAges = sources.map((source) => source.ageDays).filter((age) => age !== null);
+    const independentPublisherCount = publisherFamilies.size;
+    const recentPublisherCount = recentPublisherFamilies.size;
+    let contribution = 0;
+    let factor = null;
+    if (independentPublisherCount >= 2) {
+        contribution = recentPublisherCount >= 2 ? 18 : 10;
+        factor = {
+            label: recentPublisherCount >= 2
+                ? 'Corroborated recent external phishing/malware records'
+                : 'Corroborated external phishing/malware records',
+            delta: contribution,
+        };
+    }
+    return {
+        version: EXTERNAL_INTELLIGENCE_CALIBRATION_VERSION,
+        contribution,
+        factor,
+        eligibleProviderCount: sources.length,
+        independentPublisherCount,
+        recentPublisherCount,
+        freshestAgeDays: knownAges.length ? Math.min(...knownAges) : null,
+        unknownAgeProviderCount: sources.filter((source) => source.ageDays === null).length,
+        sources,
+    };
+}

package/lib/favicon.mjs

@@ -0,0 +1,146 @@
+// Favicon-hash fetch - a lookalike/typosquat domain that serves the same
+// favicon as a brand's real site is a strong sign of a cloned phishing kit
+// (attackers copy the favicon along with the rest of the page); a domain
+// that merely resolves and serves *some* page proves much less.
+//
+// Two hashes are produced from the same bytes:
+//   - hash:  exact SHA-256 of the raw bytes. Zero false positives, but only
+//            catches a byte-for-byte copy.
+//   - phash: perceptual (fuzzy) dHash (lib/perceptual-hash.mts). Catches a
+//            resized/recompressed/re-saved copy that's visually identical but
+//            no longer byte-identical - the common case when the favicon
+//            passed through a different tool than the original. Null when the
+//            image format can't be decoded (GIF/JPEG/SVG), so it strictly
+//            adds coverage without weakening the exact tier.
+import * as crypto from 'node:crypto';
+import { safeFetch, readBytesCapped } from "./safe-fetch.mjs";
+import { faviconPerceptualHash } from "./perceptual-hash.mjs";
+const MAX_FAVICON_BYTES = 200000; // generous for a favicon, small enough to bound memory
+const FAVICON_FETCH_TIMEOUT_MS = 5000;
+// Bounds worst-case work when a (possibly hostile) page declares many icon
+// links - we try candidates in priority order and stop at the first that
+// yields hashable bytes, so this only bites on pages where every earlier
+// candidate fails.
+const MAX_FAVICON_CANDIDATES = 4;
+// Extracts favicon URLs declared in the page's own <link rel="...icon..."> tags
+// (resolved to absolute URLs against the page origin), in preference order:
+// standard "icon"/"shortcut icon" first, then "apple-touch-icon". Many modern
+// sites (e.g. npm) serve no /favicon.ico at all and only declare a PNG on a
+// CDN this way, so checking only /favicon.ico misses them entirely. data:
+// URIs are passed through verbatim - decodeFaviconCandidate handles them
+// without a network fetch.
+function extractIconUrls(html, baseUrl) {
+    const links = [];
+    for (const tag of html.match(/<link\b[^>]*>/gi) || []) {
+        const rel = (tag.match(/\brel\s*=\s*["']([^"']*)["']/i) || [])[1];
+        if (!rel || !/icon/i.test(rel))
+            continue;
+        const href = (tag.match(/\bhref\s*=\s*["']([^"']+)["']/i) || [])[1];
+        if (!href)
+            continue;
+        links.push({ href: href.trim(), priority: /apple-touch/i.test(rel) ? 1 : 0 });
+    }
+    links.sort((a, b) => a.priority - b.priority);
+    const urls = [];
+    for (const { href } of links) {
+        if (/^data:/i.test(href)) {
+            urls.push(href);
+            continue;
+        }
+        try {
+            const resolved = new URL(href, baseUrl);
+            if (resolved.protocol === 'http:' || resolved.protocol === 'https:')
+                urls.push(resolved.toString());
+        }
+        catch {
+            /* malformed href - skip it */
+        }
+    }
+    return urls;
+}
+// Decodes an inline `data:` favicon (base64 or percent-encoded) into a byte
+// buffer, bounded to MAX_FAVICON_BYTES. Returns null on anything malformed.
+function decodeDataUri(uri) {
+    const comma = uri.indexOf(',');
+    if (comma === -1)
+        return null;
+    const meta = uri.slice(5, comma);
+    const data = uri.slice(comma + 1);
+    try {
+        const bytes = /;base64/i.test(meta)
+            ? Buffer.from(data, 'base64')
+            : Buffer.from(decodeURIComponent(data), 'latin1');
+        return bytes.length > 0 && bytes.length <= MAX_FAVICON_BYTES ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Returns the favicon bytes for one candidate URL (a real fetch, or an inline
+// data: decode), or null if it can't be retrieved/used.
+async function fetchFaviconBytes(url, headers) {
+    if (/^data:/i.test(url))
+        return decodeDataUri(url);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FAVICON_FETCH_TIMEOUT_MS);
+    try {
+        const res = await safeFetch(url, { signal: controller.signal, headers });
+        if (!res.ok) {
+            // Not reading this body - release it explicitly instead of leaving an
+            // unconsumed stream (and the connection it's tied to) open until
+            // undici's own idle-timeout eventually notices.
+            await res.body?.cancel().catch(() => { });
+            return null;
+        }
+        // The timeout stays armed through this read (cleared in `finally` below,
+        // not right after headers arrive) - a malicious site could otherwise send
+        // headers immediately and then trickle or stall the body forever, hanging
+        // this worker with no deadline once disarmed.
+        const { bytes, truncated } = await readBytesCapped(res, MAX_FAVICON_BYTES);
+        // A truncated or empty file can't be hashed meaningfully.
+        return truncated || bytes.length === 0 ? null : bytes;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+// Fetches the domain's favicon and returns both an exact SHA-256 and a
+// perceptual dHash of the same bytes (see the module header). `html`, when
+// provided (the deep-check path already has the homepage in hand), is scanned
+// for declared <link rel="icon"> URLs, which are tried before the bare
+// /favicon.ico fallback.
+function buildFaviconCandidates(domain, html = '') {
+    const candidates = [];
+    const seen = new Set();
+    const add = (url) => { if (url && !seen.has(url)) {
+        seen.add(url);
+        candidates.push(url);
+    } };
+    if (html)
+        for (const url of extractIconUrls(html, `https://${domain}/`))
+            add(url);
+    add(`https://${domain}/favicon.ico`);
+    add(`https://${domain}/favicon.svg`);
+    add(`http://${domain}/favicon.ico`);
+    add(`http://${domain}/favicon.svg`);
+    return candidates.slice(0, MAX_FAVICON_CANDIDATES);
+}
+async function fetchFaviconHash(domain, { html = '' } = {}) {
+    const headers = { 'User-Agent': 'Mozilla/5.0 (compatible; DomainStatusChecker/1.0)' };
+    const candidates = buildFaviconCandidates(domain, html);
+    for (const url of candidates) {
+        // eslint-disable-next-line no-await-in-loop
+        const bytes = await fetchFaviconBytes(url, headers);
+        if (bytes) {
+            return {
+                hash: crypto.createHash('sha256').update(bytes).digest('hex'),
+                phash: faviconPerceptualHash(bytes),
+            };
+        }
+    }
+    return null;
+}
+export { fetchFaviconHash, extractIconUrls, buildFaviconCandidates };