@sdxc/doh 2026.10.25 → 2026.11.10

package/README.md

@@ -75,6 +75,18 @@ let verdict = await mayIssue({ domain: "*.example.com", issuer: "letsencrypt.org
 if (!verdict.allowed) verdict.reason; // "not-authorized", "forbidden", "lookup-failed", …
 ```
 
+## Command line
+
+```sh
+bunx @sdxc/doh lookup example.com --type MX
+```
+
+With [`@sdxc/kit`](https://www.npmjs.com/package/@sdxc/kit) installed, `sdxc pkg doh …` runs the same command line, using the version your project installs.
+
+`lookup` prints a dig-style answer section, or the typed answer with `--json`, and exits 1 on
+NXDOMAIN, an empty answer or a resolver error. `--resolver` takes `cloudflare`, `google` or a DoH
+URL, and `--wire` speaks RFC 8484. `bunx @sdxc/doh --help` lists every flag.
+
 ## API
 
 ### `resolve(name, type, options?): Promise<Result<DoH.Answer<Type>, DoHError>>`

package/dist/cli-contract.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The `sdxc-doh` command line as a contract: `lookup` asks a DNS-over-HTTPS resolver for one
+ * name's records of one type. Help, usage errors and the handler's typed `ctx.arguments` and
+ * `ctx.flags` all come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Every command `sdxc-doh` takes. */
+export declare const DOH_COMMANDS: import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-doh — typed DNS over HTTPS lookups";
+    readonly lookup: import("@sdxc/cli").Command<{
+        readonly name: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly type: import("@sdxc/cli").ValueFlag<string, true, false, false>;
+        readonly resolver: import("@sdxc/cli").ValueFlag<string, true, false, false>;
+        readonly wire: import("@sdxc/cli").Flag<boolean>;
+        readonly dnssec: import("@sdxc/cli").Flag<boolean>;
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "flags" | "description" | "hidden" | "arguments" | "tasks">, Record<never, never>, Record<never, never>>;

package/dist/cli-contract.js

@@ -0,0 +1,78 @@
+/**
+ * The `sdxc-doh` command line as a contract: `lookup` asks a DNS-over-HTTPS resolver for one
+ * name's records of one type. Help, usage errors and the handler's typed `ctx.arguments` and
+ * `ctx.flags` all come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { argument, command, commands, flag } from "@sdxc/cli";
+import { canonicalType, typeCode } from "@sdxc/zone-file";
+import * as s from "remix/data-schema";
+/**
+ * A record type as a mnemonic or `TYPEnnn`, answered in its canonical spelling, so `mx` and
+ * `TYPE15` both query MX and an unknown mnemonic is a usage error naming what was typed.
+ */
+const RECORD_TYPE = s.createSchema(function validate(value, context) {
+    if (typeof value === "string" && typeCode(value) !== null) {
+        return { value: canonicalType(value) };
+    }
+    return s.fail(`expects a record type such as A, AAAA, MX or TYPE65; got ${JSON.stringify(value)}`, context.path);
+});
+/**
+ * A resolver as `cloudflare`, `google` or an `https:` DoH endpoint URL; the names come back
+ * lowercased and a URL as typed.
+ */
+const RESOLVER = s.createSchema(function validate(value, context) {
+    if (typeof value === "string") {
+        let lower = value.toLowerCase();
+        if (lower === "cloudflare" || lower === "google")
+            return { value: lower };
+        if (URL.canParse(value) && new URL(value).protocol === "https:")
+            return { value };
+    }
+    return s.fail(`expects cloudflare, google or an https:// URL; got ${JSON.stringify(value)}`, context.path);
+});
+/** Every command `sdxc-doh` takes. */
+export const DOH_COMMANDS = commands({
+    description: "sdxc-doh — typed DNS over HTTPS lookups",
+    lookup: command({
+        description: "Look up a name's records of one type and print them as a dig-style answer section. Exits 1 on NXDOMAIN, an empty answer or a resolver error, and 2 when the resolver cannot be reached.",
+        arguments: {
+            name: argument(s.string(), {
+                description: "The domain name, in its ASCII (punycode) form",
+            }),
+        },
+        flags: {
+            type: flag.string("type", {
+                short: "t",
+                valueName: "type",
+                default: "A",
+                schema: RECORD_TYPE,
+                description: "The record type: A, AAAA, MX, TXT, CNAME, NS, CAA, SOA, HTTPS, …",
+            }),
+            resolver: flag.string("resolver", {
+                short: "r",
+                valueName: "url",
+                default: "cloudflare",
+                schema: RESOLVER,
+                description: "cloudflare, google or a DoH endpoint URL",
+            }),
+            wire: flag.boolean("wire", {
+                description: "Speak RFC 8484 wire format instead of the JSON API, which also reports extended DNS errors",
+            }),
+            dnssec: flag.boolean("dnssec", {
+                description: "Set the DO bit, asking for DNSSEC records alongside the answer",
+            }),
+            json: flag.boolean("json", {
+                description: "Print the answer as JSON: { name, type, records, unparsed, chain, ttl, authenticated, … }, or { name, type, error } on failure",
+            }),
+        },
+        examples: [
+            "lookup example.com",
+            "lookup example.com --type MX",
+            "lookup _dmarc.example.com --type TXT --json",
+            "lookup example.com --type AAAA --resolver google --wire",
+        ],
+    }),
+});

package/dist/cli-lookup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `sdxc-doh lookup` handler: one `resolve` call printed as a dig-style answer section, or
+ * as JSON. NXDOMAIN, an empty answer and a resolver error exit 1; a resolver that never
+ * answered exits 2, since the lookup itself could not run.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Prints the chain, the records and any unparsed records in answer order; the answer section
+ * goes to stdout and the closing summary to stderr, so piping keeps only records.
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly name: import("@sdxc/cli").Argument<string>;
+}, {
+    readonly type: import("@sdxc/cli").ValueFlag<string, true, false, false>;
+    readonly resolver: import("@sdxc/cli").ValueFlag<string, true, false, false>;
+    readonly wire: import("@sdxc/cli").Flag<boolean>;
+    readonly dnssec: import("@sdxc/cli").Flag<boolean>;
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-lookup.js

@@ -0,0 +1,68 @@
+/**
+ * The `sdxc-doh lookup` handler: one `resolve` call printed as a dig-style answer section, or
+ * as JSON. NXDOMAIN, an empty answer and a resolver error exit 1; a resolver that never
+ * answered exits 2, since the lookup itself could not run.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, exit, success } from "@sdxc/cli";
+import { isFailure } from "@sdxc/result";
+import { formatRecordData } from "@sdxc/zone-file";
+import { DOH_COMMANDS } from "./cli-contract.js";
+import { TransportError } from "./errors.js";
+import { resolve } from "./resolve.js";
+import { CLOUDFLARE, CLOUDFLARE_WIRE, GOOGLE, GOOGLE_WIRE } from "./resolvers.js";
+/**
+ * The resolver a `--resolver` value and `--wire` name: the public ones by name, in the format
+ * asked for, and any other value as an endpoint URL.
+ */
+function pickResolver(resolver, wire) {
+    if (resolver === "cloudflare")
+        return wire ? CLOUDFLARE_WIRE : CLOUDFLARE;
+    if (resolver === "google")
+        return wire ? GOOGLE_WIRE : GOOGLE;
+    return { url: resolver, format: wire ? "wire" : "json" };
+}
+/** One record as a zone-file line: absolute owner, TTL, class, type and canonical data. */
+function line(record) {
+    let data = formatRecordData(record);
+    return `${record.name}.\t${record.ttl}\tIN\t${record.type}\t${data}`;
+}
+/** A failure as data: its class name, message and the own fields a script may branch on (`ttl`, `rcode`, `status`, …). */
+function describeError(error) {
+    return { name: error.name, message: error.message, ...Object.fromEntries(Object.entries(error)) };
+}
+/**
+ * Prints the chain, the records and any unparsed records in answer order; the answer section
+ * goes to stdout and the closing summary to stderr, so piping keeps only records.
+ */
+export default createCommand(DOH_COMMANDS.lookup, async (ctx) => {
+    let { name } = ctx.arguments;
+    let { type, json } = ctx.flags;
+    let answer = await resolve(name, type, {
+        resolver: pickResolver(ctx.flags.resolver, ctx.flags.wire === true),
+        dnssec: ctx.flags.dnssec === true,
+        signal: ctx.signal,
+    });
+    if (isFailure(answer)) {
+        let code = answer.error instanceof TransportError ? 2 : 1;
+        if (json) {
+            ctx.stdout(`${JSON.stringify({ name, type, error: describeError(answer.error) }, null, 2)}\n`);
+            return exit(code);
+        }
+        return exit(code, answer.error.message);
+    }
+    let { records, unparsed, chain } = answer.data;
+    let empty = records.length === 0 && unparsed.length === 0;
+    if (json) {
+        ctx.stdout(`${JSON.stringify(answer.data, null, 2)}\n`);
+        return empty ? exit(1) : success();
+    }
+    if (empty)
+        return exit(1, `${answer.data.name} has no ${type} records (NODATA)`);
+    let lines = [...chain, ...records, ...unparsed].map(line);
+    ctx.stdout(`;; ANSWER SECTION:\n${lines.join("\n")}\n`);
+    ctx.stderr(`;; Query time: ${Math.round(answer.data.durationMs)} msec\n`);
+    return success();
+});

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-doh` command-line program: the contract in `cli-contract.ts` with `lookup` mapped
+ * onto its handler, which loads only when a lookup runs. Exit codes: 0 records found, 1
+ * NXDOMAIN, an empty answer or a resolver error, 2 usage or an unreachable resolver.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The `sdxc-doh` program, run by the bin entry below and by tests through `invoke()`. */
+export declare const cli: import("@sdxc/cli").CLI<import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-doh — typed DNS over HTTPS lookups";
+    readonly lookup: import("@sdxc/cli").Command<{
+        readonly name: import("@sdxc/cli").Argument<string>;
+    }, {
+        readonly type: import("@sdxc/cli").ValueFlag<string, true, false, false>;
+        readonly resolver: import("@sdxc/cli").ValueFlag<string, true, false, false>;
+        readonly wire: import("@sdxc/cli").Flag<boolean>;
+        readonly dnssec: import("@sdxc/cli").Flag<boolean>;
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "flags" | "description" | "hidden" | "arguments" | "tasks">, Record<never, never>, Record<never, never>>, []>;

package/dist/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-doh` command-line program: the contract in `cli-contract.ts` with `lookup` mapped
+ * onto its handler, which loads only when a lookup runs. Exit codes: 0 records found, 1
+ * NXDOMAIN, an empty answer or a resolver error, 2 usage or an unreachable resolver.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCLI, lazy } from "@sdxc/cli";
+import { DOH_COMMANDS } from "./cli-contract.js";
+/** The `sdxc-doh` program, run by the bin entry below and by tests through `invoke()`. */
+export const cli = createCLI({ name: "sdxc-doh", commands: DOH_COMMANDS });
+cli.map(DOH_COMMANDS.lookup, lazy(() => import("./cli-lookup.js")));
+if (import.meta.main) {
+    process.exit(await cli.run(process.argv.slice(2)));
+}

package/package.json

@@ -1,21 +1,25 @@
 {
 	"name": "@sdxc/doh",
-	"version": "2026.10.25",
+	"version": "2026.11.10",
 	"description": "Typed DNS over HTTPS lookups",
 	"license": "MIT",
+	"bin": {
+		"sdxc-doh": "dist/cli.js"
+	},
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
 		"./caa": "./dist/caa.js"
 	},
 	"dependencies": {
+		"@sdxc/cli": "2026.11.10",
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/zone-file": "2026.10.25"
+		"@sdxc/zone-file": "2026.11.10"
 	},
 	"peerDependencies": {
-		"remix": "3.1.0"
+		"remix": "3.2.0"
 	},
-	"gitHead": "1440b969c0a3e3808dfcee3f17d2ef43915f32a8",
+	"gitHead": "6191b60a13885b1d826884d574c4a393f9b8eeee",
 	"publishConfig": {
 		"access": "public"
 	},