Getting Started

Getting Started

ASN.1 Instance Builder can be used as a local browser app, a reusable npm package, or an embeddable browser/Webview UI.

Install from npm

npm install @pkistudio/asn1instancebuilder

The package exports:

• @pkistudio/asn1instancebuilder: UI-independent Core API.
• @pkistudio/asn1instancebuilder/core: Core API alias.
• @pkistudio/asn1instancebuilder/app: browser application initializer.
• @pkistudio/asn1instancebuilder/styles.css: application stylesheet.

Run Locally from the Repository

npm install
npm run dev

Then open the Vite local URL, normally:

http://localhost:5173/

In VS Code, the Start asn1instancebuilder server task starts the same development server on port 5173.

Build DER in the Browser App

The intended browser flow is:

1. Load a supported ASN.1 definition from Load -> NamedObjects, a local file, or the clipboard.
2. Select a defined type in the Instance Input pane.
3. Edit or replace the generated sample instance JSON.
4. Click Build DER.
5. Inspect the generated DER in the standalone PkiStudioJS viewer tab.

The app starts with an empty definition workspace. Load -> NamedObjects includes bundled examples such as Person, Certificate, CertificationRequest, CertificateList, and PkiBundle.

Try a Small Definition

Use Load -> from Clipboard with this definition:

Example DEFINITIONS ::= BEGIN
Person ::= SEQUENCE {
  name UTF8String,
  age INTEGER OPTIONAL,
  email IA5String OPTIONAL
}
END

Then use this instance JSON:

{
  "name": "Alice",
  "age": 42,
  "email": "alice@example.test"
}

Click Build DER. If parsing and diagnostics pass, the app generates DER and opens the output in PkiStudioJS.

Use the APIs Directly

Use the UI-independent parser and DER builder:

import { bytesToHex, createInstance, parseAsn1Definition } from '@pkistudio/asn1instancebuilder';

const schema = parseAsn1Definition(`Example DEFINITIONS ::= BEGIN
Person ::= SEQUENCE {
  name UTF8String,
  age INTEGER OPTIONAL
}
END`);

const document = createInstance(schema, 'Person', { name: 'Alice', age: 42 });
console.log(bytesToHex(document.der));

Use diagnostics before building DER when the input comes from users:

import { parseAsn1Definition, validateInstance, validateSchemaModule } from '@pkistudio/asn1instancebuilder';

const schema = parseAsn1Definition(source);
const schemaDiagnostics = validateSchemaModule(schema);
const instanceDiagnostics = validateInstance(schema, 'Person', input);

console.log(schemaDiagnostics, instanceDiagnostics);

Bundled Fixtures

The repository includes ASN.1 definitions and matching instance JSON files under fixtures/.

Useful starting points include:

• fixtures/person.asn1 and fixtures/person.instance.json.
• fixtures/tagged-person.asn1 and fixtures/tagged-person.instance.json.
• fixtures/binary-inputs.asn1 and fixtures/binary-inputs.instance.json.
• fixtures/defaults-and-enumerated.asn1 and fixtures/defaults-and-enumerated.instance.json.
• fixtures/minimal-tbs-certificate.asn1 and certificate instance variants.
• fixtures/minimal-csr.asn1 and fixtures/minimal-csr.instance.json.
• fixtures/minimal-crl.asn1 and CRL instance variants.
• fixtures/pki-components.asn1 and fixtures/pki-components.instance.json, which include the shared PKI component baseline plus the demo-only PkiBundle wrapper.

See Schema and Instance Model for supported syntax and input forms.