@slicedearth/whoisleuth-cli 1.32.0

package/lib/rdap-capabilities.mjs

@@ -0,0 +1,292 @@
+// Bounded interpretation of RDAP conformance declarations already present in
+// a normalized response. This module performs no help request or reverse
+// search and does not treat an absent extension declaration as proof that a
+// server cannot support the related operation.
+export const RDAP_CAPABILITY_INSPECTION_VERSION = 1;
+export const RDAP_EXTENSION_CATALOG_REVIEWED_AT = '2026-07-31';
+export const MAX_RDAP_CAPABILITY_DECLARATIONS = 50;
+export const MAX_RDAP_UNKNOWN_CAPABILITIES = 20;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/u;
+// Reviewed against the protocol registry on 2026-07-31. The registry-drift
+// audit owns freshness checks; runtime lookup behavior never depends on this
+// catalogue being exhaustive.
+const EXTENSION_CATALOG = Object.freeze({
+    rdap_level_0: {
+        label: 'Core RDAP response',
+        category: 'core',
+        capability: 'Baseline lookup response conformance.',
+    },
+    arin_originas0: {
+        label: 'Origin AS extension',
+        category: 'operator',
+        capability: 'Operator-specific origin autonomous-system data.',
+    },
+    artrecord: {
+        label: 'Registry record extension',
+        category: 'operator',
+        capability: 'Operator-specific registry record data.',
+    },
+    autnums: {
+        label: 'Autonomous-system search resource',
+        category: 'standard',
+        capability: 'Autonomous-system search path support declaration.',
+    },
+    autnumsearchresults: {
+        label: 'Autonomous-system search results',
+        category: 'standard',
+        capability: 'Autonomous-system search result container declaration.',
+    },
+    cidr0: {
+        label: 'CIDR network extension',
+        category: 'standard',
+        capability: 'CIDR prefix representation in network responses.',
+    },
+    farv1: {
+        label: 'Federated authentication',
+        category: 'standard',
+        capability: 'Federated authorization profile declaration.',
+    },
+    fred: {
+        label: 'Registry-system extension',
+        category: 'operator',
+        capability: 'Operator-specific registry-system fields.',
+    },
+    geofeed1: {
+        label: 'Geofeed extension',
+        category: 'standard',
+        capability: 'Geofeed publication through RDAP.',
+    },
+    icann_rdap_response_profile_0: {
+        label: 'Response profile 0',
+        category: 'profile',
+        status: 'obsolete',
+        capability: 'Obsolete generic-domain response profile declaration.',
+    },
+    icann_rdap_response_profile_1: {
+        label: 'Response profile 1',
+        category: 'profile',
+        capability: 'Generic-domain response profile declaration.',
+    },
+    icann_rdap_technical_implementation_guide_0: {
+        label: 'Implementation guide 0',
+        category: 'profile',
+        status: 'obsolete',
+        capability: 'Obsolete generic-domain implementation profile declaration.',
+    },
+    icann_rdap_technical_implementation_guide_1: {
+        label: 'Implementation guide 1',
+        category: 'profile',
+        capability: 'Generic-domain technical implementation profile declaration.',
+    },
+    ips: {
+        label: 'IP network search resource',
+        category: 'standard',
+        capability: 'IP network search path support declaration.',
+    },
+    ipsearchresults: {
+        label: 'IP network search results',
+        category: 'standard',
+        capability: 'IP network search result container declaration.',
+    },
+    nask: {
+        label: 'Registry response extension',
+        category: 'operator',
+        capability: 'Operator-specific registry response fields.',
+    },
+    nro_rdap_profile_0: {
+        label: 'Address-registry response profile',
+        category: 'profile',
+        capability: 'Regional address-registry response profile declaration.',
+    },
+    nro_rdap_profile_asn_flat_0: {
+        label: 'Flat ASN profile',
+        category: 'profile',
+        capability: 'Flat autonomous-system hierarchy profile declaration.',
+    },
+    nro_rdap_profile_asn_hierarchical_0: {
+        label: 'Hierarchical ASN profile',
+        category: 'profile',
+        capability: 'Hierarchical autonomous-system profile declaration.',
+    },
+    paging: {
+        label: 'Result paging',
+        category: 'standard',
+        capability: 'Paged search-result behavior.',
+    },
+    platformns: {
+        label: 'Nameserver platform extension',
+        category: 'operator',
+        capability: 'Operator-specific nameserver platform context.',
+    },
+    rdap_objecttag: {
+        label: 'Object tags',
+        category: 'standard',
+        capability: 'Structured entity identifiers for query bootstrapping.',
+    },
+    redacted: {
+        label: 'Redaction metadata',
+        category: 'standard',
+        capability: 'Machine-readable response redaction markers.',
+    },
+    redirect_with_content: {
+        label: 'Redirect with content',
+        category: 'operator',
+        capability: 'Operator-specific redirect response content.',
+    },
+    regtype: {
+        label: 'Registration type extension',
+        category: 'operator',
+        capability: 'Operator-specific registration-type context.',
+    },
+    reverse_search: {
+        label: 'Reverse search',
+        category: 'standard',
+        capability: 'Server advertises the reverse-search protocol extension.',
+    },
+    rirsearch1: {
+        label: 'Address-registry search',
+        category: 'standard',
+        capability: 'Versioned network and autonomous-system search behavior.',
+    },
+    sorting: {
+        label: 'Result sorting',
+        category: 'standard',
+        capability: 'Sorted search-result behavior.',
+    },
+    subsetting: {
+        label: 'Partial response',
+        category: 'standard',
+        capability: 'Field-subset response behavior.',
+    },
+    ttl0: {
+        label: 'DNS TTL extension',
+        category: 'standard',
+        capability: 'DNS time-to-live values in RDAP responses.',
+    },
+});
+export function reviewedRdapExtensionCatalog() {
+    return Object.entries(EXTENSION_CATALOG)
+        .filter(([, entry]) => entry.category !== 'core')
+        .map(([identifier, entry]) => Object.freeze({
+        identifier,
+        status: entry.status ?? 'current',
+    }))
+        .sort((left, right) => left.identifier.localeCompare(right.identifier));
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function identifier(value) {
+    if (typeof value !== 'string' || CONTROL_RE.test(value) || value.length > 160)
+        return '';
+    return value.trim().toLowerCase();
+}
+function sourceState(parsed, status) {
+    if (!parsed || !['success', 'complete', 'partial'].includes(typeof status === 'string' ? status : '')) {
+        return 'unavailable';
+    }
+    return status === 'partial'
+        || parsed.serverTruncated === true
+        || parsed.conformanceTruncated === true
+        ? 'partial'
+        : 'complete';
+}
+function reverseSearchCapability(state, declared) {
+    if (declared) {
+        return {
+            state: 'advertised',
+            execution: 'not_attempted',
+            helpDiscoveryRequired: true,
+            actionAvailable: false,
+            detail: 'This response advertises the reverse-search extension. The server help document must still be inspected before any property or query can be offered.',
+            limitations: [
+                'An extension declaration does not prove that this endpoint permits anonymous use, supports a particular property, or will return complete results.',
+                'No reverse-search request was made.',
+            ],
+        };
+    }
+    if (state === 'complete') {
+        return {
+            state: 'not_advertised',
+            execution: 'not_attempted',
+            helpDiscoveryRequired: true,
+            actionAvailable: false,
+            detail: 'This individual response did not advertise reverse search. A separate help response could still declare server-level support.',
+            limitations: [
+                'Absence from an individual response is not proof that the server does not support reverse search.',
+                'No help or reverse-search request was made.',
+            ],
+        };
+    }
+    return {
+        state: 'unknown',
+        execution: 'not_attempted',
+        helpDiscoveryRequired: true,
+        actionAvailable: false,
+        detail: 'The response was unavailable or incomplete, so reverse-search support cannot be assessed.',
+        limitations: [
+            'Missing or truncated conformance data is not evidence that reverse search is unsupported.',
+            'No help or reverse-search request was made.',
+        ],
+    };
+}
+export function inspectRdapCapabilities(parsedValue, status) {
+    const parsed = record(parsedValue);
+    const state = sourceState(parsed, status);
+    const rawDeclarations = Array.isArray(parsed?.conformance) ? parsed.conformance : [];
+    const unique = new Set();
+    for (const value of rawDeclarations.slice(0, MAX_RDAP_CAPABILITY_DECLARATIONS * 2)) {
+        const normalized = identifier(value);
+        if (normalized)
+            unique.add(normalized);
+        if (unique.size >= MAX_RDAP_CAPABILITY_DECLARATIONS)
+            break;
+    }
+    const declarations = [...unique].sort().map((value) => {
+        const entry = EXTENSION_CATALOG[value];
+        return entry
+            ? {
+                identifier: value,
+                label: entry.label,
+                category: entry.category,
+                registered: entry.category === 'core' ? null : true,
+                status: entry.status ?? 'current',
+                capability: entry.capability,
+            }
+            : {
+                identifier: value,
+                label: 'Unclassified declaration',
+                category: 'unknown',
+                registered: null,
+                status: 'unknown',
+                capability: 'The identifier is retained for analyst review but is not interpreted by this catalogue.',
+            };
+    });
+    const omittedDeclarations = Math.max(0, rawDeclarations.length - unique.size);
+    const unknownIdentifiers = declarations
+        .filter((entry) => entry.category === 'unknown')
+        .map((entry) => entry.identifier)
+        .slice(0, MAX_RDAP_UNKNOWN_CAPABILITIES);
+    const limitations = [
+        'Declarations describe what the server claims for this response; they do not prove that an operation is authorized, implemented correctly, complete, or available anonymously.',
+        'Unknown identifiers remain visible and neutral. Catalogue recognition never affects availability or Risk scoring.',
+    ];
+    if (state === 'unavailable') {
+        limitations.unshift('No usable RDAP publication was available for capability inspection.');
+    }
+    else if (state === 'partial' || omittedDeclarations > 0) {
+        limitations.unshift('The conformance declaration set was incomplete or locally capped.');
+    }
+    return {
+        version: RDAP_CAPABILITY_INSPECTION_VERSION,
+        catalogReviewedAt: RDAP_EXTENSION_CATALOG_REVIEWED_AT,
+        state,
+        declarations,
+        unknownIdentifiers,
+        omittedDeclarations,
+        reverseSearch: reverseSearchCapability(state, declarations.some((entry) => entry.identifier === 'reverse_search')),
+        limitations,
+    };
+}

package/lib/rdap-client.mjs

@@ -0,0 +1,125 @@
+import { cached } from "./lookup-cache.mjs";
+import { findRdapBases, uniqueRdapBases, } from "./rdap-bootstrap.mjs";
+import { rdapAttempt, rdapFailure } from "./rdap-attempts.mjs";
+import { fetchRdapWithTimeout, } from "./rdap-transport.mjs";
+import { validateRdapResponse } from "./rdap-validation.mjs";
+const UPSTREAM_TIMEOUT_MS = 7_000;
+const UPSTREAM_TOTAL_DEADLINE_MS = 12_000;
+const MAX_RDAP_ENDPOINTS = 3;
+function errorProperty(value, key) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value[key];
+}
+function rdapPathFor(type, value) {
+    if (type === 'domain')
+        return `domain/${value}`;
+    if (type === 'ipv4' || type === 'ipv6')
+        return `ip/${value}`;
+    if (type === 'asn')
+        return `autnum/${value.replace(/^AS/i, '')}`;
+    throw new Error(`Unsupported RDAP type: ${type}`);
+}
+/**
+ * Query the bounded bootstrap candidate set while retaining every attempted
+ * endpoint as separately attributed transport evidence.
+ */
+export async function fetchRdapFromBasesWithParser(type, value, bases, parseRdap, fetchUpstream = fetchRdapWithTimeout) {
+    const candidates = uniqueRdapBases(bases).slice(0, MAX_RDAP_ENDPOINTS);
+    if (candidates.length === 0)
+        return null;
+    const startedAt = Date.now();
+    const attempts = [];
+    for (const base of candidates) {
+        const elapsed = Date.now() - startedAt;
+        const remaining = UPSTREAM_TOTAL_DEADLINE_MS - elapsed;
+        if (remaining <= 0)
+            break;
+        const url = `${base.replace(/\/$/, '')}/${rdapPathFor(type, value)}`;
+        try {
+            const upstream = await fetchUpstream(url, { headers: { Accept: 'application/rdap+json' } }, Math.min(UPSTREAM_TIMEOUT_MS, remaining));
+            if (upstream.status !== 404 && !upstream.ok) {
+                const outcome = upstream.status === 429
+                    ? 'rate_limited'
+                    : upstream.status >= 500
+                        ? 'server_error'
+                        : 'client_error';
+                attempts.push(rdapAttempt(url, outcome, {
+                    status: upstream.status,
+                    detail: `The endpoint returned HTTP ${upstream.status}.`,
+                }));
+                continue;
+            }
+            let data;
+            try {
+                data = JSON.parse(upstream.text);
+            }
+            catch {
+                attempts.push(rdapAttempt(url, 'invalid_json', {
+                    status: upstream.status,
+                    detail: 'The endpoint returned invalid JSON.',
+                }));
+                continue;
+            }
+            if (upstream.status === 404) {
+                attempts.push(rdapAttempt(url, 'not_found', {
+                    status: upstream.status,
+                    detail: 'The authoritative endpoint reported no matching object.',
+                    selected: true,
+                }));
+                return {
+                    rdapServer: url,
+                    transportSecurity: /^https:\/\//i.test(url) ? 'https' : 'http',
+                    upstreamStatus: upstream.status,
+                    fetchedAt: new Date().toISOString(),
+                    data,
+                    parsed: null,
+                    attempts,
+                };
+            }
+            const parsed = parseRdap(type, data);
+            const validation = validateRdapResponse(type, value, parsed);
+            if (!validation.valid) {
+                attempts.push(rdapAttempt(url, 'invalid_response', {
+                    status: upstream.status,
+                    detail: validation.detail,
+                }));
+                continue;
+            }
+            attempts.push(rdapAttempt(url, 'success', {
+                status: upstream.status,
+                detail: 'The endpoint returned the requested RDAP object.',
+                selected: true,
+            }));
+            return {
+                rdapServer: url,
+                transportSecurity: /^https:\/\//i.test(url) ? 'https' : 'http',
+                upstreamStatus: upstream.status,
+                fetchedAt: new Date().toISOString(),
+                data,
+                parsed,
+                attempts,
+            };
+        }
+        catch (cause) {
+            const detail = String(errorProperty(cause, 'message') || 'request failed');
+            const outcome = errorProperty(cause, 'name') === 'AbortError' ||
+                /timed? out|time limit/i.test(detail)
+                ? 'timeout'
+                : 'network_error';
+            attempts.push(rdapAttempt(url, outcome, { detail }));
+        }
+    }
+    const detail = attempts.length
+        ? attempts
+            .map((attempt) => `${attempt.endpoint} ${rdapFailure(attempt.outcome, attempt.status)}`)
+            .join('; ')
+        : 'the total upstream deadline expired';
+    throw Object.assign(new Error(`RDAP lookup failed across ${candidates.length} endpoint(s): ${detail}`), { attempts });
+}
+export async function fetchRdapRecordWithParser(type, value, parseRdap) {
+    return cached(`rdap:${type}:${value}`, async () => {
+        const bases = await findRdapBases(type, value);
+        return fetchRdapFromBasesWithParser(type, value, bases, parseRdap);
+    });
+}