linuxfoundation
diff --git a/‎apps/lfx-one/src/server/errors/authentication.error.ts‎
Lines changed: 9 additions & 1 deletion b/‎apps/lfx-one/src/server/errors/authentication.error.ts‎
Lines changed: 9 additions & 1 deletion
diff --git a/‎apps/lfx-one/src/server/middleware/error-handler.middleware.ts‎
Lines changed: 9 additions & 1 deletion b/‎apps/lfx-one/src/server/middleware/error-handler.middleware.ts‎
Lines changed: 9 additions & 1 deletion
diff --git a/‎apps/lfx-one/src/server/server.ts‎
Lines changed: 80 additions & 0 deletions b/‎apps/lfx-one/src/server/server.ts‎
Lines changed: 80 additions & 0 deletions
diff --git a/‎apps/lfx-one/src/server/services/session-store.service.ts‎
Lines changed: 194 additions & 0 deletions b/‎apps/lfx-one/src/server/services/session-store.service.ts‎
Lines changed: 194 additions & 0 deletions
@@ -8,16 +8,24 @@ import { BaseApiError } from './base.error';
  * Used when a user attempts to access protected routes without proper authentication
  */
 export class AuthenticationError extends BaseApiError {
+  /** When true, `apiErrorHandler` clears `req.appSession` before responding, so express-openid-connect's
+   * cookie-write hook (which fires independently of how the request settles) clears the session cookie
+   * instead of reissuing it — needed whenever the thrown error means the session data can't be trusted. */
+  public readonly clearSession: boolean;
+
   public constructor(
     message = 'Authentication required',
     options: {
       operation?: string;
       service?: string;
       path?: string;
       metadata?: Record<string, any>;
+      clearSession?: boolean;
     } = {}
   ) {
-    super(message, 401, 'AUTHENTICATION_REQUIRED', options);
+    const { clearSession, ...rest } = options;
+    super(message, 401, 'AUTHENTICATION_REQUIRED', rest);
+    this.clearSession = clearSession ?? false;
   }
 }
 
 
@@ -3,7 +3,7 @@
 
 import { NextFunction, Request, Response } from 'express';
 
-import { BaseApiError, isBaseApiError } from '../errors';
+import { AuthenticationError, BaseApiError, isBaseApiError } from '../errors';
 import { logger } from '../services/logger.service';
 
 /**
@@ -22,6 +22,14 @@ function getOperationFromPath(path: string): string {
 }
 
 export function apiErrorHandler(error: Error | BaseApiError, req: Request, res: Response, next: NextFunction): void {
+  // express-openid-connect's session-write hook (the patched res.end()) can throw this error after
+  // headers were already flushed — e.g. SSE controllers that flush before streaming. Clear the
+  // in-memory session before the headersSent check below so a failed write's session still gets
+  // cleared (and its cookie not reissued) even on responses we can no longer reshape.
+  if (error instanceof AuthenticationError && error.clearSession) {
+    req.appSession = null;
+  }
+
   // If response already sent, delegate to default Express error handler
   if (res.headersSent) {
     next(error);
 
@@ -8,6 +8,7 @@ import { AuthContext, RuntimeConfig, User } from '@lfx-one/shared/interfaces';
 import dotenv from 'dotenv';
 import express, { NextFunction, Request, Response } from 'express';
 import { attemptSilentLogin, auth, ConfigParams } from 'express-openid-connect';
+import { randomBytes } from 'node:crypto';
 import { Server as HttpServer } from 'node:http';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,6 +19,7 @@ import { ProfileController } from './controllers/profile.controller';
 import { CrowdfundingAuthService } from './services/crowdfunding-auth.service';
 import { customErrorSerializer } from './helpers/error-serializer';
 import { validateAndSanitizeUrl } from './helpers/url-validation';
+import { AuthenticationError } from './errors';
 import { authMiddleware } from './middleware/auth.middleware';
 import { apiErrorHandler } from './middleware/error-handler.middleware';
 import { apiRateLimiter, authRateLimiter, publicApiRateLimiter } from './middleware/rate-limit.middleware';
@@ -60,6 +62,7 @@ import mktgAgentsRouter from './routes/mktg-agents.route';
 import { reqSerializer, resSerializer, serverLogger } from './server-logger';
 import { logger } from './services/logger.service';
 import { NatsService } from './services/nats.service';
+import { sessionStoreService } from './services/session-store.service';
 import { SnowflakeService } from './services/snowflake.service';
 import { clearImpersonationSession, decodeJwtPayload } from './utils/auth-helper';
 import { isShuttingDown, markShuttingDown, runShutdownHooks } from './utils/shutdown';
@@ -165,6 +168,32 @@ const httpLogger = pinoHttp({
 
 app.use(httpLogger);
 
+// LFXV2-2666: move the session bundle out of the encrypted `appSession` cookie and into Valkey,
+// keyed by an opaque session id, so cookie size stays flat as more tokens (impersonation,
+// API-gateway, crowdfunding, profile) are added onto req.appSession. Only wired up when
+// SESSION_STORE_ENABLED is set and VALKEY_URL is present — without VALKEY_URL every store
+// read/write would degrade to "session missing" (ValkeyService's fail-soft behavior) and silently
+// log everyone out. Note: this only gates on URL presence, not live reachability — a Valkey outage
+// after startup surfaces as failed session writes (401, forced re-login) rather than a silent miss
+// (see SessionStoreService for the fail-soft read / fail-closed write behavior).
+//
+// Rollout note: toggling this flag changes what the `appSession` cookie *means* (encrypted JWE vs.
+// opaque Valkey id). The chart's default RollingUpdate strategy means old and new pods coexist
+// during the rollout window, so requests hitting different pods will flap between "valid session"
+// and "invalid session" until the rollout completes — see the PR description's rollout-safety note
+// for the accepted operational mitigation.
+const valkeyUrl = process.env['VALKEY_URL'];
+const sessionStoreEnabled = process.env['SESSION_STORE_ENABLED'] === 'true' && !!valkeyUrl;
+
+// The session-store payload carries the full bearer-token bundle (Auth0 access/refresh plus
+// impersonation/API-gateway/crowdfunding/profile tokens) — unlike ValkeyService's other, lower-
+// sensitivity cache entries, a plaintext `redis://` transport would ship those credentials
+// unencrypted. Fail startup rather than silently degrade; local/dev environments are exempt since
+// they don't carry real user credentials.
+if (sessionStoreEnabled && process.env['NODE_ENV'] === 'production' && !valkeyUrl!.startsWith('rediss://')) {
+  throw new Error('SESSION_STORE_ENABLED requires a TLS-secured VALKEY_URL (rediss://) in production — refusing to start with an insecure transport.');
+}
+
 const authConfig: ConfigParams = {
   // Global auth disabled; selective middleware handles it.
   authRequired: false,
@@ -182,8 +211,52 @@ const authConfig: ConfigParams = {
   routes: {
     login: false,
   },
+  ...(sessionStoreEnabled && {
+    session: {
+      store: sessionStoreService,
+      // 256 bits of cryptographically strong randomness — sufficient entropy on its own, per the
+      // library's genid docs, without needing signSessionStoreCookie. 64 hex chars is also the
+      // exact cap enforced by isFilterSafeIdentifier (used to build the Valkey cache key) — don't
+      // widen randomBytes() or change the encoding without raising that cap too, or every session
+      // id will fail the cache-key safety check and every session will be treated as missing.
+      genid: () => randomBytes(32).toString('hex'),
+    },
+  }),
 };
 
+// The native custom-store cookie writer (appSession.js's CustomStore.setCookie) only ever sets or
+// clears the single unchunked `appSession` cookie — it has no awareness of the legacy
+// `appSession.0`, `appSession.1`, ... chunk cookies a large pre-cutover session may have left in a
+// user's browser. Left uncleared, those chunks stay valid (decryptable, unexpired) in the browser
+// even after the user logs out under the store, and a later rollback to cookie mode would silently
+// re-authenticate them from that stale, pre-cutover session snapshot. Proactively clear any such
+// chunks on every request while the store is enabled, so nothing survives to be resurrected by a
+// rollback.
+//
+// Registered BEFORE auth(authConfig): express-openid-connect's built-in /logout route completes
+// the response inside its own router without calling next(), so cleanup registered after auth()
+// would never run on a logout request — the exact request where clearing these chunks matters most.
+if (sessionStoreEnabled) {
+  // Mirror the attributes express-openid-connect used when it originally set these chunk cookies
+  // (config.js's session.cookie defaults: httpOnly=true, sameSite='Lax', secure=true iff baseURL is
+  // https) — a Set-Cookie clear with mismatched attributes can be silently ignored by the browser.
+  const chunkCookieOptions = { httpOnly: true, sameSite: 'lax' as const, secure: /^https:/i.test(authConfig.baseURL as string) };
+  app.use((req, res, next) => {
+    const cookieHeader = req.headers.cookie;
+    if (cookieHeader) {
+      for (const pair of cookieHeader.split(';')) {
+        const eqIndex = pair.indexOf('=');
+        if (eqIndex === -1) continue;
+        const name = pair.slice(0, eqIndex).trim();
+        if (/^appSession\.\d+$/.test(name)) {
+          res.clearCookie(name, chunkCookieOptions);
+        }
+      }
+    }
+    next();
+  });
+}
+
 app.use(auth(authConfig));
 
 // Meeting join pages are optional-auth; silent login picks up any existing SSO session.
@@ -414,6 +487,13 @@ app.use('/**', async (req: Request, res: Response, next: NextFunction) => {
 
 // Global error handler — must be last.
 app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
+  // Clear the in-memory session before this headersSent guard so a failed session write's
+  // clearSession still takes effect on SSR/auth-redirect routes that flush headers before
+  // apiErrorHandler would otherwise run — mirrors the same guard inside apiErrorHandler itself.
+  if (error instanceof AuthenticationError && error.clearSession) {
+    req.appSession = null;
+  }
+
   if (res.headersSent) {
     next(error);
     return;
 
@@ -0,0 +1,194 @@
+// Copyright The Linux Foundation and each contributor to LFX.
+// SPDX-License-Identifier: MIT
+
+import { VALKEY_CACHE } from '@lfx-one/shared/constants';
+import { SessionStorePayload } from '@lfx-one/shared/interfaces';
+
+import { AuthenticationError } from '../errors';
+import { buildSessionCacheKey, valkeyService } from './valkey.service';
+import { logger } from './logger.service';
+
+/**
+ * express-openid-connect session store backed by Valkey. Moves the session bundle (Auth0 tokens
+ * plus impersonation / API-gateway / crowdfunding / profile tokens written onto `req.appSession`)
+ * out of the encrypted `appSession` cookie and into Valkey, keyed by an opaque session id — the
+ * cookie then only carries that id. Reads are fail-soft: a Valkey read fault degrades to a miss
+ * (treated by express-openid-connect as an expired session, forcing re-auth) rather than a 500,
+ * matching ValkeyService's existing fail-soft cache behavior. Writes are always fail-closed: a
+ * session that fails to persist is invalidated (so a stale/mutated value never survives at that
+ * key) and throws an `AuthenticationError` (401) rather than resolving — express-openid-connect
+ * surfaces the throw as a request error, and 401 rather than a bare 500 means a Valkey outage
+ * degrades every affected request to "please log in again" instead of a crash, mirroring the
+ * fail-soft *experience* of a read fault while never serving stale data. This applies uniformly to
+ * every write (new session or rolling refresh) — a refresh write can carry a real mutation (e.g.
+ * stop-impersonation clearing `impersonationToken`), and there's no cheap, reliable way to prove
+ * the payload is unchanged before deciding it's safe to leave the prior entry in place.
+ *
+ * Structurally matches express-openid-connect's `session.store` contract (`get`/`set`/`destroy`
+ * with a callback) — that type isn't exported from the library, so compatibility is enforced by
+ * assignment in `server.ts` rather than an `implements` clause here.
+ */
+export class SessionStoreService {
+  // express-openid-connect's safePromisify probes callback-vs-promise stores two ways: first by
+  // checking whether the method's *minified* source still contains the substring "cb"/"callback"
+  // (unreliable — production builds minify local parameter names), and if that fails, by invoking
+  // the method with no callback arg and checking whether the result is a thenable. Returning the
+  // underlying promise whenever `callback` is omitted satisfies that probe under either detection
+  // path, instead of invoking `callback` as a function when it's `undefined`.
+  public get(sid: string, callback?: (err: unknown, session?: SessionStorePayload | null) => void): void | Promise<SessionStorePayload | null> {
+    const promise = this.getAsync(sid);
+    if (!callback) {
+      return promise;
+    }
+    void promise.then(
+      (session) => callback(null, session),
+      (err) => callback(err)
+    );
+  }
+
+  public set(sid: string, session?: SessionStorePayload, callback?: (err?: unknown) => void): void | Promise<void> {
+    // The same detection probe above can invoke `set` with only the `sid` arg to test for a
+    // thenable return — guard against treating that as a real write (which would persist
+    // `undefined` as the session value) rather than reaching setAsync with a missing payload.
+    if (!session) {
+      return callback ? callback() : Promise.resolve();
+    }
+    const promise = this.setAsync(sid, session);
+    if (!callback) {
+      return promise;
+    }
+    void promise.then(
+      () => callback(),
+      (err) => callback(err)
+    );
+  }
+
+  public destroy(sid: string, callback?: (err?: unknown) => void): void | Promise<void> {
+    const promise = this.destroyAsync(sid);
+    if (!callback) {
+      return promise;
+    }
+    void promise.then(
+      () => callback(),
+      (err) => callback(err)
+    );
+  }
+
+  private async getAsync(sid: string): Promise<SessionStorePayload | null> {
+    const key = this.cacheKey(sid);
+    if (key === null) {
+      return null;
+    }
+    return valkeyService.getJson<SessionStorePayload>(key, SessionStoreService.isSessionPayload);
+  }
+
+  private async setAsync(sid: string, session: SessionStorePayload): Promise<void> {
+    const startTime = logger.startOperation(undefined, 'session_store_set');
+    const key = this.cacheKey(sid);
+    if (key === null) {
+      // Nothing was persisted, so letting this resolve normally would hand back a cookie whose id
+      // never resolves in Valkey — the same unrecoverable-login-loop failure mode a Valkey write
+      // failure below fails closed on. Fail closed here too instead of silently no-op'ing.
+      throw new AuthenticationError('Your session could not be saved — please sign in again.', {
+        operation: 'session_store_set',
+        clearSession: true,
+      });
+    }
+    const ttlSeconds = this.ttlSecondsFor(session);
+    const persisted = await valkeyService.setJson(key, session, ttlSeconds);
+    if (!persisted) {
+      // setJson is a `SET key val EX ttl` — a failed write leaves any prior value at this key
+      // untouched, so a stale session (e.g. a cleared impersonation token) would otherwise survive
+      // and be reloaded on the next request. Always invalidate on a failed write — whether this was
+      // a brand-new session or a rolling refresh — since a refresh write can carry a real mutation
+      // and there's no cheap, reliable way to prove the payload is unchanged before leaving the
+      // prior entry in place.
+      // `set` and `del` are independent Redis commands — a transient blip can fail both back-to-back
+      // while a later `get` succeeds against a since-recovered connection, resurrecting the stale
+      // entry. One immediate retry closes most of that window without adding real latency.
+      let invalidated = await valkeyService.del(key);
+      if (!invalidated) {
+        invalidated = await valkeyService.del(key);
+      }
+      if (!invalidated) {
+        logger.error(undefined, 'session_store_set', startTime, new Error('Valkey write and fallback invalidation both failed'), {
+          message: 'Session write failed and the stale entry could not be invalidated — a prior session value may still be served',
+        });
+      } else {
+        logger.warning(
+          undefined,
+          'session_store_set',
+          'Session write failed — invalidated the stale entry; apiErrorHandler clears the cookie and the current request gets a 401, forcing an immediate re-login'
+        );
+      }
+      // express-openid-connect awaits store.set() inside its res.end() wrapper and calls next(err)
+      // on rejection instead of completing the response. Throwing AuthenticationError (401) rather
+      // than a bare Error means apiErrorHandler returns a structured "please re-authenticate"
+      // response and logs at warn (not error) — so a Valkey outage degrades every affected request
+      // to a forced re-login instead of a raw 500, without ever serving the invalidated stale entry.
+      // Also tell apiErrorHandler to clear req.appSession: express-openid-connect's cookie-write hook
+      // fires regardless of this throw, and would otherwise reissue a cookie pointing at a stale (or
+      // un-invalidated) Valkey entry.
+      throw new AuthenticationError('Your session could not be saved — please sign in again.', { operation: 'session_store_set', clearSession: true });
+    }
+  }
+
+  private async destroyAsync(sid: string): Promise<void> {
+    const startTime = logger.startOperation(undefined, 'session_store_destroy');
+    const key = this.cacheKey(sid);
+    if (key === null) {
+      return;
+    }
+    const deleted = await valkeyService.del(key);
+    if (!deleted) {
+      logger.error(undefined, 'session_store_destroy', startTime, new Error('Valkey delete failed'), {
+        message: 'Session delete failed on logout — session will remain valid in Valkey until it expires via TTL',
+      });
+    }
+  }
+
+  /** Fail-closed on an unsafe/oversized session id — express-openid-connect then treats the session as missing rather than reading/writing a corrupt key. */
+  private cacheKey(sid: string): string | null {
+    const key = buildSessionCacheKey(sid);
+    if (key === null) {
+      // The sid comes straight from an unsigned cookie an anonymous client controls, so a malformed
+      // value is expected untrusted input rather than a system fault — debug, not warn, avoids a
+      // log flood from probing/malformed cookies ahead of route-level rate limiting.
+      logger.debug(undefined, 'session_store_key', 'Session id failed the cache-key safety check — treating session as missing');
+    }
+    return key;
+  }
+
+  /** Derives the Valkey TTL from the session's own `cookie.maxAge` (set by express-openid-connect from `session.rollingDuration`/`session.absoluteDuration`) so entries expire alongside the cookie; falls back to the configured default if that shape is ever missing. */
+  private ttlSecondsFor(session: SessionStorePayload): number {
+    const maxAgeMs = session.cookie?.maxAge;
+    if (typeof maxAgeMs === 'number') {
+      // A present-but-non-positive maxAge means the cookie has already reached its absolute expiry —
+      // the multi-day fallback below is reserved for missing/invalid metadata, not an expired session.
+      return maxAgeMs > 0 ? Math.ceil(maxAgeMs / 1000) : VALKEY_CACHE.SESSION_EXPIRED_TTL_SECONDS;
+    }
+    return VALKEY_CACHE.SESSION_FALLBACK_TTL_SECONDS;
+  }
+
+  /**
+   * Guards against a corrupt/legacy cache entry being handed back to express-openid-connect as a
+   * valid session — a shallow key-presence check would let e.g. `data: null` through, and
+   * express-openid-connect crashes trying to redefine `req.appSession` with a non-object value.
+   */
+  private static isSessionPayload(value: unknown): value is SessionStorePayload {
+    if (typeof value !== 'object' || value === null) {
+      return false;
+    }
+    const header = (value as { header?: unknown }).header;
+    const data = (value as { data?: unknown }).data;
+    const cookie = (value as { cookie?: unknown }).cookie;
+    if (typeof header !== 'object' || header === null || typeof data !== 'object' || data === null || typeof cookie !== 'object' || cookie === null) {
+      return false;
+    }
+    const { iat, uat, exp } = header as { iat?: unknown; uat?: unknown; exp?: unknown };
+    const { expires, maxAge } = cookie as { expires?: unknown; maxAge?: unknown };
+    return typeof iat === 'number' && typeof uat === 'number' && typeof exp === 'number' && typeof expires === 'number' && typeof maxAge === 'number';
+  }
+}
+
+export const sessionStoreService = new SessionStoreService();