rdapper 0.1.0

package/dist/rdap/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { DomainRecord } from "../types.js";
+/**
+ * Convert RDAP JSON into our normalized DomainRecord.
+ * This function is defensive: RDAP servers vary in completeness and field naming.
+ */
+export declare function normalizeRdap(inputDomain: string, tld: string, rdap: unknown, rdapServersTried: string[], fetchedAtISO: string, includeRaw?: boolean): DomainRecord;

package/dist/rdap/normalize.js

@@ -0,0 +1,214 @@
+import { toISO } from "../lib/dates.js";
+import { asDateLike, asString, asStringArray, uniq } from "../lib/text.js";
+/**
+ * Convert RDAP JSON into our normalized DomainRecord.
+ * This function is defensive: RDAP servers vary in completeness and field naming.
+ */
+export function normalizeRdap(inputDomain, tld, rdap, rdapServersTried, fetchedAtISO, includeRaw = false) {
+    const doc = (rdap ?? {});
+    // Safe helpers for optional fields
+    const _get = (obj, path) => path.reduce((o, k) => o?.[k] ?? undefined, obj);
+    // Prefer ldhName (punycode) and unicodeName if provided
+    const ldhName = asString(doc.ldhName) || asString(doc.handle);
+    const unicodeName = asString(doc.unicodeName);
+    // Registrar entity can be provided with role "registrar"
+    const registrar = extractRegistrar(doc.entities);
+    // Nameservers: normalize host + IPs
+    const nameservers = Array.isArray(doc.nameservers)
+        ? doc.nameservers
+            .map((ns) => {
+            const host = (asString(ns.ldhName) ??
+                asString(ns.unicodeName) ??
+                "").toLowerCase();
+            const ip = ns.ipAddresses;
+            const ipv4 = asStringArray(ip?.v4);
+            const ipv6 = asStringArray(ip?.v6);
+            const n = { host };
+            if (ipv4?.length)
+                n.ipv4 = ipv4;
+            if (ipv6?.length)
+                n.ipv6 = ipv6;
+            return n;
+        })
+            .filter((n) => !!n.host)
+        : undefined;
+    // Contacts: RDAP entities include roles like registrant, administrative, technical, billing, abuse
+    const contacts = extractContacts(doc.entities);
+    // RDAP uses IANA EPP status values. Preserve raw plus a description if any remarks are present.
+    const statuses = Array.isArray(doc.status)
+        ? doc.status
+            .filter((s) => typeof s === "string")
+            .map((s) => ({ status: s, raw: s }))
+        : undefined;
+    // Secure DNS info
+    const secureDNS = doc.secureDNS;
+    const dnssec = secureDNS
+        ? {
+            enabled: !!secureDNS.delegationSigned,
+            dsRecords: Array.isArray(secureDNS.dsData)
+                ? secureDNS.dsData.map((d) => ({
+                    keyTag: d.keyTag,
+                    algorithm: d.algorithm,
+                    digestType: d.digestType,
+                    digest: d.digest,
+                }))
+                : undefined,
+        }
+        : undefined;
+    const events = Array.isArray(doc.events)
+        ? doc.events
+        : [];
+    const byAction = (action) => events.find((e) => typeof e?.eventAction === "string" &&
+        e.eventAction.toLowerCase().includes(action));
+    const creationDate = toISO(asDateLike(byAction("registration")?.eventDate) ??
+        asDateLike(doc.registrationDate));
+    const updatedDate = toISO(asDateLike(byAction("last changed")?.eventDate) ??
+        asDateLike(doc.lastChangedDate));
+    const expirationDate = toISO(asDateLike(byAction("expiration")?.eventDate) ??
+        asDateLike(doc.expirationDate));
+    const deletionDate = toISO(asDateLike(byAction("deletion")?.eventDate) ?? asDateLike(doc.deletionDate));
+    // Derive a simple transfer lock flag from statuses
+    const transferLock = !!statuses?.some((s) => /transferprohibited/i.test(s.status));
+    // The RDAP document may include "port43" pointer to authoritative WHOIS
+    const whoisServer = asString(doc.port43);
+    const record = {
+        domain: unicodeName || ldhName || inputDomain,
+        tld,
+        isRegistered: true,
+        isIDN: /(^|\.)xn--/i.test(ldhName || inputDomain),
+        unicodeName: unicodeName || undefined,
+        punycodeName: ldhName || undefined,
+        registry: undefined, // RDAP rarely includes a clean registry operator name
+        registrar: registrar,
+        reseller: undefined,
+        statuses: statuses,
+        creationDate,
+        updatedDate,
+        expirationDate,
+        deletionDate,
+        transferLock,
+        dnssec,
+        nameservers: nameservers
+            ? uniq(nameservers.map((n) => ({ ...n, host: n.host.toLowerCase() })))
+            : undefined,
+        contacts,
+        whoisServer,
+        rdapServers: rdapServersTried,
+        rawRdap: includeRaw ? rdap : undefined,
+        rawWhois: undefined,
+        source: "rdap",
+        fetchedAt: fetchedAtISO,
+        warnings: undefined,
+    };
+    return record;
+}
+function extractRegistrar(entities) {
+    if (!Array.isArray(entities))
+        return undefined;
+    for (const ent of entities) {
+        const roles = Array.isArray(ent?.roles)
+            ? ent.roles.filter((r) => typeof r === "string")
+            : [];
+        if (!roles.some((r) => /registrar/i.test(r)))
+            continue;
+        const v = parseVcard(ent?.vcardArray);
+        const ianaId = Array.isArray(ent?.publicIds)
+            ? ent.publicIds.find((id) => /iana\s*registrar\s*id/i.test(String(id?.type)))?.identifier
+            : undefined;
+        return {
+            name: v.fn || v.org || asString(ent?.handle) || undefined,
+            ianaId: asString(ianaId),
+            url: v.url ?? undefined,
+            email: v.email ?? undefined,
+            phone: v.tel ?? undefined,
+        };
+    }
+    return undefined;
+}
+function extractContacts(entities) {
+    if (!Array.isArray(entities))
+        return undefined;
+    const out = [];
+    for (const ent of entities) {
+        const roles = Array.isArray(ent?.roles)
+            ? ent.roles.filter((r) => typeof r === "string")
+            : [];
+        const v = parseVcard(ent?.vcardArray);
+        const type = roles.find((r) => /registrant|administrative|technical|billing|abuse|reseller/i.test(r));
+        if (!type)
+            continue;
+        const map = {
+            registrant: "registrant",
+            administrative: "admin",
+            technical: "tech",
+            billing: "billing",
+            abuse: "abuse",
+            reseller: "reseller",
+        };
+        const roleKey = (map[type.toLowerCase()] ?? "unknown");
+        out.push({
+            type: roleKey,
+            name: v.fn,
+            organization: v.org,
+            email: v.email,
+            phone: v.tel,
+            fax: v.fax,
+            street: v.street,
+            city: v.locality,
+            state: v.region,
+            postalCode: v.postcode,
+            country: v.country,
+            countryCode: v.countryCode,
+        });
+    }
+    return out.length ? out : undefined;
+}
+// Parse a minimal subset of vCard 4.0 arrays as used in RDAP "vcardArray" fields
+function parseVcard(vcardArray) {
+    // vcardArray is typically ["vcard", [["version",{} ,"text","4.0"], ["fn",{} ,"text","Example"], ...]]
+    if (!Array.isArray(vcardArray) ||
+        vcardArray[0] !== "vcard" ||
+        !Array.isArray(vcardArray[1]))
+        return {};
+    const entries = vcardArray[1];
+    const out = {};
+    for (const e of entries) {
+        const key = e?.[0];
+        const _valueType = e?.[2];
+        const value = e?.[3];
+        if (!key)
+            continue;
+        switch (String(key).toLowerCase()) {
+            case "fn":
+                out.fn = asString(value);
+                break;
+            case "org":
+                out.org = Array.isArray(value)
+                    ? value.map((x) => String(x)).join(" ")
+                    : asString(value);
+                break;
+            case "email":
+                out.email = asString(value);
+                break;
+            case "tel":
+                out.tel = asString(value);
+                break;
+            case "url":
+                out.url = asString(value);
+                break;
+            case "adr": {
+                // adr value is [postOfficeBox, extendedAddress, street, locality, region, postalCode, country]
+                if (Array.isArray(value)) {
+                    out.street = value[2] ? String(value[2]).split(/\n|,\s*/) : undefined;
+                    out.locality = asString(value[3]);
+                    out.region = asString(value[4]);
+                    out.postcode = asString(value[5]);
+                    out.country = asString(value[6]);
+                }
+                break;
+            }
+        }
+    }
+    // Best effort country code from country name (often omitted). Leaving undefined unless explicitly provided.
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+export type LookupSource = "rdap" | "whois";
+export interface RegistrarInfo {
+    name?: string;
+    ianaId?: string;
+    url?: string;
+    email?: string;
+    phone?: string;
+}
+export interface Contact {
+    type: "registrant" | "admin" | "tech" | "billing" | "abuse" | "registrar" | "reseller" | "unknown";
+    name?: string;
+    organization?: string;
+    email?: string | string[];
+    phone?: string | string[];
+    fax?: string | string[];
+    street?: string[];
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+    countryCode?: string;
+}
+export interface Nameserver {
+    host: string;
+    ipv4?: string[];
+    ipv6?: string[];
+}
+export interface StatusEvent {
+    status: string;
+    description?: string;
+    raw?: string;
+}
+export interface DomainRecord {
+    domain: string;
+    tld: string;
+    isRegistered: boolean;
+    isIDN?: boolean;
+    unicodeName?: string;
+    punycodeName?: string;
+    registry?: string;
+    registrar?: RegistrarInfo;
+    reseller?: string;
+    statuses?: StatusEvent[];
+    creationDate?: string;
+    updatedDate?: string;
+    expirationDate?: string;
+    deletionDate?: string;
+    transferLock?: boolean;
+    dnssec?: {
+        enabled: boolean;
+        dsRecords?: Array<{
+            keyTag?: number;
+            algorithm?: number;
+            digestType?: number;
+            digest?: string;
+        }>;
+    };
+    nameservers?: Nameserver[];
+    contacts?: Contact[];
+    whoisServer?: string;
+    rdapServers?: string[];
+    rawRdap?: unknown;
+    rawWhois?: string;
+    source: LookupSource;
+    fetchedAt: string;
+    warnings?: string[];
+}
+export interface LookupOptions {
+    timeoutMs?: number;
+    rdapOnly?: boolean;
+    whoisOnly?: boolean;
+    followWhoisReferral?: boolean;
+    customBootstrapUrl?: string;
+    whoisHints?: Record<string, string>;
+    includeRaw?: boolean;
+    signal?: AbortSignal;
+}
+export interface LookupResult {
+    ok: boolean;
+    record?: DomainRecord;
+    error?: string;
+}
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

package/dist/types.js

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

package/dist/whois/client.d.ts

@@ -0,0 +1,10 @@
+import type { LookupOptions } from "../types.js";
+export interface WhoisQueryResult {
+    serverQueried: string;
+    text: string;
+}
+/**
+ * Perform a WHOIS query against an RFC 3912 server over TCP 43.
+ * Returns the raw text and the server used.
+ */
+export declare function whoisQuery(server: string, query: string, options?: LookupOptions): Promise<WhoisQueryResult>;

package/dist/whois/client.js

@@ -0,0 +1,46 @@
+import { createConnection } from "node:net";
+import { withTimeout } from "../lib/async.js";
+import { DEFAULT_TIMEOUT_MS } from "../lib/constants.js";
+/**
+ * Perform a WHOIS query against an RFC 3912 server over TCP 43.
+ * Returns the raw text and the server used.
+ */
+export async function whoisQuery(server, query, options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const port = 43;
+    const host = server.replace(/^whois:\/\//i, "");
+    const text = await withTimeout(queryTcp(host, port, query, options), timeoutMs, "WHOIS timeout");
+    return { serverQueried: server, text };
+}
+// Low-level WHOIS TCP client. Some registries require CRLF after the domain query.
+function queryTcp(host, port, query, options) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection({ host, port });
+        let data = "";
+        let done = false;
+        const cleanup = () => {
+            if (done)
+                return;
+            done = true;
+            socket.destroy();
+        };
+        socket.setTimeout((options?.timeoutMs ?? DEFAULT_TIMEOUT_MS) - 1000, () => {
+            cleanup();
+            reject(new Error("WHOIS socket timeout"));
+        });
+        socket.on("error", (err) => {
+            cleanup();
+            reject(err);
+        });
+        socket.on("data", (chunk) => {
+            data += chunk.toString("utf8");
+        });
+        socket.on("end", () => {
+            cleanup();
+            resolve(data);
+        });
+        socket.on("connect", () => {
+            socket.write(`${query}\r\n`);
+        });
+    });
+}

package/dist/whois/discovery.d.ts

@@ -0,0 +1,9 @@
+import type { LookupOptions } from "../types.js";
+/**
+ * Best-effort discovery of the authoritative WHOIS server for a TLD via IANA root DB.
+ */
+export declare function ianaWhoisServerForTld(tld: string, options?: LookupOptions): Promise<string | undefined>;
+/**
+ * Extract registrar referral WHOIS server from a WHOIS response, if present.
+ */
+export declare function extractWhoisReferral(text: string): string | undefined;

package/dist/whois/discovery.js

@@ -0,0 +1,50 @@
+import { whoisQuery } from "./client.js";
+import { WHOIS_TLD_EXCEPTIONS } from "./servers.js";
+/**
+ * Best-effort discovery of the authoritative WHOIS server for a TLD via IANA root DB.
+ */
+export async function ianaWhoisServerForTld(tld, options) {
+    const key = tld.toLowerCase();
+    // 1) Explicit hint override
+    const hint = options?.whoisHints?.[key];
+    if (hint)
+        return normalizeServer(hint);
+    // 2) IANA WHOIS authoritative discovery over TCP 43
+    try {
+        const res = await whoisQuery("whois.iana.org", key, options);
+        const txt = res.text;
+        const m = txt.match(/^whois:\s*(\S+)/im) ||
+            txt.match(/^refer:\s*(\S+)/im) ||
+            txt.match(/^whois server:\s*(\S+)/im);
+        const server = m?.[1];
+        if (server)
+            return normalizeServer(server);
+    }
+    catch {
+        // fallthrough to exceptions/guess
+    }
+    // 3) Curated exceptions
+    const exception = WHOIS_TLD_EXCEPTIONS[key];
+    if (exception)
+        return normalizeServer(exception);
+    return undefined;
+}
+/**
+ * Extract registrar referral WHOIS server from a WHOIS response, if present.
+ */
+export function extractWhoisReferral(text) {
+    const patterns = [
+        /^Registrar WHOIS Server:\s*(.+)$/im,
+        /^Whois Server:\s*(.+)$/im,
+        /^ReferralServer:\s*whois:\/\/(.+)$/im,
+    ];
+    for (const re of patterns) {
+        const m = text.match(re);
+        if (m?.[1])
+            return m[1].trim();
+    }
+    return undefined;
+}
+function normalizeServer(server) {
+    return server.replace(/^whois:\/\//i, "").replace(/\/$/, "");
+}

package/dist/whois/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { DomainRecord } from "../types.js";
+/**
+ * Convert raw WHOIS text into our normalized DomainRecord.
+ * Heuristics cover many gTLD and ccTLD formats; exact fields vary per registry.
+ */
+export declare function normalizeWhois(domain: string, tld: string, whoisText: string, whoisServer: string | undefined, fetchedAtISO: string, includeRaw?: boolean): DomainRecord;

package/dist/whois/normalize.js

@@ -0,0 +1,214 @@
+import { toISO } from "../lib/dates.js";
+import { isWhoisAvailable } from "../lib/domain.js";
+import { parseKeyValueLines, uniq } from "../lib/text.js";
+/**
+ * Convert raw WHOIS text into our normalized DomainRecord.
+ * Heuristics cover many gTLD and ccTLD formats; exact fields vary per registry.
+ */
+export function normalizeWhois(domain, tld, whoisText, whoisServer, fetchedAtISO, includeRaw = false) {
+    const map = parseKeyValueLines(whoisText);
+    // Date extraction across common synonyms
+    const creationDate = anyValue(map, [
+        "creation date",
+        "created on",
+        "registered on",
+        "domain registration date",
+        "domain create date",
+        "created",
+        "registered",
+    ]);
+    const updatedDate = anyValue(map, [
+        "updated date",
+        "last updated",
+        "last modified",
+        "modified",
+    ]);
+    const expirationDate = anyValue(map, [
+        "registry expiry date",
+        "expiry date",
+        "expiration date",
+        "paid-till",
+        "expires on",
+        "renewal date",
+    ]);
+    // Registrar info (thin registries like .com/.net require referral follow for full data)
+    const registrar = (() => {
+        const name = anyValue(map, [
+            "registrar",
+            "sponsoring registrar",
+            "registrar name",
+        ]);
+        const ianaId = anyValue(map, ["registrar iana id", "iana id"]);
+        const url = anyValue(map, [
+            "registrar url",
+            "url of the registrar",
+            "referrer",
+        ]);
+        const abuseEmail = anyValue(map, [
+            "registrar abuse contact email",
+            "abuse contact email",
+        ]);
+        const abusePhone = anyValue(map, [
+            "registrar abuse contact phone",
+            "abuse contact phone",
+        ]);
+        if (!name && !ianaId && !url && !abuseEmail && !abusePhone)
+            return undefined;
+        return {
+            name: name || undefined,
+            ianaId: ianaId || undefined,
+            url: url || undefined,
+            email: abuseEmail || undefined,
+            phone: abusePhone || undefined,
+        };
+    })();
+    // Statuses: multiple entries are expected; keep raw
+    const statusLines = map["domain status"] || map.status || [];
+    const statuses = statusLines.length
+        ? statusLines.map((line) => ({ status: line.split(/\s+/)[0], raw: line }))
+        : undefined;
+    // Nameservers: also appear as "nserver" on some ccTLDs (.de, .ru) and as "name server"
+    const nsLines = [
+        ...(map["name server"] || []),
+        ...(map.nameserver || []),
+        ...(map["name servers"] || []),
+        ...(map.nserver || []),
+    ];
+    const nameservers = nsLines.length
+        ? uniq(nsLines
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => {
+            // Common formats: "ns1.example.com" or "ns1.example.com 192.0.2.1" or "ns1.example.com 2001:db8::1"
+            const parts = line.split(/\s+/);
+            const host = parts.shift()?.toLowerCase() || "";
+            const ipv4 = [];
+            const ipv6 = [];
+            for (const p of parts) {
+                if (/^\d+\.\d+\.\d+\.\d+$/.test(p))
+                    ipv4.push(p);
+                else if (/^[0-9a-f:]+$/i.test(p))
+                    ipv6.push(p);
+            }
+            if (!host)
+                return undefined;
+            const ns = { host };
+            if (ipv4.length)
+                ns.ipv4 = ipv4;
+            if (ipv6.length)
+                ns.ipv6 = ipv6;
+            return ns;
+        })
+            .filter((x) => !!x))
+        : undefined;
+    // Contacts: best-effort parse common keys
+    const contacts = collectContacts(map);
+    const dnssecRaw = (map.dnssec?.[0] || "").toLowerCase();
+    const dnssec = dnssecRaw
+        ? { enabled: /signed|yes|true/.test(dnssecRaw) }
+        : undefined;
+    // Simple lock derivation from statuses
+    const transferLock = !!statuses?.some((s) => /transferprohibited/i.test(s.status));
+    const record = {
+        domain,
+        tld,
+        isRegistered: !isWhoisAvailable(whoisText),
+        isIDN: /(^|\.)xn--/i.test(domain),
+        unicodeName: undefined,
+        punycodeName: undefined,
+        registry: undefined,
+        registrar,
+        reseller: anyValue(map, ["reseller"]) || undefined,
+        statuses,
+        creationDate: toISO(creationDate || undefined),
+        updatedDate: toISO(updatedDate || undefined),
+        expirationDate: toISO(expirationDate || undefined),
+        deletionDate: undefined,
+        transferLock,
+        dnssec,
+        nameservers,
+        contacts,
+        whoisServer,
+        rdapServers: undefined,
+        rawRdap: undefined,
+        rawWhois: includeRaw ? whoisText : undefined,
+        source: "whois",
+        fetchedAt: fetchedAtISO,
+        warnings: undefined,
+    };
+    return record;
+}
+function anyValue(map, keys) {
+    for (const k of keys) {
+        const v = map[k];
+        if (v?.length)
+            return v[0];
+    }
+    return undefined;
+}
+function collectContacts(map) {
+    const roles = [
+        { role: "registrant", prefix: "registrant" },
+        { role: "admin", prefix: "admin" },
+        { role: "tech", prefix: "tech" },
+        { role: "billing", prefix: "billing" },
+        { role: "abuse", prefix: "abuse" },
+    ];
+    const contacts = [];
+    for (const r of roles) {
+        const name = anyValue(map, [
+            `${r.prefix} name`,
+            `${r.prefix} contact name`,
+            `${r.prefix}`,
+        ]);
+        const org = anyValue(map, [`${r.prefix} organization`, `${r.prefix} org`]);
+        const email = anyValue(map, [
+            `${r.prefix} email`,
+            `${r.prefix} contact email`,
+            `${r.prefix} e-mail`,
+        ]);
+        const phone = anyValue(map, [
+            `${r.prefix} phone`,
+            `${r.prefix} contact phone`,
+            `${r.prefix} telephone`,
+        ]);
+        const fax = anyValue(map, [`${r.prefix} fax`, `${r.prefix} facsimile`]);
+        const street = multi(map, [`${r.prefix} street`, `${r.prefix} address`]);
+        const city = anyValue(map, [`${r.prefix} city`]);
+        const state = anyValue(map, [
+            `${r.prefix} state`,
+            `${r.prefix} province`,
+            `${r.prefix} state/province`,
+        ]);
+        const postalCode = anyValue(map, [
+            `${r.prefix} postal code`,
+            `${r.prefix} postcode`,
+            `${r.prefix} zip`,
+        ]);
+        const country = anyValue(map, [`${r.prefix} country`]);
+        if (name || org || email || phone || street?.length) {
+            contacts.push({
+                type: r.role,
+                name: name || undefined,
+                organization: org || undefined,
+                email: email || undefined,
+                phone: phone || undefined,
+                fax: fax || undefined,
+                street: street,
+                city: city || undefined,
+                state: state || undefined,
+                postalCode: postalCode || undefined,
+                country: country || undefined,
+            });
+        }
+    }
+    return contacts.length ? contacts : undefined;
+}
+function multi(map, keys) {
+    for (const k of keys) {
+        const v = map[k];
+        if (v?.length)
+            return v;
+    }
+    return undefined;
+}

package/dist/whois/servers.d.ts

@@ -0,0 +1 @@
+export declare const WHOIS_TLD_EXCEPTIONS: Record<string, string>;