first commit

docs/security-stack/crypto/crypto-rsa/src/pem/parse-public.md

@@ -0,0 +1,52 @@
+# `pem/parse-public`
+
+## Purpose
+
+Parse an RSA public key from RFC 7468 PEM textual encoding. Accepts both
+canonical armor labels — `"PUBLIC KEY"` (SPKI per RFC 5280) and
+`"RSA PUBLIC KEY"` (PKCS#1 per RFC 8017) — and dispatches to the
+appropriate DER parser. Mismatched BEGIN/END, unknown labels, or non-base64
+body content surface as `CRYPTO_RSA.PEM_MALFORMED`.
+
+## Features
+
+- Dual-label support (`"PUBLIC KEY"` and `"RSA PUBLIC KEY"`).
+- Delegates to existing DER parsers — no DER logic duplicated.
+- Strict-grammar body validation via `decodePem`.
+
+## Usage: Basic Example
+
+```ts
+import { parseRsaPublicKeyPem } from "@suaveplan/crypto-rsa/pem";
+
+const key = parseRsaPublicKeyPem(`
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----
+`);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { parseRsaPublicKeyPem } from "@suaveplan/crypto-rsa/pem";
+
+// Either label is accepted.
+const fromSpki = parseRsaPublicKeyPem(spkiPem);
+const fromPkcs1 = parseRsaPublicKeyPem(pkcs1Pem);
+```
+
+## API Reference
+
+### `parseRsaPublicKeyPem(pem: string): RsaPublicKey`
+
+Throws `CryptoRsaError(CRYPTO_RSA.PEM_MALFORMED)` on framing errors and
+`CryptoRsaError(CRYPTO_RSA.INVALID_KEY | CRYPTO_RSA.UNSUPPORTED_FORMAT)`
+on inner-DER errors per the underlying DER parsers.
+
+## Implementation Notes
+
+The dispatcher is a `Record<string, parser>` lookup keyed by label. Building
+the allowed-label list from the dispatcher's keys ensures the codec's
+allowlist and the dispatcher's coverage cannot drift — adding a new label
+requires changing exactly one place.