Session Management

Stateful authentication and data persistence using secure, HttpOnly cookies with pluggable storage backends.

1 Storage Backends

In-Memory

Default. Fast but lost on server restart.

Disk

File-based JSON storage for persistence.

SolidB

HTTP database backend for distributed deployments.

SoliKV

Redis-compatible key-value store with TTL.

Configuration Methods

Sessions can be configured via code, environment variables, or config files:

# Change storage backend at runtime
session_configure({"driver": "solidb", "solidb_host": "db.example.com"})

export SOLI_SESSION_DRIVER=solidb
export SOLI_SOLIDB_HOST=db.example.com

1 Basic Operations

Use the built-in session helper functions to read, write, and manage user data.

controllers/session_controller.sl

# 1. Write data to the session
session_set("user_id", 42)
session_set("username", "alice_w")
session_set("role", "admin")

# 2. Read data (returns null if not found)
current_user = session_get("username")

# 3. Check if key exists
if session_has("user_id")
  print("User is authenticated!")
end

# 4. Remove specific data
session_delete("flash_message")

# 5. Clear everything (logout)
session_destroy()

2 Security Best Practices

Session Fixation Protection

When a user logs in or elevates privileges, always regenerate the session ID. This prevents session fixation attacks where an attacker tricks a user into using a known session ID.

controllers/auth_controller.sl

def login(req: Any)
  credentials = req["body"]

  if verify_user(credentials)
    # CRITICAL: Regenerate session ID before setting sensitive data
    session_regenerate
    session_set("authenticated", true)
    session_set("user_id", credentials["id"])
    return redirect("/dashboard")
  end

  render("login", { "error": "Invalid credentials" })
end

Cookie Hardening

Session cookies always carry HttpOnly and Path=/. The SameSite attribute and __Host- prefix are configurable via environment variables.

Variable	Purpose	Default
`SOLI_SESSION_SAMESITE`	`Lax`, `Strict`, or `None`. `Strict` blocks the cookie on any cross-site navigation; `None` automatically pairs with `Secure` — Soli forces the flag on regardless of the detected request scheme so browsers don't silently drop the cookie.	`Lax`
`SOLI_SESSION_HOST_PREFIX`	Set to `1` to emit the cookie as `__Host-session_id`. Browsers only accept `__Host-` cookies that are `Secure` and scoped to `Path=/` with no `Domain` — this prevents subdomain takeover from setting an attacker-controlled session cookie. Applied only when `Secure` is also active.	unset

export SOLI_SESSION_SAMESITE=Strict
export SOLI_SESSION_HOST_PREFIX=1