or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

content-security-policy.mdcross-origin-policies.mdindex.mdlegacy-security-headers.mdmain-helmet-function.mdtransport-security.md
tile.json

main-helmet-function.mddocs/

Main Helmet Function

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:

  1. Boolean true: Enable with default settings
  2. Boolean false: Disable the middleware
  3. 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()