Errors

Error taxonomy for the toolkit. Every error the library throws extends PkiError, so a consumer needs a single err instanceof pki.errors.PkiError check instead of sniffing per- module boolean flags, and every error carries a stable shape: { name, code, message, permanent, isPkiError: true }.

code is a stable, greppable domain/reason string (asn1/indefinite-length, x509/not-a-certificate): safe to switch on and safe to log. Because every failure here is a deterministic verdict on the bytes in hand (a malformed length, an unknown OID shape, a truncated certificate), errors are permanent: true. The same input will never parse on retry.

pki.errors.PkiError

since 0.1.0 stable
new PkiError(message, code)

Base class every toolkit error extends. Provides the unified instanceof check plus the { name, code, isPkiError } shape. A supplied code must be a domain/reason string (lowercase alphanumerics and dashes); the construction throws a TypeError otherwise, which catches an argument-order swap with the defineClass subclasses' (code, message) convention at the call site instead of shipping prose into a code-switching consumer.

Example

var bytes = Buffer.from([0x30, 0x80]);   // indefinite length -- not valid DER
try { pki.asn1.decode(bytes); }
catch (e) {
  if (e instanceof pki.errors.PkiError) console.error(e.code);
}

References

  • spec internal (design: error taxonomy base class)

pki.errors.defineClass

since 0.1.0 stable
pki.errors.defineClass(name, opts?) -> constructor

Factory that produces a PkiError subclass with the standard shape -- eliminating the per-domain boilerplate. The returned constructor takes (code, message), stamps name, sets an is<Name> flag, and exposes a .factory static for the common var _err = XxxError.factory shape. The code must be a domain/reason string (the base-class contract); without withCause, a third constructor argument throws a TypeError instead of silently discarding a cause the caller meant to thread.

Options

withCause:  boolean,  // default false; constructor becomes (code, message, cause)

Example

// throws: my/bad-input -- raising the new error type IS what this shows
var MyError = pki.errors.defineClass("MyError");
throw new MyError("my/bad-input", "explanation");

References

  • spec internal (design: error-class factory)