# `keys/parse`

## Purpose

Public dispatcher entry-point unifying the four key-format parsers
(PKCS#1, SPKI, PKCS#8, JWK) under one ergonomic call. Selects the
underlying parser via a `format` discriminator on the options object,
matching the round-trip pattern used elsewhere in the crypto
family.

## Features

- `parseRsaPublicKey(input, { format: "pkcs1" | "spki" | "jwk" })`.
- `parseRsaPrivateKey(input, { format: "pkcs1" | "pkcs8" | "jwk" })`.
- Binary formats accept `Uint8Array`; JWK accepts object / JSON string /
  UTF-8 bytes.
- `default` branches surface `CRYPTO_RSA.UNSUPPORTED_FORMAT` so any future
  format added to the type union without a switch arm fails loudly.

## Usage: Basic Example

```ts
import { parseRsaPublicKey } from "@suaveplan/crypto-rsa";

const key = parseRsaPublicKey(spkiBytes, { format: "spki" });
```

## Usage: Advanced Example

```ts
import {
    parseRsaPrivateKey,
    parseRsaPublicKey,
} from "@suaveplan/crypto-rsa";

const fromPkcs8 = parseRsaPrivateKey(pkcs8Bytes, { format: "pkcs8" });
const fromJwk = parseRsaPrivateKey(jwkObject, { format: "jwk" });
const fromJsonJwk = parseRsaPrivateKey(jwkJsonString, { format: "jwk" });
```

## API Reference

### `parseRsaPublicKey(input, options): RsaPublicKey`

Throws `CRYPTO_RSA.INVALID_KEY` when a non-`Uint8Array` is passed for the
binary formats.

### `parseRsaPrivateKey(input, options): RsaPrivateKey`

Same input/error contract on the private side.

## Implementation Notes

The dispatcher is exhaustive over the literal union via `assertNeverFormat`,
which TypeScript verifies statically. Adding a new format requires both a
new type member and a new switch arm — the compiler enforces both. This is
the only safe way to evolve a discriminated dispatcher without silently
falling through to a default branch.

The `requireBytes` helper is shared between the PKCS#1/SPKI/PKCS#8 paths
because they all consume `Uint8Array`. JWK input is forwarded through the
JWK parser which handles its own normalisation.