feat(auth): add "Remember me" checkbox to extend session lifetime (#1189)

Adds a "Remember me" checkbox to the login form (single responsive page,
covers mobile + desktop). Unchecked (default) issues the existing
SESSION_DURATION JWT with a browser-session cookie (no maxAge); checked
issues a longer-lived JWT plus a persistent cookie sized by the new
SESSION_DURATION_REMEMBER env var (default 30d). The choice is threaded
through the MFA verify leg so it survives the step-up.

Register/demo logins keep their current persistent behaviour.

server/src/config.ts

@@ -136,3 +136,21 @@ export const SESSION_DURATION = parsedSessionMs == null ? DEFAULT_SESSION_DURATI
 export const SESSION_DURATION_MS = parsedSessionMs ?? parseDurationMs(DEFAULT_SESSION_DURATION)!;
 /** Session length in seconds — passed to `jwt.sign({ expiresIn })` (number = seconds). */
 export const SESSION_DURATION_SECONDS = Math.floor(SESSION_DURATION_MS / 1000);
+
+// SESSION_DURATION_REMEMBER is the session length used when the user ticks
+// "Remember me" on the login form: a longer-lived JWT `exp` claim plus a
+// persistent `trek_session` cookie `maxAge`. An unticked login keeps
+// SESSION_DURATION and a browser-session cookie (no `maxAge`). Same ms-style
+// format and fallback behavior as SESSION_DURATION.
+const DEFAULT_SESSION_DURATION_REMEMBER = '30d';
+const rawRememberDuration = process.env.SESSION_DURATION_REMEMBER?.trim() || DEFAULT_SESSION_DURATION_REMEMBER;
+const parsedRememberMs = parseDurationMs(rawRememberDuration);
+if (parsedRememberMs == null) {
+  console.warn(`SESSION_DURATION_REMEMBER="${rawRememberDuration}" is not a valid duration (use e.g. 7d, 30d, 90d). Falling back to "${DEFAULT_SESSION_DURATION_REMEMBER}".`);
+}
+/** Human-readable "remember me" session length actually in effect (for logs/diagnostics). */
+export const SESSION_DURATION_REMEMBER = parsedRememberMs == null ? DEFAULT_SESSION_DURATION_REMEMBER : rawRememberDuration;
+/** "Remember me" session length in milliseconds — used for the persistent cookie `maxAge`. */
+export const SESSION_DURATION_REMEMBER_MS = parsedRememberMs ?? parseDurationMs(DEFAULT_SESSION_DURATION_REMEMBER)!;
+/** "Remember me" session length in seconds — passed to `jwt.sign({ expiresIn })`. */
+export const SESSION_DURATION_REMEMBER_SECONDS = Math.floor(SESSION_DURATION_REMEMBER_MS / 1000);

server/src/nest/auth/auth-public.controller.ts

@@ -87,7 +87,7 @@ export class AuthPublicController {
     if (result.mfa_required) {
       return { mfa_required: true, mfa_token: result.mfa_token };
     }
-    this.auth.setAuthCookie(res, result.token!, req);
+    this.auth.setAuthCookie(res, result.token!, req, result.remember);
     return { token: result.token, user: result.user };
   }
 
@@ -146,7 +146,7 @@ export class AuthPublicController {
       throw new HttpException({ error: result.error }, result.status!);
     }
     writeAudit({ userId: result.auditUserId!, action: 'user.login', ip: getClientIp(req), details: { mfa: true } });
-    this.auth.setAuthCookie(res, result.token!, req);
+    this.auth.setAuthCookie(res, result.token!, req, result.remember);
     return { token: result.token, user: result.user };
   }
 

server/src/nest/auth/auth.service.ts

@@ -14,7 +14,7 @@ import type { User } from '../../types';
 @Injectable()
 export class AuthService {
   // Cookie
-  setAuthCookie(res: Response, token: string, req: Request) { setAuthCookie(res, token, req); }
+  setAuthCookie(res: Response, token: string, req: Request, remember?: boolean) { setAuthCookie(res, token, req, remember); }
   clearAuthCookie(res: Response, req: Request) { clearAuthCookie(res, req); }
 
   // Reset-email delivery (canonical app URL, never request headers)

server/src/services/authService.ts

@@ -7,7 +7,7 @@ import { authenticator } from 'otplib';
 import QRCode from 'qrcode';
 import { randomBytes, createHash } from 'crypto';
 import { db } from '../db/database';
-import { JWT_SECRET, SESSION_DURATION_SECONDS } from '../config';
+import { JWT_SECRET, SESSION_DURATION_SECONDS, SESSION_DURATION_REMEMBER_SECONDS } from '../config';
 import { validatePassword } from './passwordPolicy';
 import { encryptMfaSecret, decryptMfaSecret } from './mfaCrypto';
 import { getAllPermissions } from './permissions';
@@ -181,14 +181,17 @@ export function isOidcOnlyMode(): boolean {
   return !resolveAuthToggles().password_login;
 }
 
-export function generateToken(user: { id: number | bigint; password_version?: number }) {
+export function generateToken(user: { id: number | bigint; password_version?: number }, rememberMe = false) {
   const pv = typeof user.password_version === 'number'
     ? user.password_version
     : ((db.prepare('SELECT password_version FROM users WHERE id = ?').get(user.id) as { password_version?: number } | undefined)?.password_version ?? 0);
+  // "Remember me" extends the JWT lifetime to match the persistent cookie maxAge;
+  // the cookie service decides session-vs-persistent off the same flag.
+  const expiresIn = rememberMe ? SESSION_DURATION_REMEMBER_SECONDS : SESSION_DURATION_SECONDS;
   return jwt.sign(
     { id: user.id, pv },
     JWT_SECRET,
-    { expiresIn: SESSION_DURATION_SECONDS, algorithm: 'HS256' }
+    { expiresIn, algorithm: 'HS256' }
   );
 }
 
@@ -443,6 +446,7 @@ export function registerUser(body: {
 export function loginUser(body: {
   email?: string;
   password?: string;
+  remember_me?: boolean;
 }): {
   error?: string;
   status?: number;
@@ -450,6 +454,7 @@ export function loginUser(body: {
   user?: Record<string, unknown>;
   mfa_required?: boolean;
   mfa_token?: string;
+  remember?: boolean;
   auditUserId?: number | null;
   auditAction?: string;
   auditDetails?: Record<string, unknown>;
@@ -458,7 +463,8 @@ export function loginUser(body: {
     return { error: 'Password authentication is disabled. Please sign in with SSO.', status: 403 };
   }
 
-  const { email, password } = body;
+  const { email, password, remember_me } = body;
+  const remember = remember_me === true;
   if (!email || !password) {
     return { error: 'Email and password are required', status: 400 };
   }
@@ -500,12 +506,13 @@ export function loginUser(body: {
   }
 
   db.prepare('UPDATE users SET last_login = CURRENT_TIMESTAMP, login_count = login_count + 1 WHERE id = ?').run(user.id);
-  const token = generateToken(user);
+  const token = generateToken(user, remember);
   const userSafe = stripUserForClient(user) as Record<string, unknown>;
 
   return {
     token,
     user: { ...userSafe, avatar_url: avatarUrl(user) },
+    remember,
     auditUserId: Number(user.id),
     auditAction: 'user.login',
     auditDetails: { email },
@@ -1066,14 +1073,17 @@ export function disableMfa(
 export function verifyMfaLogin(body: {
   mfa_token?: string;
   code?: string;
+  remember_me?: boolean;
 }): {
   error?: string;
   status?: number;
   token?: string;
   user?: Record<string, unknown>;
+  remember?: boolean;
   auditUserId?: number;
 } {
-  const { mfa_token, code } = body;
+  const { mfa_token, code, remember_me } = body;
+  const remember = remember_me === true;
   if (!mfa_token || !code) {
     return { error: 'Verification token and code are required', status: 400 };
   }
@@ -1104,11 +1114,12 @@ export function verifyMfaLogin(body: {
       );
     }
     db.prepare('UPDATE users SET last_login = CURRENT_TIMESTAMP, login_count = login_count + 1 WHERE id = ?').run(user.id);
-    const sessionToken = generateToken(user);
+    const sessionToken = generateToken(user, remember);
     const userSafe = stripUserForClient(user) as Record<string, unknown>;
     return {
       token: sessionToken,
       user: { ...userSafe, avatar_url: avatarUrl(user) },
+      remember,
       auditUserId: Number(user.id),
     };
   } catch {

server/src/services/cookie.ts

@@ -1,8 +1,17 @@
 import { Request, Response } from 'express';
-import { SESSION_DURATION_MS } from '../config';
+import { SESSION_DURATION_MS, SESSION_DURATION_REMEMBER_MS } from '../config';
 
 const COOKIE_NAME = 'trek_session';
 
+/**
+ * Controls the cookie lifetime for a login:
+ *  - `undefined` → persistent `maxAge: SESSION_DURATION_MS` (the historical
+ *    default, used by register/demo and anything that doesn't opt in).
+ *  - `true`  → persistent `maxAge: SESSION_DURATION_REMEMBER_MS` ("Remember me").
+ *  - `false` → no `maxAge` — a browser-session cookie cleared on browser close.
+ */
+export type RememberOption = boolean | undefined;
+
 /**
  * Decide whether the session cookie should carry the `Secure` flag.
  *
@@ -18,27 +27,35 @@ const COOKIE_NAME = 'trek_session';
  * on the outermost hop, the cookie is `Secure`. `COOKIE_SECURE=false`
  * remains the explicit escape hatch for plain-HTTP LAN testing.
  */
-export function cookieOptions(clear = false, req?: Request) {
+export function cookieOptions(clear = false, req?: Request, remember?: RememberOption) {
   if (process.env.COOKIE_SECURE?.toLowerCase() === 'false') {
-    return buildOptions(clear, false);
+    return buildOptions(clear, false, remember);
   }
   const envSecure = process.env.NODE_ENV?.toLowerCase() === 'production' || process.env.FORCE_HTTPS?.toLowerCase() === 'true';
   const requestSecure = req?.secure === true;
-  return buildOptions(clear, envSecure || requestSecure);
+  return buildOptions(clear, envSecure || requestSecure, remember);
 }
 
-function buildOptions(clear: boolean, secure: boolean) {
+function resolveMaxAge(remember: RememberOption): { maxAge: number } | Record<string, never> {
+  // false → session cookie (omit maxAge); true → the longer "remember me"
+  // window; undefined → the historical default. Each maxAge matches the JWT exp.
+  if (remember === false) return {};
+  if (remember === true) return { maxAge: SESSION_DURATION_REMEMBER_MS };
+  return { maxAge: SESSION_DURATION_MS };
+}
+
+function buildOptions(clear: boolean, secure: boolean, remember?: RememberOption) {
   return {
     httpOnly: true,
     secure,
     sameSite: 'lax' as const,
     path: '/',
-    ...(clear ? {} : { maxAge: SESSION_DURATION_MS }), // matches the JWT expiry (SESSION_DURATION)
+    ...(clear ? {} : resolveMaxAge(remember)),
   };
 }
 
-export function setAuthCookie(res: Response, token: string, req?: Request): void {
-  res.cookie(COOKIE_NAME, token, cookieOptions(false, req));
+export function setAuthCookie(res: Response, token: string, req?: Request, remember?: RememberOption): void {
+  res.cookie(COOKIE_NAME, token, cookieOptions(false, req, remember));
 }
 
 export function clearAuthCookie(res: Response, req?: Request): void {

server/tests/e2e/auth.e2e.test.ts

@@ -98,6 +98,28 @@ describe('Auth e2e (real auth guard + real cookie service + temp SQLite)', () =>
     expect(setCookie.some((c) => c.startsWith('trek_session=') && /HttpOnly/i.test(c))).toBe(true);
   }, 10000);
 
+  it('POST /login with remember_me sets a persistent cookie (Max-Age present)', async () => {
+    authSvc.loginUser.mockReturnValue({ token: 'jwt.token.value', user: { id: 1 }, remember: true });
+    const res = await request(server).post('/api/auth/login').send({ email: 'u@example.test', password: 'pw', remember_me: true });
+    expect(res.status).toBe(200);
+    const setCookie = res.headers['set-cookie'] as unknown as string[];
+    const cookie = setCookie.find((c) => c.startsWith('trek_session='))!;
+    expect(cookie).toMatch(/Max-Age=\d+/i);
+    // 30d default — well above the 24h (86400s) non-remember window.
+    const maxAge = Number(/Max-Age=(\d+)/i.exec(cookie)?.[1]);
+    expect(maxAge).toBeGreaterThan(86_400);
+  }, 10000);
+
+  it('POST /login without remember_me sets a session cookie (no Max-Age)', async () => {
+    authSvc.loginUser.mockReturnValue({ token: 'jwt.token.value', user: { id: 1 }, remember: false });
+    const res = await request(server).post('/api/auth/login').send({ email: 'u@example.test', password: 'pw' });
+    expect(res.status).toBe(200);
+    const setCookie = res.headers['set-cookie'] as unknown as string[];
+    const cookie = setCookie.find((c) => c.startsWith('trek_session='))!;
+    expect(cookie).not.toMatch(/Max-Age/i);
+    expect(cookie).not.toMatch(/Expires/i);
+  }, 10000);
+
   it('POST /logout clears the session cookie', async () => {
     const res = await request(server).post('/api/auth/logout');
     expect(res.status).toBe(200);

server/tests/unit/nest/auth.controller.test.ts

@@ -82,9 +82,10 @@ describe('AuthPublicController', () => {
     const setAuthCookie = vi.fn();
     const mfa = new AuthPublicController(asvc({ loginUser: vi.fn().mockReturnValue({ mfa_required: true, mfa_token: 'mt' }) } as Partial<AuthService>), rl());
     expect(await mfa.login({}, req, res)).toEqual({ mfa_required: true, mfa_token: 'mt' });
-    const ok = new AuthPublicController(asvc({ loginUser: vi.fn().mockReturnValue({ token: 'tk', user }), setAuthCookie } as Partial<AuthService>), rl());
+    const ok = new AuthPublicController(asvc({ loginUser: vi.fn().mockReturnValue({ token: 'tk', user, remember: true }), setAuthCookie } as Partial<AuthService>), rl());
     expect(await ok.login({}, req, res)).toEqual({ token: 'tk', user });
-    expect(setAuthCookie).toHaveBeenCalled();
+    // The "remember me" flag from the service rides through to the cookie service.
+    expect(setAuthCookie).toHaveBeenCalledWith(res, 'tk', req, true);
     const bad = new AuthPublicController(asvc({ loginUser: vi.fn().mockReturnValue({ error: 'Bad creds', status: 401, auditAction: 'user.login_fail' }) } as Partial<AuthService>), rl());
     expect(await thrownAsync(() => bad.login({}, req, res))).toEqual({ status: 401, body: { error: 'Bad creds' } });
   }, 10000);

server/tests/unit/services/cookie.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
 import { cookieOptions } from '../../../src/services/cookie';
+import { SESSION_DURATION_MS, SESSION_DURATION_REMEMBER_MS } from '../../../src/config';
 
 describe('cookieOptions', () => {
   afterEach(() => {
@@ -53,4 +54,16 @@ describe('cookieOptions', () => {
     const opts = cookieOptions(true);
     expect(opts).not.toHaveProperty('maxAge');
   });
+
+  it('keeps the default SESSION_DURATION maxAge when remember is undefined', () => {
+    expect(cookieOptions(false, undefined)).toHaveProperty('maxAge', SESSION_DURATION_MS);
+  });
+
+  it('uses the longer SESSION_DURATION_REMEMBER maxAge when remember is true', () => {
+    expect(cookieOptions(false, undefined, true)).toHaveProperty('maxAge', SESSION_DURATION_REMEMBER_MS);
+  });
+
+  it('omits maxAge (session cookie) when remember is false', () => {
+    expect(cookieOptions(false, undefined, false)).not.toHaveProperty('maxAge');
+  });
 });