tessl/npm-express-session

Simple session middleware for Express.js applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Session Configuration

Name: tessl/npm-express-session
Author: tessl

Comprehensive configuration options for the express-session middleware, including security settings, cookie options, and session behavior controls.

Capabilities

Session Middleware Factory

Creates Express middleware with the provided configuration options.

/**
 * Create a session middleware with the given options
 * @param options - Configuration object for session behavior
 * @returns Express middleware function
 */
function session(options: SessionOptions): (req: Request, res: Response, next: NextFunction) => void;

interface SessionOptions {
  /** Secret(s) for signing session ID cookie (required) */
  secret: string | string[];
  /** Cookie configuration options */
  cookie?: CookieOptions;
  /** Function to generate session IDs */
  genid?: (req: Request) => string;
  /** Session cookie name (default: 'connect.sid') */
  name?: string;
  /** Trust reverse proxy for secure cookies */
  proxy?: boolean;
  /** Force session save even if unmodified */
  resave?: boolean;
  /** Force cookie to be set on every response */
  rolling?: boolean;
  /** Save uninitialized sessions */
  saveUninitialized?: boolean;
  /** Session store instance */
  store?: Store;
  /** Behavior when unsetting session */
  unset?: 'destroy' | 'keep';
}

Usage Examples:

const express = require('express');
const session = require('express-session');

const app = express();

// Basic configuration
app.use(session({
  secret: 'keyboard cat',
  resave: false,
  saveUninitialized: true
}));

// Production configuration with custom store
const RedisStore = require('connect-redis')(session);
const redis = require('redis');
const client = redis.createClient();

app.use(session({
  store: new RedisStore({ client: client }),
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  rolling: true,
  cookie: {
    secure: true,
    httpOnly: true,
    maxAge: 1000 * 60 * 60 * 24 // 24 hours
  }
}));

Required Options

Secret Configuration

The secret is required for signing session ID cookies and can be a single string or array of strings.

interface SecretConfig {
  /** Single secret string or array of secrets for cookie signing */
  secret: string | string[];
}

Usage Examples:

// Single secret
session({
  secret: 'my-secret-key'
});

// Multiple secrets for rotation
session({
  secret: ['new-secret', 'old-secret']
});

// Environment variable
session({
  secret: process.env.SESSION_SECRET
});

Cookie Options

Comprehensive cookie configuration for security and behavior control.

interface CookieOptions {
  /** Cookie domain */
  domain?: string;
  /** Cookie expiration date */
  expires?: Date;
  /** HttpOnly flag (default: true) */
  httpOnly?: boolean;
  /** Max age in milliseconds */
  maxAge?: number;
  /** Partitioned attribute for CHIPS */
  partitioned?: boolean;
  /** Cookie path (default: '/') */
  path?: string;
  /** Cookie priority level */
  priority?: 'low' | 'medium' | 'high';
  /** SameSite policy */
  sameSite?: boolean | 'lax' | 'strict' | 'none';
  /** Secure flag or 'auto' for automatic detection */
  secure?: boolean | 'auto';
}

Usage Examples:

// Development configuration
session({
  secret: 'dev-secret',
  cookie: {
    secure: false,
    maxAge: 1000 * 60 * 30 // 30 minutes
  }
});

// Production HTTPS configuration
session({
  secret: process.env.SESSION_SECRET,
  cookie: {
    secure: true,
    httpOnly: true,
    sameSite: 'strict',
    maxAge: 1000 * 60 * 60 * 2 // 2 hours
  }
});

// Automatic secure detection
session({
  secret: 'secret',
  proxy: true,
  cookie: {
    secure: 'auto' // Automatically detect HTTPS
  }
});

Session Behavior Options

Control session lifecycle and persistence behavior.

interface SessionBehaviorOptions {
  /** Custom session ID generator function */
  genid?: (req: Request) => string;
  /** Session cookie name */
  name?: string;
  /** Trust reverse proxy for secure cookies */
  proxy?: boolean;
  /** Force session save even if unmodified */
  resave?: boolean;
  /** Force cookie to be set on every response */
  rolling?: boolean;
  /** Save uninitialized sessions */
  saveUninitialized?: boolean;
  /** Session store instance */
  store?: Store;
  /** Behavior when unsetting req.session */
  unset?: 'destroy' | 'keep';
}

Usage Examples:

// Custom session ID generation
session({
  secret: 'secret',
  genid: function(req) {
    return uuid.v4(); // Use UUID for session IDs
  }
});

// Rolling sessions that extend on activity
session({
  secret: 'secret',
  rolling: true,
  cookie: { maxAge: 1000 * 60 * 15 } // 15 minutes, reset on each request
});

// Login session configuration
session({
  secret: 'secret',
  resave: false,
  saveUninitialized: false, // Don't save empty sessions
  cookie: {
    secure: true,
    httpOnly: true
  }
});

// Custom session cookie name for multiple apps
session({
  secret: 'secret',
  name: 'myapp.sid',
  cookie: { path: '/myapp' }
});

Store Configuration

Session store setup for persistence beyond memory.

interface StoreConfiguration {
  /** Session store instance implementing the Store interface */
  store?: Store;
}

Usage Examples:

// Default MemoryStore (development only)
session({
  secret: 'secret'
  // Uses MemoryStore by default
});

// Redis store
const RedisStore = require('connect-redis')(session);
session({
  secret: 'secret',
  store: new RedisStore({
    host: 'localhost',
    port: 6379,
    ttl: 260
  })
});

// MongoDB store
const MongoStore = require('connect-mongo');
session({
  secret: 'secret',
  store: MongoStore.create({
    mongoUrl: 'mongodb://localhost/session-store'
  })
});

Security Considerations

Secret Management: Use environment variables for secrets, rotate regularly
HTTPS Only: Set secure: true for production HTTPS deployments
Cookie Security: Enable httpOnly, configure sameSite appropriately
Session Store: Use persistent store (Redis, MongoDB) for production
Proxy Configuration: Set proxy: true when behind reverse proxy
Session Expiration: Configure appropriate maxAge for security vs usability