@useoneauth/sessions

Phase 3 — Session Engine. Server-side session trust contexts for an identity.

Pure TypeScript, no database or transport. A Session is a server-side record of an authenticated context for an identity, with an idle-timeout + absolute-cap lifecycle, refresh, and revocation. Persistence is expressed through a repository interface with an in-memory adapter; the actual bearer the client presents (a token carrying sessionId) is Phase 4's concern.

Install

// package.json
{ "dependencies": { "@useoneauth/sessions": "workspace:*" } }

Usage

import { SessionService, InMemorySessionRepository } from "@useoneauth/sessions"
import { InMemoryEventBus } from "@useoneauth/events-core"

const sessions = new SessionService(new InMemorySessionRepository(), new InMemoryEventBus())

const s = await sessions.createSession({ identityId: "u1", trustContext: { ipAddress: "1.2.3.4" } })
await sessions.validateSession(s.id)   // throws SessionRevokedError / SessionExpiredError if not usable
await sessions.refreshSession(s.id)    // extends the idle window, clamped to the absolute cap
await sessions.revokeSession(s.id)
await sessions.revokeAllForIdentity("u1") // "log out everywhere"; returns count revoked

Configure lifetimes via the constructor ({ idleTTLMinutes, absoluteTTLMinutes }, defaults 30 min / 30 days) or per call on createSession.

Lifecycle

• A session is effectively valid when status === "active" and now <= expiresAt (idle) and now <= absoluteExpiresAt (hard cap).
• refreshSession sets expiresAt = min(now + idleTTL, absoluteExpiresAt) — it can never extend a session past its absolute cap.
• Expiry is derived from timestamps; only revoked is a stored status. No background sweeper or timers.

Events

SESSION_CREATED, SESSION_REFRESHED, SESSION_REVOKED (persist → publish).

Scope

No JWTs/bearer tokens (Phase 4 — Token System) and no trust scoring (Phase 7 — Trust Engine); TrustContext here is captured metadata only.

See ARCHITECTURE.md for details.