first commit

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

@@ -0,0 +1,52 @@
+# crypto-curve error codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`codes.ts` registers the stable error-code namespace for `@suaveplan/crypto-curve` with `defineCodes` from `@suaveplan/error`. Every error thrown by this package routes through one of these codes so consumers can write stable code-based dispatch and so observability backends see a finite tag set.
+
+The codes are namespaced under `CRYPTO.CURVE` to keep them disjoint from sibling crypto packages (`CRYPTO.CIPHER.*`, `CRYPTO.HASH.*`, `CRYPTO.KEYS.*`).
+
+## Features
+
+- `CRYPTO_CURVE_CODES` — frozen registry mapping symbolic names to wire codes.
+- `CryptoCurveCode` — string union of all wire codes for type-safe dispatch.
+- Adding a code requires editing this file and re-running typecheck — there is no runtime path that injects a code.
+
+## Usage: Basic Example
+
+```ts
+import { CRYPTO_CURVE_CODES, CryptoCurveError } from "@suaveplan/crypto-curve";
+
+throw new CryptoCurveError(
+    CRYPTO_CURVE_CODES.RECOVERY_BYTE_MISSING,
+    "error.crypto.curve.recovery-byte-missing",
+    { context: { signatureLength: 64 } }
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { CRYPTO_CURVE_CODES, type CryptoCurveCode } from "@suaveplan/crypto-curve";
+
+function isRecoverableError(code: CryptoCurveCode): boolean {
+    return (
+        code === CRYPTO_CURVE_CODES.RECOVERY_BYTE_MISSING ||
+        code === CRYPTO_CURVE_CODES.RECOVERY_BYTE_INVALID
+    );
+}
+```
+
+## API Reference
+
+- `CRYPTO_CURVE_CODES.RECOVERY_BYTE_MISSING: "CRYPTO.CURVE.RECOVERY_BYTE_MISSING"` — thrown when `recoverPublicKey` receives a 64-byte signature without a recovery byte.
+- `CRYPTO_CURVE_CODES.RECOVERY_BYTE_INVALID: "CRYPTO.CURVE.RECOVERY_BYTE_INVALID"` — thrown when the recovery byte is not in `{0, 1}` (some libraries also emit `2` and `3` for compressed-form recovery, which are explicitly rejected here).
+- `CRYPTO_CURVE_CODES.RECOVERED_KEY_MISMATCH: "CRYPTO.CURVE.RECOVERED_KEY_MISMATCH"` — reserved for callers that need to surface the comparison-failure error rather than receiving `false` from `verifyWithRecovery`. Today the public API does not throw this code (it returns `false` instead) but it is registered for future use.
+- `CryptoCurveCode` — type alias of the union of all values above.
+
+## Implementation Notes
+
+The codes are **stable wire identifiers** — once shipped they cannot be renamed or removed. Adding a new code is permitted; rename-or-delete requires a new spec change with a deprecation cycle. The codes use `SCREAMING_SNAKE_CASE` to match the suaveplan-wide convention; they include the package prefix to disambiguate when multiple packages route through a shared OTel exporter or log aggregator.