@authu/node

Node.js SDK for AuthU - Centralized Multi-Tenant Authentication Service.

Installation

npm install @authu/node
# or
pnpm add @authu/node
# or
yarn add @authu/node

Usage

1. Verify JWT Tokens

Use verifyToken to validate and decode JWT tokens:

import {verifyToken} from '@authu/node';

const result = await verifyToken(token, {
  domain: 'auth.example.com',
  audience: 'https://api.example.com'
});

console.log(result.payload.sub); // User ID
console.log(result.payload.email); // User email

2. Fastify Middleware

Use createAuthUMiddleware to protect your Fastify routes:

import Fastify from 'fastify';
import {createAuthUMiddleware} from '@authu/node';

const fastify = Fastify();

// Register the middleware
fastify.register(
  createAuthUMiddleware({
    domain: 'auth.example.com',
    audience: 'https://api.example.com'
  })
);

// Protected route
fastify.get(
  '/api/profile',
  {preHandler: [fastify.verifyAuthU]},
  async request => {
    // Access the authenticated user
    return {user: request.authUUser};
  }
);

3. Optional Authentication

For routes where authentication is optional:

fastify.register(
  createAuthUMiddleware({
    domain: 'auth.example.com',
    optional: true
  })
);

fastify.get('/api/public', {preHandler: [fastify.verifyAuthU]}, async request => {
  if (request.authUUser) {
    return {message: `Hello ${request.authUUser.name}`};
  }
  return {message: 'Hello guest'};
});

4. Custom JWKS Client

For advanced use cases, you can provide your own JWKS client:

import {JwksClient, verifyToken} from '@authu/node';

const jwksClient = new JwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cacheMaxAge: 300000 // 5 minutes cache
});

const result = await verifyToken(token, {
  domain: 'auth.example.com',
  jwksClient
});

API Reference

verifyToken(token, options)

Verifies and decodes a JWT token.

Options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | domain | string | Yes | AuthU server domain (without https://) | | audience | string | No | Expected audience claim | | issuer | string | No | Expected issuer (default: https://{domain}) | | jwksClient | JwksClient | No | Custom JWKS client instance |

Returns: Promise<VerifiedToken>

createAuthUMiddleware(options)

Creates a Fastify plugin for JWT authentication.

Options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | domain | string | Yes | AuthU server domain | | audience | string | No | Expected audience claim | | issuer | string | No | Expected issuer | | optional | boolean | No | If true, don't error on missing/invalid tokens |

Decorators added:

• fastify.verifyAuthU - Prehandler function for route protection
• request.authUUser - Authenticated user data (or null if optional)

JwksClient

JWKS client with automatic caching.

const client = new JwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cacheMaxAge: 600000 // 10 minutes (default)
});

// Get a key by kid
const key = await client.getKey('key-id');

// Get all keys
const jwks = await client.getJwks();

// Clear cache
client.clearCache();

Types

interface AuthUUser {
  sub: string;
  email?: string;
  emailVerified?: boolean;
  name?: string;
  picture?: string;
  scope?: string;
  clientId?: string;
  tenantId?: string;
}

interface VerifiedToken {
  payload: AuthUUser;
  header: {
    alg: string;
    typ?: string;
    kid?: string;
  };
}

Development

Build

pnpm run build

Lint

pnpm run lint

Publishing

Prerequisites

• Be logged in to npm: npm login
• Have publish rights on @authu scope

Publish a New Version

1. Update version in package.json
2. Build and publish:

pnpm run build
pnpm publish --access public

The --access public flag is required for scoped packages.

License

MIT