@prairielearn/session 2.0.6 → 3.0.1

package/src/index.test.ts

@@ -1,16 +1,22 @@
-import express from 'express';
 import { assert } from 'chai';
-import fetch from 'node-fetch';
-import fetchCookie from 'fetch-cookie';
-import { parse as parseSetCookie } from 'set-cookie-parser';
+import express from 'express';
 import asyncHandler from 'express-async-handler';
+import fetchCookie from 'fetch-cookie';
+import fetch from 'node-fetch';
+import setCookie from 'set-cookie-parser';
+
 import { withServer } from '@prairielearn/express-test-utils';
 
-import { createSessionMiddleware } from './index';
-import { MemoryStore } from './memory-store';
+import { MemoryStore } from './memory-store.js';
+
+import { createSessionMiddleware } from './index.js';
 
 const TEST_SECRET = 'test-secret';
 
+function parseSetCookie(header: string) {
+  return setCookie.parse(setCookie.splitCookiesString(header));
+}
+
 describe('session middleware', () => {
   it('sets a session cookie', async () => {
     const app = express();
@@ -578,7 +584,9 @@ describe('session middleware', () => {
         store,
         secret: TEST_SECRET,
         cookie: {
-          name: ['session', 'legacy_session'],
+          name: 'legacy_session',
+          writeNames: ['legacy_session', 'session'],
+          writeOverrides: [{ domain: undefined }, { domain: '.example.com' }],
         },
       }),
     );
@@ -604,8 +612,11 @@ describe('session middleware', () => {
       const header = res.headers.get('set-cookie');
       assert.isNotNull(header);
       const cookies = parseSetCookie(header ?? '');
-      assert.equal(cookies.length, 1);
-      assert.equal(cookies[0].name, 'session');
+      assert.equal(cookies.length, 2);
+      assert.equal(cookies[0].name, 'legacy_session');
+      assert.isUndefined(cookies[0].domain);
+      assert.equal(cookies[1].name, 'session');
+      assert.equal(cookies[1].domain, '.example.com');
 
       // Ensure that the legacy session is migrated to a new session.
       assert.equal(newSessionId, legacySessionId);

package/src/index.ts

@@ -1,23 +1,19 @@
-import type { Request, Response, NextFunction } from 'express';
-import onHeaders from 'on-headers';
+import cookie from 'cookie';
 import signature from 'cookie-signature';
+import type { Request, Response, NextFunction } from 'express';
 import asyncHandler from 'express-async-handler';
+import onHeaders from 'on-headers';
 
-import { SessionStore } from './store';
-import { beforeEnd } from './before-end';
-import {
-  type CookieSecure,
-  shouldSecureCookie,
-  getSessionCookie,
-  getSessionIdFromCookie,
-} from './cookie';
+import { beforeEnd } from './before-end.js';
+import { type CookieSecure, shouldSecureCookie, getSessionIdFromCookie } from './cookie.js';
 import {
   type Session,
   generateSessionId,
   loadSession,
   hashSession,
   truncateExpirationDate,
-} from './session';
+} from './session.js';
+import { type SessionStore } from './store.js';
 
 declare global {
   // eslint-disable-next-line @typescript-eslint/no-namespace
@@ -28,22 +24,34 @@ declare global {
   }
 }
 
+interface CookieOptions {
+  secure?: CookieSecure;
+  httpOnly?: boolean;
+  domain?: string;
+  sameSite?: boolean | 'none' | 'lax' | 'strict';
+  maxAge?: number;
+}
+
 export interface SessionOptions {
   secret: string | string[];
   store: SessionStore;
-  cookie?: {
+  cookie?: CookieOptions & {
+    /**
+     * The name of the session cookie. The session is always read from this
+     * named cookie, but it may be written to multiple cookies if `writeNames`
+     * is provided.
+     */
+    name?: string;
     /**
-     * If multiple names are provided, the first one is used as the primary
-     * name for setting the cookie. The other names are used as fallbacks when
-     * reading the cookie in requests. If a fallback name is found in a request,
-     * the cookie value will be transparently re-written to the primary name.
+     * Multiple write names can be provided to allow for a session cookie to be
+     * written to multiple names. This can be useful for a migration of a cookie
+     * to an explicit subdomain, for example.
      */
-    name?: string | string[];
-    secure?: CookieSecure;
-    httpOnly?: boolean;
-    domain?: string;
-    sameSite?: boolean | 'none' | 'lax' | 'strict';
-    maxAge?: number;
+    writeNames?: string[];
+    /**
+     * Used with `writeNames` to provide additional options for each written cookie.
+     */
+    writeOverrides?: Omit<CookieOptions, 'secure'>[];
   };
 }
 
@@ -54,18 +62,35 @@ const DEFAULT_COOKIE_MAX_AGE = 86400000; // 1 day
 
 export function createSessionMiddleware(options: SessionOptions) {
   const secrets = Array.isArray(options.secret) ? options.secret : [options.secret];
-  const cookieNames = getCookieNames(options.cookie?.name);
-  const primaryCookieName = cookieNames[0];
+  const cookieName = options.cookie?.name ?? DEFAULT_COOKIE_NAME;
   const cookieMaxAge = options.cookie?.maxAge ?? DEFAULT_COOKIE_MAX_AGE;
   const store = options.store;
 
+  // Ensure that the session cookie that we're reading from will be written to.
+  const writeCookieNames = options.cookie?.writeNames ?? [cookieName];
+  if (!writeCookieNames.includes(cookieName)) {
+    throw new Error('cookie.name must be included in cookie.writeNames');
+  }
+
+  // Validate write overrides.
+  if (options.cookie?.writeOverrides && !options.cookie.writeNames) {
+    throw new Error('cookie.writeOverrides must be used with cookie.writeNames');
+  }
+  if (
+    options.cookie?.writeOverrides &&
+    options.cookie.writeOverrides.length !== writeCookieNames.length
+  ) {
+    throw new Error('cookie.writeOverrides must have the same length as cookie.writeNames');
+  }
+
   return asyncHandler(async function sessionMiddleware(
     req: Request,
     res: Response,
     next: NextFunction,
   ) {
-    const sessionCookie = getSessionCookie(req, cookieNames);
-    const cookieSessionId = getSessionIdFromCookie(sessionCookie?.value, secrets);
+    const cookies = cookie.parse(req.headers.cookie ?? '');
+    const sessionCookie = cookies[cookieName];
+    const cookieSessionId = getSessionIdFromCookie(sessionCookie, secrets);
     const sessionId = cookieSessionId ?? (await generateSessionId());
     req.session = await loadSession(sessionId, req, store, cookieMaxAge);
 
@@ -79,9 +104,15 @@ export function createSessionMiddleware(options: SessionOptions) {
           // destroyed, clear the cookie.
           //
           // To cover all our bases, we'll clear *all* known session cookies to
-          // ensure that state sessions aren't left behind.
-          cookieNames.forEach((cookieName) => {
+          // ensure that state sessions aren't left behind. We'll also send commands
+          // to clear the cookies both on and off the explicit domain, to handle
+          // the case where the application has moved from one domain to another.
+          writeCookieNames.forEach((cookieName, i) => {
             res.clearCookie(cookieName);
+            const domain = options.cookie?.writeOverrides?.[i]?.domain ?? options.cookie?.domain;
+            if (domain) {
+              res.clearCookie(cookieName, { domain: options.cookie?.domain });
+            }
           });
           return;
         }
@@ -96,18 +127,22 @@ export function createSessionMiddleware(options: SessionOptions) {
         return;
       }
 
-      const needsRotation = sessionCookie?.name && sessionCookie?.name !== primaryCookieName;
+      // Ensure that all known session cookies are set to the same value.
+      const hasAllCookies = writeCookieNames.every((cookieName) => !!cookies[cookieName]);
       const isNewSession = !cookieSessionId || cookieSessionId !== req.session.id;
       const didExpirationChange =
         originalExpirationDate.getTime() !== req.session.getExpirationDate().getTime();
-      if (isNewSession || didExpirationChange || needsRotation) {
+      if (isNewSession || didExpirationChange || !hasAllCookies) {
         const signedSessionId = signSessionId(req.session.id, secrets[0]);
-        res.cookie(primaryCookieName, signedSessionId, {
-          secure: secureCookie,
-          httpOnly: options.cookie?.httpOnly ?? true,
-          domain: options.cookie?.domain,
-          sameSite: options.cookie?.sameSite ?? false,
-          expires: req.session.getExpirationDate(),
+        writeCookieNames.forEach((cookieName, i) => {
+          res.cookie(cookieName, signedSessionId, {
+            secure: secureCookie,
+            httpOnly: options.cookie?.httpOnly ?? true,
+            domain: options.cookie?.domain,
+            sameSite: options.cookie?.sameSite ?? false,
+            expires: req.session.getExpirationDate(),
+            ...(options.cookie?.writeOverrides?.[i] ?? {}),
+          });
         });
       }
     });
@@ -168,18 +203,6 @@ export function createSessionMiddleware(options: SessionOptions) {
   });
 }
 
-function getCookieNames(cookieName: string | string[] | undefined): string[] {
-  if (!cookieName) {
-    return [DEFAULT_COOKIE_NAME];
-  }
-
-  if (Array.isArray(cookieName) && cookieName.length === 0) {
-    throw new Error('cookie.name must not be an empty array');
-  }
-
-  return Array.isArray(cookieName) ? cookieName : [cookieName];
-}
-
 function signSessionId(sessionId: string, secret: string): string {
   return signature.sign(sessionId, secret);
 }

package/src/memory-store.ts

@@ -1,4 +1,4 @@
-import { SessionStore, SessionStoreData } from './store';
+import { SessionStore, SessionStoreData } from './store.js';
 
 export class MemoryStore implements SessionStore {
   private sessions = new Map<string, { expiresAt: Date; data: string }>();

package/src/session.test.ts

@@ -1,7 +1,7 @@
 import { assert } from 'chai';
 
-import { MemoryStore } from './memory-store';
-import { loadSession, makeSession } from './session';
+import { MemoryStore } from './memory-store.js';
+import { loadSession, makeSession } from './session.js';
 
 const SESSION_MAX_AGE = 10000;
 const SESSION_EXPIRATION_DATE = new Date(Date.now() + SESSION_MAX_AGE);

package/src/session.ts

@@ -1,8 +1,9 @@
+import crypto from 'node:crypto';
+
 import type { Request } from 'express';
 import uid from 'uid-safe';
-import crypto from 'node:crypto';
 
-import type { SessionStore } from './store';
+import { SessionStore } from './store.js';
 
 export interface Session {
   id: string;

package/src/test-utils.ts

@@ -1,6 +1,7 @@
-import express from 'express';
 import { Server } from 'node:http';
 
+import express from 'express';
+
 interface WithServerContext {
   server: Server;
   port: number;