# `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`.