@blamejs/core 0.9.46 → 0.10.1

package/lib/mail-dkim.js

@@ -43,6 +43,8 @@ var audit       = lazyRequire(function () { return require("./audit"); });
 var nodeCrypto  = require("node:crypto");
 var safeBuffer  = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
+var C           = require("./constants");
+var networkDnsResolver = lazyRequire(function () { return require("./network-dns-resolver"); });
 var { FrameworkError } = require("./framework-error");
 
 class DkimError extends FrameworkError {
@@ -63,11 +65,20 @@ var ALLOWED_CANON = [
 ];
 var DEFAULT_HEADERS = ["from", "to", "subject", "date", "message-id"];
 
-// RSA modulus bit-size thresholds per RFC 8301 §3.1 + M³AAWG hardening
-// guidance. Anything below MIN must be considered failure; below WEAK
+// RSA modulus bit-size thresholds per RFC 8301bis (draft-ietf-dmarc-rfc8301bis)
+// + Google + Yahoo February 2024 bulk-sender policy + M³AAWG hardening.
+// RFC 8301 §3.1 historic floor was 1024; bulk-sender enforcement at the
+// two largest mailbox providers raised the operational floor to 2048
+// (messages signed with <2048-bit keys are rejected or quarantined).
+// Anything below MIN must be considered failure on verify; below WEAK
 // emits a warning so operators can quarantine while transitioning.
-var RSA_MIN_BITS  = 1024;                                                        // allow:raw-byte-literal — RFC 8301 RSA bit floor
-var RSA_WEAK_BITS = 2048;                                                        // allow:raw-byte-literal — RFC 8301 RSA bit weak threshold
+// Operators stuck with legacy 1024-bit signers (deprecated; remediate
+// before bulk-sending) opt down via verify({ minRsaBits: 1024 }) per-call
+// — the historical floor stays available for migration but the
+// framework default refuses sub-2048 inbound.
+var RSA_MIN_BITS  = 2048;                                                        // allow:raw-byte-literal — RFC 8301bis + 2024 bulk-sender floor
+var RSA_WEAK_BITS = 2048;                                                        // allow:raw-byte-literal — RFC 8301bis weak threshold (same as floor)
+var RSA_LEGACY_MIN_BITS = 1024;                                                  // allow:raw-byte-literal — RFC 8301 historical floor, opt-in only
 
 // ---- Canonicalization (RFC 6376 §3.4) ----
 
@@ -329,7 +340,19 @@ function create(opts) {
     // order, picking the LAST occurrence per RFC 6376 §5.4.2), then
     // the DKIM-Signature header itself with empty b=. The result is
     // what gets signed.
+    //
+    // Missing-header policy (RFC 6376 §3.4.2 + §5.4): the signer is
+    // permitted to list a header in h= that isn't present in the
+    // message — the verifier will compute the canonicalized form as
+    // empty and the signature still validates IF both sides agree the
+    // header is absent. The risk is silent drift: an operator
+    // configures `headersToSign: [..., "List-Unsubscribe-Post", ...]`
+    // for a campaign mailer, the per-message builder forgets to add
+    // the header, and the signature ships without binding to the
+    // intended commitment. Emit an audit event so operators see the
+    // skip rather than only noticing when a recipient rejects.
     var headerNamesLc = parsedHeaders.map(function (h) { return h.name.toLowerCase(); });
+    var missingHeaders = [];
     var canonicalizedHeaders = "";
     for (var j = 0; j < headersToSign.length; j++) {
       var wantLc = headersToSign[j].toLowerCase();
@@ -337,12 +360,33 @@ function create(opts) {
       for (var k = 0; k < headerNamesLc.length; k++) {
         if (headerNamesLc[k] === wantLc) idx = k;
       }
-      if (idx === -1) continue;  // missing headers are skipped (signer's choice)
+      if (idx === -1) {
+        // Operator configured h= entry that isn't in the message —
+        // surface via audit; sign continues per RFC 6376 §3.4.2.
+        missingHeaders.push(headersToSign[j]);
+        continue;
+      }
       var h = parsedHeaders[idx];
       canonicalizedHeaders += canonHeader === "simple"
         ? _canonHeaderSimple(h.name, h.value)
         : _canonHeaderRelaxed(h.name, h.value);
     }
+    if (missingHeaders.length > 0 && auditOn) {
+      try {
+        audit().safeEmit({
+          action:  "dkim.sign.headers_missing",
+          outcome: "success",
+          actor:   null,
+          metadata: {
+            domain:           opts.domain,
+            selector:         opts.selector,
+            missingHeaders:   missingHeaders,
+            headersConfigured: headersToSign.length,
+            severity:         "warning",
+          },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
     // Append the unsigned DKIM-Signature header without trailing CRLF
     // per RFC 6376 §3.7.
     var dkimHeaderForSigning = canonHeader === "simple"
@@ -463,10 +507,25 @@ function _selectorTxtToKeyTags(txtRecords) {
 // fan-out and bulk-replay scenarios frequently re-fetch the same
 // selector; without a cache the verifier hammers DNS. TTL bounded so
 // rotated keys propagate within minutes, not hours.
+//
+// Eviction is LRU (not FIFO): on hit, the entry is removed and
+// re-inserted so the Map's insertion-order ordering tracks recency.
+// FIFO would evict the most-recently-fetched key of an
+// active-domain mix under cache pressure — exactly the wrong shape
+// for repeated-sender workloads.
 var DKIM_KEY_CACHE = new Map();
-var DKIM_KEY_CACHE_TTL_MS = 5 * 60 * 1000;                                       // allow:raw-time-literal — TTL ms expression
+var DKIM_KEY_CACHE_TTL_MS = C.TIME.minutes(5);
 var DKIM_KEY_CACHE_MAX_ENTRIES = 1024;
 
+// Per-message signature-count cap (DoS bound). A single message with
+// many DKIM-Signature headers forces the verifier to fetch a key and
+// run cryptographic verify for each — without a cap, an attacker
+// inflates verifier work linearly in header count. RFC 6376 §6.1
+// permits multiple signatures but doesn't bound them; mainstream
+// receivers cap at 5–8. Operators that legitimately accept more
+// override via verify({ maxSignatures }).
+var DKIM_MAX_SIGNATURES_PER_MESSAGE = 8;                                         // allow:raw-byte-literal — receiver-fan-out DoS bound
+
 function _cacheGet(qname) {
   var ent = DKIM_KEY_CACHE.get(qname);
   if (!ent) return null;
@@ -474,18 +533,59 @@ function _cacheGet(qname) {
     DKIM_KEY_CACHE.delete(qname);
     return null;
   }
+  // LRU: remove + re-insert so this entry becomes the most-recent in
+  // Map insertion order. Evictions below pop the oldest via keys().
+  DKIM_KEY_CACHE.delete(qname);
+  DKIM_KEY_CACHE.set(qname, ent);
   return ent.tags;
 }
 
 function _cachePut(qname, tags) {
   if (DKIM_KEY_CACHE.size >= DKIM_KEY_CACHE_MAX_ENTRIES) {
-    // Drop oldest (Map preserves insertion order). Cheap LRU-ish.
+    // Drop oldest by insertion-order (LRU since _cacheGet rotates).
     var oldest = DKIM_KEY_CACHE.keys().next().value;
     if (oldest !== undefined) DKIM_KEY_CACHE.delete(oldest);
   }
   DKIM_KEY_CACHE.set(qname, { tags: tags, expires: Date.now() + DKIM_KEY_CACHE_TTL_MS });
 }
 
+// Shared safe-DNS TXT lookup. Operator-supplied `dnsLookup` (legacy
+// `[[strings]]` shape) takes precedence; otherwise routes through
+// `b.network.dns.resolver` which uses DoH by default (per v0.7.23),
+// so the framework default never falls back to plaintext node:dns
+// resolution against an operator-untrusted upstream. CVE-2008-1447
+// (Kaminsky) + CVE-2022-3204 (NRDelegationAttack) class — the
+// transport-encrypted DoH path plus `b.safeDns` parse caps defend
+// both transport and parse-side. Operators that need plaintext
+// upstream wire it explicitly via `dnsLookup`.
+var _defaultResolver = null;
+function _getDefaultResolver() {
+  if (_defaultResolver) return _defaultResolver;
+  _defaultResolver = networkDnsResolver().create();
+  return _defaultResolver;
+}
+
+async function _safeResolveTxt(qname, operatorLookup) {
+  if (operatorLookup) return operatorLookup(qname, "TXT");
+  var r = await _getDefaultResolver().queryTxt(qname);
+  // Resolver returns parsed RRs; reshape to the legacy
+  // `[[chunk1, chunk2], ...]` shape so callers downstream don't care
+  // which path produced the bytes.
+  var out = [];
+  for (var i = 0; i < r.rrs.length; i += 1) {
+    var rr = r.rrs[i];
+    if (rr && rr.type === 16) {                                                  // allow:raw-byte-literal — IANA DNS qtype TXT
+      out.push(Array.isArray(rr.decoded) ? rr.decoded : [String(rr.decoded)]);
+    }
+  }
+  if (out.length === 0) {
+    var err = new Error("no TXT records for " + qname);
+    err.code = "ENODATA";
+    throw err;
+  }
+  return out;
+}
+
 function _resetDkimKeyCacheForTest() { DKIM_KEY_CACHE.clear(); }
 
 function _pemFromB64KeyMaterial(b64) {
@@ -507,12 +607,7 @@ async function _fetchDkimKey(domain, selector, dnsLookup) {
   if (cached) return cached;
   var records;
   try {
-    if (dnsLookup) {
-      records = await dnsLookup(qname, "TXT");
-    } else {
-      var dnsModule = require("node:dns/promises");
-      records = await dnsModule.resolveTxt(qname);
-    }
+    records = await _safeResolveTxt(qname, dnsLookup);
   } catch (e) {
     if (e && (e.code === "ENOTFOUND" || e.code === "ENODATA")) {
       throw new DkimError("dkim/key-not-found",
@@ -537,13 +632,68 @@ function _findDkimSignatureHeaders(parsedHeaders) {
   return out;
 }
 
-function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTags) {
+// Strip the value of the `b=` tag from a DKIM-Signature tag list per
+// RFC 6376 §3.7. Walks tag-spec boundaries (`;` separator) and only
+// matches the exact `b` tag name — not any tag whose name happens
+// to end in `b`. Returns the value with the b= tag's content removed
+// (leaving `b=` in place).
+function _stripBTagValue(value) {
+  var parts = String(value).split(";");
+  var out = [];
+  for (var i = 0; i < parts.length; i += 1) {
+    var p = parts[i];
+    var m = /^(\s*)([A-Za-z][A-Za-z0-9_-]*)(\s*=)/.exec(p);
+    if (m && m[2].toLowerCase() === "b") {
+      out.push(m[1] + m[2] + m[3]);
+      continue;
+    }
+    out.push(p);
+  }
+  return out.join(";");
+}
+
+function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTags, verifyOpts) {
+  verifyOpts = verifyOpts || {};
   // Reconstruct what the signer canonicalized, per RFC 6376 §3.7.
   var canonicalization = sigTags.c || "simple/simple";
   var canonHeader = canonicalization.split("/")[0];
   var canonBody   = canonicalization.split("/")[1];
   var algorithm   = sigTags.a;
 
+  // RFC 6376 §3.5 — the optional i= tag (Agent or User Identifier),
+  // when present, MUST have a domain part identical to or a subdomain
+  // of d=. A signature whose i= claims `@evil.example.com` while d=
+  // is `example.org` is malformed and binds the signer's claim to a
+  // domain the verifier wouldn't otherwise associate. Refuse.
+  if (typeof sigTags.i === "string" && sigTags.i.length > 0) {
+    var iDomain = sigTags.i.indexOf("@") === -1
+                    ? sigTags.i
+                    : sigTags.i.slice(sigTags.i.indexOf("@") + 1);
+    var d = String(sigTags.d || "").toLowerCase();
+    var iDl = iDomain.toLowerCase();
+    if (d.length === 0 || (iDl !== d && iDl.slice(-d.length - 1) !== "." + d)) {
+      return { result: "permerror",
+               errors: ["DKIM-Signature i=" + sigTags.i + " is not d= or a subdomain of d=" + sigTags.d + " (RFC 6376 §3.5)"] };
+    }
+  }
+
+  // RFC 6376 §3.6.1 — the key record's optional h= tag declares the
+  // hash algorithms the key MAY be used with (`sha256` is canonical).
+  // The signature's a= names the hash via its suffix (`rsa-sha256`,
+  // `ed25519-sha256`). If h= is present on the key, the signature's
+  // hash MUST appear in the colon-separated list; otherwise the key
+  // owner intends the key for a different hash family and the
+  // signature is unauthorized.
+  if (typeof keyTags.h === "string" && keyTags.h.length > 0) {
+    var sigHash = String(algorithm || "").toLowerCase().split("-").slice(-1)[0];
+    var allowedHashes = keyTags.h.toLowerCase().split(":").map(function (s) { return s.trim(); });
+    if (sigHash.length === 0 || allowedHashes.indexOf(sigHash) === -1) {
+      return { result: "permerror",
+               errors: ["DKIM-Signature a=" + algorithm + " hash '" + sigHash +
+                        "' not in key h=" + keyTags.h + " (RFC 6376 §3.6.1)"] };
+    }
+  }
+
   var split = _splitHeadersBody(rfc822);
   var body = split.body;
   if (sigTags.l !== undefined) {
@@ -593,8 +743,15 @@ function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTa
       : _canonHeaderRelaxed(h.name, h.value);
   }
   // Strip the b= value from the DKIM-Signature header for the canonical
-  // form per §3.7.
-  var unsignedSigValue = sigHeader.value.replace(/(\bb=)[^;]*/i, "$1");
+  // form per RFC 6376 §3.7. The strip must locate the `b=` tag within
+  // the tag-list grammar (`tag-spec *( ";" tag-spec )` per §3.2) and
+  // zero its value through the next `;` OR end-of-string. The earlier
+  // shape `/(\bb=)[^;]*/i` matched on the first `b=` substring anywhere
+  // in the value — fine for current DKIM tag vocabulary (no tag-name
+  // ends in `b`) but brittle against any hypothetical future tag whose
+  // name ends in `b` (`ab=`, `pub=`, `cb=` …). Anchor on the tag-list
+  // structure instead.
+  var unsignedSigValue = _stripBTagValue(sigHeader.value);
   canonicalizedHeaders += canonHeader === "simple"
     ? _canonHeaderSimple("DKIM-Signature", " " + unsignedSigValue).replace(/\r\n$/, "")
     : _canonHeaderRelaxed("DKIM-Signature", unsignedSigValue).replace(/\r\n$/, "");
@@ -620,16 +777,27 @@ function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTa
              errors: ["unsupported DKIM algorithm '" + algorithm + "'"] };
   }
 
-  // Key-size enforcement (RFC 8301 §3.1, M³AAWG hardening guidance):
-  // RSA keys < 1024 bits MUST be considered failure; < 2048 is weak.
-  // The framework rejects < 1024 as a security baseline; < 2048 emits
-  // a warning in the result so operators can quarantine.
+  // Key-size enforcement (RFC 8301bis §3.1 + Google + Yahoo Feb 2024
+  // bulk-sender + M³AAWG hardening):
+  //   - Default floor: 2048 bits (bulk-sender enforced floor).
+  //   - Operator opt-down: verify({ minRsaBits: 1024 }) re-enables the
+  //     historical RFC 8301 floor for legacy migration windows. Sub-
+  //     1024 is refused regardless of opt-down — no operator policy
+  //     can accept genuinely-too-small RSA per §3.1.
+  //   - Below opt-down-honored floor → fail; below WEAK threshold →
+  //     warning so operators can quarantine while transitioning.
+  var operatorMinBits = (typeof verifyOpts.minRsaBits === "number" &&
+                          isFinite(verifyOpts.minRsaBits) &&
+                          verifyOpts.minRsaBits >= RSA_LEGACY_MIN_BITS)
+                         ? Math.floor(verifyOpts.minRsaBits)
+                         : RSA_MIN_BITS;
   var warnings = [];
   if (algorithm === "rsa-sha256" && keyObj.asymmetricKeyType === "rsa") {
     var modBits = (keyObj.asymmetricKeyDetails && keyObj.asymmetricKeyDetails.modulusLength) || 0;
-    if (modBits > 0 && modBits < RSA_MIN_BITS) {
+    if (modBits > 0 && modBits < operatorMinBits) {
       return { result: "fail",
-               errors: ["RSA key too small: " + modBits + " bits (RFC 8301 §3.1 minimum " + RSA_MIN_BITS + ")"] };
+               errors: ["RSA key too small: " + modBits + " bits (minimum " + operatorMinBits +
+                        " — RFC 8301bis + 2024 bulk-sender)"] };
     }
     if (modBits > 0 && modBits < RSA_WEAK_BITS) {
       warnings.push("rsa-key-weak: " + modBits + " bits (< " + RSA_WEAK_BITS + ")");
@@ -652,13 +820,46 @@ function _verifySingleSignature(rfc822, parsedHeaders, sigHeader, keyTags, sigTa
     : { result: "fail", errors: ["signature verification failed"], warnings: warnings };
 }
 
+// RFC 6376 §3.5 — `t=` / `x=` clock-skew bound. Operator-tunable, but
+// must be a finite non-negative number and must NOT exceed the
+// FRAMEWORK absolute ceiling. An unbounded skew lets an attacker
+// re-play a long-expired signed message indefinitely; the ceiling
+// bounds the maximum back-dating tolerance.
+var DKIM_CLOCK_SKEW_MS_MAX = C.TIME.hours(24);
+var DKIM_CLOCK_SKEW_MS_DEFAULT = C.TIME.minutes(5);
+
 async function verify(rfc822, opts) {
   if (typeof rfc822 !== "string" || rfc822.length === 0) {
     throw new DkimError("dkim/bad-input",
       "verify(): rfc822 must be a non-empty string");
   }
   opts = opts || {};
-  validateOpts(opts, ["dnsLookup", "audit"], "mail.dkim.verify");
+  validateOpts(opts, ["dnsLookup", "audit", "clockSkewMs", "maxSignatures",
+                       "minRsaBits"], "mail.dkim.verify");
+
+  // Bounded clock skew: refuse non-numeric / negative / infinite /
+  // beyond-ceiling. Throwing on bad config-time input per the
+  // framework's three-tier validation policy.
+  var clockSkewMs;
+  if (opts.clockSkewMs === undefined || opts.clockSkewMs === null) {
+    clockSkewMs = DKIM_CLOCK_SKEW_MS_DEFAULT;
+  } else if (typeof opts.clockSkewMs !== "number" || !isFinite(opts.clockSkewMs) ||
+             opts.clockSkewMs < 0) {
+    throw new DkimError("dkim/bad-clock-skew",
+      "verify(): clockSkewMs must be a finite non-negative number");
+  } else if (opts.clockSkewMs > DKIM_CLOCK_SKEW_MS_MAX) {
+    throw new DkimError("dkim/bad-clock-skew",
+      "verify(): clockSkewMs " + opts.clockSkewMs + " exceeds framework ceiling " +
+      DKIM_CLOCK_SKEW_MS_MAX + " (RFC 6376 §3.5 — back-dating replay defense)");
+  } else {
+    clockSkewMs = Math.floor(opts.clockSkewMs);
+  }
+
+  var maxSignatures = (typeof opts.maxSignatures === "number" &&
+                        isFinite(opts.maxSignatures) && opts.maxSignatures >= 1)
+                       ? Math.floor(opts.maxSignatures)
+                       : DKIM_MAX_SIGNATURES_PER_MESSAGE;
+  var verifyOpts = { minRsaBits: opts.minRsaBits };
 
   var split = _splitHeadersBody(rfc822);
   var parsedHeaders = _parseHeaders(split.headers);
@@ -666,6 +867,13 @@ async function verify(rfc822, opts) {
   if (sigHeaders.length === 0) {
     return [{ result: "none", errors: ["no DKIM-Signature headers"] }];
   }
+  // RFC 6376 §6.1 — verifier MUST handle multiple signatures but the
+  // RFC sets no count cap. An unbounded count is a CPU-DoS surface
+  // (each sig forces a DNS fetch + cryptographic verify). Cap and
+  // surface the truncation in the result for operator visibility.
+  if (sigHeaders.length > maxSignatures) {
+    sigHeaders = sigHeaders.slice(0, maxSignatures);
+  }
 
   var results = [];
   for (var i = 0; i < sigHeaders.length; i += 1) {
@@ -685,8 +893,8 @@ async function verify(rfc822, opts) {
     // refuse if more than 24h in the future (clock drift between
     // signer + verifier of more than a day is a near-certain bug or
     // attack). Both are in seconds-since-epoch per ABNF.
-    var nowSec = Math.floor(Date.now() / 1000);                                                // allow:raw-byte-literal — Unix-epoch seconds divisor
-    var clockSkewSec = Math.floor((opts.clockSkewMs || (5 * 60 * 1000)) / 1000);              // allow:raw-time-literal — default 5-minute skew
+    var nowSec = Math.floor(Date.now() / C.TIME.seconds(1));
+    var clockSkewSec = Math.floor(clockSkewMs / C.TIME.seconds(1));
     if (sigTags.x !== undefined) {
       var expSec = parseInt(sigTags.x, 10);
       if (isFinite(expSec) && expSec + clockSkewSec < nowSec) {
@@ -755,7 +963,7 @@ async function verify(rfc822, opts) {
         continue;
       }
     }
-    var rv = _verifySingleSignature(rfc822, parsedHeaders, sigHeaders[i], keyTags, sigTags);
+    var rv = _verifySingleSignature(rfc822, parsedHeaders, sigHeaders[i], keyTags, sigTags, verifyOpts);
     results.push(Object.assign({ d: d, s: s, alg: alg }, rv));
   }
   return results;
@@ -792,13 +1000,210 @@ function dualSigner(opts) {
 
 // Test-only exports for unit testing the canonicalization primitives
 // directly without going through a full sign() round.
+/**
+ * @primitive b.mail.dkim.bootstrap
+ * @signature b.mail.dkim.bootstrap(opts)
+ * @since     0.9.48
+ * @status    stable
+ * @related   b.vault.sealPemFile
+ *
+ * Bootstrap a DKIM keypair + DNS TXT record + ready-to-use signer.
+ * Operators deploying outbound mail (b.mail.send, b.mail.server.submission)
+ * need three things in place: (1) a private signing key, (2) the matching
+ * public key published as a DNS TXT record under
+ * `<selector>._domainkey.<domain>`, (3) a `b.mail.dkim.create(...)` handle
+ * wired into the outbound agent. Pre-this-primitive every consumer
+ * reinvented the keypair-mint + DNS-record-serialize plumbing; this
+ * primitive owns it.
+ *
+ * Default algorithm is `ed25519-sha256` (RFC 8463): smaller DNS record,
+ * faster signing, modern crypto. Operators with receivers that don't yet
+ * support Ed25519 pass `algorithm: "rsa-sha256"` for RFC 6376 (defaults
+ * to 2048-bit RSA per RFC 8301 §3.1 guidance — opt up with `rsaBits`).
+ * Passing `algorithm: "dual"` mints BOTH keypairs and returns a
+ * `b.mail.dkim.dualSigner`-shaped signer that emits two DKIM-Signature
+ * headers (one per alg) for max receiver compat per RFC 8463 §3 dual-
+ * signing pattern.
+ *
+ * @opts
+ *   domain:     string,           // required — RFC 5321 domain
+ *   selector:   string,           // required — RFC 6376 §3.1 selector (the `s1` in s1._domainkey.example.com)
+ *   algorithm:  "ed25519-sha256" | "rsa-sha256" | "dual",
+ *                                  // default: "ed25519-sha256"
+ *   rsaBits:    number,           // RSA-only; default 2048; refused below 1024 (RFC 8301 §3.1)
+ *   rsaSelector: string,          // dual-only; selector for the RSA key (defaults to selector + "-rsa")
+ *
+ * @example
+ *   var dkim = b.mail.dkim.bootstrap({ domain: "example.com", selector: "s1" });
+ *   // → {
+ *   //     algorithm:    "ed25519-sha256",
+ *   //     domain:       "example.com",
+ *   //     selector:     "s1",
+ *   //     privateKeyPem,
+ *   //     publicKeyPem,
+ *   //     dnsName:      "s1._domainkey.example.com",
+ *   //     dnsTxtValue:  "v=DKIM1; k=ed25519; p=MCowBQYDK2Vw...",
+ *   //     dnsRecord:    's1._domainkey.example.com. IN TXT ("v=DKIM1; k=ed25519; p=MCo...")',
+ *   //     signer:       fn(headersToSign?, canonicalization?) → signer,
+ *   //   }
+ *
+ *   // Operator seals the private key via the vault then wires the signer:
+ *   var sealedPath = b.vault.sealPemFile({ source: "/var/lib/blamejs/dkim.key", destination: "/var/lib/blamejs/dkim.key.sealed" });
+ *   var signer = dkim.signer();      // uses dkim.privateKeyPem in-memory
+ *
+ *   // Dual signing — RSA + Ed25519 for max receiver compatibility:
+ *   var dkim2 = b.mail.dkim.bootstrap({ domain: "example.com", selector: "s1", algorithm: "dual" });
+ *   // dkim2.signer() returns a dualSigner emitting both DKIM-Signature headers.
+ */
+function bootstrap(opts) {
+  validateOpts.requireObject(opts, "b.mail.dkim.bootstrap", DkimError, "dkim/bad-opts");
+  validateOpts.requireNonEmptyString(opts.domain, "b.mail.dkim.bootstrap: opts.domain",
+    DkimError, "dkim/bad-domain");
+  validateOpts.requireNonEmptyString(opts.selector, "b.mail.dkim.bootstrap: opts.selector",
+    DkimError, "dkim/bad-selector");
+  var alg = opts.algorithm || "ed25519-sha256";
+  if (alg !== "ed25519-sha256" && alg !== "rsa-sha256" && alg !== "dual") {
+    throw new DkimError("dkim/bad-algorithm",
+      "b.mail.dkim.bootstrap: opts.algorithm must be 'ed25519-sha256' | 'rsa-sha256' | 'dual'");
+  }
+  // DKIM selector + domain shape: RFC 6376 §3.1 — selector is a
+  // sub-domain label (no leading/trailing dot; no whitespace; no
+  // wildcards). domain is a normal DNS hostname.
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/.test(opts.selector)) {                  // allow:regex-no-length-cap — anchored + bounded repeat
+    throw new DkimError("dkim/bad-selector",
+      "b.mail.dkim.bootstrap: opts.selector must match RFC 6376 §3.1 selector shape");
+  }
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,253}[A-Za-z0-9])?$/.test(opts.domain)) {                    // allow:regex-no-length-cap — anchored + bounded repeat
+    throw new DkimError("dkim/bad-domain",
+      "b.mail.dkim.bootstrap: opts.domain must be a DNS-hostname-shaped string");
+  }
+
+  if (alg === "ed25519-sha256") {
+    return _bootstrapSingle("ed25519-sha256", opts.domain, opts.selector);
+  }
+  if (alg === "rsa-sha256") {
+    var bits = opts.rsaBits === undefined ? RSA_MIN_BITS : opts.rsaBits;
+    if (typeof bits !== "number" || !isFinite(bits) || bits < RSA_LEGACY_MIN_BITS || (bits % 1) !== 0) {
+      throw new DkimError("dkim/bad-rsa-bits",
+        "b.mail.dkim.bootstrap: opts.rsaBits must be an integer >= " + RSA_LEGACY_MIN_BITS +
+        " (RFC 8301 §3.1 floor; default " + RSA_MIN_BITS +
+        " per RFC 8301bis + 2024 bulk-sender)");
+    }
+    return _bootstrapSingle("rsa-sha256", opts.domain, opts.selector, bits);
+  }
+  // dual
+  var rsaSelector = opts.rsaSelector || (opts.selector + "-rsa");
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/.test(rsaSelector)) {                    // allow:regex-no-length-cap — anchored + bounded repeat
+    throw new DkimError("dkim/bad-selector",
+      "b.mail.dkim.bootstrap: opts.rsaSelector must match RFC 6376 §3.1 selector shape");
+  }
+  var rsaBits = opts.rsaBits === undefined ? RSA_MIN_BITS : opts.rsaBits;
+  if (typeof rsaBits !== "number" || !isFinite(rsaBits) || rsaBits < RSA_LEGACY_MIN_BITS || (rsaBits % 1) !== 0) {
+    throw new DkimError("dkim/bad-rsa-bits",
+      "b.mail.dkim.bootstrap: opts.rsaBits must be an integer >= " + RSA_LEGACY_MIN_BITS);
+  }
+  var ed = _bootstrapSingle("ed25519-sha256", opts.domain, opts.selector);
+  var rsa = _bootstrapSingle("rsa-sha256",   opts.domain, rsaSelector, rsaBits);
+  return {
+    algorithm:    "dual",
+    domain:       opts.domain,
+    ed25519:      ed,
+    rsa:          rsa,
+    signer: function (signOpts) {
+      signOpts = signOpts || {};
+      return dualSigner({
+        domain:           opts.domain,
+        headersToSign:    signOpts.headersToSign,
+        canonicalization: signOpts.canonicalization,
+        eddsa: {
+          selector:   opts.selector,
+          privateKey: ed.privateKeyPem,
+        },
+        rsa: {
+          selector:   rsaSelector,
+          privateKey: rsa.privateKeyPem,
+        },
+      });
+    },
+  };
+}
+
+function _bootstrapSingle(algorithm, domain, selector, rsaBits) {
+  var keyPair;
+  var k;     // DNS TXT `k=` tag value
+  if (algorithm === "ed25519-sha256") {
+    keyPair = nodeCrypto.generateKeyPairSync("ed25519", {
+      publicKeyEncoding:  { type: "spki",  format: "der" },
+      privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    k = "ed25519";
+  } else {
+    keyPair = nodeCrypto.generateKeyPairSync("rsa", {
+      modulusLength:      rsaBits,
+      publicKeyEncoding:  { type: "spki",  format: "der" },
+      privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    k = "rsa";
+  }
+  var publicKeyPemObj = nodeCrypto.createPublicKey({ key: keyPair.publicKey, type: "spki", format: "der" });
+  var publicKeyPem    = publicKeyPemObj.export({ type: "spki", format: "pem" });
+  var pBase64         = Buffer.from(keyPair.publicKey).toString("base64");
+  var dnsName         = selector + "._domainkey." + domain;
+  // RFC 6376 §3.6.1 record syntax: v=DKIM1; k=<alg>; p=<base64>
+  // The optional t/s/g/n/h/k tags omitted (operator can re-edit
+  // the dnsTxtValue before publishing if they need policy flags).
+  var dnsTxtValue = "v=DKIM1; k=" + k + "; p=" + pBase64;
+  // BIND/Unbound zone-file shape: name TTL? IN TXT ("...").
+  // TXT values > 255 octets must be split into multiple quoted
+  // strings per RFC 1035 §3.3.14 — long RSA records will trip this.
+  var dnsRecord = dnsName + ". IN TXT (" + _wrapDnsTxt(dnsTxtValue) + ")";
+
+  return {
+    algorithm:    algorithm,
+    domain:       domain,
+    selector:     selector,
+    privateKeyPem: keyPair.privateKey,
+    publicKeyPem:  publicKeyPem,
+    dnsName:       dnsName,
+    dnsTxtValue:   dnsTxtValue,
+    dnsRecord:     dnsRecord,
+    signer: function (signOpts) {
+      signOpts = signOpts || {};
+      return create({
+        domain:           domain,
+        selector:         selector,
+        privateKey:       keyPair.privateKey,
+        algorithm:        algorithm,
+        headersToSign:    signOpts.headersToSign,
+        canonicalization: signOpts.canonicalization,
+      });
+    },
+  };
+}
+
+// RFC 1035 §3.3.14 — TXT records carry one or more <character-string>s
+// each capped at 255 octets. Long RSA p= values are split into multiple
+// quoted strings so the zone file is valid.
+function _wrapDnsTxt(value) {
+  if (value.length <= 255) return '"' + value + '"';                                                // allow:raw-byte-literal — RFC 1035 character-string cap
+  var parts = [];
+  for (var i = 0; i < value.length; i += 255) parts.push('"' + value.slice(i, i + 255) + '"');     // allow:raw-byte-literal — RFC 1035 character-string cap
+  return parts.join(" ");
+}
+
 module.exports = {
   create:      create,
+  bootstrap:   bootstrap,
   verify:      verify,
   _resetDkimKeyCacheForTest: _resetDkimKeyCacheForTest,
   dualSigner:  dualSigner,
   DkimError:   DkimError,
+  RSA_MIN_BITS:               RSA_MIN_BITS,
+  RSA_LEGACY_MIN_BITS:        RSA_LEGACY_MIN_BITS,
+  DKIM_MAX_SIGNATURES_PER_MESSAGE: DKIM_MAX_SIGNATURES_PER_MESSAGE,
+  DKIM_CLOCK_SKEW_MS_MAX:     DKIM_CLOCK_SKEW_MS_MAX,
   _canonHeaderRelaxedForTest: _canonHeaderRelaxed,
   _canonBodyRelaxedForTest:   _canonBodyRelaxed,
   _canonBodySimpleForTest:    _canonBodySimple,
+  _stripBTagValueForTest:     _stripBTagValue,
 };