Core API

Core API

The Core API is UI-independent and is available from both @pkistudio/asn1instancebuilder and @pkistudio/asn1instancebuilder/core.

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(document.typeName);
console.log(bytesToHex(document.der));

ASN.1 Definition Parser

Use parseAsn1Definition(source) to parse supported ASN.1 module text into an Asn1SchemaModule.

The parser targets a deliberately small Schema Model while the instance model and DER builder stabilize. It supports common primitives, constructed types, defined type references, low-form context-specific tags, tag defaults, named numbers, simple defaults, and selected PKI-oriented examples.

See Schema and Instance Model for the current supported syntax.

DER Builder

Use createInstance(schema, typeName, input) to create an InstanceDocument.

The returned document includes:

• moduleName: source schema module name.
• typeName: selected root ASN.1 type.
• der: generated DER bytes as a Uint8Array.

Use encodeValue(schema, type, value) when lower-level callers need to encode a specific resolved type. Use resolveDefinedType(schema, type) when working with Schema Model nodes that may reference named definitions.

Schema Diagnostics

Use validateSchemaModule(schema) before building DER from user-provided definitions.

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

const schema = parseAsn1Definition(source);
const diagnostics = validateSchemaModule(schema);

for (const diagnostic of diagnostics) {
  console.log(diagnostic.severity, diagnostic.message);
}

Schema diagnostics are structured and can report duplicate type names, unknown type references, duplicate field names, duplicate context-specific tags, unsupported tag numbers, and duplicate named numbers.

Instance Diagnostics

Use validateInstance(schema, typeName, input) to check instance JSON before generating DER.

import { validateInstance } from '@pkistudio/asn1instancebuilder';

const diagnostics = validateInstance(schema, 'Person', input);

for (const diagnostic of diagnostics) {
  console.log(diagnostic.severity, diagnostic.path, diagnostic.message);
}

Instance diagnostics include stable paths so browser or host UIs can highlight the relevant value. Diagnostics cover common OID, binary, time, CHOICE, field, and value shape errors.

Byte Helpers

The Core API includes helpers for simple byte conversion:

• bytesToHex(bytes): convert bytes to compact hexadecimal text.
• hexToBytes(text): parse hexadecimal text into bytes.

Binary ASN.1 values can also be supplied as instance JSON strings, number arrays, { hex }, { utf8 }, or { base64 } objects. See Schema and Instance Model.

OID Helpers

The package includes a small built-in PKI OID name table.

Use:

• builtInOidNames: built-in name-to-OID map.
• resolveObjectIdentifierName(schema, value): resolve dotted decimal OIDs, built-in names, or schema-provided oidNames.

Hosts can attach an oidNames map to an Asn1SchemaModule to add application-specific names.

Shared PKI Definitions

The Core API exports pkiComponentDefinition, a reusable ASN.1 definition string for common PKI component types. It is intended to keep PkiStudio packages aligned on a shared baseline for types such as AlgorithmIdentifier, Name, SubjectPublicKeyInfo, Extension, TBSCertificate, Certificate, CertificationRequest, PrivateKeyInfo, and ContentInfo.

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

const schema = parseAsn1Definition(pkiComponentDefinition);

The browser app still keeps demo-specific wrappers such as PkiBundle in its bundled fixtures. Those wrappers are useful for NamedObjects samples but are not part of the shared PKI baseline.

PkiStudioJS Adapter Helper

Use parseGeneratedDer(bytes) when a host wants to confirm that PkiStudioJS core can parse generated DER.

The browser app uses this after successful DER creation so the API Log can report generated DER parsing results.

Example Data

The Core API exports lightweight examples:

• exampleDefinition.
• exampleInput.
• exampleSchema.

These are useful for demos, tests, and host integration smoke checks.

Important Exported Types

Important exported types include:

• Asn1SchemaModule.
• Asn1TypeDefinition.
• Asn1Type.
• Asn1Field.
• Asn1Tag.
• Asn1TagDefault.
• Asn1NamedNumber.
• ByteInput.
• BitStringInput.
• ChoiceInput.
• InstanceDocument.
• SchemaDiagnostic.
• InstanceDiagnostic.

These types are designed to stay independent from DOM APIs, VS Code APIs, file dialogs, and host-specific persistence.