@edadma/hono-session

Stateless session auth for Hono using signed JWTs stored in HTTP-only cookies.

No database required. No social providers, no magic links, no opinions about the user model. Just cookie lifecycle management.

Install

npm install @edadma/hono-session

Usage

import { Hono } from 'hono'
import { createSession } from '@edadma/hono-session'

const { login, logout, authMiddleware } = createSession({
  secret: process.env.SESSION_SECRET!,
})

const app = new Hono()

app.post('/login', async (c) => {
  const { username, password } = await c.req.json()
  // validate credentials...
  await login(c, { username })
  return c.json({ ok: true })
})

app.post('/logout', (c) => {
  logout(c)
  return c.json({ ok: true })
})

app.get('/protected', authMiddleware, (c) => {
  const session = c.get('session')
  return c.json({ session })
})

API

createSession(config)

Returns { login, logout, authMiddleware } bound to the given config.

Config options:

| Option | Type | Default | Description | |---|---|---|---| | secret | string | required | Secret key for signing JWTs | | cookieName | string | "session" | Name of the cookie | | expiresIn | number | 86400 | Token expiry in seconds (24h) | | secure | boolean | true | Set the Secure flag on the cookie |

login(c, payload)

Signs the payload as a JWT and sets it as an HTTP-only cookie.

logout(c)

Clears the session cookie.

authMiddleware

Hono middleware that verifies the session cookie. Rejects with 401 if missing or invalid. On success, attaches the decoded payload to c.get('session').

Tradeoffs

Logout is "soft" — it clears the cookie client-side, but the JWT remains valid until it expires since there is no server-side session store. This is an intentional tradeoff for simplicity and zero infrastructure. If you need hard invalidation (e.g., for immediate revocation on password change), you would need a server-side session store or token blocklist, which is outside the scope of this library.

License

MIT