@slicedearth/whoisleuth-cli 1.32.0

package/lib/rdap-registrar.mjs

@@ -0,0 +1,196 @@
+import net from 'node:net';
+import { cached } from "./lookup-cache.mjs";
+import { rdapAttempt } from "./rdap-attempts.mjs";
+import { MAX_RDAP_ENDPOINT_LENGTH } from "./rdap-bootstrap.mjs";
+import { fetchRdapDetailedWithTimeout, } from "./rdap-transport.mjs";
+import { canonicalRdapDomain, validateRdapResponse, } from "./rdap-validation.mjs";
+const REGISTRAR_RDAP_TIMEOUT_MS = 7_000;
+function recordOrNull(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function registrarRdapError(endpoint, outcome, options = {}) {
+    const attempt = rdapAttempt(endpoint, outcome, options);
+    const detail = attempt.detail || 'The registrar RDAP request failed.';
+    return Object.assign(new Error(detail), {
+        registrarRdap: {
+            status: 'error',
+            detail,
+            endpoint: attempt.endpoint,
+            transportSecurity: attempt.transportSecurity,
+            upstreamStatus: attempt.status,
+            fetchedAt: null,
+            attempt,
+        },
+    });
+}
+function domainEndpointIdentity(raw, domain) {
+    try {
+        const url = new URL(raw);
+        const canonical = canonicalRdapDomain(domain);
+        const path = url.pathname.replace(/\/+$/, '');
+        const encodedDomain = path.match(/\/domain\/([^/]+)$/i)?.[1];
+        if (!canonical || !encodedDomain)
+            return null;
+        const pathDomain = canonicalRdapDomain(decodeURIComponent(encodedDomain));
+        if (pathDomain !== canonical)
+            return null;
+        return `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}/domain/${canonical}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function selectRegistrarRdapLink(domain, links, registryEndpoint = null) {
+    const canonical = canonicalRdapDomain(domain);
+    if (!canonical || !Array.isArray(links))
+        return null;
+    const registryIdentity = registryEndpoint
+        ? domainEndpointIdentity(registryEndpoint, canonical)
+        : null;
+    for (const linkValue of links) {
+        const link = linkValue;
+        if (!link || typeof link !== 'object' || Array.isArray(link))
+            continue;
+        if (link.rel !== 'related' || typeof link.href !== 'string')
+            continue;
+        if (link.href.length > MAX_RDAP_ENDPOINT_LENGTH ||
+            /[\u0000-\u001f\u007f]/.test(link.href)) {
+            continue;
+        }
+        let url;
+        try {
+            url = new URL(link.href);
+        }
+        catch {
+            continue;
+        }
+        if (url.protocol !== 'https:' || url.username || url.password)
+            continue;
+        if (url.port || url.search || url.hash)
+            continue;
+        const hostname = url.hostname.replace(/^\[|\]$/g, '');
+        if (net.isIP(hostname))
+            continue;
+        const type = typeof link.type === 'string'
+            ? (link.type.split(';', 1)[0] ?? '').trim().toLowerCase()
+            : '';
+        if (type && type !== 'application/rdap+json')
+            continue;
+        const identity = domainEndpointIdentity(url.href, canonical);
+        if (!identity || identity === registryIdentity)
+            continue;
+        return url.href;
+    }
+    return null;
+}
+export async function fetchRegistrarRdapRecordWithParser(domain, registryRecord, parseRdap, options = {}) {
+    const canonical = canonicalRdapDomain(domain);
+    if (!canonical)
+        throw new Error('A valid domain is required for registrar RDAP.');
+    const fetchUpstream = options.fetchUpstream || fetchRdapDetailedWithTimeout;
+    return cached(`rdap-registrar:domain:${canonical}`, async () => {
+        const registryParsed = recordOrNull(registryRecord?.parsed);
+        const registryEndpoint = typeof registryRecord?.rdapServer === 'string' ? registryRecord.rdapServer : null;
+        const endpoint = selectRegistrarRdapLink(canonical, registryParsed?.links, registryEndpoint);
+        if (!endpoint) {
+            return {
+                status: 'unsupported',
+                detail: 'The registry did not publish a registrar RDAP link for this domain.',
+                endpoint: null,
+                transportSecurity: null,
+                upstreamStatus: null,
+                fetchedAt: null,
+                attempt: null,
+            };
+        }
+        let upstream;
+        try {
+            upstream = await fetchUpstream(endpoint, { headers: { Accept: 'application/rdap+json' } }, REGISTRAR_RDAP_TIMEOUT_MS);
+        }
+        catch (cause) {
+            const error = cause && typeof cause === 'object' && !Array.isArray(cause)
+                ? cause
+                : {};
+            const detail = typeof error.message === 'string' ? error.message : 'request failed';
+            const outcome = error.name === 'AbortError' || /timed? out|time limit/i.test(detail)
+                ? 'timeout'
+                : /exceeded \d+ bytes/i.test(detail)
+                    ? 'invalid_response'
+                    : 'network_error';
+            throw registrarRdapError(endpoint, outcome, { detail });
+        }
+        const selectedEndpoint = upstream.finalUrl || endpoint;
+        if (selectRegistrarRdapLink(canonical, [{ rel: 'related', href: selectedEndpoint }], registryEndpoint) !== selectedEndpoint) {
+            throw registrarRdapError(selectedEndpoint, 'invalid_response', {
+                status: upstream.status,
+                detail: 'The registrar endpoint redirected outside the eligible HTTPS domain-object URL boundary.',
+            });
+        }
+        if (upstream.status !== 404 && !upstream.ok) {
+            const outcome = upstream.status === 429
+                ? 'rate_limited'
+                : upstream.status >= 500
+                    ? 'server_error'
+                    : 'client_error';
+            throw registrarRdapError(selectedEndpoint, outcome, {
+                status: upstream.status,
+                detail: `The registrar endpoint returned HTTP ${upstream.status}.`,
+            });
+        }
+        let data;
+        try {
+            data = JSON.parse(upstream.text);
+        }
+        catch {
+            throw registrarRdapError(selectedEndpoint, 'invalid_json', {
+                status: upstream.status,
+                detail: 'The registrar endpoint returned invalid JSON.',
+            });
+        }
+        const fetchedAt = new Date().toISOString();
+        if (upstream.status === 404) {
+            const attempt = rdapAttempt(selectedEndpoint, 'not_found', {
+                status: upstream.status,
+                detail: 'The registrar endpoint reported no matching object.',
+                selected: true,
+            });
+            return {
+                status: 'not_found',
+                detail: 'The registrar RDAP service reported no matching object.',
+                endpoint: selectedEndpoint,
+                transportSecurity: 'https',
+                upstreamStatus: upstream.status,
+                fetchedAt,
+                data,
+                parsed: null,
+                attempt,
+            };
+        }
+        const parsed = parseRdap('domain', data);
+        const validation = validateRdapResponse('domain', canonical, parsed);
+        if (!validation.valid) {
+            throw registrarRdapError(selectedEndpoint, 'invalid_response', {
+                status: upstream.status,
+                detail: validation.detail,
+            });
+        }
+        const attempt = rdapAttempt(selectedEndpoint, 'success', {
+            status: upstream.status,
+            detail: 'The registrar endpoint returned the requested RDAP object.',
+            selected: true,
+        });
+        return {
+            status: 'success',
+            detail: null,
+            endpoint: selectedEndpoint,
+            transportSecurity: 'https',
+            upstreamStatus: upstream.status,
+            fetchedAt,
+            data,
+            parsed,
+            attempt,
+        };
+    });
+}

package/lib/rdap-transport.mjs

@@ -0,0 +1,39 @@
+// Bounded RDAP HTTP transport. Bootstrap selection, response validation,
+// normalization, and registrar enrichment remain separate concerns in
+// lib/rdap.mts.
+import { readTextCapped, safeFetch, safeFetchDetailed } from "./safe-fetch.mjs";
+const MAX_RDAP_BYTES = 2000000;
+async function fetchRdapWithTimeout(url, options, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await safeFetch(url, { ...options, signal: controller.signal });
+        const { text, truncated } = await readTextCapped(response, MAX_RDAP_BYTES);
+        if (truncated)
+            throw new Error(`Response from ${url} exceeded ${MAX_RDAP_BYTES} bytes`);
+        return { status: response.status, ok: response.ok, text };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function fetchRdapDetailedWithTimeout(url, options, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const result = await safeFetchDetailed(url, { ...options, signal: controller.signal });
+        const { text, truncated } = await readTextCapped(result.response, MAX_RDAP_BYTES);
+        if (truncated)
+            throw new Error(`Response from ${url} exceeded ${MAX_RDAP_BYTES} bytes`);
+        return {
+            status: result.response.status,
+            ok: result.response.ok,
+            text,
+            finalUrl: result.finalUrl,
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export { fetchRdapDetailedWithTimeout, fetchRdapWithTimeout, };

package/lib/rdap-types.mjs

@@ -0,0 +1 @@
+export {};

package/lib/rdap-validation.mjs

@@ -0,0 +1,94 @@
+import net from 'node:net';
+import { domainToASCII } from 'node:url';
+import { ipv4ToLong, ipv6ToBigInt } from "./rdap-bootstrap.mjs";
+export function canonicalRdapDomain(value) {
+    if (typeof value !== 'string')
+        return null;
+    const ascii = domainToASCII(value.trim().replace(/\.+$/, ''));
+    return ascii ? ascii.toLowerCase() : null;
+}
+function ipv6ToComparableBigInt(ip) {
+    let normalized = ip;
+    if (ip.includes('.')) {
+        const lastColon = ip.lastIndexOf(':');
+        const embedded = ip.slice(lastColon + 1);
+        if (net.isIP(embedded) !== 4)
+            return null;
+        const value = ipv4ToLong(embedded);
+        normalized = `${ip.slice(0, lastColon)}:${(value >>> 16).toString(16)}:${(value & 0xffff).toString(16)}`;
+    }
+    try {
+        return ipv6ToBigInt(normalized);
+    }
+    catch {
+        return null;
+    }
+}
+export function validateRdapResponse(type, requestedValue, parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { valid: false, detail: 'The response did not contain a usable RDAP object.' };
+    }
+    const expectedClass = type === 'domain' ? 'domain' : type === 'asn' ? 'autnum' : 'ip network';
+    if (parsed.objectClassName && parsed.objectClassName !== expectedClass) {
+        return {
+            valid: false,
+            detail: `Expected object class ${expectedClass}, received ${parsed.objectClassName}.`,
+        };
+    }
+    if (type === 'domain') {
+        if (!('domain' in parsed)) {
+            return { valid: false, detail: 'The response did not contain a domain RDAP object.' };
+        }
+        const requested = canonicalRdapDomain(requestedValue);
+        const returned = canonicalRdapDomain(parsed.domain);
+        if (!requested || !returned || requested !== returned) {
+            return { valid: false, detail: 'The response domain did not match the requested domain.' };
+        }
+        return { valid: true, detail: null };
+    }
+    if (type === 'asn') {
+        if (!('startAutnum' in parsed)) {
+            return { valid: false, detail: 'The response did not contain an autnum RDAP object.' };
+        }
+        const requested = Number(String(requestedValue).replace(/^AS/i, ''));
+        const startAutnum = parsed.startAutnum;
+        const endAutnum = parsed.endAutnum;
+        if (!Number.isSafeInteger(requested) ||
+            typeof startAutnum !== 'number' ||
+            !Number.isSafeInteger(startAutnum) ||
+            typeof endAutnum !== 'number' ||
+            !Number.isSafeInteger(endAutnum) ||
+            startAutnum > endAutnum ||
+            requested < startAutnum ||
+            requested > endAutnum) {
+            return { valid: false, detail: 'The response AS range did not cover the requested ASN.' };
+        }
+        return { valid: true, detail: null };
+    }
+    if (!('startAddress' in parsed)) {
+        return { valid: false, detail: 'The response did not contain an IP network RDAP object.' };
+    }
+    const version = type === 'ipv4' ? 4 : 6;
+    const startAddress = parsed.startAddress;
+    const endAddress = parsed.endAddress;
+    if (net.isIP(requestedValue) !== version ||
+        typeof startAddress !== 'string' ||
+        net.isIP(startAddress) !== version ||
+        typeof endAddress !== 'string' ||
+        net.isIP(endAddress) !== version) {
+        return { valid: false, detail: 'The response did not contain a compatible IP range.' };
+    }
+    const convert = version === 4 ? ipv4ToLong : ipv6ToComparableBigInt;
+    const requested = convert(requestedValue);
+    const start = convert(startAddress);
+    const end = convert(endAddress);
+    if (requested === null ||
+        start === null ||
+        end === null ||
+        start > end ||
+        requested < start ||
+        requested > end) {
+        return { valid: false, detail: 'The response IP range did not cover the requested address.' };
+    }
+    return { valid: true, detail: null };
+}

package/lib/rdap.mjs

@@ -0,0 +1,16 @@
+// Public RDAP facade shared by the Express server and Netlify Functions.
+import { BOOTSTRAP_STALE_TTL_MS, BOOTSTRAP_TTL_MS, clearRdapBootstrapCache, fetchBootstrap, uniqueRdapBases as uniqueBases, } from "./rdap-bootstrap.mjs";
+import { fetchRdapFromBasesWithParser, fetchRdapRecordWithParser, } from "./rdap-client.mjs";
+import { normalizeRdapEvents, parseRdap, summarizeLifecycle, } from "./rdap-normalization.mjs";
+import { fetchRegistrarRdapRecordWithParser, selectRegistrarRdapLink, } from "./rdap-registrar.mjs";
+import { fetchRdapWithTimeout, } from "./rdap-transport.mjs";
+async function fetchRdapFromBases(type, value, bases, fetchUpstream = fetchRdapWithTimeout) {
+    return fetchRdapFromBasesWithParser(type, value, bases, parseRdap, fetchUpstream);
+}
+async function fetchRdapRecord(type, value) {
+    return fetchRdapRecordWithParser(type, value, parseRdap);
+}
+async function fetchRegistrarRdapRecord(domain, registryRecord, options = {}) {
+    return fetchRegistrarRdapRecordWithParser(domain, registryRecord, parseRdap, options);
+}
+export { BOOTSTRAP_TTL_MS, BOOTSTRAP_STALE_TTL_MS, fetchBootstrap, clearRdapBootstrapCache, fetchRdapRecord, fetchRdapFromBases, fetchRegistrarRdapRecord, selectRegistrarRdapLink, uniqueBases, parseRdap, normalizeRdapEvents, summarizeLifecycle, };

package/lib/registry-access.mjs

@@ -0,0 +1,32 @@
+const REGISTRY_ACCESS_PROFILE_LABELS = Object.freeze({
+    'iana-bootstrap': 'IANA bootstrap discovery',
+    'iana-referral': 'IANA referral discovery',
+    'no-iana-service': 'No service published by IANA',
+    'registry-policy-restricted': 'Registry policy restricted',
+    'source-ip-authorization-required': 'Source-IP authorization required',
+});
+const WHOIS_REGISTRY_ACCESS_PROFILES = new Set([
+    'iana-referral',
+    'no-iana-service',
+    'registry-policy-restricted',
+    'source-ip-authorization-required',
+]);
+const RDAP_REGISTRY_ACCESS_PROFILES = new Set([
+    'iana-bootstrap',
+    'no-iana-service',
+]);
+function isRegistryAccessProfile(value) {
+    return typeof value === 'string' && Object.hasOwn(REGISTRY_ACCESS_PROFILE_LABELS, value);
+}
+function isWhoisRegistryAccessProfile(value) {
+    return typeof value === 'string' && WHOIS_REGISTRY_ACCESS_PROFILES.has(value);
+}
+function isRdapRegistryAccessProfile(value) {
+    return typeof value === 'string' && RDAP_REGISTRY_ACCESS_PROFILES.has(value);
+}
+function registryAccessProfileLabel(value) {
+    return isRegistryAccessProfile(value)
+        ? REGISTRY_ACCESS_PROFILE_LABELS[value] ?? 'Unknown'
+        : 'Unknown';
+}
+export { isRdapRegistryAccessProfile, isWhoisRegistryAccessProfile, registryAccessProfileLabel, };

package/lib/registry-capabilities.mjs

@@ -0,0 +1,117 @@
+// Registry capability evaluation over the immutable reviewed catalogue.
+import { CAPABILITY_BY_SUFFIX, DEFAULT_CAPABILITY, EXPLICIT_CAPABILITIES, MAX_CAPABILITY_INPUT_LENGTH, REGISTRY_CAPABILITIES_VERSION, REGISTRY_STANDARDS_COVERAGE_SNAPSHOT, VERSION_26_NO_RDAP_SUFFIXES, VERSION_27_RDAP_ONLY_GENERIC_SUFFIXES, } from "./registry-capability-catalogue.mjs";
+const IANA_TLD_RECORD_PREFIX = 'https://www.iana.org/domains/root/db/';
+function documentationUrlsForSuffix(capability, suffixes) {
+    if (suffixes.length !== 1 || capability.suffixes.length <= 1) {
+        return [...capability.documentationUrls];
+    }
+    const suffix = suffixes[0];
+    const matchingIanaRecord = suffix ? `${IANA_TLD_RECORD_PREFIX}${suffix}.html` : '';
+    return capability.documentationUrls.filter((url) => (!url.startsWith(IANA_TLD_RECORD_PREFIX) || url === matchingIanaRecord));
+}
+function cloneCapability(capability, { suffixes = capability.suffixes } = {}) {
+    return {
+        ...capability,
+        suffixes: [...suffixes],
+        fixtureScenarios: [...capability.fixtureScenarios],
+        verificationFiles: [...capability.verificationFiles],
+        documentationUrls: documentationUrlsForSuffix(capability, suffixes),
+    };
+}
+function canonicalSuffix(value) {
+    if (typeof value !== 'string' ||
+        value.length > MAX_CAPABILITY_INPUT_LENGTH ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        return null;
+    }
+    let trimmed = value.trim();
+    if (trimmed.startsWith('.'))
+        trimmed = trimmed.slice(1);
+    if (trimmed.endsWith('.'))
+        trimmed = trimmed.slice(0, -1);
+    if (trimmed.startsWith('.') || trimmed.endsWith('.'))
+        return null;
+    if (!trimmed || /[\s\\/%@:?#]/u.test(trimmed))
+        return null;
+    let ascii = '';
+    try {
+        const parsed = new URL(`http://${trimmed}`);
+        if (parsed.username ||
+            parsed.password ||
+            parsed.port ||
+            parsed.pathname !== '/' ||
+            parsed.search ||
+            parsed.hash) {
+            return null;
+        }
+        ascii = parsed.hostname;
+    }
+    catch {
+        return null;
+    }
+    if (!ascii || ascii.length > MAX_CAPABILITY_INPUT_LENGTH)
+        return null;
+    const labels = ascii.toLowerCase().split('.');
+    if (labels.some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))) {
+        return null;
+    }
+    const suffix = labels.at(-1) || null;
+    return suffix && /[a-z]/.test(suffix) ? suffix : null;
+}
+function registryCapabilityFor(value) {
+    const suffix = canonicalSuffix(value);
+    if (!suffix)
+        return null;
+    const capability = CAPABILITY_BY_SUFFIX.get(suffix);
+    if (capability) {
+        return {
+            ...cloneCapability(capability, { suffixes: [suffix] }),
+            explicitSuffixProfile: true,
+        };
+    }
+    return {
+        ...cloneCapability(DEFAULT_CAPABILITY, { suffixes: [suffix] }),
+        explicitSuffixProfile: false,
+    };
+}
+function registryAccessDiagnosticFor(value) {
+    const capability = registryCapabilityFor(value);
+    if (!capability ||
+        (capability.whoisAccessProfile === 'iana-referral' &&
+            capability.rdapAccessProfile === 'iana-bootstrap')) {
+        return null;
+    }
+    return {
+        suffix: capability.suffixes[0],
+        coverageState: capability.coverageState,
+        whoisAccessProfile: capability.whoisAccessProfile,
+        rdapAccessProfile: capability.rdapAccessProfile,
+        limitation: capability.limitation,
+        authority: 'context_only',
+    };
+}
+function listRegistryCapabilities() {
+    return EXPLICIT_CAPABILITIES.map((capability) => cloneCapability(capability));
+}
+function registryStandardsCoverageSnapshot() {
+    return {
+        ...REGISTRY_STANDARDS_COVERAGE_SNAPSHOT,
+        sources: {
+            ...REGISTRY_STANDARDS_COVERAGE_SNAPSHOT.sources,
+            urls: [...REGISTRY_STANDARDS_COVERAGE_SNAPSHOT.sources.urls],
+        },
+        counts: { ...REGISTRY_STANDARDS_COVERAGE_SNAPSHOT.counts },
+        exceptions: REGISTRY_STANDARDS_COVERAGE_SNAPSHOT.exceptions.map((entry) => ({
+            ...entry,
+        })),
+    };
+}
+function registryCompatibilityMatrix() {
+    return listRegistryCapabilities()
+        .flatMap((capability) => capability.suffixes.map((suffix) => ({
+        ...cloneCapability(capability, { suffixes: [suffix] }),
+        explicitSuffixProfile: true,
+    })))
+        .sort((left, right) => (left.suffixes[0] ?? '').localeCompare(right.suffixes[0] ?? ''));
+}
+export { REGISTRY_CAPABILITIES_VERSION, VERSION_26_NO_RDAP_SUFFIXES, VERSION_27_RDAP_ONLY_GENERIC_SUFFIXES, registryCapabilityFor, registryCompatibilityMatrix, listRegistryCapabilities, registryAccessDiagnosticFor, registryStandardsCoverageSnapshot, };