@blamejs/pki 0.6.51 → 0.6.53

package/lib/cmp-verify.js

@@ -32,6 +32,10 @@ var asn1 = require("./asn1-der");
 var oid = require("./oid");
 var cmpBuild = require("./cmp-build");
 var cmp = require("./schema-cmp");
+var cms = require("./schema-cms");
+var cmsVerify = require("./cms-verify");
+var cmsDecrypt = require("./cms-decrypt");
+var pkcs8 = require("./schema-pkcs8");
 var pkix = require("./schema-pkix");
 var pbes2 = require("./pbes2");
 var x509 = require("./schema-x509");
@@ -840,6 +844,315 @@ async function _verify(message, opts) {
   return _verifySignature(m, protectedPart, protectionAlg, protection, opts);
 }
 
+var KNOWN_OPEN_KEY_PACKAGE_OPTS = intrinsic.assign(intrinsic.create(null), {
+  key: 1, cert: 1, password: 1, trustAnchors: 1, intermediates: 1, time: 1,
+  authorizedBySharedSecret: 1,
+});
+var OID_A_KEY_PACKAGE = oid.byName("aKeyPackage");
+var OID_SIGNED_DATA = oid.byName("signedData");
+var OID_ENVELOPED_DATA = oid.byName("envelopedData");
+var OID_CM_KGA = oid.byName("cmKGA");
+
+function _keyPackageErr(reason, cause) { return _err("cmp/bad-key-package", reason, cause); }
+
+/** @internal The three shapes sec. 4.1.6 profiles out of an EnvelopedData, read from the parsed
+ * container before anything is decrypted: the structure is an EnvelopedData, exactly one party can
+ * open it, and what it holds is a SignedData. */
+function _assertKeyPackageContainer(parsed) {
+  if (parsed.contentTypeName !== "envelopedData") {
+    throw _keyPackageErr("a delivered key package is carried in a CMS EnvelopedData, and this container is a " +
+      parsed.contentTypeName + " (RFC 9483 sec. 4.1.6)");
+  }
+  var ris = parsed.recipientInfos;
+  if (!_isArray(ris) || ris.length !== 1) {
+    throw _keyPackageErr("a delivered key package names exactly one RecipientInfo, and this container names " +
+      guard.text.showValue(ris && ris.length) +
+      "; a second recipient is a second party able to open a key generated for this entity (RFC 9483 sec. 4.1.6)");
+  }
+  /** @internal A `KeyAgreeRecipientInfo` wraps the content-encryption key once per entry in its
+   * `recipientEncryptedKeys` (RFC 5652 sec. 6.2.2), each for a different recipient under one
+   * originator, so counting RecipientInfos alone would admit a second party under one of them. */
+  var reks = ris[0].recipientEncryptedKeys;
+  if (_isArray(reks) && reks.length !== 1) {
+    throw _keyPackageErr("the key agreement RecipientInfo of a delivered key package wraps the content-encryption key once, and this one wraps it " +
+      reks.length + " times; each is a party able to open a key generated for this entity (RFC 9483 sec. 4.1.6, RFC 5652 sec. 6.2.2)");
+  }
+  var eci = parsed.encryptedContentInfo;
+  if (!eci || eci.contentType !== OID_SIGNED_DATA) {
+    throw _keyPackageErr("the encrypted content of a delivered key package is declared id-signedData, and this container declares " +
+      guard.text.showValue(eci && eci.contentType) + " (RFC 9483 sec. 4.1.6)");
+  }
+}
+
+/** @internal RFC 5958 sec. 2: AsymmetricKeyPackage ::= SEQUENCE SIZE (1..MAX) OF OneAsymmetricKey.
+ * Each element is surfaced as its own DER buffer, which is what a PKCS#8 `PrivateKeyInfo` is
+ * (`PrivateKeyInfo ::= OneAsymmetricKey`), so a caller imports it without re-encoding. Copied off the
+ * decrypted content rather than sliced from it, so holding one key does not hold the package. */
+var ASYMMETRIC_KEY_PACKAGE = schema.seqOf(
+  schema.decode(function (n, ctx) {
+    if (!(n.tagClass === "universal" && n.tagNumber === asn1.TAGS.SEQUENCE && n.children && n.children.length >= 1)) {
+      throw ctx.E("cmp/bad-key-package", "an AsymmetricKeyPackage element must be a OneAsymmetricKey SEQUENCE (RFC 5958 sec. 2)");
+    }
+    /** @internal OneAsymmetricKey and a PKCS#8 PrivateKeyInfo are the same structure (RFC 5958
+     * sec. 2), so the shipped strict parser decides whether an element is one; a SEQUENCE that merely
+     * looks like a container is not a delivered key. */
+    try { pkcs8.parse(n.bytes); }
+    catch (e) { throw ctx.E("cmp/bad-key-package", "an AsymmetricKeyPackage element is not a OneAsymmetricKey (RFC 5958 sec. 2)", e); }
+    return _bufferFrom(n.bytes);
+  }),
+  { assert: "sequence", min: 1, code: "cmp/bad-key-package", what: "AsymmetricKeyPackage",
+    build: function (m) { return _map(m.items, function (it) { return it.value; }); } });
+
+function _readKeyPackage(der) {
+  var node;
+  try { node = asn1.decode(der); }
+  catch (e) { throw _keyPackageErr("the signed content is not DER", e); }
+  return schema.walk(ASYMMETRIC_KEY_PACKAGE, node, NS).result;
+}
+
+function _fixOpenKeyPackageOptions(opts, made) {
+  opts = guard.identifier.optionsObject(opts, _err, "cmp/bad-input", "pki.cmp.openKeyPackage options");
+  guard.identifier.assertKnownKeys(opts, KNOWN_OPEN_KEY_PACKAGE_OPTS, _err, "cmp/bad-input", "unknown opts field ");
+  var f = {
+    key: opts.key,
+    cert: _fixByteish(opts.cert, "cert"),
+    password: _fixSecret(opts.password, made, "password"),
+    trustAnchors: _fixCertList(opts.trustAnchors, "trustAnchors"),
+    intermediates: _fixPoolCerts(opts.intermediates, "intermediates"),
+    time: _fixTime(opts.time),
+    exempt: opts.authorizedBySharedSecret === true,
+  };
+  if (opts.authorizedBySharedSecret != null && typeof opts.authorizedBySharedSecret !== "boolean") {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret is a boolean stating that this entity protected its request with the shared secret");
+  }
+  if (f.key == null && f.password == null) {
+    throw _err("cmp/bad-input", "opening a delivered key package needs the key material the content-encryption key was protected to: opts.key (with opts.cert) for the key transport and key agreement techniques, or opts.password for the password technique (RFC 9483 sec. 4.1.6.1 to 4.1.6.3)");
+  }
+  if (f.key != null && f.password != null) {
+    throw _err("cmp/bad-input", "a delivered key package is opened by one key management technique: pass opts.key or opts.password, not both");
+  }
+  /** @internal sec. 4.1.6 offers the shared-secret exemption only to an entity that protected its
+   * request with a MAC, which is the entity opening this container with that secret. Stating it
+   * alongside a private key claims the exemption for a signature-protected exchange, where the
+   * section's requirement to validate the signer stands. */
+  if (f.exempt && f.password == null) {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret authorizes the key generation authority by the secret that protected the request, so it applies only to a container opened with opts.password (RFC 9483 sec. 4.1.6)");
+  }
+  if (f.exempt && f.trustAnchors != null) {
+    throw _err("cmp/bad-input", "opts.authorizedBySharedSecret and opts.trustAnchors state two different rules for authorizing the key generation authority; supply one");
+  }
+  if (!f.exempt && f.trustAnchors == null) {
+    throw _err("cmp/bad-input", "authorizing the key generation authority needs opts.trustAnchors, or opts.authorizedBySharedSecret when this entity protected its request with the shared secret (RFC 9483 sec. 4.1.6)");
+  }
+  return f;
+}
+
+async function _openKeyPackage(container, opts) {
+  var bytes = _asContentInfo(
+    guard.bytes.snapshotSource(_coerceKeyPackageBytes(container), CmpError, "cmp/bad-input", "the delivered key package container"),
+    OID_ENVELOPED_DATA, "the delivered key package container");
+  var parsed;
+  try { parsed = cms.parse(bytes); }
+  catch (e) { throw _keyPackageErr("the delivered key package container is not a CMS ContentInfo", e); }
+  _assertKeyPackageContainer(parsed);
+
+  /** @internal The profile fixes the recipient count at one, so the arm to open is named instead of
+   * matched: a caller holding only the private key need not supply the certificate as well. */
+  /** @internal Every way the container fails to open reports the one code, so the verdict carries no
+   * more than "it did not open": `pki.cms.decrypt` already collapses each secret-dependent failure to
+   * a single uniform result, and splitting that back out here would rebuild the oracle it removes. */
+  var opened;
+  try {
+    opened = await cmsDecrypt.decrypt(bytes, opts.password != null ? { password: opts.password } : { key: opts.key, cert: opts.cert },
+      { recipientIndex: 0 });
+  } catch (e) {
+    throw _keyPackageErr("the delivered key package could not be opened under the supplied key material", e);
+  }
+
+  var verdict;
+  var signedData = _asContentInfo(opened.content, OID_SIGNED_DATA, "the encrypted content");
+  try { verdict = await cmsVerify.verify(signedData, _signedDataVerifyOpts(opts)); }
+  catch (e) { throw _keyPackageErr("the SignedData wrapping the key package could not be verified", e); }
+  if (!verdict.valid) {
+    throw _keyPackageErr("the signature over the delivered key package does not verify; the SignedData reports [" +
+      intrinsic.join(_map(verdict.signers, function (s) { return s.code || "a signature mismatch"; }), ", ") + "]");
+  }
+  if (verdict.eContentType !== OID_A_KEY_PACKAGE) {
+    throw _keyPackageErr("the signed content type is " + verdict.eContentType + ", not id-ct-KP-aKeyPackage; the signature must bind what it covers to a key package (RFC 9483 sec. 4.1.6, RFC 5958 sec. 2)");
+  }
+  var signerCert = verdict.signers[0] && verdict.signers[0].cert;
+  if (!signerCert) throw _keyPackageErr("the SignedData names no signer certificate to authorize as the key generation authority");
+  _authorizeKga(verdict, signerCert, opts);
+  if (verdict.eContent == null) throw _keyPackageErr("the SignedData carries no encapsulated content, so no key package was delivered");
+  return { keys: _readKeyPackage(verdict.eContent), kga: _bufferFrom(signerCert), trusted: opts.exempt ? false : true };
+}
+
+/** @internal sec. 4.1.6: the entity "MUST use a certificate containing the additional extended key
+ * usage extension id-kp-cmKGA in order to be accepted by the EE as a legitimate key generation
+ * authority", and the EE "MUST validate the signer certificate". `pki.path.validate`'s `requiredEku`
+ * answers the RFC 5280 sec. 4.2.1.12 question (does this certificate PERMIT the purpose), which an
+ * absent extension satisfies, so the assertion is checked here as well as the chain. */
+function _authorizeKga(verdict, signerCert, opts) {
+  if (opts.exempt) return;
+  if (!verdict.trusted) {
+    throw _err("cmp/unauthorized-kga", "the certificate that signed the delivered key package does not chain to an accepted trust anchor (RFC 9483 sec. 4.1.6)");
+  }
+  var parsedSigner;
+  try { parsedSigner = x509.parse(signerCert); }
+  catch (e) { throw _err("cmp/unauthorized-kga", "the certificate that signed the delivered key package could not be read", e); }
+  if (!pkix.assertsPurpose(NS, parsedSigner, OID_CM_KGA)) {
+    throw _err("cmp/unauthorized-kga", "the certificate that signed the delivered key package does not assert the id-kp-cmKGA extended key usage, which is what a key generation authority uses to show it is one (RFC 9483 sec. 4.1.6, RFC 9480 sec. 2.2)");
+  }
+}
+
+function _signedDataVerifyOpts(opts) {
+  if (opts.exempt) return {};
+  var v = { trustAnchors: opts.trustAnchors, requiredEku: [OID_CM_KGA] };
+  if (opts.intermediates != null) v.certs = opts.intermediates;
+  if (opts.time != null) v.time = opts.time;
+  return v;
+}
+
+/** @internal The certificate options here take one certificate or a list of them, as DER or PEM, which
+ * is the shape `pki.cmp.verify` takes. `pki.cms.verify` takes `certs` as a list of DER, so the pool is
+ * normalized at the door: a single certificate forwarded unwrapped would be walked as a sequence of
+ * its own bytes and contribute nothing, and a PEM string would not be read at all. */
+function _fixPoolCerts(v, label) {
+  if (v == null) return v;
+  var list = _fixCertList(_isArray(v) ? v : [v], label);
+  return _map(list, function (c, i) {
+    if (typeof c !== "string") return c;
+    try { return x509.pemDecode(c); }
+    catch (e) { throw _err("cmp/bad-input", "opts." + label + "[" + i + "] PEM could not be decoded", e); }
+  });
+}
+
+/** @internal Both CMS layers arrive in either of two forms, and the two are structurally exclusive so
+ * neither is guessed at. A ContentInfo opens with an OBJECT IDENTIFIER naming its content type; the
+ * bare structure opens with its own `CMSVersion` INTEGER. Both forms are seen in practice. A CMP
+ * `EncryptedKey` carries the `EnvelopedData` itself (RFC 9810 sec. 5.2.2), and RFC 5652 sec. 6.1
+ * encrypts the CONTENT rather than a ContentInfo around it, so the plaintext under an `id-signedData`
+ * `encryptedContentInfo` is a `SignedData`. Each is wrapped so one code path reads both. Anything
+ * else is left alone for the ContentInfo parse to refuse by name. */
+function _asContentInfo(der, contentTypeOid, what) {
+  var node;
+  try { node = asn1.decode(der); }
+  catch (e) { throw _keyPackageErr(what + " is not DER", e); }
+  var first = node.constructed && node.children ? node.children[0] : null;
+  if (!first || first.tagClass !== "universal" || first.tagNumber !== asn1.TAGS.INTEGER) return der;
+  return b.sequence([b.oid(contentTypeOid), b.explicit(0, b.raw(der))]);
+}
+
+function _coerceKeyPackageBytes(container) {
+  if (typeof container === "string") {
+    try { return cms.pemDecode(container); }
+    catch (e) { throw _err("cmp/bad-input", "the delivered key package container PEM could not be decoded", e); }
+  }
+  return container;
+}
+
+/**
+ * @primitive pki.cmp.openKeyPackage
+ * @signature pki.cmp.openKeyPackage(container, opts) -> Promise<{ keys, kga, trusted }>
+ * @since 0.6.52
+ * @status stable
+ * @spec RFC 9483 sec. 4.1.6, RFC 5958, RFC 5652, RFC 9480 sec. 2.2
+ * @defends unauthorized-key-generation-authority (CWE-863)
+ * @related pki.cmp.session, pki.cms.decrypt, pki.cms.verify
+ *
+ * Open a centrally generated private key delivered in a CMP response (RFC 9483 sec. 4.1.6). A CA that
+ * generates the key pair on the end entity's behalf puts it in the `privateKey` field of the granted
+ * `CertifiedKeyPair`: an RFC 5958 `AsymmetricKeyPackage`, signed by the Key Generation Authority in a
+ * CMS `SignedData`, sealed to this entity in a CMS `EnvelopedData`. `container` is those
+ * `EnvelopedData` bytes (DER `Buffer` or PEM), which `pki.cmp.session` surfaces as
+ * `deliveredKey` when the session is told to accept one.
+ *
+ * The two layers are undone in order and the authority is authorized BEFORE any key material is
+ * returned. Which key management technique opens the container follows the protection of the request
+ * that asked for the key: `opts.key` (with `opts.cert`) for the key transport and key agreement
+ * techniques a signature-protected request selects (sec. 4.1.6.1, sec. 4.1.6.2), `opts.password` for
+ * the password technique a MAC-protected request selects (sec. 4.1.6.3).
+ *
+ * Authorization is the point of the verb. The section requires the signer's certificate to carry the
+ * `id-kp-cmKGA` extended key usage "in order to be accepted by the EE as a legitimate key generation
+ * authority", so a certificate that merely PERMITS the purpose by carrying no `extendedKeyUsage` at
+ * all does not authorize: the assertion must be present, and the certificate must chain to an anchor
+ * in `opts.trustAnchors`. The one exception is the section's own: an entity that protected its request
+ * with a shared secret "MAY omit the validation" and authorize the authority by that secret instead.
+ * That is stated with `opts.authorizedBySharedSecret`, it applies only to a container opened with
+ * `opts.password`, and the result then reports `trusted: false`.
+ *
+ * Returns `{ keys, kga, trusted }`. `keys` is every `OneAsymmetricKey` in the package, in order, each
+ * as its own DER `Buffer` that is a PKCS#8 `PrivateKeyInfo` ready for `pki.key.import`. `kga` is the
+ * signer certificate whose signature was checked. `trusted` says whether that certificate chained.
+ * Malformed input, an unopenable container, an unverifiable signature, or an unauthorized authority
+ * all throw a typed `CmpError`; no key material is returned on any of them.
+ *
+ * The container's shape is held to the profile where the shape decides who reads the key or what the
+ * signature covers: it must be an `EnvelopedData`, it must name exactly one `RecipientInfo`, its
+ * encrypted content type must be `id-signedData`, and the signed content type must be
+ * `id-ct-KP-aKeyPackage`. The profile's CMS version literals are not enforced, because RFC 5652
+ * sec. 5.1 and sec. 6.1 derive those from the signer and recipient forms in use and a conforming
+ * sender reaches different values. Its choice-of-form rules, the signer identifier form and the
+ * ordering of the certificates the SignedData carries, are not judged either. Both live inside the
+ * encrypted SignedData rather than in the `container` bytes, and the result carries only the signer
+ * certificate, so a caller holding a stricter profile cannot judge them from this verdict.
+ *
+ * `keys` is the whole RFC 5958 `AsymmetricKeyPackage`, which is `SIZE (1..MAX)`, so a package carrying
+ * several is opened and every key returned. RFC 9483 sec. 4.1.6 profiles that to a sequence of one,
+ * and where the count decides something it is held: a `pki.cmp.session` enrollment requires exactly
+ * one, since one grant certifies one key and every further key is one the issued certificate says
+ * nothing about. A caller using this verb on its own owns that binding.
+ *
+ * @opts
+ *   - `key` (Buffer|PEM|CryptoKey) -- this entity's private key, for a container opened by the key
+ *     transport or key agreement technique.
+ *   - `cert` (Buffer|PEM) -- the certificate for `key`. Optional: the profile fixes the recipient
+ *     count at one, so the arm is named rather than matched.
+ *   - `password` (string|Buffer) -- the shared secret, for a container opened by the password
+ *     technique. Copied at the door and wiped when the call returns.
+ *   - `trustAnchors` (Buffer|Buffer[]|PEM) -- the roots this entity accepts for the key generation
+ *     authority. REQUIRED unless `authorizedBySharedSecret` is set.
+ *   - `intermediates` (Buffer|Buffer[]|PEM) -- extra untrusted pool certificates for path building.
+ *   - `time` (Date) -- the validity instant for path validation. Defaults to the current time.
+ *   - `authorizedBySharedSecret` (boolean) -- authorize the authority by the secret that protected
+ *     the request rather than by a chain, which sec. 4.1.6 permits a MAC-protected exchange. Requires
+ *     `opts.password` and refuses `opts.trustAnchors`.
+ * @example
+ *   var nb = new Date("2026-01-01T00:00:00Z"), na = new Date("2036-01-01T00:00:00Z");
+ *   var kgaPair = await pki.key.generate("Ed25519");                       // the key generation authority
+ *   var kgaKey = await pki.key.export(kgaPair.privateKey);
+ *   var kgaCert = await pki.x509.sign({ subject: "Key Generation Authority",
+ *     subjectPublicKey: await pki.key.export(kgaPair.publicKey), notBefore: nb, notAfter: na,
+ *     extensions: { basicConstraints: { cA: true }, keyUsage: ["digitalSignature", "keyCertSign"],
+ *       extendedKeyUsage: ["cmKGA"], subjectKeyIdentifier: true } }, { key: kgaKey });
+ *   var rsa = { name: "RSA-OAEP", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" };
+ *   var eePair = await pki.key.generate(rsa);                              // the enrolling end entity
+ *   var eeKey = await pki.key.export(eePair.privateKey);
+ *   var eeCert = await pki.x509.sign({ subject: "Enrolling client",
+ *     subjectPublicKey: await pki.key.export(eePair.publicKey), notBefore: nb, notAfter: na,
+ *     extensions: { keyUsage: ["keyEncipherment"] } }, { key: eeKey });
+ *   var generated = await pki.key.export((await pki.key.generate("Ed25519")).privateKey);
+ *   var signedPackage = await pki.cms.sign(pki.asn1.build.sequence([pki.asn1.build.raw(generated)]),
+ *     [{ key: kgaKey, cert: kgaCert }], { eContentType: "aKeyPackage", sid: "ski" });
+ *   var deliveredKeyDer = await pki.cms.encrypt(signedPackage, [{ cert: eeCert }],
+ *     { contentEncryptionAlgorithm: "aes-256-cbc", contentType: "signedData" });
+ *   var opened = await pki.cmp.openKeyPackage(deliveredKeyDer,
+ *     { key: eeKey, cert: eeCert, trustAnchors: [kgaCert] });
+ *   opened.keys.length;                                   // 1
+ *   var privateKey = await pki.key.import(opened.keys[0]);
+ */
+function openKeyPackage(container, opts) {
+  var made = [];
+  return guard.async.deferred(async function () {
+    try {
+      return await _openKeyPackage(container, _fixOpenKeyPackageOptions(opts, made));
+    } finally {
+      guard.secret.zeroizeAll(made, CmpError, "cmp/bad-input", "the copied key package shared secret");
+    }
+  });
+}
+
 /**
  * @primitive  pki.cmp.verify
  * @signature  pki.cmp.verify(message, opts?) -> Promise<verdict>
@@ -929,6 +1242,7 @@ module.exports = {
   transfer: cmpBuild.transfer,
   wellKnownUrl: cmpBuild.wellKnownUrl,
   verify: verify,
+  openKeyPackage: openKeyPackage,
   setEngine: setEngine,
   senderBoundToCert: _senderBoundToCert,
 };

package/lib/composite-kem.js

@@ -102,9 +102,16 @@ function _okpPubFromRaw(d, raw) {
   var spki = _b.sequence([_b.sequence([_b.oid(oid.byName(d.trad.curve))]), _b.bitString(raw, 0)]);
   return nodeCrypto.createPublicKey({ key: spki, format: "der", type: "spki" });
 }
+/** @internal The encoding is this helper's own allocation and holds the traditional private scalar, so
+ * it is cleared here. A caller's own cleanup cannot reach a buffer it never sees, and both the
+ * derivation and the decapsulation reach the curve through this one function. */
 function _okpPrivFromRaw(d, raw) {
   var p8 = _b.sequence([_b.integer(0n), _b.sequence([_b.oid(oid.byName(d.trad.curve))]), _b.octetString(_b.octetString(raw))]);
-  return nodeCrypto.createPrivateKey({ key: p8, format: "der", type: "pkcs8" });
+  try {
+    return nodeCrypto.createPrivateKey({ key: p8, format: "der", type: "pkcs8" });
+  } finally {
+    guard.secret.zeroize(p8, KemError, "kem/bad-input", "the " + d.trad.curve + " component key encoding");
+  }
 }
 function _rawPubOf(keyObject) {
   var spki = keyObject.export({ format: "der", type: "spki" });
@@ -170,7 +177,20 @@ function _tradDecaps(d, tradSK, tradCT) {
   var dh;
   try { dh = Buffer.from(nodeCrypto.diffieHellman({ privateKey: priv2, publicKey: eph })); }
   catch (e) { return Promise.reject(_err("kem/decapsulation-failed", "the " + trad.curve + " Diffie-Hellman failed", e)); }
-  return Promise.resolve({ ss: dh, tradPK: _rawPubOf(nodeCrypto.createPublicKey(priv2)) });
+  /** @internal The same canonical point the derivation states, read from the one function that spells
+   * it. The combiner hashes these bytes, so a stored spelling here and a generated one there would
+   * reach different secrets from the two sides of one key. */
+  var tradPK;
+  try {
+    tradPK = trad.kind === "ec" ? _ecPointOf(d, tradSK) : _rawPubOf(nodeCrypto.createPublicKey(priv2));
+  } catch (e) {
+    /** @internal The agreement already produced a secret, and this rejection happens after it, so the
+     * secret is wiped here: the caller's settle-or-wipe covers a value it was handed, and a rejected
+     * promise hands it nothing. */
+    guard.secret.zeroize(dh, KemError, "kem/bad-input", "the " + trad.curve + " component secret");
+    return Promise.reject(e);
+  }
+  return Promise.resolve({ ss: dh, tradPK: tradPK });
 }
 
 function _combine(d, mlkemSS, tradSS, tradCT, tradPK) {
@@ -309,8 +329,152 @@ async function _encapsulate(publicKey) {
 
 function _isCompositeKem(algOid) { return COMPOSITE_KEM[algOid] != null; }
 
+/** @internal The EC component's public point, generated from its scalar. RFC 5915 sec. 3 gives an
+ * ECPrivateKey an optional public point which may be written compressed, and the key engine keeps
+ * whatever encoding it was handed. The composite concatenation carries the uncompressed point at a
+ * fixed width (draft sec. 4.1), and the combiner hashes those bytes, so BOTH the derivation and the
+ * decapsulation read this one function: a point spelled two ways would agree on the secret nowhere. */
+function _ecPointOf(d, tradSK) {
+  /** @internal The scalar is a fresh copy of private key material, so it is wiped here rather than
+   * left for the caller's own copies to cover: those wipe the PKCS#8 and the key octets, and this
+   * buffer is neither. */
+  var scalar = _ecScalarOf(d, tradSK);
+  var point;
+  try {
+    var ecdh = nodeCrypto.createECDH(d.trad.node);
+    ecdh.setPrivateKey(scalar);
+    point = ecdh.getPublicKey(null, "uncompressed");
+  } catch (e) {
+    if (e instanceof KemError) throw e;
+    throw _err("kem/bad-key", "the EC component scalar does not generate a point on " + d.trad.node, e);
+  } finally {
+    guard.secret.zeroize(scalar, KemError, "kem/bad-input", "the EC component scalar");
+  }
+  if (point.length !== d.trad.ctLen) throw _err("kem/bad-key", "the EC component point is not the expected " + d.trad.ctLen + " bytes for " + d.name);
+  return point;
+}
+
+/** @internal The private scalar of a SEC1 ECPrivateKey (RFC 5915 sec. 3), left-padded to the field
+ * width the curve uses. The structure states the scalar as an OCTET STRING in its second field, and
+ * the point generation below is positional, so a short one is padded rather than shifted. */
+function _ecScalarOf(d, tradSK) {
+  var width = (d.trad.ctLen - 1) / 2;
+  var raw;
+  try {
+    var node = asn1.decode(tradSK);
+    raw = Buffer.from(asn1.read.octetString(node.children[1]));
+  } catch (e) { throw _err("kem/bad-key", "the EC component private key is not a well-formed ECPrivateKey", e); }
+  /** @internal `raw` holds private key material. It is handed on only when it IS the returned buffer,
+   * which the caller then wipes; on every other exit, the padded one and the refusal alike, this is
+   * the last reference and the copy is cleared here. */
+  var handedOn = false;
+  try {
+    if (raw.length === 0 || raw.length > width) throw _err("kem/bad-key", "the EC component scalar is not a " + d.trad.node + " field element");
+    if (raw.length === width) { handedOn = true; return raw; }
+    var out = Buffer.alloc(width);
+    raw.copy(out, width - raw.length);
+    return out;
+  } finally {
+    if (!handedOn) guard.secret.zeroize(raw, KemError, "kem/bad-input", "the EC component scalar copy");
+  }
+}
+
+/** @internal The traditional component's public half, derived from its private half by the same route
+ * `_tradDecaps` takes to report `tradPK`. Each kind states its private key in its own encoding: an
+ * RSAPrivateKey, a SEC1 ECPrivateKey, or the raw scalar an OKP curve carries. */
+function _tradPubOf(d, tradSK) {
+  var trad = d.trad;
+  if (trad.kind === "rsa") {
+    var rp;
+    try {
+      asn1.decode(tradSK);
+      rp = nodeCrypto.createPrivateKey({ key: tradSK, format: "der", type: "pkcs1" });
+    } catch (e) { throw _err("kem/bad-key", "the RSA component private key is not a valid RSAPrivateKey", e); }
+    if (rp.asymmetricKeyDetails.modulusLength !== trad.bits) {
+      throw _err("kem/bad-key", "the RSA component modulus is not " + trad.bits + " bits (draft sec. 6)");
+    }
+    return Buffer.from(nodeCrypto.createPublicKey(rp).export({ format: "der", type: "pkcs1" }));
+  }
+  var priv;
+  try {
+    if (trad.kind === "ec") {
+      asn1.decode(tradSK);
+      priv = nodeCrypto.createPrivateKey({ key: tradSK, format: "der", type: "sec1" });
+    } else {
+      priv = _okpPrivFromRaw(d, tradSK);
+    }
+  } catch (e) { throw _err("kem/bad-key", "the " + trad.curve + " key material is invalid", e); }
+  /** @internal A SEC1 ECPrivateKey names its own curve, and the composite OID names the curve the
+   * component must be on. Exporting the point of one curve under an OID that names another states a
+   * public key nothing can use, so the two are held to each other here. Decapsulation reaches the same
+   * conclusion by failing the agreement; a derivation performs no operation that would notice. */
+  if (trad.kind === "ec") {
+    var named = priv.asymmetricKeyDetails && priv.asymmetricKeyDetails.namedCurve;
+    if (named !== trad.node) {
+      throw _err("kem/bad-key", "the EC component is on " + guard.text.showValue(named) + ", and " + d.name + " names " + trad.node);
+    }
+    /** @internal Recomputed from the scalar rather than exported. RFC 5915 gives an ECPrivateKey an
+     * optional public point, the key engine keeps whatever encoding it was handed, and a compressed
+     * point is neither the width nor the form the composite concatenation carries (draft sec. 4.1).
+     * Generating the point from the scalar answers with the key this component actually holds, so a
+     * point stored beside it cannot stand in for one it does not generate. */
+    return _ecPointOf(d, tradSK);
+  }
+  return _rawPubOf(nodeCrypto.createPublicKey(priv));
+}
+
+/** @internal The composite `SubjectPublicKeyInfo` for a composite ML-KEM private key. The runtime key
+ * decoder does not know a composite OID, so a caller deriving one cannot go through it; the key is
+ * split the way `_decapsulate` splits it (draft sec. 4.1: `seed || tradSK`) and each half states its
+ * own public key, concatenated under the same OID as `mlkemEK || tradPK` (sec. 5.1). The ML-KEM half
+ * is recovered by importing the seed and reading the public key it generates, so a stored public copy
+ * could not answer in its place. The private material is wiped on every path. */
+async function _publicFromPrivate(privateKey) {
+  var pkcs8 = _toDer(privateKey, "PRIVATE KEY", "the composite ML-KEM private key");
+  /** @internal Every buffer this derivation allocates that holds private key material is registered
+   * here and cleared once, on every exit. A copy added later is covered by registering it rather than
+   * by a further nested block, which is how the ML-KEM seed encoding came to outlive two of them. */
+  var secrets = [];
+  guard.list.append(secrets, pkcs8);
+  var d;
+  try {
+    var sk;
+    try {
+      var info = schemaPkcs8.parse(pkcs8);
+      var alg = info.privateKeyAlgorithm;
+      d = _descriptorForAlg(alg.oid, alg.parameters !== null);
+      sk = Buffer.from(info.privateKey);
+      guard.list.append(secrets, sk);
+    } catch (e) {
+      if (e instanceof KemError) throw e;
+      if (e && e.code === "pkcs8/bad-algorithm-parameters") throw _err("kem/bad-algorithm", "a composite ML-KEM AlgorithmIdentifier MUST have absent parameters (draft sec. 5.3)", e);
+      throw _err("kem/bad-key", "the composite ML-KEM private key is not a well-formed OneAsymmetricKey", e);
+    }
+    if (sk.length <= MLKEM_SEED) throw _err("kem/bad-key", "the composite private key is shorter than the ML-KEM seed");
+    var seed = sk.subarray(0, MLKEM_SEED), tradSK = sk.subarray(MLKEM_SEED);
+    var ek;
+    try {
+      /** @internal The seed re-encoded as a OneAsymmetricKey the key engine reads, which is a second
+       * copy of the seed and is registered as one. */
+      var seedPkcs8 = _mlkemSeedPkcs8(d, seed);
+      guard.list.append(secrets, seedPkcs8);
+      var mlPriv = nodeCrypto.createPrivateKey({ key: seedPkcs8, format: "der", type: "pkcs8" });
+      ek = _rawPubOf(nodeCrypto.createPublicKey(mlPriv));
+    } catch (e) {
+      if (e instanceof KemError) throw e;
+      throw _err("kem/bad-key", "the ML-KEM component private key is invalid", e);
+    }
+    if (ek.length !== d.mlkemEk) throw _err("kem/bad-key", "the ML-KEM component public key is not the expected " + d.mlkemEk + " bytes for " + d.name);
+    var composite = Buffer.concat([ek, _tradPubOf(d, tradSK)]);
+    return _b.sequence([_b.sequence([_b.oid(oid.byName(d.name))]), _b.bitString(composite, 0)]);
+  } finally {
+    guard.secret.zeroizeAll(secrets, KemError, "kem/bad-input", "the composite private key material");
+  }
+}
+
 module.exports = {
   encapsulate: _encapsulate,
   decapsulate: _decapsulate,
   isCompositeKem: _isCompositeKem,
+  publicFromPrivate: _publicFromPrivate,
 };

package/lib/guard-name.js

@@ -332,6 +332,55 @@ function _hostConstraintBody(s) {
   return _charAt(h, 0) === "." ? _strSlice(h, 1) : h;
 }
 
+/** @internal A label with nothing in it, which is what makes a subtree base unmatchable. The
+ * comparisons in lib/path-validate.js compare a base against a name by suffix, so a base carrying an
+ * empty label asks for a name carrying one, and a name that carries one is not a name. */
+function _hasEmptyLabel(s) {
+  if (s.length === 0) return true;
+  if (_charAt(s, 0) === "." || _charAt(s, s.length - 1) === ".") return true;
+  return _indexOf(s, "..") !== -1;
+}
+
+/** @internal Whether the comparison can read a constraint base at all, which is a narrower question
+ * than whether a caller may state one. The door holds a caller to a well-formed host name; the
+ * comparison asks only whether an empty label leaves the base matching no name, and answers such a
+ * base with no verdict rather than with no match, since an excluded subtree that matches nothing
+ * excludes nothing. The two differ in both directions. A label carrying an underscore or edged with a
+ * hyphen is not a host name the door accepts, and the suffix comparison still applies it to exactly
+ * the names it names, so it stays enforced. The reduction here is the comparison's own, so the two
+ * cannot part company over a base like "..", whose body is empty only once a leading dot the
+ * comparison keeps has been taken off.
+ *
+ * The rule follows the comparison's own branches rather than the tag alone, since one tag can be
+ * compared two ways. An rfc822Name base carrying an at-sign is matched exactly and is read as a
+ * mailbox; one without an at-sign constrains the host and is read as a subtree, as a dNSName base is.
+ *
+ * A base that reduces to nothing is read by tag, because the comparisons do not agree on it. For
+ * dNSName it names the root of the namespace and `hostConstraintMatch` matches every name, so it is
+ * readable. For rfc822Name the same reduction leaves no domain to compare and `emailMatch` matches no
+ * mailbox, and for uniformResourceIdentifier `uriMatch` reads no host, so both are unreadable.
+ * @enforced-by behavioral -- the rule has no rename-proof code shape, and the RED vectors in
+ * path-validate.test.js driving a CA's own nameConstraints extension are the guard. */
+function constraintBaseUnreadable(tag, base) {
+  if (typeof base !== "string") return true;
+  /** @internal A base carrying an at-sign names one mailbox, and `emailMatch` compares it to a name
+   * exactly, local part and domain alike, rather than as a subtree. Each half is therefore read on
+   * its own terms: the local part by the RFC 5321 sec. 4.1.2 Dot-string or Quoted-string rule, which
+   * admits an underscore and refuses an empty atom, and the domain by the empty-label rule. A
+   * bracketed address literal carries no empty label in either accepted form, so the domain rule
+   * passes it through to the comparison, which reads it whole. */
+  if (tag === 1 && _lastIndexOf(base, "@") !== -1) {
+    var mb = splitMailbox(base);
+    if (mb === null || mb === "ambiguous") return true;
+    if (!_isMailboxLocal(mb[0])) return true;
+    return _hasEmptyLabel(stripTrailingDot(mb[1]));
+  }
+  var body = stripTrailingDot(base);
+  if (body === "") return tag !== 2;
+  if (_charAt(body, 0) === ".") body = _strSlice(body, 1);
+  return _hasEmptyLabel(body);
+}
+
 /** @internal Why a name-constraint base cannot be enforced, or null when it can. A base outside the
  * form its tag names is not a narrower namespace: an empty dNSName base matches every name, and a
  * base holding characters no host name can hold matches none, so the same value that reads as a
@@ -358,11 +407,19 @@ function constraintBaseRefusal(tag, base) {
     return _isHostName(_hostConstraintBody(base)) ? null
       : "must be a host name, optionally written as a subtree with a leading dot";
   }
+  /** @internal RFC 5280 sec. 4.2.1.10 says of a URI constraint: "The constraint MUST be specified as
+   * a fully qualified domain name and MAY specify a host or a domain. Examples would be
+   * host.example.com and .example.com." Its dNSName paragraph states no such requirement, so a single
+   * label is a valid dNSName base and is not a valid URI base. A caller meets this rule at the door,
+   * whether through `pki.trust.anchor` or through the validator's subtree seeds. A base a certificate
+   * carries in its own extension never reaches a door, and `uriMatch` is what holds it to the rule
+   * there, answering `path/name-constraint-unsupported` for a host it cannot read as fully qualified.
+   * `constraintBaseUnreadable` does not judge label count and does not stand in for that check. */
   if (tag === 6) {
     var h = _hostConstraintBody(_toLowerCase(base));
     var dotted = _isHostName(h) && _indexOf(h, ".") !== -1 && !_allCharsIn(h, _DIGDOT_TABLE);
     return dotted ? null
-      : "must be a dotted host name, which is the part of a URI a certificate is compared by";
+      : "must be a fully qualified domain name, which RFC 5280 sec. 4.2.1.10 requires of a URI constraint and not of a dNSName one";
   }
   return null;
 }
@@ -473,4 +530,5 @@ module.exports = intrinsic.freeze({
   lowerAscii: lowerAscii,
   stripTrailingDot: stripTrailingDot, isFqdnHost: isFqdnHost, splitMailbox: splitMailbox,
   constraintBaseRefusal: constraintBaseRefusal,
+  constraintBaseUnreadable: constraintBaseUnreadable,
 });

package/lib/guard-parsed.js

@@ -193,6 +193,22 @@ function isRecordedAsProduced(obj) {
   return true;
 }
 
+/**
+ * The bytes a recorded parse result came from, for a consumer that has to hand DER on to a verb taking
+ * bytes rather than a parsed object. A copy, so the caller cannot reach the recorded source.
+ *
+ * Null for anything not recorded, and for a result whose fields no longer match what the parse
+ * produced: the bytes are the truth, so handing them on for an object a caller has since edited would
+ * silently discard the edit and forward something the caller did not mean.
+ *
+ * @enforced-by behavioral -- an accessor has no rename-proof shape to detect; its contract is pinned by
+ * the vectors that drive it on an unrecorded object, a recorded one, and an edited one.
+ */
+function sourceOf(obj) {
+  if (!isRecordedAsProduced(obj)) return null;
+  return _bufferFrom(_weakGet(PROVENANCE, obj).source);
+}
+
 function _shapeOf(obj) {
   var shape = _create(null);
   var keys = _allNames(obj);
@@ -278,5 +294,5 @@ module.exports = _freezeExports({
   fromTrustedSource: fromTrustedSource, recordingParser: recordingParser,
   recordingWalker: recordingWalker,
   isCert: certShape, isCrl: crlShape, isRecorded: isRecorded,
-  isRecordedAsProduced: isRecordedAsProduced,
+  isRecordedAsProduced: isRecordedAsProduced, sourceOf: sourceOf,
 });