Skip to content

feat(examples): add stateful (server-side) sessions example - #16

Merged
frederikprijck merged 9 commits into
mainfrom
example/stateful-sessions
Jul 10, 2026
Merged

frederikprijck merged 9 commits into
mainfrom
example/stateful-sessions

Conversation

@frederikprijck

Copy link
Copy Markdown
Member

Summary

Adds a new self-contained example, example-express-stateful-sessions, demonstrating how to use a custom server-side session store with @auth0/auth0-express.

By default the SDK is stateless — the whole session is encrypted into the cookie. Passing a sessionStore to createAuth0 switches to a stateful session: the session data (authenticated user + tokens) is persisted server-side and the cookie only carries an encrypted reference to it.

  • src/session-store.tsInMemorySessionStore implements SessionStore<StoreOptions> (a Map), implementing get / set / delete / deleteByLogoutToken. Comments call out that it's illustrative and would be Redis/DB in production.
  • src/index.ts — wires the store via createAuth0({ sessionStore }) and protects /private with the SDK's requiresAuth().

Tests

Follows the existing example-express-mcd pattern (MSW + supertest):

  • src/session-store.spec.ts — unit-tests the store directly: set/get round-trip, delete, and deleteByLogoutToken matching on sub and sid (plus a non-match leaves sessions intact).
  • src/index.spec.ts — mocks Auth0 discovery, JWKS, and the token endpoint (signing a real RS256 ID token with jose), drives a full mocked login (/auth/login/auth/callback), and asserts:
    • the store grows by exactly one entry and that entry holds the real session data (user.sub), proving the session lives server-side;
    • a session cookie is still set (an encrypted reference, not the session itself);
    • the persisted session grants access to /private.

CI

Adds a Stateful Sessions job to .github/workflows/examples.yml running build + test:ci, mirroring the other per-example jobs.

Verification

npm run build -w @auth0/auth0-express && npm run build -w example-express-stateful-sessions && npm run test:ci -w example-express-stateful-sessions — build clean, 8/8 tests passing.

Comment thread examples/example-express-stateful-sessions/package.json Outdated
Comment thread examples/example-express-stateful-sessions/tsconfig.json Outdated
Comment thread examples/example-express-stateful-sessions/src/session-store.ts
Comment thread examples/example-express-stateful-sessions/views/layout.ejs Outdated
…e in layout

- drop unused ts-node dep + dead tsconfig block (tsx/tsc/vitest are used)
- use <%= over <%- so the user name is HTML-escaped in the layout
Standalone app example — remove declaration/declarationMap (no library
consumers), DOM libs (server-side, no DOM usage), and resolveJsonModule
(no JSON imports).
…ions

# Conflicts:
#	.github/workflows/examples.yml
#	README.md
@frederikprijck
frederikprijck merged commit ec1ed45 into main Jul 10, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants