first commit

docs/security-stack/crypto/crypto-rsa/src/keys/serialize.md

@@ -0,0 +1,52 @@
+# `keys/serialize`
+
+## Purpose
+
+Public dispatcher entry-point inverse of `parse`. Selects the per-format
+serialiser via the same `format` discriminator. Returns `Uint8Array` for
+binary formats (`pkcs1`, `spki`, `pkcs8`) and a structured `RsaJwk` object
+for JWK so consumers can post-process the result without re-parsing JSON.
+
+## Features
+
+- `serializeRsaPublicKey(key, { format })` over the PKCS#1 / SPKI / JWK set.
+- `serializeRsaPrivateKey(key, { format })` over the PKCS#1 / PKCS#8 / JWK set.
+- `default` branch surfaces `CRYPTO_RSA.UNSUPPORTED_FORMAT` for safety.
+
+## Usage: Basic Example
+
+```ts
+import { serializeRsaPublicKey } from "@suaveplan/crypto-rsa";
+
+const der = serializeRsaPublicKey(key, { format: "spki" });
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    serializeRsaPrivateKey,
+    serializeRsaPublicKey,
+} from "@suaveplan/crypto-rsa";
+
+const jwk = serializeRsaPublicKey(key, { format: "jwk" });
+const pkcs8 = serializeRsaPrivateKey(key, { format: "pkcs8" });
+```
+
+## API Reference
+
+### `serializeRsaPublicKey(key, options): Uint8Array | RsaJwk`
+
+Returns bytes for `pkcs1` / `spki`, a structured `RsaJwk` for `jwk`.
+
+### `serializeRsaPrivateKey(key, options): Uint8Array | RsaJwk`
+
+Returns bytes for `pkcs1` / `pkcs8`, a structured `RsaJwk` for `jwk`.
+
+## Implementation Notes
+
+The mixed `Uint8Array | RsaJwk` return type intentionally pushes the
+discrimination back to the caller — picking `format: "jwk"` is a deliberate
+choice and the caller already knows the result will be an object. Type
+narrowing on the `format` literal is left to consumer-side discriminated
+union helpers because Stage 1 deliberately keeps the dispatcher minimal.