ASN.1 Parser

ASN.1 text parser in TypeScript. To clarify: this is not a Basic Encoding Rules (BER), Distinguished Encoding Rules (DER) encoder / decoder, etc. If you are attempting to serialize or deserialize ASN.1 data, this is not the correct module for your purposes. This module parses the textual ASN.1 specifications themselves, according to the syntax defined in the freely available ITU-T Recommendations X.680, X.681, X.682, and X.683.

Documentation

• Usage
• Compatibility with Old ASN.1 Features
• Phases of Compilation
• Terminology Used by this Module
• Design Mistakes

Usage Example

This is a test, completely copied and pasted here to showcase the capabilies and usage of this module:

import { strict as assert, strictEqual as assertEquals } from 'node:assert';
import { lex, grok, normalize, parse, correct, AssignmentType, TypeType } from '../dist/index.mjs';
import { test } from 'node:test';

const AuthenticationFramework = `
AuthenticationFramework {joint-iso-itu-t ds(5) module(1) authenticationFramework(7) 8}
DEFINITIONS ::= BEGIN

-- EXPORTS All

IMPORTS

  ATTRIBUTE, DistinguishedName, MATCHING-RULE, Name, NAME-FORM, OBJECT-CLASS,
  RelativeDistinguishedName, SYNTAX-NAME, top
    FROM InformationFramework informationFramework ;

SIGNATURE ::= SEQUENCE {
  algorithmIdentifier  AlgorithmIdentifier{{SupportedAlgorithms}},
  signature            BIT STRING,
  ... }

SIGNED{ToBeSigned} ::= SEQUENCE {
  toBeSigned    ToBeSigned,
  COMPONENTS OF SIGNATURE,
  ... }
  
END`;

test('the README example works', () => {
  const text = AuthenticationFramework;
  const lexResults = Array.from(lex(text));
  const parseResults = parse(text, lexResults);
  const modules = grok(text, parseResults);
  const normalizedModules = normalize(modules);
  correct(normalizedModules);
  const afmod = normalizedModules[0];
  assertEquals(afmod.name, 'AuthenticationFramework');
  const sig = afmod.assignments.SIGNATURE;
  assert(sig.assignmentType === AssignmentType.TypeAssignment);
  assert(afmod.assignments.SIGNATURE.type.typeType === TypeType.SequenceType);
  /** @type {import('../dist/index.mjs').SetOrSequenceType} */
  const seq = afmod.assignments.SIGNATURE.type.type;
  assertEquals(seq.rootComponentTypeList1.length, 2);
  const [ comp1, comp2 ] = seq.rootComponentTypeList1 ?? [];

  assertEquals(comp1.namedType.identifier, 'algorithmIdentifier');
  assertEquals(comp1.namedType.type.typeType, TypeType.DefinedType);
  assertEquals(comp1.namedType.type.type.reference, 'AlgorithmIdentifier');
  assertEquals(comp1.optional, false);
  assertEquals(comp1.text, 'algorithmIdentifier  AlgorithmIdentifier{{SupportedAlgorithms}}');
  assertEquals(comp1.default, undefined);
  // The offset of the start of this component in characters into the original text.
  assertEquals(comp1.production.location.startIndex, 341);
  // The offset of the end of this component in characters into the original text.
  assertEquals(comp1.production.location.endIndex, 341 + 63);

  assertEquals(comp2.namedType.identifier, 'signature');
  assertEquals(comp2.namedType.type.typeType, TypeType.BitStringType);
  assertEquals(comp2.optional, false);
  assertEquals(comp2.text, 'signature            BIT STRING');
  assertEquals(comp2.default, undefined);
});

Module System and Environment

This module is published as an ESM module exclusively. If you are still using CommonJS, it is time to get with the times and switch to ESM. This module is published on both npmjs.com and jsr.io.

This module is intentionally run-time agnostic. It works on Node.js, Deno, Bun, and it probably would work on QuickJS and in any browser.

This module has a single run-time dependency, which itself has no further dependencies.

Building

You can build this library by running npm run build. The outputs will all be in dist. dist/index.mjs is the entry point where all of the symbols that constitute the public API are exported.

Testing

If you have Node.js installed, you can test using npm run node-test. To test with Bun, use npm run bun-test. To test with Deno, use npm run deno-test. There is only one Deno test, whose purpose is to kind of "smoke test" that this works on Deno.

You can check if this module has any problems with JSR by running npx jsr publish --dry-run --allow-dirty.

AI / LLM Usage Statement

None of the code in this repository was written AI / LLMs, except a few tests that were previously written run using Jest were converted to using the built-in NodeJS test runner, and Cursor was used to add some missing type annotations.

See Also

• Meerkat DSA, an X.500 directory server that uses ASN.1 that was compiled to TypeScript using this module.

• ASN.1: Communication Between Heterogeneous Systems by Olivier Dubuisson

To Do

• [ ] Performance Enhancements
• [ ] Make dependency on dependency-graph optional