@blamejs/blamejs-shop 0.0.113 → 0.0.114

package/lib/vendor/blamejs/lib/backup/index.js

@@ -1365,8 +1365,23 @@ function bundleAdapterStorage(opts) {
         nodeFs.writeFileSync(destPath, bytes, { flag: "wx", mode: 0o600 });
       }
     },
-    async listBundles() {
+    async listBundles(listOpts) {
       // Get every key, partition by bundleId prefix, return sorted.
+      listOpts = listOpts || {};
+      var withStats = listOpts.withStats === true;
+      // v0.12.17 — each bundle now carries the inferred format
+      // (tar / tar.gz / directory) so operators picking which
+      // bundle to restore can filter by format without touching
+      // bytes. Format is inferred from the key suffix the
+      // writeBundle path produced (rule §2 — the format is part
+      // of the storage layout, not behind a probe).
+      //
+      // Codex P2 on v0.12.17 PR #168 — track WHICH suffixes a
+      // bundle carries (set of booleans) then apply explicit
+      // precedence at the end: tar.gz > tar > directory. Matches
+      // readBundle's preference (which checks hasTarGz first)
+      // so listBundles' reported format aligns with restore
+      // behavior regardless of adapter.listKeys() order.
       var allKeys = await adapter.listKeys("");
       var byBundle = new Map();
       for (var i = 0; i < allKeys.length; i += 1) {
@@ -1377,28 +1392,334 @@ function bundleAdapterStorage(opts) {
         if (!_isValidBundleId(bid)) continue;
         var stats = byBundle.get(bid);
         if (!stats) {
-          stats = { count: 0, size: 0 };
+          stats = { count: 0, hasTar: false, hasTarGz: false, hasOther: false };
           byBundle.set(bid, stats);
         }
         stats.count += 1;
-        // Note: size is approximate — we'd need a stat-per-key here,
-        // and many adapter implementations don't expose a fast stat
-        // primitive. listBundles is best-effort; operators wanting
-        // exact size do their own walk.
+        var rest = key.slice(slash + 1);
+        if (rest === "bundle.tar")         stats.hasTar = true;
+        else if (rest === "bundle.tar.gz") stats.hasTarGz = true;
+        else                                stats.hasOther = true;
       }
       var out = [];
       var entries = Array.from(byBundle.entries());
       for (var j = 0; j < entries.length; j += 1) {
         var bidJ = entries[j][0];
-        out.push({
+        var statsJ = entries[j][1];
+        var fmtJ;
+        if (statsJ.hasTarGz)    fmtJ = "tar.gz";        // matches readBundle precedence
+        else if (statsJ.hasTar) fmtJ = "tar";
+        else                    fmtJ = "directory";
+        var entry = {
           bundleId:  bidJ,
-          createdAt: null,    // adapter may not expose mtime
-          size:      null,    // best-effort
-        });
+          format:    fmtJ,
+          createdAt: null,                    // adapter may not expose mtime
+          size:      null,                    // best-effort; operators with stat-fast adapters call bundleInfo
+        };
+        // v0.12.18 — when opts.withStats is true AND the adapter
+        // exposes statKey, fan-out a stat call per bundle's
+        // payload key. O(N) round-trips so this is opt-in;
+        // listBundles() with no opts stays cheap (single listKeys
+        // call). Operators wanting per-bundle stats but not the
+        // full bundleInfo envelope probe pick this middle ground.
+        if (withStats && typeof adapter.statKey === "function") {
+          var statKey;
+          if (statsJ.hasTarGz)    statKey = bidJ + TAR_GZ_KEY_SUFFIX;
+          else if (statsJ.hasTar) statKey = bidJ + TAR_KEY_SUFFIX;
+          else                    statKey = bidJ + "/manifest.json";
+          var sk = await adapter.statKey(statKey);
+          if (sk && typeof sk.size === "number") entry.size = sk.size;
+          if (sk && typeof sk.mtimeMs === "number") entry.createdAt = new Date(sk.mtimeMs).toISOString();
+        }
+        out.push(entry);
       }
       out.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
       return out;
     },
+    // verifyBundle(bundleId, opts?) — v0.12.19 integrity check.
+    // Walks the bundle without restoring: confirms the payload
+    // exists, the envelope (if any) decrypts under the supplied
+    // key, and the inner archive structure is well-formed (every
+    // entry enumerable). Returns `{ ok, format, envelopeKind,
+    // entryCount, errors }`. opts.recipient / opts.passphrase
+    // forwarded when the bundle is wrap-wrapped; omit them for
+    // plaintext bundles. Composes safeArchive.inspect which gates
+    // entries through bomb-policy + entry-type-policy walkers, so
+    // a malformed archive surfaces with a typed error rather than
+    // crashing the verify call.
+    async verifyBundle(bundleId, vOpts) {
+      vOpts = vOpts || {};
+      _ensureBundleId(bundleId);
+      var info;
+      try { info = await this.bundleInfo(bundleId); }
+      catch (e) {
+        return {
+          ok:           false,
+          format:       null,
+          envelopeKind: null,
+          entryCount:   0,
+          errors:       [e.code || e.message || String(e)],
+        };
+      }
+      if (info.format === "directory") {
+        // Directory format isn't archive-shaped — manifest.json
+        // existence + readability via bundleInfo IS the
+        // verification. No inspect walk applies.
+        return {
+          ok:           true,
+          format:       info.format,
+          envelopeKind: info.envelopeKind,
+          entryCount:   null,
+          errors:       [],
+        };
+      }
+      // Compose the reader chain directly so we don't depend on
+      // safeArchive's auto-sniff dispatch (which is conservative
+      // about inferring "tar.gz" from gzip-magic-only inner bytes).
+      // We already know the bundle's format + envelopeKind from
+      // bundleInfo — apply the layers in order: unwrap (if any)
+      // → gunzip (if tar.gz) → tar walker.
+      var keySuffix = info.format === "tar.gz" ? TAR_GZ_KEY_SUFFIX : TAR_KEY_SUFFIX;
+      var payload = await adapter.readFile(bundleId + keySuffix);
+      try {
+        // Layer 1 — unwrap envelope if present.
+        if (info.envelopeKind === "recipient") {
+          var rcp = vOpts.recipient !== undefined ? vOpts.recipient : recipient;
+          if (!rcp) {
+            return {
+              ok: false, format: info.format, envelopeKind: info.envelopeKind,
+              entryCount: 0, errors: ["backup/no-recipient-for-verify"],
+            };
+          }
+          payload = archiveLazy().unwrap(payload, { recipient: rcp });
+        } else if (info.envelopeKind === "passphrase") {
+          var pp = vOpts.passphrase !== undefined ? vOpts.passphrase : passphrase;
+          if (typeof pp !== "string" && !Buffer.isBuffer(pp)) {
+            return {
+              ok: false, format: info.format, envelopeKind: info.envelopeKind,
+              entryCount: 0, errors: ["backup/no-passphrase-for-verify"],
+            };
+          }
+          payload = await archiveLazy().unwrapWithPassphrase(payload, { passphrase: pp });
+        }
+        // Layer 2 — gunzip if tar.gz.
+        var tarReader;
+        if (info.format === "tar.gz") {
+          var gzReader = archiveLazy().read.gz(archiveAdaptersLazy().buffer(payload), {
+            maxDecompressedBytes: maxBundleBytes,
+            maxExpansionRatio:    0,
+          });
+          tarReader = gzReader.asTar();
+        } else {
+          tarReader = archiveLazy().read.tar(archiveAdaptersLazy().buffer(payload));
+        }
+        // Layer 3 — walk the tar entries (inspect doesn't extract).
+        var entries = await tarReader.inspect();
+        return {
+          ok:           true,
+          format:       info.format,
+          envelopeKind: info.envelopeKind,
+          entryCount:   entries.length,
+          errors:       [],
+        };
+      } catch (e) {
+        return {
+          ok:           false,
+          format:       info.format,
+          envelopeKind: info.envelopeKind,
+          entryCount:   0,
+          errors:       [e.code || e.message || String(e)],
+        };
+      }
+    },
+    // verifyAllBundles(opts?) — v0.12.20 batch integrity check.
+    // Iterates listBundles() + calls verifyBundle on each. Returns
+    // `{ total, ok, failed, results }` where `results` is an array
+    // of per-bundle verifyBundle outputs. opts.concurrency caps the
+    // parallelism (default 4 — gentle on the storage backend);
+    // opts.stopOnFirstFailure short-circuits the walk when an
+    // unhealthy bundle is found (default false — operators want
+    // the full report). opts.recipient / opts.passphrase forwarded
+    // to verifyBundle for each bundle.
+    async verifyAllBundles(vOpts) {
+      vOpts = vOpts || {};
+      // Codex P1 on v0.12.20 PR #171 — clamp fractional + zero
+      // floors so a stray `0.5` doesn't spawn zero workers + return
+      // a silent ok=0/failed=0 report on non-empty storage. Default
+      // 4; minimum 1; non-finite / non-positive falls back to
+      // default.
+      var concurrency = 4;                                                            // allow:raw-byte-literal — default fan-out, not byte count
+      if (typeof vOpts.concurrency === "number" && Number.isFinite(vOpts.concurrency) &&
+          vOpts.concurrency > 0) {
+        concurrency = Math.max(1, Math.floor(vOpts.concurrency));
+      }
+      var stopOnFirst = vOpts.stopOnFirstFailure === true;
+      var list = await this.listBundles();
+      var self = this;
+      var results = [];
+      var failed = 0;
+      var ok = 0;
+      var pending = list.slice();
+      var inflight = [];
+      var aborted = false;
+      // Sequential bounded-parallel walk. Bring up `concurrency`
+      // workers; each pulls the next bundleId until the queue is
+      // empty or stopOnFirstFailure trips.
+      function _spawn() {
+        if (aborted) return null;
+        if (pending.length === 0) return null;
+        var entry = pending.shift();
+        // Codex P2 on v0.12.20 PR #171 — wrap each worker so any
+        // verifyBundle rejection becomes a failed-result entry
+        // rather than rejecting the whole batch. Without this, a
+        // mid-walk failure (payload disappeared between listBundles
+        // + readFile, network blip on object-store, etc.) would
+        // throw out of Promise.race and abort verifyAllBundles
+        // without returning the promised aggregate report.
+        var promise = self.verifyBundle(entry.bundleId, {
+          recipient:  vOpts.recipient,
+          passphrase: vOpts.passphrase,
+        }).then(function (r) {
+          results.push(Object.assign({ bundleId: entry.bundleId }, r));
+          if (r.ok) ok += 1;
+          else {
+            failed += 1;
+            if (stopOnFirst) aborted = true;
+          }
+        }, function (err) {
+          // Rejection path — convert to a failed-result entry so
+          // the aggregate stays consistent.
+          results.push({
+            bundleId:     entry.bundleId,
+            ok:           false,
+            format:       null,
+            envelopeKind: null,
+            entryCount:   0,
+            errors:       [err && err.code ? err.code : ((err && err.message) || String(err))],
+          });
+          failed += 1;
+          if (stopOnFirst) aborted = true;
+        });
+        inflight.push(promise);
+        promise.finally(function () {
+          var idx = inflight.indexOf(promise);
+          if (idx !== -1) inflight.splice(idx, 1);
+        });
+        return promise;
+      }
+      // Warm-up: spawn up to concurrency workers.
+      var i;
+      for (i = 0; i < concurrency; i += 1) _spawn();
+      // Drain: as each worker resolves, spawn its replacement.
+      while (inflight.length > 0) {
+        await Promise.race(inflight.slice());
+        if (!aborted && pending.length > 0 && inflight.length < concurrency) {
+          while (inflight.length < concurrency && pending.length > 0) _spawn();
+        }
+      }
+      // Sort results back to listBundles order for operator-
+      // friendly output (concurrency reorders inflight completion).
+      results.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
+      return {
+        total:   list.length,
+        ok:      ok,
+        failed:  failed,
+        results: results,
+      };
+    },
+    // bundleInfo(bundleId) — v0.12.17 per-bundle introspection.
+    // Returns `{ bundleId, format, envelopeKind, sizeBytes }`.
+    // `format` is one of `"tar"` / `"tar.gz"` / `"directory"`
+    // inferred from the storage layout (no byte read).
+    // `envelopeKind` is the result of a 5-byte magic probe on the
+    // bundle payload — `"recipient"` (BAWRP) / `"passphrase"`
+    // (BAWPP) / `"none"` (plaintext). `sizeBytes` is the payload
+    // byte count for tar / tar.gz; null for directory format
+    // (operator's per-file walk if exact size matters).
+    //
+    // Instance method — wiki page documents this under the
+    // bundleAdapterStorage primitive rather than as a top-level
+    // b.X primitive.
+    async bundleInfo(bundleId) {
+      _ensureBundleId(bundleId);
+      var tarKey = bundleId + TAR_KEY_SUFFIX;
+      var tarGzKey = bundleId + TAR_GZ_KEY_SUFFIX;
+      var manifestKey = bundleId + "/manifest.json";
+      var fmt = null;
+      var payloadKey = null;
+      if (await adapter.hasKey(tarGzKey)) {
+        fmt = "tar.gz"; payloadKey = tarGzKey;
+      } else if (await adapter.hasKey(tarKey)) {
+        fmt = "tar"; payloadKey = tarKey;
+      } else if (await adapter.hasKey(manifestKey)) {
+        fmt = "directory";
+      } else {
+        throw new BackupError("backup/bundle-not-found",
+          "bundleInfo: '" + bundleId + "' not in storage");
+      }
+      var envelopeKind = "none";
+      var sizeBytes = null;
+      var createdAt = null;
+      // Codex P2 on v0.12.18 PR #169 — directory-format bundles
+      // leave payloadKey null but DO have a manifest.json that
+      // statKey can read. For createdAt parity with
+      // listBundles({ withStats }), stat the manifest in the
+      // directory case so the bundleInfo return shape is
+      // populated identically across formats.
+      if (payloadKey === null && fmt === "directory" &&
+          typeof adapter.statKey === "function") {
+        // Stat the manifest.json so directory-format bundles
+        // populate createdAt + sizeBytes identically to how
+        // listBundles({ withStats }) reports them. NOTE: sizeBytes
+        // is the manifest's size here, not the total file-tree
+        // payload (operators wanting the true total walk
+        // per-file keys themselves) — same convention as
+        // listBundles({ withStats }) for parity.
+        var dirSt = await adapter.statKey(manifestKey);
+        if (dirSt && typeof dirSt.size === "number") sizeBytes = dirSt.size;
+        if (dirSt && typeof dirSt.mtimeMs === "number") {
+          createdAt = new Date(dirSt.mtimeMs).toISOString();
+        }
+      }
+      if (payloadKey !== null) {
+        // Codex P1 on v0.12.17 PR #168 — claim was a 5-byte magic
+        // probe; the implementation was reading the entire bundle
+        // into memory. For multi-GB bundles, an administrative
+        // metadata call would allocate the whole payload and put
+        // memory pressure on the host. Prefer the adapter's
+        // optional `readPartial(key, length)` capability for the
+        // probe. fsAdapter + objectStoreAdapter both expose it as
+        // of v0.12.17; legacy adapters without it fall back to a
+        // capped 16-byte readFile via the fallback path (still
+        // bounded; better than full payload).
+        if (typeof adapter.readPartial === "function") {
+          var probe = await adapter.readPartial(payloadKey, 16);                      // allow:raw-byte-literal — 16-byte probe head, magic comparison
+          envelopeKind = archiveLazy().sniffEnvelope(probe);
+        } else {
+          // Legacy adapter — readPartial missing. Operators using
+          // a custom adapter without the capability get
+          // envelopeKind: "unknown" rather than an OOM risk. They
+          // can probe themselves by reading the first N bytes via
+          // their own client.
+          envelopeKind = "unknown";
+        }
+        // sizeBytes is reported via a stat-like path when the
+        // adapter exposes one; otherwise stays null. fsAdapter +
+        // objectStoreAdapter expose `statKey`.
+        if (typeof adapter.statKey === "function") {
+          var st = await adapter.statKey(payloadKey);
+          if (st && typeof st.size === "number") sizeBytes = st.size;
+          if (st && typeof st.mtimeMs === "number") createdAt = new Date(st.mtimeMs).toISOString();
+        }
+      }
+      return {
+        bundleId:     bundleId,
+        format:       fmt,
+        envelopeKind: envelopeKind,
+        sizeBytes:    sizeBytes,
+        createdAt:    createdAt,
+      };
+    },
     async deleteBundle(bundleId) {
       _ensureBundleId(bundleId);
       var keys = await adapter.listKeys(bundleId + "/");
@@ -1494,6 +1815,260 @@ bundleAdapterStorage.fsAdapter = function (fsOpts) {
       try { return nodeFs.existsSync(_keyPath(key)); }
       catch (_e) { return false; }
     },
+    // v0.12.17 — optional capabilities consumed by bundleInfo.
+    // readPartial: open + read up to `length` bytes from the start
+    // of the file without materializing the whole payload.
+    // Bundle-info's envelope probe needs at most 16 bytes — the
+    // partial read keeps multi-GB bundle metadata cheap.
+    async readPartial(key, length) {
+      // CodeQL js/file-system-race + js/insecure-temporary-file —
+      // drop the existsSync probe (TOCTOU) and the default mode on
+      // open. Use openSync with explicit owner-only mode + handle
+      // ENOENT atomically; the system call is itself the existence
+      // check.
+      var p = _keyPath(key);
+      var fd;
+      try {
+        fd = nodeFs.openSync(p, "r", 0o600);
+      } catch (e) {
+        if (e && e.code === "ENOENT") {
+          throw new BackupError("backup/no-key",
+            "fsAdapter.readPartial: key not found: " + JSON.stringify(key));
+        }
+        throw e;
+      }
+      try {
+        var buf = Buffer.alloc(length);
+        var bytesRead = nodeFs.readSync(fd, buf, 0, length, 0);
+        return buf.slice(0, bytesRead);
+      } finally {
+        try { nodeFs.closeSync(fd); } catch (_e) { /* drop-silent */ }
+      }
+    },
+    async statKey(key) {
+      var p = _keyPath(key);
+      if (!nodeFs.existsSync(p)) return null;
+      var st = nodeFs.statSync(p);
+      return { size: st.size, mtimeMs: st.mtimeMs };
+    },
+  };
+};
+
+// ---- v0.12.13: objectStoreAdapter ----------------------------------------
+
+/**
+ * @primitive b.backup.bundleAdapterStorage.objectStoreAdapter
+ * @signature b.backup.bundleAdapterStorage.objectStoreAdapter(client, opts?)
+ * @since     0.12.13
+ * @status    stable
+ * @related   b.backup.bundleAdapterStorage, b.objectStore
+ *
+ * Wraps a `b.objectStore`-shaped client into the
+ * `{ writeFile, readFile, listKeys, deleteKey, hasKey }` adapter
+ * contract that `bundleAdapterStorage` consumes. The client must
+ * expose `put(key, body) → Promise<{ size }>`, `get(key) →
+ * Promise<Buffer>`, `head(key) → Promise<{ size, ... }>`,
+ * `delete(key) → Promise<boolean>`, and `list(prefix, opts?) →
+ * Promise<{ items: [{ key, size, ... }], truncated }>` — the
+ * shape produced by `b.objectStore.buildBackend({ protocol: ... })`
+ * for the local / SigV4 / GCS / Azure-Blob backends.
+ *
+ * `opts.prefix` namespaces every key under a fixed root inside the
+ * bucket — operators sharing a bucket across multiple deployments
+ * pass distinct prefixes so listings stay scoped.
+ *
+ * `opts.list` is the operator-tunable `{ maxResults, ... }` pass-
+ * through forwarded to the underlying `client.list` call (defaults
+ * to whatever the backend's `list` defaults to — typically 1000).
+ *
+ * Closes the v0.12.10 deferral: "S3 / MinIO / Azure / GCS-backed
+ * backups" promised since v0.11.2 JSDoc.
+ *
+ * @opts
+ *   prefix:  string,    // namespace every key under this prefix in the bucket
+ *   list:    { maxResults: number },   // forwarded to client.list opts
+ *
+ * @example
+ *   var client = b.objectStore.buildBackend({
+ *     protocol: "local",
+ *     rootDir:  "/var/backups",
+ *   });
+ *   var storage = b.backup.bundleAdapterStorage({
+ *     adapter:        b.backup.bundleAdapterStorage.objectStoreAdapter(client),
+ *     format:         "tar.gz",
+ *     cryptoStrategy: "recipient",
+ *     recipient:      pair,
+ *   });
+ *   // bundle bytes hit the object-store backend's put(); restore
+ *   // path composes through unwrap + read.gz + read.tar.
+ */
+bundleAdapterStorage.objectStoreAdapter = function (client, osOpts) {
+  if (!client || typeof client !== "object") {
+    throw new BackupError("backup/bad-adapter",
+      "objectStoreAdapter: client is required (a b.objectStore-shaped object with put / get / head / delete / list)");
+  }
+  var required = ["put", "get", "head", "delete", "list"];
+  for (var i = 0; i < required.length; i += 1) {
+    if (typeof client[required[i]] !== "function") {
+      throw new BackupError("backup/bad-adapter",
+        "objectStoreAdapter: client missing method '" + required[i] + "'");
+    }
+  }
+  osOpts = osOpts || {};
+  var prefix = "";
+  if (osOpts.prefix !== undefined && osOpts.prefix !== null) {
+    if (typeof osOpts.prefix !== "string") {
+      throw new BackupError("backup/bad-arg",
+        "objectStoreAdapter: opts.prefix must be a string");
+    }
+    if (osOpts.prefix.indexOf("..") !== -1 || osOpts.prefix.indexOf("\u0000") !== -1) {
+      throw new BackupError("backup/bad-arg",
+        "objectStoreAdapter: opts.prefix contains traversal segment or NUL byte");
+    }
+    // Strip trailing slashes without a backtracking regex (CodeQL
+    // js/polynomial-redos flagged `/\/+$/`, which is linear in
+    // practice but flagged conservatively). Walk back from the end
+    // and slice once.
+    var endIdx = osOpts.prefix.length;
+    while (endIdx > 0 && osOpts.prefix.charCodeAt(endIdx - 1) === 0x2f) endIdx -= 1;  // 0x2f = "/"
+    prefix = osOpts.prefix.slice(0, endIdx);
+    if (prefix.length > 0) prefix += "/";
+  }
+  var listOpts = osOpts.list || {};
+
+  function _scopedKey(key) {
+    if (typeof key !== "string" || key.length === 0) {
+      throw new BackupError("backup/bad-key",
+        "objectStoreAdapter: key must be a non-empty string");
+    }
+    if (key.indexOf("..") !== -1 || key.indexOf("\u0000") !== -1) {
+      throw new BackupError("backup/bad-key",
+        "objectStoreAdapter: key contains traversal segment or NUL byte");
+    }
+    return prefix + key;
+  }
+
+  return {
+    async writeFile(key, bytes) {
+      if (!Buffer.isBuffer(bytes) && !(bytes instanceof Uint8Array)) {
+        throw new BackupError("backup/bad-arg",
+          "objectStoreAdapter.writeFile: bytes must be a Buffer or Uint8Array");
+      }
+      await client.put(_scopedKey(key), Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes));
+    },
+    async readFile(key) {
+      var scoped = _scopedKey(key);
+      try {
+        var body = await client.get(scoped);
+        return Buffer.isBuffer(body) ? body : Buffer.from(body);
+      } catch (e) {
+        // b.objectStore surfaces NOT_FOUND via the framework's
+        // err.code === "NOT_FOUND" convention — translate to the
+        // backup adapter contract's no-key error.
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          throw new BackupError("backup/no-key",
+            "objectStoreAdapter: key not found: " + JSON.stringify(key));
+        }
+        throw e;
+      }
+    },
+    async listKeys(keyPrefix) {
+      // _scopedKey rejects empty strings; for list(prefix) we want
+      // to allow listing the whole bundle root. Compose the
+      // prefix manually so `listKeys("")` enumerates everything
+      // under the operator-supplied namespace.
+      var realScoped = prefix + (keyPrefix || "");
+      // Codex P1 on v0.12.13 PR #164 — object-store backends page
+      // results (default 1000 keys). Without continuation, listKeys
+      // silently dropped bundles past page 1 — listBundles missed
+      // them, deleteBundle skipped them. Follow the
+      // truncated / continuationToken contract until every page
+      // is consumed. PAGINATION_CAP guards against a runaway
+      // server returning truncated:true forever (defense-in-depth;
+      // shipped backends honour the contract).
+      var PAGINATION_CAP = 1000;                                                      // allow:raw-byte-literal — page count cap, not byte count
+      var out = [];
+      var token = null;
+      var pages = 0;
+      do {
+        var pageOpts = Object.assign({}, listOpts);
+        if (token) pageOpts.continuationToken = token;
+        var result = await client.list(realScoped, pageOpts);
+        var items = result && result.items ? result.items : (Array.isArray(result) ? result : []);
+        for (var i = 0; i < items.length; i += 1) {
+          var k = typeof items[i] === "string" ? items[i] : items[i].key;
+          if (typeof k !== "string") continue;
+          if (prefix.length > 0 && k.indexOf(prefix) === 0) {
+            out.push(k.slice(prefix.length));
+          } else {
+            out.push(k);
+          }
+        }
+        token = result && result.continuationToken ? result.continuationToken : null;
+        if (!result || result.truncated !== true) break;
+        if (!token) break;                                                            // truncated:true without continuationToken — stop to avoid spin
+        pages += 1;
+        if (pages > PAGINATION_CAP) {
+          throw new BackupError("backup/list-pagination-runaway",
+            "objectStoreAdapter.listKeys: backend returned >" + PAGINATION_CAP +
+            " pages without exhausting; refusing to spin (operator should narrow the prefix or raise opts.list.maxResults)");
+        }
+      } while (true);
+      return out;
+    },
+    async deleteKey(key) {
+      try {
+        await client.delete(_scopedKey(key));
+      } catch (e) {
+        // drop-silent on NOT_FOUND — adapter contract is idempotent
+        // delete (fsAdapter same shape).
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          return;
+        }
+        throw e;
+      }
+    },
+    async hasKey(key) {
+      try {
+        await client.head(_scopedKey(key));
+        return true;
+      } catch (e) {
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          return false;
+        }
+        throw e;
+      }
+    },
+    // v0.12.17 — readPartial uses the b.objectStore client's range
+    // capability (every shipped backend honours `{ range: [start,
+    // end] }` per the client contract). bundleInfo's envelope probe
+    // reads 16 bytes regardless of bundle size.
+    async readPartial(key, length) {
+      var scoped = _scopedKey(key);
+      try {
+        var body = await client.get(scoped, { range: [0, Math.max(0, length - 1)] });
+        var buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+        return buf.slice(0, length);
+      } catch (e) {
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          throw new BackupError("backup/no-key",
+            "objectStoreAdapter.readPartial: key not found: " + JSON.stringify(key));
+        }
+        throw e;
+      }
+    },
+    async statKey(key) {
+      try {
+        var meta = await client.head(_scopedKey(key));
+        if (!meta || typeof meta.size !== "number") return null;
+        return { size: meta.size, mtimeMs: meta.lastModified || null };
+      } catch (e) {
+        if (e && (e.code === "NOT_FOUND" || /NOT_FOUND|not found/i.test(e.message || ""))) {
+          return null;
+        }
+        throw e;
+      }
+    },
   };
 };