Initial Commit

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

@@ -0,0 +1,81 @@
+# BROWSER_CRYPTO_CODES
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## 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
+
+```typescript
+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
+
+```typescript
+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`
+
+```typescript
+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`
+
+```typescript
+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.