fastify-xauth-jwks

Path-based JWT validation using JWKS (JSON Web Key Sets). Register once and protect any number of URL prefixes — each with its own JWKS endpoint, caching policy, and excluded sub-paths.

Breaking change (1.0): the decorator was renamed from fastify.xAuth to fastify.xAuthJwks. Update any code that accessed fastify.xAuth.validators.<name> to use fastify.xAuthJwks.validators.<name>.

Installation

npm install @xenterprises/fastify-xauth-jwks

Quick Start

import Fastify from "fastify";
import xAuth from "@xenterprises/fastify-xauth-jwks";

const fastify = Fastify();

await fastify.register(xAuth, {
  paths: {
    admin: {
      pathPattern: "/admin",
      jwksUrl: process.env.ADMIN_JWKS_URL,
      excludedPaths: ["/health"],
    },
    portal: {
      pathPattern: "/portal",
      jwksUrl: process.env.PORTAL_JWKS_URL,
    },
  },
});

// Protected — requires valid JWT
fastify.get("/admin/dashboard", (request) => {
  return { userId: request.auth.userId, user: request.user };
});

// Excluded — no auth required
fastify.get("/admin/health", () => ({ status: "ok" }));

await fastify.listen({ port: 3000 });

Options

The plugin accepts a single paths object. Each key is a logical name for the path and each value is its configuration.

Path Configuration

Request Properties

On authenticated requests the plugin sets:

Methods

Validator Object (fastify.xAuthJwks.validators.<name>)

Each registered path creates a validator accessible at fastify.xAuthJwks.validators.<name>:

• verifyJWT — Verify a JWT string against this path's JWKS. Returns the payload or null.
• clearPayloadCache — Clear the in-memory JWT payload cache for this path.
• getPayloadCacheStats — Get cache statistics (size, enabled, ttl) for monitoring.

Utility Exports (@xenterprises/fastify-xauth-jwks/utils)

• extractToken — Extract Bearer token from the Authorization header.
• hasRole — Check if a JWT payload contains any of the specified roles.
• hasPermission — Check if a JWT payload contains any of the specified permissions.
• getUserId — Get the user ID from request.auth.userId or request.user.sub.
• getAuthEndpoint — Get the auth path name from request.auth.path.
• requireRole — Fastify preHandler factory that replies 403 if the user lacks the role.
• requirePermission — Fastify preHandler factory that replies 403 if the user lacks the permission.
• requireEndpoint — Fastify preHandler factory that replies 403 if the request was not authenticated by the named path.
• decodeToken — Decode JWT payload without verification.
• decodeHeader — Decode JWT header without verification.

Error Reference

Runtime Errors (HTTP responses)

Startup Errors (thrown during registration)

Every message names the plugin (xauth), the offending option, and shows a usage example.

Environment Variables

The plugin does not read environment variables directly. Pass JWKS URLs from your environment:

How It Works

At registration the plugin iterates paths and creates a PathValidator for each active entry. Remote JWKS endpoints are wrapped with jose.createRemoteJWKSet (configurable cooldown and max-age); local JWKS data is wrapped with jose.createLocalJWKSet. An onRequest hook checks request.url.startsWith(pathPattern), skips any excludedPaths, extracts the Bearer token, verifies it against the path's JWKS, and populates request.user and request.auth. Two caching layers reduce latency: the jose library caches remote JWKS keys, and an optional in-memory Map caches verified JWT payloads keyed by raw token string with a configurable TTL.

AI Context

package: "@xenterprises/fastify-xauth-jwks"
type: fastify-plugin
use-when: Path-based JWT validation against remote or local JWKS — multiple route prefixes each with their own JWKS provider
decorator: fastify.xAuthJwks (validators.<name>.verifyJWT, clearPayloadCache, getPayloadCacheStats)
request-decorators: request.user (full JWT payload), request.auth.userId, request.auth.path, request.auth.payload
utility-exports: extractToken, hasRole, hasPermission, getUserId, getAuthEndpoint, requireRole, requirePermission, requireEndpoint, decodeToken, decodeHeader
import-utils: "@xenterprises/fastify-xauth-jwks/utils"