pikkujs/pikku-jose

Pikku Jose (JWT Service)

@pikku/jose provides JWT signing, verification, and decoding using the jose library. Implements the JWTService interface from @pikku/core.

Installation

yarn add @pikku/jose

API Reference

JoseJWTService

import { JoseJWTService } from '@pikku/jose'

const jwt = new JoseJWTService(
  getSecrets: () => Promise<Array<{ id: string; value: string }>>,
  logger?: Logger
)

await jwt.init()

Constructor Parameters:

• getSecrets — Async function returning an array of { id, value } key pairs. First key is used for signing; all keys are tried for verification (supports rotation).
• logger — Optional logger instance.

Methods:

• init(): Promise<void> — Fetch and cache secrets. Call at startup.
• encode<T>(expiresIn: RelativeTimeInput, payload: T): Promise<string> — Create a signed JWT.
• decode<T>(token: string): Promise<T> — Decode a JWT payload without verification.
• verify(token: string): Promise<void> — Verify a JWT signature and expiry.

Usage Patterns

Basic Setup

import { JoseJWTService } from '@pikku/jose'

const jwt = new JoseJWTService(
  async () => [{ id: 'key-1', value: process.env.JWT_SECRET! }],
  logger
)
await jwt.init()

Secret Rotation

Supply multiple keys. The first is used for signing; all are tried for verification:

const jwt = new JoseJWTService(async () => [
  { id: 'key-2', value: NEW_SECRET },   // signs with this
  { id: 'key-1', value: OLD_SECRET },   // still verifies tokens signed with this
])

With Pikku Services

const createSingletonServices = pikkuServices(async (config) => {
  const logger = new ConsoleLogger()
  const jwt = new JoseJWTService(
    async () => [{ id: 'my-key', value: config.jwtSecret }],
    logger
  )
  await jwt.init()
  return { config, logger, jwt }
})

Encoding & Verifying Tokens

const token = await jwt.encode('1h', { userId: 'abc', role: 'admin' })

await jwt.verify(token) // throws if invalid/expired

const payload = await jwt.decode<{ userId: string; role: string }>(token)