micro509/verify

Canonical advanced verification domain surface. Owns chain validation, service identity, policy, and name-constraint APIs.

DnsServiceIdentityInput

DNS hostname reference identifier.

interface DnsServiceIdentityInput {
	readonly type: dns;
	readonly value: string;
	readonly allowCommonNameFallback?: boolean;
}

Properties

• readonly type: dns — Discriminant for DNS hostname matching.
• readonly value: string — The hostname to match (e.g. "mail.example.com"). Wildcard labels in the certificate are handled internally.
• readonly allowCommonNameFallback?: boolean — When true, falls back to the subject CN if the SAN extension has no dns/uri/srv entries. Suppressed when any supported SAN type is present.

IpServiceIdentityInput

IP address reference identifier.

interface IpServiceIdentityInput {
	readonly type: ip;
	readonly value: string;
}

Properties

• readonly type: ip — Discriminant for IP address matching.
• readonly value: string — IPv4 or IPv6 address string. Normalized before comparison.

MatchServiceIdentityErrorCode

Discriminant codes for identity-matching failures.

type MatchServiceIdentityErrorCode = subject_alt_name_mismatch | common_name_fallback_suppressed | service_identity_mismatch | unsupported_service_identity_type

MatchServiceIdentityFailure

A failed identity-matching attempt.

interface MatchServiceIdentityFailure extends Micro509Error<MatchServiceIdentityErrorCode, MatchServiceIdentityFailureDetails> {
	readonly ok: false;
}

Properties

• readonly ok: false — Always false for failures.

MatchServiceIdentityFailureDetails

Diagnostic context attached to an identity-matching failure.

interface MatchServiceIdentityFailureDetails {
	readonly subjectCommonName?: string;
	readonly expected?: string;
	readonly actual?: string;
	readonly presentedIdentifierTypes?: readonly (dns | uri | srv)[];
	readonly commonNameFallbackReason?: disabled | suppressed_by_presented_identifier | common_name_missing | common_name_mismatch;
}

Properties

• readonly subjectCommonName?: string — CN of the certificate that was being matched, if present.
• readonly expected?: string — The reference identifier the caller asked to verify.
• readonly actual?: string — Comma-joined presented identifiers (from SAN) that were compared.
• readonly presentedIdentifierTypes?: readonly (dns | uri | srv)[] — SAN types that were present, relevant to CN-fallback suppression logic.
• readonly commonNameFallbackReason?: disabled | suppressed_by_presented_identifier | common_name_missing | common_name_mismatch — Explains why CN fallback was not used or failed.

MatchServiceIdentityFailureResult

Failure branch of MatchServiceIdentityResult with structured error details.

type MatchServiceIdentityFailureResult = ErrorResult<MatchServiceIdentityErrorCode, MatchServiceIdentityFailureDetails, MatchServiceIdentityFailure>

MatchServiceIdentityInput

Input for matchServiceIdentity.

interface MatchServiceIdentityInput {
	readonly certificate: ParsedCertificate;
	readonly serviceIdentity: ServiceIdentityInput;
}

Properties

• readonly certificate: ParsedCertificate — The parsed leaf certificate to check.
• readonly serviceIdentity: ServiceIdentityInput — The reference identifier the client wants to verify.

MatchServiceIdentityResult

Result of matching a reference identifier against a certificate's presented identifiers.

type MatchServiceIdentityResult = MatchServiceIdentitySuccess | MatchServiceIdentityFailureResult

MatchServiceIdentitySuccess

A successful identity match (the certificate covers the requested name).

interface MatchServiceIdentitySuccess {
	readonly ok: true;
	readonly value: undefined;
}

Properties

• readonly ok: true — Always true for success.
• readonly value: undefined — No payload on success — the match itself is the signal.

ServiceIdentityInput

Discriminated union of all supported reference identifier types.

type ServiceIdentityInput = DnsServiceIdentityInput | IpServiceIdentityInput | UriServiceIdentityInput | SrvServiceIdentityInput

ServiceIdentityType

The type discriminant values of ServiceIdentityInput.

type ServiceIdentityType = ServiceIdentityInput[type]

SrvServiceIdentityInput

SRV-ID reference identifier (RFC 4985).

interface SrvServiceIdentityInput {
	readonly type: srv;
	readonly value: string;
}

Properties

• readonly type: srv — Discriminant for SRV-ID matching.
• readonly value: string — SRV name in _service.domain form (e.g. "_imap.example.com").

UriServiceIdentityInput

URI-ID reference identifier (RFC 6125 §6.5). Scheme and host are matched.

interface UriServiceIdentityInput {
	readonly type: uri;
	readonly value: string;
}

Properties

• readonly type: uri — Discriminant for URI-ID matching.
• readonly value: string — Full URI whose scheme and reg-name will be compared.

matchCertificateServiceIdentity

Compares a reference identifier against a certificate's SAN entries.

Supports DNS (with wildcard matching), IP, URI-ID, and SRV-ID. For DNS, optionally falls back to subject CN when no SAN of a supported type is present.

function matchCertificateServiceIdentity(
	rawCertificate: ParsedCertificate,
	serviceIdentity: ServiceIdentityInput,
): MatchServiceIdentityResult

Parameters

• rawCertificate: ParsedCertificate
• serviceIdentity: ServiceIdentityInput

Examples

const result = matchCertificateServiceIdentity(parsed, {
  type: 'ip',
  value: '192.168.1.1',
});

const result = matchCertificateServiceIdentity(parsed, {
  type: 'dns',
  value: 'mail.example.com',
  allowCommonNameFallback: true,
});

matchServiceIdentity

Checks whether a certificate covers the requested service identity.

Delegates to matchCertificateServiceIdentity — this overload accepts a single options object.

function matchServiceIdentity(
	input: MatchServiceIdentityInput,
): MatchServiceIdentityResult

Parameters

• input: MatchServiceIdentityInput

Examples

const result = matchServiceIdentity({
  certificate: parsed,
  serviceIdentity: { type: 'dns', value: 'example.com' },
});
if (!result.ok) console.error(result.error.message);

InitialNameConstraintsInput

Input for createNameConstraintValidationState.

Seeds the name-constraint engine with trust-anchor-level subtree restrictions that apply before any certificate in the chain is processed.

interface InitialNameConstraintsInput {
	readonly permittedSubtrees?: readonly GeneralSubtree[];
	readonly excludedSubtrees?: readonly GeneralSubtree[];
}

Properties

• readonly permittedSubtrees?: readonly GeneralSubtree[] — Subtrees within which all subsequent subject names must fall. Default: unconstrained.
• readonly excludedSubtrees?: readonly GeneralSubtree[] — Subtrees that no subsequent subject name may fall within. Default: none.

ConstrainedPolicy

One policy OID that survives RFC 5280 / RFC 9618 processing.

interface ConstrainedPolicy {
	readonly policyIdentifier: string;
	readonly policyQualifiers?: readonly PolicyQualifierInfo[];
}

Properties

• readonly policyIdentifier: string — Dotted-decimal OID of the surviving policy.
• readonly policyQualifiers?: readonly PolicyQualifierInfo[] — Qualifier info (CPS URIs, user notices) attached to this policy, if any.

PolicyValidationInput

Input for the policy-validation engine.

All fields are optional — omitted values produce the most permissive behavior (accept any policy, allow mappings, allow anyPolicy).

interface PolicyValidationInput {
	readonly initialPolicySet?: readonly string[] | any;
	readonly requireExplicitPolicy?: boolean;
	readonly inhibitPolicyMapping?: boolean;
	readonly inhibitAnyPolicy?: boolean;
}

Properties

• readonly initialPolicySet?: readonly string``[] | any — OIDs the relying party considers acceptable, or 'any' to accept whatever the chain asserts. Default: 'any'.
• readonly requireExplicitPolicy?: boolean — When true, the chain must assert at least one acceptable policy. Default: false.
• readonly inhibitPolicyMapping?: boolean — When true, policy mappings in CA certificates are ignored. Default: false.
• readonly inhibitAnyPolicy?: boolean — When true, the anyPolicy OID is not treated as matching all policies. Default: false.

PolicyValidationOutcome

Final policy outputs exposed by successful path-validation APIs.

interface PolicyValidationOutcome {
	readonly authorityConstrainedPolicies: readonly ConstrainedPolicy[];
	readonly userConstrainedPolicies: readonly ConstrainedPolicy[];
}

Properties

• readonly authorityConstrainedPolicies: readonly ConstrainedPolicy[] — Policies valid under the authority's (CA chain) constraints alone.
• readonly userConstrainedPolicies: readonly ConstrainedPolicy[] — Policies that also satisfy the caller's PolicyValidationInput.initialPolicySet.

BuildCandidatePathInput

Input for buildCandidatePath.

interface BuildCandidatePathInput {
	readonly leaf: CertificateSource;
	readonly intermediates?: readonly CertificateSource[];
	readonly roots: readonly CertificateSource[];
	readonly trustAnchors?: readonly TrustAnchor[];
	readonly at?: Date;
}

Properties

• readonly leaf: CertificateSource — End-entity certificate to verify.
• readonly intermediates?: readonly CertificateSource[] — Intermediate CA certificates available for path building. Order does not matter.
• readonly roots: readonly CertificateSource[] — Trusted root CA certificates. At least one root or trust anchor must be supplied.
• readonly trustAnchors?: readonly TrustAnchor[] — Bare trust anchors to try when no root certificate matches.
• readonly at?: Date — Validation time. Defaults to new Date().

BuildCandidatePathResult

Result of buildCandidatePath. On success, contains the CandidatePath.

type BuildCandidatePathResult = {
  readonly ok: true;
  readonly value: CandidatePath
} | IndexedErrorResult<VerifyErrorCode, VerifyFailureDetails, VerifyChainFailure>

CandidatePath

A signature-verified certification path from leaf to root, before constraint validation.

interface CandidatePath {
	readonly leaf: ParsedCertificate;
	readonly chain: readonly ParsedCertificate[];
	readonly root: ParsedCertificate;
}

Properties

• readonly leaf: ParsedCertificate — Parsed end-entity certificate.
• readonly chain: readonly ParsedCertificate[] — Full chain in leaf-to-root order (includes both leaf and root).
• readonly root: ParsedCertificate — Trusted root that terminates the path.

CertificateSource

PEM string or DER bytes for a certificate. PEM may contain multiple blocks.

type CertificateSource = string | Uint8Array

ChainRevocationInput

Input for chain-level revocation checking in verifyCertificateChain.

interface ChainRevocationInput {
	readonly crls?: readonly CrlSource[];
	readonly ocspResponses?: readonly (string | Uint8Array)[];
	readonly extraCertificates?: readonly RevocationCertificateSource[];
	readonly trustedOcspResponders?: readonly RevocationCertificateSource[];
	readonly policy?: RevocationPolicy;
}

Properties

• readonly crls?: readonly CrlSource[] — CRLs to evaluate.
• readonly ocspResponses?: readonly (string | Uint8Array)[] — OCSP responses to evaluate (PEM strings or DER bytes).
• readonly extraCertificates?: readonly RevocationCertificateSource[] — Extra certs for indirect CRL issuers / delegated OCSP responders.
• readonly trustedOcspResponders?: readonly RevocationCertificateSource[] — Explicitly trusted OCSP responder certificates (RFC 6960 §4.2.2.2 criterion 1).
• readonly policy?: RevocationPolicy — Revocation policy.

CsrSource

PEM string or DER bytes for a certificate signing request.

type CsrSource = string | Uint8Array

EkuCheckFailure

Failure from checkExtendedKeyUsage with the chain index of the certificate that failed.

interface EkuCheckFailure extends Micro509Error<leaf_eku_missing | intermediate_eku_constraint> {
	readonly ok: false;
	readonly index: number;
}

Properties

• readonly ok: false — Always false for failures.
• readonly index: number — Zero-based index into the chain of the certificate that lacks the required EKU.

EkuCheckPurpose

Extended key usage purpose checked by checkExtendedKeyUsage.

type EkuCheckPurpose = serverAuth | clientAuth | codeSigning | emailProtection | timeStamping | ocspSigning

EkuCheckResult

Result of checkExtendedKeyUsage. Success carries no value; failure identifies the offending certificate.

type EkuCheckResult = {
  readonly ok: true;
  readonly value: undefined
} | IndexedErrorResult<leaf_eku_missing | intermediate_eku_constraint, Record<never, never>, EkuCheckFailure>

TrustAnchor

Bare trust anchor — subject identity and public key material without a full certificate. Used when the root CA certificate is unavailable but its key is known. Build from a certificate with trustAnchorFromCertificate.

interface TrustAnchor {
	readonly subject: ParsedName;
	readonly subjectPublicKeyInfoDer: Uint8Array;
	readonly publicKeyAlgorithmOid: string;
	readonly publicKeyParametersOid?: string;
	readonly subjectKeyIdentifier?: string;
}

Properties

• readonly subject: ParsedName — Parsed subject distinguished name. Used for semantic issuer matching (RFC 5280 §7.1).
• readonly subjectPublicKeyInfoDer: Uint8Array — DER-encoded SubjectPublicKeyInfo used to verify signatures from this anchor.
• readonly publicKeyAlgorithmOid: string — OID of the public key algorithm (e.g. 1.2.840.10045.2.1 for EC).
• readonly publicKeyParametersOid?: string — OID of the key parameters, when algorithm-specific (e.g. named curve OID for EC).
• readonly subjectKeyIdentifier?: string — Hex-encoded subject key identifier for AKI matching.

ValidateCandidatePathInput

Input for validateCandidatePath.

interface ValidateCandidatePathInput extends PolicyValidationInput, InitialNameConstraintsInput {
	readonly policy?: PolicyValidationInput;
	readonly nameConstraints?: InitialNameConstraintsInput;
	readonly chain: readonly ParsedCertificate[];
	readonly at?: Date;
	readonly purpose?: VerifyPurpose;
	readonly allowSelfSignedLeaf?: boolean;
}

Properties

• readonly policy?: PolicyValidationInput — Nested policy validation overrides (takes precedence over flat fields).
• readonly nameConstraints?: InitialNameConstraintsInput — Nested name constraint overrides (takes precedence over flat fields).
• readonly chain: readonly ParsedCertificate[] — Pre-built certificate chain in leaf-to-root order.
• readonly at?: Date — Validation time. Defaults to new Date().
• readonly purpose?: VerifyPurpose — Leaf purpose constraint to enforce.
• readonly allowSelfSignedLeaf?: boolean — When true, allows a self-signed leaf that is also the root. Defaults to false.

ValidateCandidatePathResult

Result of validateCandidatePath.

type ValidateCandidatePathResult = {
  readonly ok: true;
  readonly value: ValidateCandidatePathSuccess
} | IndexedErrorResult<VerifyErrorCode, VerifyFailureDetails, VerifyChainFailure>

ValidateCandidatePathSuccess

Success payload from validateCandidatePath.

interface ValidateCandidatePathSuccess {
	readonly policyValidation: PolicyValidationOutcome;
}

Properties

• readonly policyValidation: PolicyValidationOutcome — Final RFC 9618-constrained policy outputs for this validated path.

ValidateForCaInput

Input for validateForCa. Enforces basicConstraints.ca on the leaf.

interface ValidateForCaInput extends BuildCandidatePathInput, PolicyValidationInput, InitialNameConstraintsInput {
	readonly policy?: PolicyValidationInput;
	readonly nameConstraints?: InitialNameConstraintsInput;
}

Properties

• readonly policy?: PolicyValidationInput — Nested policy validation overrides.
• readonly nameConstraints?: InitialNameConstraintsInput — Nested name constraint overrides.

ValidateForCodeSigningInput

Input for validateForCodeSigning. Enforces codeSigning EKU.

interface ValidateForCodeSigningInput extends BuildCandidatePathInput, PolicyValidationInput, InitialNameConstraintsInput {
	readonly policy?: PolicyValidationInput;
	readonly nameConstraints?: InitialNameConstraintsInput;
}

Properties

• readonly policy?: PolicyValidationInput — Nested policy validation overrides.
• readonly nameConstraints?: InitialNameConstraintsInput — Nested name constraint overrides.

ValidateForTlsClientInput

Input for validateForTlsClient. Enforces clientAuth EKU.

interface ValidateForTlsClientInput extends BuildCandidatePathInput, PolicyValidationInput, InitialNameConstraintsInput {
	readonly policy?: PolicyValidationInput;
	readonly nameConstraints?: InitialNameConstraintsInput;
}

Properties

• readonly policy?: PolicyValidationInput — Nested policy validation overrides.
• readonly nameConstraints?: InitialNameConstraintsInput — Nested name constraint overrides.

ValidateForTlsServerInput

Input for validateForTlsServer. Enforces serverAuth EKU and optional DNS/IP identity matching.

interface ValidateForTlsServerInput extends BuildCandidatePathInput, PolicyValidationInput, InitialNameConstraintsInput {
	readonly policy?: PolicyValidationInput;
	readonly nameConstraints?: InitialNameConstraintsInput;
	readonly leaf: CertificateSource;
	readonly intermediates?: readonly CertificateSource[];
	readonly roots: readonly CertificateSource[];
	readonly trustAnchors?: readonly TrustAnchor[];
	readonly at?: Date;
	readonly serviceIdentity?: ServiceIdentityInput;
}

Properties

• readonly policy?: PolicyValidationInput — Nested policy validation overrides.
• readonly nameConstraints?: InitialNameConstraintsInput — Nested name constraint overrides.
• readonly leaf: CertificateSource — End-entity certificate to verify.
• readonly intermediates?: readonly CertificateSource[] — Intermediate CA certificates.
• readonly roots: readonly CertificateSource[] — Trusted root CA certificates.
• readonly trustAnchors?: readonly TrustAnchor[] — Bare trust anchors.
• readonly at?: Date — Validation time. Defaults to new Date().
• readonly serviceIdentity?: ServiceIdentityInput — DNS/IP identity to match against the leaf's SAN.

VerifiedCertificateChain

Fully verified certificate chain returned on success from verifyCertificateChain.

interface VerifiedCertificateChain {
	readonly leaf: ParsedCertificate;
	readonly chain: readonly ParsedCertificate[];
	readonly root: ParsedCertificate;
	readonly policyValidation: PolicyValidationOutcome;
}

Properties

• readonly leaf: ParsedCertificate — Parsed end-entity certificate.
• readonly chain: readonly ParsedCertificate[] — Full chain in leaf-to-root order.
• readonly root: ParsedCertificate — Trusted root that terminates the path.
• readonly policyValidation: PolicyValidationOutcome — Final RFC 5280 §6 / RFC 9618 constrained policy outputs for this validated path.

VerifyCertificateChainInput

Input for verifyCertificateChain. Combines path-building, validation, and identity options.

interface VerifyCertificateChainInput extends PolicyValidationInput, InitialNameConstraintsInput {
	readonly policy?: PolicyValidationInput;
	readonly nameConstraints?: InitialNameConstraintsInput;
	readonly leaf: CertificateSource;
	readonly intermediates?: readonly CertificateSource[];
	readonly roots: readonly CertificateSource[];
	readonly trustAnchors?: readonly TrustAnchor[];
	readonly at?: Date;
	readonly purpose?: VerifyPurpose;
	readonly serviceIdentity?: ServiceIdentityInput;
	readonly allowSelfSignedLeaf?: boolean;
	readonly revocation?: ChainRevocationInput;
}

Properties

• readonly policy?: PolicyValidationInput — Nested policy validation overrides.
• readonly nameConstraints?: InitialNameConstraintsInput — Nested name constraint overrides.
• readonly leaf: CertificateSource — End-entity certificate to verify.
• readonly intermediates?: readonly CertificateSource[] — Intermediate CA certificates available for path building.
• readonly roots: readonly CertificateSource[] — Trusted root CA certificates.
• readonly trustAnchors?: readonly TrustAnchor[] — Bare trust anchors to try when no root certificate matches.
• readonly at?: Date — Validation time. Defaults to new Date().
• readonly purpose?: VerifyPurpose — Leaf purpose constraint to enforce during validation.
• readonly serviceIdentity?: ServiceIdentityInput — DNS/IP/URI/SRV identity to match against the leaf's SAN.
• readonly allowSelfSignedLeaf?: boolean — When true, allows a self-signed leaf. Defaults to false.
• readonly revocation?: ChainRevocationInput — Optional revocation checking.

VerifyChainFailure

A chain verification failure with its error code, human message, chain index, and diagnostic details.

interface VerifyChainFailure extends IndexedMicro509Error<VerifyErrorCode, VerifyFailureDetails> {
	readonly ok: false;
}

Properties

• readonly ok: false — Always false for failures.

VerifyChainResult

Result of verifyCertificateChain. On success, contains the VerifiedCertificateChain.

type VerifyChainResult = {
  readonly ok: true;
  readonly value: VerifiedCertificateChain
} | IndexedErrorResult<VerifyErrorCode, VerifyFailureDetails, VerifyChainFailure>

VerifyErrorCode

See the doc comment above VERIFY_ERROR_CODES for the meaning of each code.

type VerifyErrorCode = (typeof VERIFY_ERROR_CODES)[number]

VerifyFailureDetails

Diagnostic context attached to every VerifyChainFailure. All fields are optional; presence depends on the error code.

interface VerifyFailureDetails {
	readonly subjectCommonName?: string;
	readonly issuerCommonName?: string;
	readonly expected?: string;
	readonly actual?: string;
	readonly chainCommonNames?: readonly string[];
	readonly presentedIdentifierTypes?: readonly (dns | uri | srv)[];
	readonly commonNameFallbackReason?: disabled | suppressed_by_presented_identifier | common_name_missing | common_name_mismatch;
}

Properties

• readonly subjectCommonName?: string — CN of the certificate that triggered the failure.
• readonly issuerCommonName?: string — CN of the issuer of the offending certificate.
• readonly expected?: string — The value the verifier expected (e.g. a validity window bound or SKI).
• readonly actual?: string — The value actually found.
• readonly chainCommonNames?: readonly string``[] — CNs of every certificate in the chain, leaf-first. Present on no_trusted_root.
• readonly presentedIdentifierTypes?: readonly (dns | uri | srv)[] — SAN identifier types the leaf actually presents. Set on identity-match failures.
• readonly commonNameFallbackReason?: disabled | suppressed_by_presented_identifier | common_name_missing | common_name_mismatch — Why the CN-fallback path was not taken. Set on common_name_fallback_suppressed.

VerifyPurpose

High-level purpose applied during path validation to enforce leaf constraints.

type VerifyPurpose = serverAuth | clientAuth | ca

VerifyRequestFailure

Failure from verifyCertificateSigningRequest.

interface VerifyRequestFailure extends Micro509Error<signature_invalid | unsupported_signature_algorithm_parameters, VerifyFailureDetails> {
	readonly ok: false;
}

Properties

• readonly ok: false — Always false for failures.

VerifyRequestResult

Result of verifyCertificateSigningRequest. On success, contains the parsed CSR.

type VerifyRequestResult = {
  readonly ok: true;
  readonly value: ParsedCertificateSigningRequest
} | ErrorResult<signature_invalid | unsupported_signature_algorithm_parameters, VerifyFailureDetails, VerifyRequestFailure>

buildCandidatePath

Builds a signature-verified path from a leaf certificate to a trusted root.

Parses the supplied certificates, walks the issuer chain, signature-checks each link, and returns the first valid path. Does not enforce time, constraints, or leaf purpose — call validateCandidatePath or use the all-in-one verifyCertificateChain for full validation.

function buildCandidatePath(
	input: BuildCandidatePathInput,
): Promise<BuildCandidatePathResult>

Parameters

• input: BuildCandidatePathInput

Examples

import { buildCandidatePath } from 'micro509';

const result = await buildCandidatePath({
  leaf: leafPem,
  intermediates: [intermediatePem],
  roots: [rootPem],
});
if (result.ok) {
  console.log('path length:', result.value.chain.length);
}

checkExtendedKeyUsage

Standalone EKU check against a verified certificate chain. Validates that the leaf has the requested purpose and that intermediate CA EKU constraints (if present) permit it.

function checkExtendedKeyUsage(
	chain: readonly ParsedCertificate[],
	purpose: EkuCheckPurpose,
): EkuCheckResult

Parameters

• chain: readonly ParsedCertificate[]
• purpose: EkuCheckPurpose

Examples

import { checkExtendedKeyUsage } from 'micro509';

const result = checkExtendedKeyUsage(chain, 'serverAuth');
if (!result.ok) {
  console.error(result.error.code, result.error.message);
}

trustAnchorFromCertificate

Extracts a TrustAnchor from a parsed certificate, copying the subject, SPKI, and key identifiers.

function trustAnchorFromCertificate(
	certificate: ParsedCertificate,
): TrustAnchor

Parameters

• certificate: ParsedCertificate

VERIFY_ERROR_CODES

Discriminant for every failure a verify operation can produce.

• no_trusted_root — chain could not be anchored to any root or TrustAnchor.
• issuer_not_found — an intermediate's issuer was not in the candidate set.
• signature_invalid — a certificate's signature failed cryptographic verification.
• certificate_expired — a certificate's notBefore/notAfter window excludes the validation time.
• ca_required — an issuer lacks basicConstraints.ca = true.
• key_cert_sign_required — an issuer has keyUsage but omits keyCertSign.
• path_length_exceeded — the number of CA certificates below an issuer exceeds its pathLength.
• authority_key_identifier_mismatch — a certificate's AKI does not match the issuer's SKI.
• extended_key_usage_invalid — the leaf certificate lacks the required EKU for the requested purpose.
• subject_alt_name_mismatch — no SAN entry matches the requested service identity.
• common_name_fallback_suppressed — CN fallback was attempted but suppressed (SAN present or disabled).
• self_signed_leaf_not_allowed — the leaf is self-signed and allowSelfSignedLeaf was not set.
• unrecognized_critical_extension — a certificate contains a critical extension the verifier cannot process.
• intermediate_eku_constraint — an intermediate CA's EKU set does not include the required purpose.
• explicit_policy_required — requireExplicitPolicy was set but no acceptable policy was found.
• initial_policy_set_not_satisfied — the chain's policies do not intersect initialPolicySet.
• unsupported_initial_name_constraints — caller-supplied initial name constraints use unsupported or malformed forms.
• unsupported_name_constraints — a certificate's nameConstraints use an unsupported form.
• name_constraints_violated — a subject name violates a permitted/excluded subtree.
• unsupported_signature_algorithm_parameters — the signature algorithm uses unrecognized parameters.
• certificate_revoked — revocation evidence confirms a chain certificate is revoked.
• revocation_indeterminate — revocation status could not be determined under a hard-fail policy.

const VERIFY_ERROR_CODES: no_trusted_root | issuer_not_found | signature_invalid | certificate_expired | ca_required | key_cert_sign_required | path_length_exceeded | authority_key_identifier_mismatch | extended_key_usage_invalid | subject_alt_name_mismatch | common_name_fallback_suppressed | self_signed_leaf_not_allowed | unrecognized_critical_extension | intermediate_eku_constraint | explicit_policy_required | initial_policy_set_not_satisfied | unsupported_initial_name_constraints | unsupported_name_constraints | name_constraints_violated | unsupported_signature_algorithm_parameters | certificate_revoked | revocation_indeterminate[]

validateCandidatePath

Validates a pre-built certificate chain for time, constraints, policy, and optionally leaf purpose. Wrap the result of buildCandidatePath.

function validateCandidatePath(
	input: ValidateCandidatePathInput,
): Promise<ValidateCandidatePathResult>

Parameters

• input: ValidateCandidatePathInput

validateForCa

Validates a certificate chain for CA use: chain verification + basicConstraints.ca check on the leaf.

function validateForCa(
	input: ValidateForCaInput,
): Promise<VerifyChainResult>

Parameters

• input: ValidateForCaInput

Examples

import { validateForCa } from 'micro509';

const result = await validateForCa({
  leaf: intermediateCertPem,
  roots: [rootCaPem],
});

validateForCodeSigning

Validates a certificate chain for code signing: chain verification + codeSigning EKU (leaf + intermediate propagation).

function validateForCodeSigning(
	input: ValidateForCodeSigningInput,
): Promise<VerifyChainResult>

Parameters

• input: ValidateForCodeSigningInput

Examples

import { validateForCodeSigning } from 'micro509';

const result = await validateForCodeSigning({
  leaf: codeSigningCertPem,
  roots: [rootCaPem],
});

validateForTlsClient

Validates a certificate chain for TLS client use: chain verification + clientAuth EKU (leaf + intermediate propagation).

function validateForTlsClient(
	input: ValidateForTlsClientInput,
): Promise<VerifyChainResult>

Parameters

• input: ValidateForTlsClientInput

Examples

import { validateForTlsClient } from 'micro509';

const result = await validateForTlsClient({
  leaf: clientCertPem,
  roots: [rootCaPem],
});

validateForTlsServer

Validates a certificate chain for TLS server use: chain verification + serverAuth EKU (leaf + intermediate propagation)

• DNS/IP identity matching.

function validateForTlsServer(
	input: ValidateForTlsServerInput,
): Promise<VerifyChainResult>

Parameters

• input: ValidateForTlsServerInput

Examples

import { validateForTlsServer } from 'micro509';

const result = await validateForTlsServer({
  leaf: serverCertPem,
  roots: [rootCaPem],
  serviceIdentity: { type: 'dns', value: 'example.com' },
});
if (result.ok) {
  console.log('valid for', result.value.leaf.subject.values.commonName);
}

verifyCertificateChain

All-in-one certificate chain verification: builds a candidate path then validates time, constraints, policy, purpose, and optional service identity.

Equivalent to calling buildCandidatePath followed by validateCandidatePath (plus identity matching when configured).

function verifyCertificateChain(
	input: VerifyCertificateChainInput,
): Promise<VerifyChainResult>

Parameters

• input: VerifyCertificateChainInput

Examples

import { verifyCertificateChain } from 'micro509';

const result = await verifyCertificateChain({
  leaf: serverCertPem,
  intermediates: [intermediatePem],
  roots: [rootCaPem],
  purpose: 'serverAuth',
  serviceIdentity: { type: 'dns', value: 'example.com' },
});
if (!result.ok) {
  console.error(result.error.code, result.error.message);
}

verifyCertificateSigningRequest

Verifies the self-signature of a PKCS#10 certificate signing request.

Parses the CSR from PEM or DER, then checks that its signature is valid against its own embedded public key.

function verifyCertificateSigningRequest(
	input: CsrSource,
): Promise<VerifyRequestResult>

Parameters

• input: CsrSource

Examples

import { verifyCertificateSigningRequest } from 'micro509';

const result = await verifyCertificateSigningRequest(csrPem);
if (result.ok) {
  console.log('subject:', result.value.subject.values.commonName);
}