interface SessionPluginOptions
Since 0.2.0

Options for SessionPlugin.

Properties

readonly
optional
secret: string | readonly string[]

The session secret, or an ordered list of secrets for rotation: index 0 signs/encrypts new cookies while every entry can still open existing ones, so rotating a secret does not log everybody out.

When omitted, the secret is resolved from CAPABILITIES.SECRETS and then from the environment. Each secret must be at least 32 characters.

readonly
optional
secretName: string

Name looked up in the secret manager and the environment. Default 'SESSION_SECRET'.

readonly
optional
mode: SessionMode

How the cookie is protected. 'encrypt' (default) hides the payload with AES-256-GCM; 'sign' leaves it readable base64url JSON under an HMAC-SHA256 signature, which suits the store strategy where the cookie holds only an opaque id.

readonly
optional
store: "memory" | "cache" | ISessionStore

Where the payload lives. Omitted (default) keeps it in the cookie itself, which needs no infrastructure. Set to 'memory', 'cache', or a custom ISessionStore to keep only an opaque id in the cookie and the payload server-side, which makes immediate revocation possible.

readonly
optional
maxAge: number

Absolute session lifetime in seconds. Default 7200 (2 hours).

readonly
optional
rolling: boolean

Re-issue the cookie on every response, extending the expiry so an active user is not logged out mid-session. Default false, which commits only when the session actually changed.

readonly
optional
idleTimeoutMs: number

Expire a session that has received no requests for this long, independently of maxAge. Omitted by default (no idle check).

Idleness is refreshed by any request, including a read-only one, which means a configured idle timeout re-issues the cookie on every response (and, on the store strategy, rewrites the stored entry) so the activity stamp can advance. That is the cost of tracking activity; it does not extend absolute expiry, which stays governed by maxAge unless rolling is also set.

readonly
optional
maxCookieBytes: number

Byte budget for the serialized cookie. Default 4096. Exceeding it throws rather than emitting a cookie the browser would silently drop.

readonly
optional
csrf: CsrfFormOptions

Enable session-backed form CSRF. Omitted means no CSRF middleware is registered; an empty object enables it with defaults.

readonly
optional
tenantBinding: boolean

Bind a session to the tenant it was minted under. Default true: when a tenant is resolved for the request, the tenant id is sealed into the session on commit, and a later request presenting that session under a different tenant is refused with 403 before the handler runs. When either the session or the request carries no tenant, nothing is compared, so an application without tenancy is inert. false restores the previous behaviour (no seal, no compare).

Usage

import { type SessionPluginOptions } from "session-plugin/src/index.ts";