Core API

Core API

The Core API is exposed from @pkistudio/asn1defsifter and @pkistudio/asn1defsifter/core.

import {
  createPkiComponentCorpus,
  extractDerFeatures,
  findAsn1Candidates,
  parseInputToTlvNodes
} from '@pkistudio/asn1defsifter';

const [node] = await parseInputToTlvNodes('300d06092a864886f70d01010b0500', { format: 'hex' });
const features = extractDerFeatures(node);
const corpus = createPkiComponentCorpus();
const candidates = findAsn1Candidates(node, { schemaCorpus: corpus });

console.log(features.tagName);
console.log(candidates[0]?.typeName);

Parsing Inputs

Use parseInputToTlvNodes(input, options?) to turn supported input into neutral TlvNode objects through the PkiStudioJS adapter.

Common inputs include:

• DER bytes as Uint8Array.
• HEX text with format: 'hex'.
• PEM, BER, Base64, and other formats supported by the PkiStudioJS adapter.

Use pkistudioNodeToTlvNode() when a host already has a PkiStudioJS node and wants to cross the adapter boundary explicitly.

Feature Extraction

Use extractDerFeatures(node) to collect resolver features such as:

• tag class, tag number, tag name, constructed state,
• child count and child tag sequence,
• primitive value kind,
• OID values and primitive value hints,
• structural facts used by candidate matching.

Feature extraction is deterministic and does not require a schema corpus.

Schema Corpus Helpers

Use createSchemaCorpus() when constructing a custom corpus from schema modules or candidate targets.

Use parseAsn1DefinitionCorpus(source) when starting from ASN.1 definition text parsed through ASN.1 Instance Builder's schema model.

Use listSchemaTargets(corpus) to inspect candidate target names available in a corpus.

Candidate Matching

Use findAsn1Candidates(node, options) to rank ASN.1 schema targets for one TLV node.

Important options include:

• schemaCorpus: required unless using a higher-level PKI report helper.
• maxResults: maximum candidate count.
• minScore: suppress weak candidates from the returned list.
• includeTypes: only consider listed type names.
• excludeTypes: omit listed type names.

includeTypes and excludeTypes accept local names such as SubjectPublicKeyInfo or qualified names such as PkiComponents.SubjectPublicKeyInfo.

PKI Helpers

Use createPkiComponentCorpus() for the built-in PKI-oriented schema corpus. The helper parses the shared pkiComponentDefinition supplied by @pkistudio/asn1instancebuilder, while keeping the ASN.1 Definition Sifter API stable for callers.

Use getPkiProfileTypeNames() to select profiles:

import { getPkiProfileTypeNames } from '@pkistudio/asn1defsifter';

const includeTypes = getPkiProfileTypeNames(['x509', 'pkcs8']);

Available profile groups include x509, pkcs10, pkcs8, cms, and shared components.

Report APIs

Use createCandidateReport() when callers want parsing, feature extraction, candidate ranking, diagnostics, ambiguities, and document hypotheses in one JSON-friendly result.

Use createCandidateReportFromNodes() when the host already has neutral TLV nodes.

Use createPkiCandidateReport() and createPkiCandidateReportFromNodes() for the built-in PKI corpus and profile filtering.

See Candidate Reports for the report shape.

Annotated Trees

Use identifyAsn1Document() and createAnnotatedTree() when turning candidate matches into schema-aware tree hypotheses.

Annotated tree entries can connect:

• TLV tag names,
• schema paths,
• inferred field names,
• referenced ASN.1 type names,
• nested children.

Exported Types

Important exported types include:

• TlvNode and TlvFeatures.
• SchemaCorpus, SchemaCandidateTarget, and ASN.1 schema model aliases.
• Candidate, Diagnostic, EvidenceItem, MatchedPath, and DocumentHypothesis.
• CandidateReport, CandidateReportRoot, CandidateReportSubtree, and CandidateReportSummary.

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