tessl/npm-helmet

Comprehensive Express.js security middleware library that automatically sets multiple HTTP response headers to protect web applications against common security vulnerabilities.

—

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

Main Helmet Function

Name: tessl/npm-helmet
Author: tessl

The primary Helmet function that combines all security middlewares into a single Express middleware with configurable options.

Capabilities

Helmet Function

Creates a middleware function that applies all configured security headers to HTTP responses.

/**
 * Creates an Express middleware that applies security headers
 * @param options - Configuration for individual security middlewares
 * @returns Express middleware function
 * @throws Error if conflicting options are provided
 */
function helmet(options?: Readonly<HelmetOptions>): (
  req: IncomingMessage,
  res: ServerResponse,
  next: (err?: unknown) => void
) => void;

type HelmetOptions = {
  contentSecurityPolicy?: ContentSecurityPolicyOptions | boolean;
  crossOriginEmbedderPolicy?: CrossOriginEmbedderPolicyOptions | boolean;
  crossOriginOpenerPolicy?: CrossOriginOpenerPolicyOptions | boolean;
  crossOriginResourcePolicy?: CrossOriginResourcePolicyOptions | boolean;
  originAgentCluster?: boolean;
  referrerPolicy?: ReferrerPolicyOptions | boolean;
} & (
  | {
      strictTransportSecurity?: StrictTransportSecurityOptions | boolean;
      hsts?: never;
    }
  | {
      hsts?: StrictTransportSecurityOptions | boolean;
      strictTransportSecurity?: never;
    }
) &
  (
    | { xContentTypeOptions?: boolean; noSniff?: never }
    | { noSniff?: boolean; xContentTypeOptions?: never }
  ) &
  (
    | {
        xDnsPrefetchControl?: XDnsPrefetchControlOptions | boolean;
        dnsPrefetchControl?: never;
      }
    | {
        dnsPrefetchControl?: XDnsPrefetchControlOptions | boolean;
        xDnsPrefetchControl?: never;
      }
  ) &
  (
    | { xDownloadOptions?: boolean; ieNoOpen?: never }
    | { ieNoOpen?: boolean; xDownloadOptions?: never }
  ) &
  (
    | { xFrameOptions?: XFrameOptionsOptions | boolean; frameguard?: never }
    | { frameguard?: XFrameOptionsOptions | boolean; xFrameOptions?: never }
  ) &
  (
    | {
        xPermittedCrossDomainPolicies?: XPermittedCrossDomainPoliciesOptions | boolean;
        permittedCrossDomainPolicies?: never;
      }
    | {
        permittedCrossDomainPolicies?: XPermittedCrossDomainPoliciesOptions | boolean;
        xPermittedCrossDomainPolicies?: never;
      }
  ) &
  (
    | { xPoweredBy?: boolean; hidePoweredBy?: never }
    | { hidePoweredBy?: boolean; xPoweredBy?: never }
  ) &
  (
    | { xXssProtection?: boolean; xssFilter?: never }
    | { xssFilter?: boolean; xXssProtection?: never }
  );

Usage Examples:

import express from "express";
import helmet from "helmet";

const app = express();

// Use all default security headers
app.use(helmet());

// Disable specific middleware
app.use(helmet({
  crossOriginEmbedderPolicy: false,
  contentSecurityPolicy: false
}));

// Configure specific middleware
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'", "https://cdn.example.com"]
    }
  },
  strictTransportSecurity: {
    maxAge: 31536000,
    includeSubDomains: true,
    preload: true
  }
}));

// Use legacy aliases
app.use(helmet({
  hsts: { maxAge: 31536000 },
  frameguard: { action: "deny" },
  noSniff: true
}));

Default Behavior

When called without options (helmet()), the following middleware are enabled with their default settings:

contentSecurityPolicy: Enabled with default directives
crossOriginOpenerPolicy: Enabled with "same-origin" policy
crossOriginResourcePolicy: Enabled with "same-origin" policy
originAgentCluster: Enabled
referrerPolicy: Enabled with "no-referrer" policy
strictTransportSecurity: Enabled with 1-year max-age and includeSubDomains
xContentTypeOptions: Enabled (sets "nosniff")
xDnsPrefetchControl: Enabled (sets "off")
xDownloadOptions: Enabled (sets "noopen")
xFrameOptions: Enabled with "sameorigin" action
xPermittedCrossDomainPolicies: Enabled with "none" policy
xPoweredBy: Enabled (removes header)
xXssProtection: Enabled (sets "0")

Disabled by default:

crossOriginEmbedderPolicy: Disabled (can break site functionality)

Configuration Options

Each middleware can be configured using one of three approaches:

Boolean true: Enable with default settings
Boolean false: Disable the middleware
Options object: Enable with custom configuration

app.use(helmet({
  // Enable with defaults
  originAgentCluster: true,
  
  // Disable completely
  crossOriginEmbedderPolicy: false,
  
  // Configure with options
  xFrameOptions: { action: "deny" },
  strictTransportSecurity: {
    maxAge: 63072000, // 2 years
    includeSubDomains: true,
    preload: true
  }
}));

Legacy Aliases

Helmet supports legacy aliases for backward compatibility. These cannot be used simultaneously with their modern equivalents:

hsts ↔ strictTransportSecurity
noSniff ↔ xContentTypeOptions
dnsPrefetchControl ↔ xDnsPrefetchControl
ieNoOpen ↔ xDownloadOptions
frameguard ↔ xFrameOptions
permittedCrossDomainPolicies ↔ xPermittedCrossDomainPolicies
hidePoweredBy ↔ xPoweredBy
xssFilter ↔ xXssProtection

Error Handling

The helmet function throws errors in the following cases:

Conflicting options: Using both modern and legacy names for the same middleware
Invalid middleware call: Passing the helmet function directly instead of calling it (common mistake: app.use(helmet) instead of app.use(helmet()))

// These will throw errors:
helmet({
  strictTransportSecurity: { maxAge: 31536000 },
  hsts: { maxAge: 63072000 } // Error: option specified twice
});

app.use(helmet); // Error: should be helmet()