0
# ASN.1 JavaScript Parser
1

2
@lapo/asn1js is a generic ASN.1 parser/decoder that can decode any valid ASN.1 DER (Distinguished Encoding Rules) or BER (Basic Encoding Rules) structures. It provides comprehensive tools for parsing, analyzing, and visualizing ASN.1 data in both Node.js and browser environments.
3

4
## Package Information
5

6
- **Package Name**: @lapo/asn1js
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES6 modules)
9
- **Installation**: `npm install @lapo/asn1js`
10

11
## Core Imports
12

13
```javascript
14
import { ASN1 } from '@lapo/asn1js';
15
import { Stream } from '@lapo/asn1js';
16
import { Hex } from '@lapo/asn1js/hex.js';
17
import { Base64 } from '@lapo/asn1js/base64.js';
18
```
19

20
For CommonJS (Node.js 22+ with `--experimental-require-module`):
21

22
```javascript
23
const { ASN1 } = require('@lapo/asn1js');
24
const { Hex } = require('@lapo/asn1js/hex.js');
25
```
26

27
For older Node.js versions (dynamic import):
28

29
```javascript
30
const { ASN1 } = await import('@lapo/asn1js');
31
const { Hex } = await import('@lapo/asn1js/hex.js');
32
```
33

34
## Basic Usage
35

36
```javascript
37
import { ASN1 } from '@lapo/asn1js';
38
import { Hex } from '@lapo/asn1js/hex.js';
39
import { Base64 } from '@lapo/asn1js/base64.js';
40

41
// Parse from hex string
42
const hexData = '06032B6570';
43
const binaryData = Hex.decode(hexData);
44
const asn1 = ASN1.decode(binaryData);
45
console.log(asn1.content()); // OID content
46

47
// Parse from Base64/PEM
48
const base64Data = 'MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA...';
49
const derData = Base64.unarmor(base64Data);
50
const parsed = ASN1.decode(derData);
51
console.log(parsed.toPrettyString());
52
```
53

54
## Architecture
55

56
The library is built around several core components:
57

58
- **ASN.1 Parser**: Core `ASN1` class for parsing and representing ASN.1 structures
59
- **Stream Processing**: `Stream` class for efficient byte-level processing with zero-copy approach
60
- **Encoding Support**: `Hex` and `Base64` classes for handling various input formats
61
- **Tag System**: `ASN1Tag` class for proper ASN.1 tag representation and validation
62
- **DOM Integration**: `ASN1DOM` class for browser-based visualization
63
- **Utility Classes**: `Int10` for big integer support, OID database, and RFC definitions
64

65
## Capabilities
66

67
### Core ASN.1 Parsing
68

69
Parse any valid ASN.1 DER or BER structure with complete type support and detailed content extraction.
70

71
```javascript { .api }
72
/**
73
 * Main ASN.1 decoder function
74
 * @param stream - Stream or binary data to decode
75
 * @param offset - Starting position (optional)
76
 * @returns ASN1 instance representing the parsed structure
77
 */
78
function ASN1.decode(stream: Stream | ArrayLike<number> | string, offset?: number): ASN1;
79

80
class ASN1 {
81
  /** Get human-readable type name for this ASN.1 element */
82
  typeName(): string;
83
  /** Get human-readable content preview */
84
  content(maxLength?: number): string | null;
85
  /** Pretty formatted string representation with indentation */
86
  toPrettyString(indent?: string): string;
87
  /** Get starting position in stream */
88
  posStart(): number;
89
  /** Get content starting position */
90
  posContent(): number;
91
  /** Get ending position */
92
  posEnd(): number;
93
  /** Convert to hexadecimal string */
94
  toHexString(type?: 'raw' | 'byte' | 'dump'): string;
95
  /** Convert to Base64url string */
96
  toB64String(type?: 'url' | 'std'): string;
97
}
98
```
99

100
[Core Parsing](./core-parsing.md)
101

102
### Stream Processing
103

104
Efficient byte-level stream processing with zero-copy approach for optimal performance.
105

106
```javascript { .api }
107
class Stream {
108
  constructor(enc: Stream | ArrayLike<number> | string, pos?: number);
109
  /** Get byte at current position (and increment) or specified position */
110
  get(pos?: number): number;
111
  /** Hexadecimal dump of stream region */
112
  hexDump(start: number, end: number, type?: 'raw' | 'byte' | 'dump'): string;
113
  /** Base64 dump of stream region */
114
  b64Dump(start: number, end: number, type?: 'url' | 'std'): string;
115
}
116
```
117

118
[Stream Processing](./stream-processing.md)
119

120
### Format Support
121

122
Comprehensive support for hexadecimal and Base64 input formats, including PEM armoring.
123

124
```javascript { .api }
125
class Hex {
126
  /** Decode hexadecimal string/array to binary data */
127
  static decode(a: string | ArrayLike<number>): Uint8Array | number[];
128
}
129

130
class Base64 {
131
  /** Decode base64 string/array to binary data */
132
  static decode(a: string | ArrayLike<number>): Uint8Array | number[];
133
  /** Format base64 string with proper padding and line breaks */
134
  static pretty(str: string): string;
135
  /** Extract and decode base64 from PEM or other armored formats */
136
  static unarmor(a: string): Uint8Array | number[];
137
}
138
```
139

140
[Format Support](./format-support.md)
141

142
### DOM Visualization
143

144
Browser-specific functionality for creating interactive ASN.1 structure visualizations.
145

146
```javascript { .api }
147
class ASN1DOM extends ASN1 {
148
  /** Generate DOM element representation of ASN.1 structure */
149
  toDOM(spaces?: string): HTMLElement;
150
  /** Generate hexadecimal DOM display */
151
  toHexDOM(start?: number, trimmedHex?: boolean): HTMLElement;
152
}
153
```
154

155
[DOM Visualization](./dom-visualization.md)
156

157
### Command Line Interface
158

159
Command-line tool for dumping and analyzing ASN.1 structures from files or data URIs.
160

161
```bash
162
# Dump ASN.1 structure from file
163
npx @lapo/asn1js certificate.der
164

165
# Dump from data URI
166
npx @lapo/asn1js data:base64,MIICIjANBgkqhkiG9w0BAQEFAAOCAg8A...
167
```
168

169
[CLI Usage](./cli-usage.md)
170

171
## Types
172

173
```javascript { .api }
174
// ASN1Tag interface (internal class, not exported - accessible via asn1.tag property)
175
interface ASN1Tag {
176
  tagClass: number;
177
  tagConstructed: boolean;
178
  tagNumber: number;
179
  isUniversal(): boolean;
180
  isEOC(): boolean;
181
}
182

183
class Int10 {
184
  constructor(value?: number);
185
  mulAdd(m: number, c: number): void;
186
  sub(c: number): void;
187
  toString(base?: number): string;
188
  valueOf(): number;
189
  simplify(): number | Int10;
190
}
191

192
// OID database - maps OID strings to descriptive information
193
interface OIDInfo {
194
  d?: string; // description
195
  c?: string; // comment  
196
  w?: string; // warning
197
}
198

199
const oids: Record<string, OIDInfo>;
200
```