@blamejs/core 0.10.6 → 0.10.8

package/lib/mail-server-mx.js

@@ -236,6 +236,13 @@ function create(opts) {
   var localDomains      = (opts.localDomains || []).map(function (d) { return String(d).toLowerCase(); });
   var relayAllowedFor   = opts.relayAllowedFor || [];
   var profile           = opts.profile || "strict";
+  // SMTPUTF8 (RFC 6531) — single switch threaded end-to-end. The MX
+  // listener doesn't advertise SMTPUTF8 to the peer regardless, so
+  // this defaults `false` (refuse non-ASCII bytes in every command
+  // line). Operators that want to accept SMTPUTF8 for downstream
+  // relay flip this `true` and the same switch reaches every
+  // `guardSmtpCommand.validate` call.
+  var allowSmtpUtf8     = opts.allowSmtpUtf8 === true;
 
   // Default-on per-IP rate limit. Operators pass `rateLimit: false` to
   // disable (only for tests / closed networks), pass a rate-limit
@@ -331,6 +338,15 @@ function create(opts) {
     var connectionId = "mxconn-" + bCrypto.generateToken(8);                                          // allow:raw-byte-literal — connection-id length
     connections.add(socket);
 
+    // Backpressure observer — `_writeReply` flips `_bpEmitted` after
+    // the first audit emission per socket to bound the audit volume.
+    socket._bpEmit = function () {
+      _emit("mail.server.mx.write_backpressure",
+        { connectionId: connectionId, remoteAddress: remoteAddress,
+          stage: state && state.stage, bufferedBytes: socket.writableLength || 0 },
+        "warning");
+    };
+
     var state = {
       id:            connectionId,
       remoteAddress: remoteAddress,
@@ -452,7 +468,11 @@ function create(opts) {
       // Per-line guard — refuse bare LF / NUL / C0 / DEL / oversize
       // BEFORE state-machine dispatch.
       try {
-        guardSmtpCommand.validate(line, { profile: profile, maxLineBytes: maxLineBytes });
+        guardSmtpCommand.validate(line, {
+          profile:        profile,
+          maxLineBytes:   maxLineBytes,
+          allowSmtpUtf8:  allowSmtpUtf8,
+        });
       } catch (err) {
         if (err.code === "guard-smtp-command/bare-lf" ||
             err.code === "guard-smtp-command/bare-cr" ||
@@ -633,17 +653,19 @@ function create(opts) {
       }
       var paramStr = match[2] || "";
       var sizeMatch = paramStr.match(RE_SIZE);
+      var declaredSize = null;
       if (sizeMatch) {
-        var declaredSize = parseInt(sizeMatch[1], 10);
+        declaredSize = parseInt(sizeMatch[1], 10);
         if (declaredSize > maxMessageBytes) {
           _writeReply(socket, REPLY_552_SIZE_EXCEEDED,
             "5.3.4 Message size exceeds fixed maximum (" + maxMessageBytes + " bytes)");
           return;
         }
       }
-      state.mailFrom = mailFrom;
-      state.stage    = "rcpt";
-      state.rcpts    = [];
+      state.mailFrom    = mailFrom;
+      state.declaredSize = declaredSize;
+      state.stage       = "rcpt";
+      state.rcpts       = [];
       _emit("mail.server.mx.mail_from",
         { connectionId: state.id, mailFrom: mailFrom });
       _writeReply(socket, REPLY_250_OK, "2.1.0 Sender OK");
@@ -692,6 +714,7 @@ function create(opts) {
         var rcptVerdict = _validateDomainHardened(rcptDomain, "rcpt_to");
         if (!rcptVerdict.ok) {
           rateLimit.noteRcptFailure(state.remoteAddress);
+          _trackRefusedRcpt(state, rcpt, "domain-refused");
           _writeReply(socket, REPLY_501_BAD_ARGS,
             "5.5.4 RCPT TO domain refused (" +
             (rcptVerdict.issues && rcptVerdict.issues[0] && rcptVerdict.issues[0].kind) + ")");
@@ -704,6 +727,7 @@ function create(opts) {
         if (localDomains.indexOf(rcptDomain) === -1 &&
             !_isRelayAllowed(state.remoteAddress, rcpt)) {
           rateLimit.noteRcptFailure(state.remoteAddress);
+          _trackRefusedRcpt(state, rcpt, "relay-denied");
           _emit("mail.server.mx.relay_refused",
             { connectionId: state.id, mailFrom: state.mailFrom, rcptTo: rcpt,
               remoteAddress: state.remoteAddress }, "denied");
@@ -739,9 +763,32 @@ function create(opts) {
       // body is the raw bytes BEFORE dot-stuffing reversal. RFC 5321
       // §4.5.2 — a single leading "." is doubled on the wire; undo.
       var dedotted = safeSmtp.dotUnstuff(body);
+      // RFC 1870 §6.3 — reconcile MAIL FROM SIZE= against the actual
+      // DATA byte count. The pre-DATA reservation at MAIL FROM time
+      // (above) is advisory; the sender's declared size is a HINT,
+      // not a guarantee. If the actual unstuffed body exceeds the
+      // declared SIZE= (with a small slack to absorb header lines the
+      // sender didn't count), refuse with 552 — defends against
+      // senders that probe maxMessageBytes by understating SIZE.
+      if (typeof state.declaredSize === "number" && isFinite(state.declaredSize)) {
+        if (dedotted.length > state.declaredSize) {
+          _emit("mail.server.mx.size_overrun", {
+            connectionId: state.id,
+            mailFrom:     state.mailFrom,
+            declaredSize: state.declaredSize,
+            actualSize:   dedotted.length,
+          }, "denied");
+          _writeReply(socket, REPLY_552_SIZE_EXCEEDED,
+            "5.3.4 Message exceeds declared SIZE=" + state.declaredSize +
+            " bytes (got " + dedotted.length + "; RFC 1870 §6.3)");
+          _resetTransaction(state);
+          return;
+        }
+      }
       // operator-supplied agent handoff — when wired, persist via
       // agent + write the 250 reply. When not wired, accept-and-drop
       // (audit-only mode useful for staging deployments).
+      var refusedSnapshot = Array.isArray(state.refusedRcpts) ? state.refusedRcpts.slice() : [];
       if (opts.agent && typeof opts.agent.handoff === "function") {
         opts.agent.handoff({
           mailFrom: state.mailFrom,
@@ -753,7 +800,8 @@ function create(opts) {
           connectionId: state.id,
         }).then(function (ack) {
           _emit("mail.server.mx.delivered",
-            { connectionId: state.id, messageId: ack && ack.messageId, sizeBytes: dedotted.length });
+            { connectionId: state.id, messageId: ack && ack.messageId,
+              sizeBytes: dedotted.length, refusedRcpts: refusedSnapshot });
           _writeReply(socket, REPLY_250_OK,
             "2.6.0 Message accepted" + (ack && ack.messageId ? " <" + ack.messageId + ">" : ""));
           _resetTransaction(state);
@@ -769,18 +817,32 @@ function create(opts) {
       }
       _emit("mail.server.mx.data_accepted",
         { connectionId: state.id, mailFrom: state.mailFrom, rcptCount: state.rcpts.length,
-          sizeBytes: dedotted.length });
+          sizeBytes: dedotted.length, refusedRcpts: refusedSnapshot });
       _writeReply(socket, REPLY_250_OK, "2.6.0 Message queued (audit-only)");
       _resetTransaction(state);
     }
 
     function _resetTransaction(state) {
-      state.mailFrom = null;
-      state.rcpts    = [];
-      state.stage    = "ehlo";
+      state.mailFrom     = null;
+      state.declaredSize = null;
+      state.rcpts        = [];
+      state.refusedRcpts = [];
+      state.stage        = "ehlo";
       state.messageBytes = 0;
     }
 
+    // Track up to MAX_REFUSED_RCPTS_PER_TXN refused recipients so the
+    // `data_accepted` / `delivered` audit can surface the bounded list
+    // for observability. Bounded to keep the audit metadata size
+    // predictable; the per-IP recipient-failure rate-limit elsewhere
+    // bounds long-run scanner damage.
+    var MAX_REFUSED_RCPTS_PER_TXN = 32;                                                                   // allow:raw-byte-literal — bounded audit-metadata list cap
+    function _trackRefusedRcpt(state, rcpt, reason) {
+      if (!Array.isArray(state.refusedRcpts)) state.refusedRcpts = [];
+      if (state.refusedRcpts.length >= MAX_REFUSED_RCPTS_PER_TXN) return;
+      state.refusedRcpts.push({ rcptTo: rcpt, reason: reason });
+    }
+
     function _requiresStartTls() {
       // Strict / balanced require STARTTLS before MAIL FROM.
       // Permissive accepts plaintext — operator-acknowledged downgrade
@@ -857,10 +919,26 @@ function create(opts) {
 
 // ---- Wire-protocol helpers --------------------------------------------------
 
+// Write back-pressure observability — when `socket.write()` returns
+// false the kernel send-buffer is full and the server is dropping
+// behind the network. Listeners attach a `_bpEmit` function to the
+// socket; we invoke it once per socket-lifetime on the first
+// backpressure event so the audit log surfaces stalled connections
+// without flooding on every reply.
+function _observeBackpressure(socket, ok) {
+  if (ok) return;
+  if (typeof socket._bpEmit !== "function") return;
+  if (socket._bpEmitted) return;
+  socket._bpEmitted = true;
+  try { socket._bpEmit(socket); } catch (_e) { /* drop-silent */ }
+}
+
 function _writeReply(socket, code, text) {
   // Single-line reply per RFC 5321 §4.2 — code SP text CRLF.
-  try { socket.write(code + " " + text + "\r\n"); }
-  catch (_e) { /* socket already closed */ }
+  try {
+    var ok = socket.write(code + " " + text + "\r\n");
+    _observeBackpressure(socket, ok);
+  } catch (_e) { /* socket already closed */ }
 }
 
 function _writeMultiline(socket, code, lines) {
@@ -868,8 +946,10 @@ function _writeMultiline(socket, code, lines) {
   // continuation, code SP text CRLF for the final line.
   for (var i = 0; i < lines.length; i += 1) {
     var sep = i === lines.length - 1 ? " " : "-";
-    try { socket.write(code + sep + lines[i] + "\r\n"); }
-    catch (_e) { /* socket already closed */ }
+    try {
+      var ok = socket.write(code + sep + lines[i] + "\r\n");
+      _observeBackpressure(socket, ok);
+    } catch (_e) { /* socket already closed */ }
   }
 }
 

package/lib/mail-server-submission.js

@@ -153,6 +153,69 @@ var RE_RCPT_TO   = /^RCPT\s+TO:\s*<([^>]+)>(?:\s+.*)?$/i;
 var RE_SIZE      = /SIZE=(\d+)/i;
 var RE_AUTH      = /^AUTH\s+([A-Za-z0-9_-]{1,32})(?:\s+(.*))?$/i;
 
+// Header/body boundary scanner. RFC 5322 §2.1 — header section ends
+// at the first empty line (CRLF CRLF). `Buffer#indexOf` runs a
+// SIMD-accelerated needle scan over the haystack without an
+// interpreter-level char-by-char walk, and the 4-byte literal
+// `_CRLF_CRLF` is a module-level singleton so the JIT folds it.
+var _CRLF_CRLF = Buffer.from([0x0d, 0x0a, 0x0d, 0x0a]);                                                 // allow:raw-byte-literal — RFC 5322 §2.1 header/body separator
+function _findHeaderEnd(buf) {
+  return buf.indexOf(_CRLF_CRLF);
+}
+
+// Walk a header block and return every unfolded `DKIM-Signature:`
+// value. RFC 5322 §2.2.3 / RFC 6376 §3.5 — DKIM signatures are
+// permitted to fold and a message MAY carry multiple signatures.
+function _extractDkimSignatures(headerBlock) {
+  var lines = headerBlock.replace(/\r\n/g, "\n").split("\n");                                           // allow:regex-no-length-cap — headerBlock length bounded by maxMessageBytes
+  var result = [];
+  var current = null;
+  for (var i = 0; i < lines.length; i += 1) {
+    var line = lines[i];
+    if (line.length === 0) break;   // end of header block
+    if (line.charAt(0) === " " || line.charAt(0) === "\t") {
+      if (current !== null) current += " " + line.replace(/^[ \t]+/, "");                                // allow:regex-no-length-cap — line length bounded by maxLineBytes // allow:duplicate-regex — RFC 5322 header continuation trim
+      continue;
+    }
+    if (current !== null) {
+      result.push(current);
+      current = null;
+    }
+    if (/^DKIM-Signature\s*:/i.test(line)) {                                                            // allow:regex-no-length-cap — line length bounded by maxLineBytes
+      current = line.slice(line.indexOf(":") + 1).replace(/^\s+/, "");                                  // allow:regex-no-length-cap — line length bounded by maxLineBytes // allow:duplicate-regex — leading-WS trim
+    }
+  }
+  if (current !== null) result.push(current);
+  return result;
+}
+
+// Pull the `d=` (signing domain) tag out of a DKIM-Signature value.
+// RFC 6376 §3.5 — tag-list `tag=value` separated by `;`. Returns
+// null if not present.
+function _extractDkimDTag(sigValue) {
+  var tags = sigValue.split(";");
+  for (var i = 0; i < tags.length; i += 1) {
+    var t = tags[i].replace(/^\s+|\s+$/g, "");                                                          // allow:regex-no-length-cap — tag length bounded by header line cap // allow:duplicate-regex — trim shape
+    if (t.length > 2 && t.charAt(0) === "d" && t.charAt(1) === "=") {
+      return t.slice(2).replace(/\s+/g, "");                                                            // allow:regex-no-length-cap — value length bounded by tag length // allow:duplicate-regex — internal-WS strip
+    }
+  }
+  return null;
+}
+
+// Domain part of the authenticated identity, falling back to the
+// envelope-sender domain when the actor doesn't carry one.
+function _actorDomain(actor, mailFrom) {
+  if (actor && typeof actor.domain === "string" && actor.domain.length > 0) return actor.domain;
+  if (actor && typeof actor.id === "string" && actor.id.indexOf("@") !== -1) {
+    return actor.id.slice(actor.id.lastIndexOf("@") + 1);
+  }
+  if (typeof mailFrom === "string" && mailFrom.indexOf("@") !== -1) {
+    return mailFrom.slice(mailFrom.lastIndexOf("@") + 1);
+  }
+  return null;
+}
+
 /**
  * @primitive b.mail.server.submission.create
  * @signature b.mail.server.submission.create(opts)
@@ -208,6 +271,30 @@ function create(opts) {
     "mail.server.submission.", MailServerSubmissionError, "mail-server-submission/bad-bound");
 
   var profile = opts.profile || "strict";
+  // SMTPUTF8 (RFC 6531) — single switch threaded end-to-end into
+  // `guardSmtpCommand.validate`. Defaults `false`; submission
+  // operators that accept EAI envelopes flip this `true`.
+  var allowSmtpUtf8 = opts.allowSmtpUtf8 === true;
+
+  // Outbound DKIM-required gate (Yahoo / Google 2024 bulk-sender
+  // alignment + RFC 6376 §1). Under `strict` profile the listener
+  // refuses outbound DATA that doesn't carry at least one
+  // `DKIM-Signature:` header; `dkimRequireMode` chooses whether the
+  // signer must match the authenticated identity's domain (`self`)
+  // or just be present (`any`). Operators that act as a smarthost
+  // relay for downstream MTAs that DKIM-sign themselves want `any`;
+  // primary senders want `self`. Default-off outside strict so
+  // unauthenticated `permissive` profiles don't break.
+  var requireDkim = opts.requireDkim === undefined
+    ? (profile === "strict")
+    : opts.requireDkim === true;
+  var dkimRequireMode = opts.dkimRequireMode || "any";
+  if (dkimRequireMode !== "self" && dkimRequireMode !== "any" && dkimRequireMode !== "off") {
+    throw new MailServerSubmissionError("mail-server-submission/bad-dkim-require-mode",
+      "mail.server.submission.create: dkimRequireMode must be 'self', 'any', or 'off' (got '" +
+      dkimRequireMode + "')");
+  }
+  if (dkimRequireMode === "off") requireDkim = false;
 
   if (profile !== "permissive" && !opts.auth) {
     throw new MailServerSubmissionError("mail-server-submission/no-auth",
@@ -424,7 +511,11 @@ function create(opts) {
 
       // guardSmtpCommand check (smuggling + shape).
       try {
-        guardSmtpCommand.validate(line, { profile: profile, maxLineBytes: maxLineBytes });
+        guardSmtpCommand.validate(line, {
+          profile:        profile,
+          maxLineBytes:   maxLineBytes,
+          allowSmtpUtf8:  allowSmtpUtf8,
+        });
       } catch (err) {
         if (err.code === "guard-smtp-command/bare-lf" ||
             err.code === "guard-smtp-command/bare-cr" ||
@@ -911,6 +1002,49 @@ function create(opts) {
 
     function _finalizeDataBody(state, socket, body) {
       var dedotted = safeSmtp.dotUnstuff(body);
+
+      // Outbound DKIM-required gate. Scan the header block for a
+      // `DKIM-Signature:` line; under `self` mode also require at
+      // least one signature whose `d=` tag matches the authenticated
+      // identity's domain part.
+      if (requireDkim) {
+        var headerEnd = _findHeaderEnd(dedotted);
+        var headerBlock = headerEnd === -1
+          ? dedotted.toString("utf8")
+          : dedotted.subarray(0, headerEnd).toString("utf8");
+        var dkimSigs = _extractDkimSignatures(headerBlock);
+        var dkimOk = false;
+        if (dkimSigs.length > 0) {
+          if (dkimRequireMode === "any") {
+            dkimOk = true;
+          } else if (dkimRequireMode === "self") {
+            var actorDomain = _actorDomain(state.actor, state.mailFrom);
+            for (var i = 0; i < dkimSigs.length; i += 1) {
+              var d = _extractDkimDTag(dkimSigs[i]);
+              if (d && actorDomain && d.toLowerCase() === actorDomain.toLowerCase()) {
+                dkimOk = true;
+                break;
+              }
+            }
+          }
+        }
+        if (!dkimOk) {
+          _emit("mail.server.submission.data_refused", {
+            connectionId:    state.id,
+            reason:          "dkim-required",
+            dkimRequireMode: dkimRequireMode,
+            mailFrom:        state.mailFrom,
+            sigCount:        dkimSigs.length,
+            actor:           state.actor && state.actor.id,
+          }, "denied");
+          _writeReply(socket, REPLY_550_MAILBOX_UNAVAIL,
+            "5.7.20 DKIM-Signature required on outbound submission " +
+            "(dkimRequireMode='" + dkimRequireMode + "'; RFC 6376; bulk-sender 2024)");
+          _resetTransaction(state);
+          return;
+        }
+      }
+
       if (opts.agent && typeof opts.agent.handoff === "function") {
         opts.agent.handoff({
           mailFrom: state.mailFrom,

package/lib/mail-store.js

@@ -368,7 +368,12 @@ function _appendMessage(args) {
   });
 
   // Allocate objectid + modseq atomically.
-  var objectid = "obj_" + bCrypto.generateToken(16).slice(0, 24);                                  // allow:raw-byte-literal — 16-byte token, 24-char hex prefix as JMAP objectid (RFC 8474)
+  // RFC 8474 §1.5.1: objectid SHOULD be sufficiently long to make
+  // collision improbable across the lifetime of the account. 16-byte
+  // token = 32-char hex = 128 bits, well above the birthday bound
+  // for any plausible message corpus. The prior `.slice(0, 24)` cut
+  // entropy to 96 bits; removed.
+  var objectid = "obj_" + bCrypto.generateToken(16);                                                // allow:raw-byte-literal — 16-byte token, 32-char hex JMAP objectid (RFC 8474 §1.5.1)
   var modseq = (folder.modseq_max || 0) + 1;
   if (!threadRootId) threadRootId = objectid;   // root of new thread
 

package/lib/network-dns-resolver.js

@@ -106,7 +106,6 @@
 
 var C                  = require("./constants");
 var https              = require("node:https");
-var nodeCrypto         = require("node:crypto");
 var bCrypto            = require("./crypto");
 var { defineClass }    = require("./framework-error");
 var networkDns         = require("./network-dns");
@@ -499,7 +498,7 @@ function _encodeWireQuery(name, qtype) {
   var nameLen = 1;
   for (var i = 0; i < parts.length; i += 1) nameLen += 1 + Buffer.byteLength(parts[i], "ascii");
   var buf = Buffer.alloc(12 + nameLen + 4);                                                              // allow:raw-byte-literal — RFC 1035 §4.1.1 header (12) + question tail (4) + name
-  var id = nodeCrypto.randomInt(0, 0x10000);
+  var id = bCrypto.randomInt(0, 0x10000);                                                              // allow:raw-byte-literal — RFC 1035 §4.1.1 16-bit query ID space
   buf.writeUInt16BE(id, 0);
   buf.writeUInt16BE(0x0100, 2);                                                                          // allow:raw-byte-literal — RFC 1035 §4.1.1 RD=1 flags
   buf.writeUInt16BE(1, 4);                                                                               // allow:raw-byte-literal — RFC 1035 §4.1.1 qdcount

package/lib/network-dns.js

@@ -2,7 +2,6 @@
 
 var dns = require("node:dns");
 var net = require("node:net");
-var nodeCrypto = require("node:crypto");
 var https = require("node:https");
 var nodeTls = require("node:tls");
 var dnsPromises = dns.promises;
@@ -274,9 +273,10 @@ function _encodeDnsQuery(host, qtype) {
   for (var i = 0; i < parts.length; i++) nameLen += 1 + Buffer.byteLength(parts[i], "ascii");
   var buf = Buffer.alloc(12 + nameLen + 4);
   // Cryptographic RNG for the 16-bit DNS query ID — frustrates poisoning
-  // attempts that guess the transaction ID. Math.random would be technically
-  // acceptable (id is non-secret) but we prefer the framework's RNG path.
-  var id = nodeCrypto.randomInt(0, 0x10000);
+  // attempts that guess the transaction ID. Routes through `b.crypto.randomInt`
+  // (which wraps nodeCrypto.randomInt) so every framework random-int draw
+  // is greppable through one substrate.
+  var id = bCrypto.randomInt(0, 0x10000);
   buf.writeUInt16BE(id, 0);
   buf.writeUInt16BE(0x0100, 2);
   buf.writeUInt16BE(1, 4);

package/lib/promise-pool.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * @module b.promisePool
+ * @nav    Async
+ * @title  Promise Pool
+ *
+ * @intro
+ *   Bounded-concurrency task runner for promise-returning work — the
+ *   common gap between `b.workerPool` (worker_threads for CPU-bound
+ *   work) and `b.queue` (durable cross-process messaging). Wraps the
+ *   typical "I have N parallel I/O fan-outs and want at most K in
+ *   flight at any moment" pattern with back-pressure on enqueue
+ *   (so the caller can't out-run the worker side) and a clean drain
+ *   path that composes with `b.appShutdown`.
+ *
+ *   Two enqueue paths:
+ *
+ *     - `pool.run(taskFn)` returns a Promise that resolves to the
+ *       task's return value (or rejects with the task's error). When
+ *       the pool is at capacity, `run` waits until a slot frees
+ *       BEFORE the task starts — back-pressure is part of the
+ *       contract, not an opt.
+ *
+ *     - `pool.fire(taskFn)` is the synchronous-enqueue variant for
+ *       fan-out from non-async contexts. Returns the same Promise
+ *       but the call itself can't await — useful inside event
+ *       handlers that fire-and-forget.
+ *
+ *   Drain semantics: `pool.drain()` resolves when every queued and
+ *   in-flight task settles. Callers wire this into shutdown via
+ *   `b.appShutdown.create({ priority: 50, run: () => pool.drain() })`
+ *   so the process doesn't tear down with work mid-flight.
+ *
+ *   The pool does NOT retry failed tasks; rejection of a task's
+ *   promise is the caller's signal. Operators that want retry compose
+ *   `b.retry.withRetry` inside the task body.
+ *
+ * @card
+ *   Bounded-concurrency promise pool — back-pressure on enqueue, drain-on-shutdown, no hidden retry. The thing every consumer reaches for p-limit for.
+ */
+
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+
+var PromisePoolError = defineClass("PromisePoolError", { alwaysPermanent: true });
+
+var MAX_CONCURRENCY = 65536;                                                                    // allow:raw-byte-literal — uint16 ceiling on parallel I/O fan-out
+
+/**
+ * @primitive b.promisePool.create
+ * @signature b.promisePool.create(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.workerPool.create, b.appShutdown.create, b.retry.withRetry
+ *
+ * Build a bounded-concurrency pool. Returns
+ * `{ run, fire, drain, size, inFlight, queued, closed }`. The pool is
+ * closed via `drain({ close: true })`; subsequent enqueues throw.
+ *
+ * @opts
+ *   concurrency: number,        // required; integer in [1, 65536]
+ *   queueLimit:  number,        // default Infinity; once exceeded, enqueue throws
+ *
+ * @example
+ *   var pool = b.promisePool.create({ concurrency: 8 });
+ *   var results = await Promise.all(items.map(function (item) {
+ *     return pool.run(function () { return fetchOne(item); });
+ *   }));
+ *   await pool.drain({ close: true });
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "b.promisePool.create",
+    PromisePoolError, "promise-pool/bad-opts");
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.concurrency,
+    "b.promisePool.create: concurrency", PromisePoolError, "promise-pool/bad-concurrency");
+  if (opts.concurrency === undefined || opts.concurrency > MAX_CONCURRENCY) {
+    throw new PromisePoolError("promise-pool/bad-concurrency",
+      "b.promisePool.create: concurrency must be an integer in [1, " +
+      MAX_CONCURRENCY + "] (got " + opts.concurrency + ")");
+  }
+  var queueLimit = opts.queueLimit === undefined ? Infinity : opts.queueLimit;
+  if (queueLimit !== Infinity) {
+    numericBounds.requirePositiveFiniteIntIfPresent(queueLimit + 1,
+      "b.promisePool.create: queueLimit (must be non-negative int)", PromisePoolError,
+      "promise-pool/bad-queue-limit");
+  }
+  var concurrency = opts.concurrency;
+  var inFlight = 0;
+  var queue = [];                // FIFO of pending { taskFn, resolve, reject }
+  var drainWaiters = [];
+  var closed = false;
+
+  function _pump() {
+    while (inFlight < concurrency && queue.length > 0) {
+      var slot = queue.shift();
+      inFlight += 1;
+      Promise.resolve().then(function () { return slot.taskFn(); })
+        .then(function (val) { slot.resolve(val); _settle(); })
+        .catch(function (err) { slot.reject(err); _settle(); });
+    }
+    if (inFlight === 0 && queue.length === 0 && drainWaiters.length > 0) {
+      var waiters = drainWaiters.slice();
+      drainWaiters.length = 0;
+      for (var i = 0; i < waiters.length; i += 1) waiters[i]();
+    }
+  }
+
+  function _settle() {
+    inFlight -= 1;
+    _pump();
+  }
+
+  function _enqueue(taskFn) {
+    if (typeof taskFn !== "function") {
+      throw new PromisePoolError("promise-pool/bad-task",
+        "b.promisePool: task must be a function returning a value or Promise");
+    }
+    if (closed) {
+      throw new PromisePoolError("promise-pool/closed",
+        "b.promisePool: pool is closed (drain({close:true}) was called)");
+    }
+    if (queue.length >= queueLimit) {
+      throw new PromisePoolError("promise-pool/queue-full",
+        "b.promisePool: queueLimit=" + queueLimit + " reached");
+    }
+    return new Promise(function (resolve, reject) {
+      queue.push({ taskFn: taskFn, resolve: resolve, reject: reject });
+      _pump();
+    });
+  }
+
+  function run(taskFn)  { return _enqueue(taskFn); }
+  function fire(taskFn) { return _enqueue(taskFn); }
+
+  function drain(drainOpts) {
+    drainOpts = drainOpts || {};
+    return new Promise(function (resolve) {
+      function _done() {
+        if (drainOpts.close === true) closed = true;
+        resolve();
+      }
+      if (inFlight === 0 && queue.length === 0) { _done(); return; }
+      drainWaiters.push(_done);
+    });
+  }
+
+  return {
+    run:      run,
+    fire:     fire,
+    drain:    drain,
+    size:     function () { return concurrency; },
+    inFlight: function () { return inFlight; },
+    queued:   function () { return queue.length; },
+    closed:   function () { return closed; },
+  };
+}
+
+module.exports = {
+  create:           create,
+  PromisePoolError: PromisePoolError,
+};