suaveplan/packages/security-stack/crypto/crypto-browser/src/errors/codes/codes.md

BROWSER_CRYPTO_CODES

(no submodules)

Purpose

codes.ts defines the complete set of stable error codes used throughout @suaveplan/crypto-browser. Each code is a namespaced string constant produced by defineCodes from @suaveplan/error, ensuring codes are unique within the "BROWSER_CRYPTO" namespace and that the BrowserCryptoCode union type is always in sync with the registered values at compile time. All WebCrypto-related failures in this package surface under one of these codes, allowing consumers to branch deterministically without parsing message strings.

Features

• Three codes covering the main WebCrypto failure domains: API unavailability, key generation, and general operation failures
• Generated via defineCodes("BROWSER_CRYPTO", [...]) which prefixes each entry and freezes the resulting object
• BrowserCryptoCode is derived as a typeof union for compile-time exhaustive narrowing
• No runtime dependencies beyond @suaveplan/error

Usage: Basic Example

import { BROWSER_CRYPTO_CODES } from "@suaveplan/crypto-browser/errors/codes";
import { BrowserCryptoError } from "@suaveplan/crypto-browser/errors/browser-crypto-error";

throw new BrowserCryptoError(
  BROWSER_CRYPTO_CODES["NOT_AVAILABLE"],
  "error.crypto-browser.not-available"
);

Usage: Advanced Example

import {
  BROWSER_CRYPTO_CODES,
  type BrowserCryptoCode,
} from "@suaveplan/crypto-browser/errors/codes";
import { BrowserCryptoError } from "@suaveplan/crypto-browser/errors/browser-crypto-error";

function handleBrowserCryptoError(err: BrowserCryptoError): string {
  switch (err.code as BrowserCryptoCode) {
    case BROWSER_CRYPTO_CODES["NOT_AVAILABLE"]:
      return "WebCrypto API is not available in this environment (requires HTTPS or localhost).";
    case BROWSER_CRYPTO_CODES["KEY.GENERATION_FAILED"]:
      return "Key generation failed — the requested algorithm may not be supported by this browser.";
    case BROWSER_CRYPTO_CODES["OPERATION.FAILED"]:
      return "Cryptographic operation failed — check key type, algorithm, and input size.";
    default:
      return "Unknown browser crypto error.";
  }
}

API Reference

BROWSER_CRYPTO_CODES

const BROWSER_CRYPTO_CODES: Readonly<Record<string, string>>

A frozen map from short code keys to their namespaced string values. All values are prefixed with "BROWSER_CRYPTO." by defineCodes.

Key	Namespaced value	When thrown
NOT_AVAILABLE	"BROWSER_CRYPTO.NOT_AVAILABLE"	globalThis.crypto.subtle is undefined or null
KEY.GENERATION_FAILED	"BROWSER_CRYPTO.KEY.GENERATION_FAILED"	SubtleCrypto.generateKey or importKey rejects
OPERATION.FAILED	"BROWSER_CRYPTO.OPERATION.FAILED"	Any SubtleCrypto operation (encrypt, decrypt, sign, verify, deriveBits, wrapKey, unwrapKey) rejects

BrowserCryptoCode

type BrowserCryptoCode =
  (typeof BROWSER_CRYPTO_CODES)[keyof typeof BROWSER_CRYPTO_CODES];

Union of all namespaced code strings. Use this type to annotate err.code when narrowing BrowserCryptoError in typed catch blocks.

Implementation Notes

defineCodes returns a plain frozen object and the BrowserCryptoCode type collapses to a string literal union. Adding a new entry to the array automatically widens the union without requiring any manual type maintenance.

OPERATION.FAILED intentionally covers a broad set of SubtleCrypto rejections rather than splitting each operation into its own code. The distinction between, say, a failed encrypt and a failed sign is captured in the structured context field on the thrown BrowserCryptoError rather than in the code itself, which keeps the code registry small and stable across algorithm additions.