@armco/iam-server

Server-side JWT validation and middleware for IAM.

Installation

npm install @armco/iam-server

Quick Start

Standalone Verifier

import { createIAMVerifier } from '@armco/iam-server';

const verifier = createIAMVerifier({
  issuer: 'http://localhost:5000',
  audience: 'my-api',
});

// Verify a token
const result = await verifier.verify(token);
if (result.valid) {
  console.log('User ID:', result.payload.sub);
  console.log('Email:', result.payload.email);
  console.log('Roles:', result.payload.roles);
}

// Or authenticate and get structured user info
const user = await verifier.authenticate(token);
if (user) {
  console.log(user.id, user.email, user.roles, user.scopes);
}

Express Middleware

import express from 'express';
import { createAuthMiddleware, requireRole } from '@armco/iam-server/express';

const app = express();

// Create auth middleware
const auth = createAuthMiddleware({
  issuer: 'http://localhost:5000',
  audience: 'my-api',
});

// Protect all /api routes
app.use('/api', auth());

// Access user in handlers
app.get('/api/profile', (req, res) => {
  res.json({
    id: req.user.id,
    email: req.user.email,
    roles: req.user.roles,
  });
});

// Require specific role
app.get('/api/admin', auth({ roles: ['admin'] }), (req, res) => {
  res.json({ message: 'Admin access granted' });
});

// Require specific scope
app.get('/api/data', auth({ scopes: ['read:data'] }), (req, res) => {
  res.json({ data: '...' });
});

// Or use standalone middleware
app.delete('/api/users/:id', auth(), requireRole('admin'), handler);

Configuration

interface IAMServerConfig {
  /** IAM server base URL */
  issuer: string;
  /** Expected audience (your app's client_id) */
  audience: string;
  /** Cache JWKS keys (default: true) */
  cacheKeys?: boolean;
  /** JWKS cache TTL in seconds (default: 3600) */
  cacheTTL?: number;
  /** Required scopes for all requests */
  requiredScopes?: string[];
  /** Custom claim to extract user ID from (default: 'sub') */
  userIdClaim?: string;
}

API Reference

IAMVerifier

Method	Description
verify(token)	Verify JWT, returns { valid, payload?, error? }
authenticate(token)	Verify and return AuthenticatedUser or null
hasRole(user, roles)	Check if user has any of the roles
hasAllRoles(user, roles)	Check if user has all roles
hasScope(user, scopes)	Check if user has any of the scopes
hasAllScopes(user, scopes)	Check if user has all scopes
clearCache()	Force JWKS refresh on next verify

Express Middleware

Function	Description
createAuthMiddleware(config)	Create auth middleware factory
auth(options?)	Middleware that requires valid token
requireRole(roles)	Middleware to check roles (use after auth)
requireScope(scopes)	Middleware to check scopes (use after auth)
createOptionalAuthMiddleware(config)	Attaches user if token present, doesn't require it

AuthenticatedUser

interface AuthenticatedUser {
  id: string;        // Global identity ID (from 'sub')
  userId?: string;   // Tenant-specific user ID
  tenantId?: string; // Tenant ID
  email?: string;
  username?: string;
  roles: string[];
  scopes: string[];
  claims: JWTPayload; // Raw JWT payload
}

Development

cd packages/iam-server
npm install
npm run build
npm run dev  # Watch mode