@sdxc/zone-file 2026.10.13 → 2026.11.3

package/dist/svc-params.js

@@ -0,0 +1,338 @@
+/**
+ * The SvcParams codec SVCB and HTTPS share (RFC 9460): presentation `key=value` lists and
+ * their wire form both read into one wire-keyed map first, so the two spellings validate
+ * by the same rules and come out as the same `SvcParams`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { isFailure } from "@sdxc/result";
+import { ipv4Octets, ipv6Octets, printIpv6 } from "./addresses.js";
+import { decodeOctets, readCharacterStrings } from "./character-strings.js";
+import { decodeBase64, encodeBase64 } from "./octets.js";
+/** The registered SvcParamKeys by number; any other key is spelled `keyNNNNN`. */
+const KEY_NAMES = {
+    0: "mandatory",
+    1: "alpn",
+    2: "no-default-alpn",
+    3: "port",
+    4: "ipv4hint",
+    5: "ech",
+    6: "ipv6hint",
+    7: "dohpath",
+    8: "ohttp",
+};
+/** The number of each registered key name. */
+const KEY_NUMBERS = new Map(Object.entries(KEY_NAMES).map(([number, name]) => [name, Number(number)]));
+/** Encodes the text of a value into the octets it is on the wire. */
+const ENCODER = new TextEncoder();
+/** The presentation name of a key number. */
+function keyName(key) {
+    return KEY_NAMES[key] ?? `key${key}`;
+}
+/** The number of a key name, registered or `keyNNNNN`; `null` for anything else and for the reserved 65535. */
+function keyNumber(name) {
+    let generic = /^key(0|[1-9]\d{0,4})$/.exec(name);
+    let number = generic ? Number(generic[1]) : (KEY_NUMBERS.get(name) ?? null);
+    return number !== null && number < 0xffff ? number : null;
+}
+/**
+ * Splits presentation params into `key[=value]` fields on whitespace outside quotes,
+ * stepping over escaped characters so `\"` and `\ ` stay inside their field.
+ */
+function splitFields(text) {
+    let fields = [];
+    let field = "";
+    let quoted = false;
+    for (let index = 0; index < text.length; index++) {
+        let char = text[index] ?? "";
+        if (char === "\\") {
+            field += text.slice(index, index + 2);
+            index += 1;
+        }
+        else if (char === '"') {
+            quoted = !quoted;
+            field += char;
+        }
+        else if (!quoted && /\s/.test(char)) {
+            if (field.length > 0)
+                fields.push(field);
+            field = "";
+        }
+        else {
+            field += char;
+        }
+    }
+    if (field.length > 0)
+        fields.push(field);
+    return fields;
+}
+/** A value's text with its quoting and escapes removed, `key=` as empty; `null` for more than one character-string. */
+function readValue(raw) {
+    if (raw.length === 0)
+        return "";
+    let strings = readCharacterStrings(raw);
+    if (isFailure(strings) || strings.data.length !== 1)
+        return null;
+    return strings.data[0] ?? null;
+}
+/**
+ * Splits a value-list (RFC 9460 Appendix A.1) on its unescaped commas, `\,` and `\\`
+ * standing for a literal comma and backslash; `null` when any item is empty.
+ */
+function splitValueList(value) {
+    let items = [];
+    let item = "";
+    for (let index = 0; index < value.length; index++) {
+        let char = value[index] ?? "";
+        if (char === "\\" && index + 1 < value.length) {
+            item += value[index + 1];
+            index += 1;
+        }
+        else if (char === ",") {
+            items.push(item);
+            item = "";
+        }
+        else {
+            item += char;
+        }
+    }
+    items.push(item);
+    return items.every((entry) => entry.length > 0) ? items : null;
+}
+/** Joins octet runs into one. */
+function concat(parts) {
+    let octets = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (let part of parts) {
+        octets.set(part, offset);
+        offset += part.length;
+    }
+    return octets;
+}
+/** A 16-bit big-endian integer's two octets. */
+function uint16(value) {
+    return Uint8Array.of(value >> 8, value & 0xff);
+}
+/** Reads every item of a value-list through `read`, `null` when the list or any item is invalid. */
+function encodeList(value, read) {
+    let items = splitValueList(value);
+    if (!items)
+        return null;
+    let parts = items.map(read);
+    return parts.every((part) => part !== null) ? concat(parts) : null;
+}
+/** The wire octets of one key's presentation value; `value` is `null` when the field has no `=`. */
+function encodeValue(key, value) {
+    switch (key) {
+        case 0: {
+            if (value === null)
+                return null;
+            let items = splitValueList(value);
+            let keys = items?.map(keyNumber);
+            if (!keys || keys.some((number) => number === null))
+                return null;
+            return concat(keys.sort((a, b) => a - b).map(uint16));
+        }
+        case 1:
+            return value === null
+                ? null
+                : encodeList(value, (item) => {
+                    let octets = ENCODER.encode(item);
+                    return octets.length <= 0xff ? concat([Uint8Array.of(octets.length), octets]) : null;
+                });
+        case 2:
+        case 8:
+            return value === null || value === "" ? new Uint8Array() : null;
+        case 3:
+            return value !== null && /^\d{1,5}$/.test(value) && Number(value) <= 0xffff
+                ? uint16(Number(value))
+                : null;
+        case 4:
+            return value === null ? null : encodeList(value, ipv4Octets);
+        case 5:
+            return value === null ? null : decodeBase64(value);
+        case 6:
+            return value === null ? null : encodeList(value, ipv6Octets);
+        default:
+            return ENCODER.encode(value ?? "");
+    }
+}
+/**
+ * Reads the params of SVCB or HTTPS presentation data, the fields after the target.
+ * Fails on an unknown or repeated key and on a value its key does not accept.
+ *
+ * @param text - Zero or more `key[=value]` fields.
+ */
+export function readSvcParams(text) {
+    let values = new Map();
+    for (let field of splitFields(text)) {
+        let separator = field.indexOf("=");
+        let key = keyNumber(separator === -1 ? field : field.slice(0, separator));
+        if (key === null || values.has(key))
+            return null;
+        let value = separator === -1 ? null : readValue(field.slice(separator + 1));
+        if (separator !== -1 && value === null)
+            return null;
+        let octets = encodeValue(key, value);
+        if (!octets)
+            return null;
+        values.set(key, octets);
+    }
+    return decodeSvcParams(new Map([...values].sort(([a], [b]) => a - b)));
+}
+/**
+ * Reads the params of SVCB or HTTPS wire data, the octets after the target. Keys must
+ * strictly increase, as RFC 9460 requires of the wire form.
+ *
+ * @param octets - The SvcParams octets, `key length value` repeated.
+ */
+export function readWireSvcParams(octets) {
+    let values = new Map();
+    let offset = 0;
+    let previous = -1;
+    while (offset < octets.length) {
+        if (offset + 4 > octets.length)
+            return null;
+        let key = ((octets[offset] ?? 0) << 8) | (octets[offset + 1] ?? 0);
+        let length = ((octets[offset + 2] ?? 0) << 8) | (octets[offset + 3] ?? 0);
+        offset += 4;
+        if (key <= previous || key === 0xffff || offset + length > octets.length)
+            return null;
+        values.set(key, octets.subarray(offset, offset + length));
+        offset += length;
+        previous = key;
+    }
+    return decodeSvcParams(values);
+}
+/** Splits octets into runs of `size`, `null` when they do not divide evenly or are empty. */
+function chunks(octets, size) {
+    if (octets.length === 0 || octets.length % size !== 0)
+        return null;
+    return Array.from({ length: octets.length / size }, (_, index) => octets.subarray(index * size, index * size + size));
+}
+/** Reads length-prefixed ALPN ids, `null` when one is empty or overruns the value. */
+function readAlpn(octets) {
+    let ids = [];
+    let offset = 0;
+    while (offset < octets.length) {
+        let length = octets[offset] ?? 0;
+        if (length === 0 || offset + 1 + length > octets.length)
+            return null;
+        ids.push(decodeOctets(octets.subarray(offset + 1, offset + 1 + length)));
+        offset += 1 + length;
+    }
+    return ids.length > 0 ? ids : null;
+}
+/**
+ * Turns wire values into `SvcParams`, enforcing what RFC 9460 asks of every key: values of
+ * the right shape, and a `mandatory` list of distinct keys that are all present and exclude
+ * `mandatory` itself.
+ */
+function decodeSvcParams(values) {
+    let params = {};
+    for (let [key, value] of values) {
+        switch (key) {
+            case 0: {
+                let keys = chunks(value, 2)?.map((pair) => ((pair[0] ?? 0) << 8) | (pair[1] ?? 0));
+                if (!keys)
+                    return null;
+                let increasing = keys.every((number, index) => index === 0 || number > (keys[index - 1] ?? 0));
+                if (!increasing || keys.some((number) => number === 0 || !values.has(number)))
+                    return null;
+                params.mandatory = keys.map(keyName);
+                break;
+            }
+            case 1: {
+                let alpn = readAlpn(value);
+                if (!alpn)
+                    return null;
+                params.alpn = alpn;
+                break;
+            }
+            case 2:
+            case 8:
+                if (value.length !== 0)
+                    return null;
+                if (key === 2)
+                    params.noDefaultAlpn = true;
+                else
+                    params.ohttp = true;
+                break;
+            case 3:
+                if (value.length !== 2)
+                    return null;
+                params.port = ((value[0] ?? 0) << 8) | (value[1] ?? 0);
+                break;
+            case 4: {
+                let addresses = chunks(value, 4);
+                if (!addresses)
+                    return null;
+                params.ipv4Hint = addresses.map((address) => Array.from(address).join("."));
+                break;
+            }
+            case 5:
+                if (value.length === 0)
+                    return null;
+                params.ech = encodeBase64(value);
+                break;
+            case 6: {
+                let addresses = chunks(value, 16);
+                if (!addresses)
+                    return null;
+                params.ipv6Hint = addresses.map(printIpv6);
+                break;
+            }
+            case 7:
+                if (value.length === 0)
+                    return null;
+                params.dohPath = decodeOctets(value);
+                break;
+            default:
+                params.other = { ...params.other, [key]: decodeOctets(value) };
+        }
+    }
+    return params;
+}
+/** Escapes a value-list item so its commas and backslashes read back as part of it. */
+function escapeItem(item) {
+    return item.replace(/[\\,]/g, "\\$&");
+}
+/**
+ * Prints params in canonical presentation form, keys in ascending number order and values
+ * quoted wherever they are free text, so two spellings of one record print alike.
+ *
+ * @param params - The params to print.
+ * @param quote - Prints a character-string with its escapes.
+ * @returns The fields joined by spaces; empty for no params.
+ */
+export function printSvcParams(params, quote) {
+    let fields = [];
+    if (params.mandatory) {
+        let keys = params.mandatory.map((name) => [keyNumber(name) ?? 0xffff, name]);
+        let sorted = keys.sort(([a], [b]) => a - b).map(([, name]) => name);
+        fields.push([0, `mandatory=${sorted.join(",")}`]);
+    }
+    if (params.alpn)
+        fields.push([1, `alpn=${quote(params.alpn.map(escapeItem).join(","))}`]);
+    if (params.noDefaultAlpn)
+        fields.push([2, "no-default-alpn"]);
+    if (params.port !== undefined)
+        fields.push([3, `port=${params.port}`]);
+    if (params.ipv4Hint)
+        fields.push([4, `ipv4hint=${params.ipv4Hint.join(",")}`]);
+    if (params.ech !== undefined)
+        fields.push([5, `ech=${params.ech}`]);
+    if (params.ipv6Hint)
+        fields.push([6, `ipv6hint=${params.ipv6Hint.join(",")}`]);
+    if (params.dohPath !== undefined)
+        fields.push([7, `dohpath=${quote(params.dohPath)}`]);
+    if (params.ohttp)
+        fields.push([8, "ohttp"]);
+    for (let [key, value] of Object.entries(params.other ?? {}))
+        fields.push([Number(key), `key${key}=${quote(value)}`]);
+    return fields
+        .sort(([a], [b]) => a - b)
+        .map(([, field]) => field)
+        .join(" ");
+}

package/dist/types.d.ts

@@ -7,7 +7,7 @@
  * @copyright Sergio Xalambrí 2026
  */
 /** The record types whose data is read into typed fields. */
-export type TypedRecordType = "A" | "AAAA" | "CNAME" | "NS" | "PTR" | "DNAME" | "MX" | "TXT" | "CAA" | "SRV" | "SOA";
+export type TypedRecordType = "A" | "AAAA" | "CNAME" | "NS" | "PTR" | "DNAME" | "MX" | "TXT" | "CAA" | "SRV" | "SOA" | "SVCB" | "HTTPS" | "TLSA" | "DS" | "CDS" | "DNSKEY" | "CDNSKEY";
 /** A record type by mnemonic; the typed ones autocomplete, any other name is accepted. */
 export type RecordType = TypedRecordType | (string & {});
 /** A record class; `IN` is the internet, `CLASSnnn` spells one without a mnemonic. */
@@ -90,13 +90,102 @@ export interface SOAData {
     /** Bounds how long a negative answer may be cached (RFC 2308). */
     minimum: number;
 }
+/**
+ * The parameters of an SVCB or HTTPS record (RFC 9460), one optional field per key. A key
+ * that is absent was not published; `true` marks a key published without a value.
+ */
+export interface SvcParams {
+    /** Keys a client must understand to use the record, by presentation name (`alpn`, `key65000`). */
+    mandatory?: string[];
+    /** Protocol ids (`h2`, `h3`) in the publisher's order of preference. */
+    alpn?: string[];
+    /** The default ALPN (`http/1.1` for HTTPS) is unsupported; only `alpn` applies. */
+    noDefaultAlpn?: true;
+    port?: number;
+    /** IPv4 addresses a client may use before the target's A records resolve. */
+    ipv4Hint?: string[];
+    /** The ECHConfigList, base64-encoded as the presentation format writes it. */
+    ech?: string;
+    /** IPv6 addresses in RFC 5952 canonical form, as hints like `ipv4Hint`. */
+    ipv6Hint?: string[];
+    /** The DoH URI template's path (RFC 9461), relative to the target. */
+    dohPath?: string;
+    /** The service accepts Oblivious HTTP requests (RFC 9540). */
+    ohttp?: true;
+    /** Keys without a reading here, by key number, each value's octets read as UTF-8. */
+    other?: {
+        [key: number]: string;
+    };
+}
+/** A service binding (RFC 9460): where and how to reach the service at the owner. */
+export interface SVCBData {
+    type: "SVCB";
+    /** `0` is AliasMode, which only names `target`; any other value orders ServiceMode records, lowest first. */
+    priority: number;
+    /** The service's host; `"."` means the owner itself in ServiceMode and no service in AliasMode. */
+    target: string;
+    params: SvcParams;
+}
+/** The SVCB record for HTTPS origins (RFC 9460), published at the origin's own name. */
+export interface HTTPSData extends Omit<SVCBData, "type"> {
+    type: "HTTPS";
+}
+/** Binds a TLS certificate or public key to a service, DANE (RFC 6698, RFC 7671). */
+export interface TLSAData {
+    type: "TLSA";
+    /** `0` PKIX-TA, `1` PKIX-EE, `2` DANE-TA, `3` DANE-EE. */
+    usage: number;
+    /** `0` matches the whole certificate, `1` its SubjectPublicKeyInfo. */
+    selector: number;
+    /** `0` the exact bytes, `1` their SHA-256, `2` their SHA-512. */
+    matchingType: number;
+    /** Lowercase hex. */
+    certificateAssociation: string;
+}
+/** A digest of the child zone's key-signing key, published in the parent (RFC 4034). */
+export interface DSData {
+    type: "DS";
+    /** The key tag of the DNSKEY the digest is of, for picking it out of the child's key set. */
+    keyTag: number;
+    /** The DNSSEC algorithm number; `13` is ECDSA P-256 with SHA-256. */
+    algorithm: number;
+    /** `1` SHA-1, `2` SHA-256, `4` SHA-384. */
+    digestType: number;
+    /** Lowercase hex. */
+    digest: string;
+}
+/** The child's DS record as it asks the parent to publish it (RFC 7344); `0 0 0 00` asks for removal. */
+export interface CDSData extends Omit<DSData, "type"> {
+    type: "CDS";
+}
+/** A zone's public signing key (RFC 4034). */
+export interface DNSKEYData {
+    type: "DNSKEY";
+    /** The flags as published, so the record prints back unchanged. */
+    flags: number;
+    /** Bit 7 of `flags`: the key signs the zone's records; DNSSEC ignores a key without it. */
+    zoneKey: boolean;
+    /** Bit 15 of `flags`: the key is a key-signing key, the one a DS record points at. */
+    secureEntryPoint: boolean;
+    /** Always `3` in a valid key. */
+    protocol: number;
+    algorithm: number;
+    /** Base64, as the presentation format writes it. */
+    publicKey: string;
+    /** The RFC 4034 Appendix B tag a DS or RRSIG names this key by. */
+    keyTag: number;
+}
+/** The child's DNSKEY as it asks the parent to derive a DS from it (RFC 7344). */
+export interface CDNSKEYData extends Omit<DNSKEYData, "type"> {
+    type: "CDNSKEY";
+}
 /** Data of a type without a typed reading, kept as written. */
 export interface UnknownData {
     type: string;
     data: string;
 }
 /** A record's type-specific fields, what `parseRecordData` reads out of RDATA. */
-export type RecordData<Type extends RecordType> = Type extends "A" ? AData : Type extends "AAAA" ? AAAAData : Type extends "CNAME" ? CNAMEData : Type extends "NS" ? NSData : Type extends "PTR" ? PTRData : Type extends "DNAME" ? DNAMEData : Type extends "MX" ? MXData : Type extends "TXT" ? TXTData : Type extends "CAA" ? CAAData : Type extends "SRV" ? SRVData : Type extends "SOA" ? SOAData : UnknownData;
+export type RecordData<Type extends RecordType> = Type extends "A" ? AData : Type extends "AAAA" ? AAAAData : Type extends "CNAME" ? CNAMEData : Type extends "NS" ? NSData : Type extends "PTR" ? PTRData : Type extends "DNAME" ? DNAMEData : Type extends "MX" ? MXData : Type extends "TXT" ? TXTData : Type extends "CAA" ? CAAData : Type extends "SRV" ? SRVData : Type extends "SOA" ? SOAData : Type extends "SVCB" ? SVCBData : Type extends "HTTPS" ? HTTPSData : Type extends "TLSA" ? TLSAData : Type extends "DS" ? DSData : Type extends "CDS" ? CDSData : Type extends "DNSKEY" ? DNSKEYData : Type extends "CDNSKEY" ? CDNSKEYData : UnknownData;
 /** What every record read from a file carries beside its data. */
 export interface RecordFields {
     /** Absolute, lowercased, no trailing dot; the root is `"."`. */

package/package.json

@@ -1,16 +1,21 @@
 {
 	"name": "@sdxc/zone-file",
-	"version": "2026.10.13",
+	"version": "2026.11.3",
 	"description": "Read and write RFC 1035 DNS zone files, with the record data codec for every typed record",
 	"license": "MIT",
+	"bin": {
+		"sdxc-zone-file": "dist/cli.js"
+	},
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js"
 	},
 	"dependencies": {
-		"@sdxc/result": "2026.10.13"
+		"@sdxc/cli": "2026.11.3",
+		"@sdxc/result": "2026.10.13",
+		"remix": "3.1.0"
 	},
-	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
+	"gitHead": "d1dd4030f8df68b8a170940a3f790ea8654d3676",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -19,7 +24,7 @@
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/zone-file"
 	},
-	"homepage": "https://sdxc.sergiodxa.com/api/zone-file",
+	"homepage": "https://sdxc.dev/api/zone-file",
 	"author": {
 		"name": "Sergio Xalambrí",
 		"url": "https://sergiodxa.com"