itty-session

itty-session is a cookie-based session middleware for itty-router on Cloudflare Workers.

This is not an official library and is not affiliated with Kevin R. Whitley.

Why ?

Cookie-based sessions are currently the most secure way to create sessions for your web app.

No, JWTs are not the solution.

Specifically, the defaults set for itty-session are httpOnly, secure, sameSite: strict, which is the most secure according to OWASP's cheat sheets (see links above).

I'll elaborate later. Right now, let's get down to brass tacks.

Installation

Install itty-session via your favourite package manager. You know the drill.

1npm install itty-session
2pnpm install itty-session
3yarn add itty-session

Requirements

Itty-session requires a database to store session data.

Currently the only database supported is Cloudflare's D1.

By default, itty-session will use the SESSIONS database and the sessions table.

Expected wrangler.toml example configuration (with a second database):

1d1_databases = [
2    { binding = "DB", database_name = "my-database", database_id = "ABCD-0123-4567-8901-ABCD-EFGH" },
3    { binding = "SESSIONS", database_name = "my-sessions", database_id = "ABCD-0123-4567-8901-ABCD-EFGH" },
4]

If you're using a different database, you can specify it via the dbName option, but make sure it matches the binding name in your wrangler.toml file. A table named sessions is also required and will not automatically be created. Make sure it matches the table name in your wrangler.toml file.

Table configuration for sessions:

1CREATE TABLE "sessions" (
2	"sid"	TEXT UNIQUE,
3	"data"	TEXT,
4	"expiry"	INTEGER
5);

You can use Wrangler to create the table for you. Example: npx wrangler d1 execute karaoke-sessions --local --file=./sessions.sql (or --remote to push to remote D1 instance)

Usage

The following example is for cloudflare workers using itty-router as a base.

1import { AutoRouter, cors, withContent } from 'itty-router';
2import { createSessionsMiddleware } from 'itty-session';
3import D1Provider from 'itty-session/providers/d1';
4
5const { sessionPreflight, sessionify } = createSessionsMiddleware({
6  logging: true,
7  Provider: D1Provider,
8  providerOptions: {
9    dbName: 'SESSIONS',
10    tableName: 'sessions',
11  }
12});
13
14const router = AutoRouter({
15  before: [sessionPreflight],
16  finally: [sessionify],
17});
18
19router.post('/login', withContent, async (request) => {
20  const { content } = request;
21  // placeholder for real auth, please don't do this!
22  if (!content?.username !== 'test' || !content?.password !== 'test') {
23    return {
24      success: false,
25      message: 'invalid credentials',
26    };
27  }
28  // creds are correct
29  request.session.username = 'test';
30  request.session.isLoggedIn = true;
31
32  return {
33    success: true,
34    message: 'logged in',
35    user: {
36      username: user.username,
37      isLoggedIn: true,
38    },
39  };
40});
41
42router.get('/logout', async (request) => {
43  request.session?.destroy();
44
45  return {
46    success: true,
47    message: 'logged out',
48  };
49});
50
51
52export default router;

Future Changes

As I continue developing this, a few items to take care of:

• More examples, including a basic non-cloudflare one
• Docs on specific methods and options
• Cookie settings (with defaults)
• Providers for persistence outside D1/Cloudflare (mongo, mysql, bla bla bla)
• More options?
• Got any suggestions? Feel free to open an issue