@prairielearn/session 2.0.6 → 3.0.0

package/src/index.ts

@@ -2,22 +2,18 @@ import type { Request, Response, NextFunction } from 'express';
 import onHeaders from 'on-headers';
 import signature from 'cookie-signature';
 import asyncHandler from 'express-async-handler';
+import cookie from 'cookie';
 
-import { SessionStore } from './store';
-import { beforeEnd } from './before-end';
-import {
-  type CookieSecure,
-  shouldSecureCookie,
-  getSessionCookie,
-  getSessionIdFromCookie,
-} from './cookie';
+import { type SessionStore } from './store.js';
+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';
 
 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

@@ -2,7 +2,7 @@ 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;