66 lines
9.4 KiB
Markdown
66 lines
9.4 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [errors](./src/errors/jwt-tenant-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt-tenant-error](./src/errors/jwt-tenant-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_ - [in-memory-key-store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_ - [jwks-endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — <!-- begin:auto-docs --> _(no submodules)_- [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_ - [key-generator](./src/keys/key-generator/key-generator.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ - [jwt-tenant.schemas](./src/schemas/jwt-tenant.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_ - [token-issuer](./src/token/token-issuer/token-issuer.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_ - [token-verifier](./src/token/token-verifier/token-verifier.md) — <!-- begin:auto-docs --> _(no submodules)_
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/jwt-tenant
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
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](./src/errors/jwt-tenant-error.md) — `JwtTenantError`, `JWT_TENANT_CODES`, structured error registry
|
|
- [Key generator](./src/keys/key-generator/key-generator.md) — `generateKeyPair`, JWK import/export, expiration helpers
|
|
- [In-memory key store](./src/jwks/in-memory-key-store/in-memory-key-store.md) — JWKS storage with rotation and expiration
|
|
- [JWKS endpoint](./src/jwks/jwks-endpoint/jwks-endpoint.md) — `createJWKSEndpoint`, `formatJWKSResponse` for `.well-known/jwks.json`
|
|
- [Token issuer](./src/token/token-issuer/token-issuer.md) — `createTokenIssuer`, `signToken`
|
|
- [Token verifier](./src/token/token-verifier/token-verifier.md) — `createTokenVerifier`, claim validation
|
|
- [Schemas](./src/schemas/jwt-tenant.schemas.md) — Zod schemas for all public option bundles
|
|
- [Types](./src/types/jwt-tenant.types.md) — shared type definitions
|