Add Session Middleware

To manage the user's authenticated state, you'll need to add Wristband's session middleware to your application. This middleware attaches a req.session object to each incoming request, which stores information about the authenticated user. The session data is securely stored in an encrypted cookie, and on subsequent requests, the middleware automatically decrypts the cookie and restores the session state.

Configure Session Middleware

To enable session management, register a session configuration factory in your Wristband configuration file. You'll need to provide a secret (at least 32 characters long) for the secrets value. You can generate a secure secret using 1Password's password generator .

⚙️
Disabling Secure Session Cookies in Local Development
By default, session cookies are marked as secure, meaning they are only sent over HTTPS connections. Most browsers make an exception for localhost and allow secure cookies to be sent over HTTP (e.g., http://localhost). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even for localhost.
If you need to disable the secure flag for local development, set secure: false in your session options. However, be sure to restore secure: true in production to protect session data.

// src/config/wristband.config.ts

import { registerAs } from '@nestjs/config';
import type { AuthConfig, SessionOptions } from '@wristband/nestjs-auth';

export const authConfig = registerAs('wristbandAuth', (): AuthConfig => ({
  clientId: '<WRISTBAND_CLIENT_ID>',
  clientSecret: '<WRISTBAND_CLIENT_SECRET>',
  wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
}));

// ADD: Session options to use in both Session Middleware and Auth Guards.
const sessionOptions: SessionOptions = {
  secrets: '<your-generated-secret>',
};

// ADD: Session configuration for the session middleware.
export const sessionConfig = registerAs(
  'wristbandSession',
  (): SessionOptions => sessionOptions,
);

// src/config/wristband.config.ts

import { registerAs } from '@nestjs/config';
import type { AuthConfig, SessionOptions } from '@wristband/nestjs-auth';

export const authConfig = registerAs('wristbandAuth', (): AuthConfig => ({
  clientId: '<WRISTBAND_CLIENT_ID>',
  clientSecret: '<WRISTBAND_CLIENT_SECRET>',
  wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
  dangerouslyDisableSecureCookies: true,
}));

// ADD: Session options to use in both Session Middleware and Auth Guards.
const sessionOptions: SessionOptions = {
  secrets: '<your-generated-secret>',
  secure: false,
};

// ADD: Session configuration for the session middleware.
export const sessionConfig = registerAs(
  'wristbandSession',
  (): SessionOptions => sessionOptions,
);

Register The Session Module and Middleware

Next, do the following:

Import the WristbandExpressSessionModule and add it to your AppModule imports. Configure it with forRootAsync() using NestJS's async provider pattern.
Import the WristbandExpressSessionMiddleware and apply it globally to all routes using NestJS's middleware consumer.

ℹ️
NestJS Version 10.x Note
If you're using NestJS 10.x, use .forRoutes('*') instead of .forRoutes('{*splat}') for the middleware consumer.

// src/app.module.ts

import { ConfigModule, ConfigService } from '@nestjs/config';
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { env } from 'node:process';
import { WristbandExpressAuthModule } from '@wristband/nestjs-auth';
import {
  WristbandExpressSessionMiddleware,
  WristbandExpressSessionModule
} from '@wristband/nestjs-auth/session';

// Import the session configuration.
import { authConfig, sessionConfig } from './config/wristband.config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [authConfig, sessionConfig], // <-- Register the session configuration.
      envFilePath: env.NODE_ENV === 'production' ? '' : '.env',
      ignoreEnvFile: env.NODE_ENV === 'production',
    }),
    WristbandExpressAuthModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => configService.get('wristbandAuth'),
      inject: [ConfigService],
    }),

    // Inject the Wristband configurations for Session Middleware.
    WristbandExpressSessionModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => configService.get('wristbandSession'),
      inject: [ConfigService],
    }),

    // ...any project-specific modules...
  ],
})

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    // ADD: Configure the middleware for your app on all routes.
    consumer.apply(WristbandExpressSessionMiddleware).forRoutes('{*splat}');
  }
}