Skip to content
Authrim

JS Server SDK Overview

What is @authrim/server?

@authrim/server is Authrim’s server-side SDK for resource servers. It validates JWT access tokens, verifies DPoP proofs, manages JWKS key sets, and provides framework middleware for popular Node.js frameworks.

Architecture

The following diagram shows where @authrim/server fits in the OAuth 2.0 architecture:

sequenceDiagram
    participant Client as Client App
(@authrim/web or
@authrim/core)
    participant AuthServer as Authrim
Authorization Server
    participant Resource as Resource Server
(@authrim/server)

    Client->>AuthServer: 1. Authorization Request
    AuthServer-->>Client: 2. Access Token (JWT)
    Client->>Resource: 3. API Request + Access Token
    Resource->>AuthServer: 4. Fetch JWKS (cached)
    Resource->>Resource: 5. Validate Token
    Resource-->>Client: 6. Protected Resource

The SDK handles steps 4 and 5 automatically, fetching and caching the authorization server’s public keys, then validating token signatures and claims.

Package Entry Points

Export PathPurposeKey Exports
@authrim/serverMain entry — client, types, validators, JWKS, utilitiesAuthrimServer, ValidatedToken, BackChannelLogoutValidator
@authrim/server/providersProvider interfaces and utilitiesCryptoProvider, HttpProvider, ClockProvider, CacheProvider
@authrim/server/adapters/expressExpress middlewareauthrimMiddleware, authrimOptionalMiddleware
@authrim/server/adapters/fastifyFastify hooks and pluginsauthrimPreHandler, authrimPlugin, authrimOptionalPreHandler, authrimOptionalPlugin
@authrim/server/adapters/honoHono middlewareauthrimMiddleware, authrimOptionalMiddleware, getAuth, getAuthTokenType
@authrim/server/adapters/koaKoa middlewareauthrimMiddleware, authrimOptionalMiddleware
@authrim/server/adapters/nestjsNestJS guard and utilitiescreateAuthrimGuard, createAuthrimOptionalGuard, getAuthFromRequest, getAuthTokenTypeFromRequest

Core Features

  • JWT Access Token Validation — Signature verification, claims validation (iss, aud, exp, nbf, iat), scope enforcement
  • DPoP Proof Validation (RFC 9449) — Sender-constrained token verification with JWK Thumbprint binding
  • JWKS Management — Auto-discovery, caching with Cache-Control, key rotation support, single-flight fetch
  • Token Introspection (RFC 7662) — Query the authorization server for opaque token status
  • Token Revocation (RFC 7009) — Revoke tokens at the authorization server
  • Back-Channel Logout (OIDC 1.0) — Validate logout tokens from the authorization server
  • Framework Middleware — Ready-to-use adapters for Express, Fastify, Hono, Koa, and NestJS
  • Security Hardened — Timing-safe comparisons, alg:none rejection, SSRF protection, JWT size limits

Supported Algorithms

FamilyAlgorithms
RSA PKCS#1 v1.5RS256, RS384, RS512
RSA-PSSPS256, PS384, PS512
ECDSAES256, ES384, ES512
EdDSAEdDSA

Supported Runtimes

@authrim/server runs on any JavaScript runtime with standard Web Crypto API support:

  • Node.js 18+
  • Bun
  • Deno
  • Cloudflare Workers
  • Vercel Edge Runtime

How It Works

@authrim/server validates access tokens in three phases:

  1. Initialization — On startup, the SDK fetches the authorization server’s OIDC Discovery document and JWKS (public keys). These are cached in memory.
  2. Token Validation — For each incoming request, the SDK parses the JWT, selects the correct signing key by kid, verifies the cryptographic signature, and validates all standard claims (issuer, audience, expiration, etc.).
  3. Ongoing Key Management — The SDK monitors key freshness, handles Cache-Control headers, and automatically refetches keys when a new kid is encountered (key rotation).

All of this is encapsulated in two method calls: init() at startup and validateToken() per request.

AuthrimServer Methods

MethodDescription
init()Fetch OIDC Discovery document and JWKS. Call once at startup.
validateToken(token, options?)Validate a JWT access token and return ValidatedToken.
validateDPoP(proof, options)Validate a DPoP proof JWT (RFC 9449).
introspect(token)Query the authorization server for token status (RFC 7662).
revoke(token, tokenTypeHint?)Revoke a token at the authorization server (RFC 7009).
invalidateJwksCache()Force the next validation to refetch the JWKS.

Quick Example

import { AuthrimServer } from '@authrim/server';


const authrim = new AuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});


// Initialize once at startup (fetches JWKS)
await authrim.init();


// Validate an incoming access token
const result = await authrim.validateToken(bearerToken);


console.log(result.claims.sub);    // Subject (user ID)
console.log(result.claims.scope);  // Granted scopes
console.log(result.tokenType);     // 'Bearer' or 'DPoP'
console.log(result.expiresIn);     // Seconds until expiration

With Framework Middleware

Instead of calling validateToken() manually, use a framework adapter for automatic token extraction and validation:

import express from 'express';
import { AuthrimServer } from '@authrim/server';
import { authrimMiddleware } from '@authrim/server/adapters/express';


const app = express();
const authrim = new AuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});
await authrim.init();


// Protected route — token validated automatically
app.get('/api/me', authrimMiddleware(authrim), (req, res) => {
  res.json({ userId: req.auth.claims.sub });
});


// Protected route with required scopes
app.delete('/api/users/:id', authrimMiddleware(authrim, { requiredScopes: ['admin:write'] }), (req, res) => {
  res.json({ deleted: true });
});


app.listen(3000);

When to Use @authrim/server

ScenarioPackageDescription
Validate tokens on your API@authrim/serverThis SDK — for resource servers
Log users in via browser@authrim/webBrowser-based OAuth/OIDC flows
Full-stack SvelteKit auth@authrim/sveltekitServer hooks + Svelte stores
Build a custom OAuth client@authrim/corePlatform-agnostic protocol library

RFC Compliance

SpecificationRFCCoverage
JSON Web Token (JWT)RFC 7519Token parsing and claims validation
JSON Web Key (JWK)RFC 7517JWKS fetch, key import, key selection
JWK ThumbprintRFC 7638DPoP thumbprint computation and binding
Token IntrospectionRFC 7662Full introspection client
Token RevocationRFC 7009Full revocation client
DPoPRFC 9449Stateless proof validation, thumbprint binding
SCIMRFC 7643 / 7644Error response format support
OIDC Core 1.0—ID token and claims validation
OIDC Back-Channel Logout 1.0—Logout token validation

Next Steps