koa-session-minimal
Native Koa 2 session middleware, inspired by and compatible with koa-generic-session. This can be used as a drop-in replacement for koa-generic-session in Koa 2.
This rewrite implements koa-generic-session's essential interfaces, with around 100 lines of code in ES6. It supports existing session stores for koa-generic-session.
Version 4+ requires node 8+. Please use v3.0.4 for node versions older than 8.
Minimum features and storage usage
This middleware guarantees the following:
- Minimum data generation and storage. No session data modification / pollution.
- Neither a cookie nor a session store record is created unless session data gets populated by other middlewares.
- Cookie options are not saved in the
ctx.session object or session store (try to address this concern).
- Minimum updates on cookie and session store. Cookie and session store only get updated when session data has been changed.
- When
ctx.session gets updated (is a non-empty object), cookie and store data will be updated with new values and new expiration time (maxAge).
- When
ctx.session gets cleared ( = {} or null ), cookie and store data will be deleted.
- If a session has not been updated within
maxAge, its data will be expired.
- Minimum public interfaces and configuration options.
- Cookie options:
maxAge, path, domain, secure, httpOnly
- Session interfaces:
session, sessionHandler { regenerateId() }
- Store interfaces:
get(), set(), destroy()
Installation
$ npm install koa-session-minimal
Usage
const Koa = require('koa')
const session = require('koa-session-minimal')
const redisStore = require('koa-redis')
const app = new Koa()
app.use(session({
store: redisStore()
}))
// count middleware, increment when url = /add
app.use(async (ctx, next) => {
ctx.session.count = ctx.session.count || 0
if (ctx.path === '/add') ctx.session.count++
await next()
ctx.body = ctx.session.count
})
app.listen(3000)
Interfaces
- session data via
ctx.session (the same way as koa-generic-session)
- session methods via
ctx.sessionHandler
regenerateId(): regenerate session id
Options
key: session cookie name and store key prefixstore: session storecookie: cookie options, can be an object (static cookie options) or a function that returns an object (dynamic cookie options). Only maxAge, path, domain, secure, httpOnly are supported as option keys (see option details in cookies module).
Session expiration
Default session has settings cookie.maxAge = 0 for cookie and ttl = ONE_DAY for session store, means that a session will be expired in one of the following circumstances:
- A user close the browser window (transient cookie ends)
- Session data hasn't been updated within
ONE_DAY (storage expires)
With settings that cookie.maxAge > 0, the ttl for store data will be always the same as maxAge.
Dynamic session expiration (cookie options)
When setting cookie option to a plain object, all sessions will use the same cookie options. If a function is assigned to cookie, cookie options will be dynamically calculated at each (non-empty) session's saving stage.
For example, you can use an arrow function to set different maxAge for user and guest sessions, as below:
session({
cookie: ctx => ({
maxAge: ctx.session.user ? ONE_MONTH : 0
})
})
Session security
Middlewares are recommended to call sessionHandler.regenerateId() during authentication state change (login). This middleware provides the essential interface, It will be other middleware's decision on when and how often they want to roll the session id.
NOTE: Below is mostly copied from koa-generic-session's README, because the two middlewares share the same store interfaces. Any store that implements koa-generic-session's store interfaces should also work with koa-session-minimal. koa-redis is tested as an example in test/store_redis.test.js
Session store
You can use any other store to replace the default MemoryStore, it just needs to follow this api:
get(sid): get session object by sidset(sid, sess, ttl): set session object for sid, with a ttl (in ms)destroy(sid): destroy session for sid
the api needs to return a Promise, Thunk, generator, or an async function.
Stores presented
License
MIT
