@blamejs/pki 0.6.13 → 0.6.15

package/lib/schema-engine.js

@@ -30,22 +30,11 @@ var asn1 = require("./asn1-der.js");
 
 var TAGS = asn1.TAGS;
 
-// ---- context ---------------------------------------------------------
-// A walk receives ctx = { E, prefix, oid } where E(code, message) constructs
-// (does not throw) the format's typed error, prefix names the error family
-// ("x509", "crl", ...) and oid is the OID registry (for name resolution in a
-// build fn). _fail throws so a schema node reads as a single expression.
 
 function _fail(ctx, code, message) {
   throw ctx.E(code, message);
 }
 
-// ---- shape assertions ------------------------------------------------
-// A schema's `assert` mode is a real behavior-preservation control: some
-// hand-written guards checked the universal SEQUENCE tag (algorithmIdentifier,
-// Name), others checked only that the node had children (Validity, SPKI, the
-// tbs body, an AttributeTypeAndValue). Collapsing them to one "is a SEQUENCE"
-// check would silently change behavior on SET-wrapped input, so each is kept.
 
 function _assertShape(schema, node, ctx) {
   var mode = schema.assert || "sequence";
@@ -58,16 +47,10 @@ function _assertShape(schema, node, ctx) {
       _fail(ctx, schema.code, (schema.what || "value") + " must be a SET");
     }
   } else if (mode === "constructed") {
-    // Bare constructed: the historical guards only required decoded children,
-    // never a specific universal tag.
     if (!node.children) {
       _fail(ctx, schema.code, (schema.what || "value") + " must be a constructed value");
     }
   } else if (mode === "implicit") {
-    // IMPLICIT [tag] SET/SEQUENCE OF or a fixed-field IMPLICIT [tag] SEQUENCE body:
-    // the context tag replaces the universal tag, so the node is a context-class
-    // constructed [tag] and its direct children are the items / positional fields
-    // (no inner universal tag, no EXPLICIT unwrap).
     if (node.tagClass !== "context" || node.tagNumber !== schema.implicitTag || !node.children) {
       _fail(ctx, schema.code, (schema.what || "value") + " must be an IMPLICIT [" + schema.implicitTag + "] constructed value");
     }
@@ -91,49 +74,21 @@ function _assertArity(schema, kids, ctx) {
   }
 }
 
-// ---- leaf / value combinators ---------------------------------------
-// Leaves read a primitive off a node via the L1 codec; the codec's own
-// asn1/* errors propagate unchanged (the frozen oracle expects those codes on
-// the OID / INTEGER / string reads). `decode(fn)` hands the whole node to fn,
-// which owns its try/catch and code mapping. `any()` yields the node itself.
 
-// Leaves carry both directions: `read(node) -> value` and `write(value) -> DER TLV`,
-// so a single leaf definition drives decode (walk) and encode (build). A [tag]
-// IMPLICIT leaf's write emits the context-tagged TLV directly, mirroring its read.
 function _implicitIntContent(v) { return asn1.decode(asn1.build.integer(v)).content; }
 function oidLeaf()        { return { kind: "leaf", read: asn1.read.oid, write: function (v) { return asn1.build.oid(v); } }; }
 function integerLeaf()    { return { kind: "leaf", read: asn1.read.integer, write: function (v) { return asn1.build.integer(v); } }; }
 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 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
-// implicitBitString, for e.g. the CMS SignerIdentifier subjectKeyIdentifier [0]
-// (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
-// of implicitBitString/implicitOctetString, for e.g. the OCSP CertStatus good [0] /
-// 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
-// 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.
 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 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,24 +101,10 @@ function time(ns) {
   });
 }
 
-// ---- field descriptors (members of a seq) ---------------------------
 
 function field(name, schema)          { return { fkind: "required", name: name, schema: schema }; }
 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, for 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 sec. 3), where ANY of the CHOICE's tags marks it present.
-  //   - whenUniversal: the next element iff its universal tag is in the set, for
-  //     the CRL TBSCertList shape (bare INTEGER version, Time nextUpdate,
-  //     SEQUENCE revokedCertificates), disambiguated by tag and not a context [n].
-  //   - whenAny:       the next element whatever its tag, for 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).
   var match = opts.whenAny
     ? function () { return true; }
     : opts.whenUniversal
@@ -171,25 +112,16 @@ 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), so 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,
            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]/
-// extensions[3] block). members: [{ tag, name, schema, explicit? }].
 function trailing(members, opts) {
   opts = opts || {};
   return { fkind: "trailing", members: members, minTag: opts.minTag, maxTag: opts.maxTag,
            unexpectedCode: opts.unexpectedCode, orderCode: opts.orderCode };
 }
 
-// ---- structural combinators -----------------------------------------
 
 function seq(fields, opts) {
   opts = opts || {};
@@ -197,9 +129,6 @@ function seq(fields, opts) {
            code: opts.code, what: opts.what, build: opts.build, checks: opts.checks || [] };
 }
 
-// A NON-optional EXPLICIT context wrapper (CMS ContentInfo; the tbs [3] uses it
-// inside `trailing`). Asserts context class + tag, constructed, >=1 child, then
-// walks the inner schema on children[0].
 function explicit(tag, schema, opts) {
   opts = opts || {};
   return { kind: "explicit", tag: tag, schema: schema, emptyCode: opts.emptyCode, code: opts.code, what: opts.what };
@@ -225,19 +154,12 @@ 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,
-// so the node is a context-class constructed [tag] whose direct children are the
-// 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, 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).
 function implicitSeqOf(tag, item, opts) {
   opts = opts || {};
   return { kind: "repeat", item: item, assert: "implicit", implicitTag: tag, code: opts.code, what: opts.what,
@@ -245,7 +167,6 @@ function implicitSeqOf(tag, item, opts) {
            unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
 }
 
-// ---- the walk engine -------------------------------------------------
 
 /**
  * @primitive  pki.schema.engine.walk
@@ -293,9 +214,6 @@ function walk(schema, node, ctx) {
   return undefined;
 }
 
-// An EXPLICIT [tag] wrapper carries EXACTLY ONE inner value; 0 children is
-// empty and 2+ would silently drop all but the first (the same drop-extra
-// fail-open the seq guard closes). Assert exactly one, return it.
 function _explicitInner(node, tag, ctx, code) {
   if (!node.children || node.children.length !== 1) {
     _fail(ctx, code, "EXPLICIT [" + tag + "] must wrap exactly one value");
@@ -326,18 +244,9 @@ function _walkRepeat(schema, node, ctx) {
   if (schema.min != null && kids.length < schema.min) {
     _fail(ctx, schema.code, (schema.what || "value") + " must contain at least " + schema.min + " element(s)");
   }
-  // The element-count ceiling: a container of a great many tiny elements
-  // amplifies memory through per-element walk products, so a schema that
-  // parses attacker-sized lists declares `max` and fails typed instead.
   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 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
-  // encodings are permitted here (semantic uniqueness is the `unique` option's
-  // job); only a descending pair is non-canonical.
   if (schema.derSetOrder) {
     for (var s = 1; s < kids.length; s++) {
       if (Buffer.compare(kids[s - 1].bytes, kids[s].bytes) > 0) {
@@ -348,8 +257,6 @@ function _walkRepeat(schema, node, ctx) {
   var items = [];
   var seen = schema.unique ? new Set() : null;
   for (var i = 0; i < kids.length; i++) {
-    // The item wrapper is the SAME shape unique() and build() see: { node,
-    // value: <walk result> }. keyFn reads off item.value just like build does.
     var item = { node: kids[i], value: walk(schema.item, kids[i], ctx) };
     if (seen) {
       var key = schema.unique(item);
@@ -363,10 +270,6 @@ 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;
@@ -393,9 +296,6 @@ function _walkSeq(schema, node, ctx) {
           inner = _explicitInner(next, fld.tag, ctx, fld.emptyCode || schema.code);
         }
         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)");
         }
@@ -407,17 +307,10 @@ function _walkSeq(schema, node, ctx) {
       _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
-  // 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");
   }
@@ -431,10 +324,6 @@ function _walkSeq(schema, node, ctx) {
 function _consumeTrailing(fld, kids, start, fields, ctx) {
   var byTag = {};
   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]
-  // 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++) {
     var t = kids[i];
@@ -455,14 +344,6 @@ function _consumeTrailing(fld, kids, start, fields, ctx) {
   }
 }
 
-// ---- the encode engine (the inverse of walk) -------------------------
-// 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
-// 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.
 
 function _encFail(message) { throw new Error("schema.encode: " + message); }
 
@@ -505,8 +386,6 @@ function _wrapConstructed(schema, parts) {
   if (schema.implicitTag != null) return asn1.build.contextConstructed(schema.implicitTag, Buffer.concat(parts));
   var mode = schema.assert || "sequence";
   if (mode === "set") return asn1.build.set(parts);
-  // "constructed" is a DECODE-time leniency (accept any constructed shape); the
-  // canonical encoding is a universal SEQUENCE, same as "sequence".
   if (mode === "sequence" || mode === "constructed") return asn1.build.sequence(parts);
   _encFail("cannot encode a seq/repeat with assert " + JSON.stringify(mode));
   return undefined;
@@ -524,16 +403,11 @@ function _encodeSeq(schema, value, ctx) {
     } else if (fld.fkind === "optional") {
       if (_present(value[fld.name])) {
         var enc = encode(fld.schema, value[fld.name], ctx);
-        // 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).
       var members = fld.members.slice().sort(function (a, b) { return a.tag - b.tag; });
       for (var i = 0; i < members.length; i++) {
         var mm = members[i];
@@ -543,8 +417,6 @@ function _encodeSeq(schema, value, ctx) {
         }
       }
     } 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));
     }
   }
@@ -553,10 +425,6 @@ function _encodeSeq(schema, value, ctx) {
 
 function _encodeRepeat(schema, items, ctx) {
   if (!Array.isArray(items)) _encFail("a repeat value must be an array");
-  // 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).
   if (schema.min != null && items.length < schema.min) {
     _encFail("this repeat requires at least " + schema.min + " element(s) but got " + items.length);
   }
@@ -580,9 +448,6 @@ function _encodeRepeat(schema, items, ctx) {
 }
 
 function _encodeChoice(schema, value, ctx) {
-  // 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> }");
   }
@@ -641,19 +506,6 @@ function embeddedDer(schema, bytes, ctx, opts) {
   return walk(schema, node, ctx);
 }
 
-// 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
-// bypass class); see the named-bitlist-minimal-encoding-inlined gate.
-// 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
-// detector-reinlines-root-tag-guard gate.
 function isUniversal(node, tagNumber) {
   return !!node && node.tagClass === "universal" && node.tagNumber === tagNumber;
 }
@@ -681,17 +533,13 @@ function assertMinimalNamedBits(unusedBits, bytes, fail) {
 }
 
 module.exports = {
-  // structural
   seq: seq, field: field, optional: optional, explicit: explicit, trailing: trailing,
   seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, implicitSetOf: implicitSetOf, implicitSeqOf: implicitSeqOf, choice: choice,
-  // leaves
   oidLeaf: oidLeaf, integerLeaf: integerLeaf, boolean: boolean, octetString: octetString,
   bitString: bitString, implicitBitString: implicitBitString, implicitOctetString: implicitOctetString,
   implicitNull: implicitNull, implicitInteger: implicitInteger, implicitBoolean: implicitBoolean,
   any: any, decode: decode, time: time,
-  // engine
   walk: walk, encode: encode, embeddedDer: embeddedDer, assertMinimalNamedBits: assertMinimalNamedBits,
-  // node tag predicates
   isUniversal: isUniversal, isContext: isContext,
   isUniversalOneOf: isUniversalOneOf, isContextOneOf: isContextOneOf, isContextInRange: isContextInRange,
 };