@blamejs/pki 0.1.22 → 0.1.23

package/lib/schema-csr.js

@@ -21,11 +21,11 @@
  *   A CSR is self-signed only in the sense that the requester proves possession of
  *   the private key; unlike a certificate or CRL there is no inner signature
  *   algorithm to agree with, the subject MAY be empty, and the attribute set has
- *   no uniqueness constraint — the parser deliberately omits those three
+ *   no uniqueness constraint -- the parser deliberately omits those three
  *   certificate/CRL guards.
  *
  * @card
- *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields — subject DN,
+ *   Parse DER / PEM PKCS#10 CSRs into structured, validated fields -- subject DN,
  *   public key, requested attributes, signature, fail-closed.
  */
 
@@ -45,23 +45,59 @@ var NS = pkix.makeNS("csr", CsrError, oid);
 var NAME = pkix.name(NS);
 var SPKI = pkix.spki(NS);
 
-// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 §4.1). A BARE
-// mandatory INTEGER whose ONLY legal value is 0 — the inverse of the cert/CRL
+// CertificationRequestInfo version ::= INTEGER { v1(0) } (RFC 2986 sec. 4.1). A BARE
+// mandatory INTEGER whose ONLY legal value is 0 -- the inverse of the cert/CRL
 // readers, which reject 0 as the DER-forbidden default. Surface v1 as 1. A
 // cert-shaped [0] EXPLICIT wrapper at this position makes asn1.read.integer throw
 // asn1/* (fail-closed).
 var CSR_VERSION = pkix.versionReader(NS, { "0": 1 });
 
-// Attribute ::= SEQUENCE { type OID, values SET OF ANY } — the shared pkix factory
+// Attribute ::= SEQUENCE { type OID, values SET OF ANY } -- the shared pkix factory
 // under the csr NS (values raw DER, SET SIZE(1..MAX), no uniqueness). The same
 // factory serves the PKCS#8 private-key attributes.
 var ATTRIBUTE = pkix.attribute(NS);
 
+// The two RECOGNIZED PKCS#9 request attributes get their value syntax enforced
+// (RFC 2985 sec. 5.4.1 challengePassword / sec. 5.4.2 extensionRequest): both
+// are SINGLE VALUE TRUE, extensionRequest carries one Extensions value
+// (RFC 5280 sec. 4.1, SIZE(1..MAX)) and challengePassword one DirectoryString
+// of 1..255 characters. A recognized type with a malformed, multi-valued, or
+// wrong-syntax value fails closed (csr/bad-attribute-value) -- a CA pipeline
+// reading requested extensions off csr.attributes must never receive garbage
+// under the extensionRequest OID. An UNRECOGNIZED attribute type stays opaque
+// raw DER and never fails the parse, and duplicate attribute TYPES stay legal
+// (RFC 2986 puts no uniqueness on the attributes SET). Registry rows keyed by
+// the stable dotted OID, not a switch; values are still surfaced raw.
+var EXTENSIONS = pkix.extensions(NS);
+var DIRECTORY_STRING_TAGS = [
+  asn1.TAGS.UTF8_STRING, asn1.TAGS.PRINTABLE_STRING, asn1.TAGS.TELETEX_STRING,
+  asn1.TAGS.UNIVERSAL_STRING, asn1.TAGS.BMP_STRING,
+];
+var RECOGNIZED_ATTRIBUTE_VALUE = {};
+RECOGNIZED_ATTRIBUTE_VALUE[oid.byName("extensionRequest")] = function (node, ctx) {
+  try { schema.walk(EXTENSIONS, node, ctx); }
+  catch (e) {
+    throw ctx.E("csr/bad-attribute-value",
+      "extensionRequest value must be a well-formed Extensions SEQUENCE (RFC 2985 sec. 5.4.2): " + ((e && e.message) || String(e)), e);
+  }
+};
+RECOGNIZED_ATTRIBUTE_VALUE[oid.byName("challengePassword")] = function (node, ctx) {
+  if (node.tagClass !== "universal" || DIRECTORY_STRING_TAGS.indexOf(node.tagNumber) === -1) {
+    throw ctx.E("csr/bad-attribute-value", "challengePassword must be a DirectoryString (RFC 2985 sec. 5.4.1)");
+  }
+  var s;
+  try { s = asn1.read.string(node); }
+  catch (e) { throw ctx.E("csr/bad-attribute-value", "challengePassword must be a well-formed DirectoryString (RFC 2985 sec. 5.4.1)", e); }
+  if (s.length < 1 || s.length > 255) {
+    throw ctx.E("csr/bad-attribute-value", "challengePassword must be 1..255 characters (RFC 2985 sec. 5.4.1)");
+  }
+};
+
 // CertificationRequestInfo ::= SEQUENCE { version, subject Name,
 //   subjectPKInfo SubjectPublicKeyInfo, attributes [0] IMPLICIT SET OF Attribute }.
 // attributes is a REQUIRED field (a CRI omitting [0] is a missing-required-field
 // fault, not silently accepted) modeled as an IMPLICIT [0] SET OF with min:0 (an
-// empty attributes SET is legal). subject MAY be empty — no non-empty-DN guard.
+// empty attributes SET is legal). subject MAY be empty -- no non-empty-DN guard.
 var CERTIFICATION_REQUEST_INFO = schema.seq([
   schema.field("version", CSR_VERSION),
   schema.field("subject", NAME),
@@ -69,21 +105,34 @@ var CERTIFICATION_REQUEST_INFO = schema.seq([
   schema.field("attributes", schema.implicitSetOf(0, ATTRIBUTE, { min: 0, code: "csr/bad-attributes", what: "attributes" })),
 ], {
   assert: "sequence", code: "csr/bad-cri", what: "certificationRequestInfo",
-  build: function (m) {
+  build: function (m, ctx) {
+    var attributes = m.fields.attributes.value.items.map(function (it) {
+      var a = it.value.result;
+      var checkValue = RECOGNIZED_ATTRIBUTE_VALUE[a.type];
+      if (checkValue) {
+        var valueItems = it.value.fields.values.value.items;
+        // Both recognized PKCS#9 types are SINGLE VALUE TRUE (RFC 2985 sec. 5.4).
+        if (valueItems.length !== 1) {
+          throw ctx.E("csr/bad-attribute-value", (a.name || a.type) + " is a SINGLE VALUE attribute (RFC 2985 sec. 5.4)");
+        }
+        checkValue(valueItems[0].node, ctx);
+      }
+      return a;
+    });
     return {
       version: m.fields.version.value,
-      subject: m.fields.subject.value.result, // Name is a seqOf → field.value is the match; .result is the {rdns, dn} build
+      subject: m.fields.subject.value.result, // Name is a seqOf -> field.value is the match; .result is the {rdns, dn} build
       subjectPublicKeyInfo: m.fields.subjectPKInfo.value.result,
-      attributes: m.fields.attributes.value.items.map(function (it) { return it.value.result; }),
+      attributes: attributes,
     };
   },
 });
 
 // CertificationRequest ::= SEQUENCE { certificationRequestInfo, signatureAlgorithm,
-//   signature BIT STRING } — the shared SIGNED envelope. DIVERGENCE from the
+//   signature BIT STRING } -- the shared SIGNED envelope. DIVERGENCE from the
 // cert/CRL builders: OMIT the outer-vs-inner signatureAlgorithm agreement check
 // (the CRI has no inner signature AlgorithmIdentifier) and the non-empty-subject
-// guard (a CSR subject MAY be empty). The omission is structural — this build
+// guard (a CSR subject MAY be empty). The omission is structural -- this build
 // simply never references the agreement bytes.
 var CERTIFICATION_REQUEST = pkix.signedEnvelope(NS, CERTIFICATION_REQUEST_INFO, {
   code: "csr/not-a-certification-request", what: "CertificationRequest",
@@ -120,8 +169,8 @@ var CERTIFICATION_REQUEST = pkix.signedEnvelope(NS, CERTIFICATION_REQUEST_INFO,
  *
  * @example
  *   var csr = pki.schema.csr.parse(der);
- *   csr.subject.dn;             // → "CN=req.example"
- *   csr.attributes[0].type;     // → "1.2.840.113549.1.9.14"
+ *   csr.subject.dn;             // -> "CN=req.example"
+ *   csr.attributes[0].type;     // -> "1.2.840.113549.1.9.14"
  */
 var parse = pkix.makeParser({ pemLabel: "CERTIFICATE REQUEST", PemError: PemError, ErrorClass: CsrError, prefix: "csr", what: "certification request", topSchema: CERTIFICATION_REQUEST, ns: NS });
 
@@ -158,7 +207,7 @@ function pemDecode(text, label) { return pkix.pemDecode(text, label || "CERTIFIC
 function pemEncode(der, label) { return pkix.pemEncode(der, label || "CERTIFICATE REQUEST", PemError); }
 
 // A CertificationRequest shares the outer SEQUENCE-of-3 shape with a certificate
-// and a CRL; a CSR is distinguished by its CertificationRequestInfo — a SEQUENCE
+// and a CRL; a CSR is distinguished by its CertificationRequestInfo -- a SEQUENCE
 // of EXACTLY four children {version INTEGER, subject SEQUENCE, subjectPKInfo
 // SEQUENCE, attributes [0]}. The mandatory trailing context-[0] attributes
 // element is what a cert (whose tbs leads with [0] EXPLICIT version or an INTEGER

package/lib/schema-engine.js

@@ -8,7 +8,7 @@
  * @order      60
  *
  * @intro
- *   L2 of the ASN.1 stack — a declarative structure-schema engine. A schema is
+ *   L2 of the ASN.1 stack -- a declarative structure-schema engine. A schema is
  *   plain data (`{kind, ...}` descriptors built by the combinators here) and
  *   `walk(schema, node, ctx)` interprets it against a decoded DER node. The
  *   engine is where every cross-cutting structural rule lives ONCE: the shape
@@ -21,7 +21,7 @@
  *   base the certificate parser (and, later, CRL / CMS) composes.
  *
  * @card
- *   Declarative ASN.1 structure schemas + one walk engine — the shared base the
+ *   Declarative ASN.1 structure schemas + one walk engine -- the shared base the
  *   certificate / CRL / CMS parsers compose instead of hand-writing.
  */
 
@@ -85,6 +85,9 @@ function _assertArity(schema, kids, ctx) {
   if (a.min != null && kids.length < a.min) {
     _fail(ctx, schema.code, (schema.what || "value") + " must have at least " + a.min + " elements");
   }
+  if (a.max != null && kids.length > a.max) {
+    _fail(ctx, schema.code, (schema.what || "value") + " must have at most " + a.max + " elements");
+  }
 }
 
 // ---- leaf / value combinators ---------------------------------------
@@ -102,23 +105,26 @@ function integerLeaf()    { return { kind: "leaf", read: asn1.read.integer, writ
 function boolean()        { return { kind: "leaf", read: asn1.read.boolean, write: function (v) { return asn1.build.boolean(v); } }; }
 function octetString()    { return { kind: "leaf", read: asn1.read.octetString, write: function (v) { return asn1.build.octetString(v); } }; }
 function bitString()      { return { kind: "leaf", read: function (n) { var b = asn1.read.bitString(n); return { unusedBits: b.unusedBits, bytes: b.bytes }; }, write: function (v) { return asn1.build.bitString(v.bytes, v.unusedBits); } }; }
-// A [tag] IMPLICIT BIT STRING leaf (context-class primitive) — the primitive-leaf
-// counterpart to implicitSetOf, for e.g. the PKCS#8 publicKey [1] (RFC 5958 §2).
+// A [tag] IMPLICIT BIT STRING leaf (context-class primitive) -- the primitive-leaf
+// counterpart to implicitSetOf, for e.g. the PKCS#8 publicKey [1] (RFC 5958 sec. 2).
 function implicitBitString(tag) { return { kind: "leaf", read: function (n) { var b = asn1.read.bitStringImplicit(n, tag); return { unusedBits: b.unusedBits, bytes: b.bytes }; }, write: function (v) { return asn1.build.contextPrimitive(tag, Buffer.concat([Buffer.from([v.unusedBits]), v.bytes])); } }; }
-// A [tag] IMPLICIT OCTET STRING leaf (context-class primitive) — the sibling of
+// A [tag] IMPLICIT OCTET STRING leaf (context-class primitive) -- the sibling of
 // implicitBitString, for e.g. the CMS SignerIdentifier subjectKeyIdentifier [0]
-// (RFC 5652 §5.3). Yields the raw content bytes.
+// (RFC 5652 sec. 5.3). Yields the raw content bytes.
 function implicitOctetString(tag) { return { kind: "leaf", read: function (n) { return asn1.read.octetStringImplicit(n, tag); }, write: function (v) { return asn1.build.contextPrimitive(tag, v); } }; }
-// A [tag] IMPLICIT NULL leaf (context-class primitive, empty content) — the sibling
+// A [tag] IMPLICIT NULL leaf (context-class primitive, empty content) -- the sibling
 // of implicitBitString/implicitOctetString, for e.g. the OCSP CertStatus good [0] /
-// unknown [2] arms (RFC 6960 §4.2.1). Yields null; rejects a constructed or
+// unknown [2] arms (RFC 6960 sec. 4.2.1). Yields null; rejects a constructed or
 // non-empty [tag] node fail-closed.
 function implicitNull(tag) { return { kind: "leaf", read: function (n) { return asn1.read.nullImplicit(n, tag); }, write: function () { return asn1.build.contextPrimitive(tag, Buffer.alloc(0)); } }; }
-// A [tag] IMPLICIT INTEGER leaf (context-class primitive) — the integer sibling of
+// A [tag] IMPLICIT INTEGER leaf (context-class primitive) -- the integer sibling of
 // implicitBitString, for the RFC 3161 Accuracy millis [0] / micros [1] fields
 // (context-tagged primitive INTEGERs). Yields a BigInt; a constructed or wrong-tag
 // node fails asn1/* at the codec.
 function implicitInteger(tag) { return { kind: "leaf", read: function (n) { return asn1.read.integerImplicit(n, tag); }, write: function (v) { return asn1.build.contextPrimitive(tag, _implicitIntContent(v)); } }; }
+// implicitBoolean, for the RFC 5280 sec. 5.2.5 IssuingDistributionPoint scope flags
+// (context-tagged primitive BOOLEANs). DER value rules enforced (0x00/0xFF only).
+function implicitBoolean(tag) { return { kind: "leaf", read: function (n) { return asn1.read.booleanImplicit(n, tag); }, write: function (v) { return asn1.build.contextPrimitive(tag, Buffer.from([v ? 0xff : 0x00])); } }; }
 function any()            { return { kind: "any" }; }
 // decode(fn, write?): a custom decode leaf; `write` is its optional paired encoder
 // (value -> DER TLV) so the same leaf drives both directions.
@@ -126,7 +132,7 @@ function decode(fn, write) { return { kind: "decode", fn: fn, write: write }; }
 
 // time(ns): a UTCTime / GeneralizedTime value, asserting the tag before the
 // codec reads it (mirrors _parseValidityTime's x509/bad-time guard). Encodes as
-// UTCTime for years 1950..2049 and GeneralizedTime otherwise (RFC 5280 §4.1.2.5).
+// UTCTime for years 1950..2049 and GeneralizedTime otherwise (RFC 5280 sec. 4.1.2.5).
 function time(ns) {
   return decode(function (n, ctx) {
     if (n.tagClass !== "universal" || (n.tagNumber !== TAGS.UTC_TIME && n.tagNumber !== TAGS.GENERALIZED_TIME)) {
@@ -146,14 +152,14 @@ function optional(name, schema, opts) {
   opts = opts || {};
   // How the optional field is recognized at its position:
   //   - default:       a context [tag] (the certificate version [0] shape).
-  //   - tags:          a context tag in the set — an OPTIONAL field whose type is
+  //   - tags:          a context tag in the set -- an OPTIONAL field whose type is
   //     itself a CHOICE of several context alternatives, e.g. the CRMF CertReqMsg
   //     popo ProofOfPossession ([0]..[3]) sitting before the universal-SEQUENCE
-  //     regInfo (RFC 4211 §3), where ANY of the CHOICE's tags marks it present.
-  //   - whenUniversal: the next element iff its UNIVERSAL tag is in the set —
+  //     regInfo (RFC 4211 sec. 3), where ANY of the CHOICE's tags marks it present.
+  //   - whenUniversal: the next element iff its UNIVERSAL tag is in the set --
   //     the CRL TBSCertList shape (bare INTEGER version, Time nextUpdate,
   //     SEQUENCE revokedCertificates), disambiguated by tag, not a context [n].
-  //   - whenAny:       the next element whatever its tag — an OPTIONAL ANY like
+  //   - whenAny:       the next element whatever its tag -- an OPTIONAL ANY like
   //     AlgorithmIdentifier.parameters.
   // The recognizer lets _walkSeq CONSUME the element so a closed sequence can
   // reject whatever is left over (without it, a trailing ANY looks unconsumed).
@@ -164,8 +170,14 @@ function optional(name, schema, opts) {
       : opts.tags
         ? function (n) { return isContextOneOf(n, opts.tags); }
         : function (n) { return isContext(n, opts.tag); };
+  // default/defaultCode: `default` binds the DEFAULT value when the field is
+  // absent. `defaultCode` opts the field into the X.690 sec. 11.5 walk-side reject
+  // (DER: a component equal to its DEFAULT shall not be included) -- a present
+  // value equal to `default` (strict equality; Buffers by bytes) fails with
+  // that code, so each format keeps its own reject-code family.
   return { fkind: "optional", name: name, schema: schema, tag: opts.tag, match: match,
-           explicit: !!opts.explicit, emptyCode: opts.emptyCode, hasDefault: ("default" in opts), def: opts.default };
+           explicit: !!opts.explicit, emptyCode: opts.emptyCode, hasDefault: ("default" in opts), def: opts.default,
+           defaultCode: opts.defaultCode };
 }
 // trailing: the [minTag..maxTag] optional context fields, each at most once in
 // strictly-increasing tag order (the tbs issuerUniqueID[1]/subjectUniqueID[2]/
@@ -212,16 +224,16 @@ function setOf(item, opts) {
 function setOfUnique(item, keyFn, opts) {
   return setOf(item, Object.assign({ unique: keyFn }, opts || {}));
 }
-// [tag] IMPLICIT SET OF item — the context tag REPLACES the universal SET tag,
+// [tag] IMPLICIT SET OF item -- the context tag REPLACES the universal SET tag,
 // so the node is a context-class constructed [tag] whose direct children are the
-// items (RFC 2986 §4.1 CSR attributes). No inner SET, no EXPLICIT unwrap.
+// items (RFC 2986 sec. 4.1 CSR attributes). No inner SET, no EXPLICIT unwrap.
 function implicitSetOf(tag, item, opts) {
   opts = opts || {};
   return { kind: "repeat", item: item, assert: "implicit", implicitTag: tag, derSetOrder: true, code: opts.code, what: opts.what,
            min: opts.min, max: opts.max, maxCode: opts.maxCode,
            unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
 }
-// [tag] IMPLICIT SEQUENCE OF item — the context tag REPLACES the universal SEQUENCE
+// [tag] IMPLICIT SEQUENCE OF item -- the context tag REPLACES the universal SEQUENCE
 // tag, so the node is a context-class constructed [tag] whose direct children are the
 // items. Order-preserving: the SEQUENCE-OF sibling of implicitSetOf WITHOUT the SET
 // ascending-DER-order rule (RFC 3161 extensions [1] IMPLICIT Extensions).
@@ -245,15 +257,17 @@ function implicitSeqOf(tag, item, opts) {
  * Interpret a declarative schema against a decoded DER node, enforcing the
  * schema's structural rules (shape assertion, arity, optional / context-tagged
  * fields in increasing tag order, SET-OF uniqueness) and returning the built
- * value — or the match tree (`{ node, fields | items }`, with the build output
+ * value -- or the match tree (`{ node, fields | items }`, with the build output
  * on `.result`) for a structure with no build fn. `ctx = { E, prefix, oid }`
  * supplies the typed-error constructor, the error-code family prefix, and the
  * OID registry a build fn resolves names through.
  *
- * The schema is assembled from the combinators this module exports — structural
+ * The schema is assembled from the combinators this module exports -- structural
  * (`seq` / `field` / `optional` / `explicit` / `trailing` / `seqOf` / `setOf` /
- * `setOfUnique` / `choice`) and value (`oidLeaf` / `integerLeaf` / `boolean` /
- * `octetString` / `bitString` / `any` / `decode` / `time`).
+ * `setOfUnique` / `implicitSeqOf` / `implicitSetOf` / `choice`) and value
+ * (`oidLeaf` / `integerLeaf` / `boolean` / `octetString` / `bitString` /
+ * `implicitBitString` / `implicitOctetString` / `implicitNull` /
+ * `implicitInteger` / `any` / `decode` / `time`).
  *
  * @example
  *   var S = pki.schema.engine;
@@ -314,7 +328,7 @@ function _walkRepeat(schema, node, ctx) {
   if (schema.max != null && kids.length > schema.max) {
     _fail(ctx, schema.maxCode || schema.code, (schema.what || "value") + " exceeds the element cap " + schema.max);
   }
-  // DER (X.690 §11.6) — the components of a SET OF appear in ascending order, the
+  // DER (X.690 sec. 11.6) -- the components of a SET OF appear in ascending order, the
   // encodings compared as octet strings. SEQUENCE OF is order-preserving and is
   // exempt (no derSetOrder). Compare full TLV byte strings, the same canonical
   // order build.set emits, so a decode round-trips a build. Equal-adjacent
@@ -323,7 +337,7 @@ function _walkRepeat(schema, node, ctx) {
   if (schema.derSetOrder) {
     for (var s = 1; s < kids.length; s++) {
       if (Buffer.compare(kids[s - 1].bytes, kids[s].bytes) > 0) {
-        _fail(ctx, schema.code, (schema.what || "value") + " components must be in ascending DER order (X.690 §11.6)");
+        _fail(ctx, schema.code, (schema.what || "value") + " components must be in ascending DER order (X.690 sec. 11.6)");
       }
     }
   }
@@ -345,6 +359,15 @@ function _walkRepeat(schema, node, ctx) {
   return match;
 }
 
+// The walked-value <-> DEFAULT comparison behind the defaultCode reject: strict
+// equality for the leaf value domains (BigInt, number, string, boolean), byte
+// equality for Buffers. A format opting in declares its `default` in the same
+// domain its leaf's read yields.
+function _equalsDefault(value, def) {
+  if (Buffer.isBuffer(value) && Buffer.isBuffer(def)) return value.equals(def);
+  return value === def;
+}
+
 function _walkSeq(schema, node, ctx) {
   var kids = _assertShape(schema, node, ctx);
   _assertArity(schema, kids, ctx);
@@ -365,18 +388,31 @@ function _walkSeq(schema, node, ctx) {
         if (fld.explicit) {
           inner = _explicitInner(next, fld.tag, ctx, fld.emptyCode || schema.code);
         }
-        fields[fld.name] = { node: next, present: true, value: walk(fld.schema, inner, ctx) };
+        var val = walk(fld.schema, inner, ctx);
+        // X.690 sec. 11.5 -- DER: a component equal to its DEFAULT value shall not
+        // be included in the encoding. Opt-in via defaultCode so the reject
+        // stays in the format's own error-code family.
+        if (fld.defaultCode != null && fld.hasDefault && _equalsDefault(val, fld.def)) {
+          _fail(ctx, fld.defaultCode, "field " + JSON.stringify(fld.name) + " explicitly encodes its DEFAULT value (X.690 sec. 11.5)");
+        }
+        fields[fld.name] = { node: next, present: true, value: val };
       } else {
         fields[fld.name] = { present: false, value: fld.hasDefault ? fld.def : undefined };
       }
     } else if (fld.fkind === "trailing") {
       _consumeTrailing(fld, kids, idx, fields, ctx);
       idx = kids.length;
+    } else {
+      // A malformed field descriptor is the same authoring fault as an
+      // unknown schema.kind (walk's default case): fail loud instead of
+      // silently skipping the descriptor -- a skipped field never binds and
+      // under-specifies the sequence.
+      _fail(ctx, (ctx.prefix || "schema") + "/bad-schema", "unknown field kind " + JSON.stringify(fld && fld.fkind));
     }
   }
 
   // Every child must be consumed by a field. A leftover element (no trailing
-  // field ran to absorb it) is malformed — dropping it silently would let a
+  // field ran to absorb it) is malformed -- dropping it silently would let a
   // closed sequence of optional fields accept a duplicate/extra element.
   if (idx < kids.length) {
     _fail(ctx, schema.code, (schema.what || "value") + " has an unexpected element after its last field");
@@ -393,7 +429,7 @@ function _consumeTrailing(fld, kids, start, fields, ctx) {
   for (var m = 0; m < fld.members.length; m++) byTag[fld.members[m].tag] = fld.members[m];
   // The monotonic-order sentinel must start below the lowest accepted tag.
   // Context tag numbers are non-negative, so -1 is below any member tag when
-  // minTag is absent — otherwise a trailing block whose first member is [0]
+  // minTag is absent -- otherwise a trailing block whose first member is [0]
   // would reject that field (0 <= last==0) as repeated/out-of-order.
   var last = fld.minTag != null ? fld.minTag - 1 : -1;
   for (var i = start; i < kids.length; i++) {
@@ -419,7 +455,7 @@ function _consumeTrailing(fld, kids, start, fields, ctx) {
 // encode(schema, value) is the constructor direction of the SAME schema walk
 // decodes: it interprets the schema against a plain structural value and emits
 // canonical DER. A single schema definition therefore drives both directions, so
-// context-tag (EXPLICIT/IMPLICIT) handling cannot diverge between them — the class
+// context-tag (EXPLICIT/IMPLICIT) handling cannot diverge between them -- the class
 // of bug where a decoder reads a [tag] IMPLICIT field but an ad-hoc encoder emits
 // the wrong tag is structurally retired. Encode errors are authoring faults (a bad
 // value / an un-encodable schema), thrown as plain Errors, not parse verdicts.
@@ -435,7 +471,7 @@ function _encFail(message) { throw new Error("schema.encode: " + message); }
  * @related    pki.schema.engine.walk
  *
  * Encode a structural value to canonical DER by interpreting the SAME schema
- * `walk` decodes — the constructor direction. `value` mirrors the schema: a `seq`
+ * `walk` decodes -- the constructor direction. `value` mirrors the schema: a `seq`
  * takes `{ fieldName: value }`, a leaf its natural JS value (an OID string, a
  * BigInt, a `{ unusedBits, bytes }` BIT STRING, a `Date`), a `repeat` an array, a
  * `choice` `{ arm, value }`. EXPLICIT wrappers and IMPLICIT `[tag]` retagging are
@@ -484,7 +520,13 @@ function _encodeSeq(schema, value, ctx) {
     } else if (fld.fkind === "optional") {
       if (_present(value[fld.name])) {
         var enc = encode(fld.schema, value[fld.name], ctx);
-        parts.push(fld.explicit ? asn1.build.explicit(fld.tag, enc) : enc);
+        // X.690 sec. 11.5 -- DER: a component equal to its DEFAULT value shall not
+        // be included in the encoding. Compare canonical field encodings, so
+        // encode never emits the non-canonical explicit-default form (which a
+        // walk-side defaultCode reject would refuse to round-trip).
+        var isDefault = fld.hasDefault && fld.def !== undefined &&
+          enc.equals(encode(fld.schema, fld.def, ctx));
+        if (!isDefault) parts.push(fld.explicit ? asn1.build.explicit(fld.tag, enc) : enc);
       }
     } else if (fld.fkind === "trailing") {
       // Emit present members in strictly-increasing tag order (the walk's rule).
@@ -496,6 +538,10 @@ function _encodeSeq(schema, value, ctx) {
           parts.push(mm.explicit ? asn1.build.explicit(mm.tag, menc) : menc);
         }
       }
+    } else {
+      // The mirror of _walkSeq's unknown-field-kind reject: a malformed
+      // descriptor is an authoring fault on the encode direction too.
+      _encFail("unknown field kind " + JSON.stringify(fld && fld.fkind));
     }
   }
   return _wrapConstructed(schema, parts);
@@ -506,7 +552,7 @@ function _encodeRepeat(schema, items, ctx) {
   // Enforce the SAME constraints walk enforces, so encode never emits DER its own
   // decoder rejects (the walk(decode(encode)) invariant): the SIZE minimum, and
   // semantic uniqueness (the key computed exactly as walk does, off the round-tripped
-  // item — a duplicate is an authoring fault, not a parse verdict).
+  // item -- a duplicate is an authoring fault, not a parse verdict).
   if (schema.min != null && items.length < schema.min) {
     _encFail("this repeat requires at least " + schema.min + " element(s) but got " + items.length);
   }
@@ -530,7 +576,10 @@ function _encodeRepeat(schema, items, ctx) {
 }
 
 function _encodeChoice(schema, value, ctx) {
-  if (!value || typeof value.arm !== "number" || value.arm < 0 || value.arm >= schema.alts.length) {
+  // Number.isInteger: a NaN / fractional arm passes a `< 0 || >= length` range
+  // check (both compares are false for NaN) into an undefined alts lookup --
+  // the same authoring fault as an out-of-range arm, failed the same way.
+  if (!value || !Number.isInteger(value.arm) || value.arm < 0 || value.arm >= schema.alts.length) {
     _encFail("a choice value must be { arm: <index>, value: <arm value> }");
   }
   return encode(schema.alts[value.arm].schema, value.value, ctx);
@@ -546,8 +595,8 @@ function _encodeChoice(schema, value, ctx) {
  * @related    pki.schema.engine.walk, pki.asn1.decode
  *
  * Decode a fresh DER (or, with `ber: true`, BER) blob carried inside an
- * already-decoded value — an OCTET STRING whose content is itself an encoded
- * structure — and walk it against a schema. A codec failure is wrapped in the
+ * already-decoded value -- an OCTET STRING whose content is itself an encoded
+ * structure -- and walk it against a schema. A codec failure is wrapped in the
  * caller's typed `code`; a schema rejection keeps its own code. This is the
  * one named form of the re-decode idiom, so the caps that a fresh
  * `pki.asn1.decode` would restart from zero can be carried across re-decode
@@ -558,7 +607,7 @@ function _encodeChoice(schema, value, ctx) {
  * @opts
  *   code:       string,   // typed code wrapping a codec failure (required)
  *   what:       string,   // human label for the wrapped message
- *   ber:        boolean,  // default false — BER content region (RFC 7292 §4.1)
+ *   ber:        boolean,  // default false -- BER content region (RFC 7292 sec. 4.1)
  *   budget:     object,   // { remaining: n } shared across a parse's re-decodes
  *   budgetCode: string,   // typed code when the budget is exhausted
  *
@@ -587,15 +636,15 @@ function embeddedDer(schema, bytes, ctx, opts) {
   return walk(schema, node, ctx);
 }
 
-// X.690 §11.2.2 — a NamedBitList BIT STRING (KeyUsage, PKIFailureInfo, and the
+// X.690 sec. 11.2.2 -- a NamedBitList BIT STRING (KeyUsage, PKIFailureInfo, and the
 // like) MUST drop every trailing zero bit under DER, giving one canonical
 // encoding per value: an empty value carries 0 unused bits; a non-empty value's
 // last content octet is non-zero AND its lowest USED bit (at position
 // `unusedBits`) is set. `fail(message)` throws the caller's typed domain error,
-// so the reject code stays per-format. Centralized so no format re-derives — and
-// silently diverges on — the minimal-encoding rule (a DER-canonicalization
+// so the reject code stays per-format. Centralized so no format re-derives -- and
+// silently diverges on -- the minimal-encoding rule (a DER-canonicalization
 // bypass class); see the named-bitlist-minimal-encoding-inlined gate.
-// ASN.1 node tag predicates — the per-node `tagClass`/`tagNumber` test every
+// ASN.1 node tag predicates -- the per-node `tagClass`/`tagNumber` test every
 // format's matches() detector (and the engine's own optional/choice walkers)
 // would otherwise re-inline. Centralized so a detector composes one predicate
 // instead of hand-rolling the comparison (and drifting); see the
@@ -618,12 +667,12 @@ function isContextInRange(node, min, max) {
 
 function assertMinimalNamedBits(unusedBits, bytes, fail) {
   if (bytes.length === 0) {
-    if (unusedBits !== 0) fail("an empty NamedBitList must encode with 0 unused bits (X.690 §11.2.2)");
+    if (unusedBits !== 0) fail("an empty NamedBitList must encode with 0 unused bits (X.690 sec. 11.2.2)");
     return;
   }
   var last = bytes[bytes.length - 1];
-  if (last === 0) fail("a NamedBitList must not carry a trailing all-zero octet (X.690 §11.2.2)");
-  if (((last >> unusedBits) & 1) !== 1) fail("a NamedBitList must drop all trailing zero bits (X.690 §11.2.2)");
+  if (last === 0) fail("a NamedBitList must not carry a trailing all-zero octet (X.690 sec. 11.2.2)");
+  if (((last >> unusedBits) & 1) !== 1) fail("a NamedBitList must drop all trailing zero bits (X.690 sec. 11.2.2)");
 }
 
 module.exports = {
@@ -633,7 +682,7 @@ module.exports = {
   // leaves
   oidLeaf: oidLeaf, integerLeaf: integerLeaf, boolean: boolean, octetString: octetString,
   bitString: bitString, implicitBitString: implicitBitString, implicitOctetString: implicitOctetString,
-  implicitNull: implicitNull, implicitInteger: implicitInteger,
+  implicitNull: implicitNull, implicitInteger: implicitInteger, implicitBoolean: implicitBoolean,
   any: any, decode: decode, time: time,
   // engine
   walk: walk, encode: encode, embeddedDer: embeddedDer, assertMinimalNamedBits: assertMinimalNamedBits,