first commit

docs/security-stack/crypto/crypto-vault/src/errors/codes.md

@@ -0,0 +1,78 @@
+# crypto-vault — Error code registry
+
+## Purpose
+
+`codes.ts` is the canonical, frozen registry of every error code emitted by
+`@suaveplan/crypto-vault`. The registry exists so that consumers — vault
+orchestrators, sync layers, telemetry pipelines, audit log post-processors —
+can assert against a stable set of strings rather than parsing free-form
+messages. The registry is built with `defineCodes` from `@suaveplan/error`,
+which freezes the resulting record at module load and infers each code's
+literal type so `instanceof CryptoVaultError` can narrow `code` to the union.
+
+## Features
+
+- Frozen `CRYPTO_VAULT_CODES` record with `CRYPTOVAULT.<MODULE>.<REASON>`
+  namespacing.
+- `CryptoVaultCode` type union for exhaustive `switch` discrimination.
+- One canonical home for every failure mode the package can produce. Adding a
+  new code requires touching this file plus the production path that throws.
+
+## Usage: Basic Example
+
+```ts
+import {
+    CRYPTO_VAULT_CODES,
+    CryptoVaultError,
+} from "@suaveplan/crypto-vault/errors";
+
+throw new CryptoVaultError(
+    CRYPTO_VAULT_CODES["BIP39.INVALID_ENTROPY_LENGTH"],
+    "error.crypto-vault.bip39.invalid-entropy-length",
+    { context: { length: 7 } }
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { CryptoVaultError } from "@suaveplan/crypto-vault/errors";
+import type { CryptoVaultCode } from "@suaveplan/crypto-vault/errors";
+
+function describe(err: unknown): string {
+    if (!(err instanceof CryptoVaultError)) return "unknown error";
+    const code: CryptoVaultCode = err.code;
+    switch (code) {
+        case "CRYPTOVAULT.BIP39.INVALID_MNEMONIC":
+            return "Invalid recovery phrase";
+        case "CRYPTOVAULT.SRP.AUTHENTICATION_FAILED":
+            return "Wrong password — try again";
+        default:
+            return `Unhandled crypto-vault code: ${code}`;
+    }
+}
+```
+
+## API Reference
+
+### `CRYPTO_VAULT_CODES`
+
+A frozen `Record<string, string>` mapping each reason key (e.g.
+`BIP39.INVALID_ENTROPY_LENGTH`) to its fully-qualified code (e.g.
+`CRYPTOVAULT.BIP39.INVALID_ENTROPY_LENGTH`).
+
+### `CryptoVaultCode`
+
+Union of every string literal value held by `CRYPTO_VAULT_CODES`. Use as the
+generic parameter of `CryptoVaultError`.
+
+## Implementation Notes
+
+- The registry is intentionally append-only. Removing a code is a breaking
+  change for any consumer that asserts on it.
+- Codes are checked at runtime via the `defineCodes` factory — any duplicate
+  reason in the array would surface as the same key collapsing in the output
+  record.
+- Every code listed here must be thrown by at least one production path. The
+  spec-conformance test enumerates the registry and verifies the production
+  surface throws each code at least once.