@blamejs/core 0.4.23 → 0.4.25

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- **0.4.24** (2026-04-30) — b.objectStore: multipart upload + server-side encryption
+- **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

package/lib/object-store/index.js

@@ -30,6 +30,7 @@
 var localProto      = require("./local");
 var httpPutProto    = require("./http-put");
 var sigv4Proto      = require("./sigv4");
+var sigv4BucketOps  = require("./sigv4-bucket-ops");
 var gcsProto        = require("./gcs");
 var azureBlobProto  = require("./azure-blob");
 var retryHelper     = require("./retry");
@@ -137,4 +138,9 @@ module.exports = {
   buildBackend:        buildBackend,
   PROTOCOLS:           dispatcher.protocols,
   DEFERRED_PROTOCOLS:  dispatcher.deferred,
+  // Bucket-level (lifecycle / CORS / create / delete / list) ops are
+  // service-scoped, not bucket-scoped — they get their own factory.
+  // SigV4 only; GCS / Azure bucket lifecycle differs substantially per
+  // cloud and is operator-managed (Terraform / CDK / Pulumi).
+  bucketOps:           sigv4BucketOps,
 };

package/lib/object-store/sigv4-bucket-ops.js

@@ -0,0 +1,491 @@
+"use strict";
+/**
+ * sigv4-bucket-ops — bucket-level operations for SigV4 backends.
+ *
+ * Per-object ops (put / get / list / delete / multipart) live in
+ * lib/object-store/sigv4.js and are bound to a single bucket at
+ * create() time. Bucket lifecycle ops are at a different level —
+ * they need a service-scoped client that addresses arbitrary
+ * buckets — so they get their own factory.
+ *
+ * Operators with multi-cloud ambitions reach for Terraform / CDK /
+ * Pulumi. The framework's bucket-ops surface is the operator-from-app
+ * path: create the bucket your app needs at boot, attach a lifecycle
+ * rule that aborts incomplete multiparts after a week, etc. Niche ops
+ * (Object Lock, Replication, Inventory, Notification) are deferred —
+ * they're well into Terraform territory.
+ *
+ * Public API:
+ *
+ *   var ops = b.objectStore.bucketOps.create({
+ *     protocol:        "sigv4",
+ *     region:          "us-east-1",
+ *     accessKeyId:     env("AWS_ACCESS_KEY_ID"),
+ *     secretAccessKey: env("AWS_SECRET_ACCESS_KEY"),
+ *     endpoint:        "https://s3.us-east-1.amazonaws.com",  // optional
+ *     pathStyle:       false,
+ *     timeoutMs:       30000,
+ *   });
+ *
+ *   await ops.create("my-bucket", { region: "eu-west-1" });
+ *   await ops.delete("my-bucket");
+ *   var buckets = await ops.list();          // [{ name, creationDate }]
+ *   await ops.setLifecycle("my-bucket", [{
+ *     id:     "abort-stale-multiparts",
+ *     status: "Enabled",
+ *     prefix: "",
+ *     abortIncompleteMultipartUpload: { daysAfterInitiation: 7 },
+ *   }]);
+ *   await ops.setCorsRules("my-bucket", [{
+ *     allowedOrigins: ["https://app.example.com"],
+ *     allowedMethods: ["GET", "PUT", "POST"],
+ *     allowedHeaders: ["*"],
+ *     exposeHeaders:  ["ETag"],
+ *     maxAgeSeconds:  3600,
+ *   }]);
+ *
+ * Validation is Tier-A: every input shape is rejected at the call
+ * site rather than producing a server-side 400. Errors surface as
+ * ObjectStoreError with codes (BUCKET_INVALID_NAME, INVALID_LIFECYCLE,
+ * INVALID_CORS_RULE, BUCKET_ALREADY_OWNED, BUCKET_NOT_EMPTY, etc.).
+ */
+var { URL } = require("url");
+var nodeCrypto = require("crypto");
+var sigv4 = require("./sigv4");
+var safeXml = require("../parsers/safe-xml");
+var safeUrl = require("../safe-url");
+var httpClient = require("../http-client");
+var { ObjectStoreError } = require("../framework-error");
+
+var _err = ObjectStoreError.factory;
+
+// S3 bucket-name rules (general purpose). Source: AWS docs
+// "Bucket naming rules". Lowercase letters, digits, hyphens; 3..63
+// chars; no consecutive dots; cannot end in -s3alias / -ol-s3 etc.
+// We catch the common-mistake cases at config time; AWS catches the
+// rest at request time.
+var BUCKET_NAME_RE = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+
+function _validateBucketName(name) {
+  if (typeof name !== "string" || name.length < 3 || name.length > 63) {
+    throw _err("BUCKET_INVALID_NAME",
+      "bucket name must be a string of length 3..63, got " +
+      (typeof name === "string" ? "length " + name.length : typeof name), true);
+  }
+  if (!BUCKET_NAME_RE.test(name)) {
+    throw _err("BUCKET_INVALID_NAME",
+      "bucket name '" + name + "' violates S3 naming rules " +
+      "(lowercase, digits, hyphens, dots — no leading/trailing punct)", true);
+  }
+  if (name.indexOf("..") !== -1) {
+    throw _err("BUCKET_INVALID_NAME",
+      "bucket name '" + name + "' contains consecutive dots", true);
+  }
+}
+
+function _xmlEscape(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function _md5Base64(buf) {
+  return nodeCrypto.createHash("md5").update(buf).digest("base64");
+}
+
+// ---- Lifecycle XML ----
+
+var ALLOWED_STORAGE_CLASSES = [
+  "STANDARD", "REDUCED_REDUNDANCY", "STANDARD_IA", "ONEZONE_IA",
+  "INTELLIGENT_TIERING", "GLACIER", "DEEP_ARCHIVE", "GLACIER_IR",
+  "EXPRESS_ONEZONE",
+];
+
+function _buildLifecycleXml(rules) {
+  if (!Array.isArray(rules) || rules.length === 0) {
+    throw _err("INVALID_LIFECYCLE",
+      "setLifecycle: rules must be a non-empty array", true);
+  }
+  if (rules.length > 1000) {
+    throw _err("INVALID_LIFECYCLE",
+      "setLifecycle: maximum 1000 rules per bucket (S3 spec)", true);
+  }
+  var body = '<?xml version="1.0" encoding="UTF-8"?>';
+  body += '<LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">';
+  for (var i = 0; i < rules.length; i++) {
+    var rule = rules[i];
+    if (!rule || typeof rule !== "object") {
+      throw _err("INVALID_LIFECYCLE",
+        "rules[" + i + "] must be an object", true);
+    }
+    var status = rule.status || "Enabled";
+    if (status !== "Enabled" && status !== "Disabled") {
+      throw _err("INVALID_LIFECYCLE",
+        "rules[" + i + "].status must be 'Enabled' or 'Disabled'", true);
+    }
+    if (!rule.expiration && !rule.transition && !rule.abortIncompleteMultipartUpload) {
+      throw _err("INVALID_LIFECYCLE",
+        "rules[" + i + "] must specify at least one of " +
+        "expiration / transition / abortIncompleteMultipartUpload", true);
+    }
+    body += "<Rule>";
+    if (rule.id !== undefined) {
+      if (typeof rule.id !== "string" || rule.id.length === 0) {
+        throw _err("INVALID_LIFECYCLE",
+          "rules[" + i + "].id must be a non-empty string when set", true);
+      }
+      body += "<ID>" + _xmlEscape(rule.id) + "</ID>";
+    }
+    body += "<Filter><Prefix>" + _xmlEscape(rule.prefix || "") + "</Prefix></Filter>";
+    body += "<Status>" + status + "</Status>";
+    if (rule.expiration) {
+      body += "<Expiration>";
+      if (rule.expiration.days !== undefined) {
+        if (typeof rule.expiration.days !== "number" || rule.expiration.days < 1) {
+          throw _err("INVALID_LIFECYCLE",
+            "rules[" + i + "].expiration.days must be a positive integer", true);
+        }
+        body += "<Days>" + rule.expiration.days + "</Days>";
+      }
+      if (rule.expiration.date !== undefined) {
+        body += "<Date>" + _xmlEscape(rule.expiration.date) + "</Date>";
+      }
+      if (rule.expiration.expiredObjectDeleteMarker !== undefined) {
+        body += "<ExpiredObjectDeleteMarker>" +
+          (rule.expiration.expiredObjectDeleteMarker ? "true" : "false") +
+          "</ExpiredObjectDeleteMarker>";
+      }
+      body += "</Expiration>";
+    }
+    if (rule.transition) {
+      if (ALLOWED_STORAGE_CLASSES.indexOf(rule.transition.storageClass) === -1) {
+        throw _err("INVALID_LIFECYCLE",
+          "rules[" + i + "].transition.storageClass must be one of: " +
+          ALLOWED_STORAGE_CLASSES.join(", "), true);
+      }
+      body += "<Transition>";
+      if (rule.transition.days !== undefined) {
+        body += "<Days>" + rule.transition.days + "</Days>";
+      }
+      if (rule.transition.date !== undefined) {
+        body += "<Date>" + _xmlEscape(rule.transition.date) + "</Date>";
+      }
+      body += "<StorageClass>" + rule.transition.storageClass + "</StorageClass>";
+      body += "</Transition>";
+    }
+    if (rule.abortIncompleteMultipartUpload) {
+      var dai = rule.abortIncompleteMultipartUpload.daysAfterInitiation;
+      if (typeof dai !== "number" || dai < 1) {
+        throw _err("INVALID_LIFECYCLE",
+          "rules[" + i + "].abortIncompleteMultipartUpload.daysAfterInitiation " +
+          "must be a positive integer", true);
+      }
+      body += "<AbortIncompleteMultipartUpload>";
+      body += "<DaysAfterInitiation>" + dai + "</DaysAfterInitiation>";
+      body += "</AbortIncompleteMultipartUpload>";
+    }
+    body += "</Rule>";
+  }
+  body += "</LifecycleConfiguration>";
+  return body;
+}
+
+// ---- CORS XML ----
+
+var ALLOWED_CORS_METHODS = ["GET", "PUT", "POST", "DELETE", "HEAD"];
+
+function _buildCorsXml(rules) {
+  if (!Array.isArray(rules) || rules.length === 0) {
+    throw _err("INVALID_CORS_RULE",
+      "setCorsRules: rules must be a non-empty array", true);
+  }
+  if (rules.length > 100) {
+    throw _err("INVALID_CORS_RULE",
+      "setCorsRules: maximum 100 rules per bucket (S3 spec)", true);
+  }
+  var body = '<?xml version="1.0" encoding="UTF-8"?>';
+  body += '<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">';
+  for (var i = 0; i < rules.length; i++) {
+    var rule = rules[i];
+    if (!rule || typeof rule !== "object") {
+      throw _err("INVALID_CORS_RULE",
+        "rules[" + i + "] must be an object", true);
+    }
+    if (!Array.isArray(rule.allowedOrigins) || rule.allowedOrigins.length === 0) {
+      throw _err("INVALID_CORS_RULE",
+        "rules[" + i + "].allowedOrigins must be a non-empty array", true);
+    }
+    if (!Array.isArray(rule.allowedMethods) || rule.allowedMethods.length === 0) {
+      throw _err("INVALID_CORS_RULE",
+        "rules[" + i + "].allowedMethods must be a non-empty array", true);
+    }
+    for (var m = 0; m < rule.allowedMethods.length; m++) {
+      if (ALLOWED_CORS_METHODS.indexOf(rule.allowedMethods[m]) === -1) {
+        throw _err("INVALID_CORS_RULE",
+          "rules[" + i + "].allowedMethods[" + m + "] must be one of: " +
+          ALLOWED_CORS_METHODS.join(", "), true);
+      }
+    }
+    body += "<CORSRule>";
+    if (rule.id !== undefined) body += "<ID>" + _xmlEscape(rule.id) + "</ID>";
+    rule.allowedOrigins.forEach(function (o) {
+      body += "<AllowedOrigin>" + _xmlEscape(o) + "</AllowedOrigin>";
+    });
+    rule.allowedMethods.forEach(function (m) {
+      body += "<AllowedMethod>" + _xmlEscape(m) + "</AllowedMethod>";
+    });
+    if (Array.isArray(rule.allowedHeaders)) {
+      rule.allowedHeaders.forEach(function (h) {
+        body += "<AllowedHeader>" + _xmlEscape(h) + "</AllowedHeader>";
+      });
+    }
+    if (Array.isArray(rule.exposeHeaders)) {
+      rule.exposeHeaders.forEach(function (h) {
+        body += "<ExposeHeader>" + _xmlEscape(h) + "</ExposeHeader>";
+      });
+    }
+    if (rule.maxAgeSeconds !== undefined) {
+      if (typeof rule.maxAgeSeconds !== "number" || rule.maxAgeSeconds < 0) {
+        throw _err("INVALID_CORS_RULE",
+          "rules[" + i + "].maxAgeSeconds must be a non-negative number", true);
+      }
+      body += "<MaxAgeSeconds>" + rule.maxAgeSeconds + "</MaxAgeSeconds>";
+    }
+    body += "</CORSRule>";
+  }
+  body += "</CORSConfiguration>";
+  if (Buffer.byteLength(body, "utf8") > 64 * 1024) {
+    throw _err("INVALID_CORS_RULE",
+      "CORS configuration exceeds 64 KB (S3 spec)", true);
+  }
+  return body;
+}
+
+// ---- Public factory ----
+
+function create(config) {
+  if (!config || typeof config !== "object") {
+    throw _err("INVALID_CONFIG", "bucketOps.create requires a config object", true);
+  }
+  if (config.protocol && config.protocol !== "sigv4") {
+    throw _err("INVALID_CONFIG",
+      "bucketOps currently only supports protocol 'sigv4'; got '" +
+      config.protocol + "'. GCS and Azure bucket lifecycle differs " +
+      "substantially per cloud and is operator-managed (Terraform / " +
+      "CDK / Pulumi).", true);
+  }
+  if (!config.region) throw _err("INVALID_CONFIG", "bucketOps: region is required", true);
+  if (!config.accessKeyId) throw _err("INVALID_CONFIG", "bucketOps: accessKeyId is required", true);
+  if (!config.secretAccessKey) throw _err("INVALID_CONFIG", "bucketOps: secretAccessKey is required", true);
+
+  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 allowedProtocols = config.allowedProtocols || safeUrl.ALLOW_HTTP_TLS;
+  var allowInternal    = config.allowInternal != null ? config.allowInternal : null;
+  safeUrl.parse(endpoint, {
+    allowedProtocols: allowedProtocols,
+    errorClass:       ObjectStoreError,
+  });
+  var reqOpts = { timeoutMs: config.timeoutMs, allowedProtocols: allowedProtocols };
+  if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
+
+  function _bucketUrl(name, query) {
+    var u;
+    if (pathStyle) {
+      u = new URL(endpoint + "/" + name + "/");
+    } else {
+      u = new URL(endpoint);
+      u.hostname = name + "." + u.hostname;
+      u.pathname = "/";
+    }
+    if (query) {
+      Object.keys(query).forEach(function (k) {
+        u.searchParams.set(k, query[k] != null ? query[k] : "");
+      });
+    }
+    return u;
+  }
+
+  function _serviceUrl(query) {
+    // ListBuckets — service-level, no bucket prefix.
+    var u = new URL(endpoint);
+    u.pathname = "/";
+    if (query) {
+      Object.keys(query).forEach(function (k) { u.searchParams.set(k, query[k]); });
+    }
+    return u;
+  }
+
+  function _signed(method, url, payloadHash, extraHeaders) {
+    var signed = sigv4.signRequest({
+      method:          method,
+      url:             url,
+      headers:         extraHeaders || {},
+      payloadHash:     payloadHash,
+      region:          config.region,
+      accessKeyId:     config.accessKeyId,
+      secretAccessKey: config.secretAccessKey,
+      sessionToken:    config.sessionToken,
+    });
+    return signed.headers;
+  }
+
+  function _request(method, url, headers, body) {
+    return httpClient.request({
+      method:           method,
+      url:              url,
+      headers:          headers,
+      body:             body,
+      idleTimeoutMs:    reqOpts.timeoutMs,
+      errorClass:       ObjectStoreError,
+      allowedProtocols: reqOpts.allowedProtocols,
+    ...((reqOpts.allowInternal !== undefined) ? { allowInternal: reqOpts.allowInternal } : {}),
+    });
+  }
+
+  // ---- create ----
+
+  function createBucket(name, opts) {
+    _validateBucketName(name);
+    opts = opts || {};
+    var targetRegion = opts.region || config.region;
+    var url = _bucketUrl(name);
+    var bodyBuf;
+    var extra = {};
+    // us-east-1 takes an empty body. Other regions need
+    // CreateBucketConfiguration with a LocationConstraint.
+    if (targetRegion && targetRegion !== "us-east-1") {
+      bodyBuf = Buffer.from(
+        '<?xml version="1.0" encoding="UTF-8"?>' +
+        '<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">' +
+        '<LocationConstraint>' + _xmlEscape(targetRegion) + '</LocationConstraint>' +
+        '</CreateBucketConfiguration>',
+        "utf8"
+      );
+      extra["Content-Type"] = "application/xml";
+      extra["Content-Length"] = String(bodyBuf.length);
+    } else {
+      bodyBuf = Buffer.alloc(0);
+      extra["Content-Length"] = "0";
+    }
+    var payloadHash = sigv4.sha256Hex(bodyBuf);
+    var headers = _signed("PUT", url, payloadHash, extra);
+    return _request("PUT", url, headers, bodyBuf).then(
+      function () { return { created: true, name: name, region: targetRegion }; },
+      function (e) {
+        // Map S3 conflict response codes into stable framework codes.
+        if (e.statusCode === 409 && /BucketAlreadyOwnedByYou/.test(e.message || "")) {
+          throw _err("BUCKET_ALREADY_OWNED",
+            "bucket '" + name + "' already exists and is owned by this account", true);
+        }
+        if (e.statusCode === 409) {
+          throw _err("BUCKET_NAME_TAKEN",
+            "bucket name '" + name + "' is taken in S3's global namespace", true);
+        }
+        throw e;
+      }
+    );
+  }
+
+  // ---- delete ----
+
+  function deleteBucket(name) {
+    _validateBucketName(name);
+    var url = _bucketUrl(name);
+    var payloadHash = sigv4.sha256Hex(Buffer.alloc(0));
+    var headers = _signed("DELETE", url, payloadHash);
+    return _request("DELETE", url, headers, null).then(
+      function () { return true; },
+      function (e) {
+        if (e.statusCode === 404) return false;
+        if (e.statusCode === 409 && /BucketNotEmpty/.test(e.message || "")) {
+          throw _err("BUCKET_NOT_EMPTY",
+            "bucket '" + name + "' is not empty; delete all objects + " +
+            "noncurrent versions + delete-markers first", true);
+        }
+        throw e;
+      }
+    );
+  }
+
+  // ---- list ----
+
+  function listBuckets() {
+    var url = _serviceUrl();
+    var payloadHash = sigv4.sha256Hex(Buffer.alloc(0));
+    var headers = _signed("GET", url, payloadHash);
+    return _request("GET", url, headers, null).then(function (res) {
+      var doc = safeXml.parse(res.body);
+      var result = doc.ListAllMyBucketsResult || {};
+      var bucketsContainer = result.Buckets || {};
+      var raw = bucketsContainer.Bucket;
+      if (!raw) return [];
+      var arr = Array.isArray(raw) ? raw : [raw];
+      return arr.map(function (b) {
+        return {
+          name:         b.Name,
+          creationDate: b.CreationDate ? Date.parse(b.CreationDate) : null,
+          region:       b.BucketRegion || null,
+        };
+      });
+    });
+  }
+
+  // ---- setLifecycle ----
+
+  function setLifecycle(name, rules) {
+    _validateBucketName(name);
+    var bodyXml = _buildLifecycleXml(rules);
+    var bodyBuf = Buffer.from(bodyXml, "utf8");
+    var url = _bucketUrl(name, { lifecycle: "" });
+    var payloadHash = sigv4.sha256Hex(bodyBuf);
+    var headers = _signed("PUT", url, payloadHash, {
+      "Content-Type":   "application/xml",
+      "Content-Length": String(bodyBuf.length),
+      "Content-MD5":    _md5Base64(bodyBuf),
+    });
+    return _request("PUT", url, headers, bodyBuf).then(function () {
+      return { applied: true, name: name, ruleCount: rules.length };
+    });
+  }
+
+  // ---- setCorsRules ----
+
+  function setCorsRules(name, rules) {
+    _validateBucketName(name);
+    var bodyXml = _buildCorsXml(rules);
+    var bodyBuf = Buffer.from(bodyXml, "utf8");
+    var url = _bucketUrl(name, { cors: "" });
+    var payloadHash = sigv4.sha256Hex(bodyBuf);
+    var headers = _signed("PUT", url, payloadHash, {
+      "Content-Type":   "application/xml",
+      "Content-Length": String(bodyBuf.length),
+      "Content-MD5":    _md5Base64(bodyBuf),
+    });
+    return _request("PUT", url, headers, bodyBuf).then(function () {
+      return { applied: true, name: name, ruleCount: rules.length };
+    });
+  }
+
+  return {
+    protocol:      "sigv4",
+    create:        createBucket,
+    delete:        deleteBucket,
+    list:          listBuckets,
+    setLifecycle:  setLifecycle,
+    setCorsRules:  setCorsRules,
+  };
+}
+
+module.exports = {
+  create: create,
+  // Test-only exports for unit-testing the XML builders without
+  // standing up a fake S3 server.
+  _buildLifecycleXmlForTest: _buildLifecycleXml,
+  _buildCorsXmlForTest:      _buildCorsXml,
+  _validateBucketNameForTest: _validateBucketName,
+};

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.23",
+  "version": "0.4.25",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",