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, Load -> Definition Bundle, a local ASN.1/Schema file, or the clipboard.
2. Select a defined type in the Instance Input pane.
3. Edit the generated sample instance input in the Form view, or switch to JSON to edit the raw instance JSON directly.
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. Load -> Definition Bundle loads portable .definition-bundle.json or .bundle.json files that can include schema data, selectable entries, sample/default input, and optional UI Profiles.

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 enter this value in the JSON view, or use the Form view to set the same fields:

{
  "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.

The Form and JSON views edit the same underlying instance value. Form edits are serialized back to instance JSON, and the JSON view remains the canonical interchange/debugging representation.

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.