whois_domain

Instructions

Implementation Reference

• src/whois/index.ts:33-101 (handler)

  Main handler function for 'whois_domain' tool. Calls the RDAP API (rdap.org/domain/{domain}), parses the JSON response, and extracts nameservers, entities (registrar, contacts with vcard data), registration/expiration/last-updated dates, and returns a structured RdapDomainResult.

  export async function whoisDomain(domain: string): Promise<RdapDomainResult> {
    await limiter.acquire();
    const res = await fetch(`https://rdap.org/domain/${domain}`);
    if (!res.ok) throw new Error(`RDAP domain lookup failed: ${res.status} ${res.statusText}`);
    const data = await res.json();
  
    const nameservers: string[] = [];
    if (data.nameservers) {
      for (const ns of data.nameservers) {
        if (ns.ldhName) nameservers.push(ns.ldhName);
      }
    }
  
    const entities: RdapDomainResult["entities"] = [];
    if (data.entities) {
      for (const ent of data.entities) {
        const roles = ent.roles ?? [];
        const vcard = ent.vcardArray?.[1];
        let name: string | undefined;
        let email: string | undefined;
        let phone: string | undefined;
  
        if (vcard) {
          for (const field of vcard) {
            if (field[0] === "fn") name = field[3];
            if (field[0] === "email") email = field[3];
            if (field[0] === "tel") phone = field[3];
          }
        }
  
        for (const role of roles) {
          entities.push({ role, name, email, phone });
        }
      }
    }
  
    // Extract dates from events
    let registrationDate: string | undefined;
    let expirationDate: string | undefined;
    let lastUpdated: string | undefined;
  
    if (data.events) {
      for (const evt of data.events) {
        if (evt.eventAction === "registration") registrationDate = evt.eventDate;
        if (evt.eventAction === "expiration") expirationDate = evt.eventDate;
        if (evt.eventAction === "last changed") lastUpdated = evt.eventDate;
      }
    }
  
    // Extract registrar from entities
    let registrar: string | undefined;
    const registrarEntity = data.entities?.find((e: any) => e.roles?.includes("registrar"));
    if (registrarEntity?.vcardArray?.[1]) {
      const fn = registrarEntity.vcardArray[1].find((f: any) => f[0] === "fn");
      if (fn) registrar = fn[3];
    }
  
    return {
      domain: data.ldhName ?? domain,
      status: data.status ?? [],
      registrar,
      registrationDate,
      expirationDate,
      lastUpdated,
      nameservers,
      entities,
      port43: data.port43,
    };
  }

• src/whois/index.ts:7-17 (schema)

  Type definition for the result returned by whoisDomain, defining the shape of RDAP domain lookup response (domain, status, registrar, dates, nameservers, entities/contacts, port43).

  interface RdapDomainResult {
    domain: string;
    status: string[];
    registrar?: string;
    registrationDate?: string;
    expirationDate?: string;
    lastUpdated?: string;
    nameservers: string[];
    entities: { role: string; name?: string; email?: string; phone?: string }[];
    port43?: string;
  }

• src/protocol/tools.ts:90-97 (registration)

  Tool registration definition for 'whois_domain'. Defines name, description, Zod schema (expects 'domain' string), and execute handler that calls whoisDomain() from src/whois/index.ts.

  const whoisDomainTool: ToolDef = {
    name: "whois_domain",
    description: "RDAP/WHOIS lookup for a domain. Returns registrar, registration/expiration dates, nameservers, and contact entities.",
    schema: {
      domain: z.string().describe("Domain name to look up"),
    },
    execute: async (args) => json(await whoisDomain(args.domain as string)),
  };

• src/protocol/tools.ts:490-491 (registration)

  Registration of whoisDomainTool in the tool list (array exported for inclusion in the tool registry).

  whoisDomainTool,
  whoisIpTool,

• src/whois/index.ts:1-3 (helper)

  Rate limiter used by whoisDomain (and whoisIp) to ensure requests are spaced at least 1000ms apart.

  import { RateLimiter } from "../utils/rate-limiter.js";
  
  const limiter = new RateLimiter(1000);

• src/index.ts:28-28 (registration)

  Tool category listing for '--list' display, grouping whois_domain under 'WHOIS / RDAP' category.

  { label: "WHOIS / RDAP", env: null, tools: ["whois_domain", "whois_ip"] },