Initial Commit

packages/security-stack/crypto/crypto-rsa/src/keys/parse.md

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