@blamejs/core 0.13.2 → 0.13.3

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.3 (2026-05-26) — **`b.crypto.xwing` — X-Wing hybrid post-quantum KEM.** b.crypto.xwing adds the X-Wing hybrid key-encapsulation mechanism (draft-connolly-cfrg-xwing-kem): it runs ML-KEM-768 and X25519 side by side and binds their shared secrets with SHA3-256, so an encapsulated key stays secure as long as either ML-KEM-768 or X25519 holds. That is the conservative shape for moving off classical ECDH today — a harvest-now-decrypt-later attacker must break the lattice KEM, and a hypothetical ML-KEM break still leaves X25519 standing. keygen() produces a 32-byte decapsulation seed and a 1216-byte public key; encapsulate(publicKey) returns a 1120-byte ciphertext and a 32-byte shared secret; decapsulate(secretKey, ciphertext) recovers it. The X-Wing combiner is frozen, but its specification is still an IETF Internet-Draft, so this primitive is marked experimental and sits beside the existing pre-RFC post-quantum HPKE drafts; it composes the framework's vendored ML-KEM-768 and X25519 with SHA3 and adds no new cryptographic core. The combiner is known-answer-tested byte-for-byte against the draft's definition. **Added:** *`b.crypto.xwing` — X-Wing hybrid PQ/T KEM (experimental)* — `keygen(seed?)` → `{ publicKey (1216 B), secretKey (32-byte seed) }`; `encapsulate(publicKey, eseed?)` → `{ ciphertext (1120 B), sharedSecret (32 B) }`; `decapsulate(secretKey, ciphertext)` → the 32-byte shared secret. Both `keygen` and `encapsulate` accept an optional seed for deterministic operation. The combiner — `SHA3-256(ssMLKEM ‖ ssX25519 ‖ ctX25519 ‖ pkX25519 ‖ label)` — is exposed as `combiner` for advanced use. Marked `experimental` while draft-connolly-cfrg-xwing-kem remains an Internet-Draft; the algorithm itself is frozen.
+
 - v0.13.2 (2026-05-26) — **`b.iabTcf.encode` — write TCF consent strings, and a TC-string timestamp fix.** b.iabTcf gains the encode half of its consent-string codec: b.iabTcf.encode(obj) serialises a parsed object back into an IAB TCF v2 TC string, and b.iabTcf.isValid(tcString) is a total never-throwing validity check. Vendor and purpose collections may be Sets, id arrays, or the parsed sections parseString returns; vendor sections are written with whichever of the bit-field and range forms is smaller, matching the reference CMP encoders, so a parsed string round-trips to an equivalent signal. parseString now fully decodes the Core publisher-restrictions list and the PublisherTC segment's publisher and custom purposes, where it previously reported only the segment's presence. The encoder is verified against the worked-example string in the IAB Tech Lab consent-string specification: it re-encodes that string's Core segment byte-for-byte. This release also fixes a TC-string parsing bug — the bit reader accumulated values with a 32-bit shift, so the 36-bit Created and LastUpdated timestamp fields were silently truncated for any real date; they now decode and round-trip exactly. **Added:** *`b.iabTcf.encode` / `b.iabTcf.isValid`* — `encode(obj)` serialises a TCF object (the shape `parseString` returns) into a TC string — Core plus optional DisclosedVendors, AllowedVendors, and PublisherTC segments — choosing the smaller of the bit-field and range vendor encodings. `isValid(tcString)` returns whether a string parses as a well-formed Core segment without throwing. `parseString` now fully decodes Core publisher restrictions and the PublisherTC purposes that were previously reported only as present. **Fixed:** *TC-string 36-bit timestamps were truncated on parse* — `b.iabTcf.parseString` read multi-bit fields with a 32-bit left-shift accumulation. The 36-bit Created and LastUpdated fields hold deciseconds-since-epoch, which exceeds 2^31 for any date after 1976, so those timestamps were silently corrupted. The reader now accumulates without the 32-bit truncation; timestamps decode correctly and round-trip through `encode`.
 
 - v0.13.1 (2026-05-26) — **`b.worm` — write-once-read-many retention.** Store records that cannot be altered or deleted before a retention period elapses — the immutable-storage discipline regulators require (SEC 17a-4(f), CFTC 1.31, FINRA 4511). b.worm.create(opts) returns a WORM store that enforces, on every mutating call, that a record is not overwritten or deleted while it is within its retainUntil window or under a legal hold. Two modes mirror cloud Object-Lock: compliance (the default — no one, including the operator, can delete before expiry) and governance (a privileged caller may override with an audited reason). Retention can only be extended, never shortened; every record carries a SHA3-512 digest that get verifies, so tampering with the underlying bytes is detected on read; every allow/refuse decision is audited. Storage is pluggable via a synchronous store adapter, so the policy layer sits over a sealed DB table, a filesystem, or any non-S3 backend — the store-agnostic, application-level companion to b.objectStore's S3 Object Lock, with content-integrity verification that native Object Lock does not provide. **Added:** *`b.worm.create` — write-once-read-many retention* — Returns a store with `put` / `get` / `delete` / `extendRetention` / `placeLegalHold` / `releaseLegalHold` / `list`. `put` is write-once (an overwrite of a retained or held record is refused); `delete` is gated by the retention window, legal holds, and the mode (`compliance` refuses any early delete; `governance` allows a privileged override with a required, audited reason); `extendRetention` is extend-only; `get` verifies the stored SHA3-512 digest and throws `worm/tampered` on a mismatch. Storage is a pluggable synchronous adapter (`get` / `set` / `delete` / `has` / `keys`), defaulting to in-memory for tests. Use it for SEC 17a-4 / CFTC / FINRA immutable records on backends without native Object Lock; `b.objectStore` remains the path for S3 Object Lock.

package/README.md

@@ -101,6 +101,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`)
 - **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
 - **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`); RFC 9530 Content-Digest / Repr-Digest body-integrity fields (SHA-256 / SHA-512, legacy algorithms refused — `b.contentDigest`) to sign the digest rather than the whole body
+- **X-Wing hybrid KEM** — `b.crypto.xwing` (draft-connolly-cfrg-xwing-kem, experimental): ML-KEM-768 + X25519 bound by SHA3-256, secure if either component holds — the conservative key-encapsulation shape for migrating off classical ECDH. `keygen` / `encapsulate` / `decapsulate` with a 1216-byte public key, 1120-byte ciphertext, and 32-byte shared secret
 - **Link header** — RFC 8288 Web Linking codec (`b.linkHeader.parse` / `serialize`): parse and build `Link: <uri>; rel="next"` relations, the standard REST pagination mechanism; quote-aware (a comma inside a quoted parameter never splits the list)
 - **URI Templates** — RFC 6570 expansion (`b.uriTemplate.expand` / `compile`): full Level 4 — every operator, the `:N` prefix and `*` explode modifiers — turning `{/path}{?q*}` plus variables into a concrete URI; validated against the official uritemplate-test suite. The `{var}` syntax behind OpenAPI links and HAL `_links`
 - **JSON Type Definition** — RFC 8927 validation (`b.jtd.validate` / `isValid`): portable, cross-implementation schema validation (all eight forms — type / enum / elements / properties / values / discriminator / ref / empty), returning instancePath / schemaPath errors; validated against the official 316-case suite. Interop companion to the fluent `b.safeSchema` builder

package/index.js

@@ -58,6 +58,7 @@ var crypto = require("./lib/crypto");
 // the dedicated lib files; these are thin aliases.
 crypto.hpke = require("./lib/crypto-hpke");
 crypto.oprf = require("./lib/crypto-oprf");
+crypto.xwing = require("./lib/crypto-xwing");
 // Both PQ-HPKE drafts behind one opt-in sub-namespace — see
 // lib/crypto-hpke-pq.js. Operators that need a draft-codepoint
 // shape reach for b.crypto.hpke.pq.connolly / .wg explicitly; the

package/lib/crypto-xwing.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * @module b.crypto.xwing
+ * @nav    Crypto
+ * @title  X-Wing KEM
+ *
+ * @intro
+ *   X-Wing is a general-purpose hybrid post-quantum / traditional key
+ *   encapsulation mechanism: it runs ML-KEM-768 and X25519 side by side and
+ *   binds their shared secrets with SHA3-256, so the resulting key stays
+ *   secure as long as <em>either</em> ML-KEM-768 or X25519 holds. That is the
+ *   conservative shape for migrating off classical ECDH today — a harvest-now-
+ *   decrypt-later attacker must break the lattice KEM, and a hypothetical
+ *   ML-KEM break still leaves X25519 standing.
+ *
+ *   The construction follows
+ *   <code>draft-connolly-cfrg-xwing-kem</code>. The combiner is frozen — it
+ *   hashes the ML-KEM shared secret, the X25519 shared secret, the X25519
+ *   ephemeral public key, the recipient's X25519 public key, and a fixed
+ *   six-byte label — but the document is still an IETF Internet-Draft, so this
+ *   primitive is marked <code>experimental</code> and sits beside the other
+ *   pre-RFC post-quantum drafts (<code>b.crypto.hpke.pq</code>). The wire
+ *   sizes are fixed: a 1216-byte public key (ML-KEM-768 1184 ‖ X25519 32), a
+ *   1120-byte ciphertext (ML-KEM-768 1088 ‖ X25519 32), a 32-byte decapsulation
+ *   seed, and a 32-byte shared secret.
+ *
+ *   X-Wing composes the framework's vendored ML-KEM-768 and X25519 plus
+ *   SHA3 — it adds no new cryptographic core, only the standard combiner and
+ *   wire framing.
+ *
+ * @card
+ *   X-Wing hybrid PQ/T KEM (`b.crypto.xwing`) — ML-KEM-768 + X25519 bound by
+ *   SHA3-256 per draft-connolly-cfrg-xwing-kem, secure if either component
+ *   holds. 1216-byte key, 1120-byte ciphertext, 32-byte shared secret.
+ */
+
+var nodeCrypto = require("node:crypto");
+var pqc = require("./vendor/noble-post-quantum.cjs");
+var { defineClass } = require("./framework-error");
+
+var XWingError = defineClass("XWingError", { alwaysPermanent: true });
+
+var mlkem = pqc.ml_kem768;
+
+// draft-connolly-cfrg-xwing-kem: the combiner label, ASCII "\./" + "/^\".
+var XWING_LABEL = Buffer.from("5c2e2f2f5e5c", "hex");
+
+// Component + composite sizes (bytes), fixed by the draft — protocol wire
+// widths, not buffer-capacity tunables.
+var ML_KEM_PK = 1184;                  // allow:raw-byte-literal — ML-KEM-768 public key
+var ML_KEM_CT = 1088;                  // allow:raw-byte-literal — ML-KEM-768 ciphertext
+var X25519_LEN = 32;                   // allow:raw-byte-literal — X25519 key/share length
+var SEED_LEN = 32;                     // allow:raw-byte-literal — X-Wing seed length
+var SS_LEN = 32;                       // allow:raw-byte-literal — shared-secret length
+var PK_LEN = ML_KEM_PK + X25519_LEN;   // 1216
+var CT_LEN = ML_KEM_CT + X25519_LEN;   // 1120
+var MLKEM_SEED = 64;                   // allow:raw-byte-literal — d ‖ z for ML-KEM KeyGen_internal
+var EXPAND_LEN = 96;                   // allow:raw-byte-literal — SHAKE256(seed) → d ‖ z ‖ sk_X
+
+// X25519 raw-scalar helpers via fixed PKCS8 / SPKI DER prefixes (OID
+// 1.3.101.110). Node clamps the scalar per RFC 7748 on use, matching X-Wing.
+var X25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+var X25519_SPKI_PREFIX  = Buffer.from("302a300506032b656e032100", "hex");
+
+function _x25519Public(sk) {
+  var key = nodeCrypto.createPrivateKey({ key: Buffer.concat([X25519_PKCS8_PREFIX, sk]), format: "der", type: "pkcs8" });
+  var spki = nodeCrypto.createPublicKey(key).export({ format: "der", type: "spki" });
+  return spki.subarray(spki.length - X25519_LEN);
+}
+function _x25519Shared(sk, pk) {
+  return nodeCrypto.diffieHellman({
+    privateKey: nodeCrypto.createPrivateKey({ key: Buffer.concat([X25519_PKCS8_PREFIX, sk]), format: "der", type: "pkcs8" }),
+    publicKey:  nodeCrypto.createPublicKey({ key: Buffer.concat([X25519_SPKI_PREFIX, pk]), format: "der", type: "spki" }),
+  });
+}
+
+function _shake256(buf, outLen) { return nodeCrypto.createHash("shake256", { outputLength: outLen }).update(buf).digest(); }
+
+/**
+ * @primitive  b.crypto.xwing.combiner
+ * @signature  b.crypto.xwing.combiner(ssM, ssX, ctX, pkX)
+ * @since      0.13.3
+ * @status     experimental
+ * @compliance soc2
+ * @related    b.crypto.xwing.encapsulate, b.crypto.xwing.decapsulate
+ *
+ * The X-Wing combiner: <code>SHA3-256(ssM ‖ ssX ‖ ctX ‖ pkX ‖ label)</code>,
+ * where the label is the fixed six bytes the draft defines. Exposed for
+ * advanced use and known-answer testing; <code>encapsulate</code> and
+ * <code>decapsulate</code> call it internally. Each input must be 32 bytes.
+ *
+ * @example
+ *   var ss = b.crypto.xwing.combiner(ssMlkem, ssX25519, ephPub, recipientPub);
+ *   // → 32-byte shared secret
+ */
+function combiner(ssM, ssX, ctX, pkX) {
+  [["ssM", ssM, SS_LEN], ["ssX", ssX, X25519_LEN], ["ctX", ctX, X25519_LEN], ["pkX", pkX, X25519_LEN]].forEach(function (t) {
+    // ML-KEM outputs are Uint8Array; X25519 outputs are Buffer — accept both.
+    if (!(Buffer.isBuffer(t[1]) || t[1] instanceof Uint8Array) || t[1].length !== t[2]) throw new XWingError("xwing/bad-input", "xwing.combiner: " + t[0] + " must be a " + t[2] + "-byte byte array");
+  });
+  return nodeCrypto.createHash("sha3-256").update(Buffer.concat([ssM, ssX, ctX, pkX, XWING_LABEL])).digest();
+}
+
+// Expand a 32-byte seed into ML-KEM key material + the X25519 scalar.
+function _expand(seed) {
+  var e = _shake256(seed, EXPAND_LEN);
+  var kp = mlkem.keygen(e.subarray(0, MLKEM_SEED));     // KeyGen_internal(d, z)
+  var skX = e.subarray(MLKEM_SEED, EXPAND_LEN);
+  return { skM: kp.secretKey, pkM: kp.publicKey, skX: skX, pkX: _x25519Public(skX) };
+}
+
+/**
+ * @primitive  b.crypto.xwing.keygen
+ * @signature  b.crypto.xwing.keygen(seed?)
+ * @since      0.13.3
+ * @status     experimental
+ * @compliance soc2
+ * @related    b.crypto.xwing.encapsulate, b.crypto.xwing.decapsulate
+ *
+ * Generate an X-Wing keypair. The decapsulation key is a 32-byte seed (store
+ * this); the encapsulation key is the 1216-byte public key to publish. Pass a
+ * 32-byte <code>seed</code> for deterministic generation, or omit it for a
+ * random key.
+ *
+ * @example
+ *   var kp = b.crypto.xwing.keygen();
+ *   kp.publicKey.length;   // → 1216
+ *   kp.secretKey.length;   // → 32  (the seed — keep it secret)
+ */
+function keygen(seed) {
+  if (seed == null) seed = nodeCrypto.randomBytes(SEED_LEN);
+  if (!Buffer.isBuffer(seed) || seed.length !== SEED_LEN) throw new XWingError("xwing/bad-seed", "xwing.keygen: seed must be a " + SEED_LEN + "-byte Buffer");
+  var k = _expand(seed);
+  return { publicKey: Buffer.concat([k.pkM, k.pkX]), secretKey: Buffer.from(seed) };
+}
+
+/**
+ * @primitive  b.crypto.xwing.encapsulate
+ * @signature  b.crypto.xwing.encapsulate(publicKey, eseed?)
+ * @since      0.13.3
+ * @status     experimental
+ * @compliance soc2
+ * @related    b.crypto.xwing.decapsulate, b.crypto.xwing.keygen
+ *
+ * Encapsulate to a 1216-byte X-Wing public key. Returns the 1120-byte
+ * <code>ciphertext</code> to send and the 32-byte <code>sharedSecret</code> to
+ * key a symmetric cipher with. Pass a 64-byte <code>eseed</code>
+ * (X25519 ephemeral scalar ‖ ML-KEM coins) for deterministic encapsulation, or
+ * omit it for fresh randomness.
+ *
+ * @example
+ *   var enc = b.crypto.xwing.encapsulate(recipientPublicKey);
+ *   enc.ciphertext.length;   // → 1120
+ *   enc.sharedSecret.length; // → 32
+ */
+function encapsulate(publicKey, eseed) {
+  if (!Buffer.isBuffer(publicKey) || publicKey.length !== PK_LEN) throw new XWingError("xwing/bad-public-key", "xwing.encapsulate: publicKey must be a " + PK_LEN + "-byte Buffer");
+  var pkM = publicKey.subarray(0, ML_KEM_PK);
+  var pkX = publicKey.subarray(ML_KEM_PK, PK_LEN);
+  var ekX, mlkemCoins = null;
+  if (eseed == null) {
+    ekX = nodeCrypto.randomBytes(X25519_LEN);
+  } else {
+    if (!Buffer.isBuffer(eseed) || eseed.length !== 2 * X25519_LEN) throw new XWingError("xwing/bad-eseed", "xwing.encapsulate: eseed must be a " + (2 * X25519_LEN) + "-byte Buffer");
+    // draft EncapsulateDerand: eseed[0:32] = ML-KEM coins, eseed[32:64] = X25519
+    // ephemeral scalar. This order matches the draft's test vectors.
+    mlkemCoins = eseed.subarray(0, X25519_LEN);
+    ekX = eseed.subarray(X25519_LEN, 2 * X25519_LEN);
+  }
+  var ctX = _x25519Public(ekX);
+  var ssX = _x25519Shared(ekX, pkX);
+  var kem = mlkemCoins ? mlkem.encapsulate(pkM, mlkemCoins) : mlkem.encapsulate(pkM);
+  var ss = combiner(kem.sharedSecret, ssX, ctX, pkX);
+  return { ciphertext: Buffer.concat([kem.cipherText, ctX]), sharedSecret: ss };
+}
+
+/**
+ * @primitive  b.crypto.xwing.decapsulate
+ * @signature  b.crypto.xwing.decapsulate(secretKey, ciphertext)
+ * @since      0.13.3
+ * @status     experimental
+ * @compliance soc2
+ * @related    b.crypto.xwing.encapsulate, b.crypto.xwing.keygen
+ *
+ * Recover the 32-byte shared secret from a 1120-byte X-Wing ciphertext using
+ * the 32-byte decapsulation seed. ML-KEM-768's implicit-rejection means a
+ * tampered ciphertext yields a different (still 32-byte) secret rather than an
+ * error, so never branch on success — derive keys and let the AEAD tag fail.
+ *
+ * @example
+ *   var ss = b.crypto.xwing.decapsulate(kp.secretKey, enc.ciphertext);
+ *   ss.equals(enc.sharedSecret);   // → true
+ */
+function decapsulate(secretKey, ciphertext) {
+  if (!Buffer.isBuffer(secretKey) || secretKey.length !== SEED_LEN) throw new XWingError("xwing/bad-seed", "xwing.decapsulate: secretKey must be a " + SEED_LEN + "-byte Buffer");
+  if (!Buffer.isBuffer(ciphertext) || ciphertext.length !== CT_LEN) throw new XWingError("xwing/bad-ciphertext", "xwing.decapsulate: ciphertext must be a " + CT_LEN + "-byte Buffer");
+  var k = _expand(secretKey);
+  var ctM = ciphertext.subarray(0, ML_KEM_CT);
+  var ctX = ciphertext.subarray(ML_KEM_CT, CT_LEN);
+  var ssM = mlkem.decapsulate(ctM, k.skM);
+  var ssX = _x25519Shared(k.skX, ctX);
+  return combiner(ssM, ssX, ctX, k.pkX);
+}
+
+module.exports = {
+  NAME:        "X-Wing",
+  keygen:      keygen,
+  encapsulate: encapsulate,
+  decapsulate: decapsulate,
+  combiner:    combiner,
+  SIZES:       { publicKey: PK_LEN, ciphertext: CT_LEN, secretKey: SEED_LEN, sharedSecret: SS_LEN },
+  XWingError:  XWingError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "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:45c82292-580f-4bfa-aa46-23d8f36d6b83",
+  "serialNumber": "urn:uuid:4dae8994-eae5-41f2-9afe-f4d18c950644",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-26T23:17:31.244Z",
+    "timestamp": "2026-05-27T00:14:33.058Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.2",
+      "bom-ref": "@blamejs/core@0.13.3",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.2",
+      "version": "0.13.3",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.2",
+      "purl": "pkg:npm/%40blamejs/core@0.13.3",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.2",
+      "ref": "@blamejs/core@0.13.3",
       "dependsOn": []
     }
   ]