dohdec/types/dot.d.ts

DNS over HTTPS and DNS over TLS

/**
 * Options for doing DOT lookups.
 *
 * @typedef {import('./dnsUtils.js').LookupOptions} DOT_LookupOptions
 */
/**
 * @typedef {import('./dnsUtils.js').Writable} Writable
 */
/**
 * @callback pendingResolve
 * @param {Buffer|object} results The results of the DNS query.
 */
/**
 * @callback pendingError
 * @param {Error} error The error that occurred.
 */
/**
 * @typedef {object} Pending
 * @property {pendingResolve} resolve Callback for success.
 * @property {pendingError} reject Callback for error.
 * @property {DOT_LookupOptions} opts The original options for the request.
 */
/**
 * A class that manages a connection to a DNS-over-TLS server.  The first time
 * [lookup]{@link DNSoverTLS#lookup} is called, a connection will be created.
 * If that connection is timed out by the server, a new connection will be
 * created as needed.
 *
 * If you want to do certificate pinning, make sure that the `hash` and
 * `hashAlg` options are set correctly to a hash of the DER-encoded
 * certificate that the server will offer.
 */
export class DNSoverTLS extends DNSutils {
    /**
     * Hash a certificate using the given algorithm.
     *
     * @param {Buffer|tls.PeerCertificate} cert The cert to hash.
     * @param {string} [hashAlg="sha256"] The hash algorithm to use.
     * @returns {string} Hex string.
     * @throws {Error} Unknown certificate type.
     */
    static hashCert(cert: Buffer | tls.PeerCertificate, hashAlg?: string): string;
    /**
     * Construct a new DNSoverTLS.
     *
     * @param {object} opts Options.
     * @param {string} [opts.host='1.1.1.1'] Server to connect to.
     * @param {number} [opts.port=853] TCP port number for server.
     * @param {string} [opts.hash] Hex-encoded hash of the DER-encoded cert
     *   expected from the server.  If not specified, no pinning checks are
     *   performed.
     * @param {string} [opts.hashAlg='sha256'] Hash algorithm for cert pinning.
     * @param {boolean} [opts.rejectUnauthorized=true] Should the server
     *   certificate even be checked using the normal TLS approach?
     * @param {number} [opts.verbose=0] How verbose do you want your logging?
     * @param {Writable} [opts.verboseStream=process.stderr] Where to write
     *   verbose output.
     */
    constructor(opts?: {
        host?: string | undefined;
        port?: number | undefined;
        hash?: string | undefined;
        hashAlg?: string | undefined;
        rejectUnauthorized?: boolean | undefined;
        verbose?: number | undefined;
        verboseStream?: import("./dnsUtils.js").Writable | undefined;
    });
    size: number;
    /** @type {tls.TLSSocket|undefined} */
    socket: tls.TLSSocket | undefined;
    /** @type {Record<number, Pending>} */
    pending: Record<number, Pending>;
    /** @type {NoFilter|undefined} */
    nof: NoFilter | undefined;
    /** @type {Buffer[]} */
    bufs: Buffer[];
    opts: {
        host: string;
        port: number;
        hash?: string | undefined;
        hashAlg: string;
        rejectUnauthorized: boolean;
        checkServerIdentity: (host: string, cert: tls.PeerCertificate) => Error | undefined;
    };
    _reset(): void;
    /**
     * @returns {Promise<void>}
     * @private
     */
    private _connect;
    /**
     * @param {string} host
     * @param {tls.PeerCertificate} cert
     * @returns {Error | undefined}
     * @private
     */
    private _checkServerIdentity;
    /**
     * Server socket was disconnected.  Clean up any pending requests.
     *
     * @private
     */
    private _disconnected;
    /**
     * Parse data if enough is available.
     *
     * @param {Buffer} b Data read from socket.
     * @private
     */
    private _data;
    /**
     * Generate a currently-unused random ID.
     *
     * @returns {Promise<number>} A random 2-byte ID number.
     * @private
     */
    private _id;
    /**
     * Look up a name in the DNS, over TLS.
     *
     * @param {DOT_LookupOptions|string} name The DNS name to look up, or opts
     *   if this is an object.
     * @param {DOT_LookupOptions|string} [opts={}] Options for the
     *   request.  If a string is given, it will be used as the rrtype.
     * @returns {Promise<Buffer|packet.Packet>} Response.
     */
    lookup(name: DOT_LookupOptions | string, opts?: DOT_LookupOptions | string): Promise<Buffer | packet.Packet>;
    /**
     * Close the socket.
     *
     * @returns {Promise<void>} Resolved on socket close.
     */
    close(): Promise<void>;
}
export namespace DNSoverTLS {
    export { DEFAULT_SERVER as server };
}
export default DNSoverTLS;
/**
 * Options for doing DOT lookups.
 */
export type DOT_LookupOptions = import("./dnsUtils.js").LookupOptions;
export type Writable = import("./dnsUtils.js").Writable;
export type pendingResolve = (results: Buffer | object) => any;
export type pendingError = (error: Error) => any;
export type Pending = {
    /**
     * Callback for success.
     */
    resolve: pendingResolve;
    /**
     * Callback for error.
     */
    reject: pendingError;
    /**
     * The original options for the request.
     */
    opts: DOT_LookupOptions;
};
import { default as DNSutils } from './dnsUtils.js';
import * as tls from 'node:tls';
import { NoFilter } from 'nofilter';
import { Buffer } from 'node:buffer';
import * as packet from 'dns-packet';
declare const DEFAULT_SERVER: "1.1.1.1";