@davaux/session

HMAC-signed cookie sessions for Davaux.

Installation

npm install @davaux/session

Setup

Add the middleware to your davaux.config.ts. The secret must be at least 32 characters — use an environment variable in production:

// davaux.config.ts
import { defineConfig } from 'davaux/config'
import { sessionMiddleware } from '@davaux/session'

export default defineConfig({
  middleware: [
    sessionMiddleware({ secret: process.env.SESSION_SECRET! }),
  ],
})

Reading and writing session data

ctx.state.session is available in every handler, layout, and middleware after setup:

// src/routes/login.page.tsx
import { definePage, redirect } from 'davaux'

export default definePage(async (ctx) => {
  if (ctx.req.method === 'POST') {
    const form = await ctx.formData()
    ctx.state.session.set('userId', form.get('userId'))
    redirect('/dashboard')
  }

  return <form method='post'>...</form>
})

// src/routes/dashboard.page.tsx
import { definePage, redirect } from 'davaux'

export default definePage((ctx) => {
  const userId = ctx.state.session.get('userId')
  if (!userId) redirect('/login')

  return <h1>Welcome, {userId}</h1>
})

Session API

ctx.state.session exposes:

| Method | Description | |---|---| | get(key) | Return the value for key, or undefined | | set(key, value) | Store a value (must be JSON-serializable) | | delete(key) | Remove a key | | clear() | Wipe the entire session | | destroy() | Clear the session and expire the cookie |

Options

| Option | Type | Default | Description | |---|---|---|---| | secret | string | — | HMAC signing secret (required, min 32 chars) | | cookieName | string | 'session' | Name of the session cookie | | maxAge | number | 86400 | Cookie lifetime in seconds | | httpOnly | boolean | true | Set the HttpOnly flag | | secure | boolean | false | Set the Secure flag (enable in production) | | sameSite | 'strict' \| 'lax' \| 'none' | 'lax' | SameSite attribute | | path | string | '/' | Cookie path |

TypeScript

ctx.state.session is typed automatically when you import @davaux/session. If you need the Session type directly:

import type { Session } from '@davaux/session'

Notes

• Sessions are stored entirely in a signed cookie — no server-side store required
• The cookie payload is Base64-encoded JSON; it is signed but not encrypted — do not store secrets in the session
• Browsers enforce a ~4 KB per-cookie limit; keep session data minimal (user IDs, flags) and load larger data from your database in the handler

Documentation

davaux.codeberg.page/docs/session