@roastery-capsules/jwt

JWT signing and verification capsule for the Roastery CMS ecosystem.

Overview

jwt provides a small, exception-safe HMAC JWT primitive for Roastery CMS applications:

• JsonWebToken — Signs and verifies JWTs via jose, with automatic iat/exp handling and normalized @roastery/terroir exceptions instead of raw jose errors.
• jwt plugin — A Barista plugin that reads JWT_SECRET from the app environment and decorates the instance with a ready-to-use JsonWebToken.
• Jwt capsule — The @roastery/blend manifest that registers the plugin and its required environment schema with the Roastery CMS platform.

Technologies

| Tool | Purpose | |------|---------| | jose | JWT signing and verification | | @roastery/barista | Web framework (Elysia-based) the plugin decorates | | @roastery/blend | Capsule manifest contract (Jwt extends Blend) | | @roastery/pantry | Shared CACHE_EXPIRATION_TIME presets used for token expiration | | @roastery/terroir | Exception hierarchy and runtime schema validation | | tsup | Bundling to ESM + CJS with .d.ts generation | | Bun | Runtime, test runner, and package manager | | Knip | Unused exports and dependency detection | | Husky + commitlint | Git hooks and conventional commit enforcement |

Installation

bun add @roastery-capsules/jwt

Capsule registration

Register the Jwt capsule with the platform's capsule manager so environmentNeeds is validated and the plugin is mounted for you:

import { Jwt } from '@roastery-capsules/jwt';

const capsule = new Jwt();
app.use(capsule.plugin);

jwt plugin

Mount the plugin directly on a Barista instance to decorate it with app.decorator.jwt:

import { jwt } from '@roastery-capsules/jwt/plugins';

app.use(jwt);
app.get('/me', ({ jwt }) => jwt.sign({ sub: '123' }));

The plugin is idempotent — if app already carries a jwt decorator, it's reused instead of replaced.

JsonWebToken

import { JsonWebToken } from '@roastery-capsules/jwt';

const jwt = new JsonWebToken('auth-service', process.env.JWT_SECRET!);

// Sign a payload (expires in 1 hour by default)
const token = await jwt.sign({ email: '[email protected]' });

// Verify and decode
const { payload } = await jwt.verify<{ email: string }>(token);

sign accepts an expirationTime preset ("SAFE" = 1h, "LOW_UPDATES" = 24h, "HIGH_UPDATES" = 15min) and a JwtProtectedHeader to override the signing algorithm (defaults to HS256).

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | JWT_SECRET | Yes | Secret key for signing and verifying JWT tokens |

Documentation

Every public export carries inline TSDoc — a package-level overview on the root entry point and a @module summary on each subpath barrel (/dtos, /plugins, /types) — so IDE hovers and the generated .d.ts files stay in sync with the in-depth, per-symbol guides in docs/:

• JsonWebToken
• jwt plugin
• Jwt capsule
• JwtDependenciesDTO
• JwtProtectedHeader
• JwsAlgorithm

Exports Reference

import { Jwt, JsonWebToken } from '@roastery-capsules/jwt';         // Jwt, JsonWebToken
import { jwt } from '@roastery-capsules/jwt/plugins';                // jwt plugin
import { JwtDependenciesDTO } from '@roastery-capsules/jwt/dtos';    // JwtDependenciesDTO
import type { JwsAlgorithm, JwtProtectedHeader } from '@roastery-capsules/jwt/types';

Development

# Run tests
bun run test:unit

# Run tests with coverage
bun run test:coverage

# Build for distribution
bun run build

# Check for unused exports and dependencies
bun run knip

# Full setup (build + bun link)
bun run setup

License

MIT