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.

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

@@ -0,0 +1,63 @@
+# CryptoCurveError
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`crypto-curve-error.ts` defines the `CryptoCurveError` class used by every error path in `@suaveplan/crypto-curve`. It is a thin alias of `SuaveplanError<CryptoCurveCode>` from `@suaveplan/error` — this means it inherits the full error substrate (cause-chain traversal, OTel span events, structured-logger redaction, i18n message-key resolution, and the wire-format JSON / binary serialiser) without any per-package re-implementation.
+
+Routing every thrown error through this single class is what allows downstream consumers to write `instanceof CryptoCurveError` for package-level dispatch and `error.code === CRYPTO_CURVE_CODES.X` for code-level dispatch, simultaneously, with full type narrowing.
+
+## Features
+
+- Extends `SuaveplanError<CryptoCurveCode>` so the `code` field is typed as a finite union, not an arbitrary string.
+- Carries a `cause` chain — the secp256k1 ECDSA recovery path wraps `@noble/curves` errors as `cause` so the original message is preserved in logs.
+- Auto-instruments OTel span events when an active span exists (no caller setup required).
+- Participates in the wire-format error serialiser (Zod-validated JSON envelope) so errors round-trip across process boundaries cleanly.
+
+## Usage: Basic Example
+
+```ts
+import { CRYPTO_CURVE_CODES, CryptoCurveError } from "@suaveplan/crypto-curve";
+
+throw new CryptoCurveError(
+    CRYPTO_CURVE_CODES.RECOVERY_BYTE_INVALID,
+    "error.crypto.curve.recovery-byte-invalid",
+    { context: { recoveryByte: 7 } }
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { CryptoCurveError } from "@suaveplan/crypto-curve";
+
+try {
+    pubKey = recoverPublicKey(sig, digest);
+} catch (err) {
+    if (err instanceof CryptoCurveError) {
+        switch (err.code) {
+            case "CRYPTO.CURVE.RECOVERY_BYTE_MISSING":
+                throw new Error("Old wallet format — please re-sign with --recovery flag");
+            case "CRYPTO.CURVE.RECOVERY_BYTE_INVALID":
+                throw new Error("Signature corrupt or wrong format");
+            default:
+                throw err;
+        }
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+- `CryptoCurveError extends SuaveplanError<CryptoCurveCode>` — public class, exported from the package root.
+- `new CryptoCurveError(code, messageKey, options?)` — standard constructor mirroring `SuaveplanError`.
+- `error.code: CryptoCurveCode` — typed code field.
+- `error.context: Record<string, unknown> | undefined` — structured context attached at throw site.
+- `error.cause: unknown` — cause chain.
+
+## Implementation Notes
+
+The constructor does no work beyond delegating to the base class — its only job is to set the generic parameter to `CryptoCurveCode` so consumers see the right type. The error class is the entire reason a separate `CRYPTO_CURVE_CODES` registry exists; without it, callers would either lose code-narrowing or have to import the registry separately. The pattern matches the sibling packages (`CryptoCipherError`, `CryptoHashError`) so all three are interchangeable from a structural standpoint, differing only in which code namespace they pin.