express-openid-connect

The testing strategy is divided into three main tiers:

1. Unit Tests: Uses Mocha, Chai (assert), Sinon, and nock. These are located in test/ with the *.tests.js naming convention. They run against a fixture server and require all outbound network calls to be stubbed via nock.
2. Type Tests: Uses tsd to validate index.d.ts against index.test-d.ts. Run these using npm run test:types.
3. End-to-end (E2E) Tests: Uses Mocha and Puppeteer to drive runnable apps from the examples/ directory. These tests run against a local oidc-provider (not a live Auth0 tenant) and are located in end-to-end/ with the *.test.js naming convention. These tests are slower and launch a headless browser.

If a logged-in user is suddenly redirected to login and req.appSession is null, the session may have expired due to the upstream Identity Provider's (IdP) session_expiry claim (IPSIE SL1).

The SDK treats this claim as a hard ceiling on the local session lifetime. Once reached, the session is cleared on the next request.

How to verify: Check if req.appSession.sessionExpiresAt was set during login. Compare that value against the current time to see if the ceiling was reached.

When contributing to or extending the library, follow these conventions:

• Module System: Use CommonJS exclusively (const x = require('...') and module.exports = { ... }). Do not use ESM import or export statements.
• File Naming: Use camelCase for filenames, matching the primary export (e.g., appSession.js).
• Variable/Function Naming: Use camelCase for functions and variables.
• Class/Error Naming: Use PascalCase for classes and error types (e.g., SessionExpiredError).
• Middleware Pattern: Middleware factories should be functions that return a standard Express (req, res, next) handler.

The project follows specific patterns for configuration and error management:

• Config-schema-as-contract: All public options are managed via a joi schema (located in lib/config.js). When adding new options, define them in the schema with a validation rule and a secure default. Avoid reading raw configuration values directly from process.env or other sources elsewhere in the code.
• Typed Errors: Instead of throwing bare Error objects, use the project's specific error types (e.g., SessionExpiredError from lib/errors.js) or http-errors for generating HTTP responses. Project error types typically include code and status properties.
• Outbound HTTP: Outbound OIDC HTTP requests are handled via createCustomFetch (lib/client.js), which manages User-Agent and Auth0-Client headers (telemetry can be opted out via enableTelemetry: false).

To allow anonymous access to some routes while protecting others, set authRequired: false in the auth() configuration. Use the requiresAuth() middleware on specific routes to enforce authentication.

const { auth, requiresAuth } = require('express-openid-connect');

app.use(
  auth({
    authRequired: false,
  }),
);

// Anyone can access the homepage
app.get('/', (req, res) => {
  res.send('<a href="/admin">Admin Section</a>');
});

// requiresAuth checks authentication.
app.get('/admin', requiresAuth(), (req, res) =>
  res.send(`Hello ${req.oidc.user.sub}, this is the admin section.`),
);