@kolaylogin/backend

Server-side SDK for verifying KolayLogin sessions in Node.js backends. Built for Express, Fastify, Nest, Koa, Hono, bare http, or anything that exposes a standard cookie header.

What it does

• Verifies the short-lived __session JWT issued by a KolayLogin instance against its JWKS endpoint.
• Parses Cookie headers and extracts the session JWT without you having to touch cookie-parsing middleware.
• Returns fully-typed session claims: sub (user id), sid (session id), env (environment id), plus any custom claims your instance has attached.

It does not perform user creation, password flows, or OAuth redirects — those belong on the instance API and in the browser SDK (@kolaylogin/react, @kolaylogin/nextjs). This package exists so your backend can trust a request without a round-trip to the auth service on every call.

Install

npm install @kolaylogin/backend
# or within the monorepo
npm install -w @kolaylogin/backend

Requires Node 20+.

Quick start

import { KolayLoginBackendClient } from '@kolaylogin/backend';

const kl = new KolayLoginBackendClient({
  baseUrl: process.env.KL_API_BASE_URL!,       // e.g. https://auth.example.com
  issuer: process.env.KL_JWT_ISSUER,           // matches the instance `iss`
  audience: process.env.KL_JWT_AUDIENCE,       // optional
});

// Express
app.get('/api/me', async (req, res) => {
  const session = await kl.getSessionFromRequest(req);
  if (!session) return res.status(401).json({ error: 'unauthenticated' });

  res.json({
    userId: session.sub,
    sessionId: session.sid,
    environment: session.env,
  });
});

The client fetches and caches JWKS the first time you verify a token. JWKS rotation is picked up automatically on cache expiry — you do not need to restart your service after a key rotation on the auth side.

API

new KolayLoginBackendClient(options)

| Option | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------------------------------------------- | | baseUrl | string | yes | Instance API base URL. JWKS is discovered at ${baseUrl}/.well-known/jwks.json. | | issuer | string | no | Expected iss claim. Strongly recommended in production. | | audience | string | no | Expected aud claim, if your instance sets it. |

client.verifySessionJwt(token)

Verifies the token against the instance's JWKS and returns the claims. Throws if the token is invalid, expired, or signed by an unknown key.

client.getSessionFromRequest(req)

Pulls the __session cookie out of req.headers.cookie, then verifies it. Returns null when no cookie is present. Throws on an invalid token so your error middleware can decide how to respond.

Low-level helpers

• parseCookieHeader(header) — returns a plain Record<string, string>.
• getSessionJwtFromCookieHeader(header) — returns the __session JWT or null.
• verifySessionJwt(token, options) — standalone verifier if you prefer not to use the class.

How sessions work (short version)

KolayLogin uses a two-cookie design:

• __client (httpOnly, long-lived) holds the refresh-capable session reference. It never leaves the browser → auth-API roundtrip.
• __session (readable by JS, ~60s TTL) is a signed JWT your services verify locally. Short lifetime means a revoked session stops working within the skew window without you having to hit the auth API.

This package is the "verify __session locally" half. The browser SDK handles the refresh loop.

Error handling

jose-thrown errors bubble up with their original names (JWSSignatureVerificationFailed, JWTExpired, etc.). Production services should log the error class, not the token, and return a generic 401 to the client.

License

MIT