Types & Interfaces
Types & Interfaces
All types are exported from the package root:
import type { OidcConfig, OidcUserContext, OidcFeatures } from "ioserver-oidc";
OidcConfig
Runtime configuration for the OIDC middleware set. Typically provided by OidcConfigManager (read from environment variables) or built manually when calling verifyOidcToken directly.
interface OidcConfig {
/** Public base URL of auth-service. Example: "https://auth.example.com" */
readonly authServiceUrl: string;
/** OAuth2 client_id / application slug. Used to validate the `aud` claim. */
readonly appSlug: string;
/** Override the JWKS URI. Defaults to "<authServiceUrl>/api/auth/jwks". */
readonly jwksUri?: string;
/** Override the expected `iss` claim. Defaults to authServiceUrl. */
readonly issuer?: string;
}
| Field | Required | Description |
|---|---|---|
authServiceUrl | Yes | Base URL without trailing slash |
appSlug | Yes | Must match aud in the JWT |
jwksUri | No | Full URL to the JWKS endpoint |
issuer | No | Expected iss claim value |
OidcUserContext
Auth context returned by verifyOidcToken and injected by the middlewares onto request / socket.
interface OidcUserContext {
/** Internal user ID — local DB record (after findOrCreate); falls back to sub. */
userId: string;
/** OIDC sub claim — stable auth-service user identifier. */
sub: string;
/** Email from JWT `email` claim. Null if the claim is absent. */
email: string | null;
/** Display name from JWT `name` claim. Null if the claim is absent. */
name: string | null;
/** Primary role — roles[0] or "user" when roles is empty. */
userRole: string;
/** Full roles array from the JWT `roles` claim. */
roles: string[];
/** Permission strings from the JWT `permissions` claim. */
permissions: string[];
/** Feature flags and limits from the JWT `features` claim. */
features: OidcFeatures;
}
OidcFeatures
Application-defined map of feature flags and resource limits decoded from the features JWT claim. The shape is not enforced by the package — cast it to a more specific type in your application.
type OidcFeatures = Record<string, unknown>;
Example application-specific type:
import type { OidcFeatures } from "ioserver-oidc";
interface AppFeatures extends OidcFeatures {
maxProjects: number;
canExport: boolean;
tier: "free" | "pro" | "enterprise";
}
// In a controller or service:
const features = request.features as AppFeatures;
if (!features.canExport) {
reply.code(403).send({ error: "Export not available on your plan" });
}
Augmenting Fastify and Socket.IO types
For full type safety without casting to any, augment the Fastify and Socket.IO type declarations in your application:
// src/types/ioserver-oidc.d.ts
import "fastify";
import type { OidcFeatures } from "ioserver-oidc";
declare module "fastify" {
interface FastifyRequest {
sub: string;
userId: string;
userRole: string;
roles: string[];
permissions: string[];
features: OidcFeatures;
}
}
declare module "socket.io" {
interface Socket {
sub: string;
userId: string;
userRole: string;
roles: string[];
permissions: string[];
features: OidcFeatures;
}
}
Add the declaration file to your tsconfig.json includes and the properties will be fully typed in every controller and service method.