@blamejs/pki 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v0.3.4 — 2026-07-17
+
+pki.schema.c509.encode produces C509 CBOR certificates -- a DER X.509 certificate compresses to a compact, byte-exact-invertible type-3 C509, and a deterministic-CBOR encoder joins pki.cbor.
+
+### Added
+
+- pki.schema.c509.encode(input) encodes a C509 certificate to deterministic-CBOR bytes -- a DER X.509 v3 certificate to a compact type-3 C509 (byte-exact-invertible, so the original signature verifies), or a pki.schema.c509.parse result re-emitted to its native array. Canonical deterministic CBOR with the registry integer shorthands and the C509 compressions; a certificate outside the invertible covered set throws a typed C509Error. Certificate parsing remains pki.schema.c509.parse.
+- pki.cbor.build is a deterministic-CBOR encoder (RFC 8949 section 4.2) -- the byte-exact inverse of pki.cbor.decode: shortest-form heads, definite lengths, sorted and unique map keys, over unsigned and negative integers, byte and text strings, arrays, maps, tags, and the tagged bignum / epoch-time / object-identifier leaves. Encoded output always re-decodes through the strict decoder.
+
 ## v0.3.3 — 2026-07-17
 
 pki.crmf.build issues RFC 4211 certificate request messages -- a CertReqMessages with a signature proof of possession, over every algorithm the toolkit supports.

package/README.md

@@ -204,7 +204,7 @@ is callable today; nothing below is a stub.
 | `pki.webcrypto` | A W3C WebCrypto (`SubtleCrypto`) engine over `node:crypto` — `sign`/`verify`/`encrypt`/`decrypt`/`deriveBits`/`digest`/`generateKey`/`importKey`/`exportKey` across RSA, ECDSA, ECDH, Ed25519/Ed448, AES, HMAC, HKDF, PBKDF2, SHA — **and** post-quantum ML-DSA-44/65/87 and SLH-DSA signatures, plus ML-KEM-512/768/1024 key generation and certificate/PKCS#8 import — the RFC 9935 seed / expandedKey / both private-key CHOICE is validated fail-closed, so an OpenSSL-legacy bare-seed or an internally inconsistent key is rejected with a typed error (KEM encapsulation lands with CMS KEM-decrypt). Zero-dependency, OpenSSL-interoperable |
 | `pki.schema` | The schema family — `parse` detects which PKI format DER / PEM encodes and routes to the right parser, `all` enumerates the registered formats, and the engine + per-format members are grouped here |
 | `pki.schema.x509` | Parse DER / PEM certificates into structured, validated fields, with named + partly-decoded extensions — including the RFC 3739 / ETSI EN 319 412-5 qualified-certificate `qcStatements` (EU-qualified declaration, reliance limit, QSCD flag, certificate type, retention, PDS URLs, country of qualification; unknown statements preserved opaque) and the Microsoft Active Directory Certificate Services enrollment extensions (certificate template, CA version, previous-CA-certificate hash, application policies), fail-closed — `parse`, `pemDecode`, `pemEncode` |
-| `pki.schema.c509` | Parse C509 CBOR-encoded certificates (draft-ietf-cose-cbor-encoded-cert) — the compact CBOR profile of X.509, decoded fail-closed under deterministic CBOR; an explicit `parse` call (CBOR, not DER, so not auto-routed) |
+| `pki.schema.c509` | Parse **and encode** C509 CBOR-encoded certificates (draft-ietf-cose-cbor-encoded-cert) — the compact CBOR profile of X.509, decoded fail-closed under deterministic CBOR; an explicit `parse` call (CBOR, not DER, so not auto-routed). `encode(input)` is the byte-exact inverse: a DER X.509 v3 certificate forward-transforms to a compact type-3 C509 whose reconstruction reproduces the original DER byte for byte (so the original signature still verifies), or a `parse` result re-emits its native array — canonical deterministic CBOR with the registry integer shorthands and the C509 compressions; a certificate outside the invertible set throws a typed `C509Error` |
 | `pki.schema.crl` | Parse DER / PEM X.509 CRLs per RFC 5280 §5 — revoked serials with real-`Date` revocation times, named + partly-decoded extensions, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.csr` | Parse DER / PEM PKCS#10 certification requests per RFC 2986 — subject DN, public key, requested attributes, signature, fail-closed — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.pkcs8` | Parse DER / PEM PKCS#8 private keys per RFC 5208 / 5958 — algorithm, raw key bytes, attributes, optional public key, fail-closed; encrypted keys recognized (not decrypted) — `parse`, `parseEncrypted`, `pemDecode`, `pemEncode` |

package/lib/cbor-det.js

@@ -624,8 +624,111 @@ function readOid(node) {
   return asn1.decodeOidContent(inner.content);
 }
 
+// ---- deterministic-CBOR encoder (RFC 8949 sec. 4.2) -- the byte-exact inverse of decode ----
+// Every emitted head is the shortest form (the exact mirror of decode's cbor/non-minimal-argument reject),
+// every length is definite, and map keys are sorted bytewise + unique -- so decode(build.x(...)) round-trips
+// or the builder produced a shape its own strict decoder rejects. Nested items are pre-encoded CBOR item
+// Buffers (the asn1.build pattern); the CBOR-encoded PKI surfaces (C509, COSE) compose these leaves.
+function _cbItem(x, who) {
+  if (!Buffer.isBuffer(x)) throw new CborError("cbor/not-buffer", who + ": expected a pre-encoded CBOR item Buffer");
+  return x;
+}
+// Validate an assembled container decodes: well-formed nested items (no malformed head, indefinite length,
+// stray break, or trailing bytes), AND within the decoder's depth cap -- a container adds ONE nesting
+// level, so a child AT the cap would overflow the output. Decoding the whole output in one pass catches
+// both, so the encoder never produces bytes its own strict decoder rejects.
+function _assertDecodes(out, who) {
+  try { decode(out); } catch (e) { throw new CborError("cbor/bad-item", who + ": produced bytes the strict decoder rejects (" + (e && e.code) + ")", e); }
+  return out;
+}
+// Mirror the decoder's total-size cap (constants.LIMITS.CBOR_MAX_BYTES) so a string leaf never emits an
+// item the strict reader would reject as too large -- the encode/decode round trip stays closed under the
+// default limits.
+function _capString(out, who) {
+  if (out.length > constants.LIMITS.CBOR_MAX_BYTES) throw new CborError("cbor/too-large", who + ": encoded " + out.length + " bytes exceeds cap " + constants.LIMITS.CBOR_MAX_BYTES);
+  return out;
+}
+// Reject a JS string carrying an unpaired UTF-16 surrogate: Buffer.from(..., "utf8") would silently
+// substitute U+FFFD, so the emitted text string would not be the input (and read.text enforces well-formed
+// UTF-8). Fail closed to match the decoder rather than corrupt the text.
+function _assertWellFormedText(str, who) {
+  for (var i = 0; i < str.length; i++) {
+    var c = str.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) { var n = str.charCodeAt(i + 1); if (!(n >= 0xdc00 && n <= 0xdfff)) throw new CborError("cbor/bad-utf8", who + ": the string has an unpaired high surrogate"); i++; }
+    else if (c >= 0xdc00 && c <= 0xdfff) throw new CborError("cbor/bad-utf8", who + ": the string has an unpaired low surrogate");
+  }
+}
+// The initial byte + minimal-width argument for major type `mt` and unsigned `argument`.
+function _head(mt, argument, who) {
+  var a = typeof argument === "bigint" ? argument : BigInt(argument);
+  if (a < 0n) throw new CborError("cbor/bad-argument", who + ": a CBOR head argument must be non-negative");
+  if (a > 0xffffffffffffffffn) throw new CborError("cbor/bad-argument", who + ": a CBOR head argument exceeds 64 bits");
+  var mtb = mt << 5, b;
+  if (a <= 23n) return Buffer.from([mtb | Number(a)]);
+  if (a < 256n) return Buffer.from([mtb | 24, Number(a)]);
+  if (a < 65536n) { b = Buffer.alloc(3); b[0] = mtb | 25; b.writeUInt16BE(Number(a), 1); return b; }
+  if (a < 4294967296n) { b = Buffer.alloc(5); b[0] = mtb | 26; b.writeUInt32BE(Number(a), 1); return b; }
+  b = Buffer.alloc(9); b[0] = mtb | 27; b.writeBigUInt64BE(a, 1); return b;
+}
+var build = {
+  uint: function (n) { var a = typeof n === "bigint" ? n : BigInt(n); if (a < 0n) throw new CborError("cbor/bad-argument", "build.uint: value must be non-negative"); return _head(0, a, "build.uint"); },
+  nint: function (n) { var a = typeof n === "bigint" ? n : BigInt(n); if (a >= 0n) throw new CborError("cbor/bad-argument", "build.nint: value must be negative"); return _head(1, -1n - a, "build.nint"); },
+  int:  function (n) { var a = typeof n === "bigint" ? n : BigInt(n); return a >= 0n ? _head(0, a, "build.int") : _head(1, -1n - a, "build.int"); },
+  byteString: function (buf) { var b = _asBuffer(buf, "build.byteString"); return _capString(Buffer.concat([_head(2, b.length, "build.byteString"), b]), "build.byteString"); },
+  textString: function (s) { var str = String(s); _assertWellFormedText(str, "build.textString"); var b = Buffer.from(str, "utf8"); return _capString(Buffer.concat([_head(3, b.length, "build.textString"), b]), "build.textString"); },
+  array: function (items) {
+    if (!Array.isArray(items)) throw new CborError("cbor/bad-argument", "build.array: expected an array of pre-encoded items");
+    var parts = items.map(function (x, i) { return _cbItem(x, "build.array[" + i + "]"); });
+    return _assertDecodes(Buffer.concat([_head(4, items.length, "build.array")].concat(parts)), "build.array");
+  },
+  map: function (pairs) {
+    if (!Array.isArray(pairs)) throw new CborError("cbor/bad-argument", "build.map: expected an array of [key, value] pairs");
+    var enc = pairs.map(function (p, i) { if (!Array.isArray(p) || p.length !== 2) throw new CborError("cbor/bad-argument", "build.map[" + i + "]: each entry is a [key, value] pair"); return [_cbItem(p[0], "build.map key"), _cbItem(p[1], "build.map value")]; });
+    // RFC 8949 sec. 4.2.1 Core Deterministic: keys sorted in the BYTEWISE lexicographic order of their
+    // encodings -- NOT the length-first order of sec. 4.2.3 (the older RFC 7049 "Canonical CBOR" variant).
+    // This MUST match the decoder, which enforces bytewise order (_profile "deterministic" -> Buffer.compare
+    // at :70); a length-first sort here would emit a map the strict decoder then rejects as unsorted.
+    enc.sort(function (a, b) { return Buffer.compare(a[0], b[0]); });
+    for (var i = 1; i < enc.length; i++) { if (Buffer.compare(enc[i - 1][0], enc[i][0]) === 0) throw new CborError("cbor/duplicate-map-key", "build.map: duplicate map key"); }
+    var flat = [_head(5, pairs.length, "build.map")];
+    enc.forEach(function (p) { flat.push(p[0], p[1]); });
+    return _assertDecodes(Buffer.concat(flat), "build.map");
+  },
+  tag: function (tagNum, inner) { return _assertDecodes(Buffer.concat([_head(6, tagNum, "build.tag"), _cbItem(inner, "build.tag content")]), "build.tag"); },
+  boolean: function (v) { return Buffer.from([v ? 0xf5 : 0xf4]); },
+  nullValue: function () { return Buffer.from([0xf6]); },
+  raw: function (buf) { return _assertDecodes(_asBuffer(buf, "build.raw"), "build.raw"); },
+  // Tagged leaves -- the inverse of read.biguint / read.time / read.oid.
+  biguint: function (n) {
+    var a = typeof n === "bigint" ? n : BigInt(n);
+    if (a < 0n) throw new CborError("cbor/bad-argument", "build.biguint: value must be non-negative");
+    var hex = a.toString(16); if (hex.length % 2) hex = "0" + hex;
+    var mag = a === 0n ? Buffer.alloc(0) : Buffer.from(hex, "hex");
+    if (mag.length <= 8) throw new CborError("cbor/bad-argument", "build.biguint: a value that fits 8 bytes must use build.uint (RFC 8949 preferred serialization)");
+    // Mirror read.biguint's cap so the tagged bignum builder never emits a value the strict reader rejects.
+    if (mag.length > constants.LIMITS.CBOR_MAX_BIGUINT_BYTES) throw new CborError("cbor/biguint-too-large", "build.biguint: " + mag.length + " bytes exceeds cap " + constants.LIMITS.CBOR_MAX_BIGUINT_BYTES);
+    return build.tag(2, build.byteString(mag));
+  },
+  time: function (v) {
+    var ms;
+    if (v instanceof Date) {
+      ms = v.getTime();
+      if (Number.isNaN(ms)) throw new CborError("cbor/bad-time", "build.time: an Invalid Date has no epoch value");
+      // read.time reads only an integer (second-granularity) tag-1, so a sub-second Date cannot round-trip:
+      // reject it rather than silently truncate the milliseconds.
+      if (ms % 1000 !== 0) throw new CborError("cbor/bad-time", "build.time: a Date with sub-second precision cannot be a second-granularity CBOR epoch; round to whole seconds");
+    }
+    var secs = v instanceof Date ? BigInt(Math.floor(ms / 1000)) : (typeof v === "bigint" ? v : BigInt(v));
+    // Mirror read.time's bound so build.time never emits a tag-1 the strict reader would reject as out of range.
+    if (secs < -_MAX_EPOCH_SECONDS || secs > _MAX_EPOCH_SECONDS) throw new CborError("cbor/bad-time", "build.time: epoch seconds " + secs + " are outside the representable Date range");
+    return build.tag(1, build.int(secs));
+  },
+  oid: function (dotted) { return build.tag(111, build.byteString(asn1.encodeOidContent(dotted))); },
+};
+
 module.exports = {
   decode: decode,
+  build: build,
   read: {
     uint:           readUint,
     nint:           readNint,

package/lib/schema-all.js

@@ -298,7 +298,7 @@ module.exports = {
   x509: { parse: x509.parse, pemDecode: x509.pemDecode, pemEncode: x509.pemEncode },
   // C509 is CBOR, not DER: an explicit-call surface only, NOT added to FORMATS / the detect-and-route
   // parse() below (which detect DER shapes). No pemDecode/pemEncode -- C509 is binary CBOR.
-  c509: { parse: c509.parse },
+  c509: { parse: c509.parse, encode: c509.encode },
   crl:  { parse: crl.parse,  pemDecode: crl.pemDecode, pemEncode: crl.pemEncode },
   csr:  { parse: csr.parse,  pemDecode: csr.pemDecode, pemEncode: csr.pemEncode },
   pkcs8: { parse: pkcs8.parse, parseEncrypted: pkcs8.parseEncrypted, pemDecode: pkcs8.pemDecode, pemEncode: pkcs8.pemEncode },

package/lib/schema-c509.js

@@ -17,6 +17,8 @@
 var cbor = require("./cbor-det");
 var asn1 = require("./asn1-der");
 var oid = require("./oid");
+var x509 = require("./schema-x509");
+var pkix = require("./schema-pkix");
 var constants = require("./constants");
 var frameworkError = require("./framework-error");
 var validator = require("./validator-all");
@@ -452,14 +454,16 @@ function parse(input) {
     signatureValue: signatureValue,
   };
 
-  // Native (type-2) signed region (sec. 3.1.12): the RAW bytes of the CBOR-sequence elements 0..9 (NOT
-  // the outer array head, NOT the signature) -- a zero-copy subarray a native verifier hashes.
-  if (type === 2) {
-    var b0 = f[0].bytes, b9 = f[9].bytes;
-    var start = b0.byteOffset - input.byteOffset;
-    var end = b9.byteOffset - input.byteOffset + b9.length;
-    result.signedData = input.subarray(start, end);
-  }
+  // The RAW bytes of CBOR-array elements 0..9 (NOT the outer array head, NOT the signature) -- a zero-copy
+  // subarray. For a native (type-2) certificate this is the signed region a verifier hashes (sec. 3.1.12);
+  // surfaced as `_fieldBytes` for BOTH types so encode() re-emits a parsed certificate byte-for-byte (a
+  // re-derivation from the decoded values could differ on a canonical-equivalent form, breaking a type-2
+  // signature or a type-3 DER reconstruction). `signedData` keeps its type-2-only signed-region meaning.
+  // From the DECODED root's own bytes (root.bytes == array head + all 11 elements), not offset arithmetic
+  // on `input` (which breaks when input is a Uint8Array the codec normalized to a different buffer): the
+  // fields region is root.bytes minus the 1-byte array(11) head and minus the trailing signatureValue.
+  result._fieldBytes = root.bytes.subarray(1, root.bytes.length - f[10].bytes.length);
+  if (type === 2) result.signedData = result._fieldBytes;
 
   // Type-3 is an invertible re-encoding of a DER X.509 certificate: reconstruct the original DER
   // byte-for-byte so the original signature verifies and x509.parse recovers the certificate.
@@ -476,4 +480,325 @@ function matches(node) {
     (Number(node.children[0].argument) === 2 || Number(node.children[0].argument) === 3);
 }
 
-module.exports = { parse: parse, matches: matches };
+// ---- the encode (the producing side; draft-20 sec. 3) -----------------------
+// The byte-exact inverse of parse/reconstruct: emit the 11-element deterministic-CBOR C509 array via the
+// cbor.build.* emitter. Two inputs, dispatched structurally: a DER X.509 certificate (Buffer/PEM) -> the
+// FLAGSHIP type-3 forward transform (parse(encode(der)).reconstructedDer == der, so the original signature
+// verifies); a c509.parse result -> re-emit its native array. Signing-free (mirrors ct.encodeSctList).
+
+// The registry INVERSE tables -- the canonical int per name (the lossy forward map is resolved to ONE
+// choice: EXT_BY_INT maps both 2 and 7 to keyUsage, so keyUsage encodes to the canonical draft int 2).
+var SIG_ALG_TO_INT = { ecdsaWithSHA256: 0, ecdsaWithSHA384: 1, ecdsaWithSHA512: 2 };
+var PK_ALG_TO_INT = { rsaEncryption: 0, "ecPublicKey|prime256v1": 1, "ecPublicKey|secp384r1": 2, "ecPublicKey|secp521r1": 3 };
+var ATTR_TO_INT = { commonName: 1, surname: 2, serialNumber: 3, countryName: 4, localityName: 6, stateOrProvinceName: 7, organizationName: 8, organizationalUnitName: 9, title: 10 };
+var EXT_TO_INT = { subjectKeyIdentifier: 1, keyUsage: 2, subjectAltName: 3, basicConstraints: 4, authorityKeyIdentifier: 10 };
+
+// A non-negative BigInt -> its minimal big-endian ~biguint bytes (the leading 0x00 sign octet omitted).
+function _minBytes(n) {
+  if (n < 0n) throw _err("c509/bad-serial", "a ~biguint value must be non-negative");
+  if (n === 0n) return Buffer.alloc(0);
+  var hex = n.toString(16); if (hex.length % 2) hex = "0" + hex;
+  return Buffer.from(hex, "hex");
+}
+// A C509 AlgorithmIdentifier -> int (registry) | ~oid (bare bytes) | [~oid, params]. `key` selects the row.
+function _encAlgorithm(alg, toInt, key) {
+  var i = toInt[key];
+  if (i !== undefined && !(alg.parameters && alg.parameters.length)) return cbor.build.int(BigInt(i));
+  var oidBytes = cbor.build.byteString(asn1.encodeOidContent(alg.oid));   // ~oid: bare BER OID content
+  if (alg.parameters && alg.parameters.length) return cbor.build.array([oidBytes, cbor.build.byteString(alg.parameters)]);
+  return oidBytes;
+}
+// A SpecialText attribute value -> CBOR (text | tag-48 EUI). v1 encodes the text + eui64 forms.
+function _encSpecialText(rdn) {
+  if (rdn.eui64) return cbor.build.tag(48, cbor.build.byteString(rdn.eui64));
+  return cbor.build.textString(String(rdn.value));
+}
+// A Name -> CBOR: null (issuer only) | a bare SpecialText single utf8 commonName | an array of RDN pairs.
+function _encName(name, isSubject) {
+  if (name === null || name === undefined) {
+    if (!isSubject) return cbor.build.nullValue();   // issuer == subject (self-signed)
+    throw _err("c509/bad-name", "the subject Name is required");
+  }
+  var rdns = name.rdns || [];
+  if (rdns.length === 1 && rdns[0].type === "commonName" && !rdns[0].printable) return _encSpecialText(rdns[0]);
+  var items = [];
+  rdns.forEach(function (rdn) {
+    var ai = ATTR_TO_INT[rdn.type];
+    if (ai === undefined) throw _err("c509/bad-name", "attribute type " + rdn.type + " has no C509 registry int");
+    items.push(cbor.build.int(BigInt(rdn.printable ? -ai : ai)));   // sign selects printableString
+    items.push(_encSpecialText(rdn));
+  });
+  return cbor.build.array(items);
+}
+// subjectPublicKey -> CBOR: EC point byte string, or an RSA ~biguint modulus ([modulus, exponent] when e != 65537).
+function _encSpk(r) {
+  if (r.rsaPublicKey) {
+    var mod = cbor.build.byteString(_minBytes(r.rsaPublicKey.modulus));
+    if (r.rsaPublicKey.exponent === 65537n) return mod;
+    return cbor.build.array([mod, cbor.build.byteString(_minBytes(r.rsaPublicKey.exponent))]);
+  }
+  if (!Buffer.isBuffer(r.subjectPublicKey)) throw _err("c509/bad-spki", "the subjectPublicKey bytes are missing");
+  return cbor.build.byteString(r.subjectPublicKey);
+}
+// extensions -> CBOR: the keyUsage int-shortcut (a lone keyUsage), else an array of [extID, extValue] pairs.
+function _encExtensions(exts) {
+  if (exts.length === 1 && exts[0].name === "keyUsage" && typeof exts[0].keyUsageBits === "number") {
+    return cbor.build.int(BigInt(exts[0].critical ? -exts[0].keyUsageBits : exts[0].keyUsageBits));
+  }
+  var items = [];
+  exts.forEach(function (ext) {
+    var ei = EXT_TO_INT[ext.name];
+    if (ei !== undefined) {
+      items.push(cbor.build.int(BigInt(ext.critical ? -ei : ei)));
+      // a registered-int extension carries its extnValue DER bytes as a bare byte string.
+      if (!Buffer.isBuffer(ext.value)) throw _err("c509/non-invertible", "extension " + ext.name + " has no byte-string value to encode");
+      items.push(cbor.build.byteString(ext.value));
+    } else {
+      items.push(cbor.build.byteString(asn1.encodeOidContent(ext.oid)));   // ~oid extension id
+      if (!Buffer.isBuffer(ext.value)) throw _err("c509/non-invertible", "extension " + (ext.oid || ext.name) + " has no byte-string value to encode");
+      var bs = cbor.build.byteString(ext.value);
+      items.push(ext.critical ? cbor.build.array([bs]) : bs);              // critical ~oid value wraps in a 1-element array
+    }
+  });
+  return cbor.build.array(items);
+}
+// forward-declared below; the DER X.509 -> type-3 C509 structured result.
+var _derToType3;
+// A hand-built (no _fieldBytes) result must carry the structured fields the encode below reads; a missing or
+// wrong-typed field fails closed with a typed verdict rather than a raw property-access crash.
+function _requireResultShape(r) {
+  if (r.certificateType == null) throw _err("c509/bad-input", "a C509 result must carry certificateType");
+  if (r.serialNumber == null && r.serialNumberHex == null) throw _err("c509/bad-input", "a C509 result must carry serialNumber or serialNumberHex");
+  if (!r.signatureAlgorithm || typeof r.signatureAlgorithm.name !== "string") throw _err("c509/bad-input", "a C509 result must carry signatureAlgorithm.name");
+  if (!r.subjectPublicKeyAlgorithm || typeof r.subjectPublicKeyAlgorithm.name !== "string") throw _err("c509/bad-input", "a C509 result must carry subjectPublicKeyAlgorithm.name");
+  if (!r.validity || !(r.validity.notBefore instanceof Date) || (r.validity.notAfter !== null && !(r.validity.notAfter instanceof Date))) throw _err("c509/bad-input", "a C509 result must carry validity.notBefore (Date) and notAfter (Date or null)");
+  if (!Array.isArray(r.extensions)) throw _err("c509/bad-input", "a C509 result must carry an extensions array");
+  if (!Buffer.isBuffer(r.signatureValue)) throw _err("c509/bad-input", "a C509 result must carry a Buffer signatureValue");
+}
+// A validity Date -> its C509 ~time (a non-negative CBOR epoch uint). A pre-epoch date cannot be
+// represented (the parser accepts only an unwrapped major-type-0 integer) and fails closed here.
+function _validityUint(date, label) {
+  var secs = Math.floor(date.getTime() / 1000);
+  if (!isFinite(secs) || secs < 0) throw _err("c509/bad-validity", label + " is before the Unix epoch or not a valid date; C509 ~time is a non-negative CBOR epoch");
+  return cbor.build.uint(BigInt(secs));
+}
+// A structured C509 result -> the 11-element deterministic-CBOR array.
+function _encodeC509Array(r) {
+  // Re-emit a PARSED certificate's raw fields (elements 0..9) VERBATIM -- re-deriving from the decoded
+  // values could differ on a canonical-equivalent form (a byte-string attribute value, a registry alias)
+  // and break a type-2 native signature (which covers these bytes) or a type-3 DER reconstruction (which
+  // depends on the field values). Both types preserve the exact bytes; only a hand-built result (no
+  // _fieldBytes) re-derives from the structured values below.
+  if (Buffer.isBuffer(r._fieldBytes)) {
+    if (!Buffer.isBuffer(r.signatureValue)) throw _err("c509/bad-input", "a re-emitted certificate must carry a Buffer signatureValue");
+    var out = Buffer.concat([Buffer.from([0x8b]), r._fieldBytes, cbor.build.byteString(r.signatureValue)]);   // array(11) head + fields 0..9 + signatureValue
+    parse(out);   // fail closed: a caller-mutated _fieldBytes must still re-parse as a valid C509, else parse throws a typed c509/* verdict
+    return out;
+  }
+  _requireResultShape(r);
+  var pkKey = r.subjectPublicKeyAlgorithm.curve ? r.subjectPublicKeyAlgorithm.name + "|" + r.subjectPublicKeyAlgorithm.curve : r.subjectPublicKeyAlgorithm.name;
+  var arr = cbor.build.array([
+    cbor.build.int(BigInt(r.certificateType)),
+    cbor.build.byteString(r.serialNumberHex != null ? Buffer.from(r.serialNumberHex, "hex") : _minBytes(r.serialNumber)),
+    _encAlgorithm(r.signatureAlgorithm, SIG_ALG_TO_INT, r.signatureAlgorithm.name),
+    _encName(r.issuer, false),
+    _validityUint(r.validity.notBefore, "validityNotBefore"),
+    r.validity.notAfter === null ? cbor.build.nullValue() : _validityUint(r.validity.notAfter, "validityNotAfter"),
+    _encName(r.subject, true),
+    _encAlgorithm(r.subjectPublicKeyAlgorithm, PK_ALG_TO_INT, pkKey),
+    _encSpk(r),
+    _encExtensions(r.extensions),
+    cbor.build.byteString(r.signatureValue),
+  ]);
+  parse(arr);   // fail closed: a hand-built result must re-parse as a valid C509 (as the verbatim path checks), else parse throws a typed c509/* verdict
+  return arr;
+}
+
+/**
+ * @primitive  pki.schema.c509.encode
+ * @signature  pki.schema.c509.encode(input[, opts]) -> Buffer
+ * @since      0.3.4
+ * @status     experimental
+ * @spec       draft-ietf-cose-cbor-encoded-cert, RFC 8949, RFC 9090
+ * @related    pki.schema.c509.parse
+ *
+ * Encode a C509 certificate to its deterministic-CBOR bytes -- the producing-side inverse of
+ * `pki.schema.c509.parse`. `input` is either a DER X.509 v3 certificate (a Buffer or PEM string), which is
+ * forward-transformed to a **type-3** C509 (a compact CBOR re-encoding whose signature is copied from the
+ * source and re-expressed as a fixed-width r||s, so `parse(encode(der)).reconstructedDer` reproduces the
+ * original DER byte for byte and the original signature still verifies), or a `pki.schema.c509.parse`
+ * result object, which is re-emitted to its native deterministic-CBOR array. The emission is canonical
+ * deterministic CBOR (RFC 8949 sec. 4.2) -- shortest-form heads, definite lengths, sorted map keys, and the
+ * registry integer shorthand for every registered algorithm / attribute / extension. It is signing-free (a
+ * byte transform, like `pki.ct.encodeSctList`); a shape outside the covered set throws a typed `C509Error`.
+ *
+ * The fixed-width ECDSA r||s is sized by the ISSUER's signing curve, which a leaf certificate does not
+ * carry. It is resolved authoritatively (never a magnitude guess, and matching issuer/subject Names are not
+ * taken as proof of self-signing): from `opts.issuerCurve`, or from the RFC 5480 standard digest<->curve
+ * pairing the signature algorithm implies. A certificate signed with a non-standard digest/curve pairing
+ * (its r/s wider than the digest's standard curve) fails closed -- supply the issuer curve via
+ * `opts.issuerCurve`.
+ *
+ * @opts
+ *   - `issuerCurve` (string) -- the ISSUER's ECDSA signing curve "P-256" / "P-384" / "P-521" (or the OID
+ *     names prime256v1 / secp384r1 / secp521r1); authoritative, overrides the resolution above. Consulted
+ *     only for the DER -> type-3 path; ignored when re-emitting a parse result.
+ *
+ * @example
+ *   var cbor = pki.schema.c509.encode(signerCertDer);   // a DER cert -> a compact type-3 C509
+ *   pki.schema.c509.parse(cbor).certificateType;        // 3
+ */
+// A commonName string that is a MAC / EUI address ("HH-HH-HH-FF-FE-HH-HH-HH") -> the C509 tag-48 byte
+// value (draft-20 sec. 3.2.3): an FF-FE-in-the-middle EUI-64 collapses to its 6-byte EUI-48, else the
+// 8-byte EUI-64 verbatim. A non-MAC commonName returns null (encoded as text). The exact inverse of
+// _macToEui64String, so the reconstruction rebuilds the identical DER commonName string.
+function _euiFromCn(value) {
+  if (!/^[0-9A-F]{2}(-[0-9A-F]{2}){7}$/.test(value)) return null;
+  var bytes = Buffer.from(value.replace(/-/g, ""), "hex");
+  if (bytes[3] === 0xff && bytes[4] === 0xfe) return Buffer.concat([bytes.subarray(0, 3), bytes.subarray(5)]);
+  return bytes;
+}
+// A DER Name -> the C509 structured rdns, decoding each attribute's string type (PrintableString ->
+// printable, UTF8String -> utf8; the C509 int sign carries this). Single-attribute RDNs only (v1).
+function _c509NameFromDer(nameBytes) {
+  var node = asn1.decode(nameBytes);
+  var rdns = [];
+  (node.children || []).forEach(function (rdnSet) {
+    if (!rdnSet.children || rdnSet.children.length !== 1) throw _err("c509/non-invertible", "a C509 Name requires single-attribute RDNs");
+    var attr = rdnSet.children[0];
+    var attrName = oid.name(asn1.read.oid(attr.children[0]));
+    if (attrName == null || ATTR_TO_INT[attrName] === undefined) throw _err("c509/non-invertible", "attribute type " + attrName + " has no C509 registry integer");
+    var valNode = attr.children[1];
+    var value = asn1.read.string(valNode);
+    var eui = attrName === "commonName" ? _euiFromCn(value) : null;
+    if (eui) rdns.push({ type: attrName, value: value, eui64: eui });                            // tag-48 MAC commonName
+    else rdns.push({ type: attrName, value: value, printable: valNode.tagNumber === asn1.TAGS.PRINTABLE_STRING });
+  });
+  return { rdns: rdns };
+}
+// A keyUsage extnValue (a DER KeyUsage BIT STRING) -> the C509 integer whose bit i is the named bit i.
+function _keyUsageBitsFromDer(extnValue) {
+  var bs;
+  try {
+    bs = asn1.read.bitString(asn1.decode(extnValue));
+  } catch (_e) {
+    return null;   // a malformed keyUsage BIT STRING cannot take the int shortcut -> encode it as a raw extension
+  }
+  var total = bs.bytes.length * 8 - bs.unusedBits, value = 0;
+  for (var bit = 0; bit < total && bit < 31; bit++) { if (bs.bytes[bit >> 3] & (0x80 >> (bit & 7))) value |= (1 << bit); }
+  return value > 0 && value <= 0x1ff ? value : null;
+}
+var _NO_EXPIRY = Date.UTC(9999, 11, 31, 23, 59, 59);
+// The C509 (OID/node) curve names <-> the WebCrypto namedCurve the P1363 converter expects, and the
+// RFC 5480 standard digest<->curve pairing an ECDSA signature algorithm implies.
+var NODE_TO_WEBCRYPTO = { "prime256v1": "P-256", "secp384r1": "P-384", "secp521r1": "P-521" };
+var WEBCRYPTO_FIELD_BYTES = { "P-256": 32, "P-384": 48, "P-521": 66 };
+var SIG_ALG_TO_CURVE = { "ecdsaWithSHA256": "P-256", "ecdsaWithSHA384": "P-384", "ecdsaWithSHA512": "P-521" };
+// A DER INTEGER magnitude byte length: the content past any leading sign/pad octet.
+function _magBytes(intNode) {
+  var c = intNode.content, i = 0;
+  while (i < c.length - 1 && c[i] === 0x00) i++;
+  return c.length - i;
+}
+// The max r/s magnitude width of a DER ECDSA signature (validating its two-INTEGER shape).
+function _sigMagWidth(derSig) {
+  var n;
+  try { n = asn1.decode(derSig); } catch (e) { throw _err("c509/bad-signature", "the ECDSA issuer signature is not valid DER", e); }
+  if (n.tagNumber !== asn1.TAGS.SEQUENCE || n.tagClass !== "universal" || !n.children || n.children.length !== 2) throw _err("c509/bad-signature", "the ECDSA issuer signature must be a SEQUENCE of two INTEGERs");
+  for (var i = 0; i < 2; i++) {
+    var ch = n.children[i];
+    if (ch.tagNumber !== asn1.TAGS.INTEGER || ch.tagClass !== "universal" || ch.constructed) throw _err("c509/bad-signature", "the ECDSA issuer signature r and s must be universal INTEGERs");
+  }
+  return Math.max(_magBytes(n.children[0]), _magBytes(n.children[1]));
+}
+var CURVE_ORDER = ["P-256", "P-384", "P-521"];   // ascending field size
+// The smallest supported curve whose field holds a magnitude, or null if none does.
+function _minCurveForMag(mag) {
+  for (var i = 0; i < CURVE_ORDER.length; i++) { if (mag <= WEBCRYPTO_FIELD_BYTES[CURVE_ORDER[i]]) return CURVE_ORDER[i]; }
+  return null;
+}
+// The ISSUER signature's fixed-width r||s is sized by the ISSUER's signing curve. The DER ECDSA signature
+// does NOT carry the curve and the r/s magnitudes are only a lower bound (a P-384 signature with small r/s
+// is byte-indistinguishable from a P-256 one), so the curve is resolved from an AUTHORITATIVE source, never
+// a guess: (1) an explicit opts.issuerCurve, or (2) the RFC 5480 standard digest<->curve pairing the
+// signature algorithm implies -- and ONLY when that pairing is the smallest curve the magnitude admits.
+// Matching issuer/subject Names are NOT treated as proof of self-signing (a self-issued certificate may be
+// cross-signed by a different key on a different curve). A signature whose r/s exceed the digest's standard
+// curve (a larger key) OR whose magnitude also fits a SMALLER curve (a smaller key signing with a larger
+// digest) leaves the curve undetermined: it fails closed and directs the caller to opts.issuerCurve.
+function _resolveIssuerSigCurve(c, opts) {
+  var mag = _sigMagWidth(c.signatureValue.bytes), curve;
+  if (opts && opts.issuerCurve != null) {
+    curve = String(opts.issuerCurve);
+    if (NODE_TO_WEBCRYPTO[curve]) curve = NODE_TO_WEBCRYPTO[curve];
+    if (!WEBCRYPTO_FIELD_BYTES[curve]) throw _err("c509/bad-input", "opts.issuerCurve must be P-256 / P-384 / P-521 (or prime256v1 / secp384r1 / secp521r1); got " + opts.issuerCurve);
+  } else {
+    curve = SIG_ALG_TO_CURVE[c.signatureAlgorithm.name];
+    if (!curve) throw _err("c509/non-invertible", "cannot resolve the issuer signing curve for signature algorithm " + c.signatureAlgorithm.name);
+    var minCurve = _minCurveForMag(mag);
+    if (!minCurve) throw _err("c509/non-invertible", "the ECDSA signature r/s width " + mag + " exceeds every supported curve field");
+    if (WEBCRYPTO_FIELD_BYTES[curve] < mag) throw _err("c509/non-invertible", "the issuer signed with a non-standard digest/curve pairing (r/s width " + mag + " exceeds the " + curve + " field implied by " + c.signatureAlgorithm.name + "); pass opts.issuerCurve (P-256 / P-384 / P-521)");
+    if (WEBCRYPTO_FIELD_BYTES[curve] > WEBCRYPTO_FIELD_BYTES[minCurve]) throw _err("c509/non-invertible", "signature algorithm " + c.signatureAlgorithm.name + " does not uniquely determine the issuer curve (r/s width " + mag + " also fits " + minCurve + "); pass opts.issuerCurve (P-256 / P-384 / P-521)");
+  }
+  if (mag > WEBCRYPTO_FIELD_BYTES[curve]) throw _err("c509/non-invertible", "the ECDSA signature r/s width " + mag + " does not fit the resolved " + curve + " field");
+  return curve;
+}
+// Compress an uncompressed SEC1 EC point (0x04||X||Y) to the C509 marker form (draft-20 sec. 3.2.2): the
+// sign-of-Y marker 0xFE (Y even) / 0xFD (Y odd) followed by X. The inverse of webcrypto.decompressEcPoint,
+// so the type-3 reconstruction recovers the exact original point. A non-0x04 point is kept verbatim.
+function _compressEcPoint(point, coordLen) {
+  if (!point.length || point[0] !== 0x04) return point;
+  if (point.length !== 1 + 2 * coordLen) throw _err("c509/non-invertible", "uncompressed EC point length " + point.length + " does not match the curve field size");
+  var x = point.subarray(1, 1 + coordLen), y = point.subarray(1 + coordLen);
+  return Buffer.concat([Buffer.from([(y[y.length - 1] & 1) ? 0xfd : 0xfe]), x]);
+}
+// A DER X.509 v3 certificate -> the type-3 C509 structured result (the inverse of _reconstructDer). Only
+// the reconstruction's covered set is invertible; encode() self-verifies the byte-exact round trip.
+_derToType3 = function (input, opts) {
+  var c;
+  try { c = x509.parse(input); } catch (e) { throw _err("c509/bad-input", "the input is not a valid X.509 certificate", e); }
+  if (!/^ecdsa/i.test(c.signatureAlgorithm.name || "")) throw _err("c509/non-invertible", "type-3 C509 encoding covers only ECDSA-signed certificates; got " + (c.signatureAlgorithm.name || "an unregistered algorithm"));
+  if (c.subjectPublicKeyInfo.algorithm.name !== "ecPublicKey") throw _err("c509/non-invertible", "type-3 C509 encoding covers only EC (ecPublicKey) certificates in v1; got " + (c.subjectPublicKeyInfo.algorithm.name || "an unregistered algorithm"));
+  var curveOid = asn1.read.oid(asn1.decode(c.subjectPublicKeyInfo.algorithm.parameters));
+  var curve = oid.name(curveOid);
+  var coordLen = EC_FIELD_BYTES[curve];
+  if (!coordLen) throw _err("c509/non-invertible", "unsupported EC subject curve " + (curve || curveOid));
+  var sigCurve = _resolveIssuerSigCurve(c, opts);   // the ISSUER signing curve, resolved authoritatively (opts / digest pairing)
+  var spkiNode = asn1.decode(c.subjectPublicKeyInfo.bytes);
+  return {
+    certificateType: 3,
+    serialNumber: c.serialNumber,          // no serialNumberHex -> the encoder uses the minimal ~biguint magnitude
+    signatureAlgorithm: { name: c.signatureAlgorithm.name, oid: c.signatureAlgorithm.oid },
+    issuer: _c509NameFromDer(c.issuer.bytes),
+    validity: { notBefore: c.validity.notBefore, notAfter: c.validity.notAfter.getTime() === _NO_EXPIRY ? null : c.validity.notAfter },
+    subject: _c509NameFromDer(c.subject.bytes),
+    subjectPublicKeyAlgorithm: { name: "ecPublicKey", oid: c.subjectPublicKeyInfo.algorithm.oid, curve: curve },
+    subjectPublicKey: _compressEcPoint(asn1.read.bitString(spkiNode.children[1]).bytes, coordLen),   // 0x04||X||Y -> C509 compressed marker
+    rsaPublicKey: null,
+    extensions: (c.extensions || []).map(function (e) {
+      var ext = { name: e.name, oid: e.oid, critical: !!e.critical, value: e.value };
+      if (e.name === "keyUsage") { var bits = _keyUsageBitsFromDer(e.value); if (bits != null) ext.keyUsageBits = bits; }   // enable the int-shortcut
+      return ext;
+    }),
+    signatureValue: validator.sig.ecdsaDerToP1363(c.signatureValue.bytes, sigCurve, C509Error, "c509/bad-signature"),
+  };
+};
+
+function encode(input, opts) {
+  if (input && typeof input === "object" && !Buffer.isBuffer(input) && input.certificateType != null) {
+    return _encodeC509Array(input);   // a parse result -> re-emit its native array
+  }
+  if (!Buffer.isBuffer(input) && typeof input !== "string") throw _err("c509/bad-input", "encode input must be a DER/PEM X.509 certificate or a c509.parse result");
+  // Normalize input to DER through the SAME shared coercion x509.parse uses (a PEM string, a PEM-armored
+  // Buffer, or raw DER all collapse to the certificate DER), so the self-verify compares against exactly the
+  // bytes _derToType3 processed -- never a Buffer of PEM text.
+  var origDer = pkix.coerceToDer(input, { pemLabel: "CERTIFICATE", PemError: frameworkError.PemError, ErrorClass: C509Error, prefix: "c509" });
+  var encoded = _encodeC509Array(_derToType3(origDer, opts));
+  // The type-3 transform MUST invert back to the original DER byte-for-byte (so the original signature
+  // verifies) -- self-verify it, failing closed on any edge the reconstruction cannot reproduce.
+  var recon = parse(encoded).reconstructedDer;
+  if (!recon || Buffer.compare(recon, origDer) !== 0) throw _err("c509/non-invertible", "the type-3 C509 does not reconstruct the source certificate byte-for-byte");
+  return encoded;
+}
+
+module.exports = { parse: parse, matches: matches, encode: encode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
   "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:e238289a-30dc-45fc-b08a-4cc7a4f0a503",
+  "serialNumber": "urn:uuid:4cfd38cc-6772-42e6-bed2-46e04c2a950e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-17T09:21:09.414Z",
+    "timestamp": "2026-07-17T17:26:06.040Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.3.3",
+      "bom-ref": "@blamejs/pki@0.3.4",
       "type": "application",
       "name": "pki",
-      "version": "0.3.3",
+      "version": "0.3.4",
       "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.3.3",
+      "purl": "pkg:npm/%40blamejs/pki@0.3.4",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.3.3",
+      "ref": "@blamejs/pki@0.3.4",
       "dependsOn": []
     }
   ]