How auth-server-nest works

auth-server-nest is a thin glue layer. Heavy lifting (JWT validation, transport, error mapping) lives in auth-server-ts. What this package adds is DI wiring + decorators that fit Nest’s metadata-driven model.

Module wiring

AuthClientModule.forRoot(options) returns a global module so every feature module can inject TokenValidatorService without importing AuthClientModule again. Internally it constructs:

AUTH_CLIENT_OPTIONS  ─► provider with the raw options
AUTH_CLIENT_REDIS    ─► optional Redis client (consumer-provided)
TokenValidator       ─► JwtValidator from auth-server-ts
HttpTransport        ─► AxiosHttpTransportAdapter
RevocationCache      ─► RedisTokenCacheAdapter (if AUTH_CLIENT_REDIS set)
                       or NullRevocationCache (otherwise)
AuthClient           ─► composed facade from auth-server-ts
TokenValidatorService
ServiceAuthClient
AuthHttpClient
PermissionRegistrarService

Guards

`JwtAuthGuard`

Reads the Authorization header, calls TokenValidatorService.validate, sets req.principal (or req.user) to the decoded principal. Opts out on routes/classes marked @Public().

Apply globally:

{ provide: APP_GUARD, useClass: JwtAuthGuard }

`RolesGuard`

Reads @Roles('a', 'b') metadata. Allows only if the principal’s roles array intersects the required set. system_admin bypasses always.

`PermissionsGuard`

Reads @Permissions('orders:read') metadata. Allows only if the principal’s permissions array includes the required code.

`ServiceOnlyGuard`

Reads @ServiceOnly() metadata. Allows only when principal.tokenType === 'service' — i.e. the bearer is a service principal from /oauth/token (m2m client_credentials), not a user token.

Decorators

Decorator	Purpose
`@Public()`	Opts out of `JwtAuthGuard` (for `/health`, `/metrics`, etc.).
`@CurrentUser()`	Param decorator returning `AuthenticatedUser \| ServicePrincipal`.
`@Roles('a', 'b')`	Requires the principal to have at least one of the listed roles.
`@Permissions('x:y')`	Requires the principal to hold a specific permission code.
`@ServiceOnly()`	Restricts the route to service principals only.

Bundled transport adapter

AxiosHttpTransportAdapter wraps the auth-server-ts HttpTransport port over Axios. It picks up Accept-Encoding, redirects, and sane defaults. Override per request via transport.request({ headers }).

You can swap it out by passing your own transport in the module options if your service uses got, undici, or another HTTP client.

Bundled cache adapter

RedisTokenCacheAdapter implements the RevocationCache port over either ioredis or node-redis. Provide the client via the AUTH_CLIENT_REDIS DI token:

{
    provide: AUTH_CLIENT_REDIS,
    useExisting: REDIS_CLIENT, // your existing Redis instance
}

Without a Redis provider, the module falls back to NullRevocationCache (signature-only validation; cross-replica token-version invalidation won’t take effect).

Permission registration

If permissions: { manifest } is passed to AuthClientModule.forRoot, the module’s OnApplicationBootstrap calls PermissionRegistrarService.register() once at boot — POSTs the manifest to /admin/permissions/register using the m2m service credentials. Idempotent.

Error propagation

Every VenAuthException thrown by guards / decorators is converted to a HttpException with the matching status code. The default mapping:

Exception	HTTP
`TokenExpiredException`, `TokenInvalidException`, `TokenRevokedException`, `InvalidCredentialsException`, `UnauthorizedException`	401
`ForbiddenException`	403
`NotFoundException`	404
`ConflictException`	409
`ValidationException`	422
`RateLimitedException`	429
`ServerException`, `NetworkException`	502

Override via a global exception filter if you need a different shape.