first commit

docs/foundation/flow/cbor/src/cose/alg-map.md

@@ -0,0 +1,67 @@
+# `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.