# `alg-map`

## Purpose

Bridge between IANA COSE Algorithm identifiers (`CoseAlg` literal strings or
the equivalent numeric labels from RFC 9053 §2) and the suaveplan-internal
algorithm identifiers consumed by `@suaveplan/crypto-curve`,
`@suaveplan/crypto-cipher`, and `@suaveplan/crypto-hash`. The bridge is the
single point where COSE / CWT / WebAuthn flows decide *which* suaveplan
primitive will run for a given algorithm label.

## Features

- Full IANA registry coverage for the algorithms the crypto packages
  ship: ES256, ES384, ES512, EdDSA (Ed25519), RS256, RS384, RS512, HS256,
  HS384, HS512, A128GCM, A192GCM, A256GCM, ChaCha20Poly1305.
- Accepts both the typed `CoseAlg` string and the raw IANA numeric label.
- Reverse mapping (`cryptoAlgToCoseAlg`) for outbound encoding.
- Throws `CborError(UNEXPECTED_TYPE)` for any algorithm the bridge does
  not implement — this is the intentional point of failure when a caller
  tries to use a primitive suaveplan does not (yet) ship.

## Usage: Basic Example

```ts
import { coseAlgToCryptoAlg } from "@suaveplan/cbor/cose";

const alg = coseAlgToCryptoAlg("ES256"); // "ecdsa-p256-sha256"
```

## Usage: Advanced Example

```ts
import { coseAlgToCryptoAlg, decodeCoseKey } from "@suaveplan/cbor/cose";

// CWT verification dispatch
const key = decodeCoseKey(keyBytes);
const cryptoAlg = coseAlgToCryptoAlg(key.alg ?? "ES256");
switch (cryptoAlg) {
  case "ecdsa-p256-sha256":
    // hand off to @suaveplan/crypto-curve.p256.verify
    break;
  case "ed25519":
    // hand off to @suaveplan/crypto-curve.ed25519.verify
    break;
  // ...
}
```

## API Reference

- `coseAlgToCryptoAlg(alg: CoseAlg | number): suaveplanCryptoAlg`
- `cryptoAlgToCoseAlg(alg: suaveplanCryptoAlg): CoseAlg`
- `type suaveplanCryptoAlg` — literal-typed union of the suaveplan-internal
  algorithm IDs the bridge resolves to.

Throws `CborError(UNEXPECTED_TYPE)` for unknown numeric labels and for
algorithm strings outside the supported set.

## Implementation Notes

The bridge is a static lookup table — adding a new algorithm requires a
single new entry in both the `CoseAlg` literal type and the `ALG_BRIDGE`
record, plus a corresponding entry in the IANA-driven `COSE_ALG_LABELS`.
Keeping the conversion in a separate module (rather than threading raw
strings through the codec) ensures every inbound algorithm label crosses
exactly one validation boundary before reaching the cryptographic core.