@sdxc/doh 2026.10.2 → 2026.10.9

package/README.md

@@ -8,8 +8,9 @@ Typed DNS over HTTPS lookups.
 npm add @sdxc/doh
 ```
 
-Every lookup returns a [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result) value, which
-installs alongside this package.
+Every lookup returns a [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result) value, and
+records are read by [`@sdxc/zone-file`](https://www.npmjs.com/package/@sdxc/zone-file)'s record data
+codec; both install 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`)
@@ -48,15 +49,6 @@ let verified = await verifyTxtRecord("_verify.example.com", "token_abc123"); //
 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`
@@ -66,7 +58,9 @@ let data = parseRecordData("MX", "10 mail.example.com.");
 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>`
+- `records` - the records of the asked type, typed by `DoH.RecordFor<Type>`: the
+  `ZoneFile.RecordData<Type>` fields plus `name` and `ttl`, so a resolved record and one read from a
+  zone file share every type-specific field
 - `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`
@@ -86,21 +80,12 @@ back lowercased without the trailing dot; an AAAA address comes back in RFC 5952
 - `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"] })
-```
+Typed record types: `A` (`address`), `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 returns records with a raw `data`
+string. To read or print RDATA outside a lookup, use `parseRecordData` and `formatRecordData` from
+`@sdxc/zone-file`.
 
 #### `verifyTxtRecord(name, expected, options?): Promise<Result<boolean, DoHError>>`
 
@@ -121,20 +106,101 @@ a loop), so it holds even when the target resolves to nothing. NXDOMAIN is `succ
 
 #### 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                       |                                                     |
+| Class                | When                                                                       | Extra field                                                                                               |
+| -------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `DoHError`           | Base of every `resolve` failure                                            |                                                                                                           |
+| `NameNotFoundError`  | RCODE 3, NXDOMAIN                                                          | `ttl`: the SOA's negative-caching TTL, or `null`; `authenticated`: the AD flag, a DNSSEC-validated denial |
+| `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                                                       |
 
 #### `DoH` namespace
 
 Types only: `RecordType`, `Resolver`, `ResolveOptions`, `Answer<Type>`, `RecordFor<Type>`,
-`RecordData<Type>`, `RecordBase`, the nine record interfaces (`ARecord` through `SOARecord`), and
-`UnknownRecord`.
+`RecordBase`, one alias per typed record (`ARecord` through `SOARecord`, `PTRRecord` and
+`DNAMERecord` included), and `UnknownRecord`.
+
+### `@sdxc/doh/caa`
+
+The WebPKI reading of CAA records (RFC 8659, RFC 8657): what a record asks of a certificate
+authority, which RRset applies to a name, and whether a CA may issue for it.
+
+#### `parseCaaProperty(record): CAA.Property`
+
+Reads one CAA record's meaning:
+
+- `issue` / `issuewild` - `{ kind, critical, issuer, malformed, parameters }`. The value follows RFC
+  8659's grammar, whitespace around `;` and `=` included. `issuer` is lowercased without a trailing
+  dot, and `null` when the value names none (`";"`), which forbids issuance. A value that fails the
+  grammar reads as `issuer: null, malformed: true`, forbidding issuance the same way. Parameters keep
+  their published order and spelling.
+- `iodef` - `{ kind, critical, url }`, `url` being `null` unless the value is a `mailto:`, `http:` or
+  `https:` URL.
+- Any other tag - `{ kind: "unknown", critical, tag, value }`; critical, it forbids issuance.
+
+```typescript
+import { parseCaaProperty } from "@sdxc/doh/caa";
+
+parseCaaProperty({
+	type: "CAA",
+	flags: 0,
+	critical: false,
+	tag: "issue",
+	value: "digicert.com; cansignhttpexchanges=yes",
+});
+// { kind: "issue", critical: false, issuer: "digicert.com", malformed: false,
+//   parameters: [{ key: "cansignhttpexchanges", value: "yes" }] }
+```
+
+#### `findRelevantCaa(domain, options?): Promise<Result<CAA.RelevantSet, DoHError>>`
+
+RFC 8659's climb: one `CAA` query for the domain, then for each ancestor up to the TLD, stopping at
+the first answer with records. A leading `*.` and a trailing dot are dropped and the name is
+lowercased. NODATA and NXDOMAIN move the climb on; any other failure ends it as a failure. Records
+reached through a CNAME or DNAME are the target's, with the aliases in `chain`, and when the target
+publishes none the climb continues at the alias's parent.
+
+The set holds `name` (where the records were found, `null` when nowhere), `records`, `unparsed`,
+`chain`, `queried` (every name asked, nearest first) and `authenticated`: whether every answer in
+the climb, denials of existence included, carried the AD flag.
+
+#### `evaluateCaa(records, request): CAA.Decision`
+
+Decides a request against one RRset with no I/O, so records from a zone file decide as records from
+DNS do. `request` is `{ domain, issuer, accountUri?, validationMethod? }`: `domain` starting with
+`*.` asks about a wildcard certificate, and `issuer` is the CA's CAA identifier or a list of them.
+In order:
+
+| Reason                                            | `allowed` | When                                                                                               |
+| ------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------- |
+| `no-policy`                                       | `true`    | No records                                                                                         |
+| `critical-tag`                                    | `false`   | A critical property of a tag this package does not interpret                                       |
+| `unrestricted`                                    | `true`    | No property applies: only `iodef`, non-critical unknown tags, or `issuewild` on a plain name       |
+| `authorized`                                      | `true`    | An applicable property names one of the issuers and its parameters are satisfied                   |
+| `account-mismatch` / `validation-method-mismatch` | `false`   | Properties name the issuer, and RFC 8657's `accounturi` or `validationmethods` exclude the request |
+| `not-authorized`                                  | `false`   | Applicable properties name other issuers, listed in `issuers`                                      |
+| `forbidden`                                       | `false`   | Every applicable property names no issuer                                                          |
+
+For a wildcard domain, any `issuewild` property replaces every `issue`. Authorizations add up, so
+`issue ";"` beside `issue "ca.example"` still authorizes `ca.example`. Issuers match exactly and
+case-insensitively. Two `accounturi` parameters, or a repeated, empty or malformed
+`validationmethods`, are never satisfied; an omitted `accountUri` or `validationMethod` passes that
+check, and the `authorized` decision carries the property whose parameters show what went unchecked.
+
+#### `mayIssue(request, options?): Promise<CAA.Verdict>`
+
+`findRelevantCaa`, then `evaluateCaa`, with the RRset in `relevant`. Two more refusals:
+`unreadable` when the set holds a record that does not parse, and `lookup-failed` when a query in
+the climb fails, with the failing `name`, `queried` and the `DoHError`. `options` reach every
+query, so `resolver: GOOGLE` confirms a verdict through a second resolver.
+
+The verdict predicts what a CA's own lookup finds when the zone serves it what the resolver saw.
+
+#### `CAA` namespace
+
+Types only: `Record`, `Parameter`, `Property` (`IssueProperty`, `IodefProperty`, `UnknownProperty`),
+`RelevantSet`, `Request`, `Decision`, `Verdict` and one interface per reason. Every one but
+`LookupFailed` is plain data, ready for a log line or storage.
 
 ## Pattern: Tell A Vanished Name From A Failing Resolver
 
@@ -154,6 +220,44 @@ if (isFailure(answer)) {
 let viaAlias = answer.data.chain.length > 0;
 ```
 
+## Pattern: Compare A Zone File With DNS
+
+A zone file and a resolver can spell one record differently: `0 ISSUE "ca.example"` in one,
+RFC 3597 generic data (`\# 15 00 05 69 73 73 75 65 …`) in the other. Parse both and print them, and
+equal records give equal strings.
+
+```typescript
+import { resolve } from "@sdxc/doh";
+import { isSuccess } from "@sdxc/result";
+import { formatRecordData, parseRecordData } from "@sdxc/zone-file";
+
+let published = parseRecordData("CAA", zoneLine.data);
+let answer = await resolve("example.com", "CAA");
+if (isSuccess(published) && isSuccess(answer)) {
+	let live = new Set(answer.data.records.map(formatRecordData));
+	let missing = !live.has(formatRecordData(published.data));
+}
+```
+
+## Pattern: A Lookup Failure Is A Refusal
+
+A CA refuses to issue when its CAA lookup fails, so `mayIssue` answers `allowed: false` for a
+failing lookup too. Checking `allowed` alone treats a SERVFAIL the way a CA does; narrow on
+`reason` to retry first.
+
+```typescript
+import { GOOGLE } from "@sdxc/doh";
+import { mayIssue } from "@sdxc/doh/caa";
+
+let request = { domain: "*.example.com", issuer: "letsencrypt.org" };
+let verdict = await mayIssue(request);
+if (verdict.reason === "lookup-failed") verdict = await mayIssue(request, { resolver: GOOGLE });
+
+if (!verdict.allowed && verdict.reason !== "lookup-failed") {
+	verdict.relevant.name; // "example.com": where the blocking policy lives
+}
+```
+
 ## Pattern: Cache Through The Answer's TTL
 
 ```typescript

package/dist/caa/evaluate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Decides a certificate request against one CAA RRset under RFC 8659 and RFC 8657, with no
+ * I/O, so records read from a zone file decide exactly as records from a resolver do: the
+ * `issuewild` override, additive authorizations, critical tags and the account and method bindings.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { CAA } from "./types.js";
+/**
+ * Decides a request against one RRset. A critical unknown tag refuses before anything
+ * else; for a wildcard domain any `issuewild` replaces every `issue`; issuers match
+ * exactly, case-insensitively and without the trailing dot. Reserved flag bits are ignored.
+ *
+ * @param records - The relevant RRset, such as `findRelevantCaa`'s records or a zone file's.
+ * @param request - The domain, the CA's identifiers and, optionally, the RFC 8657 account and method.
+ * @returns Whether the RRset allows the request, and which property or issuers decided it.
+ * @example evaluateCaa([{ type: "CAA", flags: 0, critical: false, tag: "issue", value: "pki.goog" }], { domain: "example.com", issuer: "letsencrypt.org" }) // { allowed: false, reason: "not-authorized", issuers: ["pki.goog"] }
+ */
+export declare function evaluateCaa(records: readonly CAA.Record[], request: CAA.Request): CAA.Decision;

package/dist/caa/evaluate.js

@@ -0,0 +1,87 @@
+import { parseCaaProperty } from "./property.js";
+/** RFC 8657 §4's `validationmethods` value: comma-separated method labels. */
+const METHOD_LIST = /^[A-Za-z0-9](?:-*[A-Za-z0-9])*(?:,[A-Za-z0-9](?:-*[A-Za-z0-9])*)*$/;
+/**
+ * Decides a request against one RRset. A critical unknown tag refuses before anything
+ * else; for a wildcard domain any `issuewild` replaces every `issue`; issuers match
+ * exactly, case-insensitively and without the trailing dot. Reserved flag bits are ignored.
+ *
+ * @param records - The relevant RRset, such as `findRelevantCaa`'s records or a zone file's.
+ * @param request - The domain, the CA's identifiers and, optionally, the RFC 8657 account and method.
+ * @returns Whether the RRset allows the request, and which property or issuers decided it.
+ * @example evaluateCaa([{ type: "CAA", flags: 0, critical: false, tag: "issue", value: "pki.goog" }], { domain: "example.com", issuer: "letsencrypt.org" }) // { allowed: false, reason: "not-authorized", issuers: ["pki.goog"] }
+ */
+export function evaluateCaa(records, request) {
+    if (records.length === 0)
+        return { allowed: true, reason: "no-policy" };
+    let properties = records.map(parseCaaProperty);
+    let critical = properties.find((property) => property.kind === "unknown" && property.critical);
+    if (critical)
+        return { allowed: false, reason: "critical-tag", property: critical };
+    let applicable = applicableProperties(properties, request.domain);
+    if (applicable.length === 0)
+        return { allowed: true, reason: "unrestricted" };
+    let issuers = new Set([request.issuer].flat().map(normalizeIssuer));
+    let matching = applicable.filter((property) => property.issuer !== null && issuers.has(property.issuer));
+    let authorized = matching.find((property) => accountSatisfied(property, request) && methodSatisfied(property, request));
+    if (authorized)
+        return { allowed: true, reason: "authorized", property: authorized };
+    let [first] = matching;
+    if (first) {
+        let reason = accountSatisfied(first, request)
+            ? "validation-method-mismatch"
+            : "account-mismatch";
+        return { allowed: false, reason, property: first };
+    }
+    let named = applicable.flatMap((property) => (property.issuer === null ? [] : [property.issuer]));
+    if (named.length > 0)
+        return { allowed: false, reason: "not-authorized", issuers: [...new Set(named)] };
+    return { allowed: false, reason: "forbidden" };
+}
+/**
+ * The properties that decide `domain` (RFC 8659 §4.3): `issuewild` for a wildcard name
+ * that has any, otherwise `issue`; a non-wildcard name never reads `issuewild`.
+ */
+function applicableProperties(properties, domain) {
+    let issue = properties.filter((property) => property.kind === "issue");
+    if (!domain.trim().startsWith("*."))
+        return issue;
+    let wild = properties.filter((property) => property.kind === "issuewild");
+    return wild.length > 0 ? wild : issue;
+}
+/** Folds a CA identifier the way `parseCaaProperty` folds an issuer. */
+function normalizeIssuer(issuer) {
+    let lower = issuer.trim().toLowerCase();
+    return lower.endsWith(".") ? lower.slice(0, -1) : lower;
+}
+/** The values of every parameter named `key`, in published order. */
+function parameterValues(property, key) {
+    return property.parameters
+        .filter((parameter) => parameter.key === key)
+        .map((parameter) => parameter.value);
+}
+/**
+ * RFC 8657 §3: one `accounturi` binds the property to that account, and two or more
+ * make it unsatisfiable. A request with no `accountUri` passes a single binding.
+ */
+function accountSatisfied(property, request) {
+    let accounts = parameterValues(property, "accounturi");
+    if (accounts.length === 0)
+        return true;
+    if (accounts.length > 1)
+        return false;
+    return request.accountUri === undefined || accounts[0] === request.accountUri;
+}
+/**
+ * RFC 8657 §4: `validationmethods` binds the property to the listed methods. An empty,
+ * malformed or repeated list is unsatisfiable; a request with no method passes a valid list.
+ */
+function methodSatisfied(property, request) {
+    let lists = parameterValues(property, "validationmethods");
+    if (lists.length === 0)
+        return true;
+    let [list] = lists;
+    if (lists.length > 1 || list === undefined || !METHOD_LIST.test(list))
+        return false;
+    return (request.validationMethod === undefined || list.split(",").includes(request.validationMethod));
+}

package/dist/caa/may-issue.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Predicts whether a CA may issue for a name: the relevant RRset found over DoH, then
+ * decided with no further I/O. Every failure, a broken lookup included, reads as
+ * `allowed: false`, because that is what a CA does with it (RFC 8659 §6).
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { DoH } from "../types.js";
+import type { CAA } from "./types.js";
+/**
+ * Whether a CA may issue for `request.domain`. A failing query answers `lookup-failed`
+ * with the name that failed, and an unparsable record in the set answers `unreadable`,
+ * both refused. The verdict predicts what the CA's own lookup finds if the zone serves the same.
+ *
+ * @param request - The domain, the CA's identifiers and, optionally, the RFC 8657 account and method.
+ * @param options - Passed to every lookup, so `resolver: GOOGLE` confirms through a second resolver.
+ * @returns The verdict and, unless the lookup failed, the RRset that decided it.
+ * @example let verdict = await mayIssue({ domain: "*.example.com", issuer: "letsencrypt.org" });
+ */
+export declare function mayIssue(request: CAA.Request, options?: DoH.ResolveOptions): Promise<CAA.Verdict>;

package/dist/caa/may-issue.js

@@ -0,0 +1,21 @@
+import { evaluateCaa } from "./evaluate.js";
+import { climbCaa } from "./relevant-set.js";
+/**
+ * Whether a CA may issue for `request.domain`. A failing query answers `lookup-failed`
+ * with the name that failed, and an unparsable record in the set answers `unreadable`,
+ * both refused. The verdict predicts what the CA's own lookup finds if the zone serves the same.
+ *
+ * @param request - The domain, the CA's identifiers and, optionally, the RFC 8657 account and method.
+ * @param options - Passed to every lookup, so `resolver: GOOGLE` confirms through a second resolver.
+ * @returns The verdict and, unless the lookup failed, the RRset that decided it.
+ * @example let verdict = await mayIssue({ domain: "*.example.com", issuer: "letsencrypt.org" });
+ */
+export async function mayIssue(request, options) {
+    let relevant = await climbCaa(request.domain, options);
+    if ("error" in relevant)
+        return { allowed: false, reason: "lookup-failed", ...relevant };
+    let [unreadable] = relevant.unparsed;
+    if (unreadable)
+        return { allowed: false, reason: "unreadable", record: unreadable, relevant };
+    return { ...evaluateCaa(relevant.records, request), relevant };
+}

package/dist/caa/property.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reads what one CAA record asks of a CA: the issuer and parameters of an `issue` or
+ * `issuewild` value under RFC 8659 §4.2's grammar, the report URL of an `iodef`, and any
+ * other tag kept as is, so a policy decision works on meanings instead of strings.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { CAA } from "./types.js";
+/**
+ * Reads what one CAA record asks of a CA. An `issue` value that fails the grammar reads
+ * as `issuer: null, malformed: true`, which forbids issuance as RFC 8659 says it does;
+ * issuers are lowercased without a trailing dot, parameters are kept as written.
+ *
+ * @param record - The record's data, from `resolve` or `parseRecordData`.
+ * @returns The property, with `kind: "unknown"` for any tag other than `issue`, `issuewild` and `iodef`.
+ * @example parseCaaProperty({ type: "CAA", flags: 0, critical: false, tag: "issue", value: ";" }) // { kind: "issue", critical: false, issuer: null, malformed: false, parameters: [] }
+ */
+export declare function parseCaaProperty(record: CAA.Record): CAA.Property;

package/dist/caa/property.js

@@ -0,0 +1,54 @@
+/** RFC 8659 §4.2's `label`, which is also the grammar of a parameter `tag`. */
+const LABEL = "[A-Za-z0-9](?:-*[A-Za-z0-9])*";
+/** One `tag = value` parameter; a value is any printable ASCII but space and `;`. */
+const PARAMETER = `${LABEL}[ \\t]*=[ \\t]*[\\x21-\\x3A\\x3C-\\x7E]*`;
+/**
+ * The whole `issue-value`: an optional issuer domain (a trailing dot tolerated), then an
+ * optional `;` with an optional parameter list. Group 1 is the domain, group 2 the list.
+ */
+const ISSUE_VALUE = new RegExp(`^[ \\t]*(?:(${LABEL}(?:\\.${LABEL})*)\\.?[ \\t]*)?` +
+    `(?:;[ \\t]*(?:(${PARAMETER}(?:[ \\t]*;[ \\t]*${PARAMETER})*)[ \\t]*)?)?$`);
+/** The URL schemes RFC 8659 §4.4 allows an `iodef` to report to. */
+const IODEF_SCHEMES = new Set(["mailto:", "http:", "https:"]);
+/**
+ * Reads what one CAA record asks of a CA. An `issue` value that fails the grammar reads
+ * as `issuer: null, malformed: true`, which forbids issuance as RFC 8659 says it does;
+ * issuers are lowercased without a trailing dot, parameters are kept as written.
+ *
+ * @param record - The record's data, from `resolve` or `parseRecordData`.
+ * @returns The property, with `kind: "unknown"` for any tag other than `issue`, `issuewild` and `iodef`.
+ * @example parseCaaProperty({ type: "CAA", flags: 0, critical: false, tag: "issue", value: ";" }) // { kind: "issue", critical: false, issuer: null, malformed: false, parameters: [] }
+ */
+export function parseCaaProperty(record) {
+    let tag = record.tag.toLowerCase();
+    let critical = record.critical;
+    if (tag === "issue" || tag === "issuewild") {
+        return { kind: tag, critical, ...readIssueValue(record.value) };
+    }
+    if (tag === "iodef")
+        return { kind: "iodef", critical, url: readIodefUrl(record.value) };
+    return { kind: "unknown", critical, tag, value: record.value };
+}
+/** The issuer and parameters of an `issue` value, or the malformed reading when the grammar fails. */
+function readIssueValue(value) {
+    let match = ISSUE_VALUE.exec(value);
+    if (!match)
+        return { issuer: null, malformed: true, parameters: [] };
+    let parameters = (match[2] ?? "")
+        .split(";")
+        .filter((parameter) => parameter.trim().length > 0)
+        .map((parameter) => {
+        let separator = parameter.indexOf("=");
+        return {
+            key: parameter.slice(0, separator).trim(),
+            value: parameter.slice(separator + 1).trim(),
+        };
+    });
+    return { issuer: match[1]?.toLowerCase() ?? null, malformed: false, parameters };
+}
+/** The `iodef` value when it is a URL in one of RFC 8659's schemes, `null` otherwise. */
+function readIodefUrl(value) {
+    let trimmed = value.trim();
+    let url = URL.parse(trimmed);
+    return url && IODEF_SCHEMES.has(url.protocol) ? trimmed : null;
+}

package/dist/caa/relevant-set.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Finds the CAA RRset RFC 8659 §3 applies to a name: the domain's own, or the nearest
+ * ancestor's below the root, one query per label and stopping at the first non-empty
+ * answer, so a domain publishing at its apex costs one or two lookups.
+ *
+ * @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";
+import type { CAA } from "./types.js";
+/** A climb that ended on a failing query, with the name that failed and the names asked so far. */
+export interface ClimbFailure {
+    name: string;
+    queried: string[];
+    error: DoHError;
+}
+/**
+ * Finds the RRset a CA reads for `domain`. NODATA and NXDOMAIN move the climb to the
+ * parent; any other failure ends it, since a CA would not issue past it. Aliases are the
+ * resolver's: records reached through a CNAME are the target's, and `chain` says so.
+ *
+ * @param domain - The name, a leading `*.` allowed; an internationalized name must already be punycode.
+ * @param options - Passed to every `resolve` in the climb.
+ * @returns The relevant RRset, empty with `name: null` when no ancestor publishes one.
+ * @example await findRelevantCaa("shop.example.com") // success({ name: "example.com", records: [...], queried: ["shop.example.com", "example.com"], ... })
+ */
+export declare function findRelevantCaa(domain: string, options?: DoH.ResolveOptions): Promise<Result<CAA.RelevantSet, DoHError>>;
+/**
+ * The climb behind `findRelevantCaa`, reporting a failure with the name that failed so a
+ * verdict can say where DNS broke. `authenticated` is the AD flag of every answer ANDed,
+ * NXDOMAIN included, because an unvalidated empty step is where a suppressed record hides.
+ */
+export declare function climbCaa(domain: string, options?: DoH.ResolveOptions): Promise<CAA.RelevantSet | ClimbFailure>;

package/dist/caa/relevant-set.js

@@ -0,0 +1,61 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { NameNotFoundError } from "../errors.js";
+import { resolve } from "../resolve.js";
+/**
+ * Finds the RRset a CA reads for `domain`. NODATA and NXDOMAIN move the climb to the
+ * parent; any other failure ends it, since a CA would not issue past it. Aliases are the
+ * resolver's: records reached through a CNAME are the target's, and `chain` says so.
+ *
+ * @param domain - The name, a leading `*.` allowed; an internationalized name must already be punycode.
+ * @param options - Passed to every `resolve` in the climb.
+ * @returns The relevant RRset, empty with `name: null` when no ancestor publishes one.
+ * @example await findRelevantCaa("shop.example.com") // success({ name: "example.com", records: [...], queried: ["shop.example.com", "example.com"], ... })
+ */
+export async function findRelevantCaa(domain, options) {
+    let climbed = await climbCaa(domain, options);
+    return "error" in climbed ? failure(climbed.error) : success(climbed);
+}
+/**
+ * The climb behind `findRelevantCaa`, reporting a failure with the name that failed so a
+ * verdict can say where DNS broke. `authenticated` is the AD flag of every answer ANDed,
+ * NXDOMAIN included, because an unvalidated empty step is where a suppressed record hides.
+ */
+export async function climbCaa(domain, options) {
+    let queried = [];
+    let authenticated = true;
+    for (let name of candidateNames(domain)) {
+        queried.push(name);
+        let answer = await resolve(name, "CAA", options);
+        if (isFailure(answer)) {
+            if (!(answer.error instanceof NameNotFoundError))
+                return { name, queried, error: answer.error };
+            authenticated &&= answer.error.authenticated;
+            continue;
+        }
+        authenticated &&= answer.data.authenticated;
+        let { records, unparsed, chain } = answer.data;
+        if (records.length > 0 || unparsed.length > 0)
+            return { name, records, unparsed, chain, queried, authenticated };
+    }
+    return {
+        name: null,
+        records: [],
+        unparsed: [],
+        chain: [],
+        queried,
+        authenticated: authenticated && queried.length > 0,
+    };
+}
+/**
+ * The domain and each ancestor below the root, nearest first. The domain is lowercased,
+ * its trailing dot and a leading `*.` dropped, since RFC 8659 computes `*.X`'s set at `X`.
+ */
+function candidateNames(domain) {
+    let name = domain.trim().toLowerCase();
+    if (name.endsWith("."))
+        name = name.slice(0, -1);
+    if (name.startsWith("*."))
+        name = name.slice(2);
+    let labels = name.split(".").filter((label) => label.length > 0);
+    return labels.map((_, index) => labels.slice(index).join("."));
+}