first commit

docs/security-stack/crypto/crypto-rsa/src/schemas/schemas.md

@@ -0,0 +1,90 @@
+# `schemas`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Zod boundary schemas covering every public input/output of `@suaveplan/crypto-rsa`.
+ships the canonical key shapes (`RsaPublicKeySchema`, `RsaPrivateKeySchema`),
+the parse/serialise format discriminators, and the option schemas for the sign,
+verify, PSS, and OAEP entry points that Stages 2-3 will wire up.
+
+The schemas serve two purposes: runtime validation at every public surface, and
+single-source-of-truth typing for documentation and downstream consumer
+ecosystems (e.g. JWK parsers in `@suaveplan/jws` once it lands).
+
+## Features
+
+- `HashAlgorithmSchema` — `SHA-1` | `SHA-256` | `SHA-384` | `SHA-512`.
+- `RsaPublicKeySchema` and `RsaPrivateKeySchema` — every field positive `bigint`,
+  `bitLength` positive integer.
+- `RsaPublicKeyFormatSchema` (`"pkcs1" | "spki" | "jwk"`).
+- `RsaPrivateKeyFormatSchema` (`"pkcs1" | "pkcs8" | "jwk"`).
+- `RsaParseOptions{Public,Private}Schema` and the union `RsaParseOptionsSchema`.
+- `RsaSerializeOptions{Public,Private}Schema` and the union `RsaSerializeOptionsSchema`.
+- `RsaSignOptionsSchema`, `RsaVerifyOptionsSchema`, `RsaPssOptionsSchema`,
+  `RsaOaepOptionsSchema`.
+
+## Usage: Basic Example
+
+```ts
+import { RsaPublicKeySchema } from "@suaveplan/crypto-rsa/schemas";
+
+const validated = RsaPublicKeySchema.parse({
+    n: 0xc0_de_n,
+    e: 65537n,
+    bitLength: 2048,
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    RsaParseOptionsPublicSchema,
+    RsaPssOptionsSchema,
+} from "@suaveplan/crypto-rsa/schemas";
+
+function readKey(input: unknown) {
+    const opts = RsaParseOptionsPublicSchema.parse(input);
+    // opts.format is now "pkcs1" | "spki" | "jwk"
+}
+
+function signOptions(input: unknown) {
+    const opts = RsaPssOptionsSchema.parse(input);
+    // opts.hash, opts.saltLength?, opts.mgfHash?
+}
+```
+
+## API Reference
+
+Every export is a `z.ZodType<T>`. `infer` to recover the static type:
+
+```ts
+import type { z } from "zod";
+import { RsaPublicKeySchema } from "@suaveplan/crypto-rsa/schemas";
+type RsaPublicKey = z.infer<typeof RsaPublicKeySchema>;
+```
+
+Schemas validate strictly:
+
+- `n`, `e`, `d`, `p`, `q`, `dp`, `dq`, `qInv` MUST be positive `bigint`.
+- `bitLength` MUST be a positive integer.
+- `format` MUST be one of the discriminated string literals.
+- `hash` MUST be one of the four canonical IETF hash labels (`SHA-256` etc.,
+  hyphenated, uppercase — the JOSE / WebCrypto canonical form).
+
+## Implementation Notes
+
+`positiveBigInt` and `positiveBitLength` are inlined helpers rather than exported
+schemas to keep the public surface focused on the named shapes the proposal pins.
+
+The parse/serialise option unions are `z.union(public, private)` rather than
+discriminated unions because the discriminant value sets overlap (`"pkcs1"` and
+`"jwk"` appear in both). Consumers that need stricter narrowing should call the
+specific public/private schemas directly.
+
+`RsaSignOptionsSchema` carries an optional `blinding` flag for downstream RSA
+private-key blinding (Stage 2) so callers can opt out of the side-channel
+hardening for benchmarks; the default behaviour will be `blinding: true`.