dns2 2.0.5 → 2.2.1

package/ts/index.d.ts

@@ -0,0 +1,371 @@
+/// <reference types="node" />
+
+import * as dgram from 'node:dgram';
+import { EventEmitter } from 'node:events';
+import * as http from 'node:http';
+import * as net from 'node:net';
+
+// ─── Main DNS class ───────────────────────────────────────────────────────────
+
+declare class DNS extends EventEmitter {
+  constructor(options?: Partial<DNS.ClientOptions>);
+
+  resolve(
+    domain: string,
+    type?: string,
+    cls?: number,
+    options?: DNS.ResolveOptions,
+  ): Promise<DNS.Packet>;
+
+  resolveA(domain: string, clientIp?: string): Promise<DNS.Packet>;
+  resolveAAAA(domain: string): Promise<DNS.Packet>;
+  resolveMX(domain: string): Promise<DNS.Packet>;
+  resolveCNAME(domain: string): Promise<DNS.Packet>;
+  resolvePTR(domain: string): Promise<DNS.Packet>;
+  resolveDNSKEY(domain: string): Promise<DNS.Packet>;
+  resolveRRSIG(domain: string): Promise<DNS.Packet>;
+  resolveSOA(domain: string): Promise<DNS.Packet>;
+
+  static createServer(options: DNS.CreateServerOptions): DNS.DnsServer;
+  static createUDPServer(options?: DNS.UdpServerOptions | DNS.DnsHandler): DNS.UDPServer;
+  static createTCPServer(options?: DNS.DnsHandler): DNS.TCPServer;
+  static createDOHServer(options?: DNS.DohServerOptions): DNS.DOHServer;
+
+  static UDPClient(options?: DNS.UdpClientOptions): DNS.DnsResolver;
+  static TCPClient(options?: DNS.TcpClientOptions): DNS.DnsResolver;
+  static DOHClient(options?: DNS.DohClientOptions): DNS.DnsResolver;
+  static GoogleClient(): DNS.DnsResolver;
+}
+
+// ─── Namespace (all exported sub-types live here) ─────────────────────────────
+
+declare namespace DNS {
+
+  // ── Packet ──────────────────────────────────────────────────────────────────
+
+  class Packet {
+    header: Packet.Header;
+    questions: Packet.Question[];
+    answers: Packet.Resource[];
+    authorities: Packet.Resource[];
+    additionals: Packet.Resource[];
+    recursive: boolean;
+
+    constructor(
+      data?: Packet | Packet.Header | Packet.Question | Packet.Resource | string | any[],
+    );
+
+    toBuffer(): Buffer;
+    toBase64URL(): string;
+
+    // ── Static constants ────────────────────────────────────────────────────
+
+    static TYPE: {
+      A      : 0x01;
+      NS     : 0x02;
+      MD     : 0x03;
+      MF     : 0x04;
+      CNAME  : 0x05;
+      SOA    : 0x06;
+      MB     : 0x07;
+      MG     : 0x08;
+      MR     : 0x09;
+      NULL   : 0x0a;
+      WKS    : 0x0b;
+      PTR    : 0x0c;
+      HINFO  : 0x0d;
+      MINFO  : 0x0e;
+      MX     : 0x0f;
+      TXT    : 0x10;
+      AAAA   : 0x1c;
+      SRV    : 0x21;
+      EDNS   : 0x29;
+      SPF    : 0x63;
+      AXFR   : 0xfc;
+      MAILB  : 0xfd;
+      MAILA  : 0xfe;
+      ANY    : 0xff;
+      CAA    : 0x101;
+      DNSKEY : 0x30;
+    };
+
+    static CLASS: {
+      IN  : 0x01;
+      CS  : 0x02;
+      CH  : 0x03;
+      HS  : 0x04;
+      ANY : 0xff;
+    };
+
+    static EDNS_OPTION_CODE: {
+      ECS: 0x08;
+    };
+
+    // ── Static helpers ──────────────────────────────────────────────────────
+
+    static parse(buffer: Buffer): Packet;
+    static createResponseFromRequest(request: Packet): Packet;
+    static createResourceFromQuestion(
+      base: Packet.Question,
+      record: Partial<Packet.Resource>,
+    ): Packet.Resource;
+    static readStream(socket: NodeJS.ReadableStream): Promise<Buffer>;
+    static toIPv6(parts: number[]): string;
+    static fromIPv6(address: string): string[];
+    static uuid(): number;
+
+    // ── Sub-constructors ────────────────────────────────────────────────────
+
+    static Header: {
+      new(header?: Partial<Packet.Header>): Packet.Header;
+      parse(reader: Buffer | Packet.Reader): Packet.Header;
+    };
+
+    static Question: {
+      new(
+        name?: string | Partial<Packet.Question>,
+        type?: number,
+        cls?: number,
+      ): Packet.Question;
+      parse(reader: Buffer | Packet.Reader): Packet.Question;
+      decode(reader: Buffer | Packet.Reader): Packet.Question;
+      encode(question: Packet.Question, writer?: Packet.Writer): Buffer;
+    };
+
+    static Resource: {
+      new(
+        name?: string | Partial<Packet.Resource>,
+        type?: number,
+        cls?: number,
+        ttl?: number,
+      ): Packet.Resource;
+      parse(reader: Buffer | Packet.Reader): Packet.Resource;
+      decode(reader: Buffer | Packet.Reader): Packet.Resource;
+      encode(resource: Packet.Resource, writer?: Packet.Writer): Buffer;
+      EDNS(rdata: object[]): Packet.Resource;
+    };
+
+    static Name: {
+      COPY: 0xc0;
+      encode(domain: string, writer?: Packet.Writer): Buffer;
+      decode(reader: Buffer | Packet.Reader): string;
+    };
+
+    static Reader: new(buffer: Buffer, offset?: number) => Packet.Reader;
+    static Writer: new() => Packet.Writer;
+  }
+
+  namespace Packet {
+    interface Header {
+      id: number;
+      qr: 0 | 1;
+      opcode: number;
+      aa: 0 | 1;
+      tc: 0 | 1;
+      rd: 0 | 1;
+      ra: 0 | 1;
+      z: number;
+      rcode: number;
+      qdcount: number;
+      ancount: number;
+      nscount: number;
+      arcount: number;
+      toBuffer(writer?: Writer): Buffer;
+    }
+
+    interface Question {
+      name: string;
+      type: number;
+      class: number;
+      toBuffer(writer?: Writer): Buffer;
+    }
+
+    /** Union of all possible DNS resource record shapes. */
+    interface Resource {
+      name: string;
+      type: number;
+      class: number;
+      ttl: number;
+      // A / AAAA
+      address?: string;
+      // MX
+      exchange?: string;
+      priority?: number;
+      // CNAME / PTR / NS
+      domain?: string;
+      ns?: string;
+      // TXT / SPF
+      data?: string | string[];
+      // SOA
+      primary?: string;
+      admin?: string;
+      serial?: number;
+      refresh?: number;
+      retry?: number;
+      expiration?: number;
+      minimum?: number;
+      // SRV
+      weight?: number;
+      port?: number;
+      target?: string;
+      // CAA
+      flags?: number;
+      tag?: string;
+      value?: string;
+      // DNSKEY
+      algorithm?: number;
+      keyTag?: number;
+      publicKey?: string;
+      toBuffer(writer?: Writer): Buffer;
+    }
+
+    interface Reader {
+      offset: number;
+      read(bits: number): number;
+    }
+
+    interface Writer {
+      buffer: number[];
+      write(value: number, bits: number): void;
+      writeBuffer(writer: Writer): void;
+      toBuffer(): Buffer;
+    }
+  }
+
+  // ── Servers ─────────────────────────────────────────────────────────────────
+
+  class UDPServer extends dgram.Socket {
+    constructor(options?: UdpServerOptions | DnsHandler);
+    handle(data: Buffer, rinfo: dgram.RemoteInfo): void;
+    response(rinfo: dgram.RemoteInfo, message: Packet | Buffer): Promise<Buffer>;
+    listen(port?: number, address?: string): Promise<void>;
+    on(event: 'request',      listener: DnsHandler): this;
+    on(event: 'requestError', listener: (error: Error) => void): this;
+    on(event: 'listening',    listener: () => void): this;
+    on(event: 'close',        listener: () => void): this;
+    on(event: string,         listener: (...args: any[]) => void): this;
+  }
+
+  class TCPServer extends net.Server {
+    constructor(options?: DnsHandler);
+    on(event: 'request',      listener: DnsHandler): this;
+    on(event: 'requestError', listener: (error: Error) => void): this;
+    on(event: string,         listener: (...args: any[]) => void): this;
+  }
+
+  class DOHServer extends EventEmitter {
+    constructor(options?: DohServerOptions);
+    listen(port?: number, address?: string): void;
+    address(): net.AddressInfo | null;
+    close(): void;
+    on(event: 'request',      listener: DnsHandler): this;
+    on(event: 'requestError', listener: (error: Error) => void): this;
+    on(event: 'listening',    listener: (address: net.AddressInfo) => void): this;
+    on(event: 'close',        listener: () => void): this;
+    on(event: string,         listener: (...args: any[]) => void): this;
+  }
+
+  class DnsServer extends EventEmitter {
+    constructor(options: CreateServerOptions);
+    addresses(): ServerAddresses;
+    listen(options?: DnsServerListenOptions): Promise<ServerAddresses>;
+    close(): Promise<void>;
+    on(event: 'request',      listener: DnsHandler): this;
+    on(event: 'requestError', listener: (error: Error) => void): this;
+    on(event: 'listening',    listener: (addresses: ServerAddresses) => void): this;
+    on(event: 'close',        listener: () => void): this;
+    on(event: 'error',        listener: (error: Error, transport: 'udp' | 'tcp' | 'doh') => void): this;
+    on(event: string,         listener: (...args: any[]) => void): this;
+  }
+
+  // ── Handler & resolver callable types ────────────────────────────────────────
+
+  type DnsHandler = (
+    request: Packet,
+    send: (response: Packet | Buffer) => Promise<Buffer>,
+    client: dgram.RemoteInfo | net.Socket | http.IncomingMessage,
+  ) => void;
+
+  type DnsResolver = (
+    name: string,
+    type?: string,
+    cls?: number,
+    options?: ResolveOptions,
+  ) => Promise<Packet>;
+
+  // ── Options ──────────────────────────────────────────────────────────────────
+
+  interface ClientOptions {
+    port: number;
+    retries: number;
+    timeout: number;
+    recursive: boolean;
+    /** When using UDP and the TC (truncated) bit is set, automatically retry over TCP. Default: `true`. */
+    retryOverTCP: boolean;
+    resolverProtocol: 'UDP' | 'TCP' | 'DOH' | 'Google';
+    /** Shorthand alias for `nameServers`. A single IP string or an array. */
+    dns?: string | string[];
+    nameServers: string[];
+    rootServers: string[];
+  }
+
+  interface ResolveOptions {
+    recursive?: boolean;
+    /** EDNS ECS client subnet in CIDR notation, e.g. `"1.2.3.4/24"` */
+    clientIp?: string;
+  }
+
+  interface UdpClientOptions {
+    dns?: string;
+    port?: number;
+    socketType?: dgram.SocketType;
+    timeout?: number;
+    /** When the TC (truncated) bit is set, automatically retry over TCP. Default: `true`. */
+    retryOverTCP?: boolean;
+  }
+
+  interface TcpClientOptions {
+    dns: string;
+    protocol?: 'tcp:' | 'tls:';
+    port?: number;
+  }
+
+  interface DohClientOptions {
+    dns: string;
+  }
+
+  interface UdpServerOptions {
+    type?: 'udp4' | 'udp6';
+  }
+
+  interface DohServerOptions {
+    port?: number;
+    ssl?: boolean;
+    cors?: boolean | string | ((origin: string) => boolean);
+    [key: string]: any;
+  }
+
+  type ListenOptions = number | { port?: number; address?: string };
+
+  interface DnsServerListenOptions {
+    udp?: ListenOptions;
+    tcp?: ListenOptions;
+    doh?: ListenOptions;
+  }
+
+  interface CreateServerOptions {
+    udp?: boolean | UdpServerOptions;
+    tcp?: boolean;
+    doh?: boolean | DohServerOptions;
+    handle?: DnsHandler;
+    maxConcurrent?: number;
+  }
+
+  interface ServerAddresses {
+    udp?: net.AddressInfo;
+    tcp?: net.AddressInfo;
+    doh?: net.AddressInfo;
+  }
+}
+
+export = DNS;

package/ts/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "ignoreDeprecations": "6.0",
+    "typeRoots": ["../node_modules/@types"]
+  },
+  "include": ["typings-check.ts"]
+}

package/ts/typings-check.ts

@@ -0,0 +1,124 @@
+/**
+ * Type-check smoke test for index.d.ts.
+ *
+ * This file is NOT executed at runtime. It exists solely so that `tsc` can
+ * verify that index.d.ts accurately describes the package's public API.
+ * CI runs `tsc --project tsconfig.json` and fails if there are type errors.
+ *
+ * Add a line here whenever a new public API surface is added to index.js.
+ */
+
+import DNS = require('./index');
+import type { AddressInfo } from 'node:net';
+
+const { Packet } = DNS;
+
+// ── DNS instance (high-level resolver) ────────────────────────────────────────
+
+const dns = new DNS({ nameServers: ['8.8.8.8'], port: 53, recursive: true });
+
+void dns.resolve('example.com', 'A');
+void dns.resolveA('example.com');
+void dns.resolveA('example.com', '1.2.3.4');
+void dns.resolveAAAA('example.com');
+void dns.resolveMX('example.com');
+void dns.resolveCNAME('www.example.com');
+void dns.resolvePTR('1.0.0.127.in-addr.arpa');
+void dns.resolveDNSKEY('example.com');
+void dns.resolveRRSIG('example.com');
+void dns.resolveSOA('example.com');
+
+dns.resolve('example.com').then((packet: DNS.Packet) => {
+  const hdr: DNS.Packet.Header = packet.header;
+  const _id: number = hdr.id;
+  const _rc: number = hdr.rcode;
+  const answer: DNS.Packet.Resource = packet.answers[0];
+  const _addr: string | undefined = answer.address;
+  const _ttl: number = answer.ttl;
+});
+
+// ── Packet static constants ───────────────────────────────────────────────────
+
+const _typeA: number = Packet.TYPE.A;
+const _typeAAAA: number = Packet.TYPE.AAAA;
+const _typeMX: number = Packet.TYPE.MX;
+const _typeDNSKEY: number = Packet.TYPE.DNSKEY;
+const _classIN: number = Packet.CLASS.IN;
+const _ecsCode: number = Packet.EDNS_OPTION_CODE.ECS;
+
+// ── Packet static helpers ─────────────────────────────────────────────────────
+
+const buf = Buffer.alloc(12);
+const parsed: DNS.Packet = Packet.parse(buf);
+const response: DNS.Packet = Packet.createResponseFromRequest(parsed);
+response.header.rcode = 3; // NXDOMAIN
+
+const q: DNS.Packet.Question = parsed.questions[0];
+if (q) {
+  Packet.createResourceFromQuestion(q, { address: '1.2.3.4', ttl: 60 });
+}
+
+// ── Packet encode / round-trip ────────────────────────────────────────────────
+
+const pkt = new Packet();
+pkt.header.qr = 1;
+const encoded: Buffer = pkt.toBuffer();
+Packet.parse(encoded);
+
+// ── Multi-server (DnsServer) ──────────────────────────────────────────────────
+
+const server: DNS.DnsServer = DNS.createServer({
+  udp: true,
+  tcp: true,
+  maxConcurrent: 100,
+  handle: (request, send, _client) => {
+    const res = Packet.createResponseFromRequest(request);
+    res.header.rcode = 5; // REFUSED
+    void send(res);
+  },
+});
+
+server.listen({ udp: { port: 53 }, tcp: 5353 }).then((addrs: DNS.ServerAddresses) => {
+  const _udp: AddressInfo | undefined = addrs.udp;
+});
+
+server.on('request', (req, send, _client) => {
+  void send(Packet.createResponseFromRequest(req));
+});
+
+server.on('error', (err: Error, transport: 'udp' | 'tcp' | 'doh') => {
+  void err;
+  void transport;
+});
+
+void server.close();
+
+// ── Individual server factories ───────────────────────────────────────────────
+
+const udpServer: DNS.UDPServer = DNS.createUDPServer({ type: 'udp4' });
+udpServer.on('request', (req, send) => { void send(req); });
+
+const tcpServer: DNS.TCPServer = DNS.createTCPServer();
+tcpServer.on('request', (req, send) => { void send(req); });
+
+const dohServer: DNS.DOHServer = DNS.createDOHServer({ ssl: false, cors: true });
+dohServer.on('request', (req, send) => { void send(req); });
+
+// ── Client factories ──────────────────────────────────────────────────────────
+
+const udpClient: DNS.DnsResolver = DNS.UDPClient({ dns: '8.8.8.8', port: 53 });
+const tcpClient: DNS.DnsResolver = DNS.TCPClient({ dns: '8.8.8.8', protocol: 'tcp:' });
+const dohClient: DNS.DnsResolver = DNS.DOHClient({ dns: 'https://cloudflare-dns.com/dns-query' });
+const googleClient: DNS.DnsResolver = DNS.GoogleClient();
+
+void udpClient('example.com', 'A');
+void tcpClient('example.com', 'MX');
+void dohClient('example.com', 'AAAA');
+void googleClient('example.com');
+
+// ── Sub-class type assignability ──────────────────────────────────────────────
+
+const _dnsServer: DNS.DnsServer = DNS.createServer({ udp: true });
+const _udp: DNS.UDPServer = DNS.createUDPServer();
+const _tcp: DNS.TCPServer = DNS.createTCPServer();
+const _doh: DNS.DOHServer = DNS.createDOHServer();

package/.eslintrc

@@ -1,16 +0,0 @@
-{
-  "extends": "semistandard",
-  "rules": {
-    "space-before-function-paren": ["error", "never"],
-    "no-multi-spaces": ["error"],
-    "array-bracket-spacing": ["error", "always"],
-    "key-spacing": ["error", {
-      "align": {
-        "beforeColon": true,
-        "afterColon": true,
-        "on": "colon"
-      }
-    }],
-    "comma-dangle": ["error", "always-multiline"]
-  }
-}

package/.github/FUNDING.yml

@@ -1,12 +0,0 @@
-# These are supported funding model platforms
-
-github: song940
-patreon: song940
-open_collective: song940
-ko_fi: # Replace with a single Ko-fi username
-tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
-community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
-liberapay: # Replace with a single Liberapay username
-issuehunt: # Replace with a single IssueHunt username
-otechie: # Replace with a single Otechie username
-custom: https://git.io/fjRcB

package/.github/workflows/lint.js.yml

@@ -1,17 +0,0 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
-name: Linting
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-node@v1
-      with:
-        node-version: 16
-    - run: npm i
-    - run: npm run lint

package/.github/workflows/node.js.yml

@@ -1,29 +0,0 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
-name: Node.js CI
-
-on:
-  push:
-    branches: [ master ]
-  pull_request:
-    branches: [ master ]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [10.x, 12.x, 14.x, 16.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm ci
-    - run: npm test

package/SECURITY.md

@@ -1,21 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 5.1.x   | :white_check_mark: |
-| 5.0.x   | :x:                |
-| 4.0.x   | :white_check_mark: |
-| < 4.0   | :x:                |
-
-## Reporting a Vulnerability
-
-Use this section to tell people how to report a vulnerability.
-
-Tell them where to go, how often they can expect to get an update on a
-reported vulnerability, what to expect if the vulnerability is accepted or
-declined, etc.