@slicedearth/whoisleuth-cli 1.36.1 → 1.43.0

package/lib/html-signals.mjs

@@ -9,13 +9,13 @@ import { analyzeCredentialSurfaceProfile } from "./credential-surface-profile.mj
 import { analyzeClientBehavior } from "./client-behavior-profile.mjs";
 import { createObservation } from "./observation.mjs";
 import { createPageFingerprints } from "./page-fingerprints.mjs";
+import { detectPageLanguageSignal } from "./page-language-signals.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";
 const MAX_TITLE_LENGTH = 200;
-const MAX_PHISHING_MATCH_LENGTH = 200;
 const MAX_EXTERNAL_ASSET_HOSTS = 20;
 const MAX_IDENTITY_TAGS = 512;
 const MAX_IDENTITY_TAG_LENGTH = 4096;
@@ -40,12 +40,6 @@ const TITLE_RE = /<title[^>]*>([\s\S]*?)<\/title>/i;
 // A password input is the single strongest static-HTML tell that a page is
 // asking for credentials, regardless of what it claims to be.
 const PASSWORD_FIELD_RE = /<input\b[^>]*\btype\s*=\s*["']?password["']?/i;
-// Common urgency/social-engineering phrasing used to pressure a visitor
-// into entering credentials - not exhaustive, and legitimate sites
-// occasionally use similar language too, so this is one signal among
-// several, not a verdict on its own (same framing as FOR_SALE_TEXT_RE in
-// availability.js).
-const PHISHING_LANGUAGE_RE = /(verify your account|confirm your identity|unusual (?:sign-?in|login) activity|account has been (?:suspended|limited|locked|restricted)|your account will be (?:suspended|closed|locked|terminated)|click here to (?:verify|confirm|update|restore)|security alert|immediate action required|re-?activate your account|unauthorized access detected|update your (?:payment|billing) (?:information|details)|confirm your password|your password (?:has expired|will expire soon)|connect your wallet|enter your (?:seed|recovery) phrase|verify your (?:seed|recovery) phrase|enter your private key)/i;
 // <img>/<script>/<link> tags loading a resource from an absolute, external
 // URL - a common phishing-kit tell is hotlinking the real brand's own logo/
 // CSS/JS instead of copying it. Relative URLs (the common case, same
@@ -625,7 +619,6 @@ function extractPageIdentity(html, domain, options = {}) {
     };
 }
 function extractHtmlSignals(html, domain, options = {}) {
-    const phishingMatch = html.match(PHISHING_LANGUAGE_RE);
     const pageIdentity = options.includePageIdentity === false ? null : extractPageIdentity(html, domain, options);
     const includeCredentialSurfaceProfile = pageIdentity && options.includeCredentialSurfaceProfile === true;
     const includeStructuredDataIdentity = pageIdentity && options.includeStructuredDataIdentity !== false;
@@ -633,12 +626,13 @@ function extractHtmlSignals(html, domain, options = {}) {
     const includeDerivedPageProfiles = Boolean(pageIdentity);
     const baseUrl = resolvedBaseUrl(domain, options.baseUrl);
     const htmlAnalysis = includeCredentialSurfaceProfile || includeStructuredDataIdentity || includeTechnologyProfile || includeDerivedPageProfiles
-        ? analyzeStaticHtml(html, { baseUrl })
+        ? analyzeStaticHtml(html, { baseUrl, includeVisibleText: true })
         : null;
+    const pageLanguageSignal = detectPageLanguageSignal(html, pageIdentity?.documentLanguage, htmlAnalysis ?? undefined);
     return {
         pageTitle: extractPageTitle(html),
         hasPasswordField: PASSWORD_FIELD_RE.test(html),
-        phishingLanguageMatch: phishingMatch ? boundedHtmlText(phishingMatch[0], MAX_PHISHING_MATCH_LENGTH) : null,
+        phishingLanguageMatch: pageLanguageSignal?.label ?? null,
         hasExternalFormAction: pageIdentity
             ? pageIdentity.forms.externalActionOrigins.length > 0
             : null,
@@ -681,4 +675,4 @@ function extractHtmlSignals(html, domain, options = {}) {
         }) : null,
     };
 }
-export { PAGE_IDENTITY_VERSION, MAX_IDENTITY_TAGS, MAX_FORMS, MAX_FORM_ACTION_ORIGINS, MAX_RESOURCE_TAGS, MAX_RESOURCE_ORIGINS, MAX_EMBEDDED_ORIGINS, MAX_CONTACT_DOMAINS, MAX_TRACKING_IDENTIFIERS, extractHtmlSignals, extractPageIdentity, extractPageRelationships, };
+export { PAGE_IDENTITY_VERSION, MAX_IDENTITY_TAGS, MAX_FORMS, MAX_FORM_ACTION_ORIGINS, MAX_RESOURCE_TAGS, MAX_RESOURCE_ORIGINS, MAX_EMBEDDED_ORIGINS, MAX_CONTACT_DOMAINS, MAX_TRACKING_IDENTIFIERS, extractHtmlSignals, extractPageIdentity, };

package/lib/ip-prefix.mjs

@@ -51,4 +51,37 @@ function prefixContains(container, candidate) {
         && container.length <= candidate.length
         && (candidate.value & container.mask) === container.value;
 }
-export { parseIpPrefix, prefixContains };
+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

@@ -1,5 +1,5 @@
 import { isIP } from 'node:net';
-import { parseIpPrefix, prefixContains } from "./ip-prefix.mjs";
+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;
@@ -25,7 +25,7 @@ function normalizeGeoIpEntry(value) {
     if (asnValue !== null && (!Number.isInteger(asnValue) || asnValue < 0 || asnValue > 4_294_967_295))
         return null;
     return Object.freeze({
-        network: `${parsedNetwork.address}/${parsedNetwork.length}`,
+        network: formatIpPrefix(parsedNetwork),
         parsedNetwork,
         countryCode: country,
         region: boundedText(source.region, 120),

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/nameserver-preflight-review.mjs

@@ -0,0 +1,159 @@
+import { isIP } from 'node:net';
+import { exactKeys, requireBoundedString, requireDomainName, requireIsoTimestamp, requireRecord, } from "./bounded-contract-normalizers.mjs";
+import { isPrivateAddress } from "./safe-fetch.mjs";
+export const NAMESERVER_PREFLIGHT_INPUT_SCHEMA = 'whoisleuth.nameserver-preflight.input';
+export const NAMESERVER_PREFLIGHT_REVIEW_SCHEMA = 'whoisleuth.nameserver-preflight.review';
+export const NAMESERVER_PREFLIGHT_REVIEW_VERSION = 1;
+export const MAX_PREFLIGHT_NAMESERVERS = 8;
+export const MAX_PREFLIGHT_ADDRESSES = 4;
+const ROOT_KEYS = new Set(['schema', 'version', 'domain', 'intendedNameservers', 'observations']);
+const OBSERVATION_KEYS = new Set(['nameserver', 'state', 'source', 'observedAt', 'addresses', 'authoritative', 'servedNameservers', 'soaPrimary', 'soaSerial']);
+function text(value, label, maximum = 240) {
+    return requireBoundedString(value, label, maximum);
+}
+function hostname(value, label) {
+    return requireDomainName(value, label, 'hostname');
+}
+function timestamp(value, label) {
+    return requireIsoTimestamp(value, label);
+}
+function state(value, label) {
+    if (value !== 'observed' && value !== 'partial' && value !== 'unavailable')
+        throw new TypeError(`${label} is unsupported.`);
+    return value;
+}
+function uniqueHostnames(value, label, minimum = 1) {
+    if (!Array.isArray(value) || value.length < minimum || value.length > MAX_PREFLIGHT_NAMESERVERS) {
+        throw new TypeError(`${label} must contain from ${minimum} to ${MAX_PREFLIGHT_NAMESERVERS} hostnames.`);
+    }
+    const names = value.map((item, index) => hostname(item, `${label}[${index}]`));
+    if (new Set(names).size !== names.length)
+        throw new TypeError(`${label} must not contain duplicate hostnames.`);
+    return Object.freeze(names.sort());
+}
+function addresses(value, label) {
+    if (!Array.isArray(value) || value.length > MAX_PREFLIGHT_ADDRESSES)
+        throw new TypeError(`${label} must contain no more than ${MAX_PREFLIGHT_ADDRESSES} addresses.`);
+    const normalised = value.map((item, index) => {
+        const supplied = text(item, `${label}[${index}]`, 80).toLowerCase();
+        if (!isIP(supplied) || supplied.includes('%'))
+            throw new TypeError(`${label}[${index}] must be an IPv4 or IPv6 address without a zone identifier.`);
+        return supplied;
+    });
+    return Object.freeze([...new Set(normalised)].sort());
+}
+function sameSet(left, right) {
+    return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+export function reviewNameserverPreflight(inputRaw, generatedAtValue = new Date().toISOString()) {
+    const input = requireRecord(inputRaw, 'Nameserver preflight input');
+    if (input.schema !== NAMESERVER_PREFLIGHT_INPUT_SCHEMA || input.version !== 1) {
+        throw new TypeError(`Nameserver preflight input must use ${NAMESERVER_PREFLIGHT_INPUT_SCHEMA} version 1.`);
+    }
+    exactKeys(input, ROOT_KEYS, 'Nameserver preflight input');
+    const domain = hostname(input.domain, 'domain');
+    const intendedNameservers = uniqueHostnames(input.intendedNameservers, 'intendedNameservers');
+    if (!Array.isArray(input.observations) || input.observations.length > MAX_PREFLIGHT_NAMESERVERS) {
+        throw new TypeError(`observations must contain no more than ${MAX_PREFLIGHT_NAMESERVERS} entries.`);
+    }
+    const observations = input.observations.map((raw, index) => {
+        const item = requireRecord(raw, `observations[${index}]`);
+        exactKeys(item, OBSERVATION_KEYS, `observations[${index}]`);
+        const observationState = state(item.state, `observations[${index}].state`);
+        const nameserver = hostname(item.nameserver, `observations[${index}].nameserver`);
+        const observedAddresses = addresses(item.addresses ?? [], `observations[${index}].addresses`);
+        const servedNameservers = item.servedNameservers === undefined || item.servedNameservers === null
+            ? Object.freeze([])
+            : uniqueHostnames(item.servedNameservers, `observations[${index}].servedNameservers`, 0);
+        const authoritative = item.authoritative === null || item.authoritative === undefined
+            ? null
+            : typeof item.authoritative === 'boolean'
+                ? item.authoritative
+                : (() => { throw new TypeError(`observations[${index}].authoritative must be true, false, or null.`); })();
+        const soaPrimary = item.soaPrimary === null || item.soaPrimary === undefined ? null : hostname(item.soaPrimary, `observations[${index}].soaPrimary`);
+        const soaSerial = item.soaSerial === null || item.soaSerial === undefined
+            ? null
+            : Number.isSafeInteger(item.soaSerial) && Number(item.soaSerial) >= 0 && Number(item.soaSerial) <= 0xffff_ffff
+                ? Number(item.soaSerial)
+                : (() => { throw new TypeError(`observations[${index}].soaSerial is outside its supported range.`); })();
+        if (observationState === 'unavailable' && (observedAddresses.length || servedNameservers.length || authoritative !== null || soaPrimary !== null || soaSerial !== null)) {
+            throw new TypeError(`observations[${index}] cannot contain observed values when unavailable.`);
+        }
+        return Object.freeze({
+            nameserver,
+            state: observationState,
+            source: text(item.source, `observations[${index}].source`, 240),
+            observedAt: timestamp(item.observedAt, `observations[${index}].observedAt`),
+            addresses: observedAddresses,
+            authoritative,
+            servedNameservers,
+            soaPrimary,
+            soaSerial,
+        });
+    });
+    if (new Set(observations.map((item) => item.nameserver)).size !== observations.length)
+        throw new TypeError('observations must use unique nameservers.');
+    if (observations.some((item) => !intendedNameservers.includes(item.nameserver)))
+        throw new TypeError('observations can describe only intended nameservers.');
+    const rows = intendedNameservers.map((nameserver) => {
+        const observation = observations.find((item) => item.nameserver === nameserver) ?? null;
+        const inBailiwick = nameserver === domain || nameserver.endsWith(`.${domain}`);
+        const publicAddresses = observation?.addresses.filter((address) => !isPrivateAddress(address)) ?? [];
+        const addressState = !observation || observation.state === 'unavailable'
+            ? 'unknown'
+            : !observation.addresses.length
+                ? inBailiwick ? 'missing' : 'not_supplied'
+                : publicAddresses.length ? 'ready' : 'non_public';
+        const authorityState = !observation || observation.state !== 'observed' || observation.authoritative === null
+            ? 'unknown'
+            : observation.authoritative ? 'authoritative' : 'not_authoritative';
+        const servedSetState = !observation || observation.state !== 'observed' || !observation.servedNameservers.length
+            ? 'unknown'
+            : sameSet(observation.servedNameservers, intendedNameservers) ? 'aligned' : 'different';
+        const soaState = !observation || observation.state !== 'observed' || !observation.soaPrimary || observation.soaSerial === null
+            ? 'unknown' : 'observed';
+        const ready = observation?.state === 'observed'
+            && authorityState === 'authoritative'
+            && servedSetState === 'aligned'
+            && soaState === 'observed'
+            && (!inBailiwick || addressState === 'ready');
+        return Object.freeze({
+            nameserver,
+            inBailiwick,
+            observationState: observation?.state ?? 'not_supplied',
+            addressState,
+            authorityState,
+            servedSetState,
+            soaState,
+            publicAddresses: Object.freeze(publicAddresses),
+            ready,
+            source: observation?.source ?? null,
+            observedAt: observation?.observedAt ?? null,
+        });
+    });
+    const reasons = rows.flatMap((row) => [
+        ...(!row.ready && row.observationState !== 'observed' ? [`${row.nameserver} evidence is ${row.observationState}.`] : []),
+        ...(row.addressState === 'missing' ? [`${row.nameserver} is in-bailiwick but no glue address was supplied.`] : []),
+        ...(row.addressState === 'non_public' ? [`${row.nameserver} has no observed public address suitable for delegation.`] : []),
+        ...(row.authorityState !== 'authoritative' ? [`${row.nameserver} authoritative service is ${row.authorityState}.`] : []),
+        ...(row.servedSetState !== 'aligned' ? [`${row.nameserver} served NS set is ${row.servedSetState}.`] : []),
+        ...(row.soaState !== 'observed' ? [`${row.nameserver} SOA evidence is ${row.soaState}.`] : []),
+    ]);
+    const pass = rows.every((row) => row.ready);
+    return Object.freeze({
+        schema: NAMESERVER_PREFLIGHT_REVIEW_SCHEMA,
+        version: NAMESERVER_PREFLIGHT_REVIEW_VERSION,
+        generatedAt: timestamp(generatedAtValue, 'generatedAt'),
+        domain,
+        state: pass ? 'ready' : 'review',
+        intendedNameservers,
+        rows: Object.freeze(rows),
+        gate: Object.freeze({ pass, reasons: Object.freeze(reasons) }),
+        limitations: Object.freeze([
+            'This local preflight uses only analyst-supplied observations and makes no DNS or registry request.',
+            'A ready result describes the supplied collection moment; it does not apply a delegation, publish glue, or prove continued reachability.',
+            'Partial, unavailable, and omitted observations remain unknown and cannot satisfy the preflight gate.',
+            'Only in-bailiwick nameservers require supplied public glue evidence in this review; registry-specific policy must be checked separately.',
+        ]),
+    });
+}

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();