asn1-schema

@peculiar/asn1-schema is the core schema-definition package behind PeculiarVentures’ family of ASN.1 modules (asn1-x509, asn1-csr, asn1-cms, asn1-pkcs8, and dozens more in the same monorepo). Instead of hand-writing BER/DER encoding and decoding logic, developers attach @AsnType and @AsnProp decorators to plain TypeScript classes, and the package’s AsnConvert, AsnParser, and AsnSerializer classes handle turning those classes into binary ASN.1 structures and back.

Under the hood it wraps asn1js, adding a schema-storage layer that tracks each decorated class’s structure (SEQUENCE, SET, CHOICE, context-specific tags, IMPLICIT/EXPLICIT tagging, repeated fields) so that parsing and serialization stay declarative rather than imperative. This is the foundation that lets the rest of the asn1-* packages express complex PKI structures like X.509 certificates, CSRs, and CMS messages as ordinary annotated classes.

It is widely used in the Node.js crypto ecosystem — pulled in transitively by libraries handling certificates, PKCS containers, and PKI tooling — with tens of millions of weekly npm downloads.

What You Get

• @AsnType, @AsnProp, @AsnChoiceType, @AsnSequenceType, and @AsnSetType decorators for declaring ASN.1 SEQUENCE, SET, and CHOICE structures directly on TypeScript classes
• AsnParser.parse/fromASN for deserializing DER/BER-encoded buffers into typed class instances, including CHOICE resolution and IMPLICIT/EXPLICIT context tagging
• AsnSerializer.serialize/toASN for converting decorated class instances back into ASN.1-encoded ArrayBuffers
• A library of built-in converters (AsnIntegerConverter, AsnBitStringConverter, AsnOctetStringConverter, and more) mapping ASN.1 primitive types to native JS values, with support for custom converters
• Support for repeated fields (arrays mapped to SEQUENCE OF / SET OF), default-value omission on serialize, and raw-bytes capture via the raw prop option
• Configurable resource limits (maxDepth, maxNodes, maxContentLength) forwarded to the underlying BER parser to guard against malicious/oversized untrusted input

Common Use Cases

• Building or consuming X.509 certificate, CSR, or CRL structures by composing this package with @peculiar/asn1-x509/@peculiar/asn1-csr schema classes
• Parsing PKCS#8 private keys, PKCS#12 (PFX) containers, or CMS/PKCS#7 signed and enveloped messages in Node.js or browser PKI tooling
• Implementing custom ASN.1-based protocols (e.g. OCSP, TSP, CRMF) by declaring new schema classes rather than hand-rolling BER encoding
• Adding typed, class-based parsing/serialization to any project that currently manipulates raw ASN.1 buffers via asn1js directly
• Validating untrusted DER input safely by tuning berOptions (max depth/nodes/content length) during AsnParser.parse

Under The Hood

Architecture The package centers on three collaborating pieces: a decorator layer (decorators.ts) that populates a per-class schemaStorage map when @AsnType/@AsnProp are applied, and two static classes — AsnParser (parser.ts) and AsnSerializer (serializer.ts) — that read that stored schema to convert between asn1js trees and decorated class instances. Parsing walks a class’s schema depth-first, special-casing CHOICE resolution, context-tagged IMPLICIT/EXPLICIT fields, and SEQUENCE OF/SET OF repetition, then delegates primitive leaves to a converter registry (converters.ts); serialization mirrors this in reverse, skipping properties that match their declared defaultValue to match DER’s canonical-encoding rules. Because every consuming package (asn1-x509, asn1-csr, asn1-cms, etc.) only defines schema classes and never touches BER bytes directly, the core abstraction this package owns — schemaStorage plus the parse/serialize contract — is what the rest of the monorepo’s ~30 packages depend on; changing its shape would ripple through all of them.

Tech Stack Written in TypeScript targeting ES2015/CJS dual output (build:cjs/build:es2015 via tsc), with asn1js (^3.0.10) as the underlying BER/DER codec and @peculiar/utils (^2.0.2) for buffer helpers (toArrayBuffer, BufferSourceLike) and tslib for decorator/helper runtime support. The monorepo builds with Lerna, lints/formats with oxlint/oxfmt, type-checks with a shared root tsconfig.json that path-maps all ~30 sibling packages for cross-package development, and tests with Vitest (vitest.config.ts targets packages/**/test/**/*.ts) plus v8 coverage.

Code Quality Tests live in test/test.ts (a ~31KB suite using Node’s built-in assert plus Vitest’s describe/it globals) and cover default-value omission, CHOICE/IMPLICIT/EXPLICIT tagging, repeated fields, and buffer-level serialize/parse round-trips against expected hex output — a thorough behavioral suite for a schema/codec library, though it exercises the public API rather than unit-testing internal helpers directly. Error handling is explicit and typed (AsnSchemaValidationError extends Error and accumulates a schemas trail for diagnostics as errors propagate up through nested fromASN calls), and CI (.github/workflows/test.yml) runs lint, format-check, and tsc --noEmit type-check on every PR/push to main. Internal parser/serializer methods are broken into small, well-named private static helpers (handleChoiceTypes, processRepeatedField, handleImplicitTagging, etc.), aiding readability despite the inherent complexity of ASN.1’s tagging rules.

What Makes It Unique Rather than exposing a general-purpose BER/DER tree API (as asn1js does), this package lets consumers describe ASN.1 structures the way they’d describe a class-validation schema — with decorators — and get typed parse/serialize for free, including the trickier corners of the spec (CHOICE-with-context-tags, IMPLICIT tagging fix-ups, raw-bytes capture for re-signing scenarios) handled centrally instead of per-protocol. That design is what let PeculiarVentures build and maintain dozens of standard-specific ASN.1 packages (X.509, CMS, OCSP, CRMF, PKCS variants) from one shared schema engine instead of each reimplementing BER encoding.