feature(session): add session middleware

Author: BarryThePenguin

.changeset/large-pumas-dig.md

@@ -0,0 +1,5 @@
+---
+'@hono/session': minor
+---
+
+Initial release

.github/workflows/ci-session.yml

@@ -0,0 +1,32 @@
+name: ci-session
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/session/**'
+  pull_request:
+    branches: ['*']
+    paths:
+      - 'packages/session/**'
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+      - run: yarn workspaces focus hono-middleware @hono/session
+      - run: yarn workspace @hono/session build
+      - run: yarn workspace @hono/session publint
+      - run: yarn workspace @hono/session typecheck
+      - run: yarn eslint packages/session
+      - run: yarn test --coverage --project @hono/session
+      - uses: codecov/codecov-action@v5
+        with:
+          fail_ci_if_error: true
+          directory: ./coverage
+          flags: session
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

packages/session/README.md

@@ -0,0 +1,125 @@
+# Session middleware for Hono
+
+[![codecov](https://codecov.io/github/honojs/middleware/graph/badge.svg?flag=session)](https://codecov.io/github/honojs/middleware)
+
+Session middleware for Hono using encrypted JSON Web Tokens.
+
+This middleware depends on the following pacakges:
+
+- [`@panva/hkdf`](https://github.com/panva/hkdf)
+- [`jose`](https://github.com/panva/jose)
+
+Other resources worth reading include:
+
+- [The Copenhagen Book](https://thecopenhagenbook.com/) by [Pilcrow](https://github.com/pilcrowOnPaper)
+- [Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html) from [OWASP](https://cheatsheetseries.owasp.org/index.html)
+
+## Installation
+
+```sh
+npm i @hono/session
+```
+
+## Environment Variables
+
+```sh
+AUTH_SECRET=
+```
+
+> [!TIP]
+> Quickly generate a good secret with `openssl`
+>
+> ```sh
+> $ openssl rand -base64 32
+> ```
+
+## Options
+
+| Option           | Type                                            | Description                                                                                                               |
+| ---------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `generateId`?    | `() => string`                                  | Function to generate a unique session ID                                                                                  |
+| `secret`?        | `string` or [`EncryptionKey`](#EncryptionKey)   | 32-byte, hex-encoded string, or encryption key, used to encrypt the session cookie. Defaults to `process.env.AUTH_SECRET` |
+| `sessionCookie`? | [`SessionCookieOptions`](#SessionCookieOptions) | Session cookie options                                                                                                    |
+
+## `EncryptionKey`
+
+- [`jose.CryptoKey`](https://github.com/panva/jose/blob/main/docs/types/type-aliases/CryptoKey.md) | [`jose.KeyObject`](https://github.com/panva/jose/blob/main/docs/types/interfaces/KeyObject.md) | [`jose.JWK`](https://github.com/panva/jose/blob/main/docs/types/interfaces/JWK.md) | [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)
+
+## `SessionCookieOptions`
+
+> [!IMPORTANT]
+> By default, session cookies do not expire.
+> It is recommended to provide value for `duration.absolute`
+
+### Properties
+
+| Property    | Type                                                            | Description                                                                       |
+| ----------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `duration`? | [`MaxAgeDuration`](#MaxAgeDuration)                             | The maximum age duration of the session cookie. By default, no maximum age is set |
+| `name`?     | `string`                                                        | The name of the session cookie. Defaults to `sid`                                 |
+| `options`?  | [`CookieOptions`](https://hono.dev/docs/helpers/cookie#options) | Session cookie options                                                            |
+
+## `MaxAgeDuration`
+
+See [Session lifetime](https://thecopenhagenbook.com/sessions#session-lifetime)
+
+### Properties
+
+| Property      | Type     | Description                                                                                                      |
+| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| `absolute`    | `number` | Duration in seconds a session will be valid for, after which it will be expired and have to be re-authenticated. |
+| `inactivity`? | `number` | Duration in seconds a session will be considered active, during which the session max age can be extended.       |
+
+## Example
+
+```ts
+import { session } from '@hono/session'
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app.use(session()).get('/', async (c) => {
+  const data = await c.var.session.get()
+  return c.json(data)
+})
+
+export default app
+```
+
+### With Session storage
+
+```ts
+import { session, sessionStorage } from '@hono/session'
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+app
+  .use(
+    sessionStorage({
+      delete(sid) {},
+      async get(sid) {},
+      set(sid, value) {},
+    }),
+    session()
+  )
+  .get('/', async (c) => {
+    const data = await c.var.session.get()
+    return c.json(data)
+  })
+
+export default app
+```
+
+See also:
+
+- [Cloudflare KV as session storage](./examples/cloudflare-kv.ts)
+- [Using Unstorage as session storage](./examples/unstorage.ts)
+
+## Author
+
+Jonathan haines <https://github.com/barrythepenguin>
+
+## License
+
+MIT

packages/session/examples/cloudflare-kv.test.ts

@@ -0,0 +1,66 @@
+import { createExecutionContext, env, waitOnExecutionContext } from 'cloudflare:test'
+import { createTestSession } from '../src/helper/testing'
+import { app, secret } from './cloudflare-kv'
+
+const { soon, recent, encrypt, sid, sub } = createTestSession({ secret })
+
+describe('Cloudflare KV adapter', () => {
+  it('gets session data', async () => {
+    const ctx = createExecutionContext()
+    await env.SESSION_KV.put(sid, JSON.stringify({ sub }))
+
+    const res = await app.request(
+      '/session',
+      {
+        headers: { cookie: `sid=${await encrypt({ iat: recent, exp: soon, sid })}` },
+      },
+      env,
+      ctx
+    )
+    await waitOnExecutionContext(ctx)
+    const data = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(data).toStrictEqual({ sub })
+  })
+
+  it('updates session data', async () => {
+    const ctx = createExecutionContext()
+    await env.SESSION_KV.put(sid, JSON.stringify({ sub }))
+    const newSub = 'new-subject'
+    const res = await app.request(
+      '/session',
+      {
+        body: JSON.stringify({ sub: newSub }),
+        headers: { cookie: `sid=${await encrypt({ iat: recent, exp: soon, sid })}` },
+        method: 'PUT',
+      },
+      env,
+      ctx
+    )
+    await waitOnExecutionContext(ctx)
+    const data = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(data).toStrictEqual({ sub: newSub })
+    await expect(env.SESSION_KV.get(sid, 'json')).resolves.toStrictEqual({ sub: newSub })
+  })
+
+  it('deletes session data', async () => {
+    const ctx = createExecutionContext()
+    await env.SESSION_KV.put(sid, JSON.stringify({ sub }))
+    const res = await app.request(
+      '/session',
+      {
+        headers: { cookie: `sid=${await encrypt({ iat: recent, exp: soon, sid })}` },
+        method: 'DELETE',
+      },
+      env,
+      ctx
+    )
+    await waitOnExecutionContext(ctx)
+
+    expect(res.status).toBe(204)
+    await expect(env.SESSION_KV.get(sid, 'json')).resolves.toBeNull()
+  })
+})

packages/session/examples/cloudflare-kv.ts

@@ -0,0 +1,46 @@
+import { env } from 'cloudflare:test'
+import { Hono } from 'hono'
+import { session, sessionStorage } from '../src'
+import * as cookies from '../src/cookies'
+
+export const secret = cookies.generateId(16)
+
+/**
+ * Example hono app using Cloudflare KV as session storage.
+ *
+ * This example assumes you have a Cloudflare KV namespace named `SESSION_KV`.
+ */
+export const app = new Hono()
+  .use(
+    sessionStorage((c) => ({
+      delete(sid) {
+        c.executionCtx.waitUntil(env.SESSION_KV.delete(sid))
+      },
+      get(sid) {
+        return env.SESSION_KV.get(sid, 'json')
+      },
+      set(sid, data) {
+        c.executionCtx.waitUntil(
+          env.SESSION_KV.put(sid, JSON.stringify(data), {
+            // Optionally configure session data to expire some time after the session cookie expires.
+            expirationTtl: 2_592_000, // 30 days in seconds
+          })
+        )
+      },
+    })),
+    session({ secret })
+  )
+  .get('/session', async (c) => {
+    const data = await c.var.session.get()
+    return c.json(data)
+  })
+  .put('/session', async (c) => {
+    const data = await c.req.json()
+    await c.var.session.update(data)
+    return c.json(c.var.session.data)
+  })
+  .delete('/session', async (c) => {
+    await c.var.session.get()
+    c.var.session.delete()
+    return c.body(null, 204)
+  })

packages/session/examples/cloudflare-types.d.ts

@@ -0,0 +1,5 @@
+declare module 'cloudflare:test' {
+  interface ProvidedEnv {
+    SESSION_KV: KVNamespace
+  }
+}

packages/session/examples/unstorage.test.ts

@@ -0,0 +1,43 @@
+import { createTestSession } from '../src/helper/testing'
+import { app, secret, storage } from './unstorage'
+
+const { soon, recent, encrypt, sid, sub } = createTestSession({ secret })
+
+describe('Unstorage adapter', () => {
+  it('gets session data', async () => {
+    await storage.set(sid, { sub })
+    const res = await app.request('/session', {
+      headers: { cookie: `sid=${await encrypt({ iat: recent, exp: soon, sid })}` },
+    })
+    const data = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(data).toStrictEqual({ sub })
+  })
+
+  it('updates session data', async () => {
+    await storage.set(sid, { sub })
+    const newSub = 'new-subject'
+    const res = await app.request('/session', {
+      body: JSON.stringify({ sub: newSub }),
+      headers: { cookie: `sid=${await encrypt({ iat: recent, exp: soon, sid })}` },
+      method: 'PUT',
+    })
+    const data = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(data).toStrictEqual({ sub: newSub })
+    await expect(storage.get(sid)).resolves.toStrictEqual({ sub: newSub })
+  })
+
+  it('deletes session data', async () => {
+    await storage.set(sid, { sub })
+    const res = await app.request('/session', {
+      headers: { cookie: `sid=${await encrypt({ iat: recent, exp: soon, sid })}` },
+      method: 'DELETE',
+    })
+
+    expect(res.status).toBe(204)
+    await expect(storage.get(sid)).resolves.toBeNull()
+  })
+})

packages/session/examples/unstorage.ts

@@ -0,0 +1,48 @@
+import { Hono } from 'hono'
+import { createStorage } from 'unstorage'
+import type { SessionData } from '../src'
+import { session, sessionStorage } from '../src'
+import * as cookies from '../src/cookies'
+
+interface StorageData extends SessionData {
+  sub: string
+}
+
+export const storage = createStorage<StorageData>()
+
+export const secret = cookies.generateId(16)
+
+/**
+ * Example hono app using Unstorage as session storage.
+ *
+ * @see {@link https://unstorage.unjs.io/}
+ */
+export const app = new Hono()
+  .use(
+    sessionStorage({
+      delete(sid) {
+        storage.remove(sid)
+      },
+      get(sid) {
+        return storage.get(sid)
+      },
+      set(sid, data) {
+        storage.set(sid, data)
+      },
+    }),
+    session({ secret })
+  )
+  .get('/session', async (c) => {
+    const data = await c.var.session.get()
+    return c.json(data)
+  })
+  .put('/session', async (c) => {
+    const data = await c.req.json()
+    await c.var.session.update(data)
+    return c.json(c.var.session.data)
+  })
+  .delete('/session', async (c) => {
+    await c.var.session.get()
+    c.var.session.delete()
+    return c.body(null, 204)
+  })