skills/docs/identity/auth/jwt-tenant/README.md

@suaveplan/jwt-tenant - JWT-based multi-tenant token issuance and verification with Ed25519/ECDSA signing, JWKS rotation, and injectable clock

Summary

JWT-based multi-tenant token issuance and verification for Suaveplan. Ships an Ed25519 / ECDSA-P256 signing pipeline, in-memory JWKS store with rotation and expiration, JWKS HTTP endpoint formatter, token issuer and verifier with injectable clock, and structured JWT_TENANT_* error codes — all backed by jose, Zod-validated configs, and OpenTelemetry instrumentation.

Documentation tree

• errors — (no submodules)
  • jwt-tenant-error — (no submodules)
• in-memory-key-store — (no submodules)
  • in-memory-key-store — (no submodules)
• jwks-endpoint — (no submodules)
  • jwks-endpoint — (no submodules)
• key-generator — (no submodules)
  • key-generator — (no submodules)
• schemas — (no submodules)
  • jwt-tenant.schemas — (no submodules)
• token-issuer — (no submodules)
  • token-issuer — (no submodules)
• token-verifier — (no submodules)
  • token-verifier — (no submodules)

- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_ - [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_ - [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_ - [key-generator](./src/keys/key-generator/key-generator.md) — _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_ - [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_ - [token-issuer](./src/token/token-issuer/token-issuer.md) — _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_ - [token-verifier](./src/token/token-verifier/token-verifier.md) — _(no submodules)_

Install

bun add @suaveplan/jwt-tenant

Quick start

import {
    createInMemoryKeyStore,
    createTokenIssuer,
    createTokenVerifier,
    generateKeyPair,
} from "@suaveplan/jwt-tenant";

const keyPair = await generateKeyPair({ algorithm: "EdDSA" });
const store = createInMemoryKeyStore();
await store.add(keyPair);

const issuer = createTokenIssuer({ store, issuer: "https://auth.example.com" });
const token = await issuer.sign({
    subject: "user-123",
    tenantId: "tenant-abc",
    expiresIn: 3600,
});

const verifier = createTokenVerifier({ store, issuer: "https://auth.example.com" });
const claims = await verifier.verify(token);

Modules

• Errors — JwtTenantError, JWT_TENANT_CODES, structured error registry
• Key generator — generateKeyPair, JWK import/export, expiration helpers
• In-memory key store — JWKS storage with rotation and expiration
• JWKS endpoint — createJWKSEndpoint, formatJWKSResponse for .well-known/jwks.json
• Token issuer — createTokenIssuer, signToken
• Token verifier — createTokenVerifier, claim validation
• Schemas — Zod schemas for all public option bundles
• Types — shared type definitions