Runtime Lifecycle

Understand how Keyloom processes requests and sessions across Node and Edge.

High level flow

1. Incoming request hits middleware or route handler
2. Token extracted from cookie or header
3. Strategy branch
   • JWT: verify signature and claims, optionally fetch JWKS
   • Database: read session by id via adapter
4. Optional RBAC evaluation based on user roles and permissions
5. Response, with cookie refresh if rolling sessions are enabled

Edge vs Node

• Edge: prefer JWT strategy and edge-safe adapters. Avoid Node APIs and large dependencies.
• Node: both strategies are fine. Database strategy enables server-side invalidation.

Session shape

interface Session {
  user: { id: string; name?: string; email?: string; image?: string };
  org?: { id: string; role?: string };
  expiresAt: string; // ISO timestamp
  issuedAt: string; // ISO timestamp
}

Errors and recovery

• Invalid token: redirect to sign in or return 401
• Expired session: refresh if rolling or require re-authentication
• Adapter errors: surface 500 with generic message, log details server side

Observability

• Add request ID headers and log auth events
• Track sign-in, sign-out, and error codes to monitor health