first commit

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

@@ -0,0 +1,53 @@
+# `keys/serialize-pkcs1-public`
+
+## Purpose
+
+Inverse of `parseRsaPublicKeyPkcs1`. Emits a DER `RSAPublicKey` SEQUENCE
+per RFC 8017 Appendix A.1.1 from a canonical `RsaPublicKey`. The output
+is byte-identical for any input that previously round-tripped through
+the parser, and is the canonical body wrapped by SPKI public-key
+emission and PEM `-----BEGIN RSA PUBLIC KEY-----` framing.
+
+## Features
+
+- Single-call DER emission via `encodeSequence(encodeInteger, encodeInteger)`.
+- Strict-DER output (minimal length, minimal integer encoding).
+- Pure function — no allocation beyond the byte buffers.
+
+## Usage: Basic Example
+
+```ts
+import { serializeRsaPublicKeyPkcs1 } from "@suaveplan/crypto-rsa";
+
+const der = serializeRsaPublicKeyPkcs1(key);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    parseRsaPublicKeyPkcs1,
+    serializeRsaPublicKeyPkcs1,
+} from "@suaveplan/crypto-rsa";
+
+// Round-trip invariant.
+const roundTripped = parseRsaPublicKeyPkcs1(
+    serializeRsaPublicKeyPkcs1(key)
+);
+// roundTripped equals key.
+```
+
+## API Reference
+
+### `serializeRsaPublicKeyPkcs1(key: RsaPublicKey): Uint8Array`
+
+Returns the canonical DER encoding. Never throws on a structurally valid
+`RsaPublicKey`.
+
+## Implementation Notes
+
+The serialiser does not re-validate `(n, e)`; that is the parser's job.
+Callers that reach this path have either constructed the key locally
+(in which case validation is the constructor's job) or routed through
+the parser (already validated). Adding a redundant check here would
+double the cost without adding any safety guarantee.