@blamejs/core 0.8.52 → 0.8.58

package/lib/network-dns.js

@@ -594,7 +594,7 @@ async function _dotLookup(host, family) {
       ready:      new Promise(function (res, rej) {
         sock.once("secureConnect", function () { res(); });
         sock.once("error", function (e) {
-          rej(new DnsError("dns/dot-handshake",
+          rej(new DnsError("dns/dot-handshake-failed",
             "DoT TLS handshake to " + STATE.dot.host + ":" + STATE.dot.port +
             " failed: " + ((e && e.message) || String(e))));
         });
@@ -671,6 +671,793 @@ function _resetDotPool() {
   for (var i = 0; i < keys.length; i++) _dotEvict(keys[i]);
 }
 
+// ---- Generic DNS query (arbitrary QTYPE) -----------------------------
+//
+// The pre-v0.8.53 DNS module only handled A (1) and AAAA (28) lookups.
+// SVCB (64) / HTTPS (65) and the DDR / DNR discovery primitives need a
+// path that sends an arbitrary QTYPE and returns the raw rdata buffers
+// for downstream parsing. These helpers reuse the existing encode +
+// transport infrastructure (DoH / DoT / system) and add a small
+// rdata-aware decoder that walks the answer section preserving the
+// rdata bytes and answer offsets (needed because SVCB rdata contains
+// compressed names that point back into the message).
+//
+// NOT IN SCOPE — DoQ (DNS-over-QUIC, RFC 9250). Node's QUIC support is
+// experimental as of Node 24.x (tracking issue
+// https://github.com/nodejs/node/issues/38478) and the framework's
+// "no flag-gated experimental APIs in defaults" policy keeps it
+// deferred. Operators wanting DoQ today wire it in their own agent
+// and feed the returned IP set back through the existing transport
+// abstractions (DDR-discovered DoH / DoT). Re-evaluate when Node
+// flips QUIC stable.
+
+// RFC 1035 §4.1.4 name compression — read a possibly-compressed name
+// starting at `start`. Returns { name, nextOff } where nextOff is the
+// byte immediately after the name's length-prefixed encoding (NOT
+// chasing the pointer). `name` is a dot-joined string (without the
+// trailing root label). Hardened against pointer loops with an
+// iteration cap.
+function _readDnsName(buf, start) {
+  var labels = [];
+  var off = start;
+  var nextOff = -1;
+  var iterations = 0;
+  var ITER_CAP = 256;                                                            // allow:raw-byte-literal — DNS name pointer-loop safeguard
+  while (off < buf.length && iterations < ITER_CAP) {
+    iterations += 1;
+    var len = buf[off];
+    if (len === 0) {
+      if (nextOff === -1) nextOff = off + 1;
+      break;
+    }
+    if ((len & 0xc0) === 0xc0) {                                                 // allow:raw-byte-literal — RFC 1035 name-compression pointer mask
+      if (off + 1 >= buf.length) {
+        throw new DnsError("dns/svcb-malformed",
+          "DNS name truncated at compression pointer");
+      }
+      if (nextOff === -1) nextOff = off + 2;
+      var ptr = ((len & 0x3f) << 8) | buf[off + 1];                              // allow:raw-byte-literal — RFC 1035 pointer offset mask
+      if (ptr >= buf.length || ptr === off) {
+        throw new DnsError("dns/svcb-malformed",
+          "DNS name pointer out of bounds or self-referential");
+      }
+      off = ptr;
+      continue;
+    }
+    if ((len & 0xc0) !== 0) {                                                    // allow:raw-byte-literal — RFC 1035 reserved label-type bits
+      throw new DnsError("dns/svcb-malformed",
+        "DNS name has reserved label type 0x" + len.toString(HEX_RADIX));
+    }
+    if (off + 1 + len > buf.length) {
+      throw new DnsError("dns/svcb-malformed",
+        "DNS name label exceeds message length");
+    }
+    labels.push(buf.toString("ascii", off + 1, off + 1 + len));
+    off += 1 + len;
+  }
+  if (iterations >= ITER_CAP) {
+    throw new DnsError("dns/svcb-malformed",
+      "DNS name compression loop (>" + ITER_CAP + " hops)");
+  }
+  if (nextOff === -1) {
+    throw new DnsError("dns/svcb-malformed",
+      "DNS name not terminated");
+  }
+  return { name: labels.join("."), nextOff: nextOff };
+}
+
+// Walk the answer section preserving rdata offsets so SVCB rdata can
+// resolve compressed names against the full message buffer.
+function _decodeDnsAnswerRaw(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 12) {
+    throw new DnsError("dns/bad-reply", "dns reply truncated");
+  }
+  var rcode = buf.readUInt8(3) & 0x0f;                                           // allow:raw-byte-literal — RFC 1035 RCODE nibble mask
+  if (rcode !== 0) {
+    throw new DnsError("dns/no-result", "dns reply rcode " + rcode);
+  }
+  var qdcount = buf.readUInt16BE(4);
+  var ancount = buf.readUInt16BE(6);
+  var state = { off: 12 };
+  for (var q = 0; q < qdcount; q++) {
+    _skipDnsName(buf, state);
+    state.off += 4;
+  }
+  var answers = [];
+  for (var a = 0; a < ancount; a++) {
+    _skipDnsName(buf, state);
+    var off = state.off;
+    if (off + 10 > buf.length) {
+      throw new DnsError("dns/bad-reply", "answer record truncated");
+    }
+    var rtype = buf.readUInt16BE(off); off += 2;
+    var rclass = buf.readUInt16BE(off); off += 2;
+    var ttl = buf.readUInt32BE(off); off += 4;
+    var rdlen = buf.readUInt16BE(off); off += 2;
+    if (off + rdlen > buf.length) {
+      throw new DnsError("dns/bad-reply", "answer rdata truncated");
+    }
+    answers.push({
+      rtype:    rtype,
+      rclass:   rclass,
+      ttl:      ttl,
+      rdataOff: off,
+      rdlen:    rdlen,
+    });
+    off += rdlen;
+    state.off = off;
+  }
+  return { msg: buf, answers: answers, ad: _readAdBit(buf) };
+}
+
+async function _dohRawQuery(host, qtype) {
+  var enc = _encodeDnsQuery(host, qtype);
+  var b64 = enc.buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  var getUrl = STATE.doh.url + (STATE.doh.url.indexOf("?") === -1 ? "?" : "&") + "dns=" + b64;
+  var forcedMethod = STATE.doh.method;
+  var usePost = forcedMethod === "POST" || (!forcedMethod && getUrl.length > DOH_GET_URL_MAX_BYTES);
+  var u = safeUrl.parse(STATE.doh.url, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS });
+  return new Promise(function (resolve, reject) {
+    var reqOpts = {
+      hostname:   u.hostname,
+      port:       u.port || 443,                                                 // allow:raw-byte-literal — HTTPS default port
+      path:       u.pathname + u.search,
+      method:     usePost ? "POST" : "GET",
+      headers:    { "accept": "application/dns-message" },
+      minVersion: "TLSv1.3",
+      ecdhCurve:  C.TLS_GROUP_CURVE_STR,
+    };
+    if (STATE.doh.ca) reqOpts.ca = STATE.doh.ca;
+    if (usePost) {
+      reqOpts.headers["content-type"]   = "application/dns-message";
+      reqOpts.headers["content-length"] = enc.buf.length;
+    } else {
+      var parsedGet = safeUrl.parse(getUrl, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS });
+      reqOpts.path = parsedGet.pathname + parsedGet.search;
+    }
+    var req = https.request(reqOpts, function (res) {
+      var collector = safeBuffer.boundedChunkCollector({
+        maxBytes:    C.BYTES.kib(256),
+        errorClass:  DnsError,
+        sizeCode:    "dns/doh-too-large",
+        sizeMessage: "DoH response exceeds 256 KiB",
+      });
+      var pushFailed = null;
+      res.on("data", function (c) {
+        if (pushFailed) return;
+        try { collector.push(c); }
+        catch (e) { pushFailed = e; }
+      });
+      res.on("end", function () {
+        try {
+          if (pushFailed) { reject(pushFailed); return; }
+          if (res.statusCode !== 200) {                                          // allow:raw-byte-literal — HTTP 200 OK
+            reject(new DnsError("dns/doh-http", "DoH HTTP " + res.statusCode + " for " + host));
+            return;
+          }
+          resolve(collector.result());
+        } catch (e) { reject(e); }
+      });
+    });
+    req.on("error", function (e) { reject(new DnsError("dns/doh-failed", "DoH request failed: " + e.message)); });
+    if (usePost) req.write(enc.buf);
+    req.end();
+  });
+}
+
+async function _dotRawQuery(host, qtype) {
+  var enc = _encodeDnsQuery(host, qtype);
+  var key = _dotPoolKey();
+  var entry = _dotPool.get(key);
+  if (entry && (Date.now() - entry.lastUsedAt > DOT_IDLE_TIMEOUT_MS)) {
+    _dotEvict(key);
+    entry = null;
+  }
+  if (!entry) {
+    var sock = _dotConnect();
+    entry = {
+      sock:       sock,
+      lastUsedAt: Date.now(),
+      idle:       true,
+      ready:      new Promise(function (res, rej) {
+        sock.once("secureConnect", function () { res(); });
+        sock.once("error", function (e) {
+          rej(new DnsError("dns/dot-handshake-failed",
+            "DoT TLS handshake to " + STATE.dot.host + ":" + STATE.dot.port +
+            " failed: " + ((e && e.message) || String(e))));
+        });
+      }),
+    };
+    entry.ready.catch(function () { /* observed via per-lookup handler below */ });
+    _dotPool.set(key, entry);
+    sock.on("error", function () { _dotEvict(key); });
+    sock.on("close", function () { if (_dotPool.get(key) === entry) _dotPool.delete(key); });
+  }
+  var waitTicket = entry._tail || Promise.resolve();
+  entry._tail = waitTicket.then(function () {
+    return new Promise(function (resolve, reject) {
+      entry.idle = false;
+      try { entry.sock.ref(); } catch (_e) { /* best-effort event-loop hold */ }
+      Promise.resolve(entry.ready).then(function () {
+        var lenBuf = Buffer.alloc(2);
+        lenBuf.writeUInt16BE(enc.buf.length, 0);
+        var got = [];
+        var expectLen = -1;
+        var done = false;
+        function settle(err, val) {
+          if (done) return;
+          done = true;
+          entry.sock.removeListener("data", onData);
+          entry.sock.removeListener("error", onErr);
+          entry.idle = true;
+          entry.lastUsedAt = Date.now();
+          try { entry.sock.unref(); } catch (_e) { /* best-effort event-loop release */ }
+          if (err) reject(err); else resolve(val);
+        }
+        function onData(chunk) {
+          got.push(chunk);
+          var all = Buffer.concat(got);
+          if (expectLen === -1 && all.length >= 2) expectLen = all.readUInt16BE(0);
+          if (expectLen >= 0 && all.length >= expectLen + 2) {
+            settle(null, all.slice(2, 2 + expectLen));
+          }
+        }
+        function onErr(e) {
+          _dotEvict(key);
+          settle(new DnsError("dns/dot-failed", "DoT failed: " + e.message));
+        }
+        entry.sock.on("data", onData);
+        entry.sock.on("error", onErr);
+        entry.sock.write(lenBuf);
+        entry.sock.write(enc.buf);
+      }, function (handshakeErr) {
+        entry.idle = true;
+        try { entry.sock.unref(); } catch (_e) { /* best-effort event-loop release */ }
+        reject(handshakeErr);
+      });
+    });
+  });
+  return entry._tail;
+}
+
+async function _systemRawQuery(host, qtype) {
+  // node:dns doesn't expose arbitrary-QTYPE wire-format queries; fall
+  // back to TCP framed query against the configured system resolvers
+  // (port 53). Used only when the operator has explicitly opted out
+  // of DoH/DoT via useSystemResolver().
+  var servers = getServers();
+  if (servers.length === 0) {
+    throw new DnsError("dns/no-system-resolvers",
+      "system resolver has no configured servers; cannot send raw QTYPE query");
+  }
+  var serverEntry = servers[0];
+  var serverHost = serverEntry;
+  var serverPort = 53;                                                           // allow:raw-byte-literal — IANA-assigned DNS port
+  var bracketEnd = serverEntry.lastIndexOf("]:");
+  if (bracketEnd !== -1) {
+    serverHost = serverEntry.slice(1, bracketEnd);
+    serverPort = parseInt(serverEntry.slice(bracketEnd + 2), 10) || 53;          // allow:raw-byte-literal — IANA-assigned DNS port
+  } else if (serverEntry.indexOf(":") !== -1 && net.isIP(serverEntry) === 0) {
+    var colonIdx = serverEntry.lastIndexOf(":");
+    serverHost = serverEntry.slice(0, colonIdx);
+    serverPort = parseInt(serverEntry.slice(colonIdx + 1), 10) || 53;            // allow:raw-byte-literal — IANA-assigned DNS port
+  }
+  var enc = _encodeDnsQuery(host, qtype);
+  return new Promise(function (resolve, reject) {
+    var sock = net.connect({ host: serverHost, port: serverPort });
+    var got = [];
+    var expectLen = -1;
+    var done = false;
+    function settle(err, val) {
+      if (done) return;
+      done = true;
+      try { sock.destroy(); } catch (_e) { /* best-effort socket teardown */ }
+      if (err) reject(err); else resolve(val);
+    }
+    sock.on("connect", function () {
+      var lenBuf = Buffer.alloc(2);
+      lenBuf.writeUInt16BE(enc.buf.length, 0);
+      sock.write(lenBuf);
+      sock.write(enc.buf);
+    });
+    sock.on("data", function (chunk) {
+      got.push(chunk);
+      var all = Buffer.concat(got);
+      if (expectLen === -1 && all.length >= 2) expectLen = all.readUInt16BE(0);
+      if (expectLen >= 0 && all.length >= expectLen + 2) {
+        settle(null, all.slice(2, 2 + expectLen));
+      }
+    });
+    sock.on("error", function (e) {
+      settle(new DnsError("dns/system-failed", "system DNS TCP query failed: " + e.message));
+    });
+    sock.on("close", function () {
+      if (!done) settle(new DnsError("dns/system-failed", "system DNS TCP closed before reply"));
+    });
+  });
+}
+
+// Pick a transport for raw-QTYPE queries based on operator config.
+// `forceTransport` (used by DDR) overrides; "system" routes through
+// the OS resolver.
+async function _rawQuery(host, qtype, forceTransport) {
+  _ensureSecureDefault();
+  var transport = forceTransport;
+  if (!transport) {
+    if (STATE.doh) transport = "doh";
+    else if (STATE.dot) transport = "dot";
+    else transport = "system";
+  }
+  if (transport === "doh") {
+    if (!STATE.doh) {
+      throw new DnsError("dns/transport-unavailable",
+        "raw query requested DoH transport but useDnsOverHttps() not configured");
+    }
+    return _withTimeout(_dohRawQuery(host, qtype), STATE.lookupTimeoutMs, host);
+  }
+  if (transport === "dot") {
+    if (!STATE.dot) {
+      throw new DnsError("dns/transport-unavailable",
+        "raw query requested DoT transport but useDnsOverTls() not configured");
+    }
+    return _withTimeout(_dotRawQuery(host, qtype), STATE.lookupTimeoutMs, host);
+  }
+  if (transport === "system") {
+    return _withTimeout(_systemRawQuery(host, qtype), STATE.lookupTimeoutMs, host);
+  }
+  throw new DnsError("dns/bad-transport",
+    "raw query: unknown transport '" + transport + "' (expected 'doh' | 'dot' | 'system')");
+}
+
+// ---- SVCB / HTTPS RR (RFC 9460) --------------------------------------
+
+var DNS_QTYPE_SVCB  = 64;                                                        // allow:raw-byte-literal — RFC 9460 §14.1 SVCB record type code
+var DNS_QTYPE_HTTPS = 65;                                                        // allow:raw-byte-literal — RFC 9460 §14.1 HTTPS record type code
+
+// SvcParamKey assignments (RFC 9460 §14.3.2 + IANA registry). Keys
+// past 7 are operator-extensible; we recognize the IETF-blessed set
+// and surface the rest as opaque buffers under params.unknown[<key>].
+var SVCB_KEY_MANDATORY    = 0;
+var SVCB_KEY_ALPN         = 1;
+var SVCB_KEY_NO_DEF_ALPN  = 2;
+var SVCB_KEY_PORT         = 3;
+var SVCB_KEY_IPV4HINT     = 4;
+var SVCB_KEY_ECH          = 5;
+var SVCB_KEY_IPV6HINT     = 6;
+var SVCB_KEY_DOHPATH      = 7;                                                   // allow:raw-byte-literal — RFC 9461 SvcParamKey
+
+function _readCharString(buf, off, end) {
+  if (off >= end) {
+    throw new DnsError("dns/svcb-malformed", "alpn list truncated at char-string length");
+  }
+  var len = buf[off];
+  if (off + 1 + len > end) {
+    throw new DnsError("dns/svcb-malformed", "alpn char-string overflows alpn value");
+  }
+  return { value: buf.toString("utf8", off + 1, off + 1 + len), nextOff: off + 1 + len };
+}
+
+function _parseSvcbRdata(msg, rdataOff, rdlen) {
+  var end = rdataOff + rdlen;
+  if (rdataOff + 2 > end) {
+    throw new DnsError("dns/svcb-malformed", "SVCB rdata truncated before priority");
+  }
+  var priority = msg.readUInt16BE(rdataOff);
+  var nameRes = _readDnsName(msg, rdataOff + 2);
+  var target = nameRes.name === "" ? "." : nameRes.name;
+  var off = nameRes.nextOff;
+  var params = {};
+  var prevKey = -1;
+  while (off < end) {
+    if (off + 4 > end) {
+      throw new DnsError("dns/svcb-malformed", "SvcParam header truncated");
+    }
+    var key = msg.readUInt16BE(off); off += 2;
+    var paramLen = msg.readUInt16BE(off); off += 2;
+    if (off + paramLen > end) {
+      throw new DnsError("dns/svcb-malformed", "SvcParam value overflows rdata");
+    }
+    if (key <= prevKey) {
+      throw new DnsError("dns/svcb-malformed",
+        "SvcParams not in ascending key order (key " + key + " after " + prevKey + ")");
+    }
+    prevKey = key;
+    var paramEnd = off + paramLen;
+    if (key === SVCB_KEY_MANDATORY) {
+      if (paramLen % 2 !== 0) {
+        throw new DnsError("dns/svcb-malformed", "mandatory SvcParam length not multiple of 2");
+      }
+      var mand = [];
+      for (var mo = off; mo < paramEnd; mo += 2) {
+        mand.push(msg.readUInt16BE(mo));
+      }
+      params.mandatory = mand;
+    } else if (key === SVCB_KEY_ALPN) {
+      var alpns = [];
+      var ao = off;
+      while (ao < paramEnd) {
+        var cs = _readCharString(msg, ao, paramEnd);
+        alpns.push(cs.value);
+        ao = cs.nextOff;
+      }
+      params.alpn = alpns;
+    } else if (key === SVCB_KEY_NO_DEF_ALPN) {
+      if (paramLen !== 0) {
+        throw new DnsError("dns/svcb-malformed", "no-default-alpn must have zero-length value");
+      }
+      params.noDefaultAlpn = true;
+    } else if (key === SVCB_KEY_PORT) {
+      if (paramLen !== 2) {
+        throw new DnsError("dns/svcb-malformed", "port SvcParam must be 2 bytes");
+      }
+      params.port = msg.readUInt16BE(off);
+    } else if (key === SVCB_KEY_IPV4HINT) {
+      if (paramLen % 4 !== 0) {
+        throw new DnsError("dns/svcb-malformed", "ipv4hint length not multiple of 4");
+      }
+      var v4 = [];
+      for (var v4o = off; v4o < paramEnd; v4o += 4) {
+        v4.push(msg[v4o] + "." + msg[v4o + 1] + "." + msg[v4o + 2] + "." + msg[v4o + 3]);
+      }
+      params.ipv4hint = v4;
+    } else if (key === SVCB_KEY_ECH) {
+      // ECHConfigList — opaque to the caller; surface as raw buffer.
+      params.ech = Buffer.from(msg.slice(off, paramEnd));
+    } else if (key === SVCB_KEY_IPV6HINT) {
+      if (paramLen % IPV6_ADDR_BYTES !== 0) {
+        throw new DnsError("dns/svcb-malformed", "ipv6hint length not multiple of 16");
+      }
+      var v6 = [];
+      for (var v6o = off; v6o < paramEnd; v6o += IPV6_ADDR_BYTES) {
+        var groups = [];
+        for (var g = 0; g < IPV6_HEX_GROUPS; g++) {
+          groups.push(msg.readUInt16BE(v6o + g * 2).toString(HEX_RADIX));
+        }
+        v6.push(groups.join(":"));
+      }
+      params.ipv6hint = v6;
+    } else if (key === SVCB_KEY_DOHPATH) {
+      params.dohpath = msg.toString("utf8", off, paramEnd);
+    } else {
+      // Unknown / future SvcParamKey — surface as opaque bytes so the
+      // operator can still read it without us silently dropping the
+      // record.
+      if (!params.unknown) params.unknown = {};
+      params.unknown[key] = Buffer.from(msg.slice(off, paramEnd));
+    }
+    off = paramEnd;
+  }
+  return { priority: priority, target: target, params: params };
+}
+
+function _validateLdh(host, primitive) {
+  if (typeof host !== "string" || host.length === 0 || host.length > 253) {     // allow:raw-byte-literal — RFC 1035 hostname octet ceiling
+    throw new DnsError("dns/bad-host",
+      primitive + ": host must be a non-empty RFC 1035 LDH name (length 1..253)");
+  }
+  // Allow leading underscore on labels (SVCB / HTTPS query targets like
+  // "_dns.resolver.arpa" require it).
+  var labels = host.split(".");
+  for (var li = 0; li < labels.length; li += 1) {
+    var label = labels[li];
+    if (label.length === 0 || label.length > 63) {                                            // allow:raw-byte-literal — RFC 1035 max label length
+      throw new DnsError("dns/bad-host",
+        primitive + ": host label length must be 1..63");
+    }
+    if (!/^[A-Za-z0-9_](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?$/.test(label)) {
+      throw new DnsError("dns/bad-host",
+        primitive + ": host label '" + label + "' violates LDH (allowed: letters/digits/underscore/hyphen, no leading/trailing hyphen)");
+    }
+  }
+}
+
+async function _querySvcbLike(host, qtype, opts) {
+  opts = opts || {};
+  validateOpts(opts, ["transport"], "dns.querySvcb");
+  _validateLdh(host, "dns.querySvcb");
+  if (opts.transport !== undefined && opts.transport !== "doh" &&
+      opts.transport !== "dot" && opts.transport !== "system") {
+    throw new DnsError("dns/bad-transport",
+      "dns.querySvcb: transport must be 'doh' | 'dot' | 'system' | undefined");
+  }
+  _emitObs("network.dns.svcb.requested", { qtype: qtype, transport: opts.transport || "auto" });
+  var startMs = _now();
+  var reply;
+  try {
+    reply = await _rawQuery(host, qtype, opts.transport);
+  } catch (e) {
+    _emitObs("network.dns.svcb.failure", {
+      latencyMs: _now() - startMs,
+      code:      e.code || "unknown",
+    });
+    throw e;
+  }
+  var decoded = _decodeDnsAnswerRaw(reply);
+  var records = [];
+  for (var i = 0; i < decoded.answers.length; i++) {
+    var ans = decoded.answers[i];
+    if (ans.rtype !== qtype) continue;
+    records.push(_parseSvcbRdata(decoded.msg, ans.rdataOff, ans.rdlen));
+  }
+  records.sort(function (a, b) { return a.priority - b.priority; });
+  _emitObs("network.dns.svcb.success", {
+    latencyMs: _now() - startMs,
+    count:     records.length,
+    qtype:     qtype,
+  });
+  return records;
+}
+
+/**
+ * @primitive b.network.dns.querySvcb
+ * @signature b.network.dns.querySvcb(name, opts?)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.dns.queryHttps, b.network.dns.discoverEncrypted
+ *
+ * Query SVCB records (RFC 9460 §2) for `name`. Returns an array of
+ * `{ priority, target, params }` records sorted by priority. AliasMode
+ * records (priority === 0) carry a `target` and empty `params` —
+ * the caller chases the alias by re-querying the target. ServiceMode
+ * records (priority > 0) carry SvcParams: `alpn` / `port` / `ipv4hint` /
+ * `ipv6hint` / `ech` / `mandatory` / `dohpath`. Unknown SvcParamKeys
+ * surface under `params.unknown[key]` as raw bytes — operators
+ * implementing forward-compat can still read them. Malformed rdata
+ * throws `DnsError` with code `dns/svcb-malformed`.
+ *
+ * @opts
+ *   {
+ *     transport: "doh" | "dot" | "system",
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var rrs = await b.network.dns.querySvcb("_443._wss.example.com");
+ */
+async function querySvcb(name, opts) {
+  return _querySvcbLike(name, DNS_QTYPE_SVCB, opts);
+}
+
+/**
+ * @primitive b.network.dns.queryHttps
+ * @signature b.network.dns.queryHttps(name, opts?)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.dns.querySvcb
+ *
+ * Query HTTPS records (RFC 9460 §9). Identical to `querySvcb` except
+ * the QTYPE is HTTPS (65) — the user-agent-facing variant of SVCB
+ * for `https://` origins. Browsers query this for ECH discovery and
+ * h3 advertisement; servers can call it to validate their own
+ * published HTTPS RRset. Returns the same shape as `querySvcb`.
+ *
+ * @opts
+ *   {
+ *     transport: "doh" | "dot" | "system",
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var rrs = await b.network.dns.queryHttps("example.com");
+ */
+async function queryHttps(name, opts) {
+  return _querySvcbLike(name, DNS_QTYPE_HTTPS, opts);
+}
+
+// ---- DDR / DNR (RFC 9462 + RFC 9463) ---------------------------------
+
+// Default DDR query target — RFC 9462 §3.
+var DDR_QUERY_NAME = "_dns.resolver.arpa";
+
+// Operator-supplied designated resolver list. When set, the framework
+// prefers these over its own configured transport (subject to
+// `useDesignatedResolvers` having been called explicitly — never
+// silently overriding operator config).
+var _designatedResolvers = null;
+
+/**
+ * @primitive b.network.dns.discoverEncrypted
+ * @signature b.network.dns.discoverEncrypted(opts?)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.dns.useDesignatedResolvers, b.network.dns.querySvcb
+ *
+ * RFC 9462 Discovery of Designated Resolvers. Queries
+ * `_dns.resolver.arpa` for SVCB records that advertise encrypted DNS
+ * alternatives (DoH / DoT) hosted by the network's currently-configured
+ * Do53 resolver. Returns a list of resolver descriptors with
+ * `{ transport, alpn, target, port, dohpath, ipv4hint, ipv6hint, priority }`.
+ *
+ * The discovery query goes through the system resolver by default
+ * (RFC 9462 §4 — DDR validation requires the response to come from
+ * the Do53 resolver whose IP we compare). Callers that already have
+ * a trusted DoH / DoT transport configured can pass
+ * `{ insecureSystemResolverOnly: false }` to allow DDR via the
+ * encrypted transport too.
+ *
+ * Throws `DnsError` with code `dns/ddr-not-discovered` when the
+ * resolver does not publish DDR records.
+ *
+ * @opts
+ *   {
+ *     name:                       string,
+ *     insecureSystemResolverOnly: boolean,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var resolvers = await b.network.dns.discoverEncrypted();
+ */
+async function discoverEncrypted(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["name", "insecureSystemResolverOnly"], "dns.discoverEncrypted");
+  var name = opts.name || DDR_QUERY_NAME;
+  if (typeof name !== "string" || name.length === 0) {
+    throw new DnsError("dns/bad-host",
+      "dns.discoverEncrypted: name must be a non-empty string");
+  }
+  var insecureOnly = opts.insecureSystemResolverOnly !== false;
+  var transport = insecureOnly ? "system" : undefined;
+  _validateLdh(name, "dns.discoverEncrypted");
+  var startMs = _now();
+  var records;
+  try {
+    records = await _querySvcbLike(name, DNS_QTYPE_SVCB, { transport: transport });
+  } catch (e) {
+    _emitObs("network.dns.ddr.failure", {
+      latencyMs: _now() - startMs,
+      code:      e.code || "unknown",
+    });
+    if (e.code === "dns/no-result") {
+      throw new DnsError("dns/ddr-not-discovered",
+        "dns.discoverEncrypted: resolver did not publish DDR records at " + name);
+    }
+    throw e;
+  }
+  if (records.length === 0) {
+    _emitObs("network.dns.ddr.empty", { latencyMs: _now() - startMs });
+    throw new DnsError("dns/ddr-not-discovered",
+      "dns.discoverEncrypted: resolver returned empty DDR record set at " + name);
+  }
+  var resolvers = [];
+  for (var i = 0; i < records.length; i++) {
+    var rec = records[i];
+    if (rec.priority === 0) continue;        // AliasMode — caller chases
+    var alpn = (rec.params && rec.params.alpn) || [];
+    var isDot = alpn.indexOf("dot") !== -1;
+    var isDoh = alpn.indexOf("h2") !== -1 || alpn.indexOf("h3") !== -1 ||
+                (rec.params && typeof rec.params.dohpath === "string");
+    var transportKind = isDot ? "dot" : (isDoh ? "doh" : null);
+    if (!transportKind) continue;
+    resolvers.push({
+      transport: transportKind,
+      alpn:      alpn,
+      target:    rec.target,
+      port:      (rec.params && rec.params.port) ||
+                 (transportKind === "dot" ? 853 : 443),                          // allow:raw-byte-literal — IANA-assigned DoT/HTTPS ports
+      dohpath:   (rec.params && rec.params.dohpath) || null,
+      ipv4hint:  (rec.params && rec.params.ipv4hint) || [],
+      ipv6hint:  (rec.params && rec.params.ipv6hint) || [],
+      priority:  rec.priority,
+    });
+  }
+  resolvers.sort(function (a, b) { return a.priority - b.priority; });
+  if (resolvers.length === 0) {
+    throw new DnsError("dns/ddr-not-discovered",
+      "dns.discoverEncrypted: DDR records present but none advertised a recognized transport (alpn=dot/h2/h3)");
+  }
+  _emitObs("network.dns.ddr.success", {
+    latencyMs: _now() - startMs,
+    count:     resolvers.length,
+  });
+  return resolvers;
+}
+
+/**
+ * @primitive b.network.dns.useDesignatedResolvers
+ * @signature b.network.dns.useDesignatedResolvers(list)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.network.dns.discoverEncrypted, b.network.dns.querySvcb
+ *
+ * RFC 9463 Discovery of Network-designated Resolvers. The framework
+ * doesn't run a DHCP / IPv6 RA client itself; an operator-side agent
+ * (or the output of `discoverEncrypted()`) supplies the resolver list
+ * and the framework swaps its transport over to the lowest-priority
+ * entry. Items are tried in order: the first one that successfully
+ * configures (DoH `useDnsOverHttps`, DoT `useDnsOverTls`) wins.
+ *
+ * Each entry shape:
+ *
+ *   {
+ *     transport: "doh" | "dot",
+ *     url:       string,
+ *     host:      string,
+ *     port:      number,
+ *     servername: string,
+ *     alpn:      Array<string>,
+ *     ca:        string|Buffer|Array,
+ *   }
+ *
+ * Throws `DnsError` with code `dns/dnr-no-resolvers` if `list` is
+ * empty, and `dns/dnr-malformed` if an entry is missing its required
+ * transport-specific fields.
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var found = await b.network.dns.discoverEncrypted();
+ *   b.network.dns.useDesignatedResolvers(found.map(function (r) {
+ *     return r.transport === "doh"
+ *       ? { transport: "doh", url: "https://" + r.target + (r.dohpath || "/dns-query") }
+ *       : { transport: "dot", host: r.target, port: r.port, servername: r.target };
+ *   }));
+ */
+function useDesignatedResolvers(list) {
+  if (!Array.isArray(list) || list.length === 0) {
+    throw new DnsError("dns/dnr-no-resolvers",
+      "dns.useDesignatedResolvers: expected non-empty array of resolver descriptors");
+  }
+  var validated = [];
+  for (var i = 0; i < list.length; i++) {
+    var entry = list[i];
+    if (!entry || typeof entry !== "object") {
+      throw new DnsError("dns/dnr-malformed",
+        "dns.useDesignatedResolvers[" + i + "]: entry must be an object");
+    }
+    if (entry.transport !== "doh" && entry.transport !== "dot") {
+      throw new DnsError("dns/dnr-malformed",
+        "dns.useDesignatedResolvers[" + i + "]: transport must be 'doh' or 'dot'");
+    }
+    if (entry.transport === "doh") {
+      if (typeof entry.url !== "string" || entry.url.indexOf("https://") !== 0) {
+        throw new DnsError("dns/dnr-malformed",
+          "dns.useDesignatedResolvers[" + i + "]: doh entry requires url starting with https://");
+      }
+    } else {
+      if (typeof entry.host !== "string" || entry.host.length === 0) {
+        throw new DnsError("dns/dnr-malformed",
+          "dns.useDesignatedResolvers[" + i + "]: dot entry requires host");
+      }
+    }
+    validated.push(entry);
+  }
+  var lastErr = null;
+  for (var j = 0; j < validated.length; j++) {
+    var v = validated[j];
+    try {
+      if (v.transport === "doh") {
+        useDnsOverHttps({ url: v.url, ca: v.ca || null, method: v.method });
+      } else {
+        useDnsOverTls({
+          host:       v.host,
+          port:       v.port || 853,                                             // allow:raw-byte-literal — IANA-assigned DoT port
+          servername: v.servername || v.host,
+          ca:         v.ca || null,
+        });
+      }
+      _designatedResolvers = validated.slice();
+      _emitObs("network.dns.dnr.set", {
+        count:     validated.length,
+        active:    j,
+        transport: v.transport,
+      });
+      return { active: j, count: validated.length };
+    } catch (e) {
+      lastErr = e;
+      _emitObs("network.dns.dnr.entry_failed", {
+        index:     j,
+        transport: v.transport,
+        code:      e.code || "unknown",
+      });
+    }
+  }
+  throw new DnsError("dns/dnr-no-resolvers",
+    "dns.useDesignatedResolvers: no entry could be configured. Last error: " +
+    ((lastErr && lastErr.message) || "unknown"));
+}
+
+function _designatedResolversForTest() { return _designatedResolvers; }
+
 function _orderAddrs(addrs) {
   if (STATE.resultOrder === "ipv6first") {
     addrs.sort(function (a, b) { return (b.family || 0) - (a.family || 0); });
@@ -750,7 +1537,8 @@ async function lookup(host, opts) {
   }
 }
 
-async function _resolveProtocol(host, family) {
+async function _resolveProtocol(host, family, opts) {
+  opts = opts || {};
   if (typeof host !== "string" || host.length === 0) {
     throw new DnsError("dns/bad-host", "dns.resolve" + family + ": host required");
   }
@@ -760,13 +1548,27 @@ async function _resolveProtocol(host, family) {
     }
     return [host];
   }
-  _emitObs("network.dns.resolve.requested", { family: family });
+  if (opts.transport !== undefined && opts.transport !== "doh" &&
+      opts.transport !== "dot" && opts.transport !== "system") {
+    throw new DnsError("dns/bad-transport",
+      "dns.resolve" + family + ": transport must be 'doh' | 'dot' | 'system' | undefined");
+  }
+  _emitObs("network.dns.resolve.requested", { family: family, transport: opts.transport || "auto" });
   var startMs = _now();
   try {
     var addrs;
-    if (STATE.doh) {
+    var forced = opts.transport;
+    if (forced === "doh" || (!forced && STATE.doh)) {
+      if (!STATE.doh) {
+        throw new DnsError("dns/transport-unavailable",
+          "dns.resolve" + family + ": transport 'doh' requested but useDnsOverHttps() not configured");
+      }
       addrs = await _withTimeout(_dohLookup(host, family), STATE.lookupTimeoutMs, host);
-    } else if (STATE.dot) {
+    } else if (forced === "dot" || (!forced && STATE.dot)) {
+      if (!STATE.dot) {
+        throw new DnsError("dns/transport-unavailable",
+          "dns.resolve" + family + ": transport 'dot' requested but useDnsOverTls() not configured");
+      }
       addrs = await _withTimeout(_dotLookup(host, family), STATE.lookupTimeoutMs, host);
     } else {
       var resolver = family === 6 ? dnsPromises.resolve6 : dnsPromises.resolve4;
@@ -787,9 +1589,59 @@ async function _resolveProtocol(host, family) {
   }
 }
 
-async function resolve4(host) { return _resolveProtocol(host, 4); }
-async function resolve6(host) { return _resolveProtocol(host, 6); }
-async function resolveAaaa(host) { return _resolveProtocol(host, 6); }
+async function resolve4(host, opts) { return _resolveProtocol(host, 4, opts); }
+async function resolve6(host, opts) { return _resolveProtocol(host, 6, opts); }
+async function resolveAaaa(host, opts) { return _resolveProtocol(host, 6, opts); }
+
+// Generic resolve API surfacing the transport opt + record type.
+// `type` defaults to "A"; "AAAA" routes through resolve6; SVCB / HTTPS
+// types route through the new querySvcb / queryHttps primitives.
+async function resolve(host, type, opts) {
+  type = (type || "A").toUpperCase();
+  if (type === "A")     return _resolveProtocol(host, 4, opts);
+  if (type === "AAAA")  return _resolveProtocol(host, 6, opts);
+  if (type === "SVCB")  return querySvcb(host, opts);
+  if (type === "HTTPS") return queryHttps(host, opts);
+  throw new DnsError("dns/unsupported-type",
+    "dns.resolve: type must be 'A' | 'AAAA' | 'SVCB' | 'HTTPS' (got " + JSON.stringify(type) + ")");
+}
+
+// PTR lookup — given a v4 or v6 IP literal, return the list of names
+// the in-addr.arpa / ip6.arpa zones map back to. Building block for
+// FCrDNS (forward-confirmed reverse DNS, RFC 8601 §3 lite) callers
+// and the outbound-mail iprev surface — the PTR query plus the
+// matching forward A/AAAA query share this DnsError class.
+//
+// dnsPromises.reverse() doesn't honor the DoH/DoT transports (those
+// transports query A/AAAA/TXT via wire format; PTR queries take a
+// separate code path). For now this routes through the system
+// resolver — operators who require ALL DNS over secure transport
+// wrap the surface with their own resolver.
+async function reverse(ip) {
+  if (typeof ip !== "string" || ip.length === 0) {
+    throw new DnsError("dns/bad-ip", "dns.reverse: ip must be a non-empty string");
+  }
+  if (!net.isIP(ip)) {
+    throw new DnsError("dns/bad-ip",
+      "dns.reverse: '" + ip + "' is not a valid IPv4 or IPv6 address");
+  }
+  _emitObs("network.dns.reverse.requested", { family: net.isIPv6(ip) ? 6 : 4 });
+  var startMs = _now();
+  try {
+    var ptrs = await _withTimeout(dnsPromises.reverse(ip), STATE.lookupTimeoutMs, ip);
+    _emitObs("network.dns.reverse.success", {
+      latencyMs: _now() - startMs, count: Array.isArray(ptrs) ? ptrs.length : 0,
+    });
+    return Array.isArray(ptrs) ? ptrs : [];
+  } catch (e) {
+    _emitObs("network.dns.reverse.failure", {
+      latencyMs: _now() - startMs, code: e.code || "unknown",
+    });
+    if (e instanceof DnsError) throw e;
+    throw new DnsError("dns/reverse-failed",
+      "dns.reverse of '" + ip + "' failed: " + (e.message || String(e)));
+  }
+}
 
 function nodeLookup(host, options, callback) {
   if (typeof options === "function") { callback = options; options = {}; }
@@ -813,28 +1665,39 @@ function _resetForTest() {
   STATE.servers = null; STATE.resultOrder = null; STATE.family = 0;
   STATE.lookupTimeoutMs = 0; STATE.cacheTtlMs = 0; STATE.cacheNegativeTtlMs = 0;
   STATE.doh = null; STATE.dot = null; STATE.systemResolver = false;
+  _designatedResolvers = null;
   _clearCache();
   _resetDotPool();
 }
 
 module.exports = {
-  setServers:        setServers,
-  getServers:        getServers,
-  setResultOrder:    setResultOrder,
-  setFamily:         setFamily,
-  setLookupTimeoutMs: setLookupTimeoutMs,
-  setCacheTtlMs:     setCacheTtlMs,
-  useDnsOverHttps:   useDnsOverHttps,
-  useDnsOverTls:     useDnsOverTls,
-  useSystemResolver: useSystemResolver,
-  lookup:            lookup,
-  resolve4:          resolve4,
-  resolve6:          resolve6,
-  resolveAaaa:       resolveAaaa,
-  resolveSecure:     resolveSecure,
-  nodeLookup:        nodeLookup,
-  clearCache:        _clearCache,
-  DnsError:          DnsError,
-  _stateForTest:     _stateForTest,
-  _resetForTest:     _resetForTest,
+  setServers:                  setServers,
+  getServers:                  getServers,
+  setResultOrder:              setResultOrder,
+  setFamily:                   setFamily,
+  setLookupTimeoutMs:          setLookupTimeoutMs,
+  setCacheTtlMs:               setCacheTtlMs,
+  useDnsOverHttps:             useDnsOverHttps,
+  useDnsOverTls:               useDnsOverTls,
+  useSystemResolver:           useSystemResolver,
+  useDesignatedResolvers:      useDesignatedResolvers,
+  discoverEncrypted:           discoverEncrypted,
+  lookup:                      lookup,
+  resolve:                     resolve,
+  resolve4:                    resolve4,
+  resolve6:                    resolve6,
+  resolveAaaa:                 resolveAaaa,
+  resolveSecure:               resolveSecure,
+  reverse:                     reverse,
+  querySvcb:                   querySvcb,
+  queryHttps:                  queryHttps,
+  nodeLookup:                  nodeLookup,
+  clearCache:                  _clearCache,
+  DnsError:                    DnsError,
+  _parseSvcbRdata:             _parseSvcbRdata,
+  _decodeDnsAnswerRaw:         _decodeDnsAnswerRaw,
+  _readDnsName:                _readDnsName,
+  _stateForTest:               _stateForTest,
+  _resetForTest:               _resetForTest,
+  _designatedResolversForTest: _designatedResolversForTest,
 };