@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/lib/html-signals.mjs

@@ -10,6 +10,7 @@ import { analyzeClientBehavior } from "./client-behavior-profile.mjs";
 import { createObservation } from "./observation.mjs";
 import { createPageFingerprints } from "./page-fingerprints.mjs";
 import { analyzePageRole } from "./page-role-profile.mjs";
+import { analyzeCspMetaPolicies } from "./response-policy.mjs";
 import { analyzeStaticHtml } from "./static-html-analysis.mjs";
 import { analyzeStructuredDataIdentity } from "./structured-data-identity.mjs";
 import { analyzeWebsiteTechnology } from "./website-technology.mjs";
@@ -642,6 +643,9 @@ function extractHtmlSignals(html, domain, options = {}) {
             ? pageIdentity.forms.externalActionOrigins.length > 0
             : null,
         externalAssetHosts: extractExternalAssetHosts(html, domain),
+        cspMetaPolicy: htmlAnalysis
+            ? analyzeCspMetaPolicies(htmlAnalysis.cspMetaPolicies, htmlAnalysis.cspMetaLimitReached)
+            : null,
         pageIdentity,
         credentialSurfaceProfile: includeCredentialSurfaceProfile && htmlAnalysis ? analyzeCredentialSurfaceProfile({
             htmlAnalysis,

package/lib/http-evidence-bounds.mjs

@@ -0,0 +1,4 @@
+// Browser-safe bounds for the rich HTTP evidence contract and its compact
+// browser-local projection. Both producers and consumers import these values
+// so valid retained evidence is not rejected by a stale projection.
+export const MAX_HTTP_EVIDENCE_REDIRECTS = 5;

package/lib/http-intelligence.mjs

@@ -3,8 +3,9 @@
 // converts the shared safe-fetch trace and selected response metadata into an
 // additive evidence object suitable for API responses and exports.
 import { createObservation } from "./observation.mjs";
+import { MAX_HTTP_EVIDENCE_REDIRECTS } from "./http-evidence-bounds.mjs";
 const MAX_HTTP_PROVENANCE_URL = 2048;
-const MAX_HTTP_REDIRECTS = 5;
+const MAX_HTTP_REDIRECTS = MAX_HTTP_EVIDENCE_REDIRECTS;
 const MAX_HTTP_ATTEMPTS = 2;
 const MAX_HTTP_ERROR_LENGTH = 180;
 const MAX_HTTP_HEADER_LENGTH = 1024;

package/lib/ip-prefix.mjs

@@ -0,0 +1,87 @@
+import { isIP } from 'node:net';
+function ipv4Value(value) {
+    return value.split('.').reduce((total, part) => (total << 8n) | BigInt(Number(part)), 0n);
+}
+function ipv6Parts(value) {
+    if (value.includes('.'))
+        return null;
+    const halves = value.toLowerCase().split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] ? halves[0].split(':') : [];
+    const right = halves.length === 2 && halves[1] ? halves[1].split(':') : [];
+    if (left.some((part) => !/^[0-9a-f]{1,4}$/u.test(part))
+        || right.some((part) => !/^[0-9a-f]{1,4}$/u.test(part)))
+        return null;
+    const missing = 8 - left.length - right.length;
+    if (halves.length === 1 && missing !== 0 || halves.length === 2 && missing < 1)
+        return null;
+    return [...left, ...Array(missing).fill('0'), ...right].map((part) => Number.parseInt(part, 16));
+}
+function ipValue(value, family) {
+    if (family === 4)
+        return ipv4Value(value);
+    const parts = ipv6Parts(value);
+    return parts?.reduce((total, part) => (total << 16n) | BigInt(part), 0n) ?? null;
+}
+function parseIpPrefix(value) {
+    if (typeof value !== 'string' || value.length > 96 || /[\s%\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const [addressValue, lengthValue, ...rest] = value.toLowerCase().split('/');
+    if (!addressValue || rest.length > 0)
+        return null;
+    const family = isIP(addressValue);
+    if (family !== 4 && family !== 6)
+        return null;
+    const maximum = family === 4 ? 32 : 128;
+    if (lengthValue !== undefined && !/^\d{1,3}$/u.test(lengthValue))
+        return null;
+    const length = lengthValue === undefined ? maximum : Number(lengthValue);
+    if (!Number.isInteger(length) || length < 0 || length > maximum)
+        return null;
+    const numeric = ipValue(addressValue, family);
+    if (numeric === null)
+        return null;
+    const full = (1n << BigInt(maximum)) - 1n;
+    const mask = length === 0 ? 0n : (full << BigInt(maximum - length)) & full;
+    return Object.freeze({ family, address: addressValue, length, value: numeric & mask, mask });
+}
+function prefixContains(container, candidate) {
+    return container.family === candidate.family
+        && container.length <= candidate.length
+        && (candidate.value & container.mask) === container.value;
+}
+function formatIpPrefix(prefix) {
+    if (prefix.family === 4) {
+        const parts = [24n, 16n, 8n, 0n].map((shift) => Number((prefix.value >> shift) & 255n));
+        return `${parts.join('.')}/${prefix.length}`;
+    }
+    const parts = Array.from({ length: 8 }, (_, index) => {
+        const shift = BigInt((7 - index) * 16);
+        return ((prefix.value >> shift) & 0xffffn).toString(16);
+    });
+    let bestStart = -1;
+    let bestLength = 0;
+    for (let start = 0; start < parts.length;) {
+        if (parts[start] !== '0') {
+            start += 1;
+            continue;
+        }
+        let end = start + 1;
+        while (end < parts.length && parts[end] === '0')
+            end += 1;
+        const length = end - start;
+        if (length > bestLength && length >= 2) {
+            bestStart = start;
+            bestLength = length;
+        }
+        start = end;
+    }
+    if (bestStart === -1)
+        return `${parts.join(':')}/${prefix.length}`;
+    const left = parts.slice(0, bestStart).join(':');
+    const right = parts.slice(bestStart + bestLength).join(':');
+    const address = left && right ? `${left}::${right}` : left ? `${left}::` : right ? `::${right}` : '::';
+    return `${address}/${prefix.length}`;
+}
+export { parseIpPrefix, prefixContains, formatIpPrefix };

package/lib/local-geoip-evidence.mjs

@@ -0,0 +1,89 @@
+import { isIP } from 'node:net';
+import { formatIpPrefix, parseIpPrefix, prefixContains } from "./ip-prefix.mjs";
+const LOCAL_GEOIP_SCHEMA = 'whoisleuth.local-geoip-evidence';
+const LOCAL_GEOIP_VERSION = 1;
+const MAX_GEOIP_RECORDS = 100_000;
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function boundedText(value, maximum) {
+    if (typeof value !== 'string' || value.length > maximum || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    return value.replace(/\s+/gu, ' ').trim() || null;
+}
+function normalizeGeoIpEntry(value) {
+    const source = record(value);
+    const parsedNetwork = parseIpPrefix(source?.network ?? source?.cidr);
+    if (!source || !parsedNetwork)
+        return null;
+    const country = boundedText(source.countryCode ?? source.country, 2)?.toUpperCase() ?? null;
+    if (country !== null && !/^[A-Z]{2}$/u.test(country))
+        return null;
+    const asnValue = source.asn === null || source.asn === undefined ? null : Number(String(source.asn).replace(/^AS/iu, ''));
+    if (asnValue !== null && (!Number.isInteger(asnValue) || asnValue < 0 || asnValue > 4_294_967_295))
+        return null;
+    return Object.freeze({
+        network: formatIpPrefix(parsedNetwork),
+        parsedNetwork,
+        countryCode: country,
+        region: boundedText(source.region, 120),
+        city: boundedText(source.city, 120),
+        asn: asnValue,
+        asName: boundedText(source.asName ?? source.organization, 240),
+    });
+}
+function buildLocalGeoIpDatabase(value) {
+    const source = record(value);
+    const sourceLabel = boundedText(source?.sourceLabel, 120);
+    const databaseVersion = boundedText(source?.databaseVersion, 80);
+    const license = boundedText(source?.license, 240);
+    const rows = Array.isArray(source?.records) ? source.records : null;
+    if (!sourceLabel || !databaseVersion || !license || !rows) {
+        throw new TypeError('A local GeoIP database requires bounded source, version, licence, and record fields.');
+    }
+    const truncated = rows.length > MAX_GEOIP_RECORDS;
+    const normalized = rows.slice(0, MAX_GEOIP_RECORDS).map(normalizeGeoIpEntry);
+    const records = normalized.filter((item) => item !== null)
+        .sort((left, right) => right.parsedNetwork.length - left.parsedNetwork.length);
+    return Object.freeze({
+        sourceLabel,
+        databaseVersion,
+        license,
+        records: Object.freeze(records),
+        rejectedCount: normalized.length - records.length + Math.max(0, rows.length - MAX_GEOIP_RECORDS),
+        truncated,
+    });
+}
+function lookupLocalGeoIp(database, address) {
+    const normalized = typeof address === 'string' ? address.trim().toLowerCase() : '';
+    const family = isIP(normalized);
+    const target = family === 4 || family === 6 ? parseIpPrefix(normalized) : null;
+    if (!target) {
+        return Object.freeze({ state: 'invalid', address: null, match: null, source: null, limitations: Object.freeze([]) });
+    }
+    const match = database.records.find((item) => prefixContains(item.parsedNetwork, target)) ?? null;
+    return Object.freeze({
+        state: match ? database.truncated || database.rejectedCount > 0 ? 'partial' : 'matched' : 'not_found',
+        address: normalized,
+        match: match ? Object.freeze({
+            network: match.network,
+            countryCode: match.countryCode,
+            region: match.region,
+            city: match.city,
+            asn: match.asn,
+            asName: match.asName,
+        }) : null,
+        source: Object.freeze({
+            label: database.sourceLabel,
+            version: database.databaseVersion,
+            license: database.license,
+        }),
+        limitations: Object.freeze([
+            'Geolocation and network attribution are provider estimates and may be stale, coarse, shared, or incorrect.',
+            'A location or ASN association does not establish the operator, owner, user, intent, safety, or maliciousness of an address.',
+        ]),
+    });
+}
+export { LOCAL_GEOIP_SCHEMA, LOCAL_GEOIP_VERSION, MAX_GEOIP_RECORDS, buildLocalGeoIpDatabase, lookupLocalGeoIp, };

package/lib/lookup-response-contract.mjs

@@ -0,0 +1,346 @@
+// Shared HTTP response boundary for the unified Lookup API.
+//
+// The backend owns the evidence collectors, but an HTTP response is still an
+// untrusted value when it reaches the browser. This module keeps the response
+// envelope typed and validates the small set of fields the Lookup controller
+// relies on before any evidence is derived or rendered. Nested source records
+// stay separately attributed and additive; their own normalizers remain the
+// authority for source-specific fields.
+const INVALID_LOOKUP_RESPONSE = 'INVALID_LOOKUP_RESPONSE';
+const INVALID_LOOKUP_RESPONSE_MESSAGE = 'Lookup returned an invalid response.';
+const INVALID_COMPACT_LOOKUP_RESPONSE = 'INVALID_COMPACT_LOOKUP_RESPONSE';
+const INVALID_COMPACT_LOOKUP_RESPONSE_MESSAGE = 'Bulk lookup returned an invalid response.';
+const MAX_LOOKUP_RESPONSE_QUERY_LENGTH = 4096;
+const MAX_LOOKUP_RESPONSE_HOST_LENGTH = 253;
+const MAX_LOOKUP_RESPONSE_TOP_LEVEL_KEYS = 32;
+const MAX_LOOKUP_RESPONSE_ERROR_LENGTH = 240;
+const MAX_COMPACT_LOOKUP_RESPONSE_TOP_LEVEL_KEYS = 8;
+const MAX_COMPACT_LOOKUP_AVAILABILITY_KEYS = 128;
+const MAX_COMPACT_LOOKUP_DIAGNOSTIC_KEYS = 16;
+const MAX_COMPACT_BULK_TECHNOLOGY_IDS = 12;
+const MAX_THREAT_INTELLIGENCE_PROVIDERS = 10;
+const MAX_LOOKUP_TIMING_MS = 120_000;
+const MAX_LOOKUP_TIMING_SOURCES = 10;
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/u;
+const QUERY_TYPES = new Set(['domain', 'ipv4', 'ipv6', 'asn']);
+const COMPACT_AVAILABILITY_STATES = new Set([
+    'available',
+    'expiring',
+    'for_sale',
+    'registered',
+    'unknown',
+]);
+const COMPACT_CONFIDENCE_LEVELS = new Set(['high', 'low', 'medium']);
+const COMPACT_AVAILABILITY_DIAGNOSTIC_STATES = new Set(['complete', 'disabled', 'error']);
+const COMPACT_BULK_COMPARISON_STATES = new Set([
+    'error',
+    'not_found',
+    'partial',
+    'success',
+    'unavailable',
+]);
+const COMPACT_BULK_TECHNOLOGY_ID_RE = /^[a-z0-9][a-z0-9_-]{0,79}$/u;
+const SHA256_RE = /^[a-f0-9]{64}$/u;
+const LOOKUP_TIMING_SOURCES = new Set([
+    'rdap',
+    'whois',
+    'domain_evidence',
+    'reverse_dns',
+    'registrar_rdap',
+    'network_context',
+    'security_txt',
+    'external_intelligence',
+    'malware_host_intelligence',
+    'malware_ioc_intelligence',
+]);
+const LOOKUP_TIMING_OUTCOMES = new Set(['fulfilled', 'rejected']);
+const EMPTY_RECORD = Object.freeze({});
+function isJsonObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function record(value) {
+    return isJsonObject(value) ? value : EMPTY_RECORD;
+}
+function optionalBoundedText(value, maxLength) {
+    return value === undefined || (typeof value === 'string'
+        && value.length <= maxLength
+        && !CONTROL_CHAR_RE.test(value));
+}
+function normalizedDomain(value) {
+    if (typeof value !== 'string'
+        || !value.trim()
+        || value.length > MAX_LOOKUP_RESPONSE_HOST_LENGTH
+        || CONTROL_CHAR_RE.test(value)
+        || /[\s/?#@\\:]/u.test(value)) {
+        return null;
+    }
+    try {
+        const parsed = new URL(`https://${value.trim().replace(/\.$/u, '')}/`);
+        const hostname = parsed.hostname.toLowerCase().replace(/\.$/u, '');
+        const labels = hostname.split('.');
+        return labels.length >= 2
+            && hostname.length <= MAX_LOOKUP_RESPONSE_HOST_LENGTH
+            && labels.every((label) => (label.length <= 63
+                && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(label)))
+            ? hostname
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function compactDomainMatches(value, expectedDomain) {
+    const domain = normalizedDomain(value);
+    const expected = normalizedDomain(expectedDomain);
+    return Boolean(domain && expected && (domain === expected || expected.endsWith(`.${domain}`)));
+}
+function validCompactBulkComparison(value) {
+    if (!isJsonObject(value)
+        || Object.keys(value).length > 3
+        || value.version !== 1
+        || !isJsonObject(value.technology)
+        || Object.keys(value.technology).length > 3
+        || typeof value.technology.state !== 'string'
+        || !COMPACT_BULK_COMPARISON_STATES.has(value.technology.state)
+        || !Array.isArray(value.technology.ids)
+        || value.technology.ids.length > MAX_COMPACT_BULK_TECHNOLOGY_IDS
+        || typeof value.technology.truncated !== 'boolean'
+        || !isJsonObject(value.tls)
+        || Object.keys(value.tls).length > 3
+        || typeof value.tls.state !== 'string'
+        || !COMPACT_BULK_COMPARISON_STATES.has(value.tls.state)
+        || (value.tls.issuerLabel !== null && !optionalBoundedText(value.tls.issuerLabel, 240))
+        || (value.tls.spkiSha256 !== null
+            && (typeof value.tls.spkiSha256 !== 'string' || !SHA256_RE.test(value.tls.spkiSha256)))) {
+        return false;
+    }
+    const ids = value.technology.ids;
+    return ids.every((id) => typeof id === 'string' && COMPACT_BULK_TECHNOLOGY_ID_RE.test(id))
+        && new Set(ids).size === ids.length;
+}
+function invalidLookupResponse() {
+    return {
+        ok: false,
+        errorCode: INVALID_LOOKUP_RESPONSE,
+        error: INVALID_LOOKUP_RESPONSE_MESSAGE,
+    };
+}
+function invalidCompactLookupResponse() {
+    return {
+        ok: false,
+        errorCode: INVALID_COMPACT_LOOKUP_RESPONSE,
+        error: INVALID_COMPACT_LOOKUP_RESPONSE_MESSAGE,
+    };
+}
+function parseLookupHttpResponse(value) {
+    if (!isJsonObject(value) || Object.keys(value).length > MAX_LOOKUP_RESPONSE_TOP_LEVEL_KEYS) {
+        return invalidLookupResponse();
+    }
+    if (typeof value.query !== 'string'
+        || !value.query.trim()
+        || value.query.length > MAX_LOOKUP_RESPONSE_QUERY_LENGTH
+        || CONTROL_CHAR_RE.test(value.query)
+        || typeof value.type !== 'string'
+        || !QUERY_TYPES.has(value.type)
+        || !isJsonObject(value.rdap)
+        || !isJsonObject(value.whois)
+        || !isJsonObject(value.availability)
+        || !isJsonObject(value.diagnostics)
+        || !optionalBoundedText(value.inputHostname, MAX_LOOKUP_RESPONSE_HOST_LENGTH)
+        || !optionalBoundedText(value.registrableDomain, MAX_LOOKUP_RESPONSE_HOST_LENGTH)
+        || (value.isSubdomain !== undefined && typeof value.isSubdomain !== 'boolean')) {
+        return invalidLookupResponse();
+    }
+    for (const key of ['reverseDns', 'networkContext', 'securityTxt', 'sslbl', 'threatIntelligence', 'registryInsights']) {
+        const section = value[key];
+        if (section !== undefined && !isJsonObject(section))
+            return invalidLookupResponse();
+    }
+    return { ok: true, value: value };
+}
+function parseCompactLookupHttpResponse(value, expectedDomain) {
+    if (!isJsonObject(value) || Object.keys(value).length > MAX_COMPACT_LOOKUP_RESPONSE_TOP_LEVEL_KEYS) {
+        return invalidCompactLookupResponse();
+    }
+    const availability = value.availability;
+    const diagnostics = value.diagnostics;
+    if (!isJsonObject(availability)
+        || Object.keys(availability).length > MAX_COMPACT_LOOKUP_AVAILABILITY_KEYS
+        || availability.applicable !== true
+        || !compactDomainMatches(availability.domain, expectedDomain)
+        || typeof availability.state !== 'string'
+        || !COMPACT_AVAILABILITY_STATES.has(availability.state)
+        || typeof availability.confidence !== 'string'
+        || !COMPACT_CONFIDENCE_LEVELS.has(availability.confidence)
+        || (availability.deepScanComplete !== undefined && typeof availability.deepScanComplete !== 'boolean')
+        || (availability.bulkComparison !== undefined
+            && !validCompactBulkComparison(availability.bulkComparison))
+        || (value.query !== undefined && !compactDomainMatches(value.query, expectedDomain))
+        || (value.type !== undefined && value.type !== 'domain')
+        || (value.inputHostname !== undefined && !compactDomainMatches(value.inputHostname, expectedDomain))
+        || (value.registrableDomain !== undefined
+            && normalizedDomain(value.registrableDomain) !== normalizedDomain(availability.domain))
+        || (value.isSubdomain !== undefined && typeof value.isSubdomain !== 'boolean')
+        || !isJsonObject(diagnostics)
+        || Object.keys(diagnostics).length > MAX_COMPACT_LOOKUP_DIAGNOSTIC_KEYS
+        || diagnostics.version !== 7
+        || !isJsonObject(diagnostics.rdap)
+        || !isJsonObject(diagnostics.whois)
+        || !isJsonObject(diagnostics.availability)
+        || typeof diagnostics.availability.status !== 'string'
+        || !COMPACT_AVAILABILITY_DIAGNOSTIC_STATES.has(diagnostics.availability.status)) {
+        return invalidCompactLookupResponse();
+    }
+    return { ok: true, value: value };
+}
+function lookupHttpErrorMessage(value, status) {
+    const source = record(value);
+    const message = typeof source.error === 'string'
+        ? source.error
+            .replace(/[\u0000-\u001f\u007f]+/gu, ' ')
+            .replace(/\s+/gu, ' ')
+            .trim()
+            .slice(0, MAX_LOOKUP_RESPONSE_ERROR_LENGTH)
+        : '';
+    return message || `Lookup failed (${status})`;
+}
+function isBoundedTimingMs(value, totalMs) {
+    return Number.isInteger(value)
+        && Number(value) >= 0
+        && Number(value) <= totalMs
+        && Number(value) <= MAX_LOOKUP_TIMING_MS;
+}
+function normalizeLookupTiming(value) {
+    if (!isJsonObject(value)
+        || value.version !== 1
+        || !Number.isInteger(value.totalMs)
+        || Number(value.totalMs) < 0
+        || Number(value.totalMs) > MAX_LOOKUP_TIMING_MS
+        || !Array.isArray(value.sources)
+        || value.sources.length > MAX_LOOKUP_TIMING_SOURCES) {
+        return null;
+    }
+    const totalMs = Number(value.totalMs);
+    const seen = new Set();
+    const sources = [];
+    for (const candidate of value.sources) {
+        if (!isJsonObject(candidate)
+            || typeof candidate.source !== 'string'
+            || !LOOKUP_TIMING_SOURCES.has(candidate.source)
+            || seen.has(candidate.source)
+            || typeof candidate.outcome !== 'string'
+            || !LOOKUP_TIMING_OUTCOMES.has(candidate.outcome)
+            || !isBoundedTimingMs(candidate.durationMs, totalMs)
+            || !isBoundedTimingMs(candidate.completedAfterMs, totalMs)
+            || Number(candidate.durationMs) > Number(candidate.completedAfterMs)) {
+            return null;
+        }
+        const source = candidate.source;
+        seen.add(source);
+        sources.push({
+            source,
+            outcome: candidate.outcome,
+            durationMs: Number(candidate.durationMs),
+            completedAfterMs: Number(candidate.completedAfterMs),
+        });
+    }
+    return {
+        version: 1,
+        totalMs,
+        sources,
+    };
+}
+function createLookupHttpResponse(query, classified, result) {
+    return {
+        ...result,
+        query,
+        type: classified.type,
+        inputHostname: classified.inputHostname,
+        registrableDomain: classified.registrableDomain,
+        isSubdomain: classified.isSubdomain,
+    };
+}
+function createLookupViewModel(response) {
+    const availability = record(response?.availability);
+    const rdap = record(response?.rdap);
+    const registrarRdap = record(rdap.registrarRdap);
+    const whois = record(response?.whois);
+    const diagnostics = record(response?.diagnostics);
+    const reverseDns = record(response?.reverseDns);
+    const observedNetworkContext = record(response?.networkContext);
+    const registryInsights = record(response?.registryInsights);
+    const securityTxt = record(response?.securityTxt);
+    const sslbl = record(response?.sslbl);
+    const threatIntelligence = record(response?.threatIntelligence);
+    const providers = Array.isArray(threatIntelligence.providers)
+        ? threatIntelligence.providers
+            .filter(isJsonObject)
+            .slice(0, MAX_THREAT_INTELLIGENCE_PROVIDERS)
+        : [];
+    const dnsEvidence = record(availability.dns);
+    const httpEvidence = record(availability.http);
+    const httpResponse = record(httpEvidence.response);
+    const tlsEvidence = record(availability.tls);
+    const tlsCertificate = record(tlsEvidence.certificate);
+    const pageIdentity = record(availability.pageIdentity);
+    const pageOpenGraph = record(pageIdentity.openGraph);
+    const pageResources = record(pageIdentity.resources);
+    const securityPosture = record(availability.securityPosture);
+    return {
+        availability,
+        rdap,
+        registrarRdap,
+        registrarRdapParsed: record(registrarRdap.parsed),
+        whois,
+        rdapParsed: record(rdap.parsed),
+        whoisParsed: record(whois.parsed),
+        diagnostics,
+        timing: normalizeLookupTiming(diagnostics.timing),
+        registryAccess: record(diagnostics.registryAccess),
+        registryInsights,
+        reverseDns,
+        reverseDnsRecords: record(reverseDns.records),
+        observedNetworkContext,
+        observedNetworkEndpoint: record(observedNetworkContext.endpoint),
+        observedNetworkRdap: record(observedNetworkContext.rdap),
+        observedNetwork: record(observedNetworkContext.network),
+        securityTxt,
+        sslbl,
+        threatIntelligence,
+        threatIntelligenceProviders: providers,
+        dnsEvidence,
+        dnsRecords: record(dnsEvidence.records),
+        httpEvidence,
+        httpResponse,
+        httpSecurityHeaders: record(httpResponse.securityHeaders),
+        tlsEvidence,
+        tlsCertificate,
+        tlsSubject: record(tlsCertificate.subject),
+        tlsIssuer: record(tlsCertificate.issuer),
+        tlsAltNames: record(tlsCertificate.subjectAltNames),
+        tlsPublicKey: record(tlsCertificate.publicKey),
+        tlsCipher: record(tlsEvidence.cipher),
+        tlsAuthorization: record(tlsEvidence.authorization),
+        tlsHostname: record(tlsEvidence.hostname),
+        tlsValidity: record(tlsEvidence.validity),
+        tlsDiagnostics: record(tlsEvidence.diagnostics),
+        pageIdentity,
+        pageCanonical: record(pageIdentity.canonical),
+        pageMetaRefresh: record(pageIdentity.metaRefresh),
+        pageOpenGraph,
+        pageOpenGraphUrl: record(pageOpenGraph.url),
+        pageForms: record(pageIdentity.forms),
+        pageResources,
+        pageResourceTypes: record(pageResources.byType),
+        pageDownloads: record(pageIdentity.downloads),
+        pageFingerprints: record(pageIdentity.fingerprints),
+        credentialSurfaceProfile: record(availability.credentialSurfaceProfile),
+        structuredDataIdentity: record(availability.structuredDataIdentity),
+        technologyProfile: record(availability.technologyProfile),
+        pageRoleProfile: record(availability.pageRoleProfile),
+        clientBehaviorProfile: record(availability.clientBehaviorProfile),
+        securityPosture,
+        securityPostureSummary: record(securityPosture.summary),
+    };
+}
+export { INVALID_COMPACT_LOOKUP_RESPONSE, INVALID_COMPACT_LOOKUP_RESPONSE_MESSAGE, INVALID_LOOKUP_RESPONSE, INVALID_LOOKUP_RESPONSE_MESSAGE, MAX_COMPACT_LOOKUP_AVAILABILITY_KEYS, MAX_COMPACT_LOOKUP_DIAGNOSTIC_KEYS, MAX_COMPACT_LOOKUP_RESPONSE_TOP_LEVEL_KEYS, MAX_LOOKUP_RESPONSE_ERROR_LENGTH, MAX_LOOKUP_RESPONSE_HOST_LENGTH, MAX_LOOKUP_RESPONSE_QUERY_LENGTH, MAX_LOOKUP_RESPONSE_TOP_LEVEL_KEYS, MAX_LOOKUP_TIMING_MS, MAX_LOOKUP_TIMING_SOURCES, MAX_THREAT_INTELLIGENCE_PROVIDERS, createLookupHttpResponse, createLookupViewModel, isJsonObject, lookupHttpErrorMessage, normalizeLookupTiming, parseCompactLookupHttpResponse, parseLookupHttpResponse, record as lookupRecord, };

package/lib/observed-network-context.mjs

@@ -297,7 +297,7 @@ async function collectObservedNetworkContext(availabilityValue, options = {}) {
             });
         const parsed = record(rdapRecord.parsed);
         if (rdap.httpStatus !== 200 || !Object.keys(parsed).length)
-            throw new Error('IP RDAP returned no usable normalized object');
+            throw new Error('IP RDAP returned no usable normalised object');
         const summary = networkSummary(parsed, selection.family);
         const partial = summary.truncated;
         const sourceObservedAt = rdap.fetchedAt || observedAt();

package/lib/opportunity-scoring.mjs

@@ -0,0 +1,107 @@
+import { buildScoreEvidenceQuality, } from "./scoring-evidence-quality.mjs";
+export const OPPORTUNITY_MODEL_VERSION = 2;
+export const OPPORTUNITY_REVIEW_THRESHOLD = 70;
+const STATE_BASE = Object.freeze({
+    available: 82,
+    for_sale: 70,
+    expiring: 52,
+    registered: 22,
+});
+const STATE_LABELS = Object.freeze({
+    available: 'available',
+    for_sale: 'registered with a sale signal',
+    expiring: 'registered in a lifecycle transition',
+    registered: 'registered',
+});
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function formatAge(days) {
+    if (days < 60)
+        return `${Math.max(0, Math.round(days))}d old`;
+    const years = days / 365.25;
+    return years < 1 ? `${Math.round(days / 30)}mo old` : `${years.toFixed(1)}y old`;
+}
+function addFactor(factors, dimensions, family, label, delta) {
+    factors.push({ family, label, delta });
+    dimensions.set(family, (dimensions.get(family) ?? 0) + delta);
+}
+export function normalizeOpportunityModelVersion(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= 1000 ? value : null;
+}
+// Opportunity is acquisition readiness, not price, value, eligibility, or a
+// prediction that a registration will lapse. It uses only bounded evidence
+// already collected for the current lookup.
+export function explainOpportunityScore(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const input = value;
+    const state = input.availability ?? input.state;
+    if (typeof state !== 'string' || !Object.hasOwn(STATE_BASE, state))
+        return null;
+    const factors = [];
+    const dimensions = new Map();
+    addFactor(factors, dimensions, 'registration', `Base readiness for “${STATE_LABELS[state] ?? state}”`, STATE_BASE[state] ?? 0);
+    if (input.confidence === 'high')
+        addFactor(factors, dimensions, 'registration', 'High-confidence registration decision', 8);
+    else if (input.confidence === 'medium')
+        addFactor(factors, dimensions, 'registration', 'Medium-confidence registration decision', 3);
+    else if (input.confidence === 'low')
+        addFactor(factors, dimensions, 'registration', 'Low-confidence registration decision', -8);
+    if (state === 'for_sale')
+        addFactor(factors, dimensions, 'listing', 'Bounded sale signal observed; listing remains unverified', 6);
+    else if (input.activityStatus === 'parked')
+        addFactor(factors, dimensions, 'listing', 'Parked page observed without a verified sale offer', 3);
+    else if (state === 'registered' && input.activityStatus === 'active') {
+        addFactor(factors, dimensions, 'listing', 'Active website suggests an in-use registration', -12);
+    }
+    if (input.hasPublicRegistrantContact === true) {
+        addFactor(factors, dimensions, 'contactability', 'Public registrant contact route observed; acquisition suitability is not established', 10);
+    }
+    const expiresInDays = finite(input.expiresInDays);
+    if (state === 'registered' && expiresInDays !== null && expiresInDays >= 0 && expiresInDays < 30) {
+        addFactor(factors, dimensions, 'lifecycle', 'Published expiry is within 30 days; release is not implied', 4);
+    }
+    if (typeof input.privacyProtected === 'boolean') {
+        addFactor(factors, dimensions, 'contactability', 'Registration privacy is neutral; it does not establish contactability', 0);
+    }
+    const ageDays = finite(input.domainAgeDays);
+    if (ageDays !== null && ageDays >= 0) {
+        addFactor(factors, dimensions, 'registration', `Domain age (${formatAge(ageDays)}) is context only`, 0);
+    }
+    const rawScore = Math.round(factors.reduce((total, factor) => total + factor.delta, 0));
+    const score = Math.max(0, Math.min(100, rawScore));
+    const dimensionLabels = {
+        registration: 'Registration certainty',
+        listing: 'Listing readiness',
+        contactability: 'Contactability',
+        lifecycle: 'Lifecycle timing',
+    };
+    const observedFamilies = [...dimensions.keys()];
+    const evidenceQuality = buildScoreEvidenceQuality(input, {
+        expectedDepth: 'fast',
+        observedFamilies,
+        expectedFamilies: ['registration'],
+    });
+    return {
+        modelVersion: OPPORTUNITY_MODEL_VERSION,
+        score,
+        rawScore,
+        capped: score !== rawScore,
+        factors,
+        dimensions: [...dimensions.entries()].map(([id, contribution]) => ({ id, label: dimensionLabels[id], contribution })),
+        evidenceQuality,
+    };
+}
+export function computeOpportunityScore(value) {
+    return explainOpportunityScore(value)?.score ?? null;
+}
+export function opportunityTone(score) {
+    if (score === null)
+        return 'neutral';
+    if (score >= OPPORTUNITY_REVIEW_THRESHOLD)
+        return 'good';
+    if (score >= 40)
+        return 'neutral';
+    return 'warn';
+}