first commit

docs/identity/auth/jwt-tenant/src/schemas/jwt-tenant.schemas.md

@@ -0,0 +1,77 @@
+# jwt-tenant.schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides Zod schemas for all public configuration and option types in `@suaveplan/jwt-tenant`. These schemas enable runtime validation of user-supplied configuration, making it possible to surface configuration errors at construction time rather than at operation time. They are also useful for serializing and deserializing key pairs in storage-layer integrations.
+
+## Features
+
+- `KeyGenOptionsSchema` — validates key generation options
+- `TokenIssuerConfigSchema` — validates issuer configuration
+- `CreateTokenOptionsSchema` — validates per-token creation options (required `subject` and `tenantId`)
+- `VerifyTokenOptionsSchema` — validates per-verification constraint options
+- `TokenVerifierConfigSchema` — validates verifier configuration
+- `JWKSEndpointOptionsSchema` — validates JWKS endpoint options
+- `SerializedKeyPairSchema` — validates serialized key pair JSON format
+
+## Usage: Basic Example
+
+```ts
+import { CreateTokenOptionsSchema } from "@suaveplan/jwt-tenant/schemas";
+
+const result = CreateTokenOptionsSchema.safeParse({
+  subject: "user-123",
+  tenantId: "acme",
+  role: "admin",
+});
+if (!result.success) {
+  console.error(result.error.format());
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { SerializedKeyPairSchema } from "@suaveplan/jwt-tenant/schemas";
+
+const rawJson = JSON.parse(fs.readFileSync("keypair.json", "utf8"));
+const parsed = SerializedKeyPairSchema.parse(rawJson);
+// parsed is type-narrowed as SerializedKeyPair
+```
+
+## API Reference
+
+### `KeyGenOptionsSchema`
+
+Strict schema: `keyId?` (string), `ttlMs?` (positive number).
+
+### `TokenIssuerConfigSchema`
+
+Strict schema: `issuer?` (URL string), `defaultExpiresIn?` (string).
+
+### `CreateTokenOptionsSchema`
+
+Strict schema with required `subject` (min 1) and `tenantId` (min 1). Optional: `expiresIn`, `domains`, `role`, `permissions`, `sessionId`, `issuer`, `additionalClaims`.
+
+### `VerifyTokenOptionsSchema`
+
+Strict schema: all fields optional — `requiredClaims`, `requiredRole`, `requiredPermissions`, `requiredTenantId`, `requiredDomains`.
+
+### `TokenVerifierConfigSchema`
+
+Strict schema: `issuer?` (URL), `audience?` (string[]), `clockTolerance?` (nonnegative), `jwksUri?` (URL), `cacheMaxAge?` (positive), `maxRetries?` (positive int).
+
+### `JWKSEndpointOptionsSchema`
+
+Strict schema: `cacheMaxAge?` (positive). The `keyStore` and `clock` fields are runtime objects and are excluded.
+
+### `SerializedKeyPairSchema`
+
+Validates `keyId`, `algorithm` (enum), `privateKeyJwk`/`publicKeyJwk` (records), `createdAt`/`expiresAt?` (ISO-8601 datetime strings).
+
+## Implementation Notes
+
+All schemas use `.strict()` to reject unknown keys, making configuration typos immediately surfaced. The `clock` and `signal` fields in config interfaces are runtime objects that cannot be validated by Zod and are intentionally excluded from the schemas.