@sdxc/doh 0.0.0-pre.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @sdxc/doh
+
+Typed DNS over HTTPS lookups.
+
+## Installation
+
+```bash
+npm add @sdxc/doh
+```
+
+Every lookup returns a [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result) value, which
+installs alongside this package.
+
+A runtime with no DNS socket, such as a Cloudflare Worker, resolves names through DNS over HTTPS:
+a `fetch` to a public resolver. This package speaks the DoH JSON API (`application/dns-json`)
+that Cloudflare and Google answer, validates the envelope, and returns a `Result` whose records
+are typed per query type: an `MX` query gives `preference` and `exchange`, a `TXT` query gives
+the joined `text` with the resolver's quoting and escapes removed.
+
+Failures are classes, so a caller tells "the name is gone" from "the resolver is down" with
+`instanceof`: NXDOMAIN is `NameNotFoundError`, SERVFAIL is `ServerFailureError`, any other RCODE
+is `ResponseCodeError`, and a request that produced no DNS answer is `TransportError`. A name
+that exists with no records of the asked type (NODATA) is a success with no records.
+
+Each call is one request through the global `fetch` and keeps no state: every answer carries its
+TTL for a caller that caches, and retry policy stays with the caller.
+
+## Usage
+
+### Look Up Records
+
+```typescript
+import { resolve } from "@sdxc/doh";
+import { isSuccess } from "@sdxc/result";
+
+let answer = await resolve("example.com", "MX");
+if (isSuccess(answer)) {
+	for (let record of answer.data.records) console.log(record.preference, record.exchange);
+}
+```
+
+### Check Domain Ownership
+
+```typescript
+import { checkCname, verifyTxtRecord } from "@sdxc/doh";
+
+let verified = await verifyTxtRecord("_verify.example.com", "token_abc123"); // Result<boolean>
+let pointed = await checkCname("shop.example.com", "custom.hosting.example"); // Result<boolean>
+```
+
+### Read Record Data From Anywhere
+
+```typescript
+import { parseRecordData } from "@sdxc/doh";
+
+let data = parseRecordData("MX", "10 mail.example.com.");
+// success({ type: "MX", preference: 10, exchange: "mail.example.com" })
+```
+
+## API
+
+### `@sdxc/doh`
+
+#### `resolve(name, type, options?): Promise<Result<DoH.Answer<Type>, DoHError>>`
+
+Looks up `name`'s records of `type`. The name is sent as written, so an internationalized name must
+already be in its ASCII (punycode) form. The answer holds:
+
+- `records` - the records of the asked type, typed by `DoH.RecordFor<Type>`
+- `unparsed` - records of the asked type whose data did not parse, as `{ name, ttl, type, data }`,
+  so one odd record never fails the whole answer
+- `chain` - the CNAME records followed before reaching `records`
+- `ttl` - the smallest TTL across `records` and `unparsed`, `null` when both are empty
+- `authenticated` - the AD flag (the resolver validated DNSSEC); requiring it is the caller's policy
+- `truncated` - the TC flag
+- `name` (lowercased, no trailing dot), `type`, and `durationMs`
+
+Records of other types (RRSIG with `dnssec: true`, say) are dropped. Owner names and targets come
+back lowercased without the trailing dot; an AAAA address comes back in RFC 5952 form.
+
+**Options:**
+
+- `resolver`: `CLOUDFLARE` (default), `GOOGLE`, or `{ url, format: "json" }`
+- `dnssec`: sets `do=1`
+- `checkingDisabled`: sets `cd=1`
+- `signal`: aborts the request
+- `timeoutMs`: abandons the request as a `TransportError`, default `5000`
+
+Typed record types: `A` (`address`), `AAAA` (`address`), `CNAME` (`target`), `NS` (`host`), `MX`
+(`preference`, `exchange`), `TXT` (`text`, `strings`), `CAA` (`critical`, `tag`, `value`), `SRV`
+(`priority`, `weight`, `port`, `target`), `SOA` (`primary`, `mailbox`, `serial`, `refresh`,
+`retry`, `expire`, `minimum`). Any other type returns records with a raw `data` string.
+
+#### `parseRecordData(type, data): Result<DoH.RecordData<Type>, RecordDataError>`
+
+The presentation-format reader `resolve` uses, for RDATA from anywhere else, such as a zone file.
+Reads RFC 3597 generic data (`\# 4 0A000001`) for the typed types too, which is how Cloudflare
+answers CAA. TXT bare words are separate character-strings, per RFC 1035.
+
+```typescript
+parseRecordData("TXT", '"v=DKIM1; p=AAA" "BBB"');
+// success({ type: "TXT", text: "v=DKIM1; p=AAABBB", strings: ["v=DKIM1; p=AAA", "BBB"] })
+```
+
+#### `verifyTxtRecord(name, expected, options?): Promise<Result<boolean, DoHError>>`
+
+Whether `name` publishes a TXT record whose joined text is exactly `expected`. A token split into
+several character-strings or escaped still matches. NXDOMAIN is `success(false)`, since a record not
+yet published is the ordinary state of a verification; every other failure stays a failure.
+
+#### `checkCname(name, target, options?): Promise<Result<boolean, DoHError>>`
+
+Whether `name` aliases `target`, directly or through further CNAMEs, compared case-insensitively and
+ignoring the trailing dot. It follows the chain one `CNAME` query per hop (up to eight, stopping on
+a loop), so it holds even when the target resolves to nothing. NXDOMAIN is `success(false)`.
+
+#### `CLOUDFLARE` / `GOOGLE`
+
+`{ url: "https://cloudflare-dns.com/dns-query", format: "json" }` and
+`{ url: "https://dns.google/resolve", format: "json" }`.
+
+#### Errors
+
+| Class                | When                                                                       | Extra field                                         |
+| -------------------- | -------------------------------------------------------------------------- | --------------------------------------------------- |
+| `DoHError`           | Base of every `resolve` failure                                            |                                                     |
+| `NameNotFoundError`  | RCODE 3, NXDOMAIN                                                          | `ttl`: the SOA's negative-caching TTL, or `null`    |
+| `ServerFailureError` | RCODE 2, SERVFAIL, DNSSEC validation failures included                     |                                                     |
+| `ResponseCodeError`  | Any other non-zero RCODE (FORMERR, NOTIMP, REFUSED)                        | `rcode`                                             |
+| `TransportError`     | Network error, timeout, abort, non-2xx, or a body that is not the envelope | `status`: the HTTP status, `null` when none arrived |
+| `RecordDataError`    | `parseRecordData` on data that does not fit the type                       |                                                     |
+
+#### `DoH` namespace
+
+Types only: `RecordType`, `Resolver`, `ResolveOptions`, `Answer<Type>`, `RecordFor<Type>`,
+`RecordData<Type>`, `RecordBase`, the nine record interfaces (`ARecord` through `SOARecord`), and
+`UnknownRecord`.
+
+## Pattern: Tell A Vanished Name From A Failing Resolver
+
+Keep NXDOMAIN and NODATA apart, and treat `TransportError` and `ServerFailureError` as unknown
+rather than as "no records".
+
+```typescript
+import { NameNotFoundError, resolve } from "@sdxc/doh";
+import { isFailure } from "@sdxc/result";
+
+let answer = await resolve("app.example.com", "A");
+if (isFailure(answer)) {
+	if (answer.error instanceof NameNotFoundError) return { records: [] };
+	return { error: answer.error.message }; // the resolver is having a bad minute
+}
+
+let viaAlias = answer.data.chain.length > 0;
+```
+
+## Pattern: Cache Through The Answer's TTL
+
+```typescript
+import { resolve } from "@sdxc/doh";
+import { isSuccess } from "@sdxc/result";
+
+let answer = await resolve(hostname, "A");
+if (isSuccess(answer)) {
+	let seconds = Math.max(answer.data.ttl ?? 60, 60);
+	await cache.put(`doh:A:${hostname}`, JSON.stringify(answer.data.records), {
+		expirationTtl: seconds,
+	});
+}
+```
+
+## Pattern: Confirm A SERVFAIL With A Second Resolver
+
+```typescript
+import { GOOGLE, resolve, ServerFailureError } from "@sdxc/doh";
+import { isFailure } from "@sdxc/result";
+
+let answer = await resolve(name, "TXT");
+if (isFailure(answer) && answer.error instanceof ServerFailureError) {
+	answer = await resolve(name, "TXT", { resolver: GOOGLE });
+}
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published,
+written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one
+release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no
+compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/doh": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every
+later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/character-strings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reads the character-strings of TXT RDATA in presentation format (RFC 1035 section 5.1):
+ * quoted strings keep their spaces, bare words split on whitespace, and `\"`, `\\` and
+ * `\DDD` escapes are decoded, so a resolver's quoting never leaks into the text.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { RecordDataError } from "./errors.js";
+/**
+ * Splits TXT presentation data into its character-strings. Escapes are decoded to octets
+ * and each string is read as UTF-8, so text a resolver writes as `\195\169` comes back as
+ * `é`. Fails on an unterminated quote or a decimal escape above 255.
+ *
+ * @param data - One or more quoted or bare character-strings.
+ * @returns The strings in order, empty strings included.
+ * @example readCharacterStrings('"v=DKIM1; p=AAA" "BBB"') // success(["v=DKIM1; p=AAA", "BBB"])
+ */
+export declare function readCharacterStrings(data: string): Result<string[], RecordDataError>;
+/** Decodes octets as UTF-8, the reading applied to every character-string. */
+export declare function decodeOctets(octets: Uint8Array): string;

package/dist/character-strings.js

@@ -0,0 +1,72 @@
+import { failure, success } from "@sdxc/result";
+import { RecordDataError } from "./errors.js";
+/** Decodes a character-string's octets as UTF-8, replacing invalid sequences with U+FFFD. */
+const DECODER = new TextDecoder();
+/** Encodes literal characters into the octets they stand for. */
+const ENCODER = new TextEncoder();
+/** Whether a character separates character-strings. */
+function isSpace(char) {
+    return char === " " || char === "\t" || char === "\n" || char === "\r";
+}
+/**
+ * Splits TXT presentation data into its character-strings. Escapes are decoded to octets
+ * and each string is read as UTF-8, so text a resolver writes as `\195\169` comes back as
+ * `é`. Fails on an unterminated quote or a decimal escape above 255.
+ *
+ * @param data - One or more quoted or bare character-strings.
+ * @returns The strings in order, empty strings included.
+ * @example readCharacterStrings('"v=DKIM1; p=AAA" "BBB"') // success(["v=DKIM1; p=AAA", "BBB"])
+ */
+export function readCharacterStrings(data) {
+    let chars = Array.from(data);
+    let strings = [];
+    let index = 0;
+    while (index < chars.length) {
+        if (isSpace(chars[index])) {
+            index += 1;
+            continue;
+        }
+        let quoted = chars[index] === '"';
+        if (quoted)
+            index += 1;
+        let octets = [];
+        let terminated = !quoted;
+        while (index < chars.length) {
+            let char = chars[index] ?? "";
+            if (quoted && char === '"') {
+                terminated = true;
+                index += 1;
+                break;
+            }
+            if (!quoted && isSpace(char))
+                break;
+            if (char === "\\") {
+                let digits = chars.slice(index + 1, index + 4).join("");
+                if (/^\d{3}$/.test(digits)) {
+                    let octet = Number(digits);
+                    if (octet > 255)
+                        return failure(new RecordDataError(`Invalid escape \\${digits} in TXT data`));
+                    octets.push(octet);
+                    index += 4;
+                    continue;
+                }
+                let next = chars[index + 1];
+                if (next === undefined)
+                    return failure(new RecordDataError("TXT data ends in a lone backslash"));
+                octets.push(...ENCODER.encode(next));
+                index += 2;
+                continue;
+            }
+            octets.push(...ENCODER.encode(char));
+            index += 1;
+        }
+        if (!terminated)
+            return failure(new RecordDataError("TXT data has an unterminated quoted string"));
+        strings.push(DECODER.decode(new Uint8Array(octets)));
+    }
+    return success(strings);
+}
+/** Decodes octets as UTF-8, the reading applied to every character-string. */
+export function decodeOctets(octets) {
+    return DECODER.decode(octets);
+}

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The failures a lookup returns, one class per meaning, so a caller tells "the name is
+ * gone" from "the resolver is down" with `instanceof` instead of matching messages.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Every failure `resolve` returns; `instanceof` on it narrows to a lookup failure. */
+export declare class DoHError extends Error {
+    name: string;
+}
+/** RCODE 3 (NXDOMAIN): the name does not exist. */
+export declare class NameNotFoundError extends DoHError {
+    name: string;
+    /**
+     * Seconds the absence may be cached: the smaller of the SOA's TTL and its minimum
+     * (RFC 2308), or `null` when the answer carried no SOA.
+     */
+    readonly ttl: number | null;
+    /**
+     * @param queried - The name that was looked up.
+     * @param ttl - The negative-caching TTL, when known.
+     */
+    constructor(queried: string, ttl: number | null);
+}
+/** RCODE 2 (SERVFAIL): the resolver could not answer, a DNSSEC validation failure included. */
+export declare class ServerFailureError extends DoHError {
+    name: string;
+    /** @param queried - The name that was looked up. */
+    constructor(queried: string);
+}
+/** Any other non-zero RCODE: FORMERR, NOTIMP, REFUSED and the rest. */
+export declare class ResponseCodeError extends DoHError {
+    name: string;
+    readonly rcode: number;
+    /**
+     * @param queried - The name that was looked up.
+     * @param rcode - The DNS response code the resolver returned.
+     */
+    constructor(queried: string, rcode: number);
+}
+/** The request produced no DNS answer: a network error, a timeout, a non-2xx, or a body that is not the envelope. */
+export declare class TransportError extends DoHError {
+    name: string;
+    /** The HTTP status when a response arrived, `null` when none did. */
+    readonly status: number | null;
+    /**
+     * @param message - What went wrong.
+     * @param status - The HTTP status, when a response arrived.
+     * @param options - The underlying error.
+     */
+    constructor(message: string, status: number | null, options?: ErrorOptions);
+}
+/** RDATA that does not parse for its type; `resolve` keeps such a record in `unparsed`. */
+export declare class RecordDataError extends Error {
+    name: string;
+}

package/dist/errors.js

@@ -0,0 +1,68 @@
+/**
+ * The failures a lookup returns, one class per meaning, so a caller tells "the name is
+ * gone" from "the resolver is down" with `instanceof` instead of matching messages.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Every failure `resolve` returns; `instanceof` on it narrows to a lookup failure. */
+export class DoHError extends Error {
+    name = "DoHError";
+}
+/** RCODE 3 (NXDOMAIN): the name does not exist. */
+export class NameNotFoundError extends DoHError {
+    name = "NameNotFoundError";
+    /**
+     * Seconds the absence may be cached: the smaller of the SOA's TTL and its minimum
+     * (RFC 2308), or `null` when the answer carried no SOA.
+     */
+    ttl;
+    /**
+     * @param queried - The name that was looked up.
+     * @param ttl - The negative-caching TTL, when known.
+     */
+    constructor(queried, ttl) {
+        super(`${queried} does not exist (NXDOMAIN)`);
+        this.ttl = ttl;
+    }
+}
+/** RCODE 2 (SERVFAIL): the resolver could not answer, a DNSSEC validation failure included. */
+export class ServerFailureError extends DoHError {
+    name = "ServerFailureError";
+    /** @param queried - The name that was looked up. */
+    constructor(queried) {
+        super(`The resolver failed to answer for ${queried} (SERVFAIL)`);
+    }
+}
+/** Any other non-zero RCODE: FORMERR, NOTIMP, REFUSED and the rest. */
+export class ResponseCodeError extends DoHError {
+    name = "ResponseCodeError";
+    rcode;
+    /**
+     * @param queried - The name that was looked up.
+     * @param rcode - The DNS response code the resolver returned.
+     */
+    constructor(queried, rcode) {
+        super(`The resolver answered ${queried} with response code ${rcode}`);
+        this.rcode = rcode;
+    }
+}
+/** The request produced no DNS answer: a network error, a timeout, a non-2xx, or a body that is not the envelope. */
+export class TransportError extends DoHError {
+    name = "TransportError";
+    /** The HTTP status when a response arrived, `null` when none did. */
+    status;
+    /**
+     * @param message - What went wrong.
+     * @param status - The HTTP status, when a response arrived.
+     * @param options - The underlying error.
+     */
+    constructor(message, status, options) {
+        super(message, options);
+        this.status = status;
+    }
+}
+/** RDATA that does not parse for its type; `resolve` keeps such a record in `unparsed`. */
+export class RecordDataError extends Error {
+    name = "RecordDataError";
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed DNS-over-HTTPS lookups for runtimes with no DNS socket, such as Cloudflare Workers:
+ * `resolve` returns records typed per query type and distinct failures for NXDOMAIN,
+ * SERVFAIL and transport errors, beside the TXT and CNAME checks domain verification needs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type { DoH } from "./types.js";
+export { DoHError, NameNotFoundError, RecordDataError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
+export { parseRecordData } from "./parse-record-data.js";
+export { resolve } from "./resolve.js";
+export { CLOUDFLARE, GOOGLE } from "./resolvers.js";
+export { checkCname, verifyTxtRecord } from "./verify.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Typed DNS-over-HTTPS lookups for runtimes with no DNS socket, such as Cloudflare Workers:
+ * `resolve` returns records typed per query type and distinct failures for NXDOMAIN,
+ * SERVFAIL and transport errors, beside the TXT and CNAME checks domain verification needs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { DoHError, NameNotFoundError, RecordDataError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
+export { parseRecordData } from "./parse-record-data.js";
+export { resolve } from "./resolve.js";
+export { CLOUDFLARE, GOOGLE } from "./resolvers.js";
+export { checkCname, verifyTxtRecord } from "./verify.js";

package/dist/parse-record-data.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reads record data in presentation format, as a DoH JSON answer or a zone file writes it,
+ * into typed fields per record type. RFC 3597 generic data (`\# len hex`) is decoded from
+ * its wire form, which is how some resolvers answer types such as CAA.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { DoH } from "./types.js";
+import { RecordDataError } from "./errors.js";
+/**
+ * Reads a record's data into its typed fields. Types without a typed reading come back
+ * as `{ type, data }` with the data unchanged. Names are lowercased without the trailing
+ * dot, except the root, which stays `"."`.
+ *
+ * @param type - The record type, as a mnemonic or RFC 3597 `TYPEnnn`.
+ * @param data - The RDATA in presentation format.
+ * @returns The record's fields, or why the data does not fit the type.
+ * @template Type - The record type, which selects the fields returned.
+ * @example parseRecordData("MX", "10 mx.example.com.") // success({ type: "MX", preference: 10, exchange: "mx.example.com" })
+ */
+export declare function parseRecordData<Type extends DoH.RecordType>(type: Type, data: string): Result<DoH.RecordData<Type>, RecordDataError>;

package/dist/parse-record-data.js

@@ -0,0 +1,283 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { decodeOctets, readCharacterStrings } from "./character-strings.js";
+import { RecordDataError } from "./errors.js";
+import { canonicalType } from "./record-types.js";
+/**
+ * A dotted-quad IPv4 address without leading zeros, which `inet_aton` would read as octal
+ * and browsers as decimal, so an address carrying them has no single meaning.
+ */
+const IPV4_PATTERN = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+/**
+ * Reads a record's data into its typed fields. Types without a typed reading come back
+ * as `{ type, data }` with the data unchanged. Names are lowercased without the trailing
+ * dot, except the root, which stays `"."`.
+ *
+ * @param type - The record type, as a mnemonic or RFC 3597 `TYPEnnn`.
+ * @param data - The RDATA in presentation format.
+ * @returns The record's fields, or why the data does not fit the type.
+ * @template Type - The record type, which selects the fields returned.
+ * @example parseRecordData("MX", "10 mx.example.com.") // success({ type: "MX", preference: 10, exchange: "mx.example.com" })
+ */
+export function parseRecordData(type, data) {
+    let canonical = canonicalType(type);
+    let value = data.trim();
+    let parsed = value.startsWith("\\#")
+        ? parseGeneric(canonical, value)
+        : parsePresentation(canonical, value);
+    return parsed;
+}
+/** Fails with the reason a record's data does not fit its type. */
+function invalid(type, data) {
+    return failure(new RecordDataError(`Invalid ${type} record data: ${JSON.stringify(data)}`));
+}
+/** Folds a domain name: lowercased, trailing dot dropped, the root kept as `"."`. */
+function normalizeName(name) {
+    let lower = name.toLowerCase();
+    return lower.length > 1 && lower.endsWith(".") ? lower.slice(0, -1) : lower;
+}
+/** Reads an unsigned decimal field no larger than `max`, or `null`. */
+function readNumber(field, max) {
+    if (field === undefined || !/^\d+$/.test(field))
+        return null;
+    let number = Number(field);
+    return number <= max ? number : null;
+}
+/** An IPv6 literal in RFC 5952 canonical form, or `null` when the text is not one. */
+function canonicalIpv6(value) {
+    if (!value.includes(":"))
+        return null;
+    let url = URL.parse(`http://[${value}]/`);
+    return url ? url.hostname.slice(1, -1) : null;
+}
+/** Reads presentation-format data for the typed record types. */
+function parsePresentation(type, value) {
+    let fields = value.split(/\s+/).filter((field) => field.length > 0);
+    switch (type) {
+        case "A":
+            return IPV4_PATTERN.test(value) ? success({ type, address: value }) : invalid(type, value);
+        case "AAAA": {
+            let address = canonicalIpv6(value);
+            return address ? success({ type, address }) : invalid(type, value);
+        }
+        case "CNAME":
+        case "NS": {
+            if (fields.length !== 1 || fields[0] === undefined)
+                return invalid(type, value);
+            let name = normalizeName(fields[0]);
+            return success(type === "CNAME" ? { type, target: name } : { type, host: name });
+        }
+        case "MX": {
+            let preference = readNumber(fields[0], 0xffff);
+            if (fields.length !== 2 || preference === null || fields[1] === undefined)
+                return invalid(type, value);
+            return success({ type, preference, exchange: normalizeName(fields[1]) });
+        }
+        case "TXT": {
+            let strings = readCharacterStrings(value);
+            if (isFailure(strings))
+                return strings;
+            return success({ type, text: strings.data.join(""), strings: strings.data });
+        }
+        case "CAA": {
+            let match = /^(\d+)\s+([A-Za-z0-9]+)\s+(.+)$/.exec(value);
+            let flags = readNumber(match?.[1], 0xff);
+            if (!match || flags === null || match[2] === undefined || match[3] === undefined)
+                return invalid(type, value);
+            let raw = match[3];
+            let text = raw;
+            if (raw.startsWith('"')) {
+                let strings = readCharacterStrings(raw);
+                if (isFailure(strings))
+                    return strings;
+                text = strings.data.join("");
+            }
+            return success({
+                type,
+                critical: (flags & 0x80) !== 0,
+                tag: match[2].toLowerCase(),
+                value: text,
+            });
+        }
+        case "SRV": {
+            let [priority, weight, port] = fields.slice(0, 3).map((field) => readNumber(field, 0xffff));
+            let target = fields[3];
+            if (fields.length !== 4 ||
+                priority == null ||
+                weight == null ||
+                port == null ||
+                target === undefined) {
+                return invalid(type, value);
+            }
+            return success({ type, priority, weight, port, target: normalizeName(target) });
+        }
+        case "SOA": {
+            let [primary, mailbox] = fields;
+            let numbers = fields.slice(2).map((field) => readNumber(field, 0xffffffff));
+            if (fields.length !== 7 ||
+                primary === undefined ||
+                mailbox === undefined ||
+                numbers.some((n) => n === null)) {
+                return invalid(type, value);
+            }
+            let [serial, refresh, retry, expire, minimum] = numbers;
+            return success({
+                type,
+                primary: normalizeName(primary),
+                mailbox: normalizeName(mailbox),
+                serial,
+                refresh,
+                retry,
+                expire,
+                minimum,
+            });
+        }
+        default:
+            return success({ type, data: value });
+    }
+}
+/** Decodes RFC 3597 generic data (`\# <length> <hex>`) and reads the octets for the type. */
+function parseGeneric(type, value) {
+    let match = /^\\#\s+(\d+)((?:\s*[0-9a-fA-F]+)*)\s*$/.exec(value);
+    if (!match)
+        return invalid(type, value);
+    let hex = (match[2] ?? "").replace(/\s+/g, "");
+    let length = Number(match[1]);
+    if (hex.length !== length * 2)
+        return invalid(type, value);
+    let octets = new Uint8Array(length);
+    for (let index = 0; index < length; index++)
+        octets[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    let fields = new WireReader(octets).record(type);
+    if (fields === "unknown")
+        return success({ type, data: value });
+    return fields ? success({ type, ...fields }) : invalid(type, value);
+}
+/**
+ * Reads the wire form of RDATA front to back. Every read returns `null` past the end, and a
+ * record parses only when it consumes every octet, since trailing bytes mean a wrong type.
+ */
+class WireReader {
+    #octets;
+    #offset = 0;
+    /** @param octets - The RDATA octets. */
+    constructor(octets) {
+        this.#octets = octets;
+    }
+    /**
+     * The typed fields for `type`, `null` when the octets do not fit it, or `"unknown"` for a
+     * type without a typed reading.
+     */
+    record(type) {
+        let fields = this.#fields(type);
+        if (fields === null || fields === "unknown")
+            return fields;
+        return this.#offset === this.#octets.length ? fields : null;
+    }
+    /** Reads the type's fields, leaving the offset after the last octet read. */
+    #fields(type) {
+        switch (type) {
+            case "A": {
+                let bytes = this.#bytes(4);
+                return bytes ? { address: Array.from(bytes).join(".") } : null;
+            }
+            case "AAAA": {
+                let bytes = this.#bytes(16);
+                if (!bytes)
+                    return null;
+                let groups = Array.from({ length: 8 }, (_, index) => (((bytes[index * 2] ?? 0) << 8) | (bytes[index * 2 + 1] ?? 0)).toString(16));
+                return { address: canonicalIpv6(groups.join(":")) ?? groups.join(":") };
+            }
+            case "CNAME": {
+                let target = this.#name();
+                return target === null ? null : { target };
+            }
+            case "NS": {
+                let host = this.#name();
+                return host === null ? null : { host };
+            }
+            case "MX": {
+                let preference = this.#uint(2);
+                let exchange = this.#name();
+                return preference === null || exchange === null ? null : { preference, exchange };
+            }
+            case "TXT": {
+                let strings = [];
+                while (this.#offset < this.#octets.length) {
+                    let length = this.#uint(1);
+                    let bytes = length === null ? null : this.#bytes(length);
+                    if (!bytes)
+                        return null;
+                    strings.push(decodeOctets(bytes));
+                }
+                return { text: strings.join(""), strings };
+            }
+            case "CAA": {
+                let flags = this.#uint(1);
+                let tagLength = this.#uint(1);
+                let tag = tagLength === null ? null : this.#bytes(tagLength);
+                if (flags === null || !tag)
+                    return null;
+                let rest = this.#bytes(this.#octets.length - this.#offset) ?? new Uint8Array();
+                return {
+                    critical: (flags & 0x80) !== 0,
+                    tag: decodeOctets(tag).toLowerCase(),
+                    value: decodeOctets(rest),
+                };
+            }
+            case "SRV": {
+                let priority = this.#uint(2);
+                let weight = this.#uint(2);
+                let port = this.#uint(2);
+                let target = this.#name();
+                if (priority === null || weight === null || port === null || target === null)
+                    return null;
+                return { priority, weight, port, target };
+            }
+            case "SOA": {
+                let primary = this.#name();
+                let mailbox = this.#name();
+                let numbers = Array.from({ length: 5 }, () => this.#uint(4));
+                if (primary === null || mailbox === null || numbers.some((n) => n === null))
+                    return null;
+                let [serial, refresh, retry, expire, minimum] = numbers;
+                return { primary, mailbox, serial, refresh, retry, expire, minimum };
+            }
+            default:
+                return "unknown";
+        }
+    }
+    /** The next `length` octets, or `null` past the end. */
+    #bytes(length) {
+        if (this.#offset + length > this.#octets.length)
+            return null;
+        let bytes = this.#octets.subarray(this.#offset, this.#offset + length);
+        this.#offset += length;
+        return bytes;
+    }
+    /** A big-endian unsigned integer of `size` octets. */
+    #uint(size) {
+        let bytes = this.#bytes(size);
+        if (!bytes)
+            return null;
+        return bytes.reduce((total, byte) => total * 256 + byte, 0);
+    }
+    /**
+     * An uncompressed domain name, folded like presentation names. RFC 3597 forbids
+     * compression in generic data, so a compression pointer fails the read.
+     */
+    #name() {
+        let labels = [];
+        while (true) {
+            let length = this.#uint(1);
+            if (length === null || length > 63)
+                return null;
+            if (length === 0)
+                break;
+            let label = this.#bytes(length);
+            if (!label)
+                return null;
+            labels.push(String.fromCharCode(...label));
+        }
+        return labels.length === 0 ? "." : normalizeName(labels.join("."));
+    }
+}

package/dist/record-types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Maps record type mnemonics to the IANA codes the JSON API writes in `type`, and back,
+ * with RFC 3597's `TYPEnnn` spelling for any code without a mnemonic here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The mnemonic for a type code, or `TYPEnnn` when it has none here. */
+export declare function typeName(code: number): string;
+/**
+ * The spelling of a type as the query's `type` parameter and as a record's `type`: the
+ * uppercase mnemonic, and a known mnemonic for `TYPEnnn` when one exists.
+ */
+export declare function canonicalType(type: string): string;

package/dist/record-types.js

@@ -0,0 +1,54 @@
+/**
+ * Maps record type mnemonics to the IANA codes the JSON API writes in `type`, and back,
+ * with RFC 3597's `TYPEnnn` spelling for any code without a mnemonic here.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The IANA codes of the record types a caller is likely to ask for or see in an answer. */
+const TYPE_CODES = {
+    A: 1,
+    NS: 2,
+    CNAME: 5,
+    SOA: 6,
+    PTR: 12,
+    HINFO: 13,
+    MX: 15,
+    TXT: 16,
+    AAAA: 28,
+    LOC: 29,
+    SRV: 33,
+    NAPTR: 35,
+    DNAME: 39,
+    DS: 43,
+    SSHFP: 44,
+    RRSIG: 46,
+    NSEC: 47,
+    DNSKEY: 48,
+    NSEC3: 50,
+    NSEC3PARAM: 51,
+    TLSA: 52,
+    SMIMEA: 53,
+    CDS: 59,
+    CDNSKEY: 60,
+    OPENPGPKEY: 61,
+    SVCB: 64,
+    HTTPS: 65,
+    URI: 256,
+    CAA: 257,
+};
+/** The mnemonic for each code in {@link TYPE_CODES}. */
+const TYPE_NAMES = new Map(Object.entries(TYPE_CODES).map(([name, code]) => [code, name]));
+/** The mnemonic for a type code, or `TYPEnnn` when it has none here. */
+export function typeName(code) {
+    return TYPE_NAMES.get(code) ?? `TYPE${code}`;
+}
+/**
+ * The spelling of a type as the query's `type` parameter and as a record's `type`: the
+ * uppercase mnemonic, and a known mnemonic for `TYPEnnn` when one exists.
+ */
+export function canonicalType(type) {
+    let upper = type.trim().toUpperCase();
+    let generic = /^TYPE(\d+)$/.exec(upper);
+    return generic ? typeName(Number(generic[1])) : upper;
+}

package/dist/resolve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Looks a name up over the DoH JSON API: one `fetch` to the resolver, the envelope
+ * validated, the RCODE classified into a typed failure, and the answer split into the
+ * records of the asked type and the CNAME chain that led to them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { DoHError } from "./errors.js";
+import type { DoH } from "./types.js";
+/**
+ * Resolves `name`'s records of `type`. NXDOMAIN, SERVFAIL, any other RCODE and a request
+ * that never produced an answer are distinct `DoHError` subclasses; a name that exists
+ * with no records of the type succeeds with none. The name is sent as written, so an
+ * internationalized name must already be in its ASCII form.
+ *
+ * @param name - The domain name to look up.
+ * @param type - The record type, as a mnemonic or RFC 3597 `TYPEnnn`.
+ * @param options - Resolver, DNSSEC flags, abort signal and timeout.
+ * @returns The answer, or the typed reason there is none.
+ * @template Type - The record type, which types the records returned.
+ * @example let answer = await resolve("example.com", "MX");
+ */
+export declare function resolve<Type extends DoH.RecordType>(name: string, type: Type, options?: DoH.ResolveOptions): Promise<Result<DoH.Answer<Type>, DoHError>>;

package/dist/resolve.js

@@ -0,0 +1,138 @@
+import { failure, isSuccess, success } from "@sdxc/result";
+import * as s from "remix/data-schema";
+import { NameNotFoundError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
+import { parseRecordData } from "./parse-record-data.js";
+import { canonicalType, typeName } from "./record-types.js";
+import { CLOUDFLARE } from "./resolvers.js";
+/** One resource record as the JSON API writes it. */
+const WIRE_RECORD_SCHEMA = s.object({
+    name: s.string(),
+    type: s.number(),
+    TTL: s.number(),
+    data: s.string(),
+});
+/** The members of the JSON envelope this package reads; Cloudflare and Google both send them. */
+const ENVELOPE_SCHEMA = s.object({
+    Status: s.number(),
+    TC: s.optional(s.boolean()),
+    AD: s.optional(s.boolean()),
+    Answer: s.optional(s.array(WIRE_RECORD_SCHEMA)),
+    Authority: s.optional(s.array(WIRE_RECORD_SCHEMA)),
+});
+/** Folds a name the way every owner name in an answer is reported. */
+function normalizeName(name) {
+    let lower = name.toLowerCase();
+    return lower.length > 1 && lower.endsWith(".") ? lower.slice(0, -1) : lower;
+}
+/**
+ * Resolves `name`'s records of `type`. NXDOMAIN, SERVFAIL, any other RCODE and a request
+ * that never produced an answer are distinct `DoHError` subclasses; a name that exists
+ * with no records of the type succeeds with none. The name is sent as written, so an
+ * internationalized name must already be in its ASCII form.
+ *
+ * @param name - The domain name to look up.
+ * @param type - The record type, as a mnemonic or RFC 3597 `TYPEnnn`.
+ * @param options - Resolver, DNSSEC flags, abort signal and timeout.
+ * @returns The answer, or the typed reason there is none.
+ * @template Type - The record type, which types the records returned.
+ * @example let answer = await resolve("example.com", "MX");
+ */
+export async function resolve(name, type, options = {}) {
+    let resolver = options.resolver ?? CLOUDFLARE;
+    let timeoutMs = options.timeoutMs ?? 5000;
+    let asked = canonicalType(type);
+    let url = new URL(resolver.url);
+    url.searchParams.set("name", name);
+    url.searchParams.set("type", /^TYPE\d+$/.test(asked) ? asked.slice(4) : asked);
+    if (options.dnssec)
+        url.searchParams.set("do", "1");
+    if (options.checkingDisabled)
+        url.searchParams.set("cd", "1");
+    let timeout = AbortSignal.timeout(timeoutMs);
+    let signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+    let started = performance.now();
+    let envelope = await fetchEnvelope(url, signal, timeout, timeoutMs);
+    if (!isSuccess(envelope))
+        return envelope;
+    let durationMs = Math.round(performance.now() - started);
+    let { Status: rcode } = envelope.data;
+    if (rcode === 3)
+        return failure(new NameNotFoundError(name, negativeTtl(envelope.data)));
+    if (rcode === 2)
+        return failure(new ServerFailureError(name));
+    if (rcode !== 0)
+        return failure(new ResponseCodeError(name, rcode));
+    let records = [];
+    let unparsed = [];
+    let chain = [];
+    for (let record of envelope.data.Answer ?? []) {
+        let recordType = typeName(record.type);
+        if (recordType !== asked && recordType !== "CNAME")
+            continue;
+        let base = { name: normalizeName(record.name), ttl: record.TTL };
+        let data = parseRecordData(recordType, record.data);
+        if (recordType === asked) {
+            if (isSuccess(data))
+                records.push({ ...base, ...data.data });
+            else
+                unparsed.push({ ...base, type: recordType, data: record.data });
+        }
+        else if (isSuccess(data)) {
+            chain.push({ ...base, ...data.data });
+        }
+    }
+    let ttls = [...records, ...unparsed].map((record) => record.ttl);
+    return success({
+        name: normalizeName(name),
+        type,
+        records,
+        unparsed,
+        chain,
+        ttl: ttls.length > 0 ? Math.min(...ttls) : null,
+        authenticated: envelope.data.AD ?? false,
+        truncated: envelope.data.TC ?? false,
+        durationMs,
+    });
+}
+/**
+ * Sends the query and validates the envelope, mapping every way the exchange can fail
+ * without a DNS answer to a `TransportError`.
+ */
+async function fetchEnvelope(url, signal, timeout, timeoutMs) {
+    let response;
+    try {
+        response = await fetch(url, { headers: { Accept: "application/dns-json" }, signal });
+    }
+    catch (error) {
+        let message = timeout.aborted
+            ? `The DNS query timed out after ${timeoutMs}ms`
+            : `The DNS query failed: ${error instanceof Error ? error.message : String(error)}`;
+        return failure(new TransportError(message, null, { cause: error }));
+    }
+    if (!response.ok) {
+        return failure(new TransportError(`The resolver answered HTTP ${response.status}`, response.status));
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        return failure(new TransportError("The resolver's response is not JSON", response.status, { cause: error }));
+    }
+    let parsed = s.parseSafe(ENVELOPE_SCHEMA, body);
+    if (!parsed.success) {
+        return failure(new TransportError("The resolver's response is not a DNS JSON answer", response.status));
+    }
+    return success(parsed.value);
+}
+/**
+ * The negative-caching TTL of an NXDOMAIN (RFC 2308 section 5): the smaller of the SOA
+ * record's own TTL and its `minimum` field, or `null` without a readable SOA.
+ */
+function negativeTtl(envelope) {
+    let soa = (envelope.Authority ?? []).find((record) => typeName(record.type) === "SOA");
+    if (!soa)
+        return null;
+    let data = parseRecordData("SOA", soa.data);
+    return isSuccess(data) ? Math.min(soa.TTL, data.data.minimum) : null;
+}

package/dist/resolvers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The public resolvers that answer the DoH JSON API, ready to pass as `resolver`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DoH } from "./types.js";
+/** Cloudflare's 1.1.1.1, the default resolver; it answers JSON when asked with `Accept: application/dns-json`. */
+export declare const CLOUDFLARE: DoH.Resolver;
+/** Google Public DNS, which answers JSON at `/resolve` regardless of `Accept`. */
+export declare const GOOGLE: DoH.Resolver;

package/dist/resolvers.js

@@ -0,0 +1,7 @@
+/** Cloudflare's 1.1.1.1, the default resolver; it answers JSON when asked with `Accept: application/dns-json`. */
+export const CLOUDFLARE = {
+    url: "https://cloudflare-dns.com/dns-query",
+    format: "json",
+};
+/** Google Public DNS, which answers JSON at `/resolve` regardless of `Accept`. */
+export const GOOGLE = { url: "https://dns.google/resolve", format: "json" };

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The types a DNS-over-HTTPS lookup reads and returns: the resolver it talks to, one
+ * interface per typed record, and the answer that splits records of the asked type from
+ * the CNAME chain that led to them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Groups the DNS-over-HTTPS types under a single import surface.
+ */
+export declare namespace DoH {
+    /** A record type by mnemonic; the nine typed ones autocomplete, any other name is accepted. */
+    type RecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "CAA" | "SOA" | "SRV" | (string & {});
+    /**
+     * A DoH endpoint and the encoding it answers in. `format` leaves room for an RFC 8484
+     * `application/dns-message` resolver as a new value with no change to `resolve`.
+     */
+    interface Resolver {
+        url: string;
+        format: "json";
+    }
+    /** What every record carries. */
+    interface RecordBase {
+        /** The owner name, lowercased and without the trailing dot. */
+        name: string;
+        /** Seconds the resolver allows the record to be cached. */
+        ttl: number;
+    }
+    /** An IPv4 address, in dotted-quad form. */
+    interface ARecord extends RecordBase {
+        type: "A";
+        address: string;
+    }
+    /** An IPv6 address. */
+    interface AAAARecord extends RecordBase {
+        type: "AAAA";
+        /** In RFC 5952 canonical form: lowercase, zero runs compressed. */
+        address: string;
+    }
+    /** An alias: `name` resolves as `target` does. */
+    interface CNAMERecord extends RecordBase {
+        type: "CNAME";
+        target: string;
+    }
+    /** A name server authoritative for the zone at `name`. */
+    interface NSRecord extends RecordBase {
+        type: "NS";
+        host: string;
+    }
+    /** A mail exchanger; lower `preference` values are tried first. */
+    interface MXRecord extends RecordBase {
+        type: "MX";
+        preference: number;
+        /** The mail host; `"."` is an RFC 7505 null MX, a domain that accepts no mail. */
+        exchange: string;
+    }
+    /** Free text, such as SPF policies, DKIM keys and verification tokens. */
+    interface TXTRecord extends RecordBase {
+        type: "TXT";
+        /** The character-strings concatenated with nothing between them, as SPF and DKIM read it. */
+        text: string;
+        /** The character-strings as published, for the rare record whose boundaries matter. */
+        strings: string[];
+    }
+    /** Which certificate authorities may issue for the name (RFC 8659). */
+    interface CAARecord extends RecordBase {
+        type: "CAA";
+        /** The issuer-critical flag: a CA that does not understand `tag` must refuse to issue. */
+        critical: boolean;
+        tag: string;
+        value: string;
+    }
+    /** Where a service runs; lower `priority` first, `weight` spreads load within one priority. */
+    interface SRVRecord extends RecordBase {
+        type: "SRV";
+        priority: number;
+        weight: number;
+        port: number;
+        target: string;
+    }
+    /** The zone's start of authority, found at its apex and in negative answers. */
+    interface SOARecord extends RecordBase {
+        type: "SOA";
+        primary: string;
+        /** The responsible mailbox in DNS form: its first label is the local part. */
+        mailbox: string;
+        serial: number;
+        refresh: number;
+        retry: number;
+        expire: number;
+        /** Bounds how long a negative answer may be cached (RFC 2308). */
+        minimum: number;
+    }
+    /** A record of a type without a typed reading, or one whose data failed to parse, with its raw RDATA. */
+    interface UnknownRecord extends RecordBase {
+        type: string;
+        data: string;
+    }
+    /** The record a query for `Type` returns. */
+    type RecordFor<Type extends RecordType> = Type extends "A" ? ARecord : Type extends "AAAA" ? AAAARecord : Type extends "CNAME" ? CNAMERecord : Type extends "TXT" ? TXTRecord : Type extends "MX" ? MXRecord : Type extends "NS" ? NSRecord : Type extends "CAA" ? CAARecord : Type extends "SOA" ? SOARecord : Type extends "SRV" ? SRVRecord : UnknownRecord;
+    /** A record's type-specific fields, what `parseRecordData` reads out of RDATA. */
+    type RecordData<Type extends RecordType> = Omit<RecordFor<Type>, "name" | "ttl">;
+    /** A successful (NOERROR) answer to one query. */
+    interface Answer<Type extends RecordType> {
+        /** The queried name, lowercased and without the trailing dot. */
+        name: string;
+        type: Type;
+        /** The records of the asked type; empty with an empty `unparsed` is NODATA. */
+        records: RecordFor<Type>[];
+        /** Records of the asked type whose data did not parse, kept with their raw RDATA. */
+        unparsed: UnknownRecord[];
+        /** The aliases followed before reaching `records`, in order. */
+        chain: CNAMERecord[];
+        /** The smallest TTL across `records` and `unparsed`, `null` when both are empty. */
+        ttl: number | null;
+        /** The AD flag: the resolver validated the answer with DNSSEC. */
+        authenticated: boolean;
+        /** The TC flag: the resolver's upstream answer was truncated. */
+        truncated: boolean;
+        durationMs: number;
+    }
+    /** Options for one lookup. */
+    interface ResolveOptions {
+        /**
+         * @default CLOUDFLARE
+         */
+        resolver?: Resolver;
+        /** Sets `do=1`, asking for DNSSEC records alongside the answer. */
+        dnssec?: boolean;
+        /** Sets `cd=1`, asking the resolver to skip DNSSEC validation. */
+        checkingDisabled?: boolean;
+        signal?: AbortSignal;
+        /**
+         * Milliseconds before the request is abandoned as a `TransportError`.
+         *
+         * @default 5000
+         */
+        timeoutMs?: number;
+    }
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * The types a DNS-over-HTTPS lookup reads and returns: the resolver it talks to, one
+ * interface per typed record, and the answer that splits records of the asked type from
+ * the CNAME chain that led to them.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */

package/dist/verify.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The two DNS checks a domain-ownership flow performs: a TXT token published at a name,
+ * and a CNAME pointing a name at a target. A name that does not exist yet is the ordinary
+ * state of a verification in progress, so NXDOMAIN reads as "not verified".
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { DoHError } from "./errors.js";
+import type { DoH } from "./types.js";
+/**
+ * Whether `name` publishes a TXT record whose joined text is exactly `expected`, so a
+ * token a resolver splits into several character-strings, or escapes, still matches.
+ * NXDOMAIN is `success(false)`; every other lookup failure stays a failure.
+ *
+ * @param name - The name holding the token, such as `_verify.example.com`.
+ * @param expected - The token, compared exactly.
+ * @param options - Passed to `resolve`.
+ * @example await verifyTxtRecord("_verify.example.com", "token_abc123") // success(true)
+ */
+export declare function verifyTxtRecord(name: string, expected: string, options?: DoH.ResolveOptions): Promise<Result<boolean, DoHError>>;
+/**
+ * Whether `name` is a CNAME to `target`, directly or through further aliases, compared
+ * case-insensitively without the trailing dot. The chain is followed one CNAME query per
+ * hop, up to eight, so the check holds even when the target itself resolves to nothing.
+ * NXDOMAIN at any hop is `success(false)`; every other lookup failure stays a failure.
+ *
+ * @param name - The name the customer points, such as `shop.example.com`.
+ * @param target - The host it must alias.
+ * @param options - Passed to `resolve`.
+ * @example await checkCname("shop.example.com", "custom.hosting.example") // success(true)
+ */
+export declare function checkCname(name: string, target: string, options?: DoH.ResolveOptions): Promise<Result<boolean, DoHError>>;

package/dist/verify.js

@@ -0,0 +1,57 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { NameNotFoundError } from "./errors.js";
+import { resolve } from "./resolve.js";
+/** How many aliases `checkCname` follows before giving up, bounding a long or looping chain. */
+const MAX_CNAME_HOPS = 8;
+/** Folds a name for comparison: lowercased, trailing dot dropped. */
+function normalizeName(name) {
+    let lower = name.trim().toLowerCase();
+    return lower.length > 1 && lower.endsWith(".") ? lower.slice(0, -1) : lower;
+}
+/**
+ * Whether `name` publishes a TXT record whose joined text is exactly `expected`, so a
+ * token a resolver splits into several character-strings, or escapes, still matches.
+ * NXDOMAIN is `success(false)`; every other lookup failure stays a failure.
+ *
+ * @param name - The name holding the token, such as `_verify.example.com`.
+ * @param expected - The token, compared exactly.
+ * @param options - Passed to `resolve`.
+ * @example await verifyTxtRecord("_verify.example.com", "token_abc123") // success(true)
+ */
+export async function verifyTxtRecord(name, expected, options) {
+    let answer = await resolve(name, "TXT", options);
+    if (isFailure(answer))
+        return answer.error instanceof NameNotFoundError ? success(false) : answer;
+    return success(answer.data.records.some((record) => record.text === expected));
+}
+/**
+ * Whether `name` is a CNAME to `target`, directly or through further aliases, compared
+ * case-insensitively without the trailing dot. The chain is followed one CNAME query per
+ * hop, up to eight, so the check holds even when the target itself resolves to nothing.
+ * NXDOMAIN at any hop is `success(false)`; every other lookup failure stays a failure.
+ *
+ * @param name - The name the customer points, such as `shop.example.com`.
+ * @param target - The host it must alias.
+ * @param options - Passed to `resolve`.
+ * @example await checkCname("shop.example.com", "custom.hosting.example") // success(true)
+ */
+export async function checkCname(name, target, options) {
+    let wanted = normalizeName(target);
+    let current = normalizeName(name);
+    let seen = new Set();
+    for (let hop = 0; hop < MAX_CNAME_HOPS && !seen.has(current); hop++) {
+        seen.add(current);
+        let answer = await resolve(current, "CNAME", options);
+        if (isFailure(answer)) {
+            return answer.error instanceof NameNotFoundError ? success(false) : failure(answer.error);
+        }
+        let targets = answer.data.records.map((record) => record.target);
+        if (targets.includes(wanted))
+            return success(true);
+        let next = targets[0];
+        if (next === undefined)
+            return success(false);
+        current = next;
+    }
+    return success(false);
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+	"name": "@sdxc/doh",
+	"version": "0.0.0-pre.1",
+	"description": "Typed DNS over HTTPS lookups",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js"
+	},
+	"dependencies": {
+		"@sdxc/result": "2026.9.15",
+		"remix": "3.0.0-rc.2"
+	},
+	"gitHead": "f0a77f407e4c30389df65cd8138b150e367da94f",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sergiodxa/monorepo.git",
+		"directory": "packages/doh"
+	}
+}