ioserver-oidc

OIDC/OAuth2 JWT middleware set for IOServer.
Protects Fastify HTTP routes and Socket.IO namespaces by verifying access tokens issued by auth-service (BetterAuth + OAuth2 provider) via remote JWKS — zero secret storage on the application side.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Environment variables
• API reference
  • OidcConfigManager
  • OidcHttpMiddleware
  • OidcSocketMiddleware
  • OidcSocketAdminMiddleware
  • verifyOidcToken
  • Types
• Request / socket context
• Error codes
• Security notes
• Contributing
• License

Features

• ✅ Verifies RS256 / ES256 JWT access tokens via remote JWKS (no secret distribution)
• ✅ Validates iss, aud, and expiry claims
• ✅ In-process JWKS key cache — one HTTP round-trip per key rotation
• ✅ Auto-provisions local user records via appHandle.users.findOrCreate(...)
• ✅ Rejects disabled accounts (403)
• ✅ Injects sub, userId, userRole, roles, permissions, features on every authenticated request/socket
• ✅ Admin role guard for Socket.IO namespaces
• ✅ Full TypeScript declarations; ESM-only

Requirements

| Dependency | Version | | ---------- | ------- | | Node.js | ≥ 20 | | ioserver | ≥ 2.0.0 | | jose | ≥ 6.0.0 |

Installation

# npm
npm install ioserver-oidc

# pnpm
pnpm add ioserver-oidc

# yarn
yarn add ioserver-oidc

jose is bundled as a direct dependency — no extra installation required.

Quick start

1. Register the config manager

import {
  OidcConfigManager,
  OidcHttpMiddleware,
  OidcSocketMiddleware,
  OidcSocketAdminMiddleware,
} from "ioserver-oidc";
import { IOServer } from "ioserver";

const server = new IOServer({
  /* your IOServer options */
});

// Reads AUTH_SERVICE_URL + AUTH_SERVICE_APP_SLUG from process.env
server.addManager({ name: "oidcConfig", manager: OidcConfigManager });

2. Protect HTTP controllers

server.addController({
  name: "profile",
  controller: ProfileController,
  middlewares: [OidcHttpMiddleware], // ← JWT-required
  prefix: "/profile",
});

3. Protect Socket.IO services

// Any authenticated user
server.addService({
  name: "chat",
  service: ChatService,
  middlewares: [OidcSocketMiddleware],
});

// Admin-only namespace
server.addService({
  name: "users",
  service: UserService,
  middlewares: [OidcSocketMiddleware, OidcSocketAdminMiddleware],
});

4. Read the injected context in your handlers

// HTTP (Fastify)
fastify.get("/me", async (request) => {
  const req = request as any;
  return { userId: req.userId, role: req.userRole };
});

// Socket.IO
socket.on("ping", () => {
  console.log(socket.userId, socket.userRole);
});

Environment variables

| Variable | Required | Default | Description | | ----------------------- | -------- | ---------------------------------- | --------------------------------------------------------------------- | | AUTH_SERVICE_URL | ✅ | — | Public base URL of your auth-service. E.g. https://auth.example.com | | AUTH_SERVICE_APP_SLUG | ✅ | — | OAuth2 client_id / app slug registered in auth-service | | AUTH_SERVICE_JWKS_URI | ❌ | <AUTH_SERVICE_URL>/api/auth/jwks | Override the JWKS endpoint | | AUTH_SERVICE_ISSUER | ❌ | <AUTH_SERVICE_URL> | Override the expected iss claim |

All variables are read once at server startup by OidcConfigManager.start().
If OidcConfigManager is not registered, each middleware reads the same variables lazily on first request (without caching between restarts).

API reference

OidcConfigManager

Extends BaseManager. Reads environment variables and exposes the resolved OidcConfig to sibling middlewares via appHandle.oidcConfig.getConfig().

server.addManager({ name: "oidcConfig", manager: OidcConfigManager });

The name must be "oidcConfig" — the middlewares look for appHandle.oidcConfig by that exact key.

OidcHttpMiddleware

Extends BaseMiddleware. Verifies the Authorization: Bearer <token> header on every inbound Fastify request.

Flow:

1. Extracts the Bearer token from Authorization header
2. Verifies JWT signature via JWKS (iss + aud + expiry)
3. Calls appHandle.users.findOrCreate(sub, { email, name }) if available
4. Rejects disabled accounts with 403
5. Injects auth context onto the request object

Returns 401 on missing/invalid tokens, 403 on disabled accounts, 500 if user provisioning fails.

OidcSocketMiddleware

Same as OidcHttpMiddleware but for Socket.IO connections.

Token is read from (in order):

1. socket.handshake.auth.token — preferred, set by the Vue/web client
2. socket.handshake.headers.authorization (Bearer prefix) — fallback

Calls appHandle.session.registerSocket(userId, socketId, sub) when the session manager is available.

Rejects with new Error("ERR_AUTH_TOKEN_REQUIRED") or "ERR_AUTH_TOKEN_INVALID" on failure.

OidcSocketAdminMiddleware

Role guard. Must be placed after OidcSocketMiddleware in the middlewares array (relies on socket.roles/socket.userRole being already set).

Rejects with new Error("ERR_FORBIDDEN") when the user does not hold the "admin" role.

verifyOidcToken

Low-level function — use this if you need to verify a token outside of the IOServer middleware system.

import { verifyOidcToken } from "ioserver-oidc";

const ctx = await verifyOidcToken(rawJwt, {
  authServiceUrl: "https://auth.example.com",
  appSlug: "my-app",
});
// ctx → OidcUserContext

Throws a jose JWTVerifyError (or subclass) on any verification failure.

Types

import type { OidcConfig, OidcUserContext, OidcFeatures } from "ioserver-oidc";

OidcConfig

interface OidcConfig {
  authServiceUrl: string; // e.g. "https://auth.example.com"
  appSlug: string; // OAuth2 client_id (= app slug)
  jwksUri?: string; // Override JWKS endpoint
  issuer?: string; // Override expected `iss` claim
}

OidcUserContext

interface OidcUserContext {
  userId: string; // Local DB user ID (after findOrCreate)
  sub: string; // OIDC sub claim
  email: string | null;
  name: string | null;
  userRole: string; // First element of roles[], fallback "user"
  roles: string[];
  permissions: string[];
  features: OidcFeatures; // Record<string, unknown>
}

Request / socket context

After successful authentication the following properties are available:

| Property | Type | Source | | ------------- | ------------------------ | ----------------------- | | sub | string | JWT sub claim | | userId | string | Local DB users.id | | userRole | string | roles[0] or "user" | | roles | string[] | JWT roles claim | | permissions | string[] | JWT permissions claim | | features | Record<string,unknown> | JWT features claim |

In TypeScript, cast the Fastify request or Socket.IO socket to any (or augment the types in your app) to access these properties.

Error codes

| Code | HTTP / Socket | Meaning | | --------------------------- | ------------- | ------------------------------------------ | | ERR_AUTH_TOKEN_REQUIRED | 401 / reject | No Authorization header or auth token | | ERR_AUTH_TOKEN_INVALID | 401 / reject | JWT signature / claims verification failed | | ERR_USER_DISABLED | 403 | User account is disabled in the local DB | | ERR_USER_PROVISION_FAILED | 500 | findOrCreate threw an error | | ERR_FORBIDDEN | — / reject | User lacks the required role |

Security notes

• Access tokens are never stored — they are verified in-memory on every request/connection using the cached JWKS.
• JWKS keys are fetched lazily and cached per URI. The jose library automatically re-fetches keys on signature verification failure (key rotation) with a minimum 5-minute cooldown.
• The aud (audience) claim is always validated against OidcConfig.appSlug to prevent token substitution attacks between different applications sharing the same auth-service instance.
• The iss (issuer) claim is validated against OidcConfig.authServiceUrl (or the explicit override).

Contributing

1. Fork the repo and create a branch: git checkout -b feat/my-feature
2. Make your changes (TypeScript in src/)
3. Build: pnpm run build
4. Open a Pull Request against main

License

MIT © 2026 x42en