@blamejs/pki 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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.1.13 — 2026-07-05
+
+An RFC 3161 timestamp parser joins the pki.schema family.
+
+### Added
+
+- pki.schema.tsp — an RFC 3161 timestamp parser. pki.schema.tsp.parse turns a DER Buffer or PEM into a TimeStampResp ({ status, statusString, failInfo, timeStampToken }) with the granted-carries-token / rejected-carries-none coupling enforced (tsp/missing-token, tsp/unexpected-token) and the PKIFailureInfo named bits decoded. pki.schema.tsp.parseToken parses a TimeStampToken by composing pki.schema.cms.parse and asserting the id-ct-TSTInfo content type (tsp/wrong-econtent-type), attached content (tsp/detached-token), and the single (TSA) signer (tsp/multi-signer), returning the decoded TSTInfo plus the signer material. pki.schema.tsp.parseTstInfo decodes a bare TSTInfo. The TSTInfo mandatory version-1, the GeneralizedTime-only genTime, the accuracy 1..999 range, the ordering DEFAULT FALSE omission, and the PKIStatus 0..5 range are all enforced fail-closed. pki.schema.parse detect-and-routes a TimeStampResp.
+- The codec and schema engine gain three composable primitives that TSP required: pki.asn1.read.integerImplicit / pki.schema.engine.implicitInteger(tag) (a context-tagged IMPLICIT INTEGER, for the Accuracy millis / micros fields); pki.schema.engine.implicitSeqOf(tag, item) (an order-preserving IMPLICIT SEQUENCE OF, the sibling of implicitSetOf without the SET ordering rule, for the extensions field); and RFC 3161 / X.690 §11.7 fractional-seconds GeneralizedTime support in pki.asn1.read.time (a '.'-separated, trailing-zero-free, Z-terminated fraction, surfaced at millisecond precision).
+- The OID registry gains the id-kp extended-key-purpose family (including id-kp-timeStamping) and the id-aa S/MIME authenticated-attribute family (signingCertificate / signingCertificateV2 / timeStampToken), so a parsed TSA certificate's key purpose and a signer's ESS binding attribute resolve by name.
+
+## v0.1.12 — 2026-07-05
+
+SLH-DSA object identifiers corrected and completed to all twelve FIPS 205 parameter sets.
+
+### Fixed
+
+- SLH-DSA OID resolution — id-slh-dsa-shake-128s and id-slh-dsa-shake-256s were mapped to the arcs of id-slh-dsa-sha2-256s (.24) and id-slh-dsa-shake-128f (.27), so pki.oid.name / pki.oid.byName resolved them incorrectly. All twelve Pure SLH-DSA parameter sets (sha2-128s/128f/192s/192f/256s/256f and shake-128s/128f/192s/192f/256s/256f) are now registered at their correct arcs .20 through .31 per RFC 9909 §3; the previously-absent nine sets now resolve as well. WebCrypto SLH-DSA sign/verify was unaffected — it selects by algorithm name, not through the OID registry.
+
 ## v0.1.11 — 2026-07-05
 
 An OCSP request and response parser joins the pki.schema family.

package/README.md

@@ -197,9 +197,10 @@ is callable today; nothing below is a stub.
 | `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` |
 | `pki.schema.cms` | Parse DER / PEM CMS SignedData per RFC 5652 — encapsulated content, signer infos, raw signed-attribute bytes for external verification, certificates / CRLs kept raw, fail-closed; non-SignedData content types recognized (not decoded) — `parse`, `pemDecode`, `pemEncode` |
 | `pki.schema.ocsp` | Parse DER / PEM OCSP requests and responses per RFC 6960 — per-certificate status (good / revoked / unknown), responder identity, raw tbs bytes for external verification, certificates kept raw, fail-closed; non-basic response types recognized (not decoded) — `parseRequest`, `parseResponse`, `pemDecode` |
+| `pki.schema.tsp` | Parse DER / PEM RFC 3161 timestamp responses and tokens — the TSTInfo payload (imprint, genTime with sub-second precision, serial, nonce, accuracy), the status-to-token coupling, and the token wrapper composed over CMS with the single-signer rule, fail-closed — `parse`, `parseTstInfo`, `parseToken`, `pemDecode` |
 | `pki.schema.engine` | The declarative ASN.1 structure-schema engine every format parser composes — `walk` plus the schema combinators |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
-| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError`, each carrying a stable `code` in `domain/reason` form |
+| `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -233,26 +234,31 @@ reintroduce the bug class it prevents. Adding a format is a schema declaration
 plus a documentation comment block, not new parse logic.
 
 ```
-  Detect + route     pki.schema.parse ── detects the format, routes to a sibling
-                              │
-  Format parsers     x509   crl   csr   pkcs8   cms   ocsp      (siblings)
-  (one schema each)    └──────┴─────┴──────┴──────┴─────┘
-                              │  every sibling COMPOSES ↓
-  Shared structure   pki.schema.engine        PKIX sub-schemas
-                     walk + combinators   ·   AlgorithmIdentifier · Name ·
-                     (positional reads,       Extension · version reader ·
-                      tag ordering, SET-OF     the one coerce → decode → walk
-                      uniqueness, arity,       parse-entry (PEM cap + DER
-                      fail-closed errors)      wrapping shared, never copied)
-                              │  built on ↓
-  Foundation         pki.asn1       pki.oid          pki.errors       pki.C
-                     DER codec  ·   OID registry  ·  PkiError     ·   constants
-                     (strict,       (two-way,        taxonomy         (LIMITS,
-                      bounded)       PQC-seeded)      (domain/reason)   scale)
-
-  Crypto             pki.webcrypto ──▶ node:crypto
-                     W3C SubtleCrypto over the platform: the classical set +
-                     post-quantum ML-DSA / SLH-DSA signatures + ML-KEM keygen
+┌─ Detect + route ────────────────────────────────────────────────────────┐
+│  pki.schema.parse — inspect the DER root, route to the matching sibling │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │
+ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐   Format
+ │ x509 │ │ crl  │ │ csr  │ │pkcs8 │ │ cms  │ │ ocsp │ │ tsp  │   parsers
+ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘   (siblings)
+                                     │  every sibling composes ↓
+┌─ Shared structure ──────────────────────────────────────────────────────┐
+│  pki.schema.engine — walk + combinators (positional reads, tag order,   │
+│  SET-OF uniqueness, arity, typed errors) · the PKIX sub-schemas —       │
+│  AlgorithmIdentifier · Name · Extension · a bounded version reader —    │
+│  and the one coerce → decode → walk parse-entry (PEM cap + DER wrap).   │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │  built on ↓
+┌─ Foundation ────────────────────────────────────────────────────────────┐
+│  pki.asn1 — strict, bounded DER codec · pki.oid — two-way, PQC-seeded   │
+│  OID registry · pki.errors — the PkiError domain/reason taxonomy ·      │
+│  pki.C — version-stable LIMITS + scale constants.                       │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─ Crypto ────────────────────────────────────────────────────────────────┐
+│  pki.webcrypto ──▶ node:crypto — a W3C SubtleCrypto engine: the         │
+│  classical set + post-quantum ML-DSA / SLH-DSA + ML-KEM key generation. │
+└─────────────────────────────────────────────────────────────────────────┘
 ```
 
 **Foundation.** The strict, bounded DER codec (`pki.asn1`), the two-way OID
@@ -266,7 +272,7 @@ bounded version reader, and the single coerce → decode → walk parse-entry th
 every format's `parse` is bound to. Because input coercion, the PEM size cap, and
 the DER-decode wrapping live here once, a format cannot diverge on a guard.
 
-**Format parsers.** `x509`, `crl`, `csr`, `pkcs8`, `cms`, and `ocsp` are siblings:
+**Format parsers.** `x509`, `crl`, `csr`, `pkcs8`, `cms`, `ocsp`, and `tsp` are siblings:
 each is a schema declaration composed from the shared pieces, emitting its own
 typed `domain/reason` error codes. `pki.schema.parse` inspects a decoded root and
 detect-and-routes to the matching sibling; the detectors are mutually exclusive by

package/lib/asn1-der.js

@@ -318,6 +318,18 @@ function readEnumerated(node) {
   return _readIntegerLikeContent(node, "ENUMERATED", "readEnumerated");
 }
 
+// Read a [tag] IMPLICIT INTEGER — a context-class PRIMITIVE node whose content is an
+// integer body (the IMPLICIT tag replaces the universal INTEGER tag). Same minimal
+// two's-complement content rules as a universal INTEGER. The integer counterpart of
+// readBitStringImplicit, for the RFC 3161 Accuracy millis [0] / micros [1] fields.
+function readIntegerImplicit(node, tag) {
+  if (node.tagClass !== "context" || node.tagNumber !== tag) {
+    throw new Asn1Error("asn1/unexpected-tag", "readIntegerImplicit: expected context tag [" + tag +
+      "], got " + node.tagClass + "/" + node.tagNumber);
+  }
+  return _readIntegerLikeContent(node, "INTEGER", "readIntegerImplicit");
+}
+
 // The BIT STRING content decoder (the leading unused-bit octet + body, with the
 // DER zero-pad rule). Shared by the universal reader and the IMPLICIT
 // context-tagged reader — the caller asserts the tag first.
@@ -533,8 +545,17 @@ function _decodeUtf32be(buf) {
 
 var UTC_RE = /^(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/;
 var GEN_RE = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/;
-
-function readTime(node) {
+// The X.690 §11.7 DER fractional-seconds GeneralizedTime profile: seconds present,
+// a `.` decimal separator (never `,`), a non-empty fraction, Z-terminated. The
+// trailing-zeros rule (§11.7.3) is enforced separately. Used by RFC 3161 genTime.
+var GEN_FRAC_RE = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d+)Z$/;
+
+// readTime(node, opts?) — opts.allowFractional enables the RFC 3161 / X.690 §11.7
+// fractional-seconds GeneralizedTime profile. Fractional is OFF by default because
+// most profiles (RFC 5280 certificate/CRL Validity, §4.1.2.5.2) require the integer-
+// second YYYYMMDDHHMMSSZ form and MUST NOT include a fraction; only callers that
+// permit sub-second precision (TSP genTime) pass allowFractional.
+function readTime(node, opts) {
   if (node.tagClass !== "universal") throw new Asn1Error("asn1/expected-time", "readTime: not a universal time type");
   _expectPrimitive(node, "readTime");
   var s = node.content.toString("latin1");
@@ -547,7 +568,19 @@ function readTime(node) {
     year += (year < 50) ? 2000 : 1900;
   } else if (node.tagNumber === TAGS.GENERALIZED_TIME) {
     m = GEN_RE.exec(s);
-    if (!m) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime must be YYYYMMDDHHMMSSZ, got " + JSON.stringify(s));
+    if (!m) {
+      if (!(opts && opts.allowFractional)) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime must be YYYYMMDDHHMMSSZ, got " + JSON.stringify(s));
+      m = GEN_FRAC_RE.exec(s);
+      if (!m) throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime must be YYYYMMDDHHMMSS[.fraction]Z, got " + JSON.stringify(s));
+      // X.690 §11.7.3 — the fractional part MUST NOT end in a zero (and is non-empty
+      // by the regex). ".5Z" is valid; ".50Z" and ".500Z" are non-canonical. X.690
+      // §11.7 places NO cap on the fraction length (RFC 3161 §2.4.2 gives the 5-digit
+      // example 19990609001326.34352Z), so a fraction of any length is accepted; the
+      // returned Date is millisecond-precision, and a caller needing the exact fraction
+      // reads it from node.content (the raw bytes, surfaced losslessly like the OID /
+      // serial paths).
+      if (m[7].charAt(m[7].length - 1) === "0") throw new Asn1Error("asn1/bad-generalizedtime", "GeneralizedTime fraction must not have trailing zeros, got " + JSON.stringify(s));
+    }
     year = parseInt(m[1], 10);
   } else {
     throw new Asn1Error("asn1/expected-time", "readTime: tag " + node.tagNumber + " is not a time type");
@@ -562,9 +595,12 @@ function readTime(node) {
   // GeneralizedTime year below 100 (0099 -> 1999). setUTCFullYear(year, ...)
   // takes the year literally and uses that year's own calendar, so years
   // below 100 and proleptic leap years are handled correctly.
+  // A fractional GeneralizedTime carries sub-second precision; surface it on the
+  // Date at millisecond resolution (the first three fraction digits, zero-padded).
+  var ms = (node.tagNumber === TAGS.GENERALIZED_TIME && m[7]) ? parseInt((m[7] + "000").slice(0, 3), 10) : 0;
   var d = new Date(0);
   d.setUTCFullYear(year, month - 1, day);
-  d.setUTCHours(hour, min, sec, 0);
+  d.setUTCHours(hour, min, sec, ms);
   if (isNaN(d.getTime())) throw new Asn1Error("asn1/bad-time", "unparseable time " + JSON.stringify(s));
   // Date/setUTC* silently roll over out-of-range fields (Feb 30 -> Mar 2,
   // month 13 -> next Jan, hour 25 -> +1 day). Reject unless every component
@@ -818,6 +854,7 @@ module.exports = {
   read: {
     boolean:      readBoolean,
     integer:      readInteger,
+    integerImplicit: readIntegerImplicit,
     enumerated:   readEnumerated,
     bitString:    readBitString,
     bitStringImplicit: readBitStringImplicit,

package/lib/framework-error.js

@@ -145,6 +145,10 @@ var CmsError = defineClass("CmsError", { withCause: true });
 // (OCSPRequest / OCSPResponse — RFC 6960 §4). Carries the leaf fault as `.cause`.
 var OcspError = defineClass("OcspError", { withCause: true });
 
+// TspError — a byte sequence that is not a well-formed RFC 3161 timestamp token,
+// TSTInfo, or TimeStampResp. Carries the underlying leaf fault as `.cause`.
+var TspError = defineClass("TspError", { withCause: true });
+
 module.exports = {
   PkiError:         PkiError,
   defineClass:      defineClass,
@@ -159,4 +163,5 @@ module.exports = {
   Pkcs8Error:       Pkcs8Error,
   CmsError:         CmsError,
   OcspError:        OcspError,
+  TspError:         TspError,
 };

package/lib/oid.js

@@ -79,6 +79,11 @@ var FAMILIES = {
     ocspBasic: 1, ocspNonce: 2, ocspCrl: 3, ocspResponse: 4, ocspNoCheck: 5,
     ocspArchiveCutoff: 6, ocspServiceLocator: 7, ocspPrefSigAlgs: 8, ocspExtendedRevoke: 9 } },
 
+  // PKIX extended key purposes (id-kp, RFC 5280 §4.2.1.12). timeStamping is required
+  // — critical and sole — on an RFC 3161 TSA signing certificate (§2.3).
+  pkixKp: { base: [1, 3, 6, 1, 5, 5, 7, 3], of: {
+    serverAuth: 1, clientAuth: 2, codeSigning: 3, emailProtection: 4, timeStamping: 8, ocspSigning: 9 } },
+
   // PKCS#1 RSA public-key + RSASSA signature algorithms.
   rsa: { base: [1, 2, 840, 113549, 1, 1], of: {
     rsaEncryption: 1, rsassaPss: 10, sha256WithRSAEncryption: 11,
@@ -98,6 +103,12 @@ var FAMILIES = {
   // S/MIME content types on the PKCS#9 smime arc (RFC 5652, RFC 3161): id-ct.
   smimeCt: { base: [1, 2, 840, 113549, 1, 9, 16, 1], of: { authData: 2, tSTInfo: 4 } },
 
+  // S/MIME authenticated attributes (id-aa, RFC 2634 / RFC 5035 / RFC 5816). The ESS
+  // signing-certificate attributes bind a CMS / TSP SignerInfo to its signing cert;
+  // signingCertificateV2 (ESSCertIDv2) carries a non-SHA-1 cert hash (RFC 5816 §2.2.1).
+  smimeAa: { base: [1, 2, 840, 113549, 1, 9, 16, 2], of: {
+    signingCertificate: 12, timeStampToken: 14, signingCertificateV2: 47 } },
+
   // ANSI X9.62 EC public key, named curve, and ECDSA signatures.
   ansiX962: { base: [1, 2, 840, 10045], of: {
     ecPublicKey: [2, 1], prime256v1: [3, 1, 7],
@@ -118,10 +129,17 @@ var FAMILIES = {
     sha256: 1, sha384: 2, sha512: 3, "sha3-256": 8, "sha3-512": 10, shake256: 12 } },
 
   // NIST signature algorithms — FIPS 204 ML-DSA + FIPS 205 SLH-DSA share the
-  // signature arc 2.16.840.1.101.3.4.3.
+  // signature arc 2.16.840.1.101.3.4.3. The 12 Pure SLH-DSA parameter sets are
+  // assigned sequentially (RFC 9909 §3): the SHA-2 sets .20-.25, then the SHAKE
+  // sets .26-.31.
   nistSig: { base: [2, 16, 840, 1, 101, 3, 4, 3], of: {
     "id-ml-dsa-44": 17, "id-ml-dsa-65": 18, "id-ml-dsa-87": 19,
-    "id-slh-dsa-sha2-128s": 20, "id-slh-dsa-shake-128s": 24, "id-slh-dsa-shake-256s": 27 } },
+    "id-slh-dsa-sha2-128s": 20, "id-slh-dsa-sha2-128f": 21,
+    "id-slh-dsa-sha2-192s": 22, "id-slh-dsa-sha2-192f": 23,
+    "id-slh-dsa-sha2-256s": 24, "id-slh-dsa-sha2-256f": 25,
+    "id-slh-dsa-shake-128s": 26, "id-slh-dsa-shake-128f": 27,
+    "id-slh-dsa-shake-192s": 28, "id-slh-dsa-shake-192f": 29,
+    "id-slh-dsa-shake-256s": 30, "id-slh-dsa-shake-256f": 31 } },
 
   // NIST KEM — FIPS 203 ML-KEM (arc 2.16.840.1.101.3.4.4).
   nistKem: { base: [2, 16, 840, 1, 101, 3, 4, 4], of: {

package/lib/schema-all.js

@@ -38,6 +38,7 @@ var csr = require("./schema-csr");
 var pkcs8 = require("./schema-pkcs8");
 var cms = require("./schema-cms");
 var ocsp = require("./schema-ocsp");
+var tsp = require("./schema-tsp");
 var frameworkError = require("./framework-error");
 
 var SchemaError = frameworkError.SchemaError;
@@ -66,12 +67,27 @@ var FORMATS = [
     detect: cms.matches,
     parse: function (input) { return cms.parse(input); },
   },
+  {
+    // TimeStampResp ::= SEQUENCE { status PKIStatusInfo, timeStampToken OPTIONAL } —
+    // a SEQUENCE of 1-2 whose first child is a PKIStatusInfo SEQUENCE whose own first
+    // child is an INTEGER status. This detector is a strict REFINEMENT of the
+    // ocsp-request one (both are SEQUENCE-of-1-2 with a SEQUENCE first child), so it
+    // MUST be checked first: a tokenless TimeStampResp (a bare PKIStatusInfo) would
+    // otherwise be shadowed by ocsp-request, whereas an OCSPRequest's tbsRequest never
+    // leads with a universal INTEGER and so never matches here (RFC 3161 §2.4.2). A
+    // bare timestamp token is a CMS ContentInfo and routes to cms; a bare TSTInfo is
+    // an internal payload (reached via pki.schema.tsp.parseTstInfo).
+    name: "tsp",
+    module: tsp,
+    detect: tsp.matches,
+    parse: function (input) { return tsp.parse(input); },
+  },
   {
     // OCSPRequest ::= SEQUENCE { tbsRequest SEQUENCE, optionalSignature [0] EXPLICIT
     // OPTIONAL } — a SEQUENCE of 1-2 whose first child is the tbsRequest SEQUENCE.
     // Leads with a SEQUENCE like the signed-envelope trio, but is excluded by arity
-    // (the trio is EXACTLY 3 children; an OCSPRequest is 1-2), so it detects
-    // unambiguously regardless of registry order (RFC 6960 §4.1.1).
+    // (the trio is EXACTLY 3 children; an OCSPRequest is 1-2). Checked AFTER tsp,
+    // whose detector is a strict refinement (RFC 6960 §4.1.1).
     name: "ocsp-request",
     module: ocsp,
     detect: ocsp.matchesRequest,
@@ -141,7 +157,7 @@ var FORMATS = [
  * The names of every registered format, in detection order.
  *
  * @example
- *   pki.schema.all();  // → ["cms", "ocsp-request", "ocsp-response", "pkcs8", "csr", "crl", "x509"]
+ *   pki.schema.all();  // → ["cms", "tsp", "ocsp-request", "ocsp-response", "pkcs8", "csr", "crl", "x509"]
  */
 function all() { return FORMATS.map(function (f) { return f.name; }); }
 
@@ -185,6 +201,7 @@ module.exports = {
   pkcs8: { parse: pkcs8.parse, parseEncrypted: pkcs8.parseEncrypted, pemDecode: pkcs8.pemDecode, pemEncode: pkcs8.pemEncode },
   cms:  { parse: cms.parse, pemDecode: cms.pemDecode, pemEncode: cms.pemEncode },
   ocsp: { parseRequest: ocsp.parseRequest, parseResponse: ocsp.parseResponse, pemDecode: ocsp.pemDecode },
+  tsp: { parse: tsp.parse, parseTstInfo: tsp.parseTstInfo, parseToken: tsp.parseToken, pemDecode: tsp.pemDecode },
   all: all,
   parse: parse,
 };

package/lib/schema-engine.js

@@ -109,6 +109,11 @@ function implicitOctetString(tag) { return { kind: "leaf", read: function (n) {
 // unknown [2] arms (RFC 6960 §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); } }; }
+// 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); } }; }
 function any()            { return { kind: "any" }; }
 function decode(fn)       { return { kind: "decode", fn: fn }; }
 
@@ -196,6 +201,15 @@ function implicitSetOf(tag, item, opts) {
   return { kind: "repeat", item: item, assert: "implicit", implicitTag: tag, derSetOrder: true, code: opts.code, what: opts.what,
            min: opts.min, 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,
+           min: opts.min, unique: opts.unique, dupCode: opts.dupCode, build: opts.build };
+}
 
 // ---- the walk engine -------------------------------------------------
 
@@ -377,11 +391,11 @@ function _consumeTrailing(fld, kids, start, fields, ctx) {
 module.exports = {
   // structural
   seq: seq, field: field, optional: optional, explicit: explicit, trailing: trailing,
-  seqOf: seqOf, setOf: setOf, setOfUnique: setOfUnique, implicitSetOf: implicitSetOf, choice: choice,
+  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,
+  implicitNull: implicitNull, implicitInteger: implicitInteger,
   any: any, decode: decode, time: time,
   // engine
   walk: walk,

package/lib/schema-ocsp.js

@@ -105,59 +105,10 @@ function certificateBytes() {
   });
 }
 
-// requestorName [1] EXPLICIT GeneralName — GeneralName ::= CHOICE (RFC 5280
-// §4.2.1.6). We keep the value RAW (no pkix.generalName factory yet), but validate
-// the chosen alternative's tag AND form/content so a malformed GeneralName fails
-// closed rather than passing the signed-request requestorName guard: the constructed
-// alternatives (otherName [0], x400Address [3], directoryName [4], ediPartyName [5])
-// must be constructed; rfc822Name [1] / dNSName [2] / uniformResourceIdentifier [6]
-// are primitive IA5String (7-bit); iPAddress [7] is a 4- or 16-octet OCTET STRING;
-// registeredID [8] is a primitive OBJECT IDENTIFIER.
-var GN_CONSTRUCTED = { 0: 1, 3: 1, 4: 1, 5: 1 };
-var GN_IA5 = { 1: 1, 2: 1, 6: 1 };
-function _validateGeneralName(n, ctx) {
-  if (n.tagClass !== "context" || n.tagNumber < 0 || n.tagNumber > 8) {
-    throw ctx.E("ocsp/bad-requestor-name", "requestorName must be a GeneralName (context tag [0]..[8]) (RFC 6960 §4.1.1)");
-  }
-  var t = n.tagNumber;
-  var constructed = !!n.children;
-  if (GN_CONSTRUCTED[t]) {
-    if (!constructed || n.children.length < 1) throw ctx.E("ocsp/bad-requestor-name", "GeneralName [" + t + "] must be a non-empty constructed value (RFC 5280 §4.2.1.6)");
-    if (t === 0) {
-      // otherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY } —
-      // both fields mandatory: exactly two children, a type-id OID and a [0] EXPLICIT
-      // value wrapper carrying exactly one inner value.
-      if (n.children.length !== 2) throw ctx.E("ocsp/bad-requestor-name", "GeneralName otherName [0] must be a SEQUENCE { type-id, value [0] } (RFC 5280 §4.2.1.6)");
-      try { asn1.read.oid(n.children[0]); }
-      catch (e) { throw ctx.E("ocsp/bad-requestor-name", "GeneralName otherName [0] must lead with a type-id OBJECT IDENTIFIER", e); }
-      var v = n.children[1];
-      if (!(v.tagClass === "context" && v.tagNumber === 0 && v.children && v.children.length === 1)) {
-        throw ctx.E("ocsp/bad-requestor-name", "GeneralName otherName [0] value must be a [0] EXPLICIT wrapper carrying exactly one value");
-      }
-    } else if (t === 4) {
-      // directoryName [4] EXPLICIT Name — validate the wrapped RDNSequence.
-      if (n.children.length !== 1) throw ctx.E("ocsp/bad-requestor-name", "GeneralName directoryName [4] must wrap exactly one Name (RFC 5280 §4.2.1.6)");
-      schema.walk(NAME, n.children[0], ctx);
-    }
-    // x400Address [3] / ediPartyName [5]: validated to non-empty constructed form
-    // (their full ORAddress / EDIPartyName bodies are above the requestorName altitude).
-  } else {
-    if (constructed) throw ctx.E("ocsp/bad-requestor-name", "GeneralName [" + t + "] must be primitive (RFC 5280 §4.2.1.6)");
-    if (GN_IA5[t]) {
-      if (n.content.length === 0) throw ctx.E("ocsp/bad-requestor-name", "GeneralName [" + t + "] must be a non-empty IA5String");
-      for (var i = 0; i < n.content.length; i++) {
-        if (n.content[i] > 0x7f) throw ctx.E("ocsp/bad-requestor-name", "GeneralName [" + t + "] must be an IA5String (7-bit)");
-      }
-    } else if (t === 7) {
-      if (n.content.length !== 4 && n.content.length !== 16) throw ctx.E("ocsp/bad-requestor-name", "GeneralName iPAddress [7] must be a 4- or 16-octet address");
-    } else if (t === 8) {
-      try { asn1.decodeOidContent(n.content); }
-      catch (e) { throw ctx.E("ocsp/bad-requestor-name", "GeneralName registeredID [8] must be a valid OBJECT IDENTIFIER", e); }
-    }
-  }
-  return { bytes: n.bytes, tagClass: n.tagClass, tagNumber: n.tagNumber };
-}
-var GENERAL_NAME_RAW = schema.decode(_validateGeneralName);
+// requestorName [1] EXPLICIT GeneralName (RFC 6960 §4.1.1) — validated + surfaced raw
+// via the shared pkix.generalName primitive (RFC 5280 §4.2.1.6), so a malformed
+// GeneralName fails closed and the OCSP + TSP parsers cannot drift on this grammar.
+var GENERAL_NAME_RAW = pkix.generalName(NS, { code: "ocsp/bad-requestor-name" });
 
 // An OCSP signature BIT STRING is a byte string handed to a cryptographic verifier,
 // so it MUST be octet-aligned (0 unused bits); a non-octet-aligned signature is

package/lib/schema-pkix.js

@@ -208,6 +208,62 @@ function name(ns) {
   });
 }
 
+// GeneralName ::= CHOICE (RFC 5280 §4.2.1.6). A validate-and-surface-raw leaf for a
+// caller that keeps the value RAW but needs it to be a well-formed GeneralName: it
+// checks the chosen alternative's tag, form (constructed vs primitive per X.690
+// §10.2), and content — otherName [0] is a SEQUENCE { type-id OID, value [0] EXPLICIT
+// }; x400Address [3] / ediPartyName [5] are non-empty constructed; directoryName [4]
+// EXPLICIT wraps a valid Name; rfc822Name [1] / dNSName [2] / uniformResourceIdentifier
+// [6] are primitive non-empty IA5String (7-bit); iPAddress [7] is a 4- or 16-octet
+// OCTET STRING; registeredID [8] is a primitive OBJECT IDENTIFIER — then surfaces the
+// value RAW ({ bytes, tagClass, tagNumber }). `opts.code` is the caller's error code
+// (e.g. ocsp/bad-requestor-name, tsp/bad-tsa). Shared so the two parsers cannot drift.
+var GN_CONSTRUCTED = { 0: 1, 3: 1, 4: 1, 5: 1 };
+var GN_IA5 = { 1: 1, 2: 1, 6: 1 };
+function generalName(ns, opts) {
+  opts = opts || {};
+  var code = opts.code || (ns.prefix + "/bad-general-name");
+  var NAME = name(ns);
+  return schema.decode(function (n, ctx) {
+    if (n.tagClass !== "context" || n.tagNumber < 0 || n.tagNumber > 8) {
+      throw ctx.E(code, "value must be a GeneralName (context tag [0]..[8]) (RFC 5280 §4.2.1.6)");
+    }
+    var t = n.tagNumber;
+    var constructed = !!n.children;
+    if (GN_CONSTRUCTED[t]) {
+      if (!constructed || n.children.length < 1) throw ctx.E(code, "GeneralName [" + t + "] must be a non-empty constructed value (RFC 5280 §4.2.1.6)");
+      if (t === 0) {
+        // otherName ::= SEQUENCE { type-id OBJECT IDENTIFIER, value [0] EXPLICIT ANY }.
+        if (n.children.length !== 2) throw ctx.E(code, "GeneralName otherName [0] must be a SEQUENCE { type-id, value [0] }");
+        try { asn1.read.oid(n.children[0]); }
+        catch (e) { throw ctx.E(code, "GeneralName otherName [0] must lead with a type-id OBJECT IDENTIFIER", e); }
+        var v = n.children[1];
+        if (!(v.tagClass === "context" && v.tagNumber === 0 && v.children && v.children.length === 1)) {
+          throw ctx.E(code, "GeneralName otherName [0] value must be a [0] EXPLICIT wrapper carrying exactly one value");
+        }
+      } else if (t === 4) {
+        // directoryName [4] EXPLICIT Name — validate the wrapped RDNSequence.
+        if (n.children.length !== 1) throw ctx.E(code, "GeneralName directoryName [4] must wrap exactly one Name");
+        schema.walk(NAME, n.children[0], ctx);
+      }
+    } else {
+      if (constructed) throw ctx.E(code, "GeneralName [" + t + "] must be primitive (X.690 §10.2)");
+      if (GN_IA5[t]) {
+        if (n.content.length === 0) throw ctx.E(code, "GeneralName [" + t + "] must be a non-empty IA5String");
+        for (var i = 0; i < n.content.length; i++) {
+          if (n.content[i] > 0x7f) throw ctx.E(code, "GeneralName [" + t + "] must be an IA5String (7-bit)");
+        }
+      } else if (t === 7) {
+        if (n.content.length !== 4 && n.content.length !== 16) throw ctx.E(code, "GeneralName iPAddress [7] must be a 4- or 16-octet address");
+      } else if (t === 8) {
+        try { asn1.decodeOidContent(n.content); }
+        catch (e) { throw ctx.E(code, "GeneralName registeredID [8] must be a valid OBJECT IDENTIFIER", e); }
+      }
+    }
+    return { bytes: n.bytes, tagClass: n.tagClass, tagNumber: n.tagNumber };
+  });
+}
+
 // Extension ::= SEQUENCE { extnID OID, critical BOOLEAN DEFAULT FALSE,
 // extnValue OCTET STRING }. `critical` is a universal BOOLEAN present-by-count
 // (not context-tagged), so the per-extension decode handles the 2-vs-3-child
@@ -362,6 +418,7 @@ module.exports = {
   attributeTypeAndValue: attributeTypeAndValue,
   relativeDistinguishedName: relativeDistinguishedName,
   name: name,
+  generalName: generalName,
   attribute: attribute,
   extension: extension,
   extensions: extensions,

package/lib/schema-tsp.js

@@ -0,0 +1,411 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @module     pki.schema.tsp
+ * @nav        Schema
+ * @title      TSP
+ * @order      170
+ * @slug       tsp
+ *
+ * @intro
+ *   RFC 3161 Time-Stamp Protocol handling. A `TimeStampResp` is what a client
+ *   receives from a TSA — a `PKIStatusInfo` plus, on success, a `TimeStampToken`;
+ *   `parse` decodes it and enforces the status-to-token coupling (a granted
+ *   response carries a token, a rejection does not). A `TimeStampToken` is itself a
+ *   CMS SignedData whose encapsulated content is a `TSTInfo`, so `parseToken`
+ *   composes the CMS parser, asserts the `id-ct-TSTInfo` content type and the
+ *   single-signer rule, and decodes the inner `TSTInfo`. `parseTstInfo` decodes a
+ *   bare `TSTInfo` payload directly.
+ *
+ *   The parser surfaces everything a verifier needs and interprets nothing it
+ *   cannot: `messageImprint.hashAlgorithm` and the raw `hashedMessage`, the
+ *   `genTime` (with sub-second precision), the `serialNumber` and `nonce` (lossless,
+ *   as BigInt + hex), and the `policy`. The imprint-to-request and nonce-to-request
+ *   round-trips, the ESS signing-certificate binding, the timestamping EKU, and the
+ *   signature are verification-layer concerns above parse altitude. DER-only,
+ *   fail-closed.
+ *
+ * @card
+ *   Parse DER / PEM RFC 3161 timestamp responses and tokens — per-response status,
+ *   the TSTInfo payload (imprint, genTime, serial, nonce, accuracy), raw verifier
+ *   inputs, single-signer token composition over CMS, fail-closed.
+ */
+
+var asn1 = require("./asn1-der");
+var schema = require("./schema-engine");
+var pkix = require("./schema-pkix");
+var oid = require("./oid");
+var cms = require("./schema-cms");
+var frameworkError = require("./framework-error");
+
+var TspError = frameworkError.TspError;
+var PemError = frameworkError.PemError;
+
+var NS = pkix.makeNS("tsp", TspError, oid);
+
+var ALGORITHM_IDENTIFIER = pkix.algorithmIdentifier(NS);
+var EXTENSION = pkix.extension(NS);
+
+// TSTInfo.version is INTEGER { v1(1) } — the only legal value is 1.
+var VERSION = pkix.versionReader(NS, { "1": 1 });
+
+// id-ct-TSTInfo is the eContentType that identifies a timestamp token (RFC 3161
+// §2.4.2); resolved from the registry, never a dotted literal.
+var OID_TST_INFO = oid.byName("tSTInfo");
+
+var TAGS = asn1.TAGS;
+
+// PKIFailureInfo ::= BIT STRING NamedBitList (RFC 3161 §2.4.2). bit 0 is the MSB of
+// the first content octet; a set bit outside the named set is surfaced by index.
+var FAILURE_BITS = {
+  0: "badAlg", 2: "badRequest", 5: "badDataFormat", 14: "timeNotAvailable",
+  15: "unacceptedPolicy", 16: "unacceptedExtension", 17: "addInfoNotAvailable", 25: "systemFailure",
+};
+
+// ---- shared leaves ---------------------------------------------------
+
+// GeneralizedTime-only leaf. RFC 3161 §2.4.2 requires genTime to be GeneralizedTime,
+// never UTCTime; assert the tag before the (fractional-capable) codec read.
+var GEN_TIME = schema.decode(function (n, ctx) {
+  if (n.tagClass !== "universal" || n.tagNumber !== TAGS.GENERALIZED_TIME) {
+    throw ctx.E("tsp/bad-gentime", "genTime must be a GeneralizedTime (RFC 3161 §2.4.2)");
+  }
+  // RFC 3161 genTime may carry sub-second precision (X.690 §11.7 fractional profile).
+  return asn1.read.time(n, { allowFractional: true });
+});
+
+// tsa [0] EXPLICIT GeneralName (RFC 3161 §2.4.2) — validated + surfaced raw via the
+// shared pkix.generalName primitive (RFC 5280 §4.2.1.6), which checks the chosen
+// alternative's form and content so a malformed GeneralName fails closed.
+var GENERAL_NAME_RAW = pkix.generalName(NS, { code: "tsp/bad-tsa" });
+
+// A PKIFreeText element MUST be a UTF8String (RFC 3161 §2.4.2).
+var UTF8_TEXT = schema.decode(function (n, ctx) {
+  if (n.tagClass !== "universal" || n.tagNumber !== TAGS.UTF8_STRING) {
+    throw ctx.E("tsp/bad-status-info", "PKIFreeText elements must be UTF8String");
+  }
+  return asn1.read.string(n);
+});
+
+// ---- MessageImprint --------------------------------------------------
+
+// MessageImprint ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, hashedMessage
+// OCTET STRING } (RFC 3161 §2.4.1). hashedMessage is a digest — surfaced RAW.
+var MESSAGE_IMPRINT = schema.seq([
+  schema.field("hashAlgorithm", ALGORITHM_IDENTIFIER),
+  schema.field("hashedMessage", schema.octetString()),
+], {
+  assert: "sequence", arity: { exact: 2 }, code: "tsp/bad-message-imprint", what: "MessageImprint",
+  build: function (m) {
+    return { hashAlgorithm: m.fields.hashAlgorithm.value.result, hashedMessage: m.fields.hashedMessage.value };
+  },
+});
+
+// ---- Accuracy --------------------------------------------------------
+
+// Accuracy ::= SEQUENCE { seconds INTEGER OPTIONAL, millis [0] IMPLICIT INTEGER
+// (1..999) OPTIONAL, micros [1] IMPLICIT INTEGER (1..999) OPTIONAL } (RFC 3161
+// §2.4.2). Every sub-field is optional; a missing one defaults to 0.
+var ACCURACY = schema.seq([
+  schema.optional("seconds", schema.integerLeaf(), { whenUniversal: [TAGS.INTEGER] }),
+  schema.trailing([
+    { tag: 0, name: "millis", schema: schema.implicitInteger(0) },
+    { tag: 1, name: "micros", schema: schema.implicitInteger(1) },
+  ], { minTag: 0, maxTag: 1, unexpectedCode: "tsp/bad-accuracy", orderCode: "tsp/bad-accuracy" }),
+], {
+  assert: "sequence", code: "tsp/bad-accuracy", what: "Accuracy",
+  build: function (m) {
+    function sub(f) {
+      if (!f.present) return 0;
+      var v = f.value;
+      // millis / micros are constrained to 1..999 (RFC 3161 §2.4.2); 0 is also
+      // excluded (and non-canonical for a positive count).
+      if (v < 1n || v > 999n) throw NS.E("tsp/bad-accuracy", "Accuracy millis/micros must be in 1..999");
+      return Number(v);
+    }
+    return {
+      // seconds is an unbounded INTEGER — keep it lossless as a BigInt (millis /
+      // micros are constrained to 1..999, so Number is exact for those).
+      seconds: m.fields.seconds.present ? m.fields.seconds.value : 0n,
+      millis: sub(m.fields.millis),
+      micros: sub(m.fields.micros),
+    };
+  },
+});
+
+// ---- TSTInfo ---------------------------------------------------------
+
+// TSTInfo ::= SEQUENCE { version, policy, messageImprint, serialNumber, genTime,
+// accuracy OPTIONAL, ordering DEFAULT FALSE, nonce OPTIONAL, tsa [0] EXPLICIT
+// GeneralName OPTIONAL, extensions [1] IMPLICIT Extensions OPTIONAL } (RFC 3161
+// §2.4.2). The five mandatory fields come first; the optionals are consumed by tag.
+var TST_INFO = schema.seq([
+  schema.field("version", VERSION),
+  schema.field("policy", schema.oidLeaf()),
+  schema.field("messageImprint", MESSAGE_IMPRINT),
+  schema.field("serialNumber", schema.integerLeaf()),
+  schema.field("genTime", GEN_TIME),
+  schema.optional("accuracy", ACCURACY, { whenUniversal: [TAGS.SEQUENCE] }),
+  schema.optional("ordering", schema.boolean(), { whenUniversal: [TAGS.BOOLEAN] }),
+  schema.optional("nonce", schema.integerLeaf(), { whenUniversal: [TAGS.INTEGER] }),
+  schema.trailing([
+    { tag: 0, name: "tsa", schema: GENERAL_NAME_RAW, explicit: true, emptyCode: "tsp/bad-tsa" },
+    { tag: 1, name: "extensions", schema: schema.implicitSeqOf(1, EXTENSION, { min: 1, unique: function (it) { return it.value.oid; }, dupCode: "tsp/duplicate-extension", code: "tsp/bad-extensions", what: "extensions" }) },
+  ], { minTag: 0, maxTag: 1, unexpectedCode: "tsp/bad-tst-info", orderCode: "tsp/bad-tst-info" }),
+], {
+  assert: "sequence", code: "tsp/bad-tst-info", what: "TSTInfo",
+  build: function (m, ctx) {
+    // ordering BOOLEAN DEFAULT FALSE — an explicit FALSE must be omitted (DER).
+    if (m.fields.ordering.present && m.fields.ordering.value === false) {
+      throw NS.E("tsp/bad-ordering", "ordering is BOOLEAN DEFAULT FALSE — an explicit FALSE must be omitted");
+    }
+    var policy = m.fields.policy.value;
+    var tsa = m.fields.tsa;
+    return {
+      version: m.fields.version.value,
+      policy: policy,
+      policyName: ctx.oid.name(policy) || null,
+      messageImprint: m.fields.messageImprint.value.result,
+      serialNumber: m.fields.serialNumber.value,
+      serialNumberHex: m.fields.serialNumber.node.content.toString("hex"),
+      genTime: m.fields.genTime.value,
+      // genTime is surfaced as a millisecond-precision Date; genTimeFraction is the
+      // exact fractional-seconds digits (lossless for sub-millisecond precision), or
+      // null when genTime carries no fraction.
+      genTimeFraction: (function () { var g = /\.(\d+)Z$/.exec(m.fields.genTime.node.content.toString("latin1")); return g ? g[1] : null; })(),
+      accuracy: m.fields.accuracy.present ? m.fields.accuracy.value.result : null,
+      ordering: m.fields.ordering.present ? m.fields.ordering.value : false,
+      nonce: m.fields.nonce.present ? m.fields.nonce.value : null,
+      nonceHex: m.fields.nonce.present ? m.fields.nonce.node.content.toString("hex") : null,
+      tsa: tsa.present ? tsa.value : null,
+      extensions: m.fields.extensions.present ? m.fields.extensions.value.items.map(function (it) { return it.value; }) : null,
+    };
+  },
+});
+
+// ---- PKIStatusInfo / TimeStampResp -----------------------------------
+
+// PKIStatusInfo ::= SEQUENCE { status PKIStatus (INTEGER), statusString PKIFreeText
+// OPTIONAL, failInfo PKIFailureInfo OPTIONAL } (RFC 3161 §2.4.2, from RFC 4210).
+var PKI_STATUS_INFO = schema.seq([
+  schema.field("status", schema.integerLeaf()),
+  schema.optional("statusString", schema.seqOf(UTF8_TEXT, { assert: "sequence", min: 1, code: "tsp/bad-status-info", what: "statusString" }), { whenUniversal: [TAGS.SEQUENCE] }),
+  schema.optional("failInfo", schema.bitString(), { whenUniversal: [TAGS.BIT_STRING] }),
+], {
+  assert: "sequence", code: "tsp/bad-status-info", what: "PKIStatusInfo",
+  build: function (m) {
+    var status = m.fields.status.value;
+    // PKIStatus ::= INTEGER { granted(0) .. revocationNotification(5) }.
+    if (status < 0n || status > 5n) throw NS.E("tsp/bad-status", "PKIStatus " + status + " is outside 0..5 (RFC 3161 §2.4.2)");
+    var failInfo = null;
+    if (m.fields.failInfo.present) {
+      var bs = m.fields.failInfo.value;
+      _assertMinimalNamedBits(bs.unusedBits, bs.bytes);
+      failInfo = { unusedBits: bs.unusedBits, bytes: bs.bytes, bits: _namedBits(bs.bytes) };
+    }
+    return {
+      status: Number(status),
+      statusString: m.fields.statusString.present ? m.fields.statusString.value.items.map(function (it) { return it.value; }) : null,
+      failInfo: failInfo,
+    };
+  },
+});
+
+// X.690 §11.2.2 — a BIT STRING typed with a NamedBitList (PKIFailureInfo) MUST have
+// all trailing 0 bits removed under DER: no trailing all-zero content octet, and the
+// declared unusedBits must sit exactly below the lowest set bit of the last octet (so
+// the encoding is minimal). The empty value encodes as 0 content octets, 0 unusedBits.
+function _assertMinimalNamedBits(unusedBits, bytes) {
+  if (bytes.length === 0) {
+    if (unusedBits !== 0) throw NS.E("tsp/bad-failinfo", "an empty PKIFailureInfo must encode with 0 unused bits (X.690 §11.2.2)");
+    return;
+  }
+  var last = bytes[bytes.length - 1];
+  if (last === 0) throw NS.E("tsp/bad-failinfo", "PKIFailureInfo NamedBitList must not have a trailing all-zero octet (X.690 §11.2.2)");
+  if (((last >> unusedBits) & 1) !== 1) throw NS.E("tsp/bad-failinfo", "PKIFailureInfo NamedBitList must have all trailing zero bits removed (X.690 §11.2.2)");
+}
+
+// Decode the set NamedBitList bits to their RFC 3161 names (bit 0 = MSB of byte 0).
+// A set bit outside the defined set is an unsupported PKIFailureInfo value — a client
+// MUST error on a failInfo it does not understand (RFC 3161 §2.4.2), so reject it
+// rather than surfacing an opaque "bitN".
+function _namedBits(bytes) {
+  var out = [];
+  for (var i = 0; i < bytes.length * 8; i++) {
+    if ((bytes[i >> 3] >> (7 - (i & 7))) & 1) {
+      var nm = FAILURE_BITS[i];
+      if (!nm) throw NS.E("tsp/bad-failinfo", "unsupported PKIFailureInfo bit " + i + " (RFC 3161 §2.4.2)");
+      out.push(nm);
+    }
+  }
+  return out;
+}
+
+// TimeStampResp ::= SEQUENCE { status PKIStatusInfo, timeStampToken TimeStampToken
+// OPTIONAL } (RFC 3161 §2.4.2). There is NO version field. The token is a CMS
+// ContentInfo, decoded via cms.parse; the status-to-token coupling is load-bearing.
+var TIME_STAMP_RESP = schema.seq([
+  schema.field("status", PKI_STATUS_INFO),
+  schema.optional("timeStampToken", schema.any(), { whenUniversal: [TAGS.SEQUENCE] }),
+], {
+  assert: "sequence", arity: { min: 1 }, code: "tsp/bad-response", what: "TimeStampResp",
+  build: function (m) {
+    var status = m.fields.status.value.result;
+    var present = m.fields.timeStampToken.present;
+    // RFC 3161 §2.4.2 — granted / grantedWithMods carry a token; any other status
+    // (rejection / waiting / revocation*) MUST NOT.
+    var granted = status.status === 0 || status.status === 1;
+    if (granted && !present) throw NS.E("tsp/missing-token", "a granted TimeStampResp must carry a timeStampToken (RFC 3161 §2.4.2)");
+    if (!granted && present) throw NS.E("tsp/unexpected-token", "a non-granted TimeStampResp must not carry a timeStampToken (RFC 3161 §2.4.2)");
+    // failInfo is the reason a request was rejected, so it is present ONLY when the
+    // status is rejection(2) — not on granted(0/1) nor on waiting / revocation* (3/4/5).
+    if (status.status !== 2 && status.failInfo) throw NS.E("tsp/unexpected-failinfo", "failInfo is present only when the status is rejection(2) (RFC 3161 §2.4.2)");
+    // A granted response's timeStampToken MUST be a well-formed TimeStampToken —
+    // decode it (composing the CMS parser) rather than surfacing arbitrary SEQUENCE
+    // bytes as a token; a malformed token fails the response parse.
+    return {
+      status: status.status,
+      statusString: status.statusString,
+      failInfo: status.failInfo,
+      timeStampToken: present ? parseToken(m.fields.timeStampToken.value.bytes) : null,
+    };
+  },
+});
+
+/**
+ * @primitive  pki.schema.tsp.parseTstInfo
+ * @signature  pki.schema.tsp.parseTstInfo(input) -> tstInfo
+ * @since      0.1.13
+ * @status     experimental
+ * @spec       RFC 3161
+ * @related    pki.schema.tsp.parseToken, pki.schema.tsp.parse
+ *
+ * Parse a bare `TSTInfo` payload (a DER `Buffer`) — the structure a timestamp token
+ * encapsulates — into `{ version, policy, messageImprint, serialNumber, genTime,
+ * accuracy, ordering, nonce, tsa, extensions }`. `messageImprint.hashedMessage` is
+ * the raw digest; `serialNumber` / `nonce` are lossless (BigInt + hex); `genTime` is
+ * a `Date` with sub-second precision. A malformed structure throws a typed
+ * `TspError` (`tsp/*`); a leaf-level codec fault surfaces as `asn1/*`.
+ *
+ * @example
+ *   var tst = pki.schema.tsp.parseTstInfo(der);
+ *   tst.genTime;                       // -> Date
+ *   tst.messageImprint.hashedMessage;  // -> Buffer (the raw digest)
+ */
+var parseTstInfo = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: TspError, prefix: "tsp", what: "TSTInfo", topSchema: TST_INFO, ns: NS });
+
+/**
+ * @primitive  pki.schema.tsp.parse
+ * @signature  pki.schema.tsp.parse(input) -> timeStampResp
+ * @since      0.1.13
+ * @status     experimental
+ * @spec       RFC 3161
+ * @related    pki.schema.tsp.parseToken, pki.schema.parse
+ *
+ * Parse a DER `Buffer` or a PEM string into a `TimeStampResp`: `{ status,
+ * statusString, failInfo, timeStampToken }`. The status-to-token coupling is
+ * enforced — a granted response (status 0/1) carries `timeStampToken` (surfaced raw
+ * for `parseToken`), any other status does not. `failInfo` decodes the
+ * `PKIFailureInfo` named bits. A malformed structure throws a typed `TspError`.
+ *
+ * @example
+ *   var res = pki.schema.tsp.parse(der);
+ *   res.status;                              // -> 0 (granted)
+ *   res.timeStampToken.tstInfo.genTime;      // -> Date (a granted token is decoded)
+ */
+var parse = pkix.makeParser({ pemLabel: null, PemError: PemError, ErrorClass: TspError, prefix: "tsp", what: "TimeStampResp", topSchema: TIME_STAMP_RESP, ns: NS });
+
+/**
+ * @primitive  pki.schema.tsp.parseToken
+ * @signature  pki.schema.tsp.parseToken(input) -> tstInfo
+ * @since      0.1.13
+ * @status     experimental
+ * @spec       RFC 3161, RFC 5652
+ * @related    pki.schema.tsp.parse, pki.schema.cms.parse
+ *
+ * Parse a `TimeStampToken` (a DER `Buffer` or PEM) — a CMS SignedData whose
+ * encapsulated content is a `TSTInfo`. Composes `pki.schema.cms.parse`, asserts the
+ * `id-ct-TSTInfo` content type (`tsp/wrong-econtent-type`), that the content is
+ * attached (`tsp/detached-token`), and the single-signer rule (`tsp/multi-signer`,
+ * RFC 3161 §2.4.2), then decodes the inner `TSTInfo`. Returns `{ tstInfo, eContent,
+ * signerInfo, certificates }` — the decoded payload, the raw eContent bytes a verifier
+ * hashes for the CMS message-digest, and the CMS signer material.
+ *
+ * @example
+ *   var token = pki.schema.tsp.parseToken(tokenDer);
+ *   token.tstInfo.genTime;   // -> Date
+ *   token.signerInfo.sid;    // -> the TSA signer identifier
+ */
+function parseToken(input) {
+  // De-armor with TSP's label-agnostic PEM rules first (RFC 3161 has no standard
+  // label), THEN hand DER to the CMS parser — otherwise cms.parse would reject any
+  // PEM block not labeled "CMS" before the TSP checks run.
+  var der = pkix.coerceToDer(input, { pemLabel: null, PemError: PemError, ErrorClass: TspError, prefix: "tsp" });
+  // Wrap the CMS decode so tsp.parse / parseToken keep their typed-TspError contract —
+  // a malformed token surfaces tsp/bad-token, not a bare cms/* error.
+  var signed;
+  try { signed = cms.parse(der); }
+  catch (e) {
+    if (e instanceof TspError) throw e;
+    throw new TspError("tsp/bad-token", "the timeStampToken did not decode as a CMS SignedData: " + ((e && e.message) || String(e)), e);
+  }
+  var encap = signed.encapContentInfo;
+  if (encap.eContentType !== OID_TST_INFO) {
+    throw new TspError("tsp/wrong-econtent-type", "a TimeStampToken must encapsulate id-ct-TSTInfo, got " + encap.eContentType);
+  }
+  if (encap.eContent === null) throw new TspError("tsp/detached-token", "a TimeStampToken must carry attached eContent (RFC 3161 §2.4.2)");
+  if (signed.signerInfos.length !== 1) {
+    throw new TspError("tsp/multi-signer", "a TimeStampToken must contain exactly one (TSA) signerInfo (RFC 3161 §2.4.2)");
+  }
+  var tstInfo;
+  try { tstInfo = schema.walk(TST_INFO, asn1.decode(encap.eContent), NS); }
+  catch (e) {
+    if (e instanceof TspError) throw e;
+    throw new TspError("tsp/bad-der", "the encapsulated TSTInfo did not decode: " + ((e && e.message) || String(e)), e);
+  }
+  // Surface the RAW eContent (the exact DER a verifier hashes for the CMS
+  // message-digest signed attribute) alongside the decoded TSTInfo — a re-serialized
+  // tstInfo may not byte-match, so the raw bytes are the verification feed.
+  return { tstInfo: tstInfo.result, eContent: encap.eContent, signerInfo: signed.signerInfos[0], certificates: signed.certificates };
+}
+
+/**
+ * @primitive  pki.schema.tsp.pemDecode
+ * @signature  pki.schema.tsp.pemDecode(text, label?) -> Buffer
+ * @since      0.1.13
+ * @status     experimental
+ * @spec       RFC 7468, RFC 3161
+ * @related    pki.schema.tsp.parse
+ *
+ * Extract the DER bytes from a PEM block (RFC 3161 defines no standard label, so the
+ * first block is taken unless `label` is given). Throws `PemError` on a missing
+ * envelope or a non-base64 body.
+ *
+ * @example
+ *   var der = pki.schema.tsp.pemDecode(pemText);
+ */
+function pemDecode(text, label) { return pkix.pemDecode(text, label || null, PemError); }
+
+// A TimeStampResp root is a SEQUENCE of 1-2 whose first child is a PKIStatusInfo (a
+// SEQUENCE whose own first child is an INTEGER status). Disjoint from the OID-first
+// CMS ContentInfo, the INTEGER-first PKCS#8 key, and the exactly-3 signed-envelope
+// trio, so it detects unambiguously regardless of registry order.
+function matches(root) {
+  if (!root || root.tagClass !== "universal" || root.tagNumber !== TAGS.SEQUENCE || !root.children) return false;
+  var k = root.children;
+  if (k.length < 1 || k.length > 2) return false;
+  var si = k[0];
+  if (!(si.tagClass === "universal" && si.tagNumber === TAGS.SEQUENCE && si.children && si.children.length >= 1)) return false;
+  if (!(si.children[0].tagClass === "universal" && si.children[0].tagNumber === TAGS.INTEGER)) return false;
+  if (k.length === 2 && !(k[1].tagClass === "universal" && k[1].tagNumber === TAGS.SEQUENCE)) return false;
+  return true;
+}
+
+module.exports = {
+  parse: parse,
+  parseTstInfo: parseTstInfo,
+  parseToken: parseToken,
+  pemDecode: pemDecode,
+  matches: matches,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/pki",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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:f4519864-8754-4475-8ee0-b2556afddae1",
+  "serialNumber": "urn:uuid:f3d799b0-bde8-4f05-8577-e064f7a420f1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-05T20:10:05.842Z",
+    "timestamp": "2026-07-06T00:04:32.672Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/pki@0.1.11",
+      "bom-ref": "@blamejs/pki@0.1.13",
       "type": "application",
       "name": "pki",
-      "version": "0.1.11",
+      "version": "0.1.13",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "Pure-JavaScript PKI toolkit that owns its stack — X.509, ASN.1/DER, CMS, PQC-first.",
-      "purl": "pkg:npm/%40blamejs/pki@0.1.11",
+      "purl": "pkg:npm/%40blamejs/pki@0.1.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/pki@0.1.11",
+      "ref": "@blamejs/pki@0.1.13",
       "dependsOn": []
     }
   ]