@sdxc/doh 2026.10.16 → 2026.10.25

package/README.md

@@ -82,22 +82,28 @@ if (!verdict.allowed) verdict.reason; // "not-authorized", "forbidden", "lookup-
 Looks up `name`'s records of `type` with one `fetch` and no state. Send an internationalized name
 in its ASCII (punycode) form. Options:
 
-- `resolver`: `CLOUDFLARE` (default), `GOOGLE`, or any `{ url, format: "json" }`
-- `dnssec`: sets `do=1`
-- `checkingDisabled`: sets `cd=1`
+- `resolver`: `CLOUDFLARE` (default), `GOOGLE`, their RFC 8484 wire-format endpoints
+  `CLOUDFLARE_WIRE` and `GOOGLE_WIRE`, or any `{ url, format: "json" | "wire" }`
+- `dnssec`: sets the DO bit
+- `checkingDisabled`: sets the CD bit
 - `signal`: aborts the request
 - `timeoutMs`: abandons the request as a `TransportError`, default `5000`
 
 The answer holds `records`, `unparsed` (records of the type whose data did not parse, with their
 raw `data`), `chain` (the CNAMEs followed to reach `records`), `ttl` (smallest across `records`
 and `unparsed`, `null` when both are empty), `authenticated` (the AD flag), `truncated` (the TC
-flag), `name`, `type` and `durationMs`. Names come back lowercased without the trailing dot, and
+flag), `extendedErrors` (RFC 8914 `{ code, text }` from a `"wire"` resolver), `name`, `type` and
+`durationMs`. Names come back lowercased without the trailing dot, and
 AAAA addresses in RFC 5952 form.
 
 Typed record fields: `A` and `AAAA` (`address`), `CNAME`, `PTR` and `DNAME` (`target`), `NS`
 (`host`), `MX` (`preference`, `exchange`), `TXT` (`text`, `strings`), `CAA` (`flags`, `critical`,
 `tag`, `value`), `SRV` (`priority`, `weight`, `port`, `target`), `SOA` (`primary`, `mailbox`,
-`serial`, `refresh`, `retry`, `expire`, `minimum`). Any other type gives a raw `data` string.
+`serial`, `refresh`, `retry`, `expire`, `minimum`), `SVCB` and `HTTPS` (`priority`, `target`,
+`params`), `TLSA` (`usage`, `selector`, `matchingType`, `certificateAssociation`), `DS` and `CDS`
+(`keyTag`, `algorithm`, `digestType`, `digest`), `DNSKEY` and `CDNSKEY` (`flags`, `zoneKey`,
+`secureEntryPoint`, `protocol`, `algorithm`, `publicKey`, `keyTag`). Any other type gives a raw
+`data` string.
 
 ### `verifyTxtRecord(name, expected, options?): Promise<Result<boolean, DoHError>>`
 
@@ -110,19 +116,21 @@ Whether `name` aliases `target`, directly or through up to eight CNAME hops, com
 case-insensitively without the trailing dot. It holds even when the target resolves to nothing.
 NXDOMAIN is `success(false)`.
 
-### `CLOUDFLARE` / `GOOGLE`
+### `CLOUDFLARE` / `GOOGLE` / `CLOUDFLARE_WIRE` / `GOOGLE_WIRE`
 
-The resolvers `https://cloudflare-dns.com/dns-query` and `https://dns.google/resolve`, ready to
-pass as `resolver`.
+The resolvers `https://cloudflare-dns.com/dns-query` and `https://dns.google/resolve` in the JSON
+API, and `https://cloudflare-dns.com/dns-query` and `https://dns.google/dns-query` in RFC 8484
+wire format, which also reports RFC 8914 extended errors.
 
 ### Errors
 
 | Class                | When                                                                       | Extra fields                                                     |
 | -------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------- |
 | `DoHError`           | Base of every failure                                                      |                                                                  |
+| `AnsweredError`      | Base of the three below                                                    | `extendedErrors`: RFC 8914 `{ code, text }`, from `"wire"` only  |
 | `NameNotFoundError`  | NXDOMAIN (RCODE 3)                                                         | `ttl`: the SOA's negative-caching TTL or `null`; `authenticated` |
 | `ServerFailureError` | SERVFAIL (RCODE 2), DNSSEC validation failures included                    |                                                                  |
-| `ResponseCodeError`  | Any other non-zero RCODE                                                   | `rcode`                                                          |
+| `ResponseCodeError`  | Any other non-zero RCODE, extended RCODEs included                         | `rcode`                                                          |
 | `TransportError`     | Network error, timeout, abort, non-2xx, or a body that is not a DNS answer | `status`: the HTTP status, `null` when no response arrived       |
 
 ### `parseCaaProperty(record): CAA.Property` from `./caa`
@@ -177,7 +185,8 @@ does: `unreadable` when the set holds a record that does not parse, and `lookup-
 ### Types
 
 - `DoH`: `RecordType`, `Resolver`, `ResolveOptions`, `Answer<Type>`, `RecordFor<Type>`,
-  `RecordBase`, `UnknownRecord`, and one alias per typed record (`ARecord` through `SOARecord`).
+  `RecordBase`, `UnknownRecord`, `ExtendedError`, and one alias per typed record (`ARecord`
+  through `CDNSKEYRecord`).
 - `CAA` (from `./caa`): `Record`, `Parameter`, `Property` and its three variants, `RelevantSet`,
   `Request`, `Decision`, `Verdict`, and one interface per reason. Every one but `LookupFailed` is
   plain data, ready to log or store.

package/dist/errors.d.ts

@@ -5,12 +5,24 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
+import type { DoH } from "./types.js";
 /** Every failure `resolve` returns; `instanceof` on it narrows to a lookup failure. */
 export declare class DoHError extends Error {
     name: string;
 }
+/** A failure the resolver answered with a DNS message, so it may say why with RFC 8914 extended errors. */
+export declare class AnsweredError extends DoHError {
+    name: string;
+    /** The resolver's RFC 8914 extended errors; a `json` resolver's are always empty. */
+    readonly extendedErrors: DoH.ExtendedError[];
+    /**
+     * @param message - What went wrong, the first extended error appended when there is one.
+     * @param extendedErrors - The extended errors the answer carried.
+     */
+    constructor(message: string, extendedErrors: DoH.ExtendedError[]);
+}
 /** RCODE 3 (NXDOMAIN): the name does not exist. */
-export declare class NameNotFoundError extends DoHError {
+export declare class NameNotFoundError extends AnsweredError {
     name: string;
     /**
      * Seconds the absence may be cached: the smaller of the SOA's TTL and its minimum
@@ -23,24 +35,29 @@ export declare class NameNotFoundError extends DoHError {
      * @param queried - The name that was looked up.
      * @param ttl - The negative-caching TTL, when known.
      * @param authenticated - Whether the answer carried the AD flag.
+     * @param extendedErrors - The answer's RFC 8914 extended errors.
      */
-    constructor(queried: string, ttl: number | null, authenticated?: boolean);
+    constructor(queried: string, ttl: number | null, authenticated?: boolean, extendedErrors?: DoH.ExtendedError[]);
 }
 /** RCODE 2 (SERVFAIL): the resolver could not answer, a DNSSEC validation failure included. */
-export declare class ServerFailureError extends DoHError {
+export declare class ServerFailureError extends AnsweredError {
     name: string;
-    /** @param queried - The name that was looked up. */
-    constructor(queried: string);
+    /**
+     * @param queried - The name that was looked up.
+     * @param extendedErrors - The answer's RFC 8914 extended errors, such as `6` for DNSSEC Bogus.
+     */
+    constructor(queried: string, extendedErrors?: DoH.ExtendedError[]);
 }
 /** Any other non-zero RCODE: FORMERR, NOTIMP, REFUSED and the rest. */
-export declare class ResponseCodeError extends DoHError {
+export declare class ResponseCodeError extends AnsweredError {
     name: string;
     readonly rcode: number;
     /**
      * @param queried - The name that was looked up.
-     * @param rcode - The DNS response code the resolver returned.
+     * @param rcode - The DNS response code the resolver returned, extended RCODEs included.
+     * @param extendedErrors - The answer's RFC 8914 extended errors.
      */
-    constructor(queried: string, rcode: number);
+    constructor(queried: string, rcode: number, extendedErrors?: DoH.ExtendedError[]);
 }
 /** 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 {

package/dist/errors.js

@@ -1,16 +1,28 @@
-/**
- * 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";
 }
+/** A failure the resolver answered with a DNS message, so it may say why with RFC 8914 extended errors. */
+export class AnsweredError extends DoHError {
+    name = "AnsweredError";
+    /** The resolver's RFC 8914 extended errors; a `json` resolver's are always empty. */
+    extendedErrors;
+    /**
+     * @param message - What went wrong, the first extended error appended when there is one.
+     * @param extendedErrors - The extended errors the answer carried.
+     */
+    constructor(message, extendedErrors) {
+        let [first] = extendedErrors;
+        super(first ? `${message}; extended error ${describe(first)}` : message);
+        this.extendedErrors = extendedErrors;
+    }
+}
+/** An extended error as one phrase: its code, and the resolver's text when it sent some. */
+function describe(error) {
+    return error.text ? `${error.code}: ${error.text}` : String(error.code);
+}
 /** RCODE 3 (NXDOMAIN): the name does not exist. */
-export class NameNotFoundError extends DoHError {
+export class NameNotFoundError extends AnsweredError {
     name = "NameNotFoundError";
     /**
      * Seconds the absence may be cached: the smaller of the SOA's TTL and its minimum
@@ -23,31 +35,36 @@ export class NameNotFoundError extends DoHError {
      * @param queried - The name that was looked up.
      * @param ttl - The negative-caching TTL, when known.
      * @param authenticated - Whether the answer carried the AD flag.
+     * @param extendedErrors - The answer's RFC 8914 extended errors.
      */
-    constructor(queried, ttl, authenticated = false) {
-        super(`${queried} does not exist (NXDOMAIN)`);
+    constructor(queried, ttl, authenticated = false, extendedErrors = []) {
+        super(`${queried} does not exist (NXDOMAIN)`, extendedErrors);
         this.ttl = ttl;
         this.authenticated = authenticated;
     }
 }
 /** RCODE 2 (SERVFAIL): the resolver could not answer, a DNSSEC validation failure included. */
-export class ServerFailureError extends DoHError {
+export class ServerFailureError extends AnsweredError {
     name = "ServerFailureError";
-    /** @param queried - The name that was looked up. */
-    constructor(queried) {
-        super(`The resolver failed to answer for ${queried} (SERVFAIL)`);
+    /**
+     * @param queried - The name that was looked up.
+     * @param extendedErrors - The answer's RFC 8914 extended errors, such as `6` for DNSSEC Bogus.
+     */
+    constructor(queried, extendedErrors = []) {
+        super(`The resolver failed to answer for ${queried} (SERVFAIL)`, extendedErrors);
     }
 }
 /** Any other non-zero RCODE: FORMERR, NOTIMP, REFUSED and the rest. */
-export class ResponseCodeError extends DoHError {
+export class ResponseCodeError extends AnsweredError {
     name = "ResponseCodeError";
     rcode;
     /**
      * @param queried - The name that was looked up.
-     * @param rcode - The DNS response code the resolver returned.
+     * @param rcode - The DNS response code the resolver returned, extended RCODEs included.
+     * @param extendedErrors - The answer's RFC 8914 extended errors.
      */
-    constructor(queried, rcode) {
-        super(`The resolver answered ${queried} with response code ${rcode}`);
+    constructor(queried, rcode, extendedErrors = []) {
+        super(`The resolver answered ${queried} with response code ${rcode}`, extendedErrors);
         this.rcode = rcode;
     }
 }

package/dist/exchange.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The HTTP exchange both encodings share, and the response shape each reads its body into,
+ * so `resolve` classifies RCODEs and splits answers the same way whichever format the
+ * resolver speaks.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { DoH } from "./types.js";
+import { TransportError } from "./errors.js";
+/** One resource record of a response, its data in presentation or RFC 3597 generic form. */
+export interface MessageRecord {
+    /** Lowercased, without the trailing dot. */
+    name: string;
+    /** The IANA type code. */
+    type: number;
+    ttl: number;
+    data: string;
+}
+/** What a response says, read out of either encoding. */
+export interface Message {
+    /** The full RCODE, the OPT record's extended bits included. */
+    rcode: number;
+    authenticated: boolean;
+    truncated: boolean;
+    answer: MessageRecord[];
+    authority: MessageRecord[];
+    extendedErrors: DoH.ExtendedError[];
+}
+/** What one query sends: the name and type as asked, and the DNSSEC flags. */
+export interface Query {
+    name: string;
+    /** The canonical mnemonic or `TYPEnnn`. */
+    type: string;
+    dnssec: boolean;
+    checkingDisabled: boolean;
+}
+/** The signal that aborts a request and the timeout that may be why. */
+export interface Deadline {
+    signal: AbortSignal;
+    timeout: AbortSignal;
+    timeoutMs: number;
+}
+/**
+ * Sends one request to the resolver, mapping every way it can fail before a 2xx response
+ * arrives, and a body that cannot be read, to a `TransportError`.
+ *
+ * @param url - The query URL, the question already in it.
+ * @param accept - The media type asked for.
+ * @param deadline - The caller's abort signal joined with the timeout.
+ * @param read - Reads the body, failing when it is not the encoding asked for.
+ */
+export declare function exchange<Body>(url: URL, accept: string, deadline: Deadline, read: (response: Response) => Promise<Body>): Promise<Result<{
+    body: Body;
+    status: number;
+}, TransportError>>;

package/dist/exchange.js

@@ -0,0 +1,34 @@
+import { failure, success } from "@sdxc/result";
+import { TransportError } from "./errors.js";
+/**
+ * Sends one request to the resolver, mapping every way it can fail before a 2xx response
+ * arrives, and a body that cannot be read, to a `TransportError`.
+ *
+ * @param url - The query URL, the question already in it.
+ * @param accept - The media type asked for.
+ * @param deadline - The caller's abort signal joined with the timeout.
+ * @param read - Reads the body, failing when it is not the encoding asked for.
+ */
+export async function exchange(url, accept, deadline, read) {
+    let response;
+    try {
+        response = await fetch(url, { headers: { Accept: accept }, signal: deadline.signal });
+    }
+    catch (error) {
+        let message = deadline.timeout.aborted
+            ? `The DNS query timed out after ${deadline.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));
+    }
+    try {
+        return success({ body: await read(response), status: response.status });
+    }
+    catch (error) {
+        return failure(new TransportError(`The resolver's response is not ${accept}`, response.status, {
+            cause: error,
+        }));
+    }
+}

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 export type { DoH } from "./types.js";
-export { DoHError, NameNotFoundError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
+export { AnsweredError, DoHError, NameNotFoundError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
 export { resolve } from "./resolve.js";
-export { CLOUDFLARE, GOOGLE } from "./resolvers.js";
+export { CLOUDFLARE, CLOUDFLARE_WIRE, GOOGLE, GOOGLE_WIRE } from "./resolvers.js";
 export { checkCname, verifyTxtRecord } from "./verify.js";

package/dist/index.js

@@ -6,7 +6,7 @@
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
  */
-export { DoHError, NameNotFoundError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
+export { AnsweredError, DoHError, NameNotFoundError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
 export { resolve } from "./resolve.js";
-export { CLOUDFLARE, GOOGLE } from "./resolvers.js";
+export { CLOUDFLARE, CLOUDFLARE_WIRE, GOOGLE, GOOGLE_WIRE } from "./resolvers.js";
 export { checkCname, verifyTxtRecord } from "./verify.js";

package/dist/json.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The DoH JSON API (`application/dns-json`) as Cloudflare and Google answer it: the
+ * question goes in the query string, and the validated envelope is read into the response
+ * shape `resolve` works from.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Deadline, Message, Query } from "./exchange.js";
+import type { DoH } from "./types.js";
+import { TransportError } from "./errors.js";
+/**
+ * Asks a JSON resolver one question. The envelope carries no extended errors, so a JSON
+ * response reports none.
+ *
+ * @param resolver - The endpoint, its URL taking `name`, `type`, `do` and `cd` parameters.
+ * @param query - The question and flags.
+ * @param deadline - Aborts the request.
+ */
+export declare function queryJson(resolver: DoH.Resolver, query: Query, deadline: Deadline): Promise<Result<Message, TransportError>>;

package/dist/json.js

@@ -0,0 +1,66 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import * as s from "remix/data-schema";
+import { TransportError } from "./errors.js";
+import { exchange } from "./exchange.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;
+}
+/** A record of the envelope in the shape both encodings share. */
+function toRecord(record) {
+    return {
+        name: normalizeName(record.name),
+        type: record.type,
+        ttl: record.TTL,
+        data: record.data,
+    };
+}
+/**
+ * Asks a JSON resolver one question. The envelope carries no extended errors, so a JSON
+ * response reports none.
+ *
+ * @param resolver - The endpoint, its URL taking `name`, `type`, `do` and `cd` parameters.
+ * @param query - The question and flags.
+ * @param deadline - Aborts the request.
+ */
+export async function queryJson(resolver, query, deadline) {
+    let url = new URL(resolver.url);
+    url.searchParams.set("name", query.name);
+    url.searchParams.set("type", /^TYPE\d+$/.test(query.type) ? query.type.slice(4) : query.type);
+    if (query.dnssec)
+        url.searchParams.set("do", "1");
+    if (query.checkingDisabled)
+        url.searchParams.set("cd", "1");
+    let response = await exchange(url, "application/dns-json", deadline, (body) => body.json());
+    if (isFailure(response))
+        return response;
+    let parsed = s.parseSafe(ENVELOPE_SCHEMA, response.data.body);
+    if (!parsed.success) {
+        return failure(new TransportError("The resolver's response is not a DNS JSON answer", response.data.status));
+    }
+    let envelope = parsed.value;
+    return success({
+        rcode: envelope.Status,
+        authenticated: envelope.AD ?? false,
+        truncated: envelope.TC ?? false,
+        answer: (envelope.Answer ?? []).map(toRecord),
+        authority: (envelope.Authority ?? []).map(toRecord),
+        extendedErrors: [],
+    });
+}

package/dist/resolve.d.ts

@@ -1,6 +1,6 @@
 /**
- * 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
+ * Looks a name up over DNS over HTTPS: one `fetch` to the resolver in its JSON or RFC 8484
+ * wire format, 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)
@@ -21,5 +21,6 @@ import type { DoH } from "./types.js";
  * @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");
+ * @example let answer = await resolve("example.com", "HTTPS", { resolver: CLOUDFLARE_WIRE });
  */
 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

@@ -1,23 +1,9 @@
 import { failure, isSuccess, success } from "@sdxc/result";
 import { canonicalType, parseRecordData, typeName } from "@sdxc/zone-file";
-import * as s from "remix/data-schema";
-import { NameNotFoundError, ResponseCodeError, ServerFailureError, TransportError, } from "./errors.js";
+import { NameNotFoundError, ResponseCodeError, ServerFailureError } from "./errors.js";
+import { queryJson } from "./json.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)),
-});
+import { queryWire } from "./wire.js";
 /** Folds a name the way every owner name in an answer is reported. */
 function normalizeName(name) {
     let lower = name.toLowerCase();
@@ -35,42 +21,45 @@ function normalizeName(name) {
  * @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");
+ * @example let answer = await resolve("example.com", "HTTPS", { resolver: CLOUDFLARE_WIRE });
  */
 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 deadline = { signal, timeout, timeoutMs };
+    let query = {
+        name,
+        type: asked,
+        dnssec: options.dnssec ?? false,
+        checkingDisabled: options.checkingDisabled ?? false,
+    };
     let started = performance.now();
-    let envelope = await fetchEnvelope(url, signal, timeout, timeoutMs);
-    if (!isSuccess(envelope))
-        return envelope;
+    let message = resolver.format === "wire"
+        ? await queryWire(resolver, query, deadline)
+        : await queryJson(resolver, query, deadline);
+    if (!isSuccess(message))
+        return message;
     let durationMs = Math.round(performance.now() - started);
-    let { Status: rcode } = envelope.data;
+    let { rcode, extendedErrors } = message.data;
     if (rcode === 3) {
-        let authenticated = envelope.data.AD ?? false;
-        return failure(new NameNotFoundError(name, negativeTtl(envelope.data), authenticated));
+        let ttl = negativeTtl(message.data);
+        return failure(new NameNotFoundError(name, ttl, message.data.authenticated, extendedErrors));
     }
     if (rcode === 2)
-        return failure(new ServerFailureError(name));
+        return failure(new ServerFailureError(name, extendedErrors));
     if (rcode !== 0)
-        return failure(new ResponseCodeError(name, rcode));
+        return failure(new ResponseCodeError(name, rcode, extendedErrors));
     let records = [];
     let unparsed = [];
     let chain = [];
-    for (let record of envelope.data.Answer ?? []) {
+    for (let record of message.data.answer) {
         let recordType = typeName(record.type);
         if (recordType !== asked && recordType !== "CNAME")
             continue;
-        let base = { name: normalizeName(record.name), ttl: record.TTL };
+        let base = { name: record.name, ttl: record.ttl };
         if (recordType === asked) {
             let data = parseRecordData(recordType, record.data);
             if (isSuccess(data))
@@ -92,50 +81,20 @@ export async function resolve(name, type, options = {}) {
         unparsed,
         chain,
         ttl: ttls.length > 0 ? Math.min(...ttls) : null,
-        authenticated: envelope.data.AD ?? false,
-        truncated: envelope.data.TC ?? false,
+        authenticated: message.data.authenticated,
+        truncated: message.data.truncated,
+        extendedErrors,
         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");
+function negativeTtl(message) {
+    let soa = message.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;
+    return isSuccess(data) ? Math.min(soa.ttl, data.data.minimum) : null;
 }

package/dist/resolvers.d.ts

@@ -1,5 +1,6 @@
 /**
- * The public resolvers that answer the DoH JSON API, ready to pass as `resolver`.
+ * The public resolvers, in the JSON API and the RFC 8484 wire format each answers, ready
+ * to pass as `resolver`.
  *
  * @author [Sergio Xalambrí](https://sergiodxa.com)
  * @copyright Sergio Xalambrí 2026
@@ -9,3 +10,7 @@ import type { DoH } from "./types.js";
 export declare const CLOUDFLARE: DoH.Resolver;
 /** Google Public DNS, which answers JSON at `/resolve` regardless of `Accept`. */
 export declare const GOOGLE: DoH.Resolver;
+/** Cloudflare's 1.1.1.1 in RFC 8484 wire format, which reports RFC 8914 extended errors. */
+export declare const CLOUDFLARE_WIRE: DoH.Resolver;
+/** Google Public DNS in RFC 8484 wire format, which reports RFC 8914 extended errors. */
+export declare const GOOGLE_WIRE: DoH.Resolver;

package/dist/resolvers.js

@@ -5,3 +5,10 @@ export const CLOUDFLARE = {
 };
 /** Google Public DNS, which answers JSON at `/resolve` regardless of `Accept`. */
 export const GOOGLE = { url: "https://dns.google/resolve", format: "json" };
+/** Cloudflare's 1.1.1.1 in RFC 8484 wire format, which reports RFC 8914 extended errors. */
+export const CLOUDFLARE_WIRE = {
+    url: "https://cloudflare-dns.com/dns-query",
+    format: "wire",
+};
+/** Google Public DNS in RFC 8484 wire format, which reports RFC 8914 extended errors. */
+export const GOOGLE_WIRE = { url: "https://dns.google/dns-query", format: "wire" };

package/dist/types.d.ts

@@ -14,12 +14,23 @@ export declare namespace DoH {
     /** A record type by mnemonic; the typed ones autocomplete, any other name is accepted. */
     type RecordType = ZoneFile.RecordType;
     /**
-     * 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`.
+     * A DoH endpoint and the encoding it speaks: `"json"` for the `application/dns-json` API
+     * Cloudflare and Google answer, `"wire"` for RFC 8484 `application/dns-message`, which
+     * any standard DoH server answers and which carries RFC 8914 extended errors.
      */
     interface Resolver {
         url: string;
-        format: "json";
+        format: "json" | "wire";
+    }
+    /**
+     * An RFC 8914 extended DNS error: why a resolver answered as it did, such as `6` (DNSSEC
+     * Bogus), `9` (DNSKEY Missing), `18` (Prohibited) or `22` (No Reachable Authority).
+     */
+    interface ExtendedError {
+        /** The INFO-CODE from the IANA Extended DNS Error Codes registry. */
+        code: number;
+        /** The resolver's EXTRA-TEXT, `null` when it sent none. */
+        text: string | null;
     }
     /** What every record carries. */
     interface RecordBase {
@@ -52,6 +63,20 @@ export declare namespace DoH {
     type SRVRecord = RecordFor<"SRV">;
     /** The zone's start of authority, found at its apex and in negative answers. */
     type SOARecord = RecordFor<"SOA">;
+    /** A service binding (RFC 9460): where and how to reach the service at `name`. */
+    type SVCBRecord = RecordFor<"SVCB">;
+    /** The service binding for an HTTPS origin, with its ALPN, port and address hints. */
+    type HTTPSRecord = RecordFor<"HTTPS">;
+    /** A DANE binding of a TLS certificate or key to the service at `name` (RFC 6698). */
+    type TLSARecord = RecordFor<"TLSA">;
+    /** A digest of a child zone's key, published at the delegation in the parent (RFC 4034). */
+    type DSRecord = RecordFor<"DS">;
+    /** The DS record a child asks its parent to publish (RFC 7344). */
+    type CDSRecord = RecordFor<"CDS">;
+    /** A zone's public signing key, with the key tag DS and RRSIG records name it by. */
+    type DNSKEYRecord = RecordFor<"DNSKEY">;
+    /** The key a child asks its parent to derive a DS record from (RFC 7344). */
+    type CDNSKEYRecord = RecordFor<"CDNSKEY">;
     /** A record of a type without a typed reading, or one whose data failed to parse, with its raw RDATA. */
     type UnknownRecord = ZoneFile.UnknownData & RecordBase;
     /** A successful (NOERROR) answer to one query. */
@@ -71,6 +96,8 @@ export declare namespace DoH {
         authenticated: boolean;
         /** The TC flag: the resolver's upstream answer was truncated. */
         truncated: boolean;
+        /** The resolver's RFC 8914 extended errors, such as `3` (Stale Answer); a `json` resolver's are always empty. */
+        extendedErrors: ExtendedError[];
         durationMs: number;
     }
     /** Options for one lookup. */
@@ -79,9 +106,9 @@ export declare namespace DoH {
          * @default CLOUDFLARE
          */
         resolver?: Resolver;
-        /** Sets `do=1`, asking for DNSSEC records alongside the answer. */
+        /** Sets the DO bit (`do=1` in JSON), asking for DNSSEC records alongside the answer. */
         dnssec?: boolean;
-        /** Sets `cd=1`, asking the resolver to skip DNSSEC validation. */
+        /** Sets the CD bit (`cd=1` in JSON), asking the resolver to skip DNSSEC validation. */
         checkingDisabled?: boolean;
         signal?: AbortSignal;
         /**

package/dist/wire.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RFC 8484 DNS over HTTPS in wire format (`application/dns-message`): the query is an
+ * RFC 1035 message with an EDNS(0) OPT record, and the response is read back into the shape
+ * `resolve` works from, RFC 8914 extended errors and extended RCODEs included.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { Deadline, Message, Query } from "./exchange.js";
+import type { DoH } from "./types.js";
+import { TransportError } from "./errors.js";
+/**
+ * The query message for one question: ID 0, as RFC 8484 recommends for cacheable GETs; RD
+ * and AD set so the resolver recurses and reports validation; CD and the OPT record's DO bit
+ * set from the flags; `null` when the name does not fit a question.
+ *
+ * @param query - The question and flags.
+ */
+export declare function encodeQuery(query: Query): Uint8Array | null;
+/**
+ * Reads a response message: the header flags, the answer and authority records with their
+ * data as RFC 3597 generic data, and the OPT record's extended RCODE bits and extended
+ * errors; `null` when the octets are not a well-formed response.
+ *
+ * @param octets - The response body.
+ */
+export declare function decodeResponse(octets: Uint8Array): Message | null;
+/**
+ * Asks a wire-format resolver one question with an RFC 8484 GET, which shared caches can
+ * store under the `dns` parameter.
+ *
+ * @param resolver - The endpoint, which takes the query in its `dns` parameter.
+ * @param query - The question and flags.
+ * @param deadline - Aborts the request.
+ */
+export declare function queryWire(resolver: DoH.Resolver, query: Query, deadline: Deadline): Promise<Result<Message, TransportError>>;

package/dist/wire.js

@@ -0,0 +1,252 @@
+import { failure, isFailure, isSuccess, success } from "@sdxc/result";
+import { parseRecordData, typeCode } from "@sdxc/zone-file";
+import { TransportError } from "./errors.js";
+import { exchange } from "./exchange.js";
+/** The media type RFC 8484 sends and answers in. */
+const MEDIA_TYPE = "application/dns-message";
+/** The EDNS(0) UDP payload size the query advertises, the DNS Flag Day 2020 default. */
+const PAYLOAD_SIZE = 1232;
+/** The OPT pseudo-record type, which carries EDNS(0) flags, extended RCODE bits and options. */
+const OPT = 41;
+/** The EDNS option code of an RFC 8914 extended DNS error. */
+const EXTENDED_ERROR_OPTION = 15;
+/**
+ * The RDATA layout of the types whose names a server may compress (RFC 3597 section 4):
+ * NS, CNAME, SOA, PTR and MX, each field a name or a run of octets. Expanding those names
+ * turns the RDATA into the generic data `parseRecordData` reads.
+ */
+const COMPRESSIBLE_NAMES = {
+    2: ["name"],
+    5: ["name"],
+    6: ["name", "name", 20],
+    12: ["name"],
+    15: [2, "name"],
+};
+/** How many compression pointers one name may follow, which bounds a looping message. */
+const MAX_POINTERS = 64;
+/** Encodes the text of names and option text into octets. */
+const ENCODER = new TextEncoder();
+/** Decodes an extended error's EXTRA-TEXT, which RFC 8914 makes UTF-8. */
+const DECODER = new TextDecoder();
+/**
+ * The labels of a name as written: an optional trailing dot, each label 1 to 63 octets and
+ * the whole name at most 255; `null` for a name that does not fit a question.
+ */
+function encodeName(name) {
+    let trimmed = name.endsWith(".") ? name.slice(0, -1) : name;
+    let labels = trimmed === "" ? [] : trimmed.split(".").map((label) => ENCODER.encode(label));
+    if (labels.some((label) => label.length === 0 || label.length > 63))
+        return null;
+    let octets = Uint8Array.from([...labels.flatMap((label) => [label.length, ...label]), 0]);
+    return octets.length <= 255 ? octets : null;
+}
+/**
+ * The query message for one question: ID 0, as RFC 8484 recommends for cacheable GETs; RD
+ * and AD set so the resolver recurses and reports validation; CD and the OPT record's DO bit
+ * set from the flags; `null` when the name does not fit a question.
+ *
+ * @param query - The question and flags.
+ */
+export function encodeQuery(query) {
+    let name = encodeName(query.name);
+    let type = typeCode(query.type);
+    if (!name || type === null)
+        return null;
+    let flags = 0x0100 | 0x0020 | (query.checkingDisabled ? 0x0010 : 0);
+    let header = [0, 0, flags >> 8, flags & 0xff, 0, 1, 0, 0, 0, 0, 0, 1];
+    let question = [type >> 8, type & 0xff, 0, 1];
+    let dnssec = query.dnssec ? 0x80 : 0;
+    let opt = [0, OPT >> 8, OPT, PAYLOAD_SIZE >> 8, PAYLOAD_SIZE & 0xff, 0, 0, dnssec, 0, 0, 0];
+    return Uint8Array.from([...header, ...name, ...question, ...opt]);
+}
+/** Octets as unpadded base64url, the encoding of RFC 8484's `dns` query parameter. */
+function base64Url(octets) {
+    let base64 = btoa(Array.from(octets, (octet) => String.fromCharCode(octet)).join(""));
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Prints a name's labels through `@sdxc/zone-file`'s codec, as the target of RFC 3597
+ * generic CNAME data, so owner names read here match the names inside record data exactly.
+ */
+function printName(labels) {
+    let wire = [...labels.flatMap((label) => [label.length, ...label]), 0];
+    let parsed = parseRecordData("CNAME", generic(Uint8Array.from(wire)));
+    return isSuccess(parsed) ? parsed.data.target : null;
+}
+/** Octets as RFC 3597 generic data, which `parseRecordData` reads for any type. */
+function generic(octets) {
+    let hex = Array.from(octets, (octet) => octet.toString(16).padStart(2, "0")).join("");
+    return hex.length === 0 ? "\\# 0" : `\\# ${octets.length} ${hex}`;
+}
+/**
+ * Reads a DNS message front to back. Names follow compression pointers anywhere in the
+ * message. A read past the end, a pointer loop or an unknown label type sets `failed` and
+ * reads as zeros, so a caller checks once after reading instead of after every field.
+ */
+class MessageReader {
+    #octets;
+    offset = 0;
+    failed = false;
+    /** @param octets - The whole message. */
+    constructor(octets) {
+        this.#octets = octets;
+    }
+    /** The next `length` octets, zeros once the message is exhausted. */
+    bytes(length) {
+        if (this.failed || this.offset + length > this.#octets.length) {
+            this.failed = true;
+            return new Uint8Array(length);
+        }
+        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) {
+        return this.bytes(size).reduce((total, byte) => total * 256 + byte, 0);
+    }
+    /** A name's labels, following compression pointers, leaving the offset after the name as written. */
+    labels() {
+        let labels = [];
+        let resume = null;
+        let pointers = 0;
+        while (!this.failed) {
+            let length = this.uint(1);
+            if (length === 0)
+                break;
+            if ((length & 0xc0) === 0xc0) {
+                let target = ((length & 0x3f) << 8) | this.uint(1);
+                pointers += 1;
+                if (pointers > MAX_POINTERS)
+                    this.failed = true;
+                resume ??= this.offset;
+                this.offset = target;
+            }
+            else if (length > 63) {
+                this.failed = true;
+            }
+            else {
+                labels.push(this.bytes(length));
+            }
+        }
+        if (resume !== null)
+            this.offset = resume;
+        return labels;
+    }
+}
+/** A name's labels as uncompressed wire octets. */
+function wireName(labels) {
+    return [...labels.flatMap((label) => [label.length, ...label]), 0];
+}
+/**
+ * A record's RDATA with any compressed names expanded, read in place from the message so
+ * pointers resolve against it; a layout that overruns the RDATA length fails the reader.
+ */
+function expandRdata(reader, type, length) {
+    let layout = COMPRESSIBLE_NAMES[type];
+    if (!layout)
+        return reader.bytes(length);
+    let end = reader.offset + length;
+    let octets = [];
+    for (let field of layout)
+        octets.push(...(field === "name" ? wireName(reader.labels()) : reader.bytes(field)));
+    if (reader.offset !== end)
+        reader.failed = true;
+    return Uint8Array.from(octets);
+}
+/** The RFC 8914 extended errors among an OPT record's options, trailing NULs trimmed from the text. */
+function readExtendedErrors(options) {
+    let reader = new MessageReader(options);
+    let errors = [];
+    while (reader.offset < options.length && !reader.failed) {
+        let code = reader.uint(2);
+        let data = reader.bytes(reader.uint(2));
+        if (code !== EXTENDED_ERROR_OPTION || data.length < 2 || reader.failed)
+            continue;
+        let text = DECODER.decode(data.subarray(2)).replace(/\0+$/, "");
+        errors.push({ code: ((data[0] ?? 0) << 8) | (data[1] ?? 0), text: text || null });
+    }
+    return errors;
+}
+/**
+ * Reads a response message: the header flags, the answer and authority records with their
+ * data as RFC 3597 generic data, and the OPT record's extended RCODE bits and extended
+ * errors; `null` when the octets are not a well-formed response.
+ *
+ * @param octets - The response body.
+ */
+export function decodeResponse(octets) {
+    let reader = new MessageReader(octets);
+    reader.bytes(2);
+    let flags = reader.uint(2);
+    let questions = reader.uint(2);
+    let answers = reader.uint(2);
+    let authorities = reader.uint(2);
+    let additionals = reader.uint(2);
+    if ((flags & 0x8000) === 0)
+        return null;
+    for (let index = 0; index < questions && !reader.failed; index++) {
+        reader.labels();
+        reader.bytes(4);
+    }
+    let answer = [];
+    let authority = [];
+    let extendedRcode = 0;
+    let extendedErrors = [];
+    for (let index = 0; index < answers + authorities + additionals && !reader.failed; index++) {
+        let labels = reader.labels();
+        let type = reader.uint(2);
+        reader.bytes(2);
+        let ttl = reader.uint(4);
+        let length = reader.uint(2);
+        if (type === OPT) {
+            extendedRcode = ttl >>> 24;
+            extendedErrors = readExtendedErrors(reader.bytes(length));
+            continue;
+        }
+        let data = generic(expandRdata(reader, type, length));
+        let name = printName(labels);
+        if (name === null)
+            reader.failed = true;
+        else if (index < answers)
+            answer.push({ name, type, ttl, data });
+        else if (index < answers + authorities)
+            authority.push({ name, type, ttl, data });
+    }
+    if (reader.failed)
+        return null;
+    return {
+        rcode: (extendedRcode << 4) | (flags & 0x000f),
+        authenticated: (flags & 0x0020) !== 0,
+        truncated: (flags & 0x0200) !== 0,
+        answer,
+        authority,
+        extendedErrors,
+    };
+}
+/**
+ * Asks a wire-format resolver one question with an RFC 8484 GET, which shared caches can
+ * store under the `dns` parameter.
+ *
+ * @param resolver - The endpoint, which takes the query in its `dns` parameter.
+ * @param query - The question and flags.
+ * @param deadline - Aborts the request.
+ */
+export async function queryWire(resolver, query, deadline) {
+    let message = encodeQuery(query);
+    if (!message) {
+        return failure(new TransportError(`${query.name} cannot be sent as a DNS question`, null));
+    }
+    let url = new URL(resolver.url);
+    url.searchParams.set("dns", base64Url(message));
+    let response = await exchange(url, MEDIA_TYPE, deadline, async (body) => {
+        return new Uint8Array(await body.arrayBuffer());
+    });
+    if (isFailure(response))
+        return response;
+    let decoded = decodeResponse(response.data.body);
+    if (!decoded) {
+        return failure(new TransportError("The resolver's response is not a DNS message", response.data.status));
+    }
+    return success(decoded);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sdxc/doh",
-	"version": "2026.10.16",
+	"version": "2026.10.25",
 	"description": "Typed DNS over HTTPS lookups",
 	"license": "MIT",
 	"type": "module",
@@ -10,12 +10,12 @@
 	},
 	"dependencies": {
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/zone-file": "2026.10.13"
+		"@sdxc/zone-file": "2026.10.25"
 	},
 	"peerDependencies": {
-		"remix": "3.0.0"
+		"remix": "3.1.0"
 	},
-	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
+	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
 	"publishConfig": {
 		"access": "public"
 	},