# 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.