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

jwt-tenant.schemas

(no submodules)

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

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

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.