# Schemas

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Zod boundary schemas validated at every public entry point. The `@suaveplan` convention is that public options never silently degrade into malformed tokens; every shape mismatch surfaces as `JWS.INVALID_OPTIONS` (caller misuse) or `JWS.HEADER_MALFORMED` (parsed token shape failure) before any cryptographic work runs. These schemas are exported so downstream consumers (`@suaveplan/webauthn`, future `@suaveplan/jwt`) can compose their own validators on top of the same shapes.

## Features

- `JoseHeaderSchema` — RFC 7515 §4.1 registered parameters; unknown parameters survive via `.passthrough()`.
- `JsonWebKeySchema` — RFC 7517 §4 JWK structural skeleton.
- `VerifyOptionsSchema` — every verify entry point's caller options.
- `SignOptionsSchema` — every sign entry point's caller options.
- `FlatJwsSchema` / `JwsSignatureSchema` / `GeneralJwsSchema` — wire shapes.

## Usage: Basic Example

```ts
import { VerifyOptionsSchema, JwsError } from "@suaveplan/jws";

const result = VerifyOptionsSchema.safeParse({ algorithms: ["RS256"] });
if (!result.success) {
    throw new JwsError("JWS.INVALID_OPTIONS", "...", { context: { issues: result.error.issues } });
}
```

## Usage: Advanced Example

```ts
import { GeneralJwsSchema, JoseHeaderSchema } from "@suaveplan/jws";
import z from "zod";

// Compose a stricter header schema for a JWT consumer:
const StrictJwtHeader = JoseHeaderSchema.extend({
    typ: z.literal("JWT"),
    alg: z.union([z.literal("RS256"), z.literal("ES256")]),
});

// Validate a general JWS payload at an HTTP boundary:
const parsed = GeneralJwsSchema.parse(await request.json());
```

## API Reference

- `JoseHeaderSchema: z.ZodSchema`
- `JsonWebKeySchema: z.ZodSchema`
- `VerifyOptionsSchema: z.ZodSchema`
- `SignOptionsSchema: z.ZodSchema`
- `FlatJwsSchema: z.ZodSchema`
- `JwsSignatureSchema: z.ZodSchema`
- `GeneralJwsSchema: z.ZodSchema`

All schemas use `.passthrough()` where unknown fields are permitted (header) and `.strict()` where they aren't (wire-shape objects).

## Implementation Notes

The verify-options schema declares `algorithms` as a required array — the Zod boundary catches the most common misuse (forgetting to pass `algorithms`, or passing `{} as never`) and surfaces it as `JWS.INVALID_OPTIONS` before the verify pipeline even sees the call. The general-JWS schema enforces `signatures.length >= 1` because an empty signatures array is structurally meaningless (no one signed anything) and lenient libraries that accept it silently produce false-positive verifies under `requireAll: false`.