Name: KavachOS
Author: KavachOS

Let users hold multiple active sessions and manage them from an account settings page.

By default, KavachOS allows unlimited concurrent sessions per user. The multi-session module adds a cap, a configurable overflow strategy, and endpoints for listing and revoking sessions — useful for building an "active devices" settings page.

Setup

lib/kavach.ts

import { createKavach } from 'kavachos';
import { multiSession } from 'kavachos/plugins/multi-session'; 

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
  plugins: [
    multiSession({ 
      maxSessions: 5, 
      overflow: 'evict-oldest', 
    }), 
  ],
});

Overflow strategies

Strategy	Behavior
`evict-oldest`	Deletes the least-recently-used session when the cap is reached
`reject`	Returns `429` with code `SESSION_LIMIT_REACHED` — new sign-in fails

List sessions

GET /auth/sessions

Returns all active sessions for the authenticated user. Useful for building an "active devices" UI.

List sessions (client)

const res = await fetch('/auth/sessions', {
  credentials: 'include',
});

const { sessions } = await res.json();

Response shape

{
  "sessions": [
    {
      "id": "ses_abc123",
      "current": true,
      "createdAt": "2025-06-01T10:00:00.000Z",
      "expiresAt": "2025-06-08T10:00:00.000Z",
      "device": {
        "browser": "Chrome",
        "os": "macOS",
        "type": "desktop"
      },
      "ipAddress": "203.0.113.1"
    }
  ]
}

Device information is parsed from the User-Agent header at sign-in time. IP addresses are stored as-is — apply your own masking if required.

Revoke a session

DELETE /auth/sessions/:id

Revokes a specific session. Users can revoke any of their own sessions, including the current one.

Revoke session (client)

await fetch(`/auth/sessions/${sessionId}`, {
  method: 'DELETE',
  credentials: 'include',
});

Revoke all other sessions

DELETE /auth/sessions

Revokes all sessions for the user except the current one. Useful for "sign out everywhere else" buttons.

Sign out all other devices (client)

await fetch('/auth/sessions', {
  method: 'DELETE',
  credentials: 'include',
});

Configuration reference

Prop

Type

Multi-session