@blamejs/core 0.6.37 → 0.6.58

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

@@ -52,11 +52,13 @@
 var { URL } = require("url");
 var nodeCrypto = require("crypto");
 var C = require("../constants");
+var requestHelpers = require("../request-helpers");
 var sigv4 = require("./sigv4");
 var safeXml = require("../parsers/safe-xml");
 var safeUrl = require("../safe-url");
 var template = require("../template");
 var httpClient = require("../http-client");
+var validateOpts = require("../validate-opts");
 var { ObjectStoreError } = require("../framework-error");
 
 var _err = ObjectStoreError.factory;
@@ -269,12 +271,141 @@ function _buildCorsXml(rules) {
   return body;
 }
 
+// ---- Object Lock + Retention + LegalHold validators / XML ----
+
+var OBJECT_LOCK_MODES = ["GOVERNANCE", "COMPLIANCE"];
+var LEGAL_HOLD_STATES = ["ON", "OFF"];
+
+function _validateObjectLockConfig(cfg) {
+  if (!cfg || typeof cfg !== "object") {
+    throw _err("INVALID_OBJECT_LOCK",
+      "setObjectLockConfiguration: opts must be an object " +
+      "with { mode, days|years }", true);
+  }
+  if (OBJECT_LOCK_MODES.indexOf(cfg.mode) === -1) {
+    throw _err("INVALID_OBJECT_LOCK",
+      "mode must be one of " + OBJECT_LOCK_MODES.join(", ") +
+      "; got " + JSON.stringify(cfg.mode), true);
+  }
+  var hasDays  = cfg.days  != null;
+  var hasYears = cfg.years != null;
+  if (hasDays && hasYears) {
+    throw _err("INVALID_OBJECT_LOCK",
+      "specify either days OR years, not both (S3 rule)", true);
+  }
+  if (!hasDays && !hasYears) {
+    throw _err("INVALID_OBJECT_LOCK",
+      "default retention requires days or years", true);
+  }
+  if (hasDays) {
+    if (typeof cfg.days !== "number" || !Number.isInteger(cfg.days) ||
+        cfg.days <= 0) {
+      throw _err("INVALID_OBJECT_LOCK",
+        "days must be a positive integer; got " + JSON.stringify(cfg.days), true);
+    }
+  } else {
+    if (typeof cfg.years !== "number" || !Number.isInteger(cfg.years) ||
+        cfg.years <= 0) {
+      throw _err("INVALID_OBJECT_LOCK",
+        "years must be a positive integer; got " + JSON.stringify(cfg.years), true);
+    }
+  }
+}
+
+function _buildObjectLockConfigXml(cfg) {
+  var body = '<?xml version="1.0" encoding="UTF-8"?>';
+  body += '<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">';
+  body += '<ObjectLockEnabled>Enabled</ObjectLockEnabled>';
+  body += '<Rule><DefaultRetention>';
+  body += '<Mode>' + cfg.mode + '</Mode>';
+  if (cfg.days != null)  body += '<Days>'  + cfg.days  + '</Days>';
+  if (cfg.years != null) body += '<Years>' + cfg.years + '</Years>';
+  body += '</DefaultRetention></Rule>';
+  body += '</ObjectLockConfiguration>';
+  return body;
+}
+
+function _validateRetention(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _err("INVALID_RETENTION",
+      "setObjectRetention: opts must be an object " +
+      "with { mode, retainUntil }", true);
+  }
+  if (OBJECT_LOCK_MODES.indexOf(opts.mode) === -1) {
+    throw _err("INVALID_RETENTION",
+      "mode must be one of " + OBJECT_LOCK_MODES.join(", ") +
+      "; got " + JSON.stringify(opts.mode), true);
+  }
+  if (!(opts.retainUntil instanceof Date) || isNaN(opts.retainUntil.getTime())) {
+    throw _err("INVALID_RETENTION",
+      "retainUntil must be a valid Date instance", true);
+  }
+  if (opts.retainUntil.getTime() <= Date.now()) {
+    throw _err("INVALID_RETENTION",
+      "retainUntil must be in the future", true);
+  }
+}
+
+function _buildRetentionXml(opts) {
+  return '<?xml version="1.0" encoding="UTF-8"?>' +
+         '<Retention xmlns="http://s3.amazonaws.com/doc/2006-03-01/">' +
+         '<Mode>' + opts.mode + '</Mode>' +
+         '<RetainUntilDate>' + opts.retainUntil.toISOString() + '</RetainUntilDate>' +
+         '</Retention>';
+}
+
+function _validateLegalHoldStatus(status) {
+  if (LEGAL_HOLD_STATES.indexOf(status) === -1) {
+    throw _err("INVALID_LEGAL_HOLD",
+      "legal-hold status must be one of " + LEGAL_HOLD_STATES.join(", ") +
+      "; got " + JSON.stringify(status), true);
+  }
+}
+
+function _buildLegalHoldXml(status) {
+  return '<?xml version="1.0" encoding="UTF-8"?>' +
+         '<LegalHold xmlns="http://s3.amazonaws.com/doc/2006-03-01/">' +
+         '<Status>' + status + '</Status>' +
+         '</LegalHold>';
+}
+
+// S3 + MinIO surface "this lock-related state was never set" via two
+// distinct error codes (and HTTP statuses), depending on whether the
+// query is at the bucket level or per-object: bucket-level returns 404 +
+// `ObjectLockConfigurationNotFoundError`; per-object retention/legal-hold
+// returns 4xx + `NoSuchObjectLockConfiguration`. Both translate to the
+// same operator answer: "not set". This helper recognizes both so the
+// `get*` methods can surface a clean default instead of throwing.
+function _isLockNotConfigured(err) {
+  if (!err) return false;
+  if (err.statusCode !== 404 && err.statusCode !== 400) return false;
+  var msg = String(err.message || "");
+  return msg.indexOf("ObjectLockConfigurationNotFoundError") !== -1 ||
+         msg.indexOf("NoSuchObjectLockConfiguration") !== -1;
+}
+
+function _validateObjectKey(key) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw _err("INVALID_KEY", "object key must be a non-empty string", true);
+  }
+  if (key.length > 1024) {
+    throw _err("INVALID_KEY", "object key exceeds 1024 bytes (S3 limit)", true);
+  }
+}
+
 // ---- Public factory ----
 
 function create(config) {
   if (!config || typeof config !== "object") {
     throw _err("INVALID_CONFIG", "bucketOps.create requires a config object", true);
   }
+  validateOpts(config, [
+    "protocol", "region", "accessKeyId", "secretAccessKey", "sessionToken",
+    "endpoint", "pathStyle", "forcePathStyle",
+    "allowedProtocols", "allowInternal", "timeoutMs",
+    "ca",
+    "audit", "observability", "auditSuccess", "auditFailures",
+  ], "bucketOps");
   if (config.protocol && config.protocol !== "sigv4") {
     throw _err("INVALID_CONFIG",
       "bucketOps currently only supports protocol 'sigv4'; got '" +
@@ -298,21 +429,88 @@ function create(config) {
   var reqOpts = { timeoutMs: config.timeoutMs, allowedProtocols: allowedProtocols };
   if (allowInternal !== null) reqOpts.allowInternal = allowInternal;
 
+  // Audit + observability are framework-best-practice — wired-on by
+  // default (no operator action needed beyond passing `audit: b.audit`),
+  // failure-audit always on, success-audit on by default for compliance
+  // workloads (SEC 17a-4 / FINRA / HIPAA require a trail of
+  // who-changed-the-retention-policy-and-when). Operators with extreme
+  // call rates can opt out of success-audit via auditSuccess: false;
+  // failures still audit so a forensic reconstruction of "what
+  // happened" is always possible.
+  var audit         = config.audit         || null;
+  var observability = config.observability || null;
+  var auditSuccess  = config.auditSuccess  !== false;
+  var auditFailures = config.auditFailures !== false;
+
+  function _emit(action, info) {
+    if (!audit) return;
+    try {
+      audit.safeEmit(Object.assign({ action: action }, info));
+    } catch (_e) { /* audit best-effort — never break the call */ }
+  }
+
+  function _emitEvent(name, value, labels) {
+    if (!observability || typeof observability.event !== "function") return;
+    try { observability.event(name, value, labels || {}); }
+    catch (_e) { /* observability best-effort */ }
+  }
+
+  function _actor(callerOpts) {
+    return requestHelpers.resolveActorWithOverride(callerOpts || {}, null);
+  }
+
+  // S3 subresource queries (`?lifecycle`, `?cors`, `?object-lock`,
+  // `?retention`, `?legal-hold`) are *bare* tokens on the wire — the
+  // trailing `=` produced by `URLSearchParams.set(k, "")` is interpreted
+  // by some S3 implementations (MinIO in particular) as "this is a
+  // body-write with a query parameter, not a subresource", which routes
+  // the request to the wrong handler. The SigV4 canonicalizer always
+  // reads `key=value` (with the empty `=`) per AWS spec, so the signature
+  // computation is unaffected; only the wire form differs. To preserve
+  // both behaviors, we build the URL string manually and pass it to the
+  // URL constructor — the constructor preserves the bare token in
+  // `url.search` while `url.searchParams` still presents it as `key=`.
+  function _appendQuery(base, query) {
+    if (!query) return base;
+    var keys = Object.keys(query);
+    if (keys.length === 0) return base;
+    var parts = keys.map(function (k) {
+      var v = query[k];
+      if (v === "" || v == null) return encodeURIComponent(k);
+      return encodeURIComponent(k) + "=" + encodeURIComponent(v);
+    });
+    return base + "?" + parts.join("&");
+  }
+
   function _bucketUrl(name, query) {
-    var u;
+    var base;
     if (pathStyle) {
-      u = new URL(endpoint + "/" + name + "/");
+      base = endpoint + "/" + name + "/";
     } else {
-      u = new URL(endpoint);
-      u.hostname = name + "." + u.hostname;
-      u.pathname = "/";
+      var ub = new URL(endpoint);
+      ub.hostname = name + "." + ub.hostname;
+      ub.pathname = "/";
+      base = ub.toString();
+      if (base.endsWith("/")) base = base.slice(0, -1) + "/";
     }
-    if (query) {
-      Object.keys(query).forEach(function (k) {
-        u.searchParams.set(k, query[k] != null ? query[k] : "");
-      });
+    return new URL(_appendQuery(base, query));
+  }
+
+  function _objectUrl(name, key, query) {
+    // Each key segment is encoded individually so that legitimate "/"
+    // separators in the key are preserved (S3 treats keys with slashes
+    // as flat names, not directories).
+    var encKey = key.split("/").map(encodeURIComponent).join("/");
+    var base;
+    if (pathStyle) {
+      base = endpoint + "/" + name + "/" + encKey;
+    } else {
+      var uo = new URL(endpoint);
+      uo.hostname = name + "." + uo.hostname;
+      uo.pathname = "/" + encKey;
+      base = uo.toString();
     }
-    return u;
+    return new URL(_appendQuery(base, query));
   }
 
   function _serviceUrl(query) {
@@ -357,6 +555,8 @@ function create(config) {
   function createBucket(name, opts) {
     _validateBucketName(name);
     opts = opts || {};
+    validateOpts(opts, ["region", "objectLockEnabled", "req", "actor"],
+      "bucketOps.create");
     var targetRegion = opts.region || config.region;
     var url = _bucketUrl(name);
     var bodyBuf;
@@ -377,42 +577,112 @@ function create(config) {
       bodyBuf = Buffer.alloc(0);
       extra["Content-Length"] = "0";
     }
+    // Object Lock can ONLY be enabled at create time — flipping it on
+    // a live bucket isn\'t an S3 API. Setting the header on PutBucket
+    // turns on the underlying versioning + write-once-read-many
+    // semantics so subsequent setObjectLockConfiguration / Retention
+    // / LegalHold calls actually do something.
+    if (opts.objectLockEnabled === true) {
+      extra["x-amz-bucket-object-lock-enabled"] = "true";
+    }
     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 () {
+        if (auditSuccess) {
+          _emit("objectstore.bucket.create", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            metadata: {
+              region:            targetRegion,
+              objectLockEnabled: opts.objectLockEnabled === true,
+            },
+          });
+        }
+        _emitEvent("objectstore.bucket.create", 1,
+          { outcome: "success", region: targetRegion });
+        return { created: true, name: name, region: targetRegion };
+      },
       function (e) {
         // Map S3 conflict response codes into stable framework codes.
+        var mapped = e;
         if (e.statusCode === 409 && /BucketAlreadyOwnedByYou/.test(e.message || "")) {
-          throw _err("BUCKET_ALREADY_OWNED",
+          mapped = _err("BUCKET_ALREADY_OWNED",
             "bucket '" + name + "' already exists and is owned by this account", true);
-        }
-        if (e.statusCode === 409) {
-          throw _err("BUCKET_NAME_TAKEN",
+        } else if (e.statusCode === 409) {
+          mapped = _err("BUCKET_NAME_TAKEN",
             "bucket name '" + name + "' is taken in S3's global namespace", true);
         }
-        throw e;
+        if (auditFailures) {
+          _emit("objectstore.bucket.create", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            outcome:  "failure",
+            reason:   mapped.code || "error",
+            metadata: { region: targetRegion },
+          });
+        }
+        _emitEvent("objectstore.bucket.create", 1,
+          { outcome: "failure", reason: mapped.code || "error" });
+        throw mapped;
       }
     );
   }
 
   // ---- delete ----
 
-  function deleteBucket(name) {
+  function deleteBucket(name, opts) {
     _validateBucketName(name);
+    opts = opts || {};
+    validateOpts(opts, ["req", "actor"], "bucketOps.delete");
     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 () {
+        if (auditSuccess) {
+          _emit("objectstore.bucket.delete", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            metadata: { existed: true },
+          });
+        }
+        _emitEvent("objectstore.bucket.delete", 1,
+          { outcome: "success", existed: "true" });
+        return true;
+      },
       function (e) {
-        if (e.statusCode === 404) return false;
+        if (e.statusCode === 404) {
+          // Idempotent: missing bucket → false. Audit as success-with-noop
+          // so the trail still records "operator attempted delete".
+          if (auditSuccess) {
+            _emit("objectstore.bucket.delete", {
+              actor:    _actor(opts),
+              resource: { kind: "bucket", id: name },
+              metadata: { existed: false },
+            });
+          }
+          _emitEvent("objectstore.bucket.delete", 1,
+            { outcome: "success", existed: "false" });
+          return false;
+        }
+        var mapped = e;
         if (e.statusCode === 409 && /BucketNotEmpty/.test(e.message || "")) {
-          throw _err("BUCKET_NOT_EMPTY",
+          mapped = _err("BUCKET_NOT_EMPTY",
             "bucket '" + name + "' is not empty; delete all objects + " +
             "noncurrent versions + delete-markers first", true);
         }
-        throw e;
+        if (auditFailures) {
+          _emit("objectstore.bucket.delete", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            outcome:  "failure",
+            reason:   mapped.code || "error",
+          });
+        }
+        _emitEvent("objectstore.bucket.delete", 1,
+          { outcome: "failure", reason: mapped.code || "error" });
+        throw mapped;
       }
     );
   }
@@ -428,8 +698,11 @@ function create(config) {
       var result = doc.ListAllMyBucketsResult || {};
       var bucketsContainer = result.Buckets || {};
       var raw = bucketsContainer.Bucket;
-      if (!raw) return [];
-      var arr = Array.isArray(raw) ? raw : [raw];
+      var arr;
+      if (!raw) arr = [];
+      else if (Array.isArray(raw)) arr = raw;
+      else arr = [raw];
+      _emitEvent("objectstore.bucket.list", arr.length, { outcome: "success" });
       return arr.map(function (b) {
         return {
           name:         b.Name,
@@ -442,8 +715,10 @@ function create(config) {
 
   // ---- setLifecycle ----
 
-  function setLifecycle(name, rules) {
+  function setLifecycle(name, rules, opts) {
     _validateBucketName(name);
+    opts = opts || {};
+    validateOpts(opts, ["req", "actor"], "bucketOps.setLifecycle");
     var bodyXml = _buildLifecycleXml(rules);
     var bodyBuf = Buffer.from(bodyXml, "utf8");
     var url = _bucketUrl(name, { lifecycle: "" });
@@ -453,15 +728,41 @@ function create(config) {
       "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 _request("PUT", url, headers, bodyBuf).then(
+      function () {
+        if (auditSuccess) {
+          _emit("objectstore.bucket.setLifecycle", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            metadata: { ruleCount: rules.length },
+          });
+        }
+        _emitEvent("objectstore.bucket.setLifecycle", 1,
+          { outcome: "success", ruleCount: String(rules.length) });
+        return { applied: true, name: name, ruleCount: rules.length };
+      },
+      function (e) {
+        if (auditFailures) {
+          _emit("objectstore.bucket.setLifecycle", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            outcome:  "failure",
+            reason:   e.code || "error",
+          });
+        }
+        _emitEvent("objectstore.bucket.setLifecycle", 1,
+          { outcome: "failure", reason: e.code || "error" });
+        throw e;
+      }
+    );
   }
 
   // ---- setCorsRules ----
 
-  function setCorsRules(name, rules) {
+  function setCorsRules(name, rules, opts) {
     _validateBucketName(name);
+    opts = opts || {};
+    validateOpts(opts, ["req", "actor"], "bucketOps.setCorsRules");
     var bodyXml = _buildCorsXml(rules);
     var bodyBuf = Buffer.from(bodyXml, "utf8");
     var url = _bucketUrl(name, { cors: "" });
@@ -471,18 +772,317 @@ function create(config) {
       "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 _request("PUT", url, headers, bodyBuf).then(
+      function () {
+        if (auditSuccess) {
+          _emit("objectstore.bucket.setCorsRules", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            metadata: { ruleCount: rules.length },
+          });
+        }
+        _emitEvent("objectstore.bucket.setCorsRules", 1,
+          { outcome: "success", ruleCount: String(rules.length) });
+        return { applied: true, name: name, ruleCount: rules.length };
+      },
+      function (e) {
+        if (auditFailures) {
+          _emit("objectstore.bucket.setCorsRules", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            outcome:  "failure",
+            reason:   e.code || "error",
+          });
+        }
+        _emitEvent("objectstore.bucket.setCorsRules", 1,
+          { outcome: "failure", reason: e.code || "error" });
+        throw e;
+      }
+    );
+  }
+
+  // ---- Object Lock configuration (bucket-level) ----
+
+  function setObjectLockConfiguration(name, opts) {
+    _validateBucketName(name);
+    _validateObjectLockConfig(opts);
+    validateOpts(opts, ["mode", "days", "years", "req", "actor"],
+      "bucketOps.setObjectLockConfiguration");
+    var bodyXml = _buildObjectLockConfigXml(opts);
+    var bodyBuf = Buffer.from(bodyXml, "utf8");
+    var url = _bucketUrl(name, { "object-lock": "" });
+    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 () {
+        // Compliance-critical event — SEC 17a-4 / FINRA / HIPAA require
+        // a trail of who-changed-the-default-retention-policy-and-when.
+        if (auditSuccess) {
+          _emit("objectstore.bucket.setObjectLockConfiguration", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            metadata: {
+              mode:  opts.mode,
+              days:  opts.days  != null ? opts.days  : null,
+              years: opts.years != null ? opts.years : null,
+            },
+          });
+        }
+        _emitEvent("objectstore.bucket.setObjectLockConfiguration", 1,
+          { outcome: "success", mode: opts.mode });
+        return {
+          applied: true, name: name,
+          mode:    opts.mode,
+          days:    opts.days  != null ? opts.days  : null,
+          years:   opts.years != null ? opts.years : null,
+        };
+      },
+      function (e) {
+        if (auditFailures) {
+          _emit("objectstore.bucket.setObjectLockConfiguration", {
+            actor:    _actor(opts),
+            resource: { kind: "bucket", id: name },
+            outcome:  "failure",
+            reason:   e.code || "error",
+            metadata: { mode: opts.mode },
+          });
+        }
+        _emitEvent("objectstore.bucket.setObjectLockConfiguration", 1,
+          { outcome: "failure", reason: e.code || "error" });
+        throw e;
+      }
+    );
+  }
+
+  function getObjectLockConfiguration(name) {
+    _validateBucketName(name);
+    _emitEvent("objectstore.bucket.getObjectLockConfiguration", 1,
+      { outcome: "success" });
+    var url = _bucketUrl(name, { "object-lock": "" });
+    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 olc = doc.ObjectLockConfiguration || {};
+        var enabled = olc.ObjectLockEnabled === "Enabled";
+        var rule = olc.Rule || {};
+        var def  = rule.DefaultRetention || {};
+        return {
+          enabled: enabled,
+          mode:    def.Mode || null,
+          days:    def.Days  != null ? Number(def.Days)  : null,
+          years:   def.Years != null ? Number(def.Years) : null,
+        };
+      },
+      function (e) {
+        // S3 + MinIO return 404 + ObjectLockConfigurationNotFoundError
+        // when the bucket was created without `objectLockEnabled: true`.
+        // That's a "not configured" state, not an error worth bubbling
+        // — operators asking "is this bucket lock-enabled?" want a
+        // clean false, not a try/catch.
+        if (_isLockNotConfigured(e)) {
+          return { enabled: false, mode: null, days: null, years: null };
+        }
+        throw e;
+      }
+    );
+  }
+
+  // ---- Per-object retention ----
+
+  function setObjectRetention(name, key, opts) {
+    _validateBucketName(name);
+    _validateObjectKey(key);
+    _validateRetention(opts);
+    validateOpts(opts, ["mode", "retainUntil", "bypassGovernance", "req", "actor"],
+      "bucketOps.setObjectRetention");
+    var bodyXml = _buildRetentionXml(opts);
+    var bodyBuf = Buffer.from(bodyXml, "utf8");
+    var url = _objectUrl(name, key, { retention: "" });
+    var extra = {
+      "Content-Type":   "application/xml",
+      "Content-Length": String(bodyBuf.length),
+      "Content-MD5":    _md5Base64(bodyBuf),
+    };
+    if (opts.bypassGovernance === true) {
+      extra["x-amz-bypass-governance-retention"] = "true";
+    }
+    var payloadHash = sigv4.sha256Hex(bodyBuf);
+    var headers = _signed("PUT", url, payloadHash, extra);
+    return _request("PUT", url, headers, bodyBuf).then(
+      function () {
+        // Compliance trail — bypassGovernance is the high-risk op
+        // (operator with s3:BypassGovernanceRetention shortened a
+        // GOVERNANCE retention) and operators wire alerting on this
+        // metadata field.
+        if (auditSuccess) {
+          _emit("objectstore.object.setRetention", {
+            actor:    _actor(opts),
+            resource: { kind: "object", id: name + "/" + key },
+            metadata: {
+              bucket:           name,
+              key:              key,
+              mode:             opts.mode,
+              retainUntilIso:   opts.retainUntil.toISOString(),
+              bypassGovernance: opts.bypassGovernance === true,
+            },
+          });
+        }
+        _emitEvent("objectstore.object.setRetention", 1,
+          { outcome: "success", mode: opts.mode,
+            bypassGovernance: opts.bypassGovernance === true ? "true" : "false" });
+        return {
+          applied:     true,
+          name:        name,
+          key:         key,
+          mode:        opts.mode,
+          retainUntil: opts.retainUntil,
+        };
+      },
+      function (e) {
+        if (auditFailures) {
+          _emit("objectstore.object.setRetention", {
+            actor:    _actor(opts),
+            resource: { kind: "object", id: name + "/" + key },
+            outcome:  "failure",
+            reason:   e.code || "error",
+            metadata: {
+              bucket:           name,
+              key:              key,
+              mode:             opts.mode,
+              bypassGovernance: opts.bypassGovernance === true,
+            },
+          });
+        }
+        _emitEvent("objectstore.object.setRetention", 1,
+          { outcome: "failure", reason: e.code || "error" });
+        throw e;
+      }
+    );
+  }
+
+  function getObjectRetention(name, key) {
+    _validateBucketName(name);
+    _validateObjectKey(key);
+    _emitEvent("objectstore.object.getRetention", 1, { outcome: "success" });
+    var url = _objectUrl(name, key, { retention: "" });
+    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 ret = doc.Retention || {};
+        var until = ret.RetainUntilDate ? new Date(ret.RetainUntilDate) : null;
+        return {
+          mode:        ret.Mode || null,
+          retainUntil: until,
+        };
+      },
+      function (e) {
+        // S3 + MinIO return 4xx + NoSuchObjectLockConfiguration when the
+        // object has no per-object retention applied. Same UX choice as
+        // getObjectLockConfiguration: surface the not-set state cleanly
+        // rather than forcing operators to try/catch on a known-good
+        // request shape.
+        if (_isLockNotConfigured(e)) {
+          return { mode: null, retainUntil: null };
+        }
+        throw e;
+      }
+    );
+  }
+
+  // ---- Per-object legal hold ----
+
+  function setObjectLegalHold(name, key, status, opts) {
+    _validateBucketName(name);
+    _validateObjectKey(key);
+    _validateLegalHoldStatus(status);
+    opts = opts || {};
+    validateOpts(opts, ["req", "actor"], "bucketOps.setObjectLegalHold");
+    var bodyXml = _buildLegalHoldXml(status);
+    var bodyBuf = Buffer.from(bodyXml, "utf8");
+    var url = _objectUrl(name, key, { "legal-hold": "" });
+    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 () {
+        if (auditSuccess) {
+          _emit("objectstore.object.setLegalHold", {
+            actor:    _actor(opts),
+            resource: { kind: "object", id: name + "/" + key },
+            metadata: { bucket: name, key: key, status: status },
+          });
+        }
+        _emitEvent("objectstore.object.setLegalHold", 1,
+          { outcome: "success", status: status });
+        return { applied: true, name: name, key: key, status: status };
+      },
+      function (e) {
+        if (auditFailures) {
+          _emit("objectstore.object.setLegalHold", {
+            actor:    _actor(opts),
+            resource: { kind: "object", id: name + "/" + key },
+            outcome:  "failure",
+            reason:   e.code || "error",
+            metadata: { bucket: name, key: key, status: status },
+          });
+        }
+        _emitEvent("objectstore.object.setLegalHold", 1,
+          { outcome: "failure", reason: e.code || "error" });
+        throw e;
+      }
+    );
+  }
+
+  function getObjectLegalHold(name, key) {
+    _validateBucketName(name);
+    _validateObjectKey(key);
+    _emitEvent("objectstore.object.getLegalHold", 1, { outcome: "success" });
+    var url = _objectUrl(name, key, { "legal-hold": "" });
+    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 lh = doc.LegalHold || {};
+        return { status: lh.Status || null };
+      },
+      function (e) {
+        // Object never had a legal hold set — S3 + MinIO surface this
+        // as NoSuchObjectLockConfiguration. Return a clean OFF instead
+        // of throwing; "no hold ever applied" is operationally
+        // identical to "hold is OFF".
+        if (_isLockNotConfigured(e)) {
+          return { status: "OFF" };
+        }
+        throw e;
+      }
+    );
   }
 
   return {
-    protocol:      "sigv4",
-    create:        createBucket,
-    delete:        deleteBucket,
-    list:          listBuckets,
-    setLifecycle:  setLifecycle,
-    setCorsRules:  setCorsRules,
+    protocol:                       "sigv4",
+    create:                         createBucket,
+    delete:                         deleteBucket,
+    list:                           listBuckets,
+    setLifecycle:                   setLifecycle,
+    setCorsRules:                   setCorsRules,
+    setObjectLockConfiguration:     setObjectLockConfiguration,
+    getObjectLockConfiguration:     getObjectLockConfiguration,
+    setObjectRetention:             setObjectRetention,
+    getObjectRetention:             getObjectRetention,
+    setObjectLegalHold:             setObjectLegalHold,
+    getObjectLegalHold:             getObjectLegalHold,
   };
 }
 
@@ -490,7 +1090,7 @@ 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,
+  _buildLifecycleXmlForTest:        _buildLifecycleXml,
+  _buildCorsXmlForTest:             _buildCorsXml,
+  _validateBucketNameForTest:       _validateBucketName,
 };