@blamejs/core 0.9.43 → 0.9.46

package/lib/middleware/protected-resource-metadata.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * @module     b.middleware.protectedResourceMetadata
- * @nav        Identity & access
+ * @nav        Identity
  * @title      Protected Resource Metadata
  * @order      210
  * @slug       protected-resource-metadata

package/lib/network-dns-resolver.js

@@ -107,6 +107,7 @@
 var C                  = require("./constants");
 var https              = require("node:https");
 var nodeCrypto         = require("node:crypto");
+var bCrypto            = require("./crypto");
 var { defineClass }    = require("./framework-error");
 var networkDns         = require("./network-dns");
 var safeDns            = require("./safe-dns");
@@ -413,7 +414,7 @@ async function _wireLookup(name, qtype) {
   var url = networkDns._getDohUrlForTest ? networkDns._getDohUrlForTest() : "https://cloudflare-dns.com/dns-query";
   // Encode a wire-format query for the target qtype.
   var qbuf = _encodeWireQuery(name, qtype);
-  var b64 = qbuf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  var b64 = bCrypto.toBase64Url(qbuf);
   var getUrl = url + (url.indexOf("?") === -1 ? "?" : "&") + "dns=" + b64;
   var u = safeUrl.parse(getUrl, { allowedProtocols: safeUrl.ALLOW_HTTP_TLS });
   return new Promise(function (resolve, reject) {

package/lib/network-dns.js

@@ -8,6 +8,7 @@ var nodeTls = require("node:tls");
 var dnsPromises = dns.promises;
 
 var C = require("./constants");
+var bCrypto = require("./crypto");
 var lazyRequire = require("./lazy-require");
 var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
@@ -368,7 +369,7 @@ var DOH_GET_URL_MAX_BYTES = 2048;
 async function _dohLookup(host, family) {
   var qtype = family === 6 ? 28 : 1;
   var enc = _encodeDnsQuery(host, qtype);
-  var b64 = enc.buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  var b64 = bCrypto.toBase64Url(enc.buf);
   var getUrl = STATE.doh.url + (STATE.doh.url.indexOf("?") === -1 ? "?" : "&") + "dns=" + b64;
   var forcedMethod = STATE.doh.method;
   var usePost = forcedMethod === "POST" || (!forcedMethod && getUrl.length > DOH_GET_URL_MAX_BYTES);
@@ -437,7 +438,7 @@ async function _dohLookup(host, family) {
 async function _dohLookupSecure(host, family) {
   var qtype = family === 6 ? 28 : 1;                                             // allow:raw-byte-literal — DNS QTYPE values for A / AAAA
   var enc = _encodeDnsQuery(host, qtype);
-  var b64 = enc.buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  var b64 = bCrypto.toBase64Url(enc.buf);
   var getUrl = STATE.doh.url + (STATE.doh.url.indexOf("?") === -1 ? "?" : "&") + "dns=" + b64;
   var forcedMethod = STATE.doh.method;
   var usePost = forcedMethod === "POST" || (!forcedMethod && getUrl.length > DOH_GET_URL_MAX_BYTES);
@@ -792,7 +793,7 @@ function _decodeDnsAnswerRaw(buf) {
 
 async function _dohRawQuery(host, qtype) {
   var enc = _encodeDnsQuery(host, qtype);
-  var b64 = enc.buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+  var b64 = bCrypto.toBase64Url(enc.buf);
   var getUrl = STATE.doh.url + (STATE.doh.url.indexOf("?") === -1 ? "?" : "&") + "dns=" + b64;
   var forcedMethod = STATE.doh.method;
   var usePost = forcedMethod === "POST" || (!forcedMethod && getUrl.length > DOH_GET_URL_MAX_BYTES);

package/lib/object-store/gcs.js

@@ -25,6 +25,7 @@
 var nodeFs = require("node:fs");
 var nodeCrypto = require("node:crypto");
 var { Readable } = require("node:stream");
+var bCrypto = require("../crypto");
 var safeJson = require("../safe-json");
 var C = require("../constants");
 var numericBounds = require("../numeric-bounds");
@@ -88,12 +89,7 @@ var _httpRequest = sharedRequest;
 
 // ---- JWT signing for service-account auth ----
 
-function _base64UrlEncode(buf) {
-  return Buffer.from(buf).toString("base64")
-    .replace(/=+$/g, "")
-    .replace(/\+/g, "-")
-    .replace(/\//g, "_");
-}
+function _base64UrlEncode(buf) { return bCrypto.toBase64Url(buf); }
 
 function _signJwt(serviceAccount, scope, audience) {
   var nowSec = Math.floor(Date.now() / C.TIME.seconds(1));

package/lib/pagination.js

@@ -83,16 +83,11 @@ function _toBuf(secret) {
     "secret must be a Buffer or non-empty string");
 }
 
-function _b64urlEncode(buf) {
-  var b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
-  return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
+function _b64urlEncode(buf) { return bCrypto.toBase64Url(buf); }
 
 function _b64urlDecode(s) {
   if (typeof s !== "string") throw new PaginationError("pagination/bad-cursor", "cursor must be a string");
-  var pad = s.length % 4;
-  var padded = pad ? s + "=".repeat(4 - pad) : s;
-  return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+  return bCrypto.fromBase64Url(s);
 }
 
 function _tag(secretBuf, stateJson) {

package/lib/safe-smtp.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * @module     b.safeSmtp
+ * @nav        Parsers
+ * @title      Safe SMTP
+ * @order      215
+ *
+ * @intro
+ *   Wire-protocol parsing helpers for SMTP (RFC 5321) bytes.
+ *   Operators consuming the framework's MX listener (`b.mail.server.mx`),
+ *   submission listener (slice that follows), or building their own
+ *   SMTP-shaped tooling (proxies, log analyzers, test fixtures) reach
+ *   for these primitives rather than reinventing the dot-terminator
+ *   scan + dot-stuffing reversal.
+ *
+ *   Separates the "what shape is the wire data" parsing concern from
+ *   the "is this wire data hostile" guard concern (which lives in
+ *   `b.guardSmtpCommand`). A safe-* parser primitive returns a
+ *   bounded shape or `-1`; a guard-* primitive returns a boolean
+ *   threat verdict or throws a typed error.
+ *
+ *   Wire-protocol references:
+ *     - RFC 5321 §2.3.8 — line termination MUST be CRLF
+ *     - RFC 5321 §4.5.2 — dot-stuffing on the SMTP body
+ *     - RFC 5321 §4.1.1.4 — DATA command terminates with `<CRLF>.<CRLF>`
+ *     - CVE-2023-51764 / -51765 / -51766 / 2024-32178 — SMTP
+ *       smuggling (parsers that accept bare-LF dot-terminators).
+ *       The guard primitive `b.guardSmtpCommand.detectBodySmuggling`
+ *       owns smuggling detection; the safe-* terminator scanner
+ *       here is strict CRLF-only by construction.
+ *
+ * @card
+ *   Wire-protocol parsing helpers for SMTP (RFC 5321) bytes —
+ *   findDotTerminator + dotUnstuff. Strict CRLF-only by construction
+ *   (bare-LF terminators are not honored — the smuggling-detection
+ *   guard lives in b.guardSmtpCommand.detectBodySmuggling).
+ */
+
+var { defineClass } = require("./framework-error");
+
+var SafeSmtpError = defineClass("SafeSmtpError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.safeSmtp.findDotTerminator
+ * @signature b.safeSmtp.findDotTerminator(buf)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.safeSmtp.dotUnstuff, b.guardSmtpCommand.detectBodySmuggling
+ *
+ * Scan `buf` for the canonical RFC 5321 §4.1.1.4 DATA-body terminator
+ * `<CRLF>.<CRLF>` (5 bytes: 0x0d 0x0a 0x2e 0x0d 0x0a). Returns the
+ * byte index where the body ends (exclusive — the index of the
+ * trailing CRLF the terminator starts on), or `-1` if the terminator
+ * is not yet present.
+ *
+ * Strict CRLF-only by construction — bare-LF alternate terminators
+ * are NOT honored. Operators worried about smuggling shape route the
+ * SAME body through `b.guardSmtpCommand.detectBodySmuggling` before
+ * trusting the terminator index returned here.
+ *
+ * @example
+ *   var body = Buffer.from("Hello world.\r\n.\r\n");
+ *   b.safeSmtp.findDotTerminator(body);
+ *   // → 13  (index of \r in \r\n.\r\n)
+ *
+ *   b.safeSmtp.findDotTerminator(Buffer.from("incomplete body"));
+ *   // → -1
+ */
+function findDotTerminator(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "findDotTerminator: input must be a Buffer");
+  }
+  for (var i = 0; i <= buf.length - 5; i += 1) {                                                     // allow:raw-byte-literal — 5-byte CRLF.CRLF terminator length
+    if (buf[i] === 0x0d && buf[i + 1] === 0x0a &&
+        buf[i + 2] === 0x2e &&
+        buf[i + 3] === 0x0d && buf[i + 4] === 0x0a) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * @primitive b.safeSmtp.dotUnstuff
+ * @signature b.safeSmtp.dotUnstuff(buf)
+ * @since     0.9.46
+ * @status    stable
+ * @related   b.safeSmtp.findDotTerminator
+ *
+ * Reverse RFC 5321 §4.5.2 dot-stuffing on a DATA-body buffer. SMTP
+ * senders that need to transmit a body line beginning with `.` MUST
+ * prepend an extra `.` (so the line on the wire begins with `..`);
+ * the receiver strips the leading `.` from any body line that
+ * begins with one before storing the message. Returns a fresh
+ * Buffer with the dots reversed; the input is never mutated. Result
+ * length is always `<= input length`.
+ *
+ * @example
+ *   var wire = Buffer.from("hello\r\n..secret\r\nworld\r\n");
+ *   b.safeSmtp.dotUnstuff(wire).toString("utf8");
+ *   // → "hello\r\n.secret\r\nworld\r\n"
+ */
+function dotUnstuff(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    throw new SafeSmtpError("safe-smtp/bad-input",
+      "dotUnstuff: input must be a Buffer");
+  }
+  var out = Buffer.alloc(buf.length);
+  var oi = 0;
+  for (var i = 0; i < buf.length; i += 1) {
+    out[oi++] = buf[i];
+    // After \r\n, if the next byte is `.` followed by another non-CR
+    // byte (i.e., not the terminator itself), strip the stuffing dot.
+    if (i >= 1 && buf[i - 1] === 0x0d && buf[i] === 0x0a &&
+        i + 1 < buf.length && buf[i + 1] === 0x2e &&
+        i + 2 < buf.length && buf[i + 2] !== 0x0d) {
+      i += 1;
+    }
+  }
+  return out.subarray(0, oi);
+}
+
+module.exports = {
+  findDotTerminator: findDotTerminator,
+  dotUnstuff:        dotUnstuff,
+  SafeSmtpError:     SafeSmtpError,
+};

package/lib/storage.js

@@ -41,6 +41,8 @@ var C = require("./constants");
 var { generateBytes, encryptPacked, decryptPacked } = require("./crypto");
 var objectStore = require("./object-store");
 var lazyRequire = require("./lazy-require");
+var numericBounds = require("./numeric-bounds");
+var canonicalJson = require("./canonical-json");
 var { StorageError } = require("./framework-error");
 
 var vault = lazyRequire(function () { return require("./vault"); });
@@ -827,6 +829,420 @@ function _requireInit() {
   if (!initialized) throw _err("NOT_INITIALIZED", "storage.init() must be called before any file operation", true);
 }
 
+// ---- chunk-scratch -------------------------------------------------
+//
+// Resumable-chunked-upload primitive. Operators handling large file
+// uploads (multipart form / tus / S3-multipart-style flow) need to
+// persist incoming chunks during the upload window, then assemble
+// them into a final file when the upload completes. Without a
+// framework primitive every consumer ended up reinventing the
+// per-assembly directory layout + atomic finalize + GC of partial
+// assemblies that never completed.
+//
+// chunkScratch owns:
+//   - per-assembly directory layout (sealed in the operator's
+//     storage backend just like saveFile)
+//   - chunk persistence + retrieval with the framework envelope
+//   - assembly metadata tracking createdAt/totalChunks/chunkHashes
+//   - atomic concat into the final file (no consumer ever sees a
+//     half-assembled file)
+//   - GC of stale partial assemblies (operator opts in via gc())
+//
+// Backend is the same `b.storage` backend the operator already
+// configured — chunkScratch routes through it. No new backend
+// concept. The chunk keys are namespaced under
+// `<rootKeyPrefix>/<assemblyId>/<chunkIndex>` so the operator can
+// see them via the backend's existing list/inspect surface.
+//
+// assemblyId is operator-supplied (typically a UUID tied to the
+// upload session). Shape is validated to refuse path-traversal,
+// slash/backslash, NUL/C0/DEL, oversize. The chunkScratch primitive
+// is identity-agnostic — it doesn't know which user owns which
+// assembly; that gate is the operator's surrounding handler.
+
+var ASSEMBLY_ID_MAX_LEN  = 128;
+var CHUNK_INDEX_MAX      = 100000;                                                                  // allow:raw-byte-literal — chunk-index cap (not bytes, not seconds)
+var CHUNK_BYTES_DEFAULT  = C.BYTES.mib(16);
+var STALE_DEFAULT_MS     = C.TIME.hours(24);
+
+function _stripTrailingSlashes(s) {
+  // Linear-time alternative to `.replace(/\/+$/, "")` — CodeQL flags the
+  // regex form as polynomial-ReDoS-vulnerable on inputs with many
+  // trailing slashes (theoretical here since rootKeyPrefix is operator-
+  // supplied at create-time, not request-bound, but using the explicit
+  // loop avoids the regex-engine backtracking surface entirely).
+  var end = s.length;
+  while (end > 0 && s.charCodeAt(end - 1) === 0x2F /* / */) end -= 1;
+  return end === s.length ? s : s.slice(0, end);
+}
+
+function _validateAssemblyId(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw _err("INVALID_ARGUMENT", "chunkScratch: assemblyId must be a non-empty string", true);
+  }
+  if (id.length > ASSEMBLY_ID_MAX_LEN) {
+    throw _err("INVALID_ARGUMENT",
+      "chunkScratch: assemblyId exceeds " + ASSEMBLY_ID_MAX_LEN + "-char cap", true);
+  }
+  for (var i = 0; i < id.length; i += 1) {
+    var c = id.charCodeAt(i);
+    // Refuse: C0 (0x00-0x1F), DEL (0x7F), slash, backslash, dot-prefix
+    if (c < 0x20 || c === 0x2F || c === 0x5C || c === 0x7F) {
+      throw _err("INVALID_ARGUMENT",
+        "chunkScratch: assemblyId carries forbidden character at byte " + i, true);
+    }
+  }
+  // Refuse path-traversal shapes — operator-supplied ID should be a
+  // UUID-shape or opaque session token, not a path.
+  if (id.indexOf("..") !== -1 || id.charAt(0) === ".") {
+    throw _err("INVALID_ARGUMENT",
+      "chunkScratch: assemblyId carries path-traversal shape", true);
+  }
+}
+
+function _validateChunkIndex(idx) {
+  if (typeof idx !== "number" || !Number.isInteger(idx) || idx < 0) {
+    throw _err("INVALID_ARGUMENT",
+      "chunkScratch: chunkIndex must be a non-negative integer", true);
+  }
+  if (idx >= CHUNK_INDEX_MAX) {
+    throw _err("INVALID_ARGUMENT",
+      "chunkScratch: chunkIndex exceeds cap " + CHUNK_INDEX_MAX, true);
+  }
+}
+
+/**
+ * @primitive b.storage.chunkScratch
+ * @signature b.storage.chunkScratch(opts?)
+ * @since     0.9.44
+ * @status    stable
+ * @related   b.storage.saveFile, b.storage.getFileBuffer
+ *
+ * Resumable-chunked-upload primitive. Persists incoming upload chunks
+ * during the upload window + atomically assembles them into the
+ * final file on completion. Owns per-assembly directory layout,
+ * envelope-encrypted chunk persistence, atomic finalize, and GC of
+ * partial assemblies.
+ *
+ * Composes existing primitives: each chunk routes through
+ * `b.storage.saveFile` (same XChaCha20-Poly1305 envelope as the
+ * non-chunked surface), assembly reads through `getFileBuffer`,
+ * deletion through `deleteFile`. No new crypto.
+ *
+ * Prior art / wire-protocol references:
+ *   - tus.io v1.0.0 protocol (Termination + Creation + Concatenation
+ *     extensions) — operator-facing HTTP shape that ships chunks
+ *     against a server-side assembly. This primitive is the
+ *     server-side persistence the tus protocol's upload handler
+ *     consumes.
+ *   - RFC 9110 §14.4 Content-Range — the wire-protocol header that
+ *     PUT/PATCH-based resumable uploads use to declare each chunk's
+ *     byte-range within the assembly.
+ *   - draft-ietf-httpbis-resumable-upload-08 — IETF working-draft
+ *     resumable-upload protocol; this primitive's surface mirrors
+ *     its server-side state requirements.
+ *   - AWS S3 Multipart Upload — the cloud-vendor analogue;
+ *     `saveChunk` / `assemble` are the framework's local equivalents
+ *     of UploadPart / CompleteMultipartUpload.
+ *
+ * Threat-model coverage:
+ *   - Path-traversal in upload paths (CVE-2018-1000656 class) —
+ *     `assemblyId` is validated to refuse `..`, `/`, `\`, NUL / C0
+ *     controls, DEL, dot-prefix, and oversize. A hostile client
+ *     can't escape the rootKeyPrefix namespace.
+ *   - Chunk-out-of-order replay / TOCTOU between saveChunk and
+ *     assemble — `assemble` verifies monotonic 0..N-1 indices and
+ *     refuses on gaps; a chunk inserted out-of-order can't be
+ *     surfaced as a valid assembly.
+ *   - Storage exhaustion from abandoned uploads — `gc({ olderThanMs })`
+ *     prunes stale assemblies; operator wires it on a schedule.
+ *   - AEAD context-binding — each chunk's encryption envelope is
+ *     keyed independently; an attacker who guesses one chunk's key
+ *     can't decrypt other chunks in the same assembly (the
+ *     XChaCha20-Poly1305 keys are framework-vault-derived per-call).
+ *
+ * assemblyId shape is validated to refuse path-traversal, control
+ * chars, and oversize at every entry point.
+ *
+ * @opts
+ *   rootKeyPrefix: string,   // default "chunk-scratch" — namespace under the backend
+ *   backend:       string,   // explicit backend by name (default: framework default)
+ *   maxChunkBytes: number,   // default 16 MiB — per-chunk cap
+ *   staleAfterMs:  number,   // default 24h — assemblies idle longer get GC'd
+ *
+ * @example
+ *   b.storage.init({ backend: "local", uploadDir: "./data/uploads" });
+ *   var cs = b.storage.chunkScratch({ rootKeyPrefix: "uploads/scratch" });
+ *
+ *   // During upload — each PUT lands one chunk
+ *   await cs.saveChunk({ assemblyId: "upload-abc", chunkIndex: 0, data: chunk0 });
+ *   await cs.saveChunk({ assemblyId: "upload-abc", chunkIndex: 1, data: chunk1 });
+ *   await cs.saveChunk({ assemblyId: "upload-abc", chunkIndex: 2, data: chunk2 });
+ *
+ *   // On completion — atomic assemble + cleanup
+ *   var assembled = await cs.assemble({ assemblyId: "upload-abc", expectedTotal: 3 });
+ *   await cs.removeAssembly("upload-abc");
+ *
+ *   // Periodic GC of partial uploads abandoned mid-stream
+ *   var removed = await cs.gc({ olderThanMs: 86400000 });
+ */
+function chunkScratch(opts) {
+  _requireInit();
+  opts = opts || {};
+  var rootKeyPrefix = typeof opts.rootKeyPrefix === "string" && opts.rootKeyPrefix.length > 0
+    ? _stripTrailingSlashes(opts.rootKeyPrefix)
+    : "chunk-scratch";
+  numericBounds.requirePositiveFiniteIntIfPresent(
+    opts.maxChunkBytes, "chunkScratch.maxChunkBytes", StorageError, "INVALID_ARGUMENT");
+  numericBounds.requirePositiveFiniteIntIfPresent(
+    opts.staleAfterMs, "chunkScratch.staleAfterMs", StorageError, "INVALID_ARGUMENT");
+  var maxChunkBytes = opts.maxChunkBytes !== undefined ? opts.maxChunkBytes : CHUNK_BYTES_DEFAULT;
+  var staleAfterMs  = opts.staleAfterMs  !== undefined ? opts.staleAfterMs  : STALE_DEFAULT_MS;
+  var backendOverride = opts.backend;
+
+  function _chunkKey(assemblyId, chunkIndex) {
+    return rootKeyPrefix + "/" + assemblyId + "/" + String(chunkIndex).padStart(8, "0") + ".chunk";   // allow:raw-byte-literal — 8-digit zero-pad covers CHUNK_INDEX_MAX
+  }
+  function _pickOpts() {
+    return backendOverride ? { backend: backendOverride } : {};
+  }
+
+  async function saveChunk(args) {
+    if (!args || typeof args !== "object") {
+      throw _err("INVALID_ARGUMENT", "chunkScratch.saveChunk: args must be an object", true);
+    }
+    _validateAssemblyId(args.assemblyId);
+    _validateChunkIndex(args.chunkIndex);
+    if (!Buffer.isBuffer(args.data)) {
+      throw _err("INVALID_ARGUMENT", "chunkScratch.saveChunk: data must be a Buffer", true);
+    }
+    if (args.data.length > maxChunkBytes) {
+      throw _err("INVALID_ARGUMENT",
+        "chunkScratch.saveChunk: chunk exceeds maxChunkBytes (" + args.data.length + " > " + maxChunkBytes + ")", true);
+    }
+    var saved = await saveFile(args.data, _chunkKey(args.assemblyId, args.chunkIndex), _pickOpts());
+    _emit("system.storage.chunk_scratch.chunk_saved", {
+      metadata: {
+        assemblyId: args.assemblyId,
+        chunkIndex: args.chunkIndex,
+        sizeBytes:  args.data.length,
+        backend:    saved.backend,
+      },
+    });
+    return { encryptionKey: saved.encryptionKey, sizeBytes: args.data.length };
+  }
+
+  async function getChunk(args) {
+    if (!args || typeof args !== "object") {
+      throw _err("INVALID_ARGUMENT", "chunkScratch.getChunk: args must be an object", true);
+    }
+    _validateAssemblyId(args.assemblyId);
+    _validateChunkIndex(args.chunkIndex);
+    if (typeof args.encryptionKey !== "string" || args.encryptionKey.length === 0) {
+      throw _err("INVALID_ARGUMENT", "chunkScratch.getChunk: encryptionKey required", true);
+    }
+    return getFileBuffer(_chunkKey(args.assemblyId, args.chunkIndex),
+      args.encryptionKey, _pickOpts());
+  }
+
+  async function chunkExists(args) {
+    _validateAssemblyId(args.assemblyId);
+    _validateChunkIndex(args.chunkIndex);
+    return exists(_chunkKey(args.assemblyId, args.chunkIndex), _pickOpts());
+  }
+
+  async function listChunks(assemblyId) {
+    _validateAssemblyId(assemblyId);
+    var picked = _pickBackend(_pickOpts());
+    if (typeof picked.backend.list !== "function") {
+      throw _err("UNSUPPORTED",
+        "chunkScratch.listChunks: backend '" + picked.backend.name + "' does not implement list()", true);
+    }
+    var prefix = rootKeyPrefix + "/" + assemblyId + "/";
+    var listRes = await picked.backend.list(prefix);
+    var items = listRes && Array.isArray(listRes.items) ? listRes.items
+              : Array.isArray(listRes) ? listRes : [];
+    var indices = [];
+    for (var i = 0; i < items.length; i += 1) {
+      // Backends return either { key, size, lastModified } objects
+      // (local + S3 + GCS) or bare key strings. Normalize.
+      var item = items[i];
+      var rawKey = typeof item === "string" ? item : item && item.key;
+      if (typeof rawKey !== "string") continue;
+      // The local backend's `list(prefix)` returns keys relative to
+      // the prefix; cloud backends return absolute keys. Normalize
+      // by stripping the prefix when present.
+      var base = rawKey.indexOf(prefix) === 0 ? rawKey.slice(prefix.length) : rawKey;
+      if (base === ".meta" || base.indexOf("/") !== -1) continue;
+      if (!/^[0-9]{1,8}\.chunk$/.test(base)) continue;
+      indices.push(parseInt(base.slice(0, -6), 10));
+    }
+    indices.sort(function (a, b) { return a - b; });
+    return indices;
+  }
+
+  async function countChunks(assemblyId) {
+    var indices = await listChunks(assemblyId);
+    return indices.length;
+  }
+
+  async function removeChunk(args) {
+    _validateAssemblyId(args.assemblyId);
+    _validateChunkIndex(args.chunkIndex);
+    return deleteFile(_chunkKey(args.assemblyId, args.chunkIndex), _pickOpts());
+  }
+
+  async function assemble(args) {
+    if (!args || typeof args !== "object") {
+      throw _err("INVALID_ARGUMENT", "chunkScratch.assemble: args must be an object", true);
+    }
+    _validateAssemblyId(args.assemblyId);
+    if (!Array.isArray(args.chunkEncryptionKeys) || args.chunkEncryptionKeys.length === 0) {
+      throw _err("INVALID_ARGUMENT",
+        "chunkScratch.assemble: chunkEncryptionKeys must be a non-empty array (one per chunk in order)", true);
+    }
+    var indices = await listChunks(args.assemblyId);
+    if (typeof args.expectedTotal === "number" && indices.length !== args.expectedTotal) {
+      throw _err("INCOMPLETE_ASSEMBLY",
+        "chunkScratch.assemble: have " + indices.length + " chunks; expected " + args.expectedTotal, true);
+    }
+    if (indices.length !== args.chunkEncryptionKeys.length) {
+      throw _err("INVALID_ARGUMENT",
+        "chunkScratch.assemble: chunkEncryptionKeys.length (" + args.chunkEncryptionKeys.length +
+        ") must match chunk count (" + indices.length + ")", true);
+    }
+    // Verify monotonic 0..N-1 indices — no gaps.
+    for (var i = 0; i < indices.length; i += 1) {
+      if (indices[i] !== i) {
+        throw _err("INCOMPLETE_ASSEMBLY",
+          "chunkScratch.assemble: chunk gap at index " + i + " (found " + indices[i] + ")", true);
+      }
+    }
+    // Concatenate in order. Each chunk decrypts via its own envelope
+    // key; the operator persisted the per-chunk key when saveChunk
+    // returned it.
+    var parts = [];
+    var totalBytes = 0;
+    for (var c = 0; c < indices.length; c += 1) {
+      var buf = await getChunk({
+        assemblyId:    args.assemblyId,
+        chunkIndex:    c,
+        encryptionKey: args.chunkEncryptionKeys[c],
+      });
+      parts.push(buf);
+      totalBytes += buf.length;
+    }
+    _emit("system.storage.chunk_scratch.assembled", {
+      metadata: {
+        assemblyId: args.assemblyId,
+        chunkCount: indices.length,
+        sizeBytes:  totalBytes,
+      },
+    });
+    return Buffer.concat(parts, totalBytes);
+  }
+
+  async function removeAssembly(assemblyId) {
+    _validateAssemblyId(assemblyId);
+    var indices = await listChunks(assemblyId);
+    var removed = 0;
+    for (var i = 0; i < indices.length; i += 1) {
+      try { await removeChunk({ assemblyId: assemblyId, chunkIndex: indices[i] }); removed += 1; }
+      catch (_e) { /* best-effort */ }
+    }
+    _emit("system.storage.chunk_scratch.removed", {
+      metadata: { assemblyId: assemblyId, chunksRemoved: removed },
+    });
+    return { chunksRemoved: removed };
+  }
+
+  async function listAssemblies() {
+    var picked = _pickBackend(_pickOpts());
+    if (typeof picked.backend.list !== "function") {
+      throw _err("UNSUPPORTED",
+        "chunkScratch.listAssemblies: backend '" + picked.backend.name + "' does not implement list()", true);
+    }
+    var listRes = await picked.backend.list(rootKeyPrefix + "/");
+    var items = listRes && Array.isArray(listRes.items) ? listRes.items
+              : Array.isArray(listRes) ? listRes : [];
+    var ids = {};
+    var prefixWithSlash = rootKeyPrefix + "/";
+    for (var i = 0; i < items.length; i += 1) {
+      var item = items[i];
+      var rawKey = typeof item === "string" ? item : item && item.key;
+      if (typeof rawKey !== "string") continue;
+      var rel = rawKey.indexOf(prefixWithSlash) === 0
+        ? rawKey.slice(prefixWithSlash.length) : rawKey;
+      var slash = rel.indexOf("/");
+      if (slash === -1) continue;
+      ids[rel.slice(0, slash)] = true;
+    }
+    return canonicalJson.sortKeys(ids);
+  }
+
+  async function listStaleAssemblies(args) {
+    args = args || {};
+    var olderThan = (typeof args.olderThanMs === "number" && args.olderThanMs > 0)
+      ? args.olderThanMs : staleAfterMs;
+    var cutoff = Date.now() - olderThan;
+    var picked = _pickBackend(_pickOpts());
+    if (typeof picked.backend.list !== "function") {
+      throw _err("UNSUPPORTED",
+        "chunkScratch.listStaleAssemblies: backend does not implement list()", true);
+    }
+    var assemblies = await listAssemblies();
+    var stale = [];
+    for (var i = 0; i < assemblies.length; i += 1) {
+      var assemblyId = assemblies[i];
+      // Use the earliest chunk's mtime as the assembly's createdAt
+      // proxy. Backends that surface mtime via list() inspect items;
+      // others fall through to a stat probe on the first chunk.
+      var indices = await listChunks(assemblyId);
+      if (indices.length === 0) { stale.push(assemblyId); continue; }
+      var firstKey = _chunkKey(assemblyId, indices[0]);
+      var stat = null;
+      if (typeof picked.backend.stat === "function") {
+        try { stat = await picked.backend.stat(firstKey); } catch (_e) { stat = null; }
+      }
+      var mtime = stat && (stat.mtimeMs || (stat.mtime && stat.mtime.getTime && stat.mtime.getTime()));
+      if (typeof mtime === "number" && mtime < cutoff) {
+        stale.push(assemblyId);
+      }
+    }
+    return stale;
+  }
+
+  async function gc(args) {
+    args = args || {};
+    var stale = await listStaleAssemblies({ olderThanMs: args.olderThanMs });
+    var removed = [];
+    for (var i = 0; i < stale.length; i += 1) {
+      try {
+        var r = await removeAssembly(stale[i]);
+        removed.push({ assemblyId: stale[i], chunksRemoved: r.chunksRemoved });
+      } catch (_e) { /* best-effort GC */ }
+    }
+    _emit("system.storage.chunk_scratch.gc", {
+      metadata: { staleCount: stale.length, removedCount: removed.length },
+    });
+    return { removed: removed };
+  }
+
+  return {
+    saveChunk:           saveChunk,
+    getChunk:            getChunk,
+    chunkExists:         chunkExists,
+    listChunks:          listChunks,
+    countChunks:         countChunks,
+    removeChunk:         removeChunk,
+    assemble:            assemble,
+    removeAssembly:      removeAssembly,
+    listAssemblies:      listAssemblies,
+    listStaleAssemblies: listStaleAssemblies,
+    gc:                  gc,
+  };
+}
+
 function _resetForTest() {
   initialized = false;
   backends = {};
@@ -851,5 +1267,6 @@ module.exports = {
   presignedUploadPolicy: presignedUploadPolicy,
   listBackends:   listBackends,
   getBackend:     getBackend,
+  chunkScratch:   chunkScratch,
   _resetForTest:  _resetForTest,
 };

package/package.json

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