moshcode 0.24.0

package/src/doh-server.mjs

@@ -0,0 +1,256 @@
+// The HTTP half of the DoH resolver.
+//
+// Plain HTTP on loopback, with TLS terminated by whatever already holds 443 on
+// the box — nginx, Caddy, or a platform load balancer. That is not a shortcut:
+// a resolver that manages its own certificate is a resolver that goes down when
+// the certificate expires, and every machine pointed at it loses DNS at once.
+// Renewal is a solved problem for exactly one process on a host, and it is not
+// this one.
+//
+// Which means this must never bind a public address. A DoH endpoint reachable
+// directly is an open resolver without the rate limits its proxy was going to
+// apply, and scanners find those in hours.
+
+import http from "node:http";
+import { createDohHandler, DNS_MESSAGE } from "./doh.mjs";
+import {
+  discoverUpstreams, fetchTlds, parseDnsPort, DEFAULT_REGISTRY_BASE, parkingAddress,
+} from "./dns.mjs";
+
+export const DEFAULT_DOH_PORT = 8053;
+export const DOH_PATH = "/dns-query";
+
+/**
+ * Guards on by default here, unlike the UDP bridge.
+ *
+ * The bridge listens on loopback and has one client, where rate limiting is
+ * pure cost. This is meant to be reachable, and an unprotected open resolver
+ * is found by scanners within hours of being published — so the safe
+ * configuration has to be the one you get by not thinking about it.
+ *
+ * The numbers are generous for a person and tight for a script: 20 queries a
+ * second sustained is far more than a browser produces and far less than a
+ * scraper wants.
+ */
+export const DEFAULT_GUARDS = {
+  rateLimit: { perSecond: 20, burst: 40 },
+  ban: { baseMs: 60_000, factor: 2, maxMs: 24 * 60 * 60 * 1000 },
+  // Caps amplification. 1232 is the payload size the DNS flag day settled on
+  // as safe across the internet, so nothing legitimate loses anything.
+  maxResponseBytes: 1232,
+};
+
+/**
+ * Read guard settings off the command line.
+ *
+ * `--no-guards` exists for running behind something that already limits, and
+ * is loud rather than silent: an unlimited open resolver is a decision, and
+ * the caller has to have typed it.
+ */
+export function parseGuardArgs(args = []) {
+  if (args.includes("--no-guards")) return { rateLimit: null, ban: null, maxResponseBytes: 0 };
+  const num = (flag, fallback) => {
+    const at = args.indexOf(flag);
+    if (at < 0) return fallback;
+    const value = Number(args[at + 1]);
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+  };
+  return {
+    rateLimit: {
+      perSecond: num("--rate", DEFAULT_GUARDS.rateLimit.perSecond),
+      burst: num("--burst", DEFAULT_GUARDS.rateLimit.burst),
+    },
+    ban: { ...DEFAULT_GUARDS.ban, baseMs: num("--ban-seconds", 60) * 1000 },
+    maxResponseBytes: num("--max-response", DEFAULT_GUARDS.maxResponseBytes),
+  };
+}
+
+/**
+ * Read the listen port off the command line.
+ *
+ * Same rule as the bridge's ports, by reusing the same parser: `dns install
+ * --port 1e3` is refused, so `doh --port 1e3` refusing it is one rule to learn
+ * rather than two. Bare `Number()` disagrees with that parser in both
+ * directions — it takes `1e3` and `0`, which it should not, and turns `abc`
+ * and a missing value into NaN, which reaches `listen()` as a crash.
+ *
+ * Returns the raw text back on failure so the caller can quote what was typed.
+ */
+export function parseDohPort(args = [], fallback = DEFAULT_DOH_PORT) {
+  const at = args.indexOf("--port");
+  if (at < 0) return { ok: true, port: fallback };
+  const raw = args[at + 1];
+  const port = parseDnsPort(raw);
+  return port === null ? { ok: false, raw } : { ok: true, port };
+}
+
+/** Read a request body, refusing anything implausible for a DNS message. */
+export function readBody(req, limit = 4096) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      // Hung up on rather than buffered: the cap is the point, and a client
+      // sending megabytes to a DNS endpoint is not a client.
+      if (size > limit) {
+        reject(new Error("too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+/**
+ * Who asked, as the proxy in front of us sees it.
+ *
+ * Behind a reverse proxy every request arrives from 127.0.0.1, so rate
+ * limiting on the socket address would put every client in one bucket — one
+ * abusive source would lock out everyone. The forwarded header is the only
+ * client identity available, and it is trustworthy exactly as far as the proxy
+ * is: fine when the proxy sets it, worthless if this is ever exposed directly,
+ * which is the other reason it must not be.
+ */
+export function clientAddress(req, { trustProxy = true } = {}) {
+  if (trustProxy) {
+    const forwarded = req.headers?.["x-forwarded-for"];
+    if (forwarded) return String(forwarded).split(",")[0].trim();
+  }
+  return req.socket?.remoteAddress || "";
+}
+
+/** Mount the DoH handler on an http server. Returns { port, address, close }. */
+export async function createDohServer({
+  port = DEFAULT_DOH_PORT,
+  host = "127.0.0.1",
+  registryBase = DEFAULT_REGISTRY_BASE,
+  path = DOH_PATH,
+  trustProxy = true,
+  handler = null,
+  onQuery = () => {},
+  ...guards
+} = {}) {
+  const applied = { ...DEFAULT_GUARDS, ...guards };
+  const handle = handler || createDohHandler({
+    registryBase,
+    upstreams: await discoverUpstreams(),
+    tldSet: new Set(await fetchTlds({ registryBase }).catch(() => [])),
+    parkingAddress: await parkingAddress().catch(() => null),
+    onQuery,
+    ...applied,
+  });
+
+  const server = http.createServer(async (req, res) => {
+    const url = req.url || "/";
+    if (!url.split("?")[0].endsWith(path)) {
+      res.writeHead(404, { "content-type": "text/plain" });
+      res.end("not here\n");
+      return;
+    }
+
+    let body = null;
+    if (req.method === "POST") {
+      try {
+        body = await readBody(req);
+      } catch {
+        res.writeHead(413, { "content-type": "text/plain" });
+        res.end("query too large\n");
+        return;
+      }
+    }
+
+    const answer = await handle({
+      method: req.method,
+      url,
+      body,
+      address: clientAddress(req, { trustProxy }),
+    }).catch(() => null);
+
+    if (!answer) {
+      res.writeHead(500, { "content-type": "text/plain" });
+      res.end("resolver error\n");
+      return;
+    }
+    res.writeHead(answer.status, answer.headers);
+    res.end(answer.body);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      const addr = server.address();
+      resolve({
+        port: addr.port,
+        address: addr.address,
+        url: `http://${addr.address}:${addr.port}${path}`,
+        guards: applied,
+        close: () => new Promise((done) => server.close(done)),
+      });
+    });
+  });
+}
+
+/**
+ * The reverse-proxy block that terminates TLS in front of this.
+ *
+ * Emitted rather than described because the two lines people miss are the two
+ * that matter: a DNS message is binary, so no charset and no gzip, and the
+ * client's address has to be forwarded or every client shares a rate-limit
+ * bucket.
+ *
+ * Port 80, not 443. `listen 443 ssl` without an `ssl_certificate` is a config
+ * nginx refuses to load at all — "no ssl_certificate is defined for the listen
+ * ... ssl directive" — so emitting the TLS form first is unusable by
+ * construction: nginx will not start with it, and `certbot --nginx` needs a
+ * loadable vhost to find before it can issue the certificate that would make it
+ * loadable. That is a cycle with no entry point.
+ *
+ * So this emits the half that stands on its own. certbot rewrites it in place,
+ * adding the 443 listeners, the certificate paths, and the redirect — which is
+ * also what leaves renewal owned by certbot rather than by whoever pasted this.
+ *
+ * Pass `tls: true` for the already-certified form, for a host provisioned some
+ * other way.
+ */
+export function nginxDohSite({ name, port = DEFAULT_DOH_PORT, path = DOH_PATH, tls = false }) {
+  const listeners = tls
+    ? ["\tlisten 443 ssl;", "\tlisten [::]:443 ssl;"]
+    : ["\tlisten 80;", "\tlisten [::]:80;"];
+  const certificate = tls
+    ? [`\tssl_certificate     /etc/letsencrypt/live/${name}/fullchain.pem;`,
+       `\tssl_certificate_key /etc/letsencrypt/live/${name}/privkey.pem;`]
+    : [`\t# TLS is not here yet. Install this, then: certbot --nginx -d ${name}`,
+       "\t# certbot adds the 443 listeners, the certificate, and the redirect,",
+       "\t# and owns the renewal afterwards."];
+  return [
+    `# ${name} — DoH endpoint, written by \`moshcode doh --nginx\`.`,
+    "#",
+    "# TLS is terminated here on purpose. A resolver that manages its own",
+    "# certificate goes down when that certificate expires, and every machine",
+    "# pointed at it loses DNS at once.",
+    "server {",
+    ...listeners,
+    `\tserver_name ${name};`,
+    "",
+    ...certificate,
+    "",
+    `\tlocation ${path} {`,
+    `\t\tproxy_pass http://127.0.0.1:${port};`,
+    "\t\tproxy_set_header Host $host;",
+    "\t\t# Without this every client shares one rate-limit bucket, because",
+    "\t\t# behind a proxy they all arrive from 127.0.0.1.",
+    "\t\tproxy_set_header X-Forwarded-For $remote_addr;",
+    "\t\t# A DNS message is binary. Compressing it wastes CPU and some",
+    "\t\t# clients reject a gzipped application/dns-message outright.",
+    "\t\tgzip off;",
+    "\t}",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export { DNS_MESSAGE };

package/src/doh.mjs

@@ -0,0 +1,218 @@
+// DNS over HTTPS for Moshpit names (RFC 8484).
+//
+// The same resolver, in an envelope browsers and phones already speak. That is
+// the whole reason it exists: a browser with Secure DNS enabled never asks the
+// system resolver, so a machine running the bridge perfectly still fails to
+// open a Moshpit name — `curl` resolves it and the browser does not. Pointing
+// that browser at a DoH endpoint which knows both namespaces resolves the name
+// *through* DoH instead of being defeated by it.
+//
+// It also reaches what the bridge cannot: phones, routers, and anyone else's
+// machine. No daemon, no root, one URL in a settings field.
+//
+// The privacy trade is real and does not disappear by being encrypted. DoH
+// hides lookups from the network and hands them, in full, to whoever runs the
+// endpoint. That is a move of trust, not a removal of it, and it is why this
+// keeps no per-query record of who asked what.
+
+import {
+  addressAnswer, answerRecords, buildChainResponse, buildRecordResponse, buildResponse,
+  capResponse, clientKey, createBanList, resolveChain,
+  createRateLimiter, forwardQuery, isOurs, answerPolicy, parseQuery, refusalReason,
+  RECORD_TYPES, TYPE_A, TYPE_AAAA, DEFAULT_TTL, UDP_SAFE_BYTES,
+} from "./dns.mjs";
+
+/** What RFC 8484 says both directions are. */
+export const DNS_MESSAGE = "application/dns-message";
+
+/** Answers are cacheable for as long as the record is, and no longer. */
+const MAX_QUERY_BYTES = 4096;
+
+/**
+ * Decode the DNS message out of a DoH request.
+ *
+ * GET carries it base64url in `?dns=`, POST carries it as the body. Both are
+ * required by the spec and clients differ: browsers mostly POST, some resolvers
+ * and every curl example use GET.
+ */
+export function decodeRequest({ method = "GET", url = "/", body = null } = {}) {
+  if (method === "POST") {
+    if (!body?.length) return { ok: false, status: 400, error: "empty body" };
+    if (body.length > MAX_QUERY_BYTES) return { ok: false, status: 413, error: "query too large" };
+    return { ok: true, message: Buffer.from(body) };
+  }
+  if (method !== "GET") return { ok: false, status: 405, error: "use GET or POST" };
+
+  const at = String(url).indexOf("?");
+  const params = new URLSearchParams(at >= 0 ? String(url).slice(at + 1) : "");
+  const encoded = params.get("dns");
+  if (!encoded) return { ok: false, status: 400, error: "missing ?dns=" };
+  try {
+    const message = Buffer.from(encoded, "base64url");
+    if (!message.length) return { ok: false, status: 400, error: "empty query" };
+    if (message.length > MAX_QUERY_BYTES) return { ok: false, status: 413, error: "query too large" };
+    return { ok: true, message };
+  } catch {
+    return { ok: false, status: 400, error: "?dns= is not base64url" };
+  }
+}
+
+/**
+ * How long a caching client may keep this answer.
+ *
+ * Bounded by the record's own TTL, which is short on purpose: a Moshpit name's
+ * target changes the moment its owner repoints it, and a stale answer is the
+ * one failure nobody can debug from the outside.
+ */
+export function cacheControl(ttl = DEFAULT_TTL) {
+  return `max-age=${Math.max(0, Math.floor(ttl))}`;
+}
+
+/** A REFUSED (rcode 5) answer echoing the question. */
+export function refusedMessage(query, message) {
+  const header = Buffer.alloc(12);
+  header.writeUInt16BE(query.id, 0);
+  // QR=1, AA=1, RD echoed, rcode 5.
+  header.writeUInt16BE(0x8400 | (query.recursionDesired ? 0x0100 : 0) | 5, 2);
+  header.writeUInt16BE(1, 4);
+  return Buffer.concat([header, message.subarray(12, query.questionEnd)]);
+}
+
+/**
+ * A DoH resolver over the existing bridge logic.
+ *
+ * Returns a handler taking a plain request shape and giving back a plain
+ * response shape, so it can be mounted on any server and tested without one.
+ */
+export function createDohHandler({
+  registryBase,
+  fetchImpl,
+  upstreams = [],
+  tldSet = null,
+  parkingAddress = null,
+  ttl = DEFAULT_TTL,
+  rateLimit = null,
+  ban = null,
+  maxResponseBytes = 0,
+  forwardTimeoutMs = 3000,
+  onQuery = () => {},
+} = {}) {
+  const limiter = rateLimit ? createRateLimiter(rateLimit) : null;
+  const bans = ban ? createBanList(ban) : null;
+
+  return async function handle({ method = "GET", url = "/", body = null, address = "" } = {}) {
+    const decoded = decodeRequest({ method, url, body });
+    if (!decoded.ok) {
+      return { status: decoded.status, headers: { "content-type": "text/plain" }, body: decoded.error };
+    }
+
+    const query = parseQuery(decoded.message);
+    if (!query) {
+      return { status: 400, headers: { "content-type": "text/plain" }, body: "not a DNS query" };
+    }
+
+    // Grouped by /64 for v6, as on the UDP side: a single address is free to
+    // change, so per-address limits are defeated by incrementing it.
+    const source = clientKey(address);
+    const refused = () => ({
+      status: 200,
+      headers: { "content-type": DNS_MESSAGE, "cache-control": "no-store" },
+      // A DNS-level REFUSED rather than an HTTP error: clients understand the
+      // former and retry elsewhere, where an HTTP 429 is frequently just an
+      // exception in a stack that expected a DNS message.
+      //
+      // Built here rather than through buildResponse, which only speaks the
+      // answer/NODATA/NXDOMAIN vocabulary. NXDOMAIN would be a lie with a
+      // cost: it says the name does not exist, which a resolver may cache and
+      // apply to every other type, so a rate-limited client would go on
+      // failing after the limit lifted.
+      body: refusedMessage(query, decoded.message),
+    });
+
+    if (refusalReason(query) || bans?.banned(source)) return refused();
+    if (limiter && !limiter.allow(source)) {
+      bans?.strike(source);
+      return refused();
+    }
+
+    // Not ours: relay to an upstream exactly as the UDP path does.
+    if (!isOurs(query.name, tldSet)) {
+      if (!upstreams.length) return refused();
+      let relayed = null;
+      for (const upstream of upstreams) {
+        relayed = await forwardQuery(decoded.message, upstream, { timeoutMs: forwardTimeoutMs });
+        if (relayed) break;
+      }
+      onQuery({ name: query.name, type: query.type, forwarded: true });
+      if (!relayed) {
+        return { status: 502, headers: { "content-type": "text/plain" }, body: "upstream did not answer" };
+      }
+      return {
+        status: 200,
+        headers: { "content-type": DNS_MESSAGE, "cache-control": cacheControl(ttl) },
+        body: maxResponseBytes ? capResponse(relayed, query, maxResponseBytes) : relayed,
+      };
+    }
+
+    // CNAME, MX and TXT come from the record set; addresses still come from
+    // `target`. Same split as the UDP path, and it has to stay the same split:
+    // a name that resolves over the bridge and not over DoH is the failure mode
+    // this endpoint exists to remove.
+    const wanted = RECORD_TYPES.get(query.type);
+    if (wanted) {
+      const found = await answerRecords(query.name, { registryBase, fetchImpl, type: wanted })
+        .catch(() => ({ exists: false, records: [] }));
+      onQuery({ name: query.name, type: query.type, records: found.records.length });
+      return {
+        status: 200,
+        headers: { "content-type": DNS_MESSAGE, "cache-control": cacheControl(ttl) },
+        body: buildRecordResponse(query, decoded.message, found.records, {
+          ttl, exists: found.exists, limit: maxResponseBytes || UDP_SAFE_BYTES,
+        }),
+      };
+    }
+
+    const wantsAddress = query.type === TYPE_A || query.type === TYPE_AAAA;
+    if (!wantsAddress) {
+      const policy = await answerPolicy(query.name, {
+        registryBase, fetchImpl, parkingAddress, wantsAddress: false,
+      }).catch(() => ({ exists: false, address: null }));
+      onQuery({ name: query.name, type: query.type, address: null });
+      return {
+        status: 200,
+        headers: { "content-type": DNS_MESSAGE, "cache-control": cacheControl(ttl) },
+        body: buildResponse(query, decoded.message, null, ttl, policy.exists),
+      };
+    }
+
+    // The same plan the UDP path follows, for the same reason the split above
+    // has to stay a split: a published record or a hostname target must resolve
+    // identically here, or this endpoint reintroduces the gap it exists to close.
+    const plan = await addressAnswer(query.name, {
+      registryBase, fetchImpl, parkingAddress, wantsV6: query.type === TYPE_AAAA,
+    }).catch(() => ({ exists: false, kind: "nxdomain", records: [], address: null, cname: null }));
+
+    const answer = async () => {
+      if (plan.kind === "records") {
+        return buildRecordResponse(query, decoded.message, plan.records, {
+          ttl, exists: plan.exists, limit: maxResponseBytes || UDP_SAFE_BYTES,
+        });
+      }
+      if (plan.kind === "chain") {
+        const addresses = await resolveChain(plan.cname, {
+          upstreams, wantsV6: query.type === TYPE_AAAA, timeoutMs: forwardTimeoutMs,
+        });
+        return buildChainResponse(query, decoded.message, { cname: plan.cname, addresses, ttl });
+      }
+      return buildResponse(query, decoded.message, plan.address, ttl, plan.exists);
+    };
+
+    const encoded = await answer();
+    onQuery({ name: query.name, type: query.type, address: plan.address || plan.cname || null });
+    return {
+      status: 200,
+      headers: { "content-type": DNS_MESSAGE, "cache-control": cacheControl(ttl) },
+      body: encoded,
+    };
+  };
+}