@blamejs/core 0.15.9 → 0.15.11

package/lib/object-store/azure-blob.js

@@ -356,7 +356,18 @@ function create(config) {
     });
   }
 
-  function deleteKey(key) {
+  function deleteKey(key, opts) {
+    opts = opts || {};
+    // Versioned erasure (opts.versionId) is the S3 Object-Lock workflow and is
+    // sigv4-only today. Refuse loudly rather than silently delete the current
+    // blob — a silent drop on an erasure path would let a caller believe a
+    // specific version was shredded when it was not.
+    if (opts.versionId) {
+      throw _err("VERSIONID_UNSUPPORTED",
+        "deleteKey: versioned delete (opts.versionId) is S3/sigv4-only; the Azure " +
+        "Blob backend has no version surface here. Use a sigv4 backend for " +
+        "Object-Lock version erasure.", true);
+    }
     var url = _blobUrl(key);
     var headers = _signed("DELETE", url, {});
     return _httpRequest("DELETE", url, headers, null, reqOpts).then(

package/lib/object-store/gcs.js

@@ -281,7 +281,18 @@ function create(config) {
     };
   }
 
-  async function deleteKey(key) {
+  async function deleteKey(key, opts) {
+    opts = opts || {};
+    // Versioned erasure (opts.versionId) is the S3 Object-Lock workflow and is
+    // sigv4-only today. Refuse loudly rather than silently delete the live
+    // object — a silent drop on an erasure path would let a caller believe a
+    // specific version was shredded when it was not.
+    if (opts.versionId) {
+      throw _err("VERSIONID_UNSUPPORTED",
+        "deleteKey: versioned delete (opts.versionId) is S3/sigv4-only; the GCS " +
+        "backend has no version surface here. Use a sigv4 backend for Object-Lock " +
+        "version erasure.", true);
+    }
     var token = await _ensureToken();
     var url = _objectUrl(key);
     try {

package/lib/object-store/http-put.js

@@ -110,7 +110,17 @@ function create(config) {
     });
   }
 
-  function deleteKey(key) {
+  function deleteKey(key, opts) {
+    opts = opts || {};
+    // Versioned erasure (opts.versionId) is the S3 Object-Lock workflow and is
+    // sigv4-only. A bare PUT target has no version surface, so refuse loudly
+    // rather than issue a plain DELETE and report a specific version erased —
+    // a silent drop on an erasure path is the footgun.
+    if (opts.versionId) {
+      throw _err("VERSIONID_UNSUPPORTED",
+        "deleteKey: versioned delete (opts.versionId) is S3/sigv4-only; the http-put " +
+        "backend has no version surface. Use a sigv4 backend for Object-Lock version erasure.", true);
+    }
     var url = _keyToUrl(baseUrl, key);
     return _request("DELETE", url, null, headers, reqOpts).then(
       function () { return true; },

package/lib/object-store/index.js

@@ -122,6 +122,10 @@ function buildBackend(config) {
     head:            wrap("head"),
     delete:          wrap("delete"),
     list:            wrap("list"),
+    // listVersions is S3/sigv4-only (the ?versions subresource backs the
+    // WORM erasure workflow). Backends without it expose null so callers can
+    // feature-detect rather than hit a "wrap of undefined" at boot.
+    listVersions:    typeof raw.listVersions === "function" ? wrap("listVersions") : null,
     // presigned*Url are sync URL-builders (no network call), so they
     // bypass retry + circuit-breaker — propagate any throw directly.
     presignedUploadUrl: typeof raw.presignedUploadUrl === "function"

package/lib/object-store/local.js

@@ -101,7 +101,17 @@ function create(config) {
     });
   }
 
-  function deleteKey(key) {
+  function deleteKey(key, opts) {
+    opts = opts || {};
+    // A filesystem has no object versions; a versioned-delete request can only
+    // be a caller mistake. Refuse loudly rather than unlink the single on-disk
+    // file and report a version was erased.
+    if (opts.versionId) {
+      throw _err("VERSIONID_UNSUPPORTED",
+        "deleteKey: versioned delete (opts.versionId) is not supported on the " +
+        "filesystem backend — a local file has no version history. Use a sigv4 " +
+        "(S3 Object-Lock) backend for version erasure.", true);
+    }
     cluster.requireLeader();
     var full = _resolveSafe(rootDir, key);
     if (!nodeFs.existsSync(full)) return Promise.resolve(false);

package/lib/object-store/sigv4.js

@@ -499,7 +499,15 @@ function create(config) {
     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 };
+      return {
+        size: buf.length,
+        etag: res.headers.etag,
+        // On a versioning-enabled (Object-Lock) bucket S3/MinIO returns the
+        // version this PUT created. Surface it so callers can target the
+        // exact version for a later versioned delete / erasure — without it
+        // the only way to find the version is a separate listVersions() call.
+        versionId: res.headers && res.headers["x-amz-version-id"] || null,
+      };
     });
   }
 
@@ -601,7 +609,12 @@ function create(config) {
       // 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 };
+      return {
+        size: totalSize,
+        etag: result.ETag || completeRes.headers.etag,
+        multipart: true,
+        versionId: completeRes.headers && completeRes.headers["x-amz-version-id"] || null,
+      };
     } catch (e) {
       // Abort cleans up server-side storage for the partial upload.
       // Failures here are silently swallowed — the caller's original
@@ -639,6 +652,11 @@ function create(config) {
   function getResponse(key, opts) {
     opts = opts || {};
     var url = _keyToUrl(key);
+    // Reading a specific version (opts.versionId) is the read half of the
+    // WORM erasure workflow — verify a protected version is present before /
+    // gone after a versioned delete. Set it before signing so the query
+    // param is in the SigV4 canonical request.
+    if (opts.versionId) url.searchParams.set("versionId", opts.versionId);
     var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));
     if (opts.range) {
       headers["Range"] = "bytes=" + opts.range.start + "-" + opts.range.end;
@@ -674,8 +692,10 @@ function create(config) {
     });
   }
 
-  function head(key) {
+  function head(key, opts) {
+    opts = opts || {};
     var url = _keyToUrl(key);
+    if (opts.versionId) url.searchParams.set("versionId", opts.versionId);
     var headers = _makeSigned("HEAD", url, sha256Hex(Buffer.alloc(0)));
     return _request("HEAD", url, headers, null, reqOpts).then(function (res) {
       return {
@@ -696,9 +716,25 @@ function create(config) {
     });
   }
 
-  function deleteKey(key) {
+  // deleteKey(key, opts?) — opts.versionId targets a specific version;
+  // opts.bypassGovernanceRetention signs x-amz-bypass-governance-retention so
+  // a GOVERNANCE-mode retention can be lifted by a caller with the permission
+  // (COMPLIANCE mode is immutable to everyone and stays refused).
+  //
+  // WORM-awareness: an UNVERSIONED delete on a versioning-enabled bucket only
+  // writes a delete-marker — the data version survives and the call still
+  // resolves true. To actually erase a version (e.g. crypto-shred / GDPR Art.
+  // 17 on an Object-Lock bucket) pass the versionId from put()/listVersions().
+  // A delete refused by an active retention surfaces as a thrown error (S3 403
+  // / MinIO 400), never a silent success, so the caller learns the version is
+  // still protected.
+  function deleteKey(key, opts) {
+    opts = opts || {};
     var url = _keyToUrl(key);
-    var headers = _makeSigned("DELETE", url, sha256Hex(Buffer.alloc(0)));
+    if (opts.versionId) url.searchParams.set("versionId", opts.versionId);
+    var extra = {};
+    if (opts.bypassGovernanceRetention) extra["x-amz-bypass-governance-retention"] = "true";
+    var headers = _makeSigned("DELETE", url, sha256Hex(Buffer.alloc(0)), extra);
     return _request("DELETE", url, headers, null, reqOpts).then(
       function () { return true; },
       function (e) { if (e.statusCode === 404) return false; throw e; }
@@ -953,6 +989,50 @@ function create(config) {
     });
   }
 
+  // listVersions(prefix, opts?) — enumerate every object VERSION and
+  // delete-marker under prefix (S3 ListObjectVersions / the ?versions
+  // subresource). Plain list() only sees current versions; to erase prior
+  // versions on a versioning / Object-Lock bucket you first need their
+  // versionIds, which only this call surfaces. Each item carries
+  // { key, versionId, isLatest, deleteMarker, size, lastModified, etag };
+  // deleteMarker:true rows are tombstones (no data, size null). Pagination
+  // walks (keyMarker, versionIdMarker) the way list() walks continuationToken.
+  function listVersions(prefix, opts) {
+    opts = opts || {};
+    var params = { versions: "" };
+    if (prefix) params["prefix"] = prefix;
+    if (opts.maxResults) params["max-keys"] = String(opts.maxResults);
+    if (opts.keyMarker) params["key-marker"] = opts.keyMarker;
+    if (opts.versionIdMarker) params["version-id-marker"] = opts.versionIdMarker;
+
+    var url = _bucketUrl(params);
+    var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));
+    return _request("GET", url, headers, null, reqOpts).then(function (res) {
+      var doc = safeXml.parse(res.body, LIST_PARSE_OPTS);
+      var result = doc.ListVersionsResult || {};
+      function _mapEntry(e, isDeleteMarker) {
+        return {
+          key:          e.Key,
+          versionId:    e.VersionId != null ? String(e.VersionId) : null,
+          isLatest:     e.IsLatest === "true",
+          deleteMarker: isDeleteMarker,
+          size:         isDeleteMarker ? null : (e.Size != null ? parseInt(e.Size, 10) : null),
+          lastModified: e.LastModified ? Date.parse(e.LastModified) : null,
+          etag:         isDeleteMarker ? null : (e.ETag || null),
+        };
+      }
+      var versions = _arrayify(result.Version).map(function (v) { return _mapEntry(v, false); });
+      var markers = _arrayify(result.DeleteMarker).map(function (m) { return _mapEntry(m, true); });
+      var items = versions.concat(markers).filter(function (it) { return it.key; });
+      return {
+        items:           items,
+        truncated:       result.IsTruncated === "true",
+        keyMarker:       result.NextKeyMarker || null,
+        versionIdMarker: result.NextVersionIdMarker || null,
+      };
+    });
+  }
+
   return {
     protocol:  "sigv4",
     endpoint:  endpoint,
@@ -966,6 +1046,7 @@ function create(config) {
     head:      head,
     delete:    deleteKey,
     list:      list,
+    listVersions: listVersions,
     presignedUploadUrl:    presignedUploadUrl,
     presignedDownloadUrl:  presignedDownloadUrl,
     presignedUploadPolicy: presignedUploadPolicy,

package/lib/parsers/safe-env.js

@@ -147,7 +147,7 @@ function parse(input, opts) {
     if (eqIdx < 0) {
       throw new SafeEnvError("missing '=' separator", "env/bad-line", lineNumber);
     }
-    var key = trimmed.substring(0, eqIdx).replace(safeBuffer.TRAILING_HSPACE_RE, "");
+    var key = safeBuffer.stripTrailingHspace(trimmed.substring(0, eqIdx));
     var rest = trimmed.substring(eqIdx + 1);
 
     if (key.length === 0) {
@@ -186,10 +186,13 @@ function parse(input, opts) {
       // The comment marker MUST be preceded by whitespace to count
       // (so a value like `KEY=color#red` keeps the literal `#`).
       var commentMatch = rest.match(/^([^\s#]*(?:[ \t]+[^#\s]+)*)\s+#.*$/);
+      // stripTrailingHspace is a linear char-scan; .replace(/[ \t]+$/) is O(n^2)
+      // in V8 and the env parser only caps TOTAL bytes, not per-line, so a
+      // single huge-whitespace value line would otherwise hang the parser.
       if (commentMatch) {
-        value = commentMatch[1].replace(safeBuffer.TRAILING_HSPACE_RE, "");
+        value = safeBuffer.stripTrailingHspace(commentMatch[1]);
       } else {
-        value = rest.replace(safeBuffer.TRAILING_HSPACE_RE, "");
+        value = safeBuffer.stripTrailingHspace(rest);
       }
       // Reject `$VAR` style references — explicit error so operators
       // see the policy rather than silently getting unexpanded text.

package/lib/parsers/safe-yaml.js

@@ -185,7 +185,7 @@ function parse(input, opts) {
     var raw = rawLines[i];
     // Strip trailing whitespace from the line for analysis (block-scalar
     // content paths preserve their own internal spacing separately).
-    var trimmed = raw.replace(safeBuffer.TRAILING_HSPACE_RE, "");
+    var trimmed = safeBuffer.stripTrailingHspace(raw);
     var indent = 0;
     while (indent < raw.length && raw.charAt(indent) === " ") indent += 1;
     if (indent < raw.length && raw.charAt(indent) === "\t") {
@@ -332,7 +332,7 @@ function parse(input, opts) {
     if (raw.charAt(0) === "'") {
       return _decodeSingleQuoted(raw, lineNumber, col);
     }
-    var trimmed = raw.replace(safeBuffer.TRAILING_HSPACE_RE, "");
+    var trimmed = safeBuffer.stripTrailingHspace(raw);
     if (POISONED_KEYS.has(trimmed)) {
       throw new SafeYamlError("forbidden key '" + trimmed + "'",
         "yaml/poisoned-key", lineNumber, col);
@@ -506,7 +506,7 @@ function parse(input, opts) {
       return sq;
     }
     // Plain scalar — strip trailing space, resolve type.
-    return _resolveScalar(t.replace(safeBuffer.TRAILING_HSPACE_RE, ""));
+    return _resolveScalar(safeBuffer.stripTrailingHspace(t));
   }
 
   // For quoted-string termination check on a single-line value.
@@ -622,7 +622,7 @@ function parse(input, opts) {
       if (c === "," || c === "}" || c === "]") break;
       p += 1;
     }
-    var raw = text.substring(start, p).replace(safeBuffer.TRAILING_HSPACE_RE, "");
+    var raw = safeBuffer.stripTrailingHspace(text.substring(start, p));
     return { value: _resolveScalar(raw), nextPos: p };
   }
 
@@ -645,7 +645,7 @@ function parse(input, opts) {
       if (c === ":" || c === "," || c === "}" || c === "]") break;
       p += 1;
     }
-    return { key: text.substring(start, p).replace(safeBuffer.TRAILING_HSPACE_RE, ""), nextPos: p };
+    return { key: safeBuffer.stripTrailingHspace(text.substring(start, p)), nextPos: p };
   }
 
   function _findMatchingBracket(text, start, open, close, lineNumber, col) {
@@ -772,7 +772,7 @@ function parse(input, opts) {
   function _stripEolComment(text) {
     // Strip ` #...` comments (must be preceded by whitespace) at end of line.
     var match = text.match(/^(.*?)(\s+#.*)?$/);
-    return (match && match[1] != null ? match[1] : text).replace(safeBuffer.TRAILING_HSPACE_RE, "");
+    return safeBuffer.stripTrailingHspace(match && match[1] != null ? match[1] : text);
   }
 
   // ---- Block scalars (| literal, > folded) ----

package/lib/safe-buffer.js

@@ -494,7 +494,74 @@ var TRAILING_HSPACE_RE = /[ \t]+$/;
  */
 function stripTrailingHspace(s) {
   if (typeof s !== "string") return s;
-  return s.replace(TRAILING_HSPACE_RE, "");
+  // Linear backward scan over trailing spaces/tabs — NOT s.replace(/[ \t]+$/).
+  // The `$`-after-greedy-`[ \t]+` regex is O(n^2) in V8 on adversarial input
+  // (a long run of spaces followed by a non-space: the engine retries the
+  // greedy match from every offset). normalizeText callers cap TOTAL bytes but
+  // not per-line, so a single ~500K-space value hangs (~85s). The char-scan is
+  // O(trailing-whitespace) and byte-identical to the regex on every input
+  // (JS `$` without /m matches only the absolute end, so a trailing \n is not
+  // stripped — the scan stops at it too).
+  var e = s.length;
+  while (e > 0) {
+    var c = s.charCodeAt(e - 1);
+    if (c === 0x20 || c === 0x09) { e -= 1; } else { break; }
+  }
+  return e === s.length ? s : s.slice(0, e);
+}
+
+/**
+ * @primitive b.safeBuffer.indexAfterOpenTag
+ * @signature b.safeBuffer.indexAfterOpenTag(html, tagName)
+ * @since     0.15.11
+ * @related   b.safeBuffer.stripTrailingHspace
+ *
+ * Find the offset in `html` just past the first `<tagName ...>` opening
+ * tag (case-insensitive), or `-1` when the tag is absent or unterminated.
+ * The insertion point a response rewriter uses to splice content right
+ * after `<body>` / `<head>` without a regex.
+ *
+ * This replaces the `html.match(/<body[^>]*>/i)` shape, which is O(n^2)
+ * in V8: a body carrying many `<body` starts with no closing `>` (e.g.
+ * rendered user content) makes the engine retry the greedy `[^>]*` from
+ * every offset — a `<body`-repeated 200K-char body benchmarks in
+ * seconds. This is a single forward `indexOf` walk: linear in the input,
+ * and stricter than the regex — it requires a real tag boundary after
+ * the name (whitespace, `>`, or `/`), so `<bodyfoo>` is not mistaken for
+ * `<body>`. Non-string input returns `-1`.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   b.safeBuffer.indexAfterOpenTag("<html><body class=x>hi", "body");
+ *   // → 19  (just past the '>' of <body class=x>)
+ *
+ *   b.safeBuffer.indexAfterOpenTag("<p>no body here</p>", "body");
+ *   // → -1
+ */
+function indexAfterOpenTag(html, tagName) {
+  if (typeof html !== "string" || typeof tagName !== "string" || tagName.length === 0) return -1;
+  var needle = "<" + tagName.toLowerCase();
+  var nlen = needle.length;
+  // One O(n) lowercase pass keeps the case-insensitive search linear; the
+  // forward indexOf walk below never re-scans a region it has passed.
+  var lower = html.toLowerCase();
+  var from = 0;
+  for (;;) {
+    var lt = lower.indexOf(needle, from);
+    if (lt === -1) return -1;
+    var after = lt + nlen;
+    var boundary = after < html.length ? html.charCodeAt(after) : -1;
+    // The char after "<tag" must end the tag name — '>' (0x3e), '/' (0x2f),
+    // or ASCII whitespace — else this is a longer name like "<bodyfoo".
+    if (boundary === 0x3e || boundary === 0x2f ||
+        boundary === 0x20 || boundary === 0x09 ||
+        boundary === 0x0a || boundary === 0x0d || boundary === 0x0c) {
+      var gt = html.indexOf(">", after);
+      if (gt === -1) return -1;   // unterminated opening tag — no insertion point
+      return gt + 1;
+    }
+    from = lt + 1;
+  }
 }
 
 /**
@@ -612,6 +679,7 @@ module.exports = {
   hasCrlf:               hasCrlf,
   stripCrlf:             stripCrlf,
   stripTrailingHspace:   stripTrailingHspace,
+  indexAfterOpenTag:     indexAfterOpenTag,
   HEX_RE:                HEX_RE,
   BASE64URL_RE:          BASE64URL_RE,
   BASE64_RE:             BASE64_RE,

package/lib/safe-decompress.js

@@ -171,18 +171,9 @@ function safeDecompress(input, opts) {
         JSON.stringify(opts.algorithm));
   }
 
-  // maxOutputBytes — required, positive finite integer. Inline gate
-  // is intentional: it's a REQUIRED opt (not optional), so the
-  // `requirePositiveFiniteIntIfPresent` helper doesn't apply (it skips
-  // when undefined). The numericBounds.requirePositiveFiniteInt helper
-  // would fit, but the existing call surface across the framework
-  // uses the inline shape for required-opt validation.
-  if (!numericBounds.isPositiveFiniteInt(opts.maxOutputBytes)) {                     // allow:inline-numeric-bounds-cascade — required (non-optional) opt; requirePositiveFiniteIntIfPresent skips when undefined
-    throw new SafeDecompressError(
-      "safe-decompress/bad-arg",
-      "safeDecompress: maxOutputBytes must be a positive finite integer; got " +
-        numericBounds.shape(opts.maxOutputBytes));
-  }
+  // maxOutputBytes — required, positive finite integer.
+  numericBounds.requirePositiveFiniteInt(opts.maxOutputBytes,
+    "safeDecompress: maxOutputBytes", SafeDecompressError, "safe-decompress/bad-arg");
 
   // Input shape
   var buf;

package/lib/seeders.js

@@ -546,46 +546,40 @@ function create(opts) {
 
         try {
            
-          await (async function () {
-            // Per-seed transaction: SQLite txns are sync, but the
-            // seed's run() may be async — so we begin/commit around
-            // an awaited body. Failures roll back this seed only.
-            _runSql(db, "BEGIN");
-            try {
-              await mod.run(db, ctx);
-              var nowIso = new Date(clock()).toISOString();
-              var writeBuilt;
-              if (alreadyApplied && mod.rerunnable) {
-                writeBuilt = sql.update(_seedersTable(), _sqlOpts(db))
-                  .set({ appliedAt: nowIso, description: mod.description || "",
-                         rerunnable: mod.rerunnable ? 1 : 0 })
-                  .where("env", env).where("name", name).toSql();
-              } else if (alreadyApplied && force) {
-                writeBuilt = sql.update(_seedersTable(), _sqlOpts(db))
-                  .set({ appliedAt: nowIso, description: mod.description || "" })
-                  .where("env", env).where("name", name).toSql();
-              } else {
-                writeBuilt = sql.insert(_seedersTable(), _sqlOpts(db))
-                  .values({ env: env, name: name, description: mod.description || "",
-                            appliedAt: nowIso, rerunnable: mod.rerunnable ? 1 : 0 })
-                  .toSql();
-              }
-              var writeStmt = db.prepare(writeBuilt.sql);
-              writeStmt.run.apply(writeStmt, writeBuilt.params);
-              _runSql(db, "COMMIT");
-            } catch (e) {
-              try { _runSql(db, "ROLLBACK"); }
-              catch (rollbackErr) {
-                log.debug("rollback-failed", {
-                  op: "seed-apply",
-                  env: env,
-                  name: name,
-                  error: rollbackErr && rollbackErr.message,
-                });
-              }
-              throw e;
+          // Per-seed transaction: SQLite txns are sync, but the seed's
+          // run() may be async — runInTransactionAsync wraps BEGIN/COMMIT
+          // around the awaited body and rolls back this seed only on failure.
+          await dbSchema.runInTransactionAsync(db, async function () {
+            await mod.run(db, ctx);
+            var nowIso = new Date(clock()).toISOString();
+            var writeBuilt;
+            if (alreadyApplied && mod.rerunnable) {
+              writeBuilt = sql.update(_seedersTable(), _sqlOpts(db))
+                .set({ appliedAt: nowIso, description: mod.description || "",
+                       rerunnable: mod.rerunnable ? 1 : 0 })
+                .where("env", env).where("name", name).toSql();
+            } else if (alreadyApplied && force) {
+              writeBuilt = sql.update(_seedersTable(), _sqlOpts(db))
+                .set({ appliedAt: nowIso, description: mod.description || "" })
+                .where("env", env).where("name", name).toSql();
+            } else {
+              writeBuilt = sql.insert(_seedersTable(), _sqlOpts(db))
+                .values({ env: env, name: name, description: mod.description || "",
+                          appliedAt: nowIso, rerunnable: mod.rerunnable ? 1 : 0 })
+                .toSql();
             }
-          })();
+            var writeStmt = db.prepare(writeBuilt.sql);
+            writeStmt.run.apply(writeStmt, writeBuilt.params);
+          }, {
+            onRollbackFail: function (rollbackErr) {
+              log.debug("rollback-failed", {
+                op: "seed-apply",
+                env: env,
+                name: name,
+                error: rollbackErr && rollbackErr.message,
+              });
+            },
+          });
           applied.push(name);
           appliedSet.add(name);
 

package/lib/storage.js

@@ -425,7 +425,7 @@ async function getFileStream(key, sealedKey, opts) {
  * @example
  *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
  *   var saved = await b.storage.saveRaw(Buffer.from("public-bytes"), "logo.png");
- *   // → { storedPath: "logo.png", backend: "default" }
+ *   // → { storedPath: "logo.png", backend: "default", versionId: null }
  */
 async function saveRaw(buffer, key, opts) {
   _requireInit();
@@ -443,7 +443,9 @@ async function saveRaw(buffer, key, opts) {
       raw:            true,
     },
   });
-  return { storedPath: key, backend: picked.backend.name };
+  // versionId is non-null only on a versioning-enabled (S3 Object-Lock)
+  // backend; capture it to target the exact version for later erasure.
+  return { storedPath: key, backend: picked.backend.name, versionId: result.versionId || null };
 }
 
 /**
@@ -486,14 +488,24 @@ async function getRawBuffer(key, opts) {
  * Remove `key` from the routed backend. Returns `true` when the
  * object existed and was removed, `false` when it was already
  * absent. Emits `system.storage.delete` with `{ backend, key,
- * existed }` so the audit chain records GDPR right-to-erasure
+ * existed, versionId }` so the audit chain records GDPR right-to-erasure
  * flows. The sealed encryption key the caller persisted alongside
  * the row should be discarded by the caller after a successful
  * delete — without the bytes, the key has no recovery value.
  *
+ * On a versioning-enabled (S3 Object-Lock) backend an unversioned
+ * delete only writes a delete-marker — the data version survives. To
+ * erase a specific version pass `versionId` (from `saveRaw`'s return or
+ * `listVersions`); a version under an active retention is refused (the
+ * call throws), and `bypassGovernanceRetention` lifts a GOVERNANCE-mode
+ * retention for callers with the permission (COMPLIANCE stays immutable).
+ * `versionId` is S3/sigv4-only and is refused on other backends.
+ *
  * @opts
  *   classification:  string,    // route to a backend serving this classification
  *   backend:         string,    // explicit backend by name
+ *   versionId:       string,    // erase a specific object version (S3 Object-Lock)
+ *   bypassGovernanceRetention: boolean, // lift GOVERNANCE retention (not COMPLIANCE)
  *
  * @example
  *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
@@ -507,12 +519,16 @@ async function deleteFile(key, opts) {
   _requireInit();
   opts = opts || {};
   var picked = _pickBackend(opts);
-  var result = await picked.backend.delete(key);
+  var result = await picked.backend.delete(key, {
+    versionId:                 opts.versionId,
+    bypassGovernanceRetention: opts.bypassGovernanceRetention,
+  });
   _emit("system.storage.delete", {
     metadata: {
-      backend: picked.backend.name,
-      key:     key,
-      existed: result,
+      backend:   picked.backend.name,
+      key:       key,
+      existed:   result,
+      versionId: opts.versionId || null,
     },
   });
   return result;
@@ -556,6 +572,53 @@ async function exists(key, opts) {
   }
 }
 
+/**
+ * @primitive b.storage.listVersions
+ * @signature b.storage.listVersions(prefix, opts?)
+ * @since     0.15.10
+ * @status    stable
+ * @compliance gdpr, sox-404, soc2
+ * @related   b.storage.deleteFile, b.storage.saveRaw, b.worm.create
+ *
+ * Enumerate every object VERSION and delete-marker under `prefix` on a
+ * versioning-enabled (S3 Object-Lock) backend. Plain reads only see the
+ * current version; right-to-erasure / crypto-shred on an Object-Lock
+ * bucket must target prior versions by `versionId`, which only this call
+ * surfaces. Each item is `{ key, versionId, isLatest, deleteMarker, size,
+ * lastModified, etag }`; `deleteMarker: true` rows are tombstones with no
+ * data. Pair with `deleteFile(key, { versionId })` to erase a version.
+ *
+ * Versioning is an S3/sigv4 feature — a backend without a version surface
+ * (filesystem, and the current Azure/GCS adapters) throws
+ * `VERSIONS_UNSUPPORTED` rather than silently returning the current view,
+ * so an erasure workflow can never mistake a single-version backend for a
+ * fully-enumerated one.
+ *
+ * @opts
+ *   classification:   string,   // route to a backend serving this classification
+ *   backend:          string,   // explicit backend by name
+ *   maxResults:       number,   // page size
+ *   keyMarker:        string,   // pagination cursor (from a prior page)
+ *   versionIdMarker:  string,   // pagination cursor (from a prior page)
+ *
+ * @example
+ *   var page = await b.storage.listVersions("filings/2026/");
+ *   for (var v of page.items) {
+ *     if (!v.isLatest) await b.storage.deleteFile(v.key, { versionId: v.versionId });
+ *   }
+ */
+async function listVersions(prefix, opts) {
+  _requireInit();
+  opts = opts || {};
+  var picked = _pickBackend(opts);
+  if (typeof picked.backend.listVersions !== "function") {
+    throw _err("VERSIONS_UNSUPPORTED",
+      "listVersions: backend '" + picked.backend.name + "' has no version surface " +
+      "(S3/sigv4 only). A filesystem / single-version backend cannot enumerate versions.", true);
+  }
+  return picked.backend.listVersions(prefix, opts);
+}
+
 /**
  * @primitive b.storage.listBackends
  * @signature b.storage.listBackends()
@@ -1266,6 +1329,7 @@ module.exports = {
   getRawBuffer:   getRawBuffer,
   deleteFile:     deleteFile,
   exists:         exists,
+  listVersions:   listVersions,
   presignedUploadUrl:    presignedUploadUrl,
   presignedDownloadUrl:  presignedDownloadUrl,
   presignedUploadPolicy: presignedUploadPolicy,