@prairielearn/session 1.0.0

package/src/index.ts

@@ -0,0 +1,132 @@
+import type { Request, Response, NextFunction } from 'express';
+import onHeaders from 'on-headers';
+import signature from 'cookie-signature';
+import asyncHandler from 'express-async-handler';
+
+import { SessionStore } from './store';
+import { beforeEnd } from './before-end';
+import { getSessionIdFromCookie, type CookieSecure, shouldSecureCookie } from './cookie';
+import { type Session, generateSessionId, loadSession, hashSession } from './session';
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      session: Session;
+    }
+  }
+}
+
+export interface SessionOptions {
+  secret: string | string[];
+  store: SessionStore;
+  canSetCookie?: (req: Request) => boolean;
+  cookie?: {
+    name?: string;
+    secure?: CookieSecure;
+    httpOnly?: boolean;
+    sameSite?: boolean | 'none' | 'lax' | 'strict';
+    maxAge?: number;
+  };
+}
+
+const DEFAULT_COOKIE_NAME = 'session';
+const DEFAULT_COOKIE_MAX_AGE = 86400000; // 1 day
+
+export function createSessionMiddleware(options: SessionOptions) {
+  const secrets = Array.isArray(options.secret) ? options.secret : [options.secret];
+  const cookieName = options.cookie?.name ?? DEFAULT_COOKIE_NAME;
+  const cookieMaxAge = options.cookie?.maxAge ?? DEFAULT_COOKIE_MAX_AGE;
+  const store = options.store;
+
+  return asyncHandler(async function sessionMiddleware(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) {
+    const cookieSessionId = getSessionIdFromCookie(req, cookieName, secrets);
+    const sessionId = cookieSessionId ?? (await generateSessionId());
+    req.session = await loadSession(sessionId, req, store, cookieMaxAge);
+
+    const originalHash = hashSession(req.session);
+    const originalExpirationDate = req.session.getExpirationDate();
+
+    const canSetCookie = options.canSetCookie?.(req) ?? true;
+
+    onHeaders(res, () => {
+      if (!req.session) {
+        if (cookieSessionId) {
+          // If the request arrived with a session cookie but the session was
+          // destroyed, clear the cookie.
+          res.clearCookie(cookieName);
+          return;
+        }
+
+        // There is no session to do anything with.
+        return;
+      }
+
+      const secureCookie = shouldSecureCookie(req, options.cookie?.secure ?? 'auto');
+      if (secureCookie && req.protocol !== 'https') {
+        // Avoid sending cookie over insecure connection.
+        return;
+      }
+
+      const isNewSession = !cookieSessionId || cookieSessionId !== req.session.id;
+      const didExpirationChange =
+        originalExpirationDate.getTime() !== req.session.getExpirationDate().getTime();
+      if (canSetCookie && (isNewSession || didExpirationChange)) {
+        const signedSessionId = signSessionId(req.session.id, secrets[0]);
+        res.cookie(cookieName, signedSessionId, {
+          secure: secureCookie,
+          httpOnly: options.cookie?.httpOnly ?? true,
+          sameSite: options.cookie?.sameSite ?? false,
+          expires: req.session.getExpirationDate(),
+        });
+      }
+    });
+
+    beforeEnd(res, next, async () => {
+      if (!req.session) {
+        // There is no session to do anything with.
+        return;
+      }
+
+      const isExistingSession = cookieSessionId && cookieSessionId === req.session.id;
+      const hashChanged = hashSession(req.session) !== originalHash;
+      const didExpirationChange =
+        originalExpirationDate.getTime() !== req.session.getExpirationDate().getTime();
+      if (
+        (hashChanged && isExistingSession) ||
+        (canSetCookie && (!isExistingSession || didExpirationChange))
+      ) {
+        // Only update the expiration date in the store if we were actually
+        // able to update the cookie too.
+        const expirationDate = canSetCookie
+          ? req.session.getExpirationDate()
+          : originalExpirationDate;
+
+        await store.set(
+          req.session.id,
+          req.session,
+          // Cookies only support second-level resolution. To ensure consistency
+          // between the cookie and the store, truncate the expiration date to
+          // the nearest second.
+          truncateExpirationDate(expirationDate),
+        );
+      }
+    });
+
+    next();
+  });
+}
+
+function signSessionId(sessionId: string, secret: string): string {
+  return signature.sign(sessionId, secret);
+}
+
+function truncateExpirationDate(date: Date) {
+  const time = date.getTime();
+  const truncatedTime = Math.floor(time / 1000) * 1000;
+  return new Date(truncatedTime);
+}

package/src/memory-store.ts

@@ -0,0 +1,25 @@
+import { SessionStore, SessionStoreData } from './store';
+
+export class MemoryStore implements SessionStore {
+  private sessions = new Map<string, { expiresAt: Date; data: string }>();
+
+  async set(id: string, session: any, expiresAt: Date): Promise<void> {
+    this.sessions.set(id, {
+      expiresAt,
+      data: JSON.stringify(session),
+    });
+  }
+
+  async get(id: string): Promise<SessionStoreData | null> {
+    const value = this.sessions.get(id);
+    if (!value) return null;
+    return {
+      expiresAt: value.expiresAt,
+      data: JSON.parse(value.data),
+    };
+  }
+
+  async destroy(id: string): Promise<void> {
+    this.sessions.delete(id);
+  }
+}

package/src/session.test.ts

@@ -0,0 +1,122 @@
+import { assert } from 'chai';
+
+import { MemoryStore } from './memory-store';
+import { hashSession, loadSession, makeSession } from './session';
+
+const SESSION_MAX_AGE = 10000;
+const SESSION_EXPIRATION_DATE = new Date(Date.now() + SESSION_MAX_AGE);
+
+describe('session', () => {
+  describe('loadSession', () => {
+    it('loads session that does not exist', async () => {
+      const store = new MemoryStore();
+
+      const req = {} as any;
+      const session = await loadSession('123', req, store, SESSION_MAX_AGE);
+
+      assert.equal(session.id, '123');
+    });
+
+    it('loads session from store', async () => {
+      const store = new MemoryStore();
+      await store.set('123', { foo: 'bar' }, SESSION_EXPIRATION_DATE);
+
+      const req = {} as any;
+      const session = await loadSession('123', req, store, SESSION_MAX_AGE);
+
+      assert.equal(session.id, '123');
+      assert.equal(session.foo, 'bar');
+    });
+
+    it('does not try to overwrite existing session properties', async () => {
+      const store = new MemoryStore();
+      await store.set('123', { foo: 'bar', id: '456' }, SESSION_EXPIRATION_DATE);
+
+      const req = {} as any;
+      const session = await loadSession('123', req, store, SESSION_MAX_AGE);
+
+      assert.equal(session.id, '123');
+      assert.equal(session.foo, 'bar');
+    });
+  });
+
+  describe('makeSession', () => {
+    it('has immutable properties', () => {
+      const store = new MemoryStore();
+
+      const req = {} as any;
+      const session = makeSession('123', req, store, SESSION_EXPIRATION_DATE, SESSION_MAX_AGE);
+
+      assert.equal(session.id, '123');
+
+      const originalId = session.id;
+      const originalDestroy = session.destroy;
+      const originalRegenerate = session.regenerate;
+
+      assert.throw(() => {
+        session.id = '456';
+      });
+
+      assert.throw(() => {
+        session.destroy = async () => {};
+      });
+
+      assert.throw(() => {
+        session.regenerate = async () => {};
+      });
+
+      assert.equal(session.id, originalId);
+      assert.equal(session.destroy, originalDestroy);
+      assert.equal(session.regenerate, originalRegenerate);
+    });
+
+    it('has immutable destroy property', async () => {
+      const store = new MemoryStore();
+
+      const req = {} as any;
+      const session = makeSession('123', req, store, SESSION_EXPIRATION_DATE, SESSION_MAX_AGE);
+
+      assert.throw(() => {
+        session.destroy = async () => {};
+      });
+    });
+
+    it('can destroy itself', async () => {
+      const store = new MemoryStore();
+
+      const req = {} as any;
+      const session = makeSession('123', req, store, SESSION_EXPIRATION_DATE, SESSION_MAX_AGE);
+      req.session = session;
+
+      await session.destroy();
+
+      assert.isUndefined(req.session);
+      assert.isNull(await store.get('123'));
+    });
+
+    it('can regenerate itself', async () => {
+      const store = new MemoryStore();
+
+      const req = {} as any;
+      const session = makeSession('123', req, store, SESSION_EXPIRATION_DATE, SESSION_MAX_AGE);
+      req.session = session;
+
+      await session.regenerate();
+
+      assert.notEqual(req.session, session);
+      assert.notEqual(req.session.id, '123');
+      assert.isNull(await store.get('123'));
+    });
+  });
+
+  describe('hashSession', () => {
+    it('ignores the cookie property', () => {
+      const hash1 = hashSession({ id: '123' } as any);
+      const hash2 = hashSession({ id: '123', cookie: { foo: 'bar' } } as any);
+
+      assert.equal(hash1, hash2);
+    });
+  });
+
+  it('has cookie property', () => {});
+});

package/src/session.ts

@@ -0,0 +1,106 @@
+import type { Request } from 'express';
+import uid from 'uid-safe';
+import crypto from 'node:crypto';
+
+import type { SessionStore } from './store';
+
+export interface Session {
+  id: string;
+  destroy(): Promise<void>;
+  regenerate(): Promise<void>;
+  setExpiration(expiry: Date | number): void;
+  getExpirationDate(): Date;
+  [key: string]: any;
+}
+
+export async function generateSessionId(): Promise<string> {
+  return await uid(24);
+}
+
+export async function loadSession(
+  sessionId: string,
+  req: Request,
+  store: SessionStore,
+  maxAge: number,
+): Promise<Session> {
+  const sessionStoreData = await store.get(sessionId);
+  const expiresAt = sessionStoreData?.expiresAt ?? null;
+
+  const session = makeSession(sessionId, req, store, expiresAt, maxAge);
+
+  // Copy session data into the session object.
+  if (sessionStoreData != null) {
+    const { data } = sessionStoreData;
+    for (const prop in data) {
+      if (!(prop in session)) {
+        session[prop] = data[prop];
+      }
+    }
+  }
+
+  return session;
+}
+
+export function makeSession(
+  sessionId: string,
+  req: Request,
+  store: SessionStore,
+  expirationDate: Date | null,
+  maxAge: number,
+): Session {
+  const session = {};
+
+  let expiresAt = expirationDate;
+
+  defineStaticProperty<Session['id']>(session, 'id', sessionId);
+
+  defineStaticProperty<Session['destroy']>(session, 'destroy', async () => {
+    delete (req as any).session;
+    await store.destroy(sessionId);
+  });
+
+  defineStaticProperty<Session['regenerate']>(session, 'regenerate', async () => {
+    await store.destroy(sessionId);
+    req.session = makeSession(await generateSessionId(), req, store, null, maxAge);
+  });
+
+  defineStaticProperty<Session['getExpirationDate']>(session, 'getExpirationDate', () => {
+    if (expiresAt == null) {
+      expiresAt = new Date(Date.now() + maxAge);
+    }
+    return expiresAt;
+  });
+
+  defineStaticProperty<Session['setExpiration']>(session, 'setExpiration', (expiration) => {
+    if (typeof expiration === 'number') {
+      expiresAt = new Date(Date.now() + expiration);
+    } else {
+      expiresAt = expiration;
+    }
+  });
+
+  return session as Session;
+}
+
+export function hashSession(session: Session): string {
+  const str = JSON.stringify(session, function (key, val) {
+    // ignore cookie property on the root object
+    if (this === session && key === 'cookie') {
+      return;
+    }
+
+    return val;
+  });
+
+  // hash
+  return crypto.createHash('sha1').update(str, 'utf8').digest('hex');
+}
+
+function defineStaticProperty<T>(obj: object, name: string, fn: T) {
+  Object.defineProperty(obj, name, {
+    configurable: false,
+    enumerable: false,
+    writable: false,
+    value: fn,
+  });
+}

package/src/store.ts

@@ -0,0 +1,10 @@
+export interface SessionStoreData {
+  data: any;
+  expiresAt: Date;
+}
+
+export interface SessionStore {
+  set(id: string, session: any, expiresAt: Date): Promise<void>;
+  get(id: string): Promise<SessionStoreData | null>;
+  destroy(id: string): Promise<void>;
+}

package/src/test-utils.ts

@@ -0,0 +1,42 @@
+import express from 'express';
+import { Server } from 'node:http';
+
+interface WithServerContext {
+  server: Server;
+  port: number;
+  url: string;
+}
+
+export async function withServer(
+  app: express.Express,
+  fn: (ctx: WithServerContext) => Promise<void>,
+) {
+  const server = app.listen();
+
+  await new Promise<void>((resolve, reject) => {
+    server.on('listening', () => resolve());
+    server.on('error', (err) => reject(err));
+  });
+
+  try {
+    await fn({
+      server,
+      port: getServerPort(server),
+      url: `http://localhost:${getServerPort(server)}`,
+    });
+  } finally {
+    server.close();
+  }
+}
+
+function getServerPort(server: Server): number {
+  const address = server.address();
+
+  // istanbul ignore next
+  if (!address) throw new Error('Server is not listening');
+
+  // istanbul ignore next
+  if (typeof address === 'string') throw new Error('Server is listening on a pipe');
+
+  return address.port;
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "@prairielearn/tsconfig/tsconfig.package.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["mocha", "node"]
+  },
+  "ts-node": {
+    "transpileOnly": true
+  }
+}