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

Transport Security

Name: tessl/npm-helmet
Author: tessl

HTTPS enforcement and referrer policy configuration for secure communication and privacy protection.

Capabilities

Strict Transport Security (HSTS)

Enforces HTTPS connections by instructing browsers to only connect via HTTPS for a specified period.

/**
 * Sets Strict-Transport-Security header to enforce HTTPS
 * @param options - HSTS configuration options
 * @returns Express middleware function
 */
function strictTransportSecurity(
  options?: StrictTransportSecurityOptions
): MiddlewareFunction;

interface StrictTransportSecurityOptions {
  /** Duration in seconds for HSTS policy (default: 31536000 - 1 year) */
  maxAge?: number;
  /** Apply policy to all subdomains (default: true) */
  includeSubDomains?: boolean;
  /** Eligible for browser preload lists (default: false) */
  preload?: boolean;
}

Usage Examples:

import { strictTransportSecurity } from "helmet";

// Default: 1 year, include subdomains
app.use(strictTransportSecurity());

// Custom configuration
app.use(strictTransportSecurity({
  maxAge: 63072000, // 2 years
  includeSubDomains: true,
  preload: true
}));

// Short duration for testing
app.use(strictTransportSecurity({
  maxAge: 300, // 5 minutes
  includeSubDomains: false
}));

Configuration Details:

maxAge: Duration in seconds that browsers should remember to only access via HTTPS
- Minimum recommended: 1 year (31536000 seconds)
- For preload: minimum 1 year, recommended 2 years (63072000 seconds)
includeSubDomains: Whether to apply HSTS policy to all subdomains
- true: Protects subdomains but requires all to support HTTPS
- false: Only applies to the exact domain
preload: Whether the domain is eligible for browser preload lists
- Requires maxAge >= 31536000 and includeSubDomains: true
- Submit to https://hstspreload.org/ for inclusion in browser preload lists

Referrer Policy

Controls how much referrer information is sent with requests.

/**
 * Sets Referrer-Policy header to control referrer information
 * @param options - Referrer policy configuration options
 * @returns Express middleware function
 */
function referrerPolicy(
  options?: ReferrerPolicyOptions
): MiddlewareFunction;

interface ReferrerPolicyOptions {
  /** Policy or array of policies (default: ["no-referrer"]) */
  policy?: ReferrerPolicyToken | ReferrerPolicyToken[];
}

type ReferrerPolicyToken = 
  | "no-referrer"
  | "no-referrer-when-downgrade" 
  | "same-origin"
  | "origin"
  | "strict-origin"
  | "origin-when-cross-origin"
  | "strict-origin-when-cross-origin"
  | "unsafe-url"
  | "";

Usage Examples:

import { referrerPolicy } from "helmet";

// Default: no-referrer
app.use(referrerPolicy());

// Single policy
app.use(referrerPolicy({ 
  policy: "strict-origin-when-cross-origin" 
}));

// Multiple policies (fallback support)
app.use(referrerPolicy({ 
  policy: ["strict-origin-when-cross-origin", "origin-when-cross-origin"] 
}));

// No referrer for privacy
app.use(referrerPolicy({ 
  policy: "no-referrer" 
}));

Policy Values:

no-referrer: Never send referrer information
no-referrer-when-downgrade: Send referrer except when downgrading from HTTPS to HTTP
same-origin: Send referrer only for same-origin requests
origin: Send only origin (no path) as referrer
strict-origin: Send origin only, and not when downgrading from HTTPS to HTTP
origin-when-cross-origin: Send full URL for same-origin, origin only for cross-origin
strict-origin-when-cross-origin: Send full URL for same-origin, origin for cross-origin (not when downgrading)
unsafe-url: Always send full URL (not recommended)
"" (empty string): Same as no-referrer-when-downgrade

Security Considerations

HSTS Best Practices

Start with short maxAge: Test with 5-10 minutes initially
Gradually increase: Move to hours, then days, then months/years
Plan for HTTPS everywhere: HSTS applies to entire domain/subdomains
Consider preload carefully: Very hard to undo once submitted
Monitor certificate expiry: HSTS prevents fallback to HTTP

HSTS Deployment Strategy:

// Phase 1: Testing (short duration)
app.use(strictTransportSecurity({
  maxAge: 300, // 5 minutes
  includeSubDomains: false
}));

// Phase 2: Staging (medium duration) 
app.use(strictTransportSecurity({
  maxAge: 86400, // 1 day
  includeSubDomains: true
}));

// Phase 3: Production (long duration)
app.use(strictTransportSecurity({
  maxAge: 31536000, // 1 year
  includeSubDomains: true,
  preload: true
}));

Referrer Policy Privacy vs Functionality

High Privacy (least referrer info):

app.use(referrerPolicy({ policy: "no-referrer" }));

Balanced (good privacy, maintains some functionality):

app.use(referrerPolicy({ policy: "strict-origin-when-cross-origin" }));

Legacy Compatibility (moderate privacy):

app.use(referrerPolicy({ policy: "origin-when-cross-origin" }));

Common Use Cases

E-commerce/Banking (High Security)

app.use(strictTransportSecurity({
  maxAge: 63072000, // 2 years
  includeSubDomains: true,
  preload: true
}));

app.use(referrerPolicy({ 
  policy: "strict-origin-when-cross-origin" 
}));

Content Sites (Balanced)

app.use(strictTransportSecurity({
  maxAge: 31536000, // 1 year
  includeSubDomains: true
}));

app.use(referrerPolicy({ 
  policy: "origin-when-cross-origin" 
}));

Development/Testing (Flexible)

app.use(strictTransportSecurity({
  maxAge: 3600, // 1 hour
  includeSubDomains: false
}));

app.use(referrerPolicy({ 
  policy: "same-origin" 
}));

Error Scenarios

HSTS Warnings

Mixed content errors when not all resources are HTTPS
Certificate errors become unrecoverable during HSTS period
Subdomain issues when includeSubDomains is true but subdomains lack HTTPS

Referrer Policy Issues

Analytics tools may lose referrer data with strict policies
Third-party integrations may require specific referrer information
SEO tools may be affected by no-referrer policies

docs

content-security-policy.md

cross-origin-policies.md

index.md

legacy-security-headers.md

main-helmet-function.md

transport-security.md

tile.json

tessl/npm-helmet