Skip to content
BranchesTags

Repository files navigation

@aokiapp/tlv

Tag-Length-Value (TLV) parser and builder library with schema support. Provides both parsing and building APIs as submodules.

Features

  • Schema-based TLV parsing and building: Define structured schemas for complex TLV data
  • DER encoding support: Full compliance with Distinguished Encoding Rules
  • Modular API: Separate parser and builder modules for focused usage
  • TypeScript-first: Complete type safety with inferred types from schemas
  • ASN.1 compatible: Support for various ASN.1 constructs (SEQUENCE, SET, primitives, etc.)
  • Real-world examples: Includes CMS (RFC 5652) and CRCL implementations

Installation

From npm

npm install @aokiapp/tlv

From GitHub Packages

Note: GitHub Packages requires authentication even for public packages.

First, authenticate with GitHub:

npm login --registry=https://npm.pkg.github.com

Then install:

npm install @aokiapp/tlv --registry=https://npm.pkg.github.com

Or configure your .npmrc:

@aokiapp:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Quick Start

Basic TLV Parsing

import{BasicTLVParser}from"@aokiapp/tlv/parser";// Parse raw TLV dataconstbuffer=newUint8Array([0x04,0x05,0x48,0x65,0x6c,0x6c,0x6f]).buffer;consttlv=BasicTLVParser.parse(buffer);console.log(tlv);// {// tag: { tagClass: 0, constructed: false, tagNumber: 4 },// length: 5,// value: ArrayBuffer(...),// endOffset: 7// }

Schema-based Parsing

import{SchemaParser,Schema,TagClass}from"@aokiapp/tlv/parser";import{decodeUtf8,decodeInteger}from"@aokiapp/tlv/common";// Define a schema for a person recordconstPersonSchema=Schema.constructed("person",{tagNumber: 16},[Schema.primitive("id",{tagNumber: 2},decodeInteger),Schema.primitive("name",{tagNumber: 12},decodeUtf8),Schema.primitive("email",{tagNumber: 12,optional: true},decodeUtf8),]);// Parse TLV data according to schemaconstparser=newSchemaParser(PersonSchema);constresult=parser.parse(tlvBuffer);// Result is fully typed:// { id: number, name: string, email?: string }

Schema-based Building

import{SchemaBuilder,Schema}from"@aokiapp/tlv/builder";import{encodeUtf8,encodeInteger}from"@aokiapp/tlv/common";// Define builder schemaconstPersonSchema=Schema.constructed("person",{tagNumber: 16},[Schema.primitive("id",{tagNumber: 2},encodeInteger),Schema.primitive("name",{tagNumber: 12},encodeUtf8),]);// Build TLV data from structured inputconstbuilder=newSchemaBuilder(PersonSchema);consttlvBuffer=builder.build({id: 123,name: "John Doe",});

API Reference

Parser Module (@aokiapp/tlv/parser)

BasicTLVParser

Low-level TLV parsing for raw DER/BER data.

classBasicTLVParser{staticparse(buffer: ArrayBuffer): TLVResult;}

Parameters:

  • buffer: ArrayBuffer - Raw TLV data to parse

Returns:

  • TLVResult - Parsed structure with tag, length, value, and endOffset

Throws:

  • Error if indefinite length (0x80) is encountered (DER compliance)
  • Error if declared length exceeds available bytes

Example:

constbuffer=newUint8Array([0x04,0x05,0x48,0x65,0x6c,0x6c,0x6f]).buffer;constresult=BasicTLVParser.parse(buffer);// Returns: {// tag: { tagClass: 0, constructed: false, tagNumber: 4 },// length: 5,// value: ArrayBuffer(5), // "Hello"// endOffset: 7// }

SchemaParser

Schema-driven TLV parsing with full type inference.

classSchemaParser{constructor(schema: TLVSchema,options?: {strict?: boolean});parse(buffer: ArrayBuffer): any;// Fully typed based on schema}

Constructor Parameters:

  • schema: TLVSchema - TLV schema definition
  • options.strict?: boolean - Enable strict validation (default: true)

Methods:

parse(buffer: ArrayBuffer): any

Parse TLV data according to schema with full type inference.

Parameters:

  • buffer: ArrayBuffer - DER-encoded TLV data

Returns:

  • Fully typed result based on schema definition (TypeScript infers the exact type)

Behavior:

  • Strict mode (default): Enforces exact schema compliance, canonical SET ordering
  • Non-strict mode: More permissive parsing, preserves original SET order
  • SEQUENCE: Children must appear in exact schema order
  • SET: Children can appear in any order, validated for canonical ordering in strict mode
  • Repeated fields: Automatically collect multiple consecutive matching children

Throws:

  • Error on tag class/number mismatches
  • Error on missing required fields
  • Error on unknown children (immediate failure regardless of strict mode)
  • Error on DER canonical order violations in SET (strict mode only)

Schema (Parser)

Factory class for creating parser schemas.

classSchema{staticprimitive(name: string,options: SchemaOptions,decode?: (buffer: ArrayBuffer)=>any,): TLVSchema;staticconstructed(name: string,options: SchemaOptions,fields: TLVSchema[],): TLVSchema;staticrepeated(name: string,options: SchemaOptions,item: TLVSchema,): TLVSchema;}

Builder Module (@aokiapp/tlv/builder)

BasicTLVBuilder

Low-level TLV building for constructing DER-encoded data.

classBasicTLVBuilder{staticbuild(tlv: TLVResult): ArrayBuffer;}

Parameters:

  • tlv: TLVResult - TLV structure to encode

Returns:

  • ArrayBuffer - DER-encoded TLV data

Behavior:

  • Supports high tag numbers (>= 31) with multi-byte encoding
  • Supports long-form length encoding (>= 128 bytes)
  • Enforces DER canonical encoding rules
  • Maximum length field: 126 bytes (BER/DER limit)

Throws:

  • Error for invalid tag numbers (negative, non-finite)
  • Error for invalid tag classes (outside 0-3 range)
  • Error for values too large to encode (> 126-byte length field)

Example:

consttlv: TLVResult={tag: {tagClass: TagClass.Universal,constructed: false,tagNumber: 4},length: 5,value: newTextEncoder().encode("Hello").buffer,endOffset: 0,};constencoded=BasicTLVBuilder.build(tlv);

SchemaBuilder

Schema-driven TLV building with type validation.

classSchemaBuilder{constructor(schema: TLVSchema,options?: {strict?: boolean});build(data: any): ArrayBuffer;// Input type inferred from schema}

Constructor Parameters:

  • schema: TLVSchema - TLV schema definition
  • options.strict?: boolean - Enable strict validation (default: true)

Methods:

build(data: any): ArrayBuffer

Build DER-encoded TLV data from structured input.

Parameters:

  • data: any - Input data matching schema structure (TypeScript infers exact type)

Returns:

  • ArrayBuffer - DER-encoded TLV data

Behavior:

  • Strict mode (default): Validates all required fields, sorts SET children canonically
  • Non-strict mode: Permits missing fields, preserves SET child order
  • Type safety: Input data type is inferred from schema definition
  • SET ordering: Applies DER canonical lexicographic sorting in strict mode

Throws:

  • Error on missing required properties (strict mode)
  • Error on type validation failures
  • Error on top-level repeated schemas (must be wrapped in constructed container)

Schema (Builder)

Factory class for creating builder schemas.

classSchema{staticprimitive(name: string,options: SchemaOptions,encode?: (data: any)=>ArrayBuffer,): TLVSchema;staticconstructed(name: string,options: SchemaOptions,fields: TLVSchema[],): TLVSchema;staticrepeated(name: string,options: SchemaOptions,item: TLVSchema,): TLVSchema;}

Schema Options

All schema factory methods accept common options:

interfaceSchemaOptions{readonlytagClass?: TagClass;// Default: TagClass.UniversalreadonlytagNumber?: number;// Required for primitivesreadonlyoptional?: boolean;// Default: falsereadonlyisSet?: boolean;// Auto-inferred for UNIVERSAL 16/17}

Tag Class Values:

  • TagClass.Universal (0) - Standard ASN.1 types
  • TagClass.Application (1) - Application-specific types
  • TagClass.ContextSpecific (2) - Context-specific types
  • TagClass.Private (3) - Private types

Tag Number Inference:

  • SEQUENCE: tagNumber: 16 (UNIVERSAL, constructed)
  • SET: tagNumber: 17 (UNIVERSAL, constructed)
  • Custom tags: Explicit tagNumber required

Utility Functions

Encoding Functions

// Text encodingfunctionencodeUtf8(str: string): ArrayBuffer;functionencodeAscii(str: string): ArrayBuffer;// Number encodingfunctionencodeInteger(n: number): ArrayBuffer;// DER INTEGER encodingfunctionencodeOID(oid: string): ArrayBuffer;// OBJECT IDENTIFIER encoding// Binary encodingfunctionencodeBitString(bits: {unusedBits: number;data: Uint8Array;}): ArrayBuffer;// Buffer utilitiesfunctiontoArrayBuffer(u8: Uint8Array): ArrayBuffer;

Decoding Functions

// Text decodingfunctiondecodeUtf8(buffer: ArrayBuffer): string;functiondecodeAscii(buffer: ArrayBuffer): string;functiondecodeShiftJis(buffer: ArrayBuffer): string;// Number decodingfunctiondecodeInteger(buffer: ArrayBuffer): number;functiondecodeOID(buffer: ArrayBuffer): string;// Binary decodingfunctiondecodeBitStringHex(buffer: ArrayBuffer): {unusedBits: number;hex: string;};// Buffer utilitiesfunctiontoHex(input: ArrayBuffer|Uint8Array): string;functionbufferToArrayBuffer(buf: Buffer): ArrayBuffer;

Schema Pattern Examples

Basic Schema Types

// Primitive fieldSchema.primitive("fieldName",{tagNumber: 4},decodeUtf8);// Optional fieldSchema.primitive("optional",{tagNumber: 5,optional: true},decodeUtf8);// Context-specific tag [0], [1], etc.Schema.primitive("contextTag",{tagClass: TagClass.ContextSpecific,tagNumber: 0,},decodeInteger,);// SEQUENCE (ordered container)Schema.constructed("sequence",{tagNumber: 16},[Schema.primitive("field1",{tagNumber: 2},decodeInteger),Schema.primitive("field2",{tagNumber: 12},decodeUtf8),]);// SET (unordered container)Schema.constructed("set",{tagNumber: 17,isSet: true},[Schema.primitive("a",{tagNumber: 2},decodeInteger),Schema.primitive("b",{tagNumber: 12},decodeUtf8),]);// SEQUENCE OF (repeated items)Schema.constructed("container",{tagNumber: 16},[Schema.repeated("items",{},Schema.primitive("item",{tagNumber: 4},decodeUtf8),),]);

Nested Structures

constDocumentSchema=Schema.constructed("document",{tagNumber: 16},[Schema.constructed("header",{tagNumber: 16},[Schema.primitive("version",{tagNumber: 2},decodeInteger),Schema.primitive("timestamp",{tagNumber: 24},decodeUtf8),]),Schema.constructed("content",{tagNumber: 16},[Schema.primitive("title",{tagNumber: 12},decodeUtf8),Schema.primitive("description",{tagNumber: 12,optional: true},decodeUtf8,),Schema.repeated("tags",{},Schema.primitive("tag",{tagNumber: 12},decodeUtf8),),]),]);// TypeScript infers:// {// header: { version: number; timestamp: string };// content: { title: string; description?: string; tags: string[] }// }

Operating Modes

Strict Mode (Default)

newSchemaParser(schema,{strict: true});// DefaultnewSchemaBuilder(schema,{strict: true});
  • Validation: Enforces exact schema compliance
  • SET ordering: Validates/applies DER canonical ordering
  • Error handling: Fails fast on any schema violations

Non-Strict Mode

newSchemaParser(schema,{strict: false});newSchemaBuilder(schema,{strict: false});
  • Flexibility: More permissive parsing/building
  • SET ordering: Preserves original order
  • Performance: Faster with less validation overhead

Error Handling

try{constresult=newSchemaParser(schema).parse(buffer);}catch(error){// Detailed error messages for debugging:// - "TLV tag mismatch for primitive 'fieldName'"// - "Missing required property 'fieldName'"// - "DER canonical order violation in SET 'setName'"console.error("Parse failed:",error.message);}

Advanced Usage

Custom Codecs

// Custom timestamp codecfunctiondecodeTimestamp(buffer: ArrayBuffer): Date{constiso=newTextDecoder().decode(buffer);returnnewDate(iso);}constschema=Schema.primitive("created",{tagNumber: 24},decodeTimestamp);// Result type automatically inferred as Date

Development

Build

npm run build # Compile TypeScript
npm run typecheck # Type checking only

Testing

npm test# Run tests

Code Quality

npm run lint # ESLint
npm run format # Prettier

Release

This library is automatically published to both npm and GitHub Packages via GitHub Actions.

npm run changelog # Create changeset
npm run version # Update version
npm run publish # Publish manually (for testing, otherwise use GitHub Actions)

When changes are pushed to the main branch with a changeset, the GitHub Actions workflow will:

  1. Create a release PR or publish to npm
  2. Automatically publish to GitHub Packages if npm publish succeeds

Project Structure

├── src/
│ ├── parser/ # TLV parsing functionality
│ ├── builder/ # TLV building functionality
│ ├── common/ # Shared types and utilities
│ └── utils/ # Encoding/decoding utilities
├── examples/
│ ├── cms/ # CMS (RFC 5652) examples
│ └── crcl/ # CRCL certificate request examples
├── tests/ # Test suite
└── dist/ # Compiled output

Supported Encoders/Decoders

The library includes various built-in codecs:

  • Text: UTF-8, ASCII, Shift-JIS
  • Numbers: INTEGER (DER encoding)
  • Identifiers: OBJECT IDENTIFIER
  • Binary: BIT STRING, OCTET STRING
  • Utility: Hex conversion, buffer operations

TypeScript Support

Full TypeScript support with:

  • Schema type inference for parsing results
  • Compile-time validation of builder input data
  • Optional/required field type safety
  • Generic schema composition

License

This project is licensed under the AokiApp Normative Application License - Tight. See LICENSE.md for details.

Note: This is NOT an open source license. The source code is made publicly visible for transparency only. Commercial use requires explicit written permission from AokiApp Inc.

Contributing

This project is currently under restrictive licensing. For contribution guidelines or commercial licensing inquiries, please contact AokiApp Inc. at hello+github@aoki.app.

Changelog

See CHANGELOG.md for version history and changes.

About

High-performance TypeScript library for Tag-Length-Value (TLV) parsing and building, with schema-driven API and full type support.

Resources

Readme
License
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages