@blamejs/core 0.13.25 → 0.13.27

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.27 (2026-05-28) — **Documentation corrected across api-encrypt, mail-crypto, mail-store, and calendar.** A set of JSDoc corrections where the documented contract had drifted from the code. The most actionable: b.middleware.apiEncrypt's @opts named the keypair fields secretKey / ecSecretKey, but the middleware requires privateKey / ecPrivateKey (the shape b.crypto.generateEncryptionKeyPair returns), so a keypair built from the docs threw INVALID_KEYPAIR at construction; the same block documented a wrong custom-nonceStore interface and an example calling a non-existent b.crypto.keypair(). Also corrected: the b.mail.crypto facade and the PGP module described S/MIME sign/verify and PGP encrypt/decrypt/WKD as deferred when they ship and are live; b.mail.crypto.smime.checkCert documented a return shape whose field names did not match what it returns; and b.mailStore.create listed a destroy method it does not expose. No code behavior changed — only the docs were wrong. **Fixed:** *`b.middleware.apiEncrypt` options documented with the correct field names* — The `@opts` listed the keypair as `{ publicKey, secretKey, ecPublicKey, ecSecretKey }`, but the middleware requires `{ publicKey, privateKey, ecPublicKey, ecPrivateKey }` — the shape `b.crypto.generateEncryptionKeyPair()` returns — and threw `INVALID_KEYPAIR` for the documented shape. The custom `nonceStore` interface was documented as `{ has, add, prune }` but the middleware calls `{ checkAndInsert, purgeExpired, close }`, and the example called a non-existent `b.crypto.keypair()`. All three now match the implementation (`b.crypto.generateEncryptionKeyPair()`). · *`b.mail.crypto` S/MIME and PGP availability described accurately* — The `b.mail.crypto` facade said S/MIME `sign()` / `verify()` were deferred, and the PGP module's intro said in-process encrypt / decrypt and WKD discovery would 'ship in v0.10.14'. All of these are implemented and live (PGP encrypt/decrypt/WKD were promoted to the stable surface in v0.11.32; S/MIME sign/verify/verifyAll run on the `b.cms` substrate). The docs now describe them as available; the genuinely-deferred PGP v6-signature-packet support remains noted as deferred. · *`b.mail.crypto.smime.checkCert` return shape documented correctly* — The doc and example described the result as `{ subjectCN, issuerCN, validFrom, validTo, keyAlg, keyBits, sigAlg }`; the function returns `{ subject, issuer, validFrom, validTo, sigAlgName, sigAlgOid, keyType, fingerprint256 }` (full DN strings, no key-size field). The documented shape now matches. · *`b.mailStore.create` method list matches the returned handle* — The doc listed a `destroy` method the handle does not expose and omitted `search` / `moveMessages` / `hardExpunge` that it does. The list now reflects the actual methods. · *Smaller doc corrections* — `b.calendar` fromIcal / toIcal / validate now document that they also handle Task (VTODO), Note (VJOURNAL), and Group, not just Event. `b.middleware.requireAuth`'s `prefersJson` default is documented as Accept / X-Requested-With only (Content-Type is intentionally not a signal, as the module already noted). The default CSP nonce is 24 base64 chars (16 bytes), not 22. `b.mail.bimi`'s returned `evidenceDocument` is noted as echoed from the operator-supplied option rather than pulled from the certificate.
+
+- v0.13.26 (2026-05-28) — **`b.cryptoField.unsealRow` nulls a sealed column on unseal failure instead of returning the forged ciphertext.** When a sealed column failed to unseal — a DB-write attacker's forged `vault:<…>` payload, or a valid ciphertext copied into a different row so the AAD no longer matches — unsealRow recorded the failure on the audit chain but then kept the original attacker-crafted string in the field rather than nulling it, despite the documented contract that downstream sees 'no value'. A write-back guard discarded the intended null on the failure path. The column is now nulled on any unseal failure, so a forged or cross-row-copied value never reaches downstream code as if it were a real plaintext. Valid values round-trip unchanged and genuinely-unsealed pass-through values are still kept. This hardens every sealed-column reader, including the agent idempotency / orchestrator / tenant rows sealed in 0.13.25. **Fixed:** *Audit checkpoint docs name the actual signature algorithm* — `b.audit.checkpoint` / `b.audit.verifyCheckpoints` described the anchor signature as ML-DSA-87, but the checkpoint is signed with the configured `b.auditSign` algorithm — SLH-DSA-SHAKE-256f by default (ML-DSA-87 / ML-DSA-65 are opt-in). The docs and the verify-failure reason now refer to the post-quantum signature without naming a specific algorithm the operator may not be using. · *`b.storage.chunkScratch` example and assembly description corrected* — The `assemble()` example omitted the mandatory `chunkEncryptionKeys` argument (one sealed key per chunk, returned by `saveChunk`), so it would have thrown as written; it now collects and passes the keys. The prose no longer claims the primitive writes a final file with an 'atomic finalize' — `assemble()` concatenates the chunks in order and returns the assembled bytes for the caller to persist. **Security:** *Sealed columns are nulled on unseal failure (forged / cross-row ciphertext)* — `b.cryptoField.unsealRow` now nulls a sealed field when its value fails to unseal — a crafted `vault:`/`vault.aad:` payload written by a DB-write attacker, or a valid ciphertext copied to a different row (AAD mismatch). Previously the field kept the attacker-controlled string, so downstream code could read the forged ciphertext as if it were the plaintext. The audit emit (`system.crypto.unseal_failed`) is unchanged. Valid round-trips and not-actually-sealed pass-through values are unaffected. A regression test pins the forged-value, cross-row-copy, and pass-through cases.
+
 - v0.13.25 (2026-05-28) — **Agent idempotency results and orchestrator/tenant registry rows are sealed at rest.** The b.agent.idempotency, b.agent.orchestrator, and b.agent.tenant primitives documented their stored rows as sealed at rest, but the values were written as plaintext JSON — a database dump could expose cached result payloads (which can carry mail-move / search data), the tenant ids that own each agent, and operator-supplied endpoint metadata. Those values are now sealed via b.cryptoField (XChaCha20-Poly1305 through the vault) before they reach the backing store and unsealed on read, when a vault is configured — which is the default in a booted app. Each ciphertext is AAD-bound to its row identity so a database-write attacker cannot copy a sealed value between rows. Reads of rows written before this release (plain JSON) continue to work unchanged, and a vault-less deployment stores rows as before. No API or call-site changes are required. **Fixed:** *`b.agent.saga` run() return/throw shape documented correctly* — The doc said `run()` resolves to `{ status: "failed", failedStep, lastCompensationError }` on failure and to a bare final state. In fact it resolves to `{ status: "completed", sagaId, state }` on success and rejects (throws) on step failure with an error carrying `failedStep`, `cause`, `compensationCause`, and `failedCompStepName`. The docs now describe the actual contract. · *`b.agent.idempotency` put() example uses the real option name* — The example passed `{ argsFingerprint: ... }`, which the function does not read; the fingerprint option is `requestFingerprint` (or `args`). The example now uses `requestFingerprint`. · *`b.agent.tenant.derivedKey` @since corrected to 0.9.26* — It was tagged `@since 0.9.25`, a version before the tenant module existed; it ships in 0.9.26 alongside `b.agent.tenant.create`. · *`b.agent.trace.injectIntoEnvelope` documented as single-argument* — The doc listed a second `currentSpan` argument the function ignores — it always injects the currently-active span's trace context. The doc now shows `injectIntoEnvelope(envelope)` and notes it should be called while the intended span is active. **Security:** *Agent idempotency / orchestrator / tenant rows sealed at rest* — `b.agent.idempotency` cached result blobs, `b.agent.orchestrator` registry rows (owning tenant id + endpoint metadata), and `b.agent.tenant` registry-row metadata are now sealed via `b.cryptoField` when a vault is configured (the default in a booted app via `b.start`). The fields were previously stored as plaintext despite the docs describing them as sealed, so a DB dump exposed cached payloads, agent↔tenant ownership, and endpoint detail. Each sealed value is AAD-bound to the row identity (the idempotency key hash / the agent name / the tenant id), so a sealed value cannot be copied between rows. Rows written before this release remain readable (a non-sealed value passes through unseal), and a vault-less deployment behaves as before. No call-site changes.
 
 - v0.13.24 (2026-05-28) — **`b.guard*` docs corrected: the compliance-posture opt key, the gate API, and validate return shapes.** Documentation corrections across the b.guard* family. The most consequential: the posture-selection option was documented as `compliance:` in many guards' @opts, but the working key is `compliancePosture:` — passing the documented `{ compliance: "hipaa" }` was silently ignored, so a compliance posture (e.g. HIPAA PII redaction) never activated. If you select a posture via the gate/validate/sanitize options, use `compliancePosture:`; `compliance:` had no effect. The guard docs now name the correct key uniformly. Also corrected: gate examples and prose that invoked the gate as a callable or via `.run` / `.inspect` (the gate is an object whose method is `.check(ctx)`), and validate() return shapes that listed `severities` / `summary` / `refusal` fields the function never returned (it returns `{ ok, issues }`). **Fixed:** *guard posture option is `compliancePosture:`, not `compliance:`* — Many `b.guard*` primitives documented the compliance-posture selector as `compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2"` in their `@opts`, but the family resolver reads `compliancePosture:`. Passing `{ compliance: "hipaa" }` was accepted and silently ignored — the posture overlay (e.g. CSV `piiPolicy: "redact"` under HIPAA) never applied, leaving the default policy in force. The docs across the guard family now name `compliancePosture:` consistently (the key the resolver and `b.guardX.compliancePosture(name)` already used). Action: if you selected a posture with `compliance:`, switch to `compliancePosture:` — the posture was not taking effect before. · *guard gate is an object with `.check(ctx)`, not a callable* — Several guards' gate `@example`s and prose invoked the gate as a function (`g({...})`), via `.run(...)`, or via `.inspect(...)`, and a few described it as "an async function". `b.guardX.gate(opts)` returns an object whose async method is `.check(ctx)`; the examples and prose now use `.check`, so they run as written. · *guard validate() returns `{ ok, issues }`* — Several guards documented `validate()` as returning `{ ok, issues, severities }`, `{ ok, issues, summary }`, or `{ ok, issues, refusal? }`. The function returns `{ ok, issues }` (each issue carries its own `severity` / `kind`); the documented extra top-level fields were never present. The docs now state the actual shape.

package/lib/audit.js

@@ -796,9 +796,10 @@ function _checkpointPayload(atMonotonicCounter, atRowHash, createdAt) {
   );
 }
 
-// Anchor the current chain tip with a fresh ML-DSA-87 signature. Inserts
-// a row into audit_checkpoints. Updates <dataDir>/audit.tip for boot-time
-// rollback detection.
+// Anchor the current chain tip with a fresh post-quantum signature (the
+// configured b.auditSign algorithm — SLH-DSA-SHAKE-256f by default).
+// Inserts a row into audit_checkpoints. Updates <dataDir>/audit.tip for
+// boot-time rollback detection.
 //
 // opts:
 //   skipIfUnchanged: bool — return null without inserting if the chain tip
@@ -810,8 +811,10 @@ function _checkpointPayload(atMonotonicCounter, atRowHash, createdAt) {
  * @compliance soc2, pci-dss, sox-404
  * @related   b.audit.verifyCheckpoints, b.audit.verify
  *
- * Anchor the current chain tip with a fresh ML-DSA-87 (post-quantum)
- * signature. Inserts a row into `audit_checkpoints` and updates the
+ * Anchor the current chain tip with a fresh post-quantum signature (the
+ * configured `b.auditSign` algorithm — SLH-DSA-SHAKE-256f by default,
+ * ML-DSA-87 / ML-DSA-65 optional). Inserts a row into `audit_checkpoints`
+ * and updates the
  * boot-time rollback-detection sidecar (single-node) or the cluster
  * audit-tip row (cluster mode, fencing-token guarded). Cluster mode
  * requires the caller hold leader status — `cluster.requireLeader()`
@@ -917,8 +920,8 @@ async function checkpoint(opts) {
  * @related   b.audit.checkpoint, b.audit.verify
  *
  * Walk every checkpoint and verify (a) the public-key fingerprint
- * matches the current signing key, (b) the ML-DSA-87 signature over the
- * payload still verifies, (c) the audit_log row at the anchored counter
+ * matches the current signing key, (b) the post-quantum signature over
+ * the payload still verifies, (c) the audit_log row at the anchored counter
  * still has the recorded rowHash. Catches tampering that recomputed
  * chain hashes after holding the vault key, because the off-chain
  * signature anchor is unforgeable without the signing key.
@@ -967,7 +970,7 @@ async function verifyCheckpoints() {
         checkpointsVerified: i,
         breakAt:             i,
         checkpointId:        c._id,
-        reason:              "ML-DSA-87 signature failed",
+        reason:              "post-quantum signature failed",
       };
     }
     // Also confirm the audit row at atMonotonicCounter still matches the

package/lib/calendar.js

@@ -107,8 +107,9 @@ var MAX_EXPAND_SPAN_MS   = 10 * 365 * 24 * 60 * 60 * 1000;
  * @since     0.11.31
  * @status    stable
  *
- * Validate a JSCalendar Event / Task object's required-field shape per
- * RFC 8984 §5 (Event) + §6 (Task). Returns the input on success; throws
+ * Validate a JSCalendar Event / Task / Note / Group object's
+ * required-field shape per RFC 8984 §5 (Event) / §6 (Task) / §7 (Note) /
+ * §1.4.4 (Group). Returns the input on success; throws
  * `CalendarError` on refusal with a `.code` naming the specific shape
  * rule that failed.
  *
@@ -337,10 +338,11 @@ function validate(jsCal) {
  * @since     0.11.31
  * @status    stable
  *
- * Parse iCalendar text (RFC 5545) via `b.safeIcal.parse` and map the
- * first VEVENT into a JSCalendar Event object (RFC 8984 §5). Returns
- * a single Event when the VCALENDAR contains exactly one VEVENT, or
- * an array when multiple VEVENTs are present.
+ * Parse iCalendar text (RFC 5545) via `b.safeIcal.parse` and map each
+ * VEVENT → JSCalendar Event, VTODO → Task, and VJOURNAL → Note
+ * (RFC 8984 §5 / §6 / §7). Returns a single object when the VCALENDAR
+ * holds exactly one component, or an array across all components when
+ * there are several.
  *
  * @opts
  *   safeIcalOpts: object,   // forwarded to b.safeIcal.parse (caps, allowExperimental, etc.)
@@ -381,10 +383,12 @@ function fromIcal(text, opts) {
  * @since     0.11.31
  * @status    stable
  *
- * Render a JSCalendar Event back to RFC 5545 iCalendar text. Returns a
- * CRLF-terminated string wrapped in a `BEGIN:VCALENDAR / VERSION:2.0 /
- * PRODID:-//blamejs//Calendar//EN / BEGIN:VEVENT ... END:VEVENT /
- * END:VCALENDAR` envelope per RFC 5545 §3.4.
+ * Render a JSCalendar object back to RFC 5545 iCalendar text — Event →
+ * VEVENT, Task → VTODO, Note → VJOURNAL, and a Group to a VCALENDAR
+ * carrying each member component. Returns a CRLF-terminated string
+ * wrapped in a `BEGIN:VCALENDAR / VERSION:2.0 /
+ * PRODID:-//blamejs//Calendar//EN / … / END:VCALENDAR` envelope per
+ * RFC 5545 §3.4.
  *
  * @opts
  *   prodid: string,   // PRODID value to emit; default "-//blamejs//Calendar//EN"

package/lib/crypto-field.js

@@ -495,9 +495,14 @@ function unsealRow(table, row) {
         } catch (_e) { /* drop-silent */ }
         unsealed = null;
       }
-      // If the value wasn't actually sealed, vault.unseal returns the input
-      // unchanged — keep the original.
-      out[field] = unsealed !== undefined && unsealed !== null ? unsealed : out[field];
+      // Assign unconditionally. `unsealed` already carries the right value
+      // for every branch: the plaintext on success, the original value on
+      // the not-actually-sealed pass-through (set above), and `null` on an
+      // unseal failure. The failure case MUST null the column so downstream
+      // sees "no value" rather than the attacker-crafted `vault:<…>` string
+      // (a prior `... ? unsealed : out[field]` guard silently kept the
+      // forged ciphertext on failure, defeating the documented defense).
+      out[field] = unsealed;
     }
   }
 

package/lib/mail-bimi.js

@@ -34,8 +34,9 @@
  *   subjectAltName URI matches the BIMI domain, and confirms the
  *   cert carries the BIMI mark-verification policy OID
  *   (1.3.6.1.5.5.7.3.31). The verified mark is returned as
- *   { svg, evidenceDocument } pulled from RFC 3709 logotype extension
- *   when present.
+ *   { svg, evidenceDocument } — `svg` pulled from the RFC 3709
+ *   logotype extension when present, `evidenceDocument` echoed from the
+ *   operator-supplied opts.evidenceDocument.
  *
  *   `validateTinyPsSvg` enforces the AuthIndicators-WG Tiny PS subset:
  *   single root <svg>, version="1.2", baseProfile="tiny-ps", viewBox

package/lib/mail-crypto-pgp.js

@@ -57,19 +57,15 @@
  *       to a known operator key rather than trusting any key that
  *       happens to match the signature.
  *
- *   Deferred from v1 (each with the documented condition for opting in):
+ *   Now live (promoted to the stable top-level surface in v0.11.32):
  *     - In-process encrypt + decrypt (Message Encrypted Session Key +
  *       Symmetrically Encrypted Integrity Protected Data packets,
- *       RFC 9580 §5.1 / §5.13) and WKD key discovery (draft-koch-
- *       openpgp-webkey-service). Defer condition: ships in v0.10.14
- *       alongside `b.mail.crypto.smime` sign + verify — the CMS
- *       substrate `b.cms` landed in v0.10.13 unblocked the S/MIME
- *       side, and OpenPGP encrypt rides the same release so the
- *       mail-crypto surface lights up coherently rather than half-
- *       on-each-side across two patches. Cheap escape hatch (pre-
- *       v0.10.14): operators wire a third-party OpenPGP library in
- *       their own consumer code and call this module's sign() /
- *       verify() on the resulting cleartext blob.
+ *       RFC 9580 §5.1 / §5.13) as `b.mail.crypto.pgp.encrypt` /
+ *       `.decrypt`, and WKD key discovery (draft-koch-openpgp-webkey-
+ *       service) as `b.mail.crypto.pgp.wkd` — all on the same `b.cms`
+ *       substrate that backs S/MIME sign/verify.
+ *
+ *   Deferred (with the documented condition for opting in):
  *     - v6 signature packets (RFC 9580 §5.2.3, packet version 6 with
  *       SHA2-512 fingerprints and salted hashes). Defer condition: v6
  *       is not yet emitted by GnuPG 2.4 LTS or by Sequoia stable, so

package/lib/mail-crypto-smime.js

@@ -670,14 +670,15 @@ function _wrapBase64(s) {
  * Operator-side cert preflight that lights up at boot: refuses
  * SHA-1 / MD5 signatures, RSA keys < 2048 bits, MD2 / MD5 / SHA-1
  * as the certificate-signature algorithm. Returns the parsed cert
- * shape (subject CN, issuer CN, validFrom / validTo, key algorithm
- * + size, signature algorithm). Throws `mail-crypto/smime/bad-cert`
- * on any of the above; throws `mail-crypto/smime/expired-cert` if
- * the cert is outside its validity window.
+ * shape: the full subject / issuer DN strings, the validity window,
+ * the signature algorithm (name + OID), the key type, and the SHA-256
+ * fingerprint. Throws `mail-crypto/smime/bad-cert` on any of the above;
+ * throws `mail-crypto/smime/expired-cert` if the cert is outside its
+ * validity window.
  *
  * @example
  *   var info = b.mail.crypto.smime.checkCert({ certPem: pem });
- *   // → { subjectCN, issuerCN, validFrom, validTo, keyAlg, keyBits, sigAlg }
+ *   // → { subject, issuer, validFrom, validTo, sigAlgName, sigAlgOid, keyType, fingerprint256 }
  */
 function checkCert(opts) {
   opts = validateOpts.requireObject(opts, "mail.crypto.smime.checkCert",

package/lib/mail-crypto.js

@@ -22,11 +22,11 @@
  *       (pub-alg 1, EMSA-PKCS1-v1_5 + SHA-256, 2048-bit floor per
  *       RFC 8301).
  *     - `b.mail.crypto.smime` — S/MIME 4.0 per RFC 8551 with CMS
- *       SignedData per RFC 5652. v1 surface: checkCert() — the
- *       operator-side preflight that refuses SHA-1 / MD5 / < 2048-bit
- *       RSA certs at boot. sign() + verify() are DEFERRED in v1; see
- *       the @intro block in lib/mail-crypto-smime.js for the deferral
- *       conditions and the operator escape hatch.
+ *       SignedData per RFC 5652. Surface: sign() + verify() + verifyAll()
+ *       (built on the `b.cms` substrate — digest recompute + timing-safe
+ *       compare + PQC signature verify + X.509 chain walk) plus
+ *       checkCert(), the operator-side preflight that refuses SHA-1 /
+ *       MD5 / < 2048-bit RSA certs at boot.
  *
  *   Both sub-namespaces share `MailCryptoError` (FrameworkError
  *   subclass via defineClass with alwaysPermanent: true) so operator

package/lib/mail-store.js

@@ -90,8 +90,9 @@ var DEFAULT_FOLDERS = Object.freeze([
  * @related   b.safeMime, b.guardMessageId, b.cryptoField
  *
  * Build a mail-store handle. Returns an object with `appendMessage` /
- * `fetchByObjectId` / `queryByModseq` / `setFlags` / `createFolder` /
- * `listFolders` / `threadFor` / `quota` / `setLegalHold` / `destroy`.
+ * `fetchByObjectId` / `search` / `queryByModseq` / `setFlags` /
+ * `createFolder` / `listFolders` / `threadFor` / `quota` /
+ * `moveMessages` / `setLegalHold` / `hardExpunge`.
  *
  * @opts
  *   backend:     object,   // required — sqlite-shaped { prepare(sql) → { run, get, all }, transaction(fn) }

package/lib/middleware/api-encrypt.js

@@ -250,11 +250,11 @@ function _writeRejection(res, code, body) {
  *
  * @opts
  *   {
- *     keypair:             { publicKey, secretKey, ecPublicKey, ecSecretKey },
+ *     keypair:             { publicKey, privateKey, ecPublicKey, ecPrivateKey },
  *     keypairs:            [...]            // multi-key rotation set; first = active
  *     replayWindowMs:      number,
  *     pruneIntervalMs:     number,
- *     nonceStore:          { has, add, prune },
+ *     nonceStore:          { checkAndInsert, purgeExpired, close },
  *     exemptPaths:         string[],
  *     contentTypes:        string[],         // default ["application/json"]
  *     audit:               boolean,
@@ -270,7 +270,7 @@ function _writeRejection(res, code, body) {
  * @example
  *   var b = require("@blamejs/core");
  *   var app = b.router.create();
- *   var kp = b.crypto.keypair();
+ *   var kp = b.crypto.generateEncryptionKeyPair();
  *   app.use(b.middleware.apiEncrypt({
  *     keypair:        kp,
  *     replayWindowMs: 30000,

package/lib/middleware/csp-nonce.js

@@ -8,7 +8,7 @@
  * browser refuses to execute them. This middleware closes the gap:
  *
  *   1. Generate a fresh random nonce per request (base64, default
- *      16 bytes / 22 chars).
+ *      16 bytes / 24 chars).
  *   2. Attach it to `req.cspNonce` (handler-readable) AND
  *      `res.locals.cspNonce` (template-data-readable — render.js
  *      auto-merges res.locals into template data).
@@ -233,7 +233,7 @@ function _injectNonce(cspHeader, nonce, directives, strictDynamic) {
  * Per-request CSP nonce + render integration. Constructed via
  * `b.middleware.cspNonce(opts)`; the resulting middleware has the
  * `(req, res, next)` shape shown above. Generates a fresh
- * random nonce (16 bytes / 22 chars base64 by default), attaches it
+ * random nonce (16 bytes / 24 chars base64 by default), attaches it
  * to `req.cspNonce` and `res.locals.cspNonce` (auto-merged into
  * template data), and patches the existing Content-Security-Policy
  * header to append `'nonce-XYZ'` to the configured directives

package/lib/middleware/require-auth.js

@@ -30,7 +30,8 @@
  *                                   when set, prefersJson()=false rejections
  *                                   produce 302 instead of 401 text/plain)
  *     prefersJson:   function     (optional override; defaults to checking
- *                                   Accept / X-Requested-With / Content-Type)
+ *                                   Accept / X-Requested-With — NOT
+ *                                   Content-Type, see the note above)
  *     errorMessage:  'Authentication required.'
  *     audit:         true         (emit auth.required.denied on reject)
  *   }

package/lib/storage.js

@@ -833,10 +833,10 @@ function _requireInit() {
 //
 // 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
+// persist incoming chunks during the upload window, then concatenate
+// them in order when the upload completes. Without a framework
+// primitive every consumer ended up reinventing the per-assembly
+// directory layout + ordered gap-checked assembly + GC of partial
 // assemblies that never completed.
 //
 // chunkScratch owns:
@@ -844,8 +844,8 @@ function _requireInit() {
 //     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)
+//   - ordered, gap-checked concat returning the assembled bytes for
+//     the caller to persist (the primitive does not write a final file)
 //   - GC of stale partial assemblies (operator opts in via gc())
 //
 // Backend is the same `b.storage` backend the operator already
@@ -919,10 +919,11 @@ function _validateChunkIndex(idx) {
  * @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.
+ * during the upload window, then concatenates them in order on
+ * completion and returns the assembled bytes for the caller to persist
+ * (the primitive does not itself write a final file). Owns per-assembly
+ * directory layout, envelope-encrypted chunk persistence, ordered
+ * gap-checked assembly, and GC of partial assemblies.
  *
  * Composes existing primitives: each chunk routes through
  * `b.storage.saveFile` (same XChaCha20-Poly1305 envelope as the
@@ -974,13 +975,16 @@ function _validateChunkIndex(idx) {
  *   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 });
+ *   // During upload — each PUT lands one chunk. saveChunk returns the
+ *   // chunk's sealed encryptionKey; collect them in order for assemble.
+ *   var keys = [];
+ *   keys[0] = (await cs.saveChunk({ assemblyId: "upload-abc", chunkIndex: 0, data: chunk0 })).encryptionKey;
+ *   keys[1] = (await cs.saveChunk({ assemblyId: "upload-abc", chunkIndex: 1, data: chunk1 })).encryptionKey;
+ *   keys[2] = (await cs.saveChunk({ assemblyId: "upload-abc", chunkIndex: 2, data: chunk2 })).encryptionKey;
  *
- *   // On completion — atomic assemble + cleanup
- *   var assembled = await cs.assemble({ assemblyId: "upload-abc", expectedTotal: 3 });
+ *   // On completion — concat the chunks (in order) into the assembled
+ *   // buffer, then clean up. chunkEncryptionKeys is one key per chunk.
+ *   var assembled = await cs.assemble({ assemblyId: "upload-abc", expectedTotal: 3, chunkEncryptionKeys: keys });
  *   await cs.removeAssembly("upload-abc");
  *
  *   // Periodic GC of partial uploads abandoned mid-stream

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:47754ab4-658d-4a84-ac31-adda479b6281",
+  "serialNumber": "urn:uuid:ffa5e6b8-d243-4ea1-813c-7fa23f7cf2ae",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-28T12:35:12.333Z",
+    "timestamp": "2026-05-28T23:00:13.047Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.25",
+      "bom-ref": "@blamejs/core@0.13.27",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.25",
+      "version": "0.13.27",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.25",
+      "purl": "pkg:npm/%40blamejs/core@0.13.27",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.25",
+      "ref": "@blamejs/core@0.13.27",
       "dependsOn": []
     }
   ]