Skip to content
Vendidit Auth

auth-server-ts overview

@vendidit/auth-server-ts is the framework-agnostic TypeScript core for backend services that need to validate auth-server JWTs. Top-level AuthClient facade composing JwtValidator (HS256 + secret rotation + JTI blacklist + per-user token-version gate), HttpTransport, SessionStore, Clock. Flows covers the full HTTP surface.

SourceVendidit/auth-server-ts
StackTypeScript 5+ · Node 20+ · jsonwebtoken
Companionauth-server-nest (NestJS adapter)
Mirrorauth-server-php (PHP equivalent, same structure)

When to use this directly

  • You’re on Fastify / Express / vanilla Node / Bun / Deno / edge runtime.
  • You’re building a custom NestJS integration that doesn’t fit auth-server-nest’s shape.
  • You need to wire AuthClient into a non-HTTP context (CLI, queue worker, scheduled job).

If you’re on NestJS, install auth-server-nest instead — it wraps this core in @Injectable() providers, guards, and decorators.

The 80% usage

import {
    AuthClient,
    HttpTransport,
    JwtValidator,
    InMemorySessionStore,
    SystemClock,
} from '@vendidit/auth-server-ts';


const auth = new AuthClient({
    config: { authServerUrl: 'https://auth.vendidit.com', appCode: 'orders-api' },
    transport: new HttpTransport({ baseUrl: 'https://auth.vendidit.com/api/v1' }),
    validator: new JwtValidator({
        secret: process.env.JWT_ACCESS_SECRET!,
        issuer: 'ven-auth',
        audience: 'ven-platform',
    }),
    session: new InMemorySessionStore(),
    clock: new SystemClock(),
});


// Fastify / Express middleware
app.use(async (req, res, next) => {
    try {
        const principal = await auth.validateBearer(req.headers.authorization);
        req.user = principal;
        next();
    } catch (err) {
        res.status(401).send({ error: err.code });
    }
});

What it gives you

  • AuthClient facade — the recommended entry point. Composes the ports into validateBearer, login, register, refresh, logout, me, authenticatedRequest.
  • Flows — extended endpoint surface: SSO + PKCE, magic link, email verification, password lifecycle, 2FA, sessions, admin lookup/ impersonate, audit log, invitations, m2m, permission registration.
  • JwtValidator — local HS256 validation with secret rotation, JTI blacklist, per-user token-version gate.
  • Bundled adapter impls — HttpTransport (fetch), InMemoryTransport (test), NullRevocationCache, InMemoryRevocationCache, InMemorySessionStore, SystemClock, FixedClock.
  • 15-class typed exception hierarchy rooted at VenAuthException: TokenExpiredException, TokenRevokedException, InvalidCredentialsException, TwoFactorRequiredException, RateLimitedException, ServerException, NetworkException, etc.
  • Port contracts in ./contracts — implement your own adapters if the bundled ones don’t fit (e.g. RedisRevocationCache for shared revocation across replicas).