knock 0.1.0 → 1.1.0

package/dist/index.js

@@ -0,0 +1,278 @@
+/**
+ * knock — subdomain enumeration via Certificate Transparency logs and
+ * wordlist DNS brute forcing, with wildcard DNS detection.
+ */
+import { Resolver } from 'node:dns/promises';
+import { readFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { loadPublicSuffixList, getRegistrableDomain } from './psl.js';
+/** Absolute paths to the wordlists bundled with the package. */
+export const wordlists = {
+    subs: fileURLToPath(new URL('../lists/subs.txt', import.meta.url)),
+    org: fileURLToPath(new URL('../lists/org.txt', import.meta.url)),
+};
+// DNS answers that simply mean "nothing there", as opposed to a lookup failure.
+const NEGATIVE_CODES = new Set(['ENOTFOUND', 'ENODATA', 'NXDOMAIN']);
+const HOSTNAME_PATTERN = /^[a-z0-9_][a-z0-9_.-]*$/;
+// Dotted-quad IPv4 literals have no registrable domain; skip PSL reduction.
+const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const defaults = {
+    wordlist: wordlists.subs,
+    concurrency: 64,
+    timeout: 5000,
+    tries: 2,
+    family: 4,
+    wildcardTests: 3,
+    ct: true,
+    ctTimeout: 15000,
+    verify: true,
+    web: false,
+    webTimeout: 5000,
+    baseDomainOnly: true,
+    icannOnly: false,
+};
+/**
+ * Reduce user input like "HTTPS://www.Example.com/path" to a bare hostname.
+ * Throws TypeError when no usable hostname can be extracted.
+ */
+export function normalizeDomain(input) {
+    const raw = String(input ?? '').trim();
+    if (raw === '')
+        throw new TypeError('domain is required');
+    const url = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`;
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        throw new TypeError(`invalid domain: ${raw}`);
+    }
+    hostname = hostname.toLowerCase().replace(/\.+$/, '');
+    if (hostname === '' || hostname.startsWith('[')) {
+        throw new TypeError(`invalid domain: ${raw}`);
+    }
+    return hostname;
+}
+/** Parse wordlist text into unique, lowercased labels. Blank lines and #comments are skipped. */
+export function parseWordlist(text) {
+    const words = new Set();
+    for (const line of String(text).split(/\r?\n/)) {
+        const word = line.trim().toLowerCase();
+        if (word === '' || word.startsWith('#'))
+            continue;
+        words.add(word);
+    }
+    return [...words];
+}
+/** Read and parse a wordlist file. */
+export async function loadWordlist(path) {
+    return parseWordlist(await readFile(path, 'utf8'));
+}
+/**
+ * Query Certificate Transparency logs (via crt.sh) for names certified under
+ * `domain`. Purely passive: one HTTPS request, no DNS traffic to the target.
+ * Wildcard entries like "*.dev.example.com" are reported as "dev.example.com".
+ * Resolves to a sorted array of hostnames, the apex excluded.
+ */
+export async function certSubdomains(domain, options = {}) {
+    const target = normalizeDomain(domain);
+    const { timeout = defaults.ctTimeout, signal, fetch: fetchImpl = globalThis.fetch } = options;
+    const url = `https://crt.sh/?q=${encodeURIComponent(`%.${target}`)}&output=json`;
+    const signals = [AbortSignal.timeout(timeout)];
+    if (signal)
+        signals.push(signal);
+    const response = await fetchImpl(url, {
+        signal: AbortSignal.any(signals),
+        headers: { accept: 'application/json' },
+    });
+    if (!response.ok)
+        throw new Error(`crt.sh responded with HTTP ${response.status}`);
+    const entries = await response.json();
+    const names = new Set();
+    for (const entry of Array.isArray(entries) ? entries : []) {
+        const record = entry;
+        const candidates = [record?.common_name, ...String(record?.name_value ?? '').split('\n')];
+        for (const candidate of candidates) {
+            if (!candidate)
+                continue;
+            let name = String(candidate).trim().toLowerCase().replace(/\.+$/, '');
+            if (name.startsWith('*.'))
+                name = name.slice(2);
+            if (name === target || !name.endsWith(`.${target}`))
+                continue;
+            if (!HOSTNAME_PATTERN.test(name))
+                continue;
+            names.add(name);
+        }
+    }
+    return [...names].sort();
+}
+function makeResolver({ timeout, tries, servers, }) {
+    const resolver = new Resolver({ timeout, tries });
+    if (servers && servers.length > 0)
+        resolver.setServers(servers);
+    return resolver;
+}
+async function lookupName(resolver, name, family) {
+    const addresses = [];
+    let error;
+    const families = family === 'any' ? [4, 6] : [family];
+    for (const fam of families) {
+        try {
+            const found = fam === 6 ? await resolver.resolve6(name) : await resolver.resolve4(name);
+            addresses.push(...found);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (!NEGATIVE_CODES.has(code ?? ''))
+                error = err;
+        }
+    }
+    return { addresses, error };
+}
+// Resolve a few random labels that cannot exist; any answers reveal a wildcard record.
+async function detectWildcard(resolver, domain, { tests, family }) {
+    const addresses = new Set();
+    for (let i = 0; i < tests; i += 1) {
+        const name = `knock-${randomBytes(8).toString('hex')}.${domain}`;
+        const { addresses: found } = await lookupName(resolver, name, family);
+        for (const address of found)
+            addresses.add(address);
+    }
+    return addresses;
+}
+async function probeWeb(name, timeout) {
+    const statuses = { https: null, http: null };
+    await Promise.all(['https', 'http'].map(async (protocol) => {
+        try {
+            const response = await fetch(`${protocol}://${name}/`, {
+                method: 'HEAD',
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeout),
+            });
+            statuses[protocol] = response.status;
+        }
+        catch {
+            statuses[protocol] = null;
+        }
+    }));
+    return statuses;
+}
+async function pool(items, worker, concurrency, signal) {
+    let index = 0;
+    const size = Math.max(1, Math.min(concurrency, items.length));
+    const runners = Array.from({ length: size }, async () => {
+        while (index < items.length && !signal?.aborted) {
+            const item = items[index];
+            index += 1;
+            await worker(item);
+        }
+    });
+    await Promise.all(runners);
+}
+/**
+ * Enumerate subdomains of `domain`.
+ *
+ * Two sources feed the candidate set: Certificate Transparency logs
+ * (passive, `ct` option) and a wordlist brute force over DNS. Candidates
+ * are resolved concurrently; hosts that only echo a wildcard DNS answer are
+ * suppressed unless Certificate Transparency vouches for them.
+ */
+export async function knock(domain, options = {}) {
+    const opts = { ...defaults, ...options };
+    let target = normalizeDomain(domain);
+    if (opts.baseDomainOnly && !IPV4_PATTERN.test(target)) {
+        const rules = opts.psl ?? (await loadPublicSuffixList());
+        const base = getRegistrableDomain(target, rules, { icannOnly: opts.icannOnly });
+        if (base)
+            target = base;
+    }
+    const words = opts.words ?? (await loadWordlist(opts.wordlist));
+    const resolver = opts.resolver ?? makeResolver(opts);
+    const { signal } = opts;
+    signal?.throwIfAborted();
+    const started = Date.now();
+    const ct = { enabled: Boolean(opts.ct), names: 0, unresolved: [], error: null };
+    const candidates = new Map();
+    for (const word of words) {
+        candidates.set(`${word}.${target}`, new Set(['wordlist']));
+    }
+    if (opts.ct) {
+        try {
+            const names = await certSubdomains(target, {
+                timeout: opts.ctTimeout,
+                signal,
+                fetch: opts.fetch,
+            });
+            ct.names = names.length;
+            for (const name of names) {
+                const sources = candidates.get(name);
+                if (sources)
+                    sources.add('ct');
+                else
+                    candidates.set(name, new Set(['ct']));
+            }
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            ct.error = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const wildcardAddresses = words.length > 0 && opts.wildcardTests > 0
+        ? await detectWildcard(resolver, target, { tests: opts.wildcardTests, family: opts.family })
+        : new Set();
+    const results = [];
+    let queried = 0;
+    let errors = 0;
+    await pool([...candidates.entries()], async ([name, sources]) => {
+        const fromCt = sources.has('ct');
+        const emit = async (addresses) => {
+            const result = { name, addresses, sources: [...sources] };
+            if (opts.web)
+                result.web = await probeWeb(name, opts.webTimeout);
+            results.push(result);
+            opts.onResult?.(result);
+        };
+        if (fromCt && !sources.has('wordlist') && !opts.verify) {
+            await emit([]);
+            return;
+        }
+        const { addresses, error } = await lookupName(resolver, name, opts.family);
+        queried += 1;
+        if (addresses.length === 0) {
+            if (error)
+                errors += 1;
+            if (fromCt)
+                ct.unresolved.push(name);
+            return;
+        }
+        // A wordlist hit that only mirrors the wildcard answer is not a real
+        // discovery; a certificate in the CT logs is evidence on its own.
+        if (!fromCt &&
+            wildcardAddresses.size > 0 &&
+            addresses.every((address) => wildcardAddresses.has(address))) {
+            return;
+        }
+        await emit(addresses);
+    }, opts.concurrency, signal);
+    signal?.throwIfAborted();
+    ct.unresolved.sort();
+    return {
+        domain: target,
+        wildcard: { detected: wildcardAddresses.size > 0, addresses: [...wildcardAddresses] },
+        ct,
+        results,
+        stats: {
+            words: words.length,
+            candidates: candidates.size,
+            queried,
+            found: results.length,
+            errors,
+            durationMs: Date.now() - started,
+        },
+    };
+}
+export { publicSuffixListPath, parsePublicSuffixList, loadPublicSuffixList, getPublicSuffix, getRegistrableDomain, } from './psl.js';
+export default knock;

package/dist/mcp.d.ts

@@ -0,0 +1,14 @@
+import type { Readable, Writable } from 'node:stream';
+import type { KnockOptions } from './index.ts';
+/** Protocol revisions this server speaks, newest first. */
+export declare const MCP_PROTOCOL_VERSIONS: string[];
+export interface McpServerOptions {
+    input?: Readable;
+    output?: Writable;
+    /** Merged into every knock() / certSubdomains() call, mainly for testing (resolver, fetch, psl). */
+    knockOptions?: Pick<KnockOptions, 'resolver' | 'fetch' | 'psl'>;
+}
+/**
+ * Serve MCP over stdio (or the given streams). Resolves when the input ends.
+ */
+export declare function serveMcp(options?: McpServerOptions): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,319 @@
+/**
+ * knock as a Model Context Protocol server over stdio — newline-delimited
+ * JSON-RPC 2.0, implemented directly so the package stays dependency-free.
+ */
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { knock, certSubdomains, normalizeDomain, wordlists, loadPublicSuffixList, getPublicSuffix, getRegistrableDomain, } from './index.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+/** Protocol revisions this server speaks, newest first. */
+export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+class InvalidParams extends Error {
+}
+const INSTRUCTIONS = `knock enumerates subdomains of a domain using Certificate Transparency logs (passive, via crt.sh) and a wordlist DNS brute force with wildcard detection.
+Prefer knock_ct_lookup or knock_enumerate with passive: true for a quick, low-noise look; a full brute force sends ~31k DNS queries and takes roughly 30-90 seconds.
+Only enumerate domains the user owns or is authorized to assess.`;
+const domainProperty = {
+    type: 'string',
+    description: 'Domain, hostname or URL, e.g. "example.com" or "https://www.example.co.uk/path".',
+};
+const TOOLS = [
+    {
+        name: 'knock_enumerate',
+        title: 'Enumerate subdomains',
+        description: 'Find subdomains of a domain. Combines Certificate Transparency logs with a DNS brute force over a bundled wordlist, filters wildcard DNS, and verifies names with real lookups. Input is reduced to its registrable domain first (www.example.co.uk -> example.co.uk) unless fullHost is set. Returns the full report: results (name, addresses, sources), wildcard, ct (including unresolved CT names), and stats. A full run sends ~31k DNS queries; use passive: true for a CT-only lookup.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: domainProperty,
+                passive: {
+                    type: 'boolean',
+                    description: 'Skip the wordlist brute force; Certificate Transparency only. Default false.',
+                },
+                ct: { type: 'boolean', description: 'Query Certificate Transparency logs. Default true.' },
+                verify: {
+                    type: 'boolean',
+                    description: 'Resolve CT-discovered names over DNS. Default true.',
+                },
+                fullHost: {
+                    type: 'boolean',
+                    description: 'Scan the exact host given instead of its registrable domain. Default false.',
+                },
+                wordlist: {
+                    type: 'string',
+                    enum: ['subs', 'org'],
+                    description: 'Bundled wordlist: "subs" (~31k labels, default) or "org".',
+                },
+                words: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Custom labels to try instead of a bundled wordlist, e.g. ["www", "api"].',
+                },
+                concurrency: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 512,
+                    description: 'Parallel DNS queries. Default 64.',
+                },
+                timeout: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Per-query DNS timeout in milliseconds. Default 5000.',
+                },
+                servers: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'DNS server IPs to query instead of the system resolvers.',
+                },
+                ipv6: { type: 'boolean', description: 'Also resolve AAAA records. Default false.' },
+                web: {
+                    type: 'boolean',
+                    description: 'Probe http/https on each found host and report status codes. Default false.',
+                },
+            },
+            required: ['domain'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: 'knock_ct_lookup',
+        title: 'Certificate Transparency lookup',
+        description: 'List hostnames under a domain that appear in Certificate Transparency logs (crt.sh). Passive: one HTTPS request to crt.sh, no DNS traffic to the target. Names are not verified and may be stale. The domain is used exactly as given (no registrable-domain reduction).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                domain: domainProperty,
+                timeout: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Request timeout in milliseconds. Default 15000.',
+                },
+            },
+            required: ['domain'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    {
+        name: 'knock_registrable_domain',
+        title: 'Registrable domain',
+        description: 'Reduce a hostname or URL to its public suffix and registrable domain using the bundled Public Suffix List, e.g. "a.b.example.co.uk" -> suffix "co.uk", registrable "example.co.uk". Offline; no network access.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                host: domainProperty,
+                icannOnly: {
+                    type: 'boolean',
+                    description: 'Ignore private suffixes like github.io. Default false.',
+                },
+            },
+            required: ['host'],
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+function optional(args, key, check, expected) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (!check(value))
+        throw new InvalidParams(`"${key}" must be ${expected}`);
+    return value;
+}
+const isBoolean = (v) => typeof v === 'boolean';
+const isString = (v) => typeof v === 'string';
+const isPositiveInteger = (v) => Number.isInteger(v) && v > 0;
+const isStringArray = (v) => Array.isArray(v) && v.every(isString);
+function required(args, key) {
+    const value = optional(args, key, isString, 'a string');
+    if (!value)
+        throw new InvalidParams(`"${key}" is required`);
+    return value;
+}
+/**
+ * Serve MCP over stdio (or the given streams). Resolves when the input ends.
+ */
+export async function serveMcp(options = {}) {
+    const { input = process.stdin, output = process.stdout, knockOptions = {} } = options;
+    const inFlight = new Map();
+    const send = (message) => {
+        output.write(`${JSON.stringify({ jsonrpc: '2.0', ...message })}\n`);
+    };
+    const reply = (id, result) => send({ id, result });
+    const replyError = (id, code, message) => send({ id, error: { code, message } });
+    const toolResult = (data, summary) => ({
+        content: [
+            ...(summary ? [{ type: 'text', text: summary }] : []),
+            { type: 'text', text: JSON.stringify(data) },
+        ],
+        structuredContent: data,
+    });
+    async function callTool(name, args, signal, progress) {
+        switch (name) {
+            case 'knock_enumerate': {
+                const domain = required(args, 'domain');
+                const passive = optional(args, 'passive', isBoolean, 'a boolean') ?? false;
+                const list = optional(args, 'wordlist', isString, 'a string');
+                if (list !== undefined && list !== 'subs' && list !== 'org') {
+                    throw new InvalidParams('"wordlist" must be "subs" or "org"');
+                }
+                const run = {
+                    ...knockOptions,
+                    signal,
+                    ct: optional(args, 'ct', isBoolean, 'a boolean') ?? true,
+                    verify: optional(args, 'verify', isBoolean, 'a boolean') ?? true,
+                    baseDomainOnly: !(optional(args, 'fullHost', isBoolean, 'a boolean') ?? false),
+                    wordlist: wordlists[list ?? 'subs'],
+                    words: passive ? [] : optional(args, 'words', isStringArray, 'an array of strings'),
+                    concurrency: Math.min(optional(args, 'concurrency', isPositiveInteger, 'a positive integer') ?? 64, 512),
+                    timeout: optional(args, 'timeout', isPositiveInteger, 'a positive integer'),
+                    servers: optional(args, 'servers', isStringArray, 'an array of strings'),
+                    family: optional(args, 'ipv6', isBoolean, 'a boolean') ? 'any' : 4,
+                    web: optional(args, 'web', isBoolean, 'a boolean') ?? false,
+                };
+                if (passive && !run.ct)
+                    throw new InvalidParams('passive with ct: false leaves nothing to do');
+                if (run.timeout === undefined)
+                    delete run.timeout;
+                let found = 0;
+                run.onResult = (result) => {
+                    found += 1;
+                    progress(found, result.name);
+                };
+                const report = await knock(domain, run);
+                const { stats, wildcard, ct } = report;
+                const summary = `${report.domain}: ${stats.found} found from ${stats.candidates} candidates` +
+                    (ct.enabled ? `, ${ct.names} CT names (${ct.unresolved.length} unresolved)` : '') +
+                    (wildcard.detected ? `, wildcard DNS detected (${wildcard.addresses.join(', ')})` : '') +
+                    (ct.error ? `, CT lookup failed: ${ct.error}` : '') +
+                    ` in ${(stats.durationMs / 1000).toFixed(1)}s`;
+                return toolResult(report, summary);
+            }
+            case 'knock_ct_lookup': {
+                const domain = normalizeDomain(required(args, 'domain'));
+                const names = await certSubdomains(domain, {
+                    signal,
+                    fetch: knockOptions.fetch,
+                    timeout: optional(args, 'timeout', isPositiveInteger, 'a positive integer'),
+                });
+                return toolResult({ domain, names }, `${names.length} CT names under ${domain}`);
+            }
+            case 'knock_registrable_domain': {
+                const host = normalizeDomain(required(args, 'host'));
+                const icannOnly = optional(args, 'icannOnly', isBoolean, 'a boolean') ?? false;
+                const rules = knockOptions.psl ?? (await loadPublicSuffixList());
+                return toolResult({
+                    host,
+                    publicSuffix: getPublicSuffix(host, rules, { icannOnly }),
+                    registrableDomain: getRegistrableDomain(host, rules, { icannOnly }),
+                });
+            }
+            default:
+                throw new InvalidParams(`unknown tool: ${name}`);
+        }
+    }
+    async function handle(message) {
+        const { id, method } = message;
+        const params = (message.params ?? {});
+        const isRequest = typeof id === 'string' || typeof id === 'number';
+        if (typeof method !== 'string') {
+            // Responses to requests we never send; ignore. Malformed requests get an error.
+            if (isRequest && !('result' in message || 'error' in message)) {
+                replyError(id, -32600, 'invalid request');
+            }
+            return;
+        }
+        if (!isRequest) {
+            if (method === 'notifications/cancelled') {
+                inFlight.get(params.requestId)?.abort(new Error(String(params.reason ?? 'cancelled')));
+            }
+            return;
+        }
+        switch (method) {
+            case 'initialize': {
+                const requested = params.protocolVersion;
+                reply(id, {
+                    protocolVersion: typeof requested === 'string' && MCP_PROTOCOL_VERSIONS.includes(requested)
+                        ? requested
+                        : MCP_PROTOCOL_VERSIONS[0],
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: 'knock', title: 'knock', version },
+                    instructions: INSTRUCTIONS,
+                });
+                return;
+            }
+            case 'ping':
+                reply(id, {});
+                return;
+            case 'tools/list':
+                reply(id, { tools: TOOLS });
+                return;
+            case 'tools/call': {
+                const name = String(params.name ?? '');
+                const args = (params.arguments ?? {});
+                const progressToken = params._meta?.progressToken;
+                const controller = new AbortController();
+                inFlight.set(id, controller);
+                const progress = (count, text) => {
+                    if (progressToken === undefined)
+                        return;
+                    send({
+                        method: 'notifications/progress',
+                        params: { progressToken, progress: count, message: `found ${text}` },
+                    });
+                };
+                try {
+                    reply(id, await callTool(name, args, controller.signal, progress));
+                }
+                catch (error) {
+                    // A cancelled request gets no response, per the spec.
+                    if (controller.signal.aborted)
+                        return;
+                    const text = error instanceof Error ? error.message : String(error);
+                    if (error instanceof InvalidParams && text.startsWith('unknown tool')) {
+                        replyError(id, -32602, text);
+                    }
+                    else {
+                        reply(id, { content: [{ type: 'text', text }], isError: true });
+                    }
+                }
+                finally {
+                    inFlight.delete(id);
+                }
+                return;
+            }
+            default:
+                replyError(id, -32601, `method not found: ${method}`);
+        }
+    }
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    const pending = new Set();
+    for await (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            replyError(null, -32700, 'parse error');
+            continue;
+        }
+        if (typeof message !== 'object' || message === null || Array.isArray(message)) {
+            replyError(null, -32600, 'invalid request');
+            continue;
+        }
+        // Requests run concurrently so pings and cancellations stay responsive during a scan.
+        const task = handle(message).catch((error) => {
+            process.stderr.write(`knock mcp: ${error instanceof Error ? error.stack : String(error)}\n`);
+        });
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    }
+    for (const controller of inFlight.values())
+        controller.abort(new Error('input closed'));
+    await Promise.allSettled(pending);
+}

package/dist/psl.d.ts

@@ -0,0 +1,36 @@
+/** Absolute path to the vendored Public Suffix List. */
+export declare const publicSuffixListPath: string;
+/** A single Public Suffix List rule. */
+export interface PublicSuffixRule {
+    /** The rule began with `!`, marking an exception to a wildcard rule. */
+    exception: boolean;
+    /** From the ICANN section rather than the PRIVATE section of the list. */
+    icann: boolean;
+}
+/** Parsed rule set: punycode rule string (without any leading `!`) → rule. */
+export type PublicSuffixRules = Map<string, PublicSuffixRule>;
+/** Options shared by the Public Suffix List lookups. */
+export interface PublicSuffixOptions {
+    /** Ignore the PRIVATE section (github.io, herokuapp.com, …). Default false. */
+    icannOnly?: boolean;
+}
+/**
+ * Parse Public Suffix List text into a rule map. Each line is read only up to
+ * the first whitespace; `//` lines and blanks are skipped. The ICANN/PRIVATE
+ * section is tracked from the `===BEGIN …===` markers.
+ */
+export declare function parsePublicSuffixList(text: string): PublicSuffixRules;
+/** Read and parse a Public Suffix List file, memoized per path. */
+export declare function loadPublicSuffixList(path?: string): Promise<PublicSuffixRules>;
+/**
+ * The public suffix of `hostname` (e.g. "co.uk", "github.io"), or null when the
+ * hostname has fewer labels than the matching rule. `hostname` should already
+ * be a bare, lowercased, punycode host as produced by `normalizeDomain`.
+ */
+export declare function getPublicSuffix(hostname: string, rules: PublicSuffixRules, options?: PublicSuffixOptions): string | null;
+/**
+ * The registrable domain of `hostname` — its public suffix plus one label
+ * (e.g. "www.example.co.uk" → "example.co.uk"). Returns null when `hostname` is
+ * itself a public suffix (or shorter), i.e. has no registrable domain.
+ */
+export declare function getRegistrableDomain(hostname: string, rules: PublicSuffixRules, options?: PublicSuffixOptions): string | null;