@blamejs/core 0.10.14 → 0.11.0

package/lib/mail-crypto-pgp.js

@@ -120,6 +120,7 @@ var lazyRequire  = require("./lazy-require");
 var audit        = lazyRequire(function () { return require("./audit"); });
 var nodeCrypto   = require("node:crypto");
 var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
 var { defineClass } = require("./framework-error");
 
 var MailCryptoError = defineClass("MailCryptoError", { alwaysPermanent: true });
@@ -923,12 +924,321 @@ function _audit(auditHandle, action, outcome, metadata) {
   } catch (_e) { /* drop-silent — audit failures must not crash callers */ }
 }
 
+// ---- v0.10.16 experimental encrypt/decrypt + WKD ----
+//
+// PQC PGP encrypt/decrypt for ML-KEM-1024 recipients shipped under
+// `experimental` namespace (RFC 9580bis PKESK ML-KEM codepoints
+// haven't IANA-registered yet). Framework-private envelope matching
+// the v0.10.10 `b.jose.jwe.experimental` precedent. Operators
+// integrating with peers running this same framework get
+// encrypt/decrypt today; cross-implementation interop waits for IANA.
+
+var bCrypto    = require("./crypto");
+var pqcSoftware = require("./pqc-software");
+
+var PGP_PQ_MAGIC = Buffer.from("BJ-PGP-PQ", "ascii");                                                 // allow:raw-byte-literal — 9-byte framework magic
+var PGP_PQ_VERSION = 1;                                                                               // allow:raw-byte-literal — envelope version
+
+function experimentalEncrypt(opts) {
+  opts = validateOpts.requireObject(opts, "mail.crypto.pgp.experimental.encrypt",
+    MailCryptoError, "mail-crypto/pgp/bad-opts");
+  validateOpts(opts, ["message", "recipients", "audit"], "mail.crypto.pgp.experimental.encrypt");
+  if (!opts.message || (!Buffer.isBuffer(opts.message) && typeof opts.message !== "string")) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-message",
+      "encrypt: opts.message must be a Buffer or string");
+  }
+  if (!Array.isArray(opts.recipients) || opts.recipients.length === 0) {
+    throw new MailCryptoError("mail-crypto/pgp/no-recipients",
+      "encrypt: opts.recipients must be a non-empty array");
+  }
+  var plaintext = Buffer.isBuffer(opts.message) ? opts.message : Buffer.from(opts.message, "utf8");
+  var sessionKey = bCrypto.generateBytes(32);                                                         // allow:raw-byte-literal — 256-bit session key
+  var ciphertext = bCrypto.encryptPacked(plaintext, sessionKey);
+  var recipientBlobs = [];
+  for (var i = 0; i < opts.recipients.length; i += 1) {
+    var r = opts.recipients[i];
+    if (!Buffer.isBuffer(r.recipientId)) {
+      throw new MailCryptoError("mail-crypto/pgp/bad-recipient",
+        "encrypt: recipients[" + i + "].recipientId must be a Buffer");
+    }
+    if (!(r.publicKey instanceof Uint8Array)) {
+      throw new MailCryptoError("mail-crypto/pgp/bad-recipient",
+        "encrypt: recipients[" + i + "].publicKey must be a Uint8Array (ML-KEM-1024)");
+    }
+    if (r.recipientId.length > 255) {                                                                 // allow:raw-byte-literal — u8 length cap
+      throw new MailCryptoError("mail-crypto/pgp/bad-recipient",
+        "encrypt: recipients[" + i + "].recipientId must be <= 255 bytes");
+    }
+    var encap = pqcSoftware.ml_kem_1024.encapsulate(r.publicKey);
+    var kek = bCrypto.kdf(Buffer.concat([
+      Buffer.from(encap.sharedSecret),
+      Buffer.from("pgp/experimental/chacha20-poly1305", "ascii"),
+    ]), 32);                                                                                          // allow:raw-byte-literal — 256-bit KEK
+    var wrappedKey = bCrypto.encryptPacked(sessionKey, kek);
+    var ct = Buffer.from(encap.cipherText);
+    recipientBlobs.push(Buffer.concat([
+      Buffer.from([r.recipientId.length]),
+      r.recipientId,
+      _u16be(ct.length),
+      ct,
+      _u16be(wrappedKey.length),
+      wrappedKey,
+    ]));
+  }
+  var envelope = Buffer.concat([
+    PGP_PQ_MAGIC,
+    Buffer.from([PGP_PQ_VERSION]),
+    Buffer.from([opts.recipients.length]),                                                            // allow:raw-byte-literal — u8 recipient count
+    Buffer.concat(recipientBlobs),
+    _u32be(ciphertext.length),
+    ciphertext,
+  ]);
+  var armored = _armorMessage(envelope);
+  _audit(opts.audit, "mail.crypto.pgp.experimental.encrypt", "success", {
+    recipients: opts.recipients.length,
+  });
+  return { armored: armored, envelope: envelope };
+}
+
+function experimentalDecrypt(opts) {
+  opts = validateOpts.requireObject(opts, "mail.crypto.pgp.experimental.decrypt",
+    MailCryptoError, "mail-crypto/pgp/bad-opts");
+  validateOpts(opts, ["armored", "envelope", "recipientId", "secretKey", "audit"],
+    "mail.crypto.pgp.experimental.decrypt");
+  if (!Buffer.isBuffer(opts.recipientId)) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-opts",
+      "decrypt: opts.recipientId must be a Buffer");
+  }
+  if (!(opts.secretKey instanceof Uint8Array)) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-opts",
+      "decrypt: opts.secretKey must be a Uint8Array");
+  }
+  var envelope;
+  if (Buffer.isBuffer(opts.envelope)) {
+    envelope = opts.envelope;
+  } else if (typeof opts.armored === "string" && opts.armored.length > 0) {
+    envelope = _dearmorMessage(opts.armored);
+  } else {
+    throw new MailCryptoError("mail-crypto/pgp/bad-opts",
+      "decrypt: opts.envelope OR opts.armored required");
+  }
+  if (envelope.length < PGP_PQ_MAGIC.length + 2 ||
+      !envelope.slice(0, PGP_PQ_MAGIC.length).equals(PGP_PQ_MAGIC)) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-magic",
+      "decrypt: envelope magic mismatch (not a blamejs-pgp-pq-v1 envelope)");
+  }
+  var off = PGP_PQ_MAGIC.length;
+  var version = envelope[off]; off += 1;
+  if (version !== PGP_PQ_VERSION) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-version",
+      "decrypt: envelope version " + version + " unsupported (expected " + PGP_PQ_VERSION + ")");
+  }
+  var nRecips = envelope[off]; off += 1;
+  var matchedSessionKey = null;
+  for (var i = 0; i < nRecips; i += 1) {
+    if (off >= envelope.length) {
+      throw new MailCryptoError("mail-crypto/pgp/truncated",
+        "decrypt: envelope truncated at recipient " + i);
+    }
+    var ridLen = envelope[off]; off += 1;
+    var rid = envelope.slice(off, off + ridLen); off += ridLen;
+    var ctLen = envelope.readUInt16BE(off); off += 2;                                                 // allow:raw-byte-literal — u16-be width
+    var ct = envelope.slice(off, off + ctLen); off += ctLen;
+    var wkLen = envelope.readUInt16BE(off); off += 2;                                                 // allow:raw-byte-literal — u16-be width
+    var wrappedKey = envelope.slice(off, off + wkLen); off += wkLen;
+    if (matchedSessionKey) continue;
+    if (!rid.equals(opts.recipientId)) continue;
+    var shared;
+    try { shared = pqcSoftware.ml_kem_1024.decapsulate(new Uint8Array(ct), opts.secretKey); }
+    catch (e) {
+      throw new MailCryptoError("mail-crypto/pgp/decap-failed",
+        "decrypt: ML-KEM-1024 decapsulate failed: " + ((e && e.message) || String(e)));
+    }
+    var kek = bCrypto.kdf(Buffer.concat([
+      Buffer.from(shared),
+      Buffer.from("pgp/experimental/chacha20-poly1305", "ascii"),
+    ]), 32);                                                                                          // allow:raw-byte-literal — 256-bit KEK
+    try { matchedSessionKey = bCrypto.decryptPacked(wrappedKey, kek); }
+    catch (e2) {
+      throw new MailCryptoError("mail-crypto/pgp/unwrap-failed",
+        "decrypt: session-key unwrap failed: " + ((e2 && e2.message) || String(e2)));
+    }
+  }
+  if (!matchedSessionKey) {
+    throw new MailCryptoError("mail-crypto/pgp/no-matching-recipient",
+      "decrypt: no recipient in envelope matches opts.recipientId");
+  }
+  var bodyLen = envelope.readUInt32BE(off); off += 4;                                                 // allow:raw-byte-literal — u32-be width
+  var body = envelope.slice(off, off + bodyLen);
+  var plaintext;
+  try { plaintext = bCrypto.decryptPacked(body, matchedSessionKey); }
+  catch (e3) {
+    throw new MailCryptoError("mail-crypto/pgp/body-decrypt-failed",
+      "decrypt: body AEAD verify failed: " + ((e3 && e3.message) || String(e3)));
+  }
+  _audit(opts.audit, "mail.crypto.pgp.experimental.decrypt", "success", {});
+  return { plaintext: plaintext, recipientId: opts.recipientId };
+}
+
+function _armorMessage(bytes) {
+  var b64 = bytes.toString("base64");
+  var lines = [];
+  for (var i = 0; i < b64.length; i += 64) {                                                          // allow:raw-byte-literal — RFC 2045 base64 line length
+    lines.push(b64.slice(i, i + 64));                                                                 // allow:raw-byte-literal — RFC 2045 base64 line length
+  }
+  return "-----BEGIN PGP MESSAGE-----\r\nVersion: blamejs-pgp-pq-v1\r\n\r\n" +
+         lines.join("\r\n") + "\r\n-----END PGP MESSAGE-----\r\n";
+}
+
+function _dearmorMessage(armored) {
+  // Line-by-line parser — avoids the polynomial-time backtracking of
+  // the prior regex (CodeQL "Polynomial regular expression on
+  // uncontrolled data"). The previous shape
+  //   /-----BEGIN PGP MESSAGE-----\r?\n(?:[^\r\n]+\r?\n)*\r?\n.../
+  // backtracks pathologically on inputs starting with many repeated
+  // BEGIN lines. Split + walk in linear time instead.
+  if (typeof armored !== "string") {
+    throw new MailCryptoError("mail-crypto/pgp/bad-armor",
+      "dearmor: envelope must be a string");
+  }
+  var lines = armored.split(/\r?\n/);
+  var begin = -1;
+  var end = -1;
+  for (var i = 0; i < lines.length; i += 1) {
+    if (begin === -1 && lines[i] === "-----BEGIN PGP MESSAGE-----") begin = i;
+    else if (begin !== -1 && lines[i] === "-----END PGP MESSAGE-----") { end = i; break; }
+  }
+  if (begin === -1 || end === -1) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-armor",
+      "dearmor: envelope is not BEGIN PGP MESSAGE armored");
+  }
+  // Skip header lines until the blank-line separator (RFC 9580 §6.2),
+  // then collect base64 body lines until the END marker.
+  var bodyStart = begin + 1;
+  while (bodyStart < end && lines[bodyStart] !== "") bodyStart += 1;
+  if (bodyStart >= end) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-armor",
+      "dearmor: armor header has no blank-line separator before body");
+  }
+  var bodyChunks = [];
+  for (var j = bodyStart + 1; j < end; j += 1) bodyChunks.push(lines[j]);
+  return Buffer.from(bodyChunks.join(""), "base64");
+}
+
+/**
+ * @primitive  b.mail.crypto.pgp.experimental.wkd.fetch
+ * @signature  b.mail.crypto.pgp.experimental.wkd.fetch(email, opts)
+ * @since      0.10.16
+ * @status     experimental
+ *
+ * Fetch a WKD key for `email` per draft-koch-openpgp-webkey-service.
+ * Tries the direct URL first; on 404 / network failure falls back
+ * to the advanced URL. `opts.httpsGet(url) → Promise<{ status,
+ * body: Buffer }>` is operator-supplied so the framework doesn't
+ * couple to a specific HTTP client. Returns
+ * `{ keyBytes, source: "direct" | "advanced", url }` or throws
+ * `mail-crypto/pgp/wkd-not-found` when both URLs fail.
+ *
+ * @opts
+ *   httpsGet:      Function,   // (url) → Promise<{ status, body }>; REQUIRED
+ *   advancedHost:  string,     // passed through to computeUrl
+ *   maxKeyBytes:   number,     // default 256 KiB
+ *
+ * @example
+ *   var key = await b.mail.crypto.pgp.experimental.wkd.fetch("alice@example.com", {
+ *     httpsGet: function (url) {
+ *       return b.httpClient.request({ url: url, method: "GET" });
+ *     },
+ *   });
+ */
+function wkdFetch(email, opts) {
+  opts = validateOpts.requireObject(opts, "mail.crypto.pgp.experimental.wkd.fetch",
+    MailCryptoError, "mail-crypto/pgp/bad-opts");
+  if (typeof opts.httpsGet !== "function") {
+    throw new MailCryptoError("mail-crypto/pgp/no-https-get",
+      "wkd.fetch: opts.httpsGet must be a function (url) => Promise<{status, body}>");
+  }
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.maxKeyBytes, "maxKeyBytes",
+    MailCryptoError, "mail-crypto/pgp/bad-max-key-bytes");
+  var maxBytes = typeof opts.maxKeyBytes === "number" ? opts.maxKeyBytes : (256 * 1024);            // allow:raw-byte-literal — 256 KiB default key cap
+  var urls = wkdComputeUrl(email, { advancedHost: opts.advancedHost });
+  return Promise.resolve(opts.httpsGet(urls.direct)).then(function (resp) {
+    if (resp && resp.status === 200 && Buffer.isBuffer(resp.body) && resp.body.length > 0) {          // allow:raw-byte-literal — HTTP 200
+      if (resp.body.length > maxBytes) {
+        throw new MailCryptoError("mail-crypto/pgp/wkd-too-large",
+          "wkd.fetch: key bytes " + resp.body.length + " exceed maxKeyBytes=" + maxBytes);
+      }
+      return { keyBytes: resp.body, source: "direct", url: urls.direct };
+    }
+    return Promise.resolve(opts.httpsGet(urls.advanced)).then(function (resp2) {
+      if (resp2 && resp2.status === 200 && Buffer.isBuffer(resp2.body) && resp2.body.length > 0) {    // allow:raw-byte-literal — HTTP 200
+        if (resp2.body.length > maxBytes) {
+          throw new MailCryptoError("mail-crypto/pgp/wkd-too-large",
+            "wkd.fetch: key bytes " + resp2.body.length + " exceed maxKeyBytes=" + maxBytes);
+        }
+        return { keyBytes: resp2.body, source: "advanced", url: urls.advanced };
+      }
+      throw new MailCryptoError("mail-crypto/pgp/wkd-not-found",
+        "wkd.fetch: neither direct nor advanced URL returned a key for " + email);
+    });
+  });
+}
+
+function wkdComputeUrl(email, opts) {
+  opts = opts || {};
+  if (typeof email !== "string" || email.indexOf("@") <= 0 || email.indexOf("@") === email.length - 1) {
+    throw new MailCryptoError("mail-crypto/pgp/bad-email",
+      "wkd.computeUrl: email must be a 'local@domain' string");
+  }
+  var at = email.indexOf("@");
+  var localRaw = email.slice(0, at);
+  var localLower = localRaw.toLowerCase();
+  var domain = email.slice(at + 1).toLowerCase();
+  var hashed = bCrypto.kdf(Buffer.from(localLower, "utf8"), 20);                                      // allow:raw-byte-literal — 20-byte hash per draft-koch §3.1
+  var encoded = _zbase32Encode(hashed);
+  var advancedHost = opts.advancedHost || ("openpgpkey." + domain);
+  var encodedLocal = encodeURIComponent(localRaw);
+  return {
+    direct:     "https://" + domain + "/.well-known/openpgpkey/hu/" + encoded + "?l=" + encodedLocal,
+    advanced:   "https://" + advancedHost + "/.well-known/openpgpkey/" + domain + "/hu/" + encoded + "?l=" + encodedLocal,
+    hashed:     encoded,
+    localLower: localLower,
+    domain:     domain,
+  };
+}
+
+var ZBASE32_ALPHABET = "ybndrfg8ejkmcpqxot1uwisza345h769";
+
+function _zbase32Encode(buf) {
+  var bits = 0;
+  var bitCount = 0;
+  var out = "";
+  for (var i = 0; i < buf.length; i += 1) {
+    bits = (bits << 8) | buf[i];                                                                      // allow:raw-byte-literal — 8 bits per input byte
+    bitCount += 8;                                                                                    // allow:raw-byte-literal — 8 bits per input byte
+    while (bitCount >= 5) {                                                                           // allow:raw-byte-literal — 5 bits per zbase32 char
+      bitCount -= 5;                                                                                  // allow:raw-byte-literal — 5 bits per zbase32 char
+      out += ZBASE32_ALPHABET.charAt((bits >> bitCount) & 0x1f);                                      // allow:raw-byte-literal — 5-bit mask
+    }
+  }
+  if (bitCount > 0) {
+    out += ZBASE32_ALPHABET.charAt((bits << (5 - bitCount)) & 0x1f);                                  // allow:raw-byte-literal — final partial char
+  }
+  return out;
+}
+
 module.exports = {
   sign:            sign,
   verify:          verify,
+  experimental: {
+    encrypt:    experimentalEncrypt,
+    decrypt:    experimentalDecrypt,
+    wkd: {
+      computeUrl: wkdComputeUrl,
+      fetch:      wkdFetch,
+    },
+  },
   MailCryptoError: MailCryptoError,
-  // Test-only exports — operators don't call these. Stable for v1 so
-  // the codebase-patterns gate sees them as named.
   _v4FingerprintForTest: _v4Fingerprint,
   _armorForTest:         _armor,
   _dearmorForTest:       _dearmor,