@davaux/session 0.8.0

package/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- pka-generated -->
+# @davaux/session
+
+> Generated by Project Knowledge Analyzer on 2026-06-06T21:53:10.444Z
+
+## Overview
+
+HMAC-signed cookie sessions for Davaux
+
+**Version**: 0.8.0
+**Author**: David L Dyess II
+**License**: MIT
+**Repository**: https://codeberg.org/davaux/davaux#readme
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Module System**: ESM (`type: module`)
+
+## Commands
+
+- `npm run build` — tsc
+- `npm run typecheck` — tsc --noEmit
+
+## Project Structure
+
+```
+├── CLAUDE.md
+├── README.md
+├── package.json
+├── tsconfig.json
+└── src/
+    └── index.ts
+
+```
+
+## Entry Points
+
+- `src/index.ts`
+
+## Files by Type
+
+### Documentation (2)
+- `CLAUDE.md`
+- `README.md`
+
+### Config (2)
+- `package.json`
+- `tsconfig.json`
+
+### Module (1)
+- `src/index.ts`
+
+
+## Git
+- **Branch**: main
+- **Last Commit**: chore: Add alpha status note to README
+- **Author**: David Dyess II
+- **Date**: 2026-06-06 15:52:27 -0600
+- **Remote**: https://codeberg.org/davaux/davaux.git
+
+### Recent Commits
+```
+f527031 chore: Add alpha status note to README
+90c819e chore: Add repo info to package.json files
+b200d9d feat(davaux)!: Add OmlCacheConfig - opt-in with includes option or opt-out with excludes option; Fix OML implementation to follow OML spec - use output instead of return
+3bce0c2 chore: Update and add READMEs to packages; update ROADMAP
+fc27c20 fix(davaux): Remove old dist folder on new builds; fix server port per DavauxConfig
+c760659 feat(davaux): Add minify CSS in production builds
+c899ab8 fix(davaux): Added method JS and JSX extenstion to scanner
+7d99f04 feat(davaux): Add support for declarative partial updates
+3b47f37 chore: Bump package versions to 0.8.0
+aa0460f chore: Add CHANGELOG.md
+```
+
+## Dependencies
+
+
+### Development
+@types/node, davaux, typescript
+
+
+
+
+
+
+
+
+
+## Exported Symbols
+
+**`src/index.ts`**
+`Session`, `sessionMiddleware`, `SessionOptions`
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David L Dyess II
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @davaux/session
+
+HMAC-signed cookie sessions for Davaux.
+
+## Installation
+
+```bash
+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:
+
+```ts
+// 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:
+
+```ts
+// 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>
+})
+```
+
+```ts
+// 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:
+
+```ts
+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](https://davaux.codeberg.page/docs/session)

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@davaux/session",
+  "version": "0.8.0",
+  "description": "HMAC-signed cookie sessions for Davaux",
+  "type": "module",
+  "author": "David L Dyess II",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/davaux/davaux"
+  },
+  "bugs": {
+    "url": "https://codeberg.org/davaux/davaux/issues"
+  },
+  "homepage": "https://codeberg.org/davaux/davaux#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "davaux": ">=0.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "davaux": "*",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import type { ServerResponse } from 'node:http'
+import type { MiddlewareFn } from 'davaux'
+
+// ─── State augmentation ───────────────────────────────────────────────────────
+
+declare module 'davaux' {
+  interface State {
+    session: Session
+  }
+}
+
+// ─── Session ──────────────────────────────────────────────────────────────────
+
+/**
+ * Per-request session object. Stores arbitrary key-value data serialised into
+ * an HMAC-signed cookie. Mutations (`set`, `delete`, `destroy`) are persisted
+ * automatically before the response headers are sent.
+ */
+export class Session {
+  private readonly _data: Record<string, unknown>
+  private _dirty = false
+  private _destroyed = false
+
+  constructor(data: Record<string, unknown> = {}) {
+    this._data = data
+  }
+
+  /** Retrieve a session value by key. Returns `undefined` when absent. */
+  get<T = unknown>(key: string): T | undefined {
+    return this._data[key] as T | undefined
+  }
+
+  /** Store a value under `key`. Marks the session dirty so it is persisted. */
+  set(key: string, value: unknown): void {
+    this._data[key] = value
+    this._dirty = true
+  }
+
+  /** Remove `key` from the session. Marks the session dirty so it is persisted. */
+  delete(key: string): void {
+    delete this._data[key]
+    this._dirty = true
+  }
+
+  /** Clear all session data and delete the cookie on response. */
+  destroy(): void {
+    this._destroyed = true
+    this._dirty = false
+  }
+
+  /** Snapshot of current session data. */
+  get data(): Record<string, unknown> {
+    return { ...this._data }
+  }
+
+  /** @internal */
+  get dirty(): boolean {
+    return this._dirty
+  }
+
+  /** @internal */
+  get destroyed(): boolean {
+    return this._destroyed
+  }
+}
+
+// ─── Options ──────────────────────────────────────────────────────────────────
+
+export interface SessionOptions {
+  /**
+   * Secret(s) used to sign the session cookie with HMAC-SHA256.
+   * Pass an array for rotation: the first secret signs new sessions,
+   * all are accepted for verification.
+   */
+  secret: string | string[]
+  /** Cookie name. Default: `'session'` */
+  cookieName?: string
+  /** Max-Age in seconds. Omit for a session cookie (clears on browser close). */
+  maxAge?: number
+  /** Default: `true` */
+  httpOnly?: boolean
+  /** Default: `false`. Enable in production to require HTTPS. */
+  secure?: boolean
+  /** Default: `'Lax'` */
+  sameSite?: 'Strict' | 'Lax' | 'None'
+  /** Default: `'/'` */
+  path?: string
+  domain?: string
+}
+
+// ─── Signing ──────────────────────────────────────────────────────────────────
+
+function sign(payload: string, secret: string): string {
+  const sig = createHmac('sha256', secret).update(payload).digest('base64url')
+  return `${payload}.${sig}`
+}
+
+function verify(value: string, secrets: string[]): Record<string, unknown> | null {
+  const dot = value.lastIndexOf('.')
+  if (dot === -1) return null
+
+  const payload = value.slice(0, dot)
+  const sigBuf = Buffer.from(value.slice(dot + 1), 'base64url')
+
+  for (const secret of secrets) {
+    const expectedBuf = createHmac('sha256', secret).update(payload).digest()
+    if (expectedBuf.length === sigBuf.length && timingSafeEqual(expectedBuf, sigBuf)) {
+      try {
+        return JSON.parse(Buffer.from(payload, 'base64url').toString('utf-8')) as Record<
+          string,
+          unknown
+        >
+      } catch {
+        return null
+      }
+    }
+  }
+
+  return null
+}
+
+// ─── Middleware ───────────────────────────────────────────────────────────────
+
+/**
+ * HMAC-signed cookie session middleware. Parses the incoming session cookie,
+ * exposes the data as `ctx.state.session`, and automatically writes an updated
+ * cookie when the session is mutated or destroyed.
+ *
+ * Pass an array of secrets for key rotation: the first secret signs new
+ * sessions, all secrets are accepted for verification.
+ *
+ * @example
+ * import { sessionMiddleware } from '@davaux/session'
+ * export default sessionMiddleware({
+ *   secret: process.env.SESSION_SECRET!,
+ *   maxAge: 60 * 60 * 24 * 7, // 1 week
+ * })
+ */
+export function sessionMiddleware(options: SessionOptions): MiddlewareFn {
+  const secrets = Array.isArray(options.secret) ? options.secret : [options.secret]
+  if (secrets.length === 0 || secrets.some((s) => !s)) {
+    throw new Error('@davaux/session: at least one non-empty secret is required')
+  }
+  if (secrets.some((s) => s.length < 32)) {
+    console.warn(
+      '@davaux/session: secret should be at least 32 characters — short secrets are weak and easy to brute-force',
+    )
+  }
+
+  const name = options.cookieName ?? 'session'
+
+  return async (ctx, next) => {
+    const raw = ctx.cookies.get(name)
+    const existing = raw ? verify(raw, secrets) : null
+    const session = new Session(existing ?? {})
+    ctx.state.session = session
+
+    // Inject the session cookie right before headers are committed.
+    // This approach handles the common case where the route handler calls
+    // res.writeHead() inside next(), after which res.setHeader() would fail.
+    const originalWriteHead = ctx.res.writeHead.bind(ctx.res) as typeof ctx.res.writeHead
+    // biome-ignore lint/suspicious/noExplicitAny: writeHead has multiple overloads
+    ctx.res.writeHead = ((...args: any[]) => {
+      ctx.res.writeHead = originalWriteHead
+      if (session.destroyed) {
+        ctx.cookies.delete(name, { path: options.path ?? '/' })
+      } else if (session.dirty) {
+        const payload = Buffer.from(JSON.stringify(session.data)).toString('base64url')
+        const signed = sign(payload, secrets[0])
+        ctx.cookies.set(name, signed, {
+          httpOnly: options.httpOnly ?? true,
+          secure: options.secure ?? false,
+          sameSite: options.sameSite ?? 'Lax',
+          maxAge: options.maxAge,
+          path: options.path ?? '/',
+          domain: options.domain,
+        })
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: forwarding overloaded args
+      return (originalWriteHead as (...a: any[]) => ServerResponse)(...args)
+    }) as typeof ctx.res.writeHead
+
+    await next()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "skipLibCheck": true,
+    "lib": ["ESNext"],
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}