@blamejs/core 0.4.22 → 0.4.24

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.23** (2026-04-30) — b.mail.dkim signing + calendar invites
+- **0.4.22** (2026-04-30) — b.mail attachments + inline images + plain/HTML alternatives
 - **0.4.21** (2026-04-30) — b.queue: repeat-in-queue (cron) + parent-child Flows
 - **0.4.20** (2026-04-30) — b.queue + b.jobs: priority, rate-limit, progress
 - **0.4.19** (2026-04-30) — b.router: schema-validated routes + OpenAPI gen

package/lib/audit.js

@@ -202,6 +202,7 @@ var FRAMEWORK_NAMESPACES = [
   "apikey",     // b.apiKey
   "backup",     // b.backup
   "cache",      // b.cache
+  "dkim",       // b.mail.dkim (DKIM-Signature generation events)
   "mail",       // b.mail (b.mail-bounce uses "system.mail.*")
   "notify",     // b.notify
   "permissions", // b.permissions

package/lib/mail-dkim.js

@@ -0,0 +1,365 @@
+"use strict";
+/**
+ * mail-dkim — DKIM-Signature header generation for outbound mail.
+ *
+ * RFC 6376 (rsa-sha256) is the default; RFC 8463 (ed25519-sha256) is
+ * available as opt-in. The two share the same signer surface so
+ * operators flip algorithms by changing the `algorithm` opt and the
+ * private key — no code change.
+ *
+ * Forward-looking: the DKIM-Signature `a=` tag carries an algorithm
+ * identifier. When the IETF standardizes a post-quantum DKIM algorithm
+ * (an SLH-DSA or ML-DSA variant), this module gains a third allowed
+ * value alongside `rsa-sha256` and `ed25519-sha256`. The signer's
+ * outer surface stays the same.
+ *
+ * Public API:
+ *
+ *   var signer = b.mail.dkim.create({
+ *     domain:          "example.com",
+ *     selector:        "s1",
+ *     privateKey:      pemString | crypto.KeyObject,
+ *     algorithm:       "rsa-sha256" (default) | "ed25519-sha256"
+ *     headersToSign:   ["from","to","subject","date","message-id"]
+ *                       (default — order matters in the signed string)
+ *     canonicalization:"relaxed/relaxed" (default) | "simple/simple"
+ *                      | "relaxed/simple" | "simple/relaxed"
+ *     bodyLength:      number (optional `l=` cap; off by default)
+ *     audit:           false (default true)
+ *   });
+ *
+ *   var signedRfc822 = signer.sign(rfc822String);
+ *
+ * The signer never mutates the message object — it consumes the final
+ * RFC 822 wire format produced by `mail._buildRfc822` and returns a
+ * new string with the DKIM-Signature header prepended.
+ *
+ * Validation surface uses DkimError (FrameworkError subclass) with a
+ * permanent flag — every problem here is a configuration / shape
+ * problem, not a transient one.
+ */
+var lazyRequire = require("./lazy-require");
+var audit       = lazyRequire(function () { return require("./audit"); });
+var nodeCrypto  = require("crypto");
+var validateOpts = require("./validate-opts");
+var { FrameworkError } = require("./framework-error");
+
+class DkimError extends FrameworkError {
+  constructor(code, message) {
+    super(message, code);
+    this.name = "DkimError";
+    this.permanent = true;
+    this.isDkimError = true;
+  }
+}
+
+var ALLOWED_ALGORITHMS = ["rsa-sha256", "ed25519-sha256"];
+var ALLOWED_CANON = [
+  "relaxed/relaxed",
+  "simple/simple",
+  "relaxed/simple",
+  "simple/relaxed",
+];
+var DEFAULT_HEADERS = ["from", "to", "subject", "date", "message-id"];
+
+// ---- Canonicalization (RFC 6376 §3.4) ----
+
+function _canonHeaderRelaxed(name, value) {
+  // Lowercase name, unfold continuations, collapse internal WSP runs to
+  // single SP, strip leading/trailing WSP from value.
+  var unfolded = String(value).replace(/\r?\n[ \t]+/g, " ");
+  var trimmed = unfolded.replace(/[ \t]+/g, " ").replace(/^[ \t]+|[ \t]+$/g, "");
+  return name.toLowerCase() + ":" + trimmed + "\r\n";
+}
+
+function _canonHeaderSimple(name, value) {
+  // Preserve as-is. Used rarely in practice but spec-compliant.
+  return name + ":" + value + "\r\n";
+}
+
+function _canonBodyRelaxed(body) {
+  // 1) Reduce internal WSP runs in each line to a single SP, strip
+  //    trailing WSP. 2) Strip empty lines at end of body. 3) Ensure
+  //    a single trailing CRLF. Empty body → just "\r\n".
+  if (!body) return "\r\n";
+  var normalized = body.replace(/\r?\n/g, "\r\n");
+  var lines = normalized.split("\r\n");
+  for (var i = 0; i < lines.length; i++) {
+    lines[i] = lines[i].replace(/[ \t]+/g, " ").replace(/[ \t]+$/, "");
+  }
+  // Drop trailing empty lines.
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  if (lines.length === 0) return "\r\n";
+  return lines.join("\r\n") + "\r\n";
+}
+
+function _canonBodySimple(body) {
+  // Strip trailing empty lines but otherwise preserve the body. Empty
+  // body → "\r\n".
+  if (!body) return "\r\n";
+  var normalized = body.replace(/\r?\n/g, "\r\n");
+  // Strip trailing empty lines.
+  while (normalized.endsWith("\r\n\r\n")) {
+    normalized = normalized.slice(0, -2);
+  }
+  if (!normalized.endsWith("\r\n")) normalized += "\r\n";
+  return normalized;
+}
+
+// ---- RFC 822 split ----
+
+function _splitHeadersBody(rfc822) {
+  // Headers terminated by the first empty line. Headers may use folded
+  // continuation lines (CRLF + WSP); we keep them folded and let the
+  // canonicalizer unfold relaxed-mode.
+  var sep = rfc822.indexOf("\r\n\r\n");
+  if (sep === -1) {
+    throw new DkimError("dkim/missing-body-separator",
+      "rfc822 input has no header/body separator (CRLF CRLF)");
+  }
+  return {
+    headers: rfc822.slice(0, sep + 2),  // include trailing CRLF after last header
+    body:    rfc822.slice(sep + 4),
+  };
+}
+
+function _parseHeaders(rawHeaders) {
+  // Parse into [{ name, value }, ...] preserving order. Folded
+  // continuation lines (start with WSP) are appended to the prior
+  // header's value verbatim.
+  var lines = rawHeaders.split("\r\n");
+  var out = [];
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    if (!line) continue;
+    if (line[0] === " " || line[0] === "\t") {
+      if (out.length > 0) out[out.length - 1].value += "\r\n" + line;
+      continue;
+    }
+    var colon = line.indexOf(":");
+    if (colon === -1) continue;
+    out.push({
+      name:  line.slice(0, colon),
+      value: line.slice(colon + 1),  // preserve leading SP for simple canon
+    });
+  }
+  return out;
+}
+
+// ---- Hashing + signing ----
+
+function _bodyHashB64(body, algorithm, canonBody) {
+  var canonicalized = canonBody === "simple"
+    ? _canonBodySimple(body)
+    : _canonBodyRelaxed(body);
+  var hashName = "sha256";  // both rsa-sha256 and ed25519-sha256 hash with sha256
+  return nodeCrypto.createHash(hashName)
+    .update(canonicalized).digest("base64");
+}
+
+function _signString(strToSign, privateKey, algorithm) {
+  if (algorithm === "rsa-sha256") {
+    return nodeCrypto.createSign("RSA-SHA256")
+      .update(strToSign).sign(privateKey).toString("base64");
+  }
+  if (algorithm === "ed25519-sha256") {
+    // Ed25519 in node:crypto signs the raw message (it hashes
+    // internally as part of EdDSA). Per RFC 8463 the verifier still
+    // sees `a=ed25519-sha256` because the body hash is sha256.
+    return nodeCrypto.sign(null, Buffer.from(strToSign, "utf8"), privateKey)
+      .toString("base64");
+  }
+  throw new DkimError("dkim/bad-algorithm",
+    "unknown algorithm: " + algorithm);
+}
+
+// ---- Signature header construction ----
+
+function _foldSignatureHeader(unfolded) {
+  // RFC 5322 §2.2.3 line length: 78 preferred, 998 max. The b= value
+  // is long enough that folding helps readability and stays well clear
+  // of the limit.
+  var maxLine = 76;
+  var name = "DKIM-Signature: ";
+  var rest = unfolded;
+  if ((name + rest).length <= maxLine) return name + rest;
+  // Fold on tag boundaries (`; tag=value`). Keep the first chunk on
+  // the header line, subsequent chunks on continuation lines starting
+  // with TAB.
+  var parts = rest.split("; ");
+  var lines = [name + parts[0]];
+  for (var i = 1; i < parts.length; i++) {
+    lines.push("\t" + parts[i] + (i < parts.length - 1 ? ";" : ""));
+  }
+  return lines.join("\r\n");
+}
+
+// ---- Public surface ----
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "domain", "selector", "privateKey", "algorithm",
+    "headersToSign", "canonicalization", "bodyLength", "audit",
+  ], "mail.dkim.create");
+
+  if (typeof opts.domain !== "string" || !/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(opts.domain)) {
+    throw new DkimError("dkim/bad-domain",
+      "domain must be a valid DNS name (e.g. 'example.com')");
+  }
+  if (typeof opts.selector !== "string" || !/^[a-z0-9_-]+$/i.test(opts.selector)) {
+    throw new DkimError("dkim/bad-selector",
+      "selector must be a non-empty token of [A-Za-z0-9_-]");
+  }
+  if (!opts.privateKey || (typeof opts.privateKey !== "string" &&
+      typeof opts.privateKey !== "object")) {
+    throw new DkimError("dkim/missing-private-key",
+      "privateKey is required (PEM string or crypto.KeyObject)");
+  }
+  var algorithm = opts.algorithm || "rsa-sha256";
+  if (ALLOWED_ALGORITHMS.indexOf(algorithm) === -1) {
+    throw new DkimError("dkim/bad-algorithm",
+      "algorithm must be one of: " + ALLOWED_ALGORITHMS.join(", "));
+  }
+  var canonicalization = opts.canonicalization || "relaxed/relaxed";
+  if (ALLOWED_CANON.indexOf(canonicalization) === -1) {
+    throw new DkimError("dkim/bad-canonicalization",
+      "canonicalization must be one of: " + ALLOWED_CANON.join(", "));
+  }
+  var canonHeader = canonicalization.split("/")[0];
+  var canonBody   = canonicalization.split("/")[1];
+
+  var headersToSign = opts.headersToSign || DEFAULT_HEADERS;
+  if (!Array.isArray(headersToSign) || headersToSign.length === 0) {
+    throw new DkimError("dkim/bad-headers",
+      "headersToSign must be a non-empty array of header names");
+  }
+  for (var i = 0; i < headersToSign.length; i++) {
+    if (typeof headersToSign[i] !== "string" || headersToSign[i].length === 0) {
+      throw new DkimError("dkim/bad-headers",
+        "headersToSign[" + i + "] must be a non-empty string");
+    }
+  }
+  if (opts.bodyLength !== undefined &&
+      (typeof opts.bodyLength !== "number" || !isFinite(opts.bodyLength) || opts.bodyLength < 0)) {
+    throw new DkimError("dkim/bad-body-length",
+      "bodyLength must be a non-negative finite number");
+  }
+
+  var auditOn = opts.audit !== false;
+  // Try to parse the private key once at create time so misconfigured
+  // operators see the failure at boot rather than at first send().
+  var keyObject;
+  try {
+    keyObject = typeof opts.privateKey === "string" || Buffer.isBuffer(opts.privateKey)
+      ? nodeCrypto.createPrivateKey({ key: opts.privateKey, format: "pem" })
+      : opts.privateKey;
+  } catch (e) {
+    throw new DkimError("dkim/bad-private-key",
+      "privateKey could not be parsed: " + ((e && e.message) || String(e)));
+  }
+
+  function _emit(action, info) {
+    if (!auditOn) return;
+    audit().safeEmit({
+      action:   action,
+      outcome:  info.outcome || "success",
+      actor:    info.actor || {},
+      metadata: {
+        domain:     opts.domain,
+        selector:   opts.selector,
+        algorithm:  algorithm,
+        bodyLength: info.bodyLength,
+        durationMs: info.durationMs,
+      },
+      reason: info.reason || null,
+    });
+  }
+
+  function sign(rfc822) {
+    if (typeof rfc822 !== "string" || rfc822.length === 0) {
+      throw new DkimError("dkim/bad-input",
+        "sign() requires the rfc822 wire format as a non-empty string");
+    }
+    var t0 = Date.now();
+    var split = _splitHeadersBody(rfc822);
+    var parsedHeaders = _parseHeaders(split.headers);
+
+    // Body hash
+    var body = split.body;
+    if (opts.bodyLength !== undefined) {
+      body = body.slice(0, opts.bodyLength);
+    }
+    var bh = _bodyHashB64(body, algorithm, canonBody);
+
+    // Build the unsigned DKIM-Signature header (b= empty).
+    // Tag order follows RFC 6376 examples: v, a, c, d, s, h, bh, b.
+    var sigTags = [
+      "v=1",
+      "a=" + algorithm,
+      "c=" + canonicalization,
+      "d=" + opts.domain,
+      "s=" + opts.selector,
+      "h=" + headersToSign.join(":"),
+      "bh=" + bh,
+    ];
+    if (opts.bodyLength !== undefined) sigTags.push("l=" + opts.bodyLength);
+    sigTags.push("b=");
+    var unsignedSigValue = sigTags.join("; ");
+
+    // Canonicalize the header set: each header in headersToSign (in
+    // 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.
+    var headerNamesLc = parsedHeaders.map(function (h) { return h.name.toLowerCase(); });
+    var canonicalizedHeaders = "";
+    for (var j = 0; j < headersToSign.length; j++) {
+      var wantLc = headersToSign[j].toLowerCase();
+      var idx = -1;
+      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)
+      var h = parsedHeaders[idx];
+      canonicalizedHeaders += canonHeader === "simple"
+        ? _canonHeaderSimple(h.name, h.value)
+        : _canonHeaderRelaxed(h.name, h.value);
+    }
+    // Append the unsigned DKIM-Signature header without trailing CRLF
+    // per RFC 6376 §3.7.
+    var dkimHeaderForSigning = canonHeader === "simple"
+      ? _canonHeaderSimple("DKIM-Signature", " " + unsignedSigValue)
+      : _canonHeaderRelaxed("DKIM-Signature", unsignedSigValue);
+    canonicalizedHeaders += dkimHeaderForSigning.replace(/\r\n$/, "");
+
+    var signature = _signString(canonicalizedHeaders, keyObject, algorithm);
+    // Replace the empty `b=` placeholder with the actual base64 signature.
+    var finalSigValue = sigTags.slice(0, -1).concat(["b=" + signature]).join("; ");
+
+    var dkimHeaderLine = _foldSignatureHeader(finalSigValue) + "\r\n";
+
+    _emit("dkim.sign.success", {
+      bodyLength: body.length,
+      durationMs: Date.now() - t0,
+    });
+
+    return dkimHeaderLine + rfc822;
+  }
+
+  return {
+    sign: sign,
+    domain:    opts.domain,
+    selector:  opts.selector,
+    algorithm: algorithm,
+  };
+}
+
+// Test-only exports for unit testing the canonicalization primitives
+// directly without going through a full sign() round.
+module.exports = {
+  create:    create,
+  DkimError: DkimError,
+  _canonHeaderRelaxedForTest: _canonHeaderRelaxed,
+  _canonBodyRelaxedForTest:   _canonBodyRelaxed,
+  _canonBodySimpleForTest:    _canonBodySimple,
+};

package/lib/mail.js

@@ -139,9 +139,31 @@ function _validateMessage(message) {
       "message.subject contains forbidden CRLF", true);
   }
 
-  if (!message.text && !message.html) {
+  if (!message.text && !message.html && !message.calendar) {
     throw new MailError("mail/missing-body",
-      "message must include at least one of text or html", true);
+      "message must include at least one of text, html, or calendar", true);
+  }
+
+  if (message.calendar !== undefined) {
+    if (!message.calendar || typeof message.calendar !== "object") {
+      throw new MailError("mail/invalid-calendar",
+        "message.calendar must be an object { method, icalText }", true);
+    }
+    var ALLOWED_METHODS = ["REQUEST", "CANCEL", "REPLY", "PUBLISH", "COUNTER", "REFRESH", "ADD", "DECLINECOUNTER"];
+    if (typeof message.calendar.method !== "string" ||
+        ALLOWED_METHODS.indexOf(message.calendar.method) === -1) {
+      throw new MailError("mail/invalid-calendar",
+        "calendar.method must be one of: " + ALLOWED_METHODS.join(", "), true);
+    }
+    if (typeof message.calendar.icalText !== "string" ||
+        message.calendar.icalText.length === 0) {
+      throw new MailError("mail/invalid-calendar",
+        "calendar.icalText is required (non-empty string)", true);
+    }
+    if (!/^BEGIN:VCALENDAR/.test(message.calendar.icalText)) {
+      throw new MailError("mail/invalid-calendar",
+        "calendar.icalText must start with 'BEGIN:VCALENDAR' (RFC 5545)", true);
+    }
   }
 
   if (message.attachments !== undefined) {
@@ -291,28 +313,38 @@ function _buildAttachmentPart(att) {
 }
 
 function _buildBodyPart(message) {
-  // Text + html → multipart/alternative; otherwise single-part.
-  if (message.text && message.html) {
-    var altBoundary = _newBoundary("alt");
-    return {
-      contentType: 'multipart/alternative; boundary="' + altBoundary + '"',
-      body: [
-        "--" + altBoundary,
-        "Content-Type: text/plain; charset=utf-8",
-        "",
-        message.text,
-        "--" + altBoundary,
-        "Content-Type: text/html; charset=utf-8",
-        "",
-        message.html,
-        "--" + altBoundary + "--",
-      ].join("\r\n"),
-    };
+  // Collect body parts (text / html / calendar). Multiple parts → wrap
+  // in multipart/alternative so the recipient client picks whichever
+  // it can render. Calendar parts carry the `method=` parameter so
+  // mail clients (Outlook / Gmail / Apple Mail) treat the message as
+  // an invite, not a generic ics download.
+  var parts = [];
+  if (message.text) {
+    parts.push({ contentType: "text/plain; charset=utf-8", body: message.text });
   }
   if (message.html) {
-    return { contentType: "text/html; charset=utf-8", body: message.html };
+    parts.push({ contentType: "text/html; charset=utf-8", body: message.html });
+  }
+  if (message.calendar) {
+    parts.push({
+      contentType: 'text/calendar; method="' + message.calendar.method + '"; charset=utf-8',
+      body:        message.calendar.icalText,
+    });
   }
-  return { contentType: "text/plain; charset=utf-8", body: message.text || "" };
+  if (parts.length === 1) return parts[0];
+  var altBoundary = _newBoundary("alt");
+  var lines = [];
+  for (var i = 0; i < parts.length; i++) {
+    lines.push("--" + altBoundary);
+    lines.push("Content-Type: " + parts[i].contentType);
+    lines.push("");
+    lines.push(parts[i].body);
+  }
+  lines.push("--" + altBoundary + "--");
+  return {
+    contentType: 'multipart/alternative; boundary="' + altBoundary + '"',
+    body:        lines.join("\r\n"),
+  };
 }
 
 function _buildRfc822(message) {
@@ -376,6 +408,12 @@ function smtpTransport(opts) {
     throw new MailError("mail/smtp-misconfigured",
       "smtp transport requires opts.host", true);
   }
+  if (opts.dkimSigner !== undefined && opts.dkimSigner !== null &&
+      (typeof opts.dkimSigner !== "object" || typeof opts.dkimSigner.sign !== "function")) {
+    throw new MailError("mail/smtp-misconfigured",
+      "dkimSigner must be an object with a .sign(rfc822) method " +
+      "(see b.mail.dkim.create)", true);
+  }
   var port = opts.port || 587;
   var useImplicitTLS = port === 465 || opts.implicitTls === true;
   var rejectUnauthorized = opts.rejectUnauthorized !== false;
@@ -397,6 +435,7 @@ function smtpTransport(opts) {
     ehloName:       ehloName,
     timeoutMs:      timeoutMs,
     tlsOpts:        tlsOpts,
+    dkimSigner:     opts.dkimSigner || null,
   };
 
   return {
@@ -420,6 +459,13 @@ function _smtpSend(message, cfg) {
     var bccList  = _toArray(message.bcc).map(_extractAddr);
     var rcpts    = toList.concat(ccList, bccList);
     var dataMessage = _buildRfc822(message);
+    if (cfg.dkimSigner) {
+      try { dataMessage = cfg.dkimSigner.sign(dataMessage); }
+      catch (e) {
+        return reject(new MailError("mail/dkim-sign-failed",
+          "dkim signing failed: " + ((e && e.message) || String(e)), true));
+      }
+    }
 
     function fail(reason) {
       if (settled) return;
@@ -828,6 +874,10 @@ function create(opts) {
 module.exports = {
   create:     create,
   MailError:  MailError,
+  // DKIM-Signature header generation for outbound mail (rsa-sha256
+  // default, ed25519-sha256 opt-in). Wire it into the smtp transport
+  // via opts.dkimSigner. See lib/mail-dkim.js for the full surface.
+  dkim:       require("./mail-dkim"),
   // Test-only export: lets unit tests inspect the wire format without
   // standing up a TLS-capable SMTP fixture. Operators don't call this.
   _buildRfc822ForTest: _buildRfc822,

package/lib/object-store/sigv4.js

@@ -208,6 +208,135 @@ function _request(method, url, headers, body, opts) {
   });
 }
 
+// ---- Multipart-upload constants ----
+
+// S3 spec floor for non-final part size. Below this the API rejects
+// CompleteMultipartUpload with EntityTooSmall. The framework refuses
+// configurations below this floor at create() time so operators don't
+// see surprising failures only on large uploads.
+var MIN_PART_SIZE_BYTES = 5 * 1024 * 1024;
+// S3 spec ceiling on part count. CompleteMultipartUpload rejects
+// uploads with more than 10000 parts.
+var MAX_PARTS = 10000;
+// Auto-multipart trigger: buffered bodies under this stay single-PUT.
+// Streams always go multipart since size isn't known up-front.
+var DEFAULT_MULTIPART_THRESHOLD_BYTES = 64 * 1024 * 1024;
+// Conservative default part size — large enough to keep round-trip
+// overhead small relative to payload, small enough to fit comfortably
+// in a 4-way-concurrent upload's memory footprint.
+var DEFAULT_PART_SIZE_BYTES = 16 * 1024 * 1024;
+var DEFAULT_PART_CONCURRENCY = 4;
+
+// ---- SSE option handling ----
+
+function _resolveSseHeaders(sse) {
+  if (sse === undefined || sse === null) return null;
+  var type;
+  var keyId = null;
+  if (typeof sse === "string") {
+    type = sse;
+  } else if (sse && typeof sse === "object") {
+    type = sse.type;
+    keyId = sse.keyId || null;
+  } else {
+    throw _err("INVALID_SSE",
+      "opts.sse must be a string ('AES256' | 'aws:kms') or " +
+      "{ type, keyId }, got " + typeof sse, true);
+  }
+  if (type !== "AES256" && type !== "aws:kms") {
+    throw _err("INVALID_SSE",
+      "opts.sse type must be 'AES256' or 'aws:kms', got '" + type + "'", true);
+  }
+  var h = { "x-amz-server-side-encryption": type };
+  if (type === "aws:kms" && keyId) {
+    h["x-amz-server-side-encryption-aws-kms-key-id"] = String(keyId);
+  }
+  return { type: type, keyId: keyId, headers: h };
+}
+
+function _verifySseResponse(sseRequested, resHeaders) {
+  // Operators who specified an SSE policy expect the bucket / object to
+  // honor it. If the server silently dropped the header (mis-configured
+  // bucket policy, unsupported endpoint, etc.) the request looks like a
+  // success but the at-rest data is unencrypted. Surface this as a
+  // hard failure rather than a silent compliance hole.
+  if (!sseRequested) return;
+  var got = resHeaders["x-amz-server-side-encryption"];
+  if (!got) {
+    throw _err("SSE_NOT_APPLIED",
+      "opts.sse was '" + sseRequested.type + "' but server did not " +
+      "apply server-side encryption (no x-amz-server-side-encryption " +
+      "response header)", true);
+  }
+  if (got !== sseRequested.type) {
+    throw _err("SSE_MISMATCH",
+      "opts.sse requested '" + sseRequested.type + "' but server " +
+      "applied '" + got + "'", true);
+  }
+}
+
+// ---- Multipart helpers ----
+
+// Build the CompleteMultipartUpload request body. Parts must be in
+// ascending PartNumber order. ETags from S3 include surrounding
+// quotes — preserve them exactly.
+function _buildCompleteMultipartXml(parts) {
+  var body = "<CompleteMultipartUpload>";
+  for (var i = 0; i < parts.length; i++) {
+    body += "<Part>";
+    body += "<PartNumber>" + parts[i].partNumber + "</PartNumber>";
+    body += "<ETag>" + parts[i].etag + "</ETag>";
+    body += "</Part>";
+  }
+  body += "</CompleteMultipartUpload>";
+  return body;
+}
+
+// Read a Readable stream into fixed-size buffers. Yields one Buffer
+// per part (size <= partSize). The final part may be smaller. The
+// stream is consumed exactly once.
+async function _readStreamParts(readable, partSize) {
+  var parts = [];
+  var pending = [];
+  var pendingBytes = 0;
+  for await (var chunk of readable) {
+    var buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    pending.push(buf);
+    pendingBytes += buf.length;
+    while (pendingBytes >= partSize) {
+      var combined = Buffer.concat(pending, pendingBytes);
+      parts.push(combined.slice(0, partSize));
+      var leftover = combined.slice(partSize);
+      pending = leftover.length > 0 ? [leftover] : [];
+      pendingBytes = leftover.length;
+    }
+  }
+  if (pendingBytes > 0) {
+    parts.push(Buffer.concat(pending, pendingBytes));
+  }
+  return parts;
+}
+
+// Run an array of async tasks with bounded parallelism. Preserves
+// result order by index.
+async function _bounded(items, concurrency, runner) {
+  var results = new Array(items.length);
+  var i = 0;
+  async function worker() {
+    while (true) {
+      var idx = i++;
+      if (idx >= items.length) return;
+      results[idx] = await runner(items[idx], idx);
+    }
+  }
+  var workers = [];
+  for (var w = 0; w < Math.min(concurrency, items.length); w++) {
+    workers.push(worker());
+  }
+  await Promise.all(workers);
+  return results;
+}
+
 // ---- Public adapter factory ----
 
 function create(config) {
@@ -220,6 +349,30 @@ function create(config) {
   var endpoint = config.endpoint || ("https://s3." + config.region + ".amazonaws.com");
   if (endpoint.endsWith("/")) endpoint = endpoint.slice(0, -1);
   var pathStyle = !!(config.pathStyle || config.forcePathStyle);
+
+  var partSize = config.partSizeBytes != null
+    ? config.partSizeBytes
+    : DEFAULT_PART_SIZE_BYTES;
+  if (typeof partSize !== "number" || !isFinite(partSize) || partSize < MIN_PART_SIZE_BYTES) {
+    throw _err("INVALID_CONFIG",
+      "sigv4: partSizeBytes must be a number >= " + MIN_PART_SIZE_BYTES +
+      " (S3 minimum part size), got " + partSize, true);
+  }
+  var multipartThreshold = config.multipartThresholdBytes != null
+    ? config.multipartThresholdBytes
+    : DEFAULT_MULTIPART_THRESHOLD_BYTES;
+  if (typeof multipartThreshold !== "number" || !isFinite(multipartThreshold) || multipartThreshold < 0) {
+    throw _err("INVALID_CONFIG",
+      "sigv4: multipartThresholdBytes must be a non-negative finite number, got " +
+      multipartThreshold, true);
+  }
+  var partConcurrency = config.partConcurrency != null
+    ? config.partConcurrency
+    : DEFAULT_PART_CONCURRENCY;
+  if (typeof partConcurrency !== "number" || partConcurrency < 1 || !isFinite(partConcurrency)) {
+    throw _err("INVALID_CONFIG",
+      "sigv4: partConcurrency must be a positive finite number, got " + partConcurrency, true);
+  }
   // HTTPS-only by default — AWS S3, R2, MinIO-over-https. Operators with
   // an internal cleartext S3-compatible endpoint (test fixtures, local
   // dev MinIO) opt in via config.allowedProtocols.
@@ -274,19 +427,150 @@ function create(config) {
   }
 
   function put(key, body, opts) {
-    var url = _keyToUrl(key);
+    opts = opts || {};
+    var sseRequested = _resolveSseHeaders(opts.sse);
+    // Streams always go multipart — size isn't known up-front. Buffers
+    // dispatch to multipart when they exceed the threshold; operators
+    // can force the single-PUT path with `multipart: false` (small
+    // bodies in unit tests, or to keep the request count to one).
+    var isStream = body && typeof body === "object" && typeof body.pipe === "function";
+    if (isStream) {
+      if (opts.multipart === false) {
+        return Promise.reject(_err("STREAM_REQUIRES_MULTIPART",
+          "put(stream) requires multipart upload (set opts.multipart !== false)", true));
+      }
+      return _multipartPut(key, body, opts, sseRequested);
+    }
     var buf = Buffer.isBuffer(body) ? body : Buffer.from(typeof body === "string" ? body : "", "utf8");
+    if (opts.multipart !== false &&
+        (opts.multipart === true || buf.length > multipartThreshold)) {
+      return _multipartPut(key, buf, opts, sseRequested);
+    }
+    return _singlePut(key, buf, opts, sseRequested);
+  }
+
+  function _singlePut(key, buf, opts, sseRequested) {
+    var url = _keyToUrl(key);
     var payloadHash = sha256Hex(buf);
-    var contentType = (opts && opts.contentType) || "application/octet-stream";
-    var headers = _makeSigned("PUT", url, payloadHash, {
+    var contentType = opts.contentType || "application/octet-stream";
+    var extra = {
       "Content-Type":   contentType,
       "Content-Length": String(buf.length),
-    });
+    };
+    if (sseRequested) Object.assign(extra, sseRequested.headers);
+    var headers = _makeSigned("PUT", url, payloadHash, extra);
     return _request("PUT", url, headers, buf, reqOpts).then(function (res) {
+      _verifySseResponse(sseRequested, res.headers);
       return { size: buf.length, etag: res.headers.etag };
     });
   }
 
+  async function _multipartPut(key, body, opts, sseRequested) {
+    var contentType = opts.contentType || "application/octet-stream";
+
+    // Slice into parts. For Buffers we slice up-front; for streams we
+    // read sequentially into part-sized buffers (memory bounded).
+    var parts;
+    if (Buffer.isBuffer(body)) {
+      parts = [];
+      for (var off = 0; off < body.length; off += partSize) {
+        parts.push(body.slice(off, Math.min(off + partSize, body.length)));
+      }
+      // Edge case: empty buffer → one zero-length part. S3 rejects
+      // multipart with zero parts; rather than handling this corner
+      // we route empty buffers through single-PUT instead.
+      if (parts.length === 0) parts = [Buffer.alloc(0)];
+    } else {
+      parts = await _readStreamParts(body, partSize);
+      if (parts.length === 0) parts = [Buffer.alloc(0)];
+    }
+    if (parts.length > MAX_PARTS) {
+      throw _err("TOO_MANY_PARTS",
+        "multipart upload would require " + parts.length + " parts " +
+        "(S3 max " + MAX_PARTS + "); increase partSizeBytes", true);
+    }
+
+    // 1. Initiate
+    var url = _keyToUrl(key);
+    var initiateUrl = new URL(url.href);
+    initiateUrl.searchParams.set("uploads", "");
+    var initiateExtra = {
+      "Content-Type":   contentType,
+      "Content-Length": "0",
+    };
+    if (sseRequested) Object.assign(initiateExtra, sseRequested.headers);
+    var initiateHeaders = _makeSigned("POST", initiateUrl, sha256Hex(Buffer.alloc(0)), initiateExtra);
+    var initRes = await _request("POST", initiateUrl, initiateHeaders, Buffer.alloc(0), reqOpts);
+    _verifySseResponse(sseRequested, initRes.headers);
+    var initDoc = safeXml.parse(initRes.body, LIST_PARSE_OPTS);
+    var uploadId = initDoc.InitiateMultipartUploadResult &&
+      initDoc.InitiateMultipartUploadResult.UploadId;
+    if (!uploadId) {
+      throw _err("MULTIPART_INIT_FAILED",
+        "S3 InitiateMultipartUpload response missing UploadId", false);
+    }
+
+    var totalSize = 0;
+    var uploadedEtags;
+
+    try {
+      // 2. Upload parts (concurrency-bounded)
+      uploadedEtags = await _bounded(parts, partConcurrency, async function (partBuf, idx) {
+        var partNumber = idx + 1;
+        var partUrl = new URL(url.href);
+        partUrl.searchParams.set("partNumber", String(partNumber));
+        partUrl.searchParams.set("uploadId", uploadId);
+        var partHeaders = _makeSigned("PUT", partUrl, sha256Hex(partBuf), {
+          "Content-Length": String(partBuf.length),
+        });
+        var partRes = await _request("PUT", partUrl, partHeaders, partBuf, reqOpts);
+        if (!partRes.headers.etag) {
+          throw _err("MULTIPART_PART_FAILED",
+            "UploadPart response missing ETag for part " + partNumber, false);
+        }
+        totalSize += partBuf.length;
+        return { partNumber: partNumber, etag: partRes.headers.etag };
+      });
+
+      // 3. Complete
+      var completeUrl = new URL(url.href);
+      completeUrl.searchParams.set("uploadId", uploadId);
+      var completeBody = Buffer.from(_buildCompleteMultipartXml(uploadedEtags), "utf8");
+      var completeHeaders = _makeSigned("POST", completeUrl, sha256Hex(completeBody), {
+        "Content-Type":   "application/xml",
+        "Content-Length": String(completeBody.length),
+      });
+      var completeRes = await _request("POST", completeUrl, completeHeaders, completeBody, reqOpts);
+      // S3 may return 200 OK with an error body on CompleteMultipartUpload —
+      // surface that as a hard error rather than a silent success.
+      var completeDoc = safeXml.parse(completeRes.body, LIST_PARSE_OPTS);
+      if (completeDoc.Error) {
+        throw _err("MULTIPART_COMPLETE_FAILED",
+          "CompleteMultipartUpload returned error: " +
+          (completeDoc.Error.Code || "unknown") + " " +
+          (completeDoc.Error.Message || ""), false);
+      }
+      // SSE was already verified on the InitiateMultipartUpload
+      // response — that's the request that establishes the upload's
+      // encryption policy server-side. The CompleteMultipartUpload
+      // response may or may not echo the header depending on vendor;
+      // re-verifying here would double-fault on otherwise-fine setups.
+      var result = completeDoc.CompleteMultipartUploadResult || {};
+      return { size: totalSize, etag: result.ETag || completeRes.headers.etag, multipart: true };
+    } catch (e) {
+      // Abort cleans up server-side storage for the partial upload.
+      // Failures here are silently swallowed — the caller's original
+      // error is what they need to see, not a secondary cleanup error.
+      try {
+        var abortUrl = new URL(url.href);
+        abortUrl.searchParams.set("uploadId", uploadId);
+        var abortHeaders = _makeSigned("DELETE", abortUrl, sha256Hex(Buffer.alloc(0)));
+        await _request("DELETE", abortUrl, abortHeaders, null, reqOpts);
+      } catch (_e) { /* primary error wins */ }
+      throw e;
+    }
+  }
+
   function get(key) {
     var url = _keyToUrl(key);
     var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",