@blamejs/pki 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.2.5 — 2026-07-12
+
+WebAuthn / passkey attestation verification joins the toolkit as pki.webauthn.
+
+### Added
+
+- pki.webauthn.parseAttestationObject(bytes) structurally decodes a WebAuthn attestation object (the CBOR { fmt, attStmt, authData }) and its authenticatorData over the strict pki.cbor codec, returning the format id, the decoded rpIdHash / flags / signCount, the attested credential data (aaguid, credentialId, and the decoded COSE credentialPublicKey), and the raw authenticatorData bytes a signature covers. Malformed input throws webauthn/bad-attestation-object. W3C WebAuthn Level 3.
+- pki.webauthn.verify(attestationObject, clientDataHash, opts) verifies a WebAuthn attestation statement -- packed, tpm, android-key, apple, fido-u2f, or none -- checking the attestation signature over authenticatorData || clientDataHash and each format's structural bindings (the x5c leaf key, the apple nonce, the tpm certInfo Name / extraData over the pubArea, the android KeyDescription, the fido-u2f verificationData), binding each attestation certificate key to the credential public key, and enforcing each format's certificate requirements (a packed leaf's Authenticator Attestation subject and non-CA basic constraints, a tpm AIK's empty subject and non-CA constraints). It resolves the attestation type and trust path or throws a typed webauthn/* error; a signature that does not verify is a webauthn/verify-failed verdict, never a silent pass. The error taxonomy gains WebauthnError (webauthn/*). W3C WebAuthn Level 3, RFC 9052.
+- The OID registry gains the FIDO id-fido-gen-ce-aaguid, Android key-attestation, Apple anonymous-attestation, and TCG TPM (AIK key purpose, tpmManufacturer / tpmModel / tpmVersion) arcs that WebAuthn attestation certificates carry.
+
+### Changed
+
+- The bounded big-endian byte cursor under pki.ct's TLS-vector decoding is extracted to a shared engine primitive so the packed big-endian TPM structures in pki.webauthn read through the same bounds-before-slice cursor -- one definition of the length-checked read, carrying each caller's typed error domain.
+
+## v0.2.4 — 2026-07-12
+
+Human-readable certificate inspection joins the toolkit as pki.inspect.
+
+### Added
+
+- pki.inspect.certificate(input) renders a certificate (a PEM string, a DER Buffer, or a pki.schema.x509.parse result) as a human-readable OpenSSL-x509-text-style report, composed over the strict X.509 parser, the shared RFC 5280 extension decoders, and the two-way OID registry. Standard extensions (basic constraints, key usage, extended key usage with purpose names, subject/issuer alternative names, subject and authority key identifiers, and more) decode to their content; an extension with no decoder is named from the registry and shown as its string or a hex dump. A value that is not a certificate, DER, or PEM throws inspect/bad-input; malformed certificate bytes throw inspect/bad-certificate; a malformed single extension never sinks the report. The error taxonomy gains InspectError (inspect/*). RFC 5280.
+
 ## v0.2.3 — 2026-07-12
 
 Offline Sigstore bundle verification joins the toolkit as pki.sigstore.

package/README.md

@@ -227,8 +227,10 @@ is callable today; nothing below is a stub.
 | `pki.shbs` | Stateful hash-based signature **verification** — HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and CMS by RFC 9708, profiled by NIST SP 800-208 (CNSA 2.0 firmware signing). `verify` checks an HSS signature (every level must pass) and `verifyLms` a single-tree LMS, over the raw public-key / signature blobs the parsers already surface. Pure public-input SHA-256 / SHAKE256 hashing, a data-driven typecode registry, bounds-before-slice reads; a malformed blob throws a typed `ShbsError`, a well-formed-but-wrong signature returns `false`. **Verify only by design** — stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |
 | `pki.hpke` | Hybrid Public Key Encryption (RFC 9180) — the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS`/`setupR` establish a sender/recipient context (KEM encapsulation + HKDF key schedule); the context's `seal`/`open` AEAD-encrypt with a sequence-counter nonce and `export` derives further secrets; `seal`/`open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) × HKDF-SHA256/SHA512 × AES-GCM/ChaCha20Poly1305/export-only × all four modes, proven against the RFC 9180 Appendix A vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered but Appendix A ships no vector for them, so they fail closed until an authoritative KAT exists. Pure composition over `node:crypto`; ML-KEM / X-Wing are a registry data-row extension pending stable drafts — `suites`, `setupS`, `setupR`, `seal`, `open` |
 | `pki.sigstore` | Offline verifier for a Sigstore bundle — the exact artifact `npm publish --provenance` produces and the registry serves. `verifyBundle` composes five fail-closed legs against caller-pinned trust (Fulcio CA roots + Rekor log keys, never trusted from the bundle): the DSSE signature over its PAE preimage under the Fulcio leaf key; the ephemeral Fulcio certificate chain, validated as of the Rekor log time; the RFC 9162 inclusion proof folded to a Rekor-signed tree root; the log entry bound to this exact signature; and the in-toto SLSA subject digest the caller confirms against the published artifact. Zero runtime deps — reuses the X.509 parser, RFC 5280 path validator, and Merkle verifier; the net-new codecs are the DSSE PAE byte-builder and a fail-closed JSON reader. `pae`, `parseBundle`, `verifyBundle` |
+| `pki.inspect` | Human-readable certificate inspection — the pure-JS equivalent of `openssl x509 -text`. `certificate(pem | der | parsed)` renders a familiar OpenSSL-style report: version, serial, signature algorithm, issuer/subject distinguished names, validity, public-key details (curve or modulus size + the raw point/modulus), every decoded extension with its critical flag, and the signature. Built over the strict parser and the two-way OID registry, so it names extension and algorithm OIDs an OpenSSL build shows only as raw bytes. No OpenSSL dependency; the format is stable and OpenSSL-familiar rather than pinned to one OpenSSL version; a malformed extension falls back to a hex dump rather than throwing — `certificate` |
+| `pki.webauthn` | WebAuthn / passkey attestation verification — offline trust evaluation of a W3C WebAuthn (Level 3) attestation. `parseAttestationObject(bytes)` decodes the CBOR attestation object + authenticatorData + COSE credential key over the strict `pki.cbor` codec; `verify(attestationObject, clientDataHash, opts)` checks the attestation-statement signature and each format's structural bindings for **packed / tpm / android-key / apple / fido-u2f / none** — the x5c leaf key, the apple nonce, the tpm `certInfo` Name/`extraData` over the `pubArea`, the android `KeyDescription`, the fido-u2f `verificationData` — binding the credential public key to each attestation (via the signed authenticatorData for packed/fido-u2f, or a cert/`pubArea`-key equality check for android-key/apple/tpm) and enforcing each leaf's certificate requirements. A verifier, not a ceremony client; fail-closed with typed `webauthn/*` errors. Chaining the returned trust path to a pinned root (and aaguid→root via FIDO MDS) is the caller's step through `pki.path.validate` — `parseAttestationObject`, `verify` |
 | `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` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError`, 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` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError` / `WebauthnError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
 
 ### CLI
@@ -323,7 +325,8 @@ modules reached by explicit call rather than DER routing: `pki.path` (RFC 5280
 path validation), `pki.trust` (trust anchors), `pki.ct` (Certificate Transparency
 SCTs), `pki.hpke` (RFC 9180), `pki.shbs` (HSS/LMS stateful hash signatures),
 `pki.merkle` (RFC 9162 transparency proofs), `pki.sigstore` (offline npm-provenance
-verification), and the `jose` / `acme` / `est` enrollment surfaces. Each composes
+verification), `pki.webauthn` (WebAuthn / passkey attestation verification), and the
+`jose` / `acme` / `est` enrollment surfaces. Each composes
 the shared structure, foundation, and crypto layers directly. Alongside the schema
 engine, the fail-closed **guard family** (`guard-*`) centralizes each CVE-class
 defense — detached-buffer re-view, resource caps, constant-time compares,

package/index.js

@@ -44,6 +44,8 @@ var est        = require("./lib/est");
 var jose       = require("./lib/jose");
 var acme       = require("./lib/acme");
 var trust      = require("./lib/trust");
+var inspect    = require("./lib/inspect");
+var webauthn   = require("./lib/webauthn");
 
 module.exports = {
   version:   constants.version,
@@ -110,6 +112,19 @@ module.exports = {
   // root list omits); pki.trust.anchor hands one to pki.path.validate. Offline:
   // the operator supplies the text; no fetch.
   trust:     trust,
+  // `inspect` is human-readable inspection -- pki.inspect.certificate(pem|der|parsed)
+  // renders an OpenSSL-familiar `x509 -text`-style report from the strict parser +
+  // OID registry, naming extension/algorithm OIDs OpenSSL shows only as raw bytes.
+  // Pure, no OpenSSL dependency; best-effort (a bad extension falls back to hex).
+  inspect:   inspect,
+  // `webauthn` verifies a W3C WebAuthn / passkey attestation -- pki.webauthn.verify
+  // checks the attestation-statement signature + each format's structural bindings
+  // (packed / tpm / android-key / apple / fido-u2f / none) and surfaces the x5c chain
+  // for the caller to anchor to a pinned root via pki.path.validate; it does not
+  // itself chain to a trust anchor. parseAttestationObject structurally decodes the
+  // attestation object + authenticatorData + COSE key over the strict pki.cbor codec.
+  // A verifier, not a ceremony client; fail-closed.
+  webauthn:  webauthn,
   // A ready W3C Crypto instance (globalThis.crypto shape) with the classes for
   // constructing more attached under the same namespace (pki.webcrypto.CryptoKey,
   // .SubtleCrypto, .Crypto, .WebCryptoError). PQC-first, classical-capable, zero-dep.

package/lib/byte-reader.js

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) blamejs contributors
+"use strict";
+/**
+ * @internal
+ * lib/byte-reader.js -- a bounded big-endian byte cursor: the shared ENCODING-layer
+ * primitive under the toolkit's non-ASN.1 length-prefixed wire formats (TLS-vector
+ * SCTs in pki.ct, the packed big-endian TPM2B_* / authenticatorData structures in
+ * pki.webauthn). Every read is length-checked against a hard [pos, end) window
+ * BEFORE a byte is taken, so a lying inner length can overrun only the current
+ * sub-reader's `end`, never the parent buffer -- bounds-before-slice is structural,
+ * not a per-call discipline. It carries the CALLER's typed ErrorClass so every wire
+ * format keeps its own `domain/reason` fault code, exactly as the guard family does.
+ *
+ * This is an engine primitive, not a format: a new fixed-width or length-prefixed
+ * wire field is a method here (with its own bounds check), never a hand-rolled
+ * offset walk in a format module.
+ */
+
+// A bounded cursor over `buf[start, end)`, faulting through the caller's ErrorClass
+// `E` (constructed `new E(code, message)`). `defaultCode` is the fault code used
+// when a read is not given its own.
+function ByteReader(buf, start, end, E, defaultCode) {
+  if (!Buffer.isBuffer(buf)) throw new TypeError("ByteReader: buf must be a Buffer");
+  this.buf = buf;
+  this.pos = start | 0;
+  this.end = end == null ? buf.length : (end | 0);
+  this.E = E;
+  this.defaultCode = defaultCode || "byte-reader/truncated";
+}
+ByteReader.prototype._need = function (n, code) {
+  if (this.pos + n > this.end) {
+    throw new this.E(code || this.defaultCode, "need " + n + " byte(s), only " + (this.end - this.pos) + " remain");
+  }
+};
+ByteReader.prototype.u8 = function (code) { this._need(1, code); return this.buf[this.pos++]; };
+ByteReader.prototype.u16 = function (code) { this._need(2, code); var v = this.buf.readUInt16BE(this.pos); this.pos += 2; return v; };
+ByteReader.prototype.u24 = function (code) {
+  this._need(3, code);
+  var v = (this.buf[this.pos] << 16) | (this.buf[this.pos + 1] << 8) | this.buf[this.pos + 2];
+  this.pos += 3; return v >>> 0;
+};
+ByteReader.prototype.u32 = function (code) { this._need(4, code); var v = this.buf.readUInt32BE(this.pos); this.pos += 4; return v; };
+ByteReader.prototype.u64 = function (code) { this._need(8, code); var v = this.buf.readBigUInt64BE(this.pos); this.pos += 8; return v; };
+// A fixed-width opaque slice (zero-copy view into the backing buffer).
+ByteReader.prototype.fixed = function (n, code) {
+  this._need(n, code);
+  var s = this.buf.subarray(this.pos, this.pos + n); this.pos += n; return s;
+};
+// opaque<min..max> -- a length-prefixed vector (lenWidth-byte big-endian prefix:
+// 2 or 3). The length prefix itself is a plain read (a truncation there is the
+// default code); only a LYING length whose body overruns the bound carries `code`.
+ByteReader.prototype.vector = function (lenWidth, min, max, code) {
+  var len = lenWidth === 3 ? this.u24() : this.u16();
+  if (len < min) throw new this.E(code, "vector length " + len + " below minimum " + min);
+  if (max != null && len > max) throw new this.E(code, "vector length " + len + " above maximum " + max);
+  this._need(len, code);
+  var s = this.buf.subarray(this.pos, this.pos + len); this.pos += len; return s;
+};
+// A bounded child cursor over the next `len` bytes, sharing the same ErrorClass.
+ByteReader.prototype.subReader = function (len, code) {
+  this._need(len, code);
+  var r = new ByteReader(this.buf, this.pos, this.pos + len, this.E, this.defaultCode); this.pos += len; return r;
+};
+ByteReader.prototype.remaining = function () { return this.end - this.pos; };
+ByteReader.prototype.atEnd = function () { return this.pos === this.end; };
+
+module.exports = ByteReader;

package/lib/constants.js

@@ -257,6 +257,101 @@ var LIMITS = {
   TRUST_MAX_CSV_FIELD_BYTES: BYTES.kib(64),
 };
 
+// NAMES -- display-naming conventions shared by the human-readable renderers
+// (pki.inspect today; a future lint / CLI report tomorrow). Centralized so every
+// consumer speaks ONE convention -- the OpenSSL-familiar labels an operator expects
+// -- rather than each renderer copying a table that silently drifts. These are
+// DISPLAY strings, not wire identifiers (those resolve through pki.oid): a value here
+// never affects parse or verify, only how a decoded field is titled in a report.
+var NAMES = {
+  // ==== Distinguished-name attribute short names (RFC 4514 sec. 3 + RFC 4519 / CABF) ==
+  // The single source of truth: this table was previously copied in both
+  // lib/inspect.js and lib/schema-pkix.js and had already drifted (STREET vs street,
+  // SERIALNUMBER vs serialNumber). An entry whose type the OID registry does not yet
+  // resolve is simply never hit -- forward entries (jurisdiction*, organizationIdentifier)
+  // are harmless until their arc is registered.
+  DN_SHORT: {
+    commonName: "CN", surname: "SN", serialNumber: "SERIALNUMBER", countryName: "C",
+    localityName: "L", stateOrProvinceName: "ST", streetAddress: "STREET",
+    organizationName: "O", organizationalUnitName: "OU", title: "title", givenName: "GN",
+    initials: "initials", generationQualifier: "generationQualifier", distinguishedNameQualifier: "dnQualifier",
+    pseudonym: "pseudonym", domainComponent: "DC", userId: "UID", emailAddress: "emailAddress",
+    businessCategory: "businessCategory", postalCode: "postalCode", name: "name",
+    jurisdictionCountryName: "jurisdictionC", jurisdictionStateOrProvinceName: "jurisdictionST",
+    jurisdictionLocalityName: "jurisdictionL", organizationIdentifier: "organizationIdentifier",
+  },
+  // ==== X.509v3 extension section titles (OpenSSL-familiar); an extension absent
+  // here is titled from the OID registry name / dotted OID ====
+  EXTENSION: {
+    basicConstraints: "X509v3 Basic Constraints", keyUsage: "X509v3 Key Usage",
+    extKeyUsage: "X509v3 Extended Key Usage", subjectAltName: "X509v3 Subject Alternative Name",
+    issuerAltName: "X509v3 Issuer Alternative Name", subjectKeyIdentifier: "X509v3 Subject Key Identifier",
+    authorityKeyIdentifier: "X509v3 Authority Key Identifier", certificatePolicies: "X509v3 Certificate Policies",
+    policyMappings: "X509v3 Policy Mappings", policyConstraints: "X509v3 Policy Constraints",
+    inhibitAnyPolicy: "X509v3 Inhibit Any Policy", nameConstraints: "X509v3 Name Constraints",
+    cRLDistributionPoints: "X509v3 CRL Distribution Points", freshestCRL: "X509v3 Freshest CRL",
+    subjectInfoAccess: "Subject Information Access", authorityInfoAccess: "Authority Information Access",
+    cRLNumber: "X509v3 CRL Number", deltaCRLIndicator: "X509v3 Delta CRL Indicator",
+    issuingDistributionPoint: "X509v3 Issuing Distribution Point", cRLReason: "X509v3 CRL Reason Code",
+    invalidityDate: "Invalidity Date", certificateIssuer: "X509v3 Certificate Issuer",
+    signedCertificateTimestampList: "CT Precertificate SCTs", precertificatePoison: "CT Precertificate Poison",
+  },
+  // ==== KeyUsage bits (RFC 5280 sec. 4.2.1.3, bit order) ====
+  KEY_USAGE: {
+    digitalSignature: "Digital Signature", nonRepudiation: "Non Repudiation", keyEncipherment: "Key Encipherment",
+    dataEncipherment: "Data Encipherment", keyAgreement: "Key Agreement", keyCertSign: "Certificate Sign",
+    cRLSign: "CRL Sign", encipherOnly: "Encipher Only", decipherOnly: "Decipher Only",
+  },
+  // ==== ExtendedKeyUsage purposes (RFC 5280 sec. 4.2.1.12 + common); an unlisted
+  // purpose shows its registry name / OID ====
+  EXT_KEY_USAGE: {
+    anyExtendedKeyUsage: "Any Extended Key Usage", serverAuth: "TLS Web Server Authentication",
+    clientAuth: "TLS Web Client Authentication", codeSigning: "Code Signing",
+    emailProtection: "E-mail Protection", timeStamping: "Time Stamping", ocspSigning: "OCSP Signing",
+  },
+  // ==== GeneralName CHOICE labels, by context tag number (RFC 5280 sec. 4.2.1.6) ====
+  GENERAL_NAME: { 0: "othername", 1: "email", 2: "DNS", 3: "X400Name", 4: "DirName", 5: "EdiPartyName", 6: "URI", 7: "IP Address", 8: "Registered ID" },
+  // ==== Named-curve -> NIST alias, for the EC key line ====
+  NIST_CURVE: { prime256v1: "P-256", secp384r1: "P-384", secp521r1: "P-521" },
+  // ==== ReasonFlags BIT STRING bit -> name (RFC 5280 sec. 4.2.1.13, a CRL
+  // distribution point's revocation scope; bit 0 is "unused"). Distinct from the
+  // CRLReason ENUMERATED below -- a BIT STRING of scopes, not a single code. ====
+  REASON_FLAGS: {
+    1: "Key Compromise", 2: "CA Compromise", 3: "Affiliation Changed", 4: "Superseded",
+    5: "Cessation Of Operation", 6: "Certificate Hold", 7: "Privilege Withdrawn", 8: "AA Compromise",
+  },
+  // ==== CRLReason ENUMERATED value names (RFC 5280 sec. 5.3.1; value 7 is unused) ====
+  CRL_REASON: {
+    "0": "unspecified", "1": "keyCompromise", "2": "cACompromise", "3": "affiliationChanged",
+    "4": "superseded", "5": "cessationOfOperation", "6": "certificateHold",
+    "8": "removeFromCRL", "9": "privilegeWithdrawn", "10": "aACompromise",
+  },
+  // ==== OCSPResponseStatus value names (RFC 6960 sec. 4.2.1; value 4 is unassigned) ====
+  OCSP_STATUS: { "0": "successful", "1": "malformedRequest", "2": "internalError", "3": "tryLater", "5": "sigRequired", "6": "unauthorized" },
+  // ==== Attribute-cert objectDigestInfo digested-object types (RFC 5755 sec. 4.4.2) ====
+  OBJECT_DIGEST_TYPE: { "0": "publicKey", "1": "publicKeyCert", "2": "otherObjectTypes" },
+  // ==== Public-key / signature algorithm display names, classical + PQC. Forward-
+  // looking: the toolkit is PQC-first, so the FIPS 203/204/205 names render as-is;
+  // a consumer that finds no entry shows the OID registry name / dotted OID ====
+  ALGORITHM: {
+    rsaEncryption: "rsaEncryption", rsassaPss: "rsassaPss", rsaesOaep: "rsaesOaep", ecPublicKey: "id-ecPublicKey",
+    ed25519: "ED25519", ed448: "ED448", x25519: "X25519", x448: "X448",
+    "ML-DSA-44": "ML-DSA-44", "ML-DSA-65": "ML-DSA-65", "ML-DSA-87": "ML-DSA-87",
+    "ML-KEM-512": "ML-KEM-512", "ML-KEM-768": "ML-KEM-768", "ML-KEM-1024": "ML-KEM-1024",
+    "SLH-DSA-SHA2-128s": "SLH-DSA-SHA2-128s", "SLH-DSA-SHA2-128f": "SLH-DSA-SHA2-128f",
+    "SLH-DSA-SHA2-192s": "SLH-DSA-SHA2-192s", "SLH-DSA-SHA2-256s": "SLH-DSA-SHA2-256s",
+  },
+};
+
+// NAMES is BOTH a display table (pki.inspect) and the strict parsers' legal-value
+// allow-list: the CRL reasonCode, OCSP response-status, and attribute-cert object-
+// digest decoders check membership against CRL_REASON / OCSP_STATUS / OBJECT_DIGEST_TYPE
+// to fail closed on an RFC-reserved / undefined value. Deep-freeze it so a caller can
+// NEVER widen what those decoders accept by mutating the "display-only" table (e.g.
+// adding CRLReason 7, RFC-reserved, which would otherwise make the decoders fail open).
+Object.keys(NAMES).forEach(function (k) { Object.freeze(NAMES[k]); });
+Object.freeze(NAMES);
+
 // Single-sourced from the package manifest so the reported version can
 // never drift from the published package (package.json is always present
 // in the installed tarball). A hand-maintained literal here silently
@@ -267,5 +362,6 @@ module.exports = {
   TIME:    TIME,
   BYTES:   BYTES,
   LIMITS:  LIMITS,
+  NAMES:   NAMES,
   version: VERSION,
 };

package/lib/ct.js

@@ -42,6 +42,7 @@ var asn1 = require("./asn1-der.js");
 var constants = require("./constants.js");
 var frameworkError = require("./framework-error.js");
 var guard = require("./guard-all.js");
+var ByteReader = require("./byte-reader.js");
 
 var CtError = frameworkError.CtError;
 var C = constants;
@@ -64,44 +65,11 @@ var SCT_MIN_BODY = 47;
 var LOGID_BYTES = 32;
 var MAX_SAFE = 9007199254740991n;   // 2^53 - 1; above this a Number loses precision
 
-// ---- TlsReader -- the one net-new primitive (an ENCODING layer, not a schema
-// combinator): a bounded big-endian TLS-vector cursor with a hard [pos, end).
-// A lying inner length can overrun only the current sub-reader's `end`, never
-// the parent buffer, so bounds-before-slice is structural.
-function TlsReader(buf, start, end) { this.buf = buf; this.pos = start; this.end = end; }
-TlsReader.prototype._need = function (n, code) {
-  if (this.pos + n > this.end) {
-    throw new CtError(code || "ct/truncated", "need " + n + " byte(s), only " + (this.end - this.pos) + " remain");
-  }
-};
-TlsReader.prototype.u8 = function (code) { this._need(1, code); return this.buf[this.pos++]; };
-TlsReader.prototype.u16 = function (code) { this._need(2, code); var v = this.buf.readUInt16BE(this.pos); this.pos += 2; return v; };
-TlsReader.prototype.u24 = function (code) {
-  this._need(3, code);
-  var v = (this.buf[this.pos] << 16) | (this.buf[this.pos + 1] << 8) | this.buf[this.pos + 2];
-  this.pos += 3; return v;
-};
-TlsReader.prototype.u64 = function (code) { this._need(8, code); var v = this.buf.readBigUInt64BE(this.pos); this.pos += 8; return v; };
-TlsReader.prototype.fixed = function (n, code) {
-  this._need(n, code);
-  var s = this.buf.subarray(this.pos, this.pos + n); this.pos += n; return s;
-};
-// opaque<min..max> -- a length-prefixed vector (lenWidth-byte big-endian prefix).
-// The length prefix itself is a plain read (a truncation there is ct/truncated);
-// only a LYING length whose body overruns the bound carries the field's own code.
-TlsReader.prototype.vector = function (lenWidth, min, max, code) {
-  var len = lenWidth === 3 ? this.u24() : this.u16();
-  if (len < min) throw new CtError(code, "vector length " + len + " below minimum " + min);
-  if (max != null && len > max) throw new CtError(code, "vector length " + len + " above maximum " + max);
-  this._need(len, code);
-  var s = this.buf.subarray(this.pos, this.pos + len); this.pos += len; return s;
-};
-TlsReader.prototype.subReader = function (len, code) {
-  this._need(len, code);
-  var r = new TlsReader(this.buf, this.pos, this.pos + len); this.pos += len; return r;
-};
-TlsReader.prototype.remaining = function () { return this.end - this.pos; };
-TlsReader.prototype.atEnd = function () { return this.pos === this.end; };
+// ---- TlsReader -- the RFC 6962 TLS-vector cursor, the shared bounded big-endian
+// ByteReader engine primitive bound to the ct/* fault domain. A lying inner length
+// can overrun only the current sub-reader's `end`, never the parent buffer, so
+// bounds-before-slice is structural (see lib/byte-reader.js).
+function TlsReader(buf, start, end) { return new ByteReader(buf, start, end, CtError, "ct/truncated"); }
 
 // Peel the RFC 6962 sec. 3.3 inner DER OCTET STRING (the certificate/OCSP layer
 // already peeled the outer extnValue OCTET STRING). Rides the strict codec, so

package/lib/framework-error.js

@@ -293,6 +293,16 @@ var HpkeError = defineClass("HpkeError", { withCause: true });
 // expected in-toto Statement. Carries the underlying leaf fault (an x509/*,
 // merkle/*, or asn1/* error) as `.cause`.
 var SigstoreError = defineClass("SigstoreError", { withCause: true });
+// InspectError -- a bad input to the human-readable inspector (pki.inspect): a
+// value that is neither a parsed structure, DER Buffer, nor PEM string, or a PEM
+// whose label does not decode. Rendering itself is best-effort and never throws on
+// a malformed field -- an undecodable extension falls back to a hex dump.
+var InspectError = defineClass("InspectError", { withCause: true });
+// WebauthnError -- a malformed or unverifiable WebAuthn attestation (pki.webauthn):
+// a non-well-formed attestation object / COSE key, an authenticatorData that fails
+// its bounded layout, an attestation-statement signature that does not verify, or a
+// trust path that does not reach the caller's anchor. Fail-closed, typed reason.
+var WebauthnError = defineClass("WebauthnError", { withCause: true });
 
 module.exports = {
   PkiError:         PkiError,
@@ -319,6 +329,8 @@ module.exports = {
   ShbsError:        ShbsError,
   HpkeError:        HpkeError,
   SigstoreError:    SigstoreError,
+  InspectError:     InspectError,
+  WebauthnError:    WebauthnError,
   MerkleError:      MerkleError,
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,

package/lib/guard-all.js

@@ -23,6 +23,8 @@
 //                                        to Number (silent-narrowing defence)
 //   guard.name.dnEqual / .rdnEqual / .assertNoControlBytes / .assertPrintableIa5
 //                                     -- canonical DN identity + name-string integrity
+//   guard.name.escapeControlBytes / .escapeDnValue
+//                                     -- render-side name safety: control-byte + RFC 4514 escaping
 //                                        (CVE-2009-2408 truncation / identity defence)
 //   guard.encoding.base64url / .base64 / .hex
 //                                     -- strict textual-encoding decode, canonical

package/lib/guard-name.js

@@ -108,4 +108,53 @@ function dnEqual(rdnsA, rdnsB, E, code, label) {
   return true;
 }
 
-module.exports = { assertNoControlBytes: assertNoControlBytes, assertPrintableIa5: assertPrintableIa5, dnEqual: dnEqual, rdnEqual: rdnEqual };
+// escapeControlBytes(str) -> str. The render-side sibling of assertNoControlBytes:
+// where a name string must still be DISPLAYED best-effort (a human-readable report,
+// a log line) rather than rejected, neutralize every C0 control byte and DEL by
+// rendering it as \xHH. A bare CR / LF / NUL in a decoded dNSName or DN value would
+// otherwise forge or overwrite report lines in a terminal or log (CWE-117 output-log
+// injection / CWE-116 improper output encoding). Non-control bytes pass through.
+// Written as a charCodeAt scan, not a /[\x00-\x1f]/ regex: eslint's no-control-regex
+// (correctly) refuses control characters in a regex literal, and the control-byte
+// range test is the rename-proof shape the detector keys on regardless.
+// @enforced-by guard-shape-reinlined
+// @guard-shape < 0x20 \|\| \w+ === 0x7f
+function escapeControlBytes(str) {
+  var s = String(str), out = "";
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charCodeAt(i);
+    out += (c < 0x20 || c === 0x7f) ? "\\x" + (c < 16 ? "0" : "") + c.toString(16).toUpperCase() : s.charAt(i);
+  }
+  return out;
+}
+
+// escapeDnValue(v) -> str. RFC 4514 sec. 2.4 string-representation escaping of a DN
+// attribute value (the input is the already-unwrapped semantic string): backslash-
+// escape the always-specials , + " \ < > ; and a NUL (as \00), then the positional
+// rules -- a trailing space as '\ ' and a leading '#' or space as '\#' / '\ '. Without
+// this a value like `foo, CN=admin` renders as two RDNs, and a literal `#05` collides
+// with the hexstring form, so the report misstates a subject/issuer name (CWE-116).
+// The one place a DN attribute value is made display-safe; pki.schema.pkix's DN
+// rendering composes it, and pki.inspect reuses that parser output (name.dn).
+// @enforced-by behavioral -- the RFC 4514 separator class carries a quote inside a
+//   regex literal, which the codebase-patterns literal-stripper mis-tokenizes, so no
+//   rename-proof shape is detectable; the guard-name RED vectors + the schema-pkix DN
+//   round-trip vectors (a comma / plus / leading '#' renders backslash-escaped) are the guard.
+function escapeDnValue(v) {
+  var s = String(v).replace(/([,+"\\<>;])/g, "\\$1"), out = "";
+  // RFC 4514 sec. 2.4: a NUL / control octet -> '\' + two hex digits, so an embedded
+  // CR / LF / NUL in a decoded DN value can never forge a report line when displayed.
+  for (var i = 0; i < s.length; i++) {
+    var c = s.charCodeAt(i);
+    out += (c < 0x20 || c === 0x7f) ? "\\" + (c < 16 ? "0" : "") + c.toString(16).toUpperCase() : s.charAt(i);
+  }
+  if (out.length && out.charAt(out.length - 1) === " ") out = out.slice(0, -1) + "\\ ";
+  if (out.charAt(0) === "#" || out.charAt(0) === " ") out = "\\" + out;
+  return out;
+}
+
+module.exports = {
+  assertNoControlBytes: assertNoControlBytes, assertPrintableIa5: assertPrintableIa5,
+  dnEqual: dnEqual, rdnEqual: rdnEqual,
+  escapeControlBytes: escapeControlBytes, escapeDnValue: escapeDnValue,
+};