Schemas

(no submodules)

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

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

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.

2.6 KiB Raw Blame History