Session

Introduction

Browser sessions in JCC Express MVC build on express-session and connect-flash, registered in the framework’s global middleware stack. After those run, each request gets:

• req.session — the Express session object (plain record you can read and assign).
• req.flash(...) — flash messaging API from connect-flash (messages cleared after they are read on the next request pattern).
• req.jccSession — a session bridge that mirrors the same store: get / put / flash / getFlash / all / forget / flush, plus save, regenerate, and getId.

The global helper session() returns request()?.jccSession when the per-request container binding is active (same window as request() / response() — see Request and Routing).

HTTP handlers normally use req.session and req.jccSession.

Configuration

Session middleware uses express-session with options such as secret: process.env.SESSION_SECRET || "your_secret", resave, saveUninitialized, and cookie secure flags. Harden this in production: set SESSION_SECRET in .env, enable secure cookies behind HTTPS, and tune sameSite as needed.

Configure drivers, lifetime, and cookie options in app/Config/session.ts when you need file, database, or Redis session storage.

Reading and writing session data

Via req.session

(req.session as any).cartId = "abc";
const cartId = (req.session as any).cartId;

Via req.jccSession (recommended JCC style)

req.jccSession?.put("cartId", "abc");
const cartId = req.jccSession?.get("cartId");
if (req.jccSession?.has("step")) {
  /* … */
}
req.jccSession?.forget("tempKey");
const snapshot = req.jccSession?.all();
const subset = req.jccSession?.only(["user_id", "locale"]);
const withoutSecrets = req.jccSession?.except(["_token"]);

Via session() (inside a request, after middleware)

session()?.put("theme", "dark");
const theme = session()?.get("theme", "light");

flush() on jccSession removes all keys except the session cookie metadata.

Persisting and rotating the session

• await req.jccSession?.save() — Calls req.session.save() when available so the store persists before you finish the response (useful before a redirect after login).
• await req.jccSession?.regenerate() — Calls req.session.regenerate() when available; use after authentication to reduce fixation risk.
• getId() — Current session id string when exposed by Express (sessionID on the request).

If req.session is undefined (middleware mis-ordered or disabled), jccSession will not be useful—ensure the session stack runs before your routes.

Flash messages

connect-flash adds req.flash. Typical usage:

req.flash("success", "Saved.");
req.flash("error", ["First error", "Second error"]);
const messages = req.flash("success"); // consumes that key for this response cycle
const all = req.flash(); // object of arrays, consumed

jccSession.flash / getFlash delegate to req.flash so they stay aligned with res.with().

In Blade, flash-backed res.locals for validation and old input are available on the next render; see Request and Response.

CSRF and session

The csrf() middleware stores the CSRF token in the session (see CSRF-protection.md). Session middleware must run before csrf() in the pipeline so req.session exists when the token is created.

Summary

• Sessions rely on express-session + connect-flash; req.jccSession is the typed bridge for get / put / flash / all / flush / save / regenerate.
• Use session() for the same API from globals during a request.
• Flash: req.flash or jccSession.flash / getFlash; res.with integrates with flash for UI messages.
• Configure secrets and cookies for production; call save() / regenerate() when your auth flow requires it.