first commit

docs/security-stack/security/jws/src/schemas/schemas.md

@@ -0,0 +1,59 @@
+# 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`.