@blamejs/pki 0.1.22 → 0.1.24

package/lib/schema-x509.js

@@ -11,7 +11,7 @@
  *
  * @intro
  *   X.509 certificate handling per RFC 5280. The seed surface is
- *   `parse` — turn a DER or PEM certificate into a structured,
+ *   `parse` -- turn a DER or PEM certificate into a structured,
  *   fully-decoded object: version, serial, signature algorithm, issuer
  *   and subject distinguished names, validity window (as real `Date`s),
  *   subject public-key info, and the extension list. The parser composes
@@ -48,15 +48,16 @@ var PemError = frameworkError.PemError;
  * @spec       RFC 7468, RFC 5280
  * @related    pki.schema.x509.pemEncode
  *
- * Extract the DER bytes from a PEM block. With `label` given (e.g.
- * `"CERTIFICATE"`) the block type must match; without it, the first block
- * is taken. Throws `PemError` on a missing / mismatched envelope or a
- * non-base64 body.
+ * Extract the DER bytes from a PEM block (default label `CERTIFICATE`, the
+ * RFC 7468 sec. 5 armor -- the canonical-label default every sibling format
+ * applies). Pass a `label` to enforce a different block type, or an explicit
+ * `null` to take the first block of any type. Throws `PemError` on a
+ * missing / mismatched envelope or a non-base64 body.
  *
  * @example
- *   var der = pki.schema.x509.pemDecode(pemText, "CERTIFICATE");
+ *   var der = pki.schema.x509.pemDecode(pemText);
  */
-function pemDecode(text, label) { return pkix.pemDecode(text, label, PemError); }
+function pemDecode(text, label) { return pkix.pemDecode(text, label === null ? null : (label || "CERTIFICATE"), PemError); }
 
 /**
  * @primitive  pki.schema.x509.pemEncode
@@ -85,17 +86,19 @@ var NS = pkix.makeNS("x509", CertificateError, oid);
 var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
 var NAME = pkix.name(NS);
 
-// Validity ::= SEQUENCE { notBefore Time, notAfter Time }. The historical guard
-// checked only children.length===2 (not the SEQUENCE tag) -> assert "constructed".
+// Validity ::= SEQUENCE { notBefore Time, notAfter Time } -- the outer tag is
+// asserted (a SET-tagged body is a different ASN.1 type, not a Validity).
+// pkix.time enforces the RFC 5280 sec. 4.1.2.5 encoding cutover on decode: a
+// validity date through 2049 must be UTCTime, GeneralizedTime is 2050 onward.
 var VALIDITY = schema.seq([
-  schema.field("notBefore", schema.time(NS)),
-  schema.field("notAfter", schema.time(NS)),
+  schema.field("notBefore", pkix.time(NS)),
+  schema.field("notAfter", pkix.time(NS)),
 ], {
-  assert: "constructed", arity: { exact: 2 }, code: "x509/bad-validity", what: "Validity",
+  assert: "sequence", arity: { exact: 2 }, code: "x509/bad-validity", what: "Validity",
   build: function (m) { return { notBefore: m.fields.notBefore.value, notAfter: m.fields.notAfter.value }; },
 });
 
-// SubjectPublicKeyInfo — the shared pkix.spki factory under the x509 NS.
+// SubjectPublicKeyInfo -- the shared pkix.spki factory under the x509 NS.
 var SPKI = pkix.spki(NS);
 
 var EXTENSIONS = pkix.extensions(NS);
@@ -103,7 +106,7 @@ var EXTENSIONS = pkix.extensions(NS);
 // Version ::= INTEGER { v1(0), v2(1), v3(2) }, [0] EXPLICIT DEFAULT v1. Read as a
 // BigInt so an out-of-range value can't coerce to a float; reject an explicitly-
 // encoded v1 (DER forbids encoding the DEFAULT).
-// version ::= INTEGER { v1(0), v2(1), v3(2) } inside a [0] EXPLICIT DEFAULT v1 —
+// version ::= INTEGER { v1(0), v2(1), v3(2) } inside a [0] EXPLICIT DEFAULT v1 --
 // DER forbids encoding the default, so 0 is rejected; 1->v2, 2->v3.
 var CERTIFICATE_VERSION = pkix.versionReader(NS, { "1": 2, "2": 3 });
 
@@ -122,19 +125,21 @@ var CERTIFICATE_TBS = schema.seq([
   schema.field("subject", NAME),
   schema.field("subjectPublicKeyInfo", SPKI),
   schema.trailing([
-    { tag: 1, name: "issuerUniqueID", schema: schema.any() },
-    { tag: 2, name: "subjectUniqueID", schema: schema.any() },
+    // RFC 5280 sec. 4.1.2.8 -- the unique identifiers are [n] IMPLICIT BIT
+    // STRING (context PRIMITIVE, unusedBits validated), never an EXPLICIT wrap.
+    { tag: 1, name: "issuerUniqueID", schema: schema.implicitBitString(1) },
+    { tag: 2, name: "subjectUniqueID", schema: schema.implicitBitString(2) },
     { tag: 3, name: "extensions", schema: EXTENSIONS, explicit: true, emptyCode: "x509/bad-extensions" },
   ], { minTag: 1, maxTag: 3, unexpectedCode: "x509/bad-tbs", orderCode: "x509/bad-tbs" }),
-], { assert: "constructed", code: "x509/bad-tbs", what: "tbsCertificate" });
+], { assert: "sequence", code: "x509/bad-tbs", what: "tbsCertificate" });
 
 // Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue
-// BIT STRING }. The build runs the RFC 5280 cross-field checks (§4.1.1.2 sig-alg
-// agreement, §4.1.2.4 non-empty issuer, §4.1.2.9 extensions-only-in-v3) after the
+// BIT STRING }. The build runs the RFC 5280 cross-field checks (sec. 4.1.1.2 sig-alg
+// agreement, sec. 4.1.2.4 non-empty issuer, sec. 4.1.2.9 extensions-only-in-v3) after the
 // structural walk, then assembles the public parse result. Raw-byte accessors
 // (serialNumberHex, tbsBytes, sig-alg agreement) read off the match-tree nodes.
 // Certificate ::= SEQUENCE { tbsCertificate, signatureAlgorithm, signatureValue }
-// — the shared SIGNED envelope. The certificate-specific invariants (outer==inner
+// -- the shared SIGNED envelope. The certificate-specific invariants (outer==inner
 // signatureAlgorithm agreement, non-empty issuer, v3-only extensions) live in the
 // build; the envelope owns the SEQUENCE-of-3 shape and signature extraction.
 var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
@@ -142,25 +147,31 @@ var CERTIFICATE = pkix.signedEnvelope(NS, CERTIFICATE_TBS, {
   build: function (e, ctx) {
     var tbs = e.tbsMatch; // CERTIFICATE_TBS seq-match (no build)
 
-    // RFC 5280 §4.1.1.2 — outer signatureAlgorithm MUST equal tbsCertificate.signature.
+    // RFC 5280 sec. 4.1.1.2 -- outer signatureAlgorithm MUST equal tbsCertificate.signature.
     if (!e.outerSignatureAlgorithmBytes.equals(tbs.fields.signature.node.bytes)) {
-      throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 §4.1.1.2)");
+      throw ctx.E("x509/bad-signature-algorithm", "signatureAlgorithm must match tbsCertificate.signature (RFC 5280 sec. 4.1.1.2)");
     }
 
     var version = tbs.fields.version.value; // 1 (default) | 2 | 3
     var issuer = tbs.fields.issuer.value.result;
-    // RFC 5280 §4.1.2.4 — issuer MUST be non-empty (an empty subject is permitted, §4.1.2.6).
+    // RFC 5280 sec. 4.1.2.4 -- issuer MUST be non-empty (an empty subject is permitted, sec. 4.1.2.6).
     if (!issuer.rdns.length) {
       throw ctx.E("x509/bad-issuer", "issuer must be a non-empty distinguished name");
     }
 
     var extField = tbs.fields.extensions;
     var hasExtensions = !!(extField && extField.present);
-    // RFC 5280 §4.1.2.9 — extensions appear only in a v3 certificate.
+    // RFC 5280 sec. 4.1.2.9 -- extensions appear only in a v3 certificate.
     if (hasExtensions && version !== 3) {
       throw ctx.E("x509/bad-version", "extensions are only permitted in a v3 certificate");
     }
 
+    // RFC 5280 sec. 4.1.2.8 -- issuerUniqueID / subjectUniqueID MUST NOT
+    // appear when the version is 1; they require a v2 or v3 certificate.
+    if ((tbs.fields.issuerUniqueID.present || tbs.fields.subjectUniqueID.present) && version < 2) {
+      throw ctx.E("x509/bad-version", "issuerUniqueID/subjectUniqueID require a v2 or v3 certificate (RFC 5280 sec. 4.1.2.8)");
+    }
+
     var serialNode = tbs.fields.serialNumber.node;
     return {
       version:               version,
@@ -211,7 +222,7 @@ var parse = pkix.makeParser({ pemLabel: "CERTIFICATE", PemError: PemError, Error
 
 // matches(root): does the decoded DER look like a Certificate? A CSR and a CRL
 // share the outer SEQUENCE-of-3 envelope, so the discriminator is inside the
-// tbs: a certificate has a Validity — a SEQUENCE of exactly two Time values — at
+// tbs: a certificate has a Validity -- a SEQUENCE of exactly two Time values -- at
 // position [serial, signature, issuer, VALIDITY] after the optional [0] version.
 // A CSR's certificationRequestInfo has subjectPublicKeyInfo there (no Validity),
 // and a CRL leads with a bare Time; neither matches. Used by the orchestrator.

package/lib/webcrypto.js

@@ -13,13 +13,13 @@
  *   A zero-dependency W3C Web Cryptography API (`Crypto` / `SubtleCrypto`
  *   / `CryptoKey`) built directly on Node's native `node:crypto`. It is
  *   the toolkit's injectable crypto engine, presented in the standard
- *   WebCrypto shape so operators — and every higher structure (X.509,
- *   CMS, OCSP) — reach for one familiar surface.
+ *   WebCrypto shape so operators -- and every higher structure (X.509,
+ *   CMS, OCSP) -- reach for one familiar surface.
  *
  *   Unlike the browser's built-in `crypto.subtle`, this engine is
  *   **PQC-first without being PQC-only**: the FIPS 204 ML-DSA and FIPS
  *   205 SLH-DSA signature suites sit alongside the full classical set PKI
- *   still runs on — RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH,
+ *   still runs on -- RSASSA-PKCS1-v1_5, RSA-PSS, RSA-OAEP, ECDSA, ECDH,
  *   Ed25519 / Ed448, AES-GCM / CBC / KW, HMAC, HKDF, PBKDF2, and the SHA
  *   family (including legacy SHA-1 for old certificates and signatures).
  *   FIPS 203 ML-KEM key generation and encoding are available; KEM
@@ -29,16 +29,18 @@
  *
  * @card
  *   A zero-dep, PQC-first W3C WebCrypto (`SubtleCrypto`) engine over
- *   `node:crypto` — ML-DSA + SLH-DSA signatures alongside the full
+ *   `node:crypto` -- ML-DSA + SLH-DSA signatures alongside the full
  *   classical algorithm set.
  */
 
 var nodeCrypto = require("node:crypto");
 var frameworkError = require("./framework-error");
 
-// Single-owner error class — co-located with its module (framework-error
-// stays the cross-module home; this is webcrypto-private).
-var WebCryptoError = frameworkError.defineClass("WebCryptoError");
+// Single-owner error class -- co-located with its module (framework-error
+// stays the cross-module home; this is webcrypto-private). withCause: a
+// failure discovered while processing decrypted/untrusted bytes threads the
+// underlying fault instead of discarding it.
+var WebCryptoError = frameworkError.defineClass("WebCryptoError", { withCause: true });
 
 var MAX_RANDOM_BYTES = 65536;
 
@@ -88,6 +90,29 @@ function _hashNode(h, who) {
   return node;
 }
 
+// W3C HMAC get-key-length: an explicit `length` is used as given (validated
+// to a positive multiple of 8, so the byte-level key material is exact and
+// never a raw RangeError out of randomBytes); an OMITTED length defaults to
+// the BLOCK size of the hash -- the HMAC key-pad width -- NOT the digest
+// size. A digest-size default would mint different key material than every
+// conforming WebCrypto for identical inputs, so MACs keyed through this
+// engine would fail to verify elsewhere.
+var HMAC_BLOCK_BITS = {
+  "SHA-1": 512, "SHA-256": 512, "SHA-384": 1024, "SHA-512": 1024,
+  "SHA3-256": 1088, "SHA3-384": 832, "SHA3-512": 576,
+};
+
+function _hmacLengthBits(alg, who) {
+  var name = (typeof alg.hash === "string") ? alg.hash : (alg.hash && alg.hash.name);
+  var blockBits = HMAC_BLOCK_BITS[String(name).toUpperCase()];
+  if (!blockBits) throw new WebCryptoError("webcrypto/not-supported", who + ": unsupported hash " + JSON.stringify(name));
+  if (alg.length == null) return blockBits;
+  if (typeof alg.length !== "number" || !isFinite(alg.length) || alg.length <= 0 || alg.length % 8 !== 0) {
+    throw new WebCryptoError("webcrypto/syntax", who + ": HMAC length must be a positive multiple of 8 bits");
+  }
+  return alg.length;
+}
+
 // WebCrypto namedCurve -> node namedCurve.
 var CURVE_NODE = { "P-256": "prime256v1", "P-384": "secp384r1", "P-521": "secp521r1" };
 var CURVE_FIELD_BYTES = { "P-256": 32, "P-384": 48, "P-521": 66 };
@@ -95,7 +120,7 @@ var CURVE_FIELD_BYTES = { "P-256": 32, "P-384": 48, "P-521": 66 };
 var ML_DSA_NODE = { "ML-DSA-44": "ml-dsa-44", "ML-DSA-65": "ml-dsa-65", "ML-DSA-87": "ml-dsa-87" };
 var ML_KEM_NODE = { "ML-KEM-512": "ml-kem-512", "ML-KEM-768": "ml-kem-768", "ML-KEM-1024": "ml-kem-1024" };
 
-// FIPS 205 SLH-DSA — stateless hash-based signatures. All twelve
+// FIPS 205 SLH-DSA -- stateless hash-based signatures. All twelve
 // parameter sets Node exposes; signing is one-shot (null algorithm), the
 // same shape as ML-DSA / EdDSA. KEM encapsulation for ML-KEM is not yet
 // in Node's API, so ML-KEM here is key-generation / encoding only.
@@ -104,6 +129,17 @@ var SLH_DSA_NODE = {};
  "shake-128s", "shake-128f", "shake-192s", "shake-192f", "shake-256s", "shake-256f"
 ].forEach(function (s) { SLH_DSA_NODE["SLH-DSA-" + s.toUpperCase()] = "slh-dsa-" + s; });
 
+// The algorithm names each keyed operation recognizes. Membership is checked
+// BEFORE the algorithm/key name binding so an unrecognized algorithm reports
+// NotSupportedError while a recognized-but-wrong-for-this-key one reports
+// InvalidAccessError, matching the W3C error ordering.
+var SIGN_VERIFY_NAMES = {};
+["RSASSA-PKCS1-V1_5", "RSA-PSS", "ECDSA", "ED25519", "ED448", "HMAC"]
+  .concat(Object.keys(ML_DSA_NODE), Object.keys(SLH_DSA_NODE))
+  .forEach(function (n) { SIGN_VERIFY_NAMES[n] = true; });
+var ENCRYPT_DECRYPT_NAMES = { "RSA-OAEP": true, "AES-GCM": true, "AES-CBC": true, "AES-CTR": true };
+var DERIVE_NAMES = { "ECDH": true, "X25519": true, "X448": true, "HKDF": true, "PBKDF2": true };
+
 // ---- CryptoKey -------------------------------------------------------
 
 /**
@@ -111,11 +147,11 @@ var SLH_DSA_NODE = {};
  * @signature  new pki.webcrypto.CryptoKey(type, extractable, algorithm, usages, handle)
  * @since      0.1.0
  * @status     stable
- * @spec       W3C WebCrypto §cryptokey
+ * @spec       W3C WebCrypto sec. cryptokey
  *
  * Opaque handle to key material, matching the W3C `CryptoKey` shape:
  * `{ type, extractable, algorithm, usages }`. The underlying
- * `node:crypto` KeyObject is non-enumerable and never serialized —
+ * `node:crypto` KeyObject is non-enumerable and never serialized --
  * extract material only through `subtle.exportKey`, and only when the key
  * was created `extractable`. Instances are produced by
  * `subtle.generateKey` / `subtle.importKey`; the constructor is rarely
@@ -140,6 +176,20 @@ function _requireUsage(key, usage) {
   }
 }
 
+// W3C WebCrypto sign/verify/encrypt/decrypt/deriveBits/deriveKey/wrapKey/
+// unwrapKey MUST throw an InvalidAccessError when the normalized algorithm's
+// name differs from the key's own algorithm name. The binding is load-bearing
+// for the one-shot signature families (EdDSA / ML-DSA / SLH-DSA): node derives
+// the algorithm from the KEY handle, so without this check the requested name
+// would be silently ignored and an operation requested under algorithm X could
+// be satisfied by a key of algorithm Y (algorithm confusion).
+function _requireAlgMatch(alg, key, who) {
+  var keyName = key && key.algorithm && key.algorithm.name;
+  if (String(keyName).toUpperCase() !== alg.name) {
+    throw new WebCryptoError("webcrypto/invalid-access", who + ": algorithm " + JSON.stringify(alg.name) + " does not match the key's algorithm " + JSON.stringify(keyName));
+  }
+}
+
 // ---- SubtleCrypto ----------------------------------------------------
 
 function SubtleCrypto() {}
@@ -164,8 +214,7 @@ SubtleCrypto.prototype.generateKey = async function generateKey(algorithm, extra
     return new CryptoKey("secret", extractable, { name: name, length: bits }, usages, secret);
   }
   if (name === "HMAC") {
-    var hnode = _hashNode(alg.hash, "generateKey HMAC");
-    var lenBits = alg.length || (nodeCrypto.createHash(hnode).digest().length * 8);
+    var lenBits = _hmacLengthBits(alg, "generateKey HMAC");
     var hkey = nodeCrypto.createSecretKey(nodeCrypto.randomBytes(lenBits / 8));
     return new CryptoKey("secret", extractable, { name: name, hash: { name: (typeof alg.hash === "string" ? alg.hash : alg.hash.name) }, length: lenBits }, usages, hkey);
   }
@@ -213,13 +262,32 @@ function _generateKeyPair(alg) {
 }
 
 function _hashObj(h) { if (!h) return undefined; return { name: (typeof h === "string" ? h : h.name) }; }
-function _bufToBigIntNum(exp) { var b = _toBuf(exp, "publicExponent"); return Number(BigInt("0x" + b.toString("hex"))); }
+// publicExponent arrives as a W3C BigInteger octet string but node:crypto
+// takes a JS number, so the value is bounds-checked BEFORE the Number()
+// narrowing: an empty buffer has no integer value (BigInt("0x") is a raw
+// SyntaxError), and a value above 2^32-1 is outside the interoperable
+// WebCrypto exponent range and heads toward Number's exact-integer limit,
+// where the narrowing would silently hand node a different exponent than
+// the caller requested.
+function _bufToBigIntNum(exp) {
+  var b = _toBuf(exp, "publicExponent");
+  if (b.length === 0) {
+    throw new WebCryptoError("webcrypto/syntax", "publicExponent must be a non-empty BigInteger octet string");
+  }
+  var v = BigInt("0x" + b.toString("hex"));
+  if (v > 0xffffffffn) {
+    throw new WebCryptoError("webcrypto/syntax", "publicExponent " + v.toString() + " exceeds the 2^32-1 bound");
+  }
+  return Number(v);
+}
 
 SubtleCrypto.prototype.sign = async function sign(algorithm, key, data) {
   var alg = _normalizeAlg(algorithm, "sign");
   _requireUsage(key, "sign");
   var buf = _toBuf(data, "sign");
   var name = alg.name;
+  if (!SIGN_VERIFY_NAMES[name]) throw new WebCryptoError("webcrypto/not-supported", "sign: unsupported algorithm " + JSON.stringify(name));
+  _requireAlgMatch(alg, key, "sign");
   if (name === "RSASSA-PKCS1-V1_5") {
     return _toArrayBuffer(nodeCrypto.sign(_hashNode(key.algorithm.hash, "sign"), buf, key._handle));
   }
@@ -249,6 +317,8 @@ SubtleCrypto.prototype.verify = async function verify(algorithm, key, signature,
   var sig = _toBuf(signature, "verify");
   var buf = _toBuf(data, "verify");
   var name = alg.name;
+  if (!SIGN_VERIFY_NAMES[name]) throw new WebCryptoError("webcrypto/not-supported", "verify: unsupported algorithm " + JSON.stringify(name));
+  _requireAlgMatch(alg, key, "verify");
   if (name === "RSASSA-PKCS1-V1_5") {
     return nodeCrypto.verify(_hashNode(key.algorithm.hash, "verify"), buf, key._handle, sig);
   }
@@ -269,10 +339,11 @@ SubtleCrypto.prototype.verify = async function verify(algorithm, key, signature,
     hm.update(buf);
     // Verify must RESOLVE false for any invalid signature, including one of
     // the wrong length. timingSafeEqual throws RangeError on a length
-    // mismatch, so gate on length first; the length is already public, so
-    // this leaks nothing a constant-time compare would protect.
-    var mac = hm.digest();
-    return mac.length === sig.length && nodeCrypto.timingSafeEqual(mac, sig);
+    // mismatch, so gate on the (public) length first, then compare the bytes
+    // in constant time. The length check leaks nothing a constant-time compare
+    // would protect; the secret-dependent byte comparison is timingSafeEqual.
+    var digest = hm.digest();
+    return digest.length === sig.length && nodeCrypto.timingSafeEqual(digest, sig);
   }
   throw new WebCryptoError("webcrypto/not-supported", "verify: unsupported algorithm " + JSON.stringify(name));
 };
@@ -282,6 +353,8 @@ SubtleCrypto.prototype.encrypt = async function encrypt(algorithm, key, data) {
   _requireUsage(key, "encrypt");
   var buf = _toBuf(data, "encrypt");
   var name = alg.name;
+  if (!ENCRYPT_DECRYPT_NAMES[name]) throw new WebCryptoError("webcrypto/not-supported", "encrypt: unsupported algorithm " + JSON.stringify(name));
+  _requireAlgMatch(alg, key, "encrypt");
   if (name === "RSA-OAEP") {
     return _toArrayBuffer(nodeCrypto.publicEncrypt({
       key: key._handle, padding: nodeCrypto.constants.RSA_PKCS1_OAEP_PADDING,
@@ -313,6 +386,8 @@ SubtleCrypto.prototype.decrypt = async function decrypt(algorithm, key, data) {
   _requireUsage(key, "decrypt");
   var buf = _toBuf(data, "decrypt");
   var name = alg.name;
+  if (!ENCRYPT_DECRYPT_NAMES[name]) throw new WebCryptoError("webcrypto/not-supported", "decrypt: unsupported algorithm " + JSON.stringify(name));
+  _requireAlgMatch(alg, key, "decrypt");
   if (name === "RSA-OAEP") {
     return _toArrayBuffer(nodeCrypto.privateDecrypt({
       key: key._handle, padding: nodeCrypto.constants.RSA_PKCS1_OAEP_PADDING,
@@ -346,7 +421,7 @@ function _secretBytes(key) { return key._handle.export(); }
 
 // AES-CTR: node always treats the full 128-bit block as the counter and
 // never reads the spec's `length` (counter-width) parameter. A length < 128
-// would silently diverge from the W3C definition, so fail closed — accept
+// would silently diverge from the W3C definition, so fail closed -- accept
 // only the one value node can honor.
 function _requireCtrLength128(alg) {
   if (alg.length !== 128) {
@@ -354,21 +429,41 @@ function _requireCtrLength128(alg) {
   }
 }
 
-// Raw key-agreement / KDF derivation with NO usage check — the usage a
+// W3C deriveBits: the requested length must be a positive multiple of 8 --
+// the `length / 8` narrowing in the per-algorithm branches below would
+// otherwise silently truncate a fractional byte count.
+function _requireDeriveLength(length, who) {
+  if (typeof length !== "number" || !isFinite(length) || length <= 0 || length % 8 !== 0) {
+    throw new WebCryptoError("webcrypto/operation", who + ": length must be a positive multiple of 8 bits");
+  }
+}
+
+// Raw key-agreement / KDF derivation with NO usage check -- the usage a
 // caller must hold differs by entry point (deriveBits requires "deriveBits",
 // deriveKey requires "deriveKey"), so each public method checks its own
 // usage and then routes the actual derivation through here.
 function _deriveBitsRaw(alg, key, length) {
   var name = alg.name;
   if (name === "ECDH" || name === "X25519" || name === "X448") {
+    _requireAlgMatch(alg, alg.public, name + " public key");
     var secret = nodeCrypto.diffieHellman({ privateKey: key._handle, publicKey: alg.public._handle });
-    return _toArrayBuffer(length == null ? secret : secret.subarray(0, length / 8));
+    if (length == null) return _toArrayBuffer(secret);
+    _requireDeriveLength(length, name);
+    // subarray clamps at the end of the secret, so an unchecked over-request
+    // would silently return fewer bytes than asked. W3C deriveBits: throw an
+    // OperationError when the requested length cannot be satisfied.
+    if (length / 8 > secret.length) {
+      throw new WebCryptoError("webcrypto/operation", name + ": requested " + length + " bits but the shared secret has " + (secret.length * 8));
+    }
+    return _toArrayBuffer(secret.subarray(0, length / 8));
   }
   if (name === "HKDF") {
+    _requireDeriveLength(length, "HKDF");
     var derived = nodeCrypto.hkdfSync(_hashNode(alg.hash, "HKDF"), _secretBytes(key), _toBuf(alg.salt, "HKDF salt"), _toBuf(alg.info || Buffer.alloc(0), "HKDF info"), length / 8);
     return derived instanceof ArrayBuffer ? derived : _toArrayBuffer(Buffer.from(derived));
   }
   if (name === "PBKDF2") {
+    _requireDeriveLength(length, "PBKDF2");
     var out = nodeCrypto.pbkdf2Sync(_secretBytes(key), _toBuf(alg.salt, "PBKDF2 salt"), alg.iterations, length / 8, _hashNode(alg.hash, "PBKDF2"));
     return _toArrayBuffer(out);
   }
@@ -378,18 +473,42 @@ function _deriveBitsRaw(alg, key, length) {
 SubtleCrypto.prototype.deriveBits = async function deriveBits(algorithm, key, length) {
   var alg = _normalizeAlg(algorithm, "deriveBits");
   _requireUsage(key, "deriveBits");
+  if (!DERIVE_NAMES[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "deriveBits: unsupported algorithm " + JSON.stringify(alg.name));
+  _requireAlgMatch(alg, key, "deriveBits");
   return _deriveBitsRaw(alg, key, length);
 };
 
 SubtleCrypto.prototype.deriveKey = async function deriveKey(algorithm, baseKey, derivedKeyType, extractable, keyUsages) {
-  // deriveKey requires the "deriveKey" usage — NOT "deriveBits". Delegating
+  // deriveKey requires the "deriveKey" usage -- NOT "deriveBits". Delegating
   // to this.deriveBits would false-reject a key created with ["deriveKey"]
   // and fail-open on a ["deriveBits"]-only key, so check the correct usage
   // here and route the raw derivation past deriveBits' own usage gate.
   _requireUsage(baseKey, "deriveKey");
   var alg = _normalizeAlg(algorithm, "deriveKey");
+  if (!DERIVE_NAMES[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "deriveKey: unsupported algorithm " + JSON.stringify(alg.name));
+  _requireAlgMatch(alg, baseKey, "deriveKey");
   var dk = _normalizeAlg(derivedKeyType, "deriveKey");
-  var bits = dk.length || (dk.name.indexOf("AES") === 0 ? dk.length : 256);
+  var bits;
+  if (dk.name.indexOf("AES") === 0) {
+    // W3C get-key-length for AES: the derivedKeyType MUST carry a length of
+    // 128/192/256. Without this check the derived key would silently take
+    // the size of the raw agreement/KDF output (e.g. a 384-bit "AES" key
+    // from a P-384 secret) instead of a usable AES size.
+    if (dk.length !== 128 && dk.length !== 192 && dk.length !== 256) {
+      throw new WebCryptoError("webcrypto/syntax", "deriveKey: " + dk.name + " length must be 128/192/256");
+    }
+    bits = dk.length;
+  } else if (dk.name === "HMAC") {
+    // The same W3C HMAC get-key-length rule as generateKey: an omitted
+    // length is the hash's BLOCK size, never a fixed 256.
+    bits = _hmacLengthBits(dk, "deriveKey");
+  } else {
+    // HKDF / PBKDF2 derived-key types carry no intrinsic size (W3C
+    // get-key-length is null): the base derivation decides -- a key
+    // agreement yields its full shared secret as the input keying
+    // material; a KDF base has no implicit output size and fails closed.
+    bits = dk.length != null ? dk.length : null;
+  }
   var raw = _deriveBitsRaw(alg, baseKey, bits);
   return this.importKey("raw", raw, dk, extractable, keyUsages);
 };
@@ -399,6 +518,8 @@ SubtleCrypto.prototype.wrapKey = async function wrapKey(format, key, wrappingKey
   var bytes = (format === "jwk") ? Buffer.from(JSON.stringify(exported)) : Buffer.from(exported);
   var alg = _normalizeAlg(wrapAlgorithm, "wrapKey");
   _requireUsage(wrappingKey, "wrapKey");
+  if (alg.name !== "AES-KW" && !ENCRYPT_DECRYPT_NAMES[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "wrapKey: unsupported algorithm " + JSON.stringify(alg.name));
+  _requireAlgMatch(alg, wrappingKey, "wrapKey");
   if (alg.name === "AES-KW") {
     var c = nodeCrypto.createCipheriv("aes" + wrappingKey.algorithm.length + "-wrap", _secretBytes(wrappingKey), Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
     return _toArrayBuffer(Buffer.concat([c.update(bytes), c.final()]));
@@ -416,6 +537,8 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
   // never verify the caller was actually permitted to unwrap (mirrors
   // wrapKey, which checks before both of its paths).
   _requireUsage(unwrappingKey, "unwrapKey");
+  if (alg.name !== "AES-KW" && !ENCRYPT_DECRYPT_NAMES[alg.name]) throw new WebCryptoError("webcrypto/not-supported", "unwrapKey: unsupported algorithm " + JSON.stringify(alg.name));
+  _requireAlgMatch(alg, unwrappingKey, "unwrapKey");
   var bytes;
   if (alg.name === "AES-KW") {
     var d = nodeCrypto.createDecipheriv("aes" + unwrappingKey.algorithm.length + "-wrap", _secretBytes(unwrappingKey), Buffer.from("A6A6A6A6A6A6A6A6", "hex"));
@@ -424,7 +547,17 @@ SubtleCrypto.prototype.unwrapKey = async function unwrapKey(format, wrappedKey,
     var unwrapKeyClone = _cloneWithUsage(unwrappingKey, "decrypt");
     bytes = Buffer.from(await this.decrypt(unwrapAlgorithm, unwrapKeyClone, wrappedKey));
   }
-  var keyData = (format === "jwk") ? JSON.parse(bytes.toString()) : bytes;
+  var keyData;
+  if (format === "jwk") {
+    // A NON-authenticating unwrap algorithm (AES-CBC / AES-CTR) decrypts
+    // tampered bytes "successfully", so this JSON.parse is the first point
+    // that can notice -- its failure must surface as the module's typed
+    // error (W3C: DataError), never a raw SyntaxError from the public API.
+    try { keyData = JSON.parse(bytes.toString()); }
+    catch (e) { throw new WebCryptoError("webcrypto/data", "unwrapKey: unwrapped bytes are not a valid JWK", e); }
+  } else {
+    keyData = bytes;
+  }
   return this.importKey(format, keyData, unwrappedKeyAlgorithm, extractable, keyUsages);
 };
 
@@ -477,7 +610,9 @@ function _importRawPublic(name, alg, raw, extractable, usages) {
   if (name === "ED25519" || name === "ED448" || name === "X25519" || name === "X448") {
     var jwk = { kty: "OKP", crv: (name === "ED25519" ? "Ed25519" : name === "ED448" ? "Ed448" : name === "X25519" ? "X25519" : "X448"), x: _bufToB64url(raw) };
     var ko = nodeCrypto.createPublicKey({ key: jwk, format: "jwk" });
-    return new CryptoKey("public", true, { name: alg.name === "ED25519" ? "Ed25519" : alg.name }, usages, ko);
+    // The canonical mixed-case EdDSA labels, matching _algFromImport -- a raw
+    // import must not label the same key differently than an spki/jwk one.
+    return new CryptoKey("public", true, { name: name === "ED25519" ? "Ed25519" : name === "ED448" ? "Ed448" : alg.name }, usages, ko);
   }
   if (name === "ECDSA" || name === "ECDH") {
     var fb = CURVE_FIELD_BYTES[alg.namedCurve];
@@ -491,7 +626,7 @@ function _importRawPublic(name, alg, raw, extractable, usages) {
 
 function _algFromImport(name, alg, keyObject) {
   if (name === "ECDSA" || name === "ECDH") {
-    // W3C WebCrypto EC import — the curve is a property of the KEY, not the
+    // W3C WebCrypto EC import -- the curve is a property of the KEY, not the
     // caller's claim. Derive it from the imported key material; reject an
     // unsupported curve (NotSupportedError, matching generateKey) and reject a
     // requested namedCurve that disagrees with the key (DataError). Trusting
@@ -523,7 +658,7 @@ function _curveFromKey(ko) {
  * @signature  await pki.webcrypto.subtle.exportKey(format, key)
  * @since      0.1.0
  * @status     stable
- * @spec       W3C WebCrypto §subtlecrypto, FIPS 186-5, FIPS 203, FIPS 204, FIPS 205, RFC 8017
+ * @spec       W3C WebCrypto sec. subtlecrypto, FIPS 186-5, FIPS 203, FIPS 204, FIPS 205, RFC 8017
  * @related    pki.webcrypto.CryptoKey
  *
  * Export a `CryptoKey` to `spki` (public), `pkcs8` (private), `jwk`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",
@@ -69,6 +69,7 @@
     "check:vendor-currency": "node scripts/check-vendor-currency.js"
   },
   "devDependencies": {
-    "esbuild": "0.28.1"
+    "esbuild": "0.28.1",
+    "eslint": "10.3.0"
   }
 }

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:38c53855-3eaa-4d1a-8c48-b03540881d8a",
+  "serialNumber": "urn:uuid:dfb00f98-2ca7-4fd1-b0e7-90fccf92604a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-09T18:46:47.249Z",
+    "timestamp": "2026-07-10T12:57:51.582Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.22",
+      "bom-ref": "@blamejs/pki@0.1.24",
       "type": "application",
       "name": "pki",
-      "version": "0.1.22",
+      "version": "0.1.24",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.1.22",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.24",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.22",
+      "ref": "@blamejs/pki@0.1.24",
       "dependsOn": []
     }
   ]