@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