@civic/auth-verify

@civic/auth-verify

JWT verification library for Civic Auth tokens using JWKS endpoint discovery.

Features

• JWT token verification using JWKS endpoint discovery
• OIDC configuration discovery (.well-known/openid-configuration)
• Built-in caching for JWKS data with issuer-based keys
• Support for multiple cache implementations (InMemory and Bundled)
• TypeScript support with full type safety

Installation

pnpm add @civic/auth-verify

Usage

Basic Usage

import { verify } from '@civic/auth-verify';

// Verify a token with default settings (uses Civic Auth issuer)
const payload = await verify(token);
console.log(payload);

Using a Custom Cache

By default, the library uses an in-memory cache for JWKS data. You can provide your own cache implementation if needed.

In the in-memory cache, keys are stored in memory and lost when the process restarts. The library uses a shared default instance across all verify calls unless you provide your own.

If you want to control the lifecycle of the cache, provide your own as follows:

import { verify, InMemoryJWKSCache } from '@civic/auth-verify';

// Create a custom cache instance
const cache = new InMemoryJWKSCache();

// Use the cache for verification
const payload = await verify(token, {
  jwksCache: cache
});

Using a "Bundled Cache" (Pre-loaded Civic Auth JWKS)

The Bundled Cache is a key cache pre-populated with Civic Auth JWKS keys, useful for offline verification or reduced latency.

• Pre-loaded keys: Contains the latest Civic Auth JWKS bundled at build time
• Offline support: Can verify Civic Auth tokens without any network requests
• Performance: Eliminates the initial JWKS fetch for Civic Auth tokens
• Updates: The bundled JWKS is updated when the package is built/published
• Extensible: Can still fetch and cache JWKS for other issuers dynamically

Note: The bundled JWKS is specific to Civic Auth keys. If using another issuer, you can still use the InMemoryJWKSCache or implement your own cache.

import { verify, BundledJWKSCache } from '@civic/auth-verify';

// Use bundled cache with pre-downloaded Civic Auth JWKS
const cache = new BundledJWKSCache();

const payload = await verify(token, {
  jwksCache: cache
});

API

verify(token: string, options?: VerifyOptions): Promise<JWTPayload>

Verifies a JWT token and returns its payload.

Parameters

• token - The JWT token to verify
• options - Optional verification options
  • issuer - The token issuer URL (defaults to Civic Auth)
  • wellKnownConfigurationUrl - Custom OpenID configuration URL
  • jwksCache - Custom JWKS cache implementation
  • aud - Expected audience value for the token (optional)
  • clientId - Expected client ID value for the token (optional). If provided, the JWT must contain this value in either the client_id or tid field

Returns

A promise that resolves to the JWT payload.

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

# Lint
pnpm lint