@blamejs/core 0.6.20 → 0.6.22

package/lib/http-client.js

@@ -98,8 +98,8 @@ var { FrameworkError } = require("./framework-error");
 // node's TLS layer — see TLS_SESSION_RESUMPTION_NOTES below).
 var _transports = new Map();
 
-// TLS session resumption notes — what we get for free vs. what's
-// out of reach today:
+// TLS session resumption notes — what's automatic vs. what's not
+// exposed by Node's public API:
 //
 //   keepAlive Agent (h1) / long-lived ClientHttp2Session (h2) means
 //   the WARM-CONNECTION case is zero-handshake — better than 0-RTT.
@@ -115,7 +115,8 @@ var _transports = new Map();
 //
 //   QUIC/h3 changes this calculus: 0-RTT is a first-class feature
 //   built into the protocol, with replay protection at the QUIC
-//   layer. We'll plumb it through when h3 lands.
+//   layer. The framework's `b.httpClient` is HTTP/1.1 + HTTP/2 only;
+//   operators wanting h3 wire their own client.
 
 // Pool tuning for the HTTP-client transport cache. Keep-alive is
 // shorter than the standalone pqc-agent default (1s vs 30s) because

package/lib/mail.js

@@ -403,10 +403,11 @@ function _buildRfc822(message) {
     body = inner.body;
   } else {
     // multipart/mixed: first part is the body (single or alternative),
-    // subsequent parts are the attachments. Inline disposition + Content-ID
-    // is interpreted correctly by every major client even inside mixed;
-    // operators with strict-RFC-2387 multipart/related needs subscribe
-    // to a future patch when demand surfaces.
+    // subsequent parts are the attachments. Inline disposition +
+    // Content-ID is interpreted correctly by every major client even
+    // inside mixed. Operators needing strict-RFC-2387 multipart/related
+    // wrap the body via the mail.transports interface and pass a
+    // content-type override.
     var mixedBoundary = _newBoundary("mixed");
     headers.push('Content-Type: multipart/mixed; boundary="' + mixedBoundary + '"');
     var parts = [];

package/lib/network-dns.js

@@ -136,7 +136,7 @@ function setCacheTtlMs(ms, negativeMs) {
 
 function useDnsOverHttps(opts) {
   opts = opts || {};
-  validateOpts(opts, ["provider", "url"], "dns.useDnsOverHttps");
+  validateOpts(opts, ["provider", "url", "method"], "dns.useDnsOverHttps");
   var url = opts.url;
   if (!url && opts.provider) {
     var p = String(opts.provider).toLowerCase();
@@ -149,9 +149,15 @@ function useDnsOverHttps(opts) {
     throw new DnsError("dns/bad-doh-url",
       "dns.useDnsOverHttps: url must be an https:// string, got " + JSON.stringify(url));
   }
-  STATE.doh = { url: url };
+  var method = opts.method;
+  if (method !== undefined && method !== "GET" && method !== "POST") {
+    throw new DnsError("dns/bad-doh-method",
+      "dns.useDnsOverHttps: method must be 'GET' | 'POST' | undefined (auto), got " +
+      JSON.stringify(method));
+  }
+  STATE.doh = { url: url, method: method };
   _clearCache();
-  _emitObs("network.dns.doh.set", { url: url });
+  _emitObs("network.dns.doh.set", { url: url, method: method || "auto" });
 }
 
 function useDnsOverTls(opts) {
@@ -244,22 +250,41 @@ function _decodeDnsAnswer(buf, qtype) {
   return addrs;
 }
 
+// DoH GET URL length cap. RFC 8484 §4.1 says clients MAY use POST when
+// the GET URL would exceed implementation limits. We pick 2048 bytes
+// (a conservative ceiling well below RFC 7230's recommended 8 KB) so
+// long DNS names (e.g. ESNI / SVCB record queries with operator-side
+// hostname concatenation) fall back cleanly. Operator can force POST
+// always with `useDnsOverHttps({ url, method: "POST" })`.
+var DOH_GET_URL_MAX_BYTES = 2048;
+
 async function _dohLookup(host, family) {
   var qtype = family === 6 ? 28 : 1;
   var enc = _encodeDnsQuery(host, qtype);
   var b64 = enc.buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-  var url = STATE.doh.url + (STATE.doh.url.indexOf("?") === -1 ? "?" : "&") + "dns=" + b64;
-  var u = new URL(url);
+  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 = new URL(STATE.doh.url);
   return new Promise(function (resolve, reject) {
-    var req = https.request({
-      hostname: u.hostname,
-      port:     u.port || 443,
-      path:     u.pathname + u.search,
-      method:   "GET",
-      headers:  { "accept": "application/dns-message" },
+    var reqOpts = {
+      hostname:   u.hostname,
+      port:       u.port || 443,
+      path:       u.pathname + u.search,
+      method:     usePost ? "POST" : "GET",
+      headers:    {
+        "accept": "application/dns-message",
+      },
       minVersion: "TLSv1.3",
-      ecdhCurve: C.TLS_GROUP_CURVE_STR,
-    }, function (res) {
+      ecdhCurve:  C.TLS_GROUP_CURVE_STR,
+    };
+    if (usePost) {
+      reqOpts.headers["content-type"]   = "application/dns-message";
+      reqOpts.headers["content-length"] = enc.buf.length;
+    } else {
+      reqOpts.path = (new URL(getUrl)).pathname + (new URL(getUrl)).search;
+    }
+    var req = https.request(reqOpts, function (res) {
       var chunks = [];
       res.on("data", function (c) { chunks.push(c); });
       res.on("end", function () {
@@ -274,45 +299,114 @@ async function _dohLookup(host, family) {
       });
     });
     req.on("error", function (e) { reject(new DnsError("dns/doh-failed", "DoH request failed: " + e.message)); });
+    if (usePost) req.write(enc.buf);
     req.end();
   });
 }
 
+// DoT connection pool. Per-(host:port) cached TLS socket so successive
+// lookups amortize the handshake. Sockets idle past the timeout are
+// closed and removed; first lookup after expiry rebuilds. Each socket
+// services one in-flight query at a time (DNS-over-TCP allows pipelining
+// but the framework chooses serialization for simpler back-pressure).
+var DOT_IDLE_TIMEOUT_MS = C.TIME.minutes(2);
+var _dotPool = new Map();           // "host:port" → { sock, lastUsedAt, idle, queue }
+
+function _dotPoolKey() {
+  return STATE.dot.host + ":" + STATE.dot.port;
+}
+
+function _dotConnect() {
+  var sock = tls.connect({
+    host:       STATE.dot.host,
+    port:       STATE.dot.port,
+    servername: STATE.dot.servername,
+    minVersion: "TLSv1.3",
+    ecdhCurve:  C.TLS_GROUP_CURVE_STR,
+  });
+  sock.unref && sock.unref();
+  return sock;
+}
+
+function _dotEvict(key) {
+  var entry = _dotPool.get(key);
+  if (!entry) return;
+  try { entry.sock.destroy(); } catch (_e) {}
+  _dotPool.delete(key);
+}
+
 async function _dotLookup(host, family) {
   var qtype = family === 6 ? 28 : 1;
   var enc = _encodeDnsQuery(host, qtype);
-  return new Promise(function (resolve, reject) {
-    var sock = tls.connect({
-      host:       STATE.dot.host,
-      port:       STATE.dot.port,
-      servername: STATE.dot.servername,
-      minVersion: "TLSv1.3",
-      ecdhCurve:  C.TLS_GROUP_CURVE_STR,
-    });
-    var lenBuf = Buffer.alloc(2);
-    lenBuf.writeUInt16BE(enc.buf.length, 0);
-    var got = [];
-    var expectLen = -1;
-    sock.on("secureConnect", function () {
-      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) {
-        try {
-          var ans = _decodeDnsAnswer(all.slice(2, 2 + expectLen), qtype);
-          sock.destroy();
-          resolve(ans);
-        } catch (e) { sock.destroy(); reject(e); }
-      }
+  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(e); });
+      }),
+    };
+    _dotPool.set(key, entry);
+    sock.on("error", function () { _dotEvict(key); });
+    sock.on("close", function () { if (_dotPool.get(key) === entry) _dotPool.delete(key); });
+  }
+  // Serialize: each socket handles one query at a time. If another
+  // query is in flight, queue behind it.
+  var waitTicket = entry._tail || Promise.resolve();
+  entry._tail = waitTicket.then(function () {
+    return new Promise(function (resolve, reject) {
+      entry.idle = false;
+      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();
+          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) {
+            try {
+              settle(null, _decodeDnsAnswer(all.slice(2, 2 + expectLen), qtype));
+            } catch (e) { settle(e); }
+          }
+        }
+        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);
+      });
     });
-    sock.on("error", function (e) { reject(new DnsError("dns/dot-failed", "DoT failed: " + e.message)); });
   });
+  return entry._tail;
+}
+
+function _resetDotPool() {
+  var keys = Array.from(_dotPool.keys());
+  for (var i = 0; i < keys.length; i++) _dotEvict(keys[i]);
 }
 
 function _orderAddrs(addrs) {
@@ -446,6 +540,7 @@ function _resetForTest() {
   STATE.lookupTimeoutMs = 0; STATE.cacheTtlMs = 0; STATE.cacheNegativeTtlMs = 0;
   STATE.doh = null; STATE.dot = null;
   _clearCache();
+  _resetDotPool();
 }
 
 module.exports = {

package/lib/pagination.js

@@ -75,10 +75,17 @@
  * module's offset() returns a `total` (from COUNT(*)) and computes
  * `totalPages` so legacy clients can render numbered nav.
  *
+ * Multi-column ordering:
+ *   - orderBy accepts a string (single column), an array of strings
+ *     (multiple columns, all using opts.direction), or an array of
+ *     { column, direction } objects (mixed directions per column).
+ *     The keyset WHERE expands to the standard OR cascade
+ *       (col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ...)
+ *     so successive pages can't repeat or skip rows when ties on the
+ *     leading columns are broken by trailing ones. _id is appended as
+ *     a tiebreaker if not already in the orderBy chain.
+ *
  * Out of scope (with structural reasons documented):
- *   - Multi-column composite orderBy (orderBy: ["a", "b"]). Use raw
- *     SQL + encodeCursor / decodeCursor. The Query builder doesn't
- *     model multi-column ORDER BY today.
  *   - Cursor TTL / expiry. Operators who want time-limited cursors
  *     embed a timestamp in their own state and check at decode-time
  *     before passing to .cursor(). The framework's HMAC tag carries
@@ -202,6 +209,83 @@ function _resolveLimit(opts) {
 
 // ---- Cursor pagination ----
 
+// Normalize opts.orderBy into an array of { column, direction } entries.
+// Accepts:
+//   undefined / null            → [{ column: "_id", direction: opts.direction || "asc" }]
+//   "createdAt"                 → [{ column: "createdAt", direction: opts.direction || "asc" }]
+//   ["createdAt", "_id"]        → all entries default to opts.direction || "asc"
+//   [{column:"a",direction:"desc"}, {column:"b"}]
+//                               → mixed; missing direction defaults to opts.direction || "asc"
+// Always appends an _id tiebreaker if not present, so cursor uniqueness
+// is guaranteed regardless of the operator's spec.
+function _normalizeOrderBy(opts) {
+  var defaultDir = (opts && opts.direction === "desc") ? "desc" : "asc";
+  var raw = opts && opts.orderBy;
+  var entries;
+  if (raw == null) {
+    entries = [{ column: "_id", direction: defaultDir }];
+  } else if (typeof raw === "string") {
+    entries = [{ column: raw, direction: defaultDir }];
+  } else if (Array.isArray(raw)) {
+    entries = raw.map(function (e) {
+      if (typeof e === "string") return { column: e, direction: defaultDir };
+      if (!e || typeof e !== "object" || typeof e.column !== "string") {
+        throw new PaginationError("pagination/bad-orderby",
+          "orderBy[] entries must be strings or { column, direction } objects, got " +
+          JSON.stringify(e));
+      }
+      var d = (e.direction || defaultDir).toLowerCase();
+      if (d !== "asc" && d !== "desc") {
+        throw new PaginationError("pagination/bad-orderby",
+          "orderBy[].direction must be 'asc' | 'desc', got " + JSON.stringify(e.direction));
+      }
+      return { column: e.column, direction: d };
+    });
+  } else {
+    throw new PaginationError("pagination/bad-orderby",
+      "orderBy must be a string, array, or omitted; got " + typeof raw);
+  }
+  for (var i = 0; i < entries.length; i++) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(entries[i].column)) {
+      throw new PaginationError("pagination/bad-orderby",
+        "orderBy column must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
+        JSON.stringify(entries[i].column));
+    }
+  }
+  // Append _id tiebreaker if not already in the chain. Direction
+  // matches the chain's last entry by convention so the tiebreaker
+  // doesn't reverse the natural reading order.
+  var hasId = entries.some(function (e) { return e.column === "_id"; });
+  if (!hasId) {
+    entries.push({ column: "_id", direction: entries[entries.length - 1].direction });
+  }
+  return entries;
+}
+
+// Build the keyset WHERE clause for next-page navigation given the
+// cursor's column values. Each (col, dir) entry expands the OR cascade:
+//   col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ... OR (col0 = ? AND ... AND coln [opn] ?)
+// The compareOp per column flips by direction × forward (XNOR).
+function _buildKeysetWhere(orderEntries, cursorVals, forward) {
+  var clauses = [];
+  var params = [];
+  for (var i = 0; i < orderEntries.length; i++) {
+    var entry = orderEntries[i];
+    // Effective direction: asc + forward → ">", desc + forward → "<", and reversed for backward.
+    var effectiveAsc = (entry.direction === "asc") === forward;
+    var op = effectiveAsc ? ">" : "<";
+    var equalChain = [];
+    for (var j = 0; j < i; j++) {
+      equalChain.push('"' + orderEntries[j].column + '" = ?');
+      params.push(cursorVals[j]);
+    }
+    equalChain.push('"' + entry.column + '" ' + op + ' ?');
+    params.push(cursorVals[i]);
+    clauses.push("(" + equalChain.join(" AND ") + ")");
+  }
+  return { sql: clauses.join(" OR "), params: params };
+}
+
 async function cursor(query, opts) {
   if (!query || typeof query.where !== "function" || typeof query.orderBy !== "function" ||
       typeof query.limit !== "function" || typeof query.all !== "function") {
@@ -213,110 +297,86 @@ async function cursor(query, opts) {
     throw new PaginationError("pagination/no-secret",
       "cursor: opts.secret is required (Buffer or non-empty string for HMAC tagging)");
   }
-  var limit     = _resolveLimit(opts);
-  var orderBy   = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Throw at call site on bad orderBy — the value is interpolated into
-  // a raw SQL fragment for the keyset where-clause. Restrict to
-  // identifier-safe characters so a careless caller piping
-  // `req.query.orderBy` through doesn't create an SQL-injection vector.
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(orderBy)) {
-    throw new PaginationError("pagination/bad-orderby",
-      "cursor: orderBy must match /^[A-Za-z_][A-Za-z0-9_]*$/ (identifier-safe), got " +
-      JSON.stringify(orderBy));
-  }
-  var direction = (opts.direction === "desc") ? "desc" : "asc";
+  var limit = _resolveLimit(opts);
+  var orderEntries = _normalizeOrderBy(opts);
+  // Cursor compatibility key: array of `column:direction` pairs canonicalizes
+  // the orderBy spec so a stored cursor must match exactly to be replayed.
+  var orderKey = orderEntries.map(function (e) { return e.column + ":" + e.direction; });
 
-  // Decode incoming cursor (if any) and override direction from cursor.
-  // The cursor authoritatively encodes which way we're paging — operators
-  // shouldn't need to round-trip direction in the URL.
   var cursorState = null;
   var forward = (opts.forward !== false);
   if (opts.cursor) {
     cursorState = decodeCursor(opts.cursor, opts.secret);
-    if (cursorState.orderBy !== orderBy || cursorState.dir !== direction) {
+    var cursorKey = Array.isArray(cursorState.orderKey) ? cursorState.orderKey :
+      // Back-compat with v0.6.20 single-column cursors: synthesize the
+      // key from the legacy orderBy/dir fields.
+      [cursorState.orderBy + ":" + cursorState.dir];
+    if (JSON.stringify(cursorKey) !== JSON.stringify(orderKey)) {
       throw new PaginationError("pagination/cursor-mismatch",
-        "cursor was created with orderBy='" + cursorState.orderBy + "' direction='" +
-        cursorState.dir + "' but call uses orderBy='" + orderBy + "' direction='" +
-        direction + "' — operator must use the same opts the cursor was issued under");
+        "cursor orderKey [" + cursorKey.join(", ") + "] does not match call orderKey [" +
+        orderKey.join(", ") + "] — operator must use the same orderBy/direction spec");
     }
     if (typeof cursorState.forward === "boolean") forward = cursorState.forward;
   }
 
-  // Apply the cursor predicate. Direction interacts with forward/backward:
-  //   asc  + forward  → strictly greater than (orderByVal, _id)
-  //   asc  + backward → strictly less than (orderByVal, _id)
-  //   desc + forward  → strictly less than
-  //   desc + backward → strictly greater than
-  // We always SELECT in the direction that matches forward (so the
-  // result rows arrive in the right reading order), then if
-  // backward we reverse client-side at the end.
-  var effectiveAsc = (direction === "asc") === forward; // XNOR
-  var compareOp;
+  // Apply the keyset WHERE if a cursor is present.
   if (cursorState) {
-    compareOp = effectiveAsc ? ">" : "<";
-    // (orderByVal, _id) <op> (?, ?)
-    // Express via OR to be portable across SQLite + Postgres.
-    var oCol = orderBy;
-    query.whereRaw(
-      '"' + oCol + '" ' + compareOp + ' ? OR ("' + oCol + '" = ? AND "_id" ' + compareOp + ' ?)',
-      [cursorState.orderByVal, cursorState.orderByVal, cursorState.id]
-    );
+    var cursorVals;
+    if (Array.isArray(cursorState.vals)) {
+      cursorVals = cursorState.vals;
+    } else {
+      // v0.6.20 single-column shape — synthesize the vals array.
+      cursorVals = [cursorState.orderByVal, cursorState.id];
+      // Drop the synthetic _id append if the legacy cursor already had it
+      if (orderEntries.length === 1) cursorVals = [cursorState.orderByVal];
+    }
+    if (cursorVals.length !== orderEntries.length) {
+      throw new PaginationError("pagination/cursor-mismatch",
+        "cursor encoded " + cursorVals.length + " column value(s) but orderBy has " +
+        orderEntries.length + " — operator changed the orderBy spec mid-flight");
+    }
+    var where = _buildKeysetWhere(orderEntries, cursorVals, forward);
+    query.whereRaw(where.sql, where.params);
   }
-  query.orderBy(orderBy, effectiveAsc ? "asc" : "desc");
-  if (orderBy !== "_id") {
-    // Tiebreaker by _id in the same direction — the framework Query
-    // only models a single orderBy, so we add the tiebreaker as a
-    // raw ORDER BY suffix via _orderLimitOffset cooperation. Today
-    // Query lacks multi-orderBy; we emulate by sorting in-memory
-    // after the fetch using _id within each orderBy group. Keeps
-    // pagination correct without expanding the Query API.
-    // No raw orderBy needed because the WHERE condition above
-    // strictly disambiguates (orderByVal, _id) tuples — successive
-    // pages can't repeat or skip a row even with ties on orderBy.
+
+  // Apply ORDER BY for each entry. When forward=false we reverse direction
+  // per entry so the SQL returns rows in the right reading order; we then
+  // reverse client-side at the end.
+  for (var oi = 0; oi < orderEntries.length; oi++) {
+    var entry = orderEntries[oi];
+    var effectiveDir = ((entry.direction === "asc") === forward) ? "asc" : "desc";
+    query.orderBy(entry.column, effectiveDir);
   }
   query.limit(limit + 1);
 
   var rows = await Promise.resolve(query.all());
 
-  // Tiebreaker stability: when orderBy != _id, the SQL only sorts by
-  // orderBy. Within an orderByVal cluster, sort by _id in JS so the
-  // cursor predicate's _id-based tiebreaker stays consistent with the
-  // returned ordering.
-  if (orderBy !== "_id") {
-    rows.sort(function (a, b) {
-      var av = a[orderBy], bv = b[orderBy];
-      if (av < bv) return effectiveAsc ? -1 : 1;
-      if (av > bv) return effectiveAsc ?  1 : -1;
-      var ai = String(a._id), bi = String(b._id);
-      if (ai < bi) return effectiveAsc ? -1 : 1;
-      if (ai > bi) return effectiveAsc ?  1 : -1;
-      return 0;
-    });
-  }
-
   var hasMore = rows.length > limit;
   var page = hasMore ? rows.slice(0, limit) : rows.slice();
   if (!forward) page.reverse();
 
+  function _valsForRow(row) {
+    return orderEntries.map(function (e) {
+      return e.column === "_id" ? String(row._id) : row[e.column];
+    });
+  }
+
   var nextCursor = null;
   var prevCursor = null;
   if (hasMore && page.length > 0) {
     var last = page[page.length - 1];
     nextCursor = encodeCursor({
-      dir: direction, orderBy: orderBy,
-      orderByVal: last[orderBy], id: String(last._id),
-      forward: true,
+      orderKey: orderKey,
+      vals:     _valsForRow(last),
+      forward:  true,
     }, opts.secret);
   }
-  // Always emit a prev cursor when we have a starting position (the
-  // operator was on a non-first page). Operator UI hides it on the
-  // first page.
   if (cursorState && page.length > 0) {
     var first = page[0];
     prevCursor = encodeCursor({
-      dir: direction, orderBy: orderBy,
-      orderByVal: first[orderBy], id: String(first._id),
-      forward: false,
+      orderKey: orderKey,
+      vals:     _valsForRow(first),
+      forward:  false,
     }, opts.secret);
   }
 

package/lib/parsers/index.js

@@ -42,19 +42,33 @@
  *           opted in. Dev-tooling — production secrets should still
  *           come through the operator's secrets-management; this is
  *           the local-development convenience.
- *   ini  — Windows .ini files (rare today; lower priority)
+ *   ini  — INI / .gitconfig / systemd-unit / php.ini / tox.ini parser.
+ *           Sections (incl. [parent.child] / [parent "child"] nesting),
+ *           ; or # comments (inline + leading), single + double quoting
+ *           with \n / \t / \\ / \" / \' escapes, boolean coercion
+ *           (true/false/yes/no/on/off), decimal + hex integers + floats.
+ *           Prototype-pollution defense (__proto__/constructor/prototype
+ *           rejected); duplicate-key policy throws by default
+ *           (onDuplicate: "first"|"last" opts in to silent
+ *           shadowing); section + per-section key + value-bytes
+ *           caps configurable via opts.
  *
  * Public API:
  *   parsers.xml.parse(input, opts?)              → object
+ *   parsers.ini.parse(input, opts?)              → object
+ *   parsers.toml.parse(input, opts?)             → object
+ *   parsers.yaml.parse(input, opts?)             → object
+ *   parsers.env.load(filepath, opts?)            → { values, diff }
  *
  * (CSV moved to top-level `b.csv` in v0.5.17 — same surface unified.)
  *
  * Error types: each parser exports its own *SafeError class with .code
- * matching the format (xml/..., toml/...).
+ * matching the format (xml/..., toml/..., ini/..., yaml/..., env/...).
  */
 module.exports = {
   xml:  require("./safe-xml"),
   toml: require("./safe-toml"),
   yaml: require("./safe-yaml"),
   env:  require("./safe-env"),
+  ini:  require("./safe-ini"),
 };