Session model

KavachOS has three session types:

Cookie sessions for human users in browsers. A signed JWT sits in an httpOnly cookie. The session record lives in your database so you can revoke it instantly.
JWT sessions for SPAs, mobile apps, and server-to-server flows. Stateless access tokens paired with rotating refresh tokens.
Ephemeral agent sessions for AI agents (Claude, GPT-with-browsing, operator loops). Short-lived, budget-bounded credentials that expire by time or action count, whichever comes first.

This page covers cookie sessions and JWT sessions. For ephemeral agent sessions see the agents guide.

Configure the session manager

Pass createCookieSessionManager a config object and your kavach.db instance. The manager handles creation, validation, refresh, and revocation.

lib/kavach.ts

import { createKavach } from 'kavachos';
import { createCookieSessionManager } from 'kavachos/auth'; 

export const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
});

export const sessions = createCookieSessionManager({ 
  sessionName: 'kavach_session', 
  maxAge: 7 * 24 * 60 * 60, // 7 days in seconds
  autoRefresh: true, 
  cookie: {
    httpOnly: true, 
    secure: true, 
    sameSite: 'lax', 
    path: '/',
  },
}, kavach.db);

Call createSession with a user ID after your authentication logic succeeds. The response includes the cookie header to send back to the browser.

routes/sign-in.ts

import { sessions } from '@/lib/kavach';

export async function POST(req: Request): Promise<Response> {
  // ... validate credentials, look up user

  const result = await sessions.createSession(user.id, { 
    metadata: {
      ipAddress: req.headers.get('x-forwarded-for') ?? 'unknown',
      userAgent: req.headers.get('user-agent') ?? 'unknown',
    },
  });

  if (!result.success) {
    return Response.json({ error: result.error }, { status: 500 });
  }

  return Response.json(
    { user: { id: user.id, email: user.email } },
    {
      status: 200,
      headers: { 'Set-Cookie': result.data.setCookieHeader }, 
    },
  );
}

Validate on each request

Read the cookie from the incoming request and validate it. If valid, the session data is returned. If expired or revoked, success is false.

middleware.ts

import { sessions } from '@/lib/kavach';

export async function middleware(req: Request): Promise<Response | null> {
  const cookieHeader = req.headers.get('cookie') ?? '';
  const result = await sessions.validateSession(cookieHeader); 

  if (!result.success) {
    return Response.json({ error: result.error }, { status: 401 });
  }

  const { session } = result.data; 
  // session.userId, session.createdAt, session.expiresAt, session.metadata
  return null; // continue
}

When autoRefresh: true, validating a session that is more than halfway through its lifetime automatically extends it. The response from validateSession includes a refreshedCookieHeader field when a refresh occurred. Forward it in your response.

middleware.ts

const result = await sessions.validateSession(cookieHeader);

if (result.success && result.data.refreshedCookieHeader) {
  response.headers.set('Set-Cookie', result.data.refreshedCookieHeader); 
}

Revoke on sign-out

Revoking a session removes it from the database immediately. Any subsequent validation attempt returns SESSION_REVOKED.

routes/sign-out.ts

import { sessions } from '@/lib/kavach';

export async function POST(req: Request): Promise<Response> {
  const cookieHeader = req.headers.get('cookie') ?? '';
  const result = await sessions.validateSession(cookieHeader);

  if (result.success) {
    await sessions.revokeSession(result.data.session.id); 
  }

  return new Response(null, {
    status: 204,
    headers: { 'Set-Cookie': sessions.clearCookieHeader() }, 
  });
}

JWT sessions

Use JWT sessions when cookies don’t work: SPAs calling a separate API origin, mobile apps, server-to-server flows. Access tokens are short-lived and stateless. Refresh tokens are opaque random strings stored as SHA-256 hashes, and they rotate on every use.

lib/kavach.ts

import { createJwtSessionModule } from 'kavachos/auth'; 

export const jwtSessions = createJwtSessionModule({
  secret: process.env.SESSION_SECRET!, // HS256 by default
  issuer: 'https://auth.example.com', 
  audience: 'https://app.example.com',
  accessTokenTtl: 900, // 15 minutes
  refreshTokenTtl: 604_800, // 7 days
  customClaims: (user) => ({ role: user.role, orgId: user.orgId }), 
}, kavach.db);

Create a session

routes/sign-in.ts

const result = await jwtSessions.createSession({
  id: user.id,
  email: user.email,
  name: user.name,
});

if (!result.success) {
  return Response.json({ error: result.error }, { status: 500 });
}

const { accessToken, refreshToken, expiresIn } = result.data; 
// Store refreshToken in an httpOnly cookie or secure storage
// Send accessToken to the client for use in Authorization headers

Verify on each request

Access token verification is stateless. No database round-trip.

middleware.ts

const authHeader = req.headers.get('authorization') ?? '';
const token = authHeader.replace('Bearer ', '');

const result = await jwtSessions.verifySession(token); 

if (!result.success) {
  return Response.json({ error: result.error }, { status: 401 });
}

const { userId, email, claims } = result.data; 

Refresh

Calling refreshSession marks the old refresh token as used and issues a new access + refresh pair. Each refresh rotates the token, so a stolen token is invalidated the moment the legitimate client refreshes.

routes/refresh.ts

const result = await jwtSessions.refreshSession(refreshToken); 

if (!result.success) {
  // REFRESH_TOKEN_EXPIRED, REFRESH_TOKEN_USED, REFRESH_TOKEN_NOT_FOUND
  return Response.json({ error: result.error }, { status: 401 });
}

const { accessToken, refreshToken: newRefreshToken, expiresIn } = result.data;
// Return newRefreshToken to the client to replace the old one

If refreshSession returns REFRESH_TOKEN_USED, a previously-used token was replayed. This is a strong signal that the refresh token was stolen. Revoke all sessions for the affected user and force re-authentication.

Session freshness

Some operations should require that the user authenticated recently, not just that they hold any valid session. Changing a password, registering a passkey, or modifying billing details are examples where a session from 6 days ago is not good enough even though it is technically valid. createSessionFreshnessModule wraps this check. When a session is older than freshAge seconds, it returns a 403 response with code SESSION_STALE. Your handler returns it directly.

lib/freshness.ts

import { createSessionFreshnessModule } from 'kavachos'; 

export const freshness = createSessionFreshnessModule({
  freshAge: 300, // 5 minutes
});

Use it in any endpoint that needs re-authentication assurance:

routes/change-password.ts

import { sessions } from '@/lib/kavach';
import { freshness } from '@/lib/freshness';

export async function POST(req: Request): Promise<Response> {
  const cookieHeader = req.headers.get('cookie') ?? '';
  const result = await sessions.validateSession(cookieHeader);

  if (!result.success) {
    return Response.json({ error: result.error }, { status: 401 });
  }

  const staleResponse = freshness.guard(result.data.session); 
  if (staleResponse) return staleResponse; // 403 SESSION_STALE if too old

  // Session is fresh, safe to proceed with the sensitive operation
  // ...
}

When the client receives SESSION_STALE, redirect them to a lightweight re-authentication page (password confirmation, passkey prompt, or similar) rather than a full sign-out. After re-auth succeeds, refresh the session’s createdAt timestamp by issuing a new session, then retry the original operation.

The freshAge threshold is separate from maxAge. A session can be well within its 7-day lifetime but still be considered stale for sensitive operations. Keep freshAge short. 5 to 15 minutes is typical.

CSRF protection

Cookie-based sessions are vulnerable to cross-site request forgery unless you add a second layer. KavachOS uses the double-submit cookie pattern: a random token is set in a separate readable cookie and must also appear in the request body or header. An attacker’s page can trigger the cookie but cannot read it to reproduce the header value.

lib/csrf.ts

import { generateCsrfToken, validateCsrfToken, validateOrigin } from 'kavachos'; 

// On page load or sign-in response, set a CSRF cookie
const csrfToken = generateCsrfToken(); 
// Return it in a Set-Cookie header: SameSite=Strict, NOT httpOnly
// Also send it in the response body so the client can store it

// On each mutating request (POST, PUT, DELETE, PATCH)
const headerToken = req.headers.get('x-csrf-token') ?? '';
const cookieToken = parseCookies(req.headers.get('cookie') ?? '')['kavach_csrf'] ?? '';

const valid = validateCsrfToken(headerToken, cookieToken); 
if (!valid) {
  return Response.json(
    { error: { code: 'CSRF_INVALID', message: 'CSRF token mismatch' } },
    { status: 403 },
  );
}

// Also validate the Origin header to defend against subdomain takeover
const originOk = validateOrigin(req, ['https://app.example.com']); 
if (!originOk) {
  return Response.json(
    { error: { code: 'ORIGIN_MISMATCH', message: 'Request origin not allowed' } },
    { status: 403 },
  );
}

The CSRF cookie must not be httpOnly. It needs to be readable by JavaScript so the client can include its value in the x-csrf-token request header. Set it as SameSite=Strict instead.

Revocation patterns

Single session
All sessions
All except current

Revoke one session

// Revoke by session ID. Use this for "sign out this device"
await sessions.revokeSession(sessionId); 

Revoke all sessions for a user

// Full sign-out. Use this after a password reset or account compromise
await sessions.revokeAllSessions(userId); 

Password reset automatically calls revokeAllSessions for you when using the emailPassword plugin. You only need to call this directly when handling a security event (suspicious login, compromised credential detected, etc.).

Revoke all other sessions

// Keep the current session, revoke everything else
// The session ID of the current request comes from validateSession
const { session } = result.data;
await sessions.revokeAllSessionsExcept(userId, session.id); 

This is the “sign out everywhere else” pattern, common in account security settings.

Session metadata

Store arbitrary data on a session at creation time or update it later. Useful for tracking the device, IP address, or a custom attribute your app needs.

Creating a session with metadata

const result = await sessions.createSession(userId, {
  metadata: { 
    ipAddress: req.headers.get('x-forwarded-for') ?? 'unknown', 
    userAgent: req.headers.get('user-agent') ?? 'unknown', 
    deviceType: parseDeviceType(req.headers.get('user-agent')), 
    appVersion: req.headers.get('x-app-version'), 
  },
});

Read it back when you validate:

Reading session metadata

const result = await sessions.validateSession(cookieHeader);

if (result.success) {
  const { session } = result.data;
  console.log(session.metadata.deviceType, session.metadata.ipAddress);
}

Metadata is stored as a JSON column. It is not indexed, so avoid querying sessions by metadata fields. If you need to look up sessions by device or IP, store those in a separate indexed column via a custom schema extension.

Human sessions vs agent tokens

	Human sessions	Agent tokens
Format	Signed JWT in `httpOnly` cookie	`kv_...` bearer token
Lifetime	7 days (configurable)	24 hours (configurable)
Storage	Database row	SHA-256 hash in database
Revocation	Per-session or per-user bulk	Per-agent
CSRF	Required (cookie-based)	Not needed (header-based)
Freshness guard	Yes, for sensitive operations	N/A
Action budget	No	Yes (ephemeral sessions)

Agent tokens use a kv_ prefix and are stored only as a SHA-256 hash. The raw token is shown once at creation and cannot be recovered. If a token is lost, issue a new one.

Error codes

Code	Status	Meaning
`SESSION_NOT_FOUND`	401	No session record matches the provided token
`SESSION_EXPIRED`	401	Session exceeded its `maxAge`
`SESSION_REVOKED`	401	Session was explicitly revoked
`SESSION_STALE`	403	Session is valid but older than `freshAge`
`CSRF_INVALID`	403	CSRF token in header does not match cookie value
`ORIGIN_MISMATCH`	403	Request `Origin` header not in the allowed list
`REFRESH_TOKEN_NOT_FOUND`	401	Refresh token does not exist in the database
`REFRESH_TOKEN_USED`	401	Refresh token was already exchanged (possible replay)
`REFRESH_TOKEN_EXPIRED`	401	Refresh token lifetime has elapsed
`CREATE_SESSION_FAILED`	500	Database error during session creation

Configuration reference

CookieSessionConfig

string

default:"'kavach_session'"

Name of the session cookie.

number

default:"604800 (7 days)"

Session lifetime in seconds. After this period the session is considered expired even if it has been used recently.

boolean

default:"true"

Automatically extend the session when validation is called and more than half the lifetime has elapsed.

Prevents client-side JavaScript from accessing the cookie. Always set this to true for session cookies.

Only send the cookie over HTTPS. Must be true in production.

Controls cross-site cookie behavior. ‘lax’ works for most apps. ‘strict’ adds more protection. ‘none’ is only for cross-origin cookie transport (requires secure: true).

Restricts the cookie to a URL path prefix.

Set a cookie domain to share sessions across subdomains. Omit for single-domain apps.

JwtSessionConfig

string | CryptoKey | JsonWebKey

required

Signing secret. A string uses HMAC-SHA256 and must be at least 32 characters. Pass a CryptoKey or JsonWebKey for asymmetric algorithms (RS256, ES256).

string

default:"'HS256'"

JWT signing algorithm. Inferred from the secret type when not set: ‘HS256’ for strings, ‘RS256’ for RSA keys, ‘ES256’ for EC keys.

number

default:"900 (15 min)"

Access token lifetime in seconds. Keep this short. Access tokens are stateless and cannot be revoked before expiry.

number

default:"604800 (7 days)"

Refresh token lifetime in seconds. Refresh tokens are stored hashed and can be revoked immediately.

string

default:"undefined"

Value for the JWT ‘iss’ claim. Validated on every verify call.

string

default:"undefined"

Value for the JWT ‘aud’ claim. Validated on every verify call.

default:"undefined"

Function called at token creation to attach extra claims to the access token payload.

SessionFreshnessConfig

number

default:"300 (5 min)"

Maximum session age in seconds before a sensitive operation requires re-authentication. The freshness guard returns 403 SESSION_STALE when the session is older than this.

Security best practices

Always set cookie.httpOnly: true and cookie.secure: true in production. Without httpOnly, a single XSS vulnerability lets an attacker read the session cookie directly. Without secure, the cookie travels over plain HTTP and can be intercepted on any network path.

Rotate KAVACH_SECRET periodically. All existing sessions signed with the old secret become invalid when you rotate. Plan for a brief period where some users need to sign in again, or run with two active secrets during the transition window.

Set cookie.sameSite: 'lax' for most apps. 'lax' allows the cookie to be sent on top-level navigations (clicking a link) but blocks it on cross-origin subresource requests, which stops most CSRF attacks without breaking OAuth redirect flows. Only use 'strict' if you have no external links that expect to land in an authenticated state.

Short access token TTLs (accessTokenTtl) reduce the window of exposure for a stolen token, but they increase refresh traffic. 15 minutes is a reasonable default. If you need to revoke access instantly (account ban, credential compromise), route your API through the session validation middleware instead of relying solely on stateless JWT verification.

Start here

Setup

Sessions

Configure the session manager

Validate on each request

Revoke on sign-out

JWT sessions

Create a session

Verify on each request

Refresh

Session freshness

CSRF protection

Revocation patterns

Session metadata

Human sessions vs agent tokens

Error codes

Configuration reference

CookieSessionConfig

JwtSessionConfig

SessionFreshnessConfig

Security best practices

​Cookie sessions

​Configure the session manager

​Create a session after sign-in

​Validate on each request

​Revoke on sign-out

​JWT sessions

​Create a session

​Verify on each request

​Refresh

​Session freshness

​CSRF protection

​Revocation patterns

​Session metadata

​Human sessions vs agent tokens

​Error codes

​Configuration reference

​CookieSessionConfig

​JwtSessionConfig

​SessionFreshnessConfig

​Security best practices

Cookie sessions

Configure the session manager

Create a session after sign-in

Validate on each request

Revoke on sign-out

JWT sessions

Create a session

Verify on each request

Refresh

Session freshness

CSRF protection

Revocation patterns

Session metadata

Human sessions vs agent tokens

Error codes

Configuration reference

CookieSessionConfig

JwtSessionConfig

SessionFreshnessConfig

Security best practices