xAuthJWSK

Lightweight, zero-config path-based JWT/JWKS validation for Fastify v5.

Protect multiple API paths with independent JWKS providers. Simple, fast, and production-ready.

Features

✅ Path-Based Protection - Protect /admin, /portal, /api with different JWKS providers ✅ Bearer Token Validation - Automatic JWT validation against remote JWKS endpoints ✅ Local or Remote JWKS - Use remote URLs for production or local JWKS data for development ✅ Dual-Level Caching - JWKS cache (30 min) + JWT payload cache (5 min) ✅ Excluded Paths - Skip auth for health checks, docs, etc. ✅ Zero Dependencies - Only uses jose and fastify-plugin ✅ Slim & Focused - ~200 lines of core code, no bloat ✅ Configurable - All caching parameters customizable ✅ Request Isolation - Each path has separate validator & cache

Installation

npm install @xenterprises/fastify-xauth-jwks

Quick Example

import Fastify from 'fastify';
import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';

const fastify = Fastify();

await fastify.register(xAuthJWSK, {
  paths: {
    admin: {
      pathPattern: "/admin",
      jwksUrl: "https://your-auth.com/.well-known/jwks.json",
    }
  }
});

fastify.get('/admin/users', (request) => {
  return { userId: request.auth.userId };
});

fastify.listen({ port: 3000 });

Documentation

Getting Started:

• QUICK_START.md - Get started in 5 minutes
• CONFIGURATION.md - Complete configuration reference (all options + examples)

Examples & Guides:

• AUTHENTICATION_EXAMPLE.md - Email/password auth with JWT signing
• DEVELOPMENT.md - Local development with test tokens
• KEYS_GENERATION.md - Generate JWKS keys and test tokens

Advanced:

• CACHING.md - Configure caching for performance
• JOSE_UTILITIES.md - Advanced JWT inspection

Tests

npm test
# 49/49 tests passing ✅

License

ISC