CryptoVaultError

Purpose

CryptoVaultError is the umbrella error class for @suaveplan/crypto-vault. Every failure mode in the package — invalid BIP39 entropy, unsafe Argon2id parameters, SRP authentication failures, zeroized SecureBuffer access — is surfaced as a CryptoVaultError carrying a code from CRYPTO_VAULT_CODES. Extending SuaveplanError means the error participates in the project's wire format, OTel span events, redaction, and i18n infrastructure for free.

Features

Inherits structured code, context, timestamp, and traceId from SuaveplanError.
Code field is narrowed to the CryptoVaultCode union so switch (err.code) is exhaustive.
Tagged with a unique brand symbol so cross-realm instanceof checks (web workers, iframes) can be defended against via CryptoVaultError.is(value).
Public constructor — internal modules instantiate freely; consumers may also instantiate when re-throwing across boundaries.

Usage: Basic Example

import {
    CRYPTO_VAULT_CODES,
    CryptoVaultError,
} from "@suaveplan/crypto-vault/errors";

throw new CryptoVaultError(
    CRYPTO_VAULT_CODES["BIP39.INVALID_MNEMONIC"],
    "error.crypto-vault.bip39.invalid-mnemonic"
);

Usage: Advanced Example

import {
    CRYPTO_VAULT_CODES,
    CryptoVaultError,
} from "@suaveplan/crypto-vault/errors";

try {
    // ... call into crypto-vault ...
} catch (raw) {
    if (CryptoVaultError.is(raw)) {
        switch (raw.code) {
            case CRYPTO_VAULT_CODES["SRP.AUTHENTICATION_FAILED"]:
                return { kind: "auth-failed" } as const;
            case CRYPTO_VAULT_CODES["SECURE.ZEROIZED"]:
                return { kind: "vault-locked" } as const;
            default:
                throw raw;
        }
    }
    throw raw;
}

API Reference

`class CryptoVaultError extends SuaveplanError<CryptoVaultCode>`

Constructor

new CryptoVaultError(code, messageKey, options?)

code: CryptoVaultCode — fully-qualified registry code.
messageKey: string — i18n key resolved by @suaveplan/error's MessageResolver.
options?: SuaveplanErrorOptions — forwarded to SuaveplanError.

`static is(value: unknown): value is CryptoVaultError`

Returns true when value was constructed by this package. Combines instanceof with a brand-symbol identity check, defending against cross-realm prototype divergence.

Implementation Notes

The brand symbol is a unique symbol keyed off Symbol("@suaveplan/crypto-vault.error"); the symbol identity is not stable across realms by design — CryptoVaultError.is uses it as a same-realm assertion only. Cross-realm instances must be re-thrown by their owning realm before reaching this guard.
The constructor sets the brand field after super(...) so the assignment happens after the prototype chain is initialised.
The class is intentionally non-abstract. Internal callers throw it directly with a CRYPTO_VAULT_CODES.* value rather than maintaining one subclass per error reason.

3.0 KiB Raw Blame History