or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-koa-helmet

Security header middleware collection for Koa applications that wraps Helmet.js

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/koa-helmet@8.0.x

To install, run

npx @tessl/cli install tessl/npm-koa-helmet@8.0.0

index.mddocs/

Koa Helmet

Koa Helmet is a wrapper for Helmet.js that provides security header middleware collection for Koa applications. It converts Helmet's Express-style middleware into Koa-compatible middleware, applying essential security headers to protect web applications from common vulnerabilities.

Package Information

  • Package Name: koa-helmet
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install koa-helmet helmet
  • Peer Dependencies: helmet >= 6

Core Imports

import helmet from "koa-helmet";

For CommonJS:

const helmet = require("koa-helmet");

Basic Usage

import Koa from "koa";
import helmet from "koa-helmet";

const app = new Koa();

// Apply all security headers (recommended)
app.use(helmet());

// Or use individual middleware
app.use(helmet.contentSecurityPolicy());
app.use(helmet.hsts());
app.use(helmet.frameguard());

app.use((ctx) => {
  ctx.body = "Hello World";
});

app.listen(4000);

Architecture

Koa Helmet works by dynamically wrapping all Helmet.js middleware methods:

  • Dynamic Wrapping: Automatically detects and wraps all Helmet middleware using Object.keys(helmet)
  • Promise-based Conversion: Uses Node.js promisify to convert Express-style middleware to Koa's promise-based pattern
  • Context Bridging: Maps Koa's ctx.req and ctx.res to work with Helmet's Express-style middleware
  • Method Preservation: Maintains all static properties and methods from the original Helmet middleware

Capabilities

Main Security Middleware

The primary function that applies all recommended security headers.

/**
 * Apply all Helmet security headers with default settings
 * @param options - Optional Helmet configuration options
 * @returns Koa middleware function
 */
function helmet(options?: HelmetOptions): Middleware;

Usage Example:

import helmet from "koa-helmet";

// Apply all security headers with defaults
app.use(helmet());

// Apply with custom options
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"]
    }
  }
}));

Content Security Policy

Sets Content-Security-Policy headers to mitigate XSS attacks and control resource loading.

/**
 * Configure Content Security Policy headers
 * @param options - CSP configuration options
 * @returns Koa middleware function
 */
function contentSecurityPolicy(options?: CSPOptions): Middleware;

// Static methods available on contentSecurityPolicy
contentSecurityPolicy.getDefaultDirectives(): CSPDirectives;
contentSecurityPolicy.dangerouslyDisableDefaultSrc(directives: CSPDirectives): CSPDirectives;

Usage Example:

app.use(helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    scriptSrc: ["'self'", "'unsafe-inline'"],
    styleSrc: ["'self'", "'unsafe-inline'"],
    imgSrc: ["'self'", "data:", "https:"]
  }
}));

Cross-Origin Policies

Controls cross-origin resource access and embedding policies.

/**
 * Set Cross-Origin-Embedder-Policy header
 * @param options - COEP configuration options
 * @returns Koa middleware function
 */
function crossOriginEmbedderPolicy(options?: COEPOptions): Middleware;

/**
 * Set Cross-Origin-Opener-Policy header
 * @param options - COOP configuration options
 * @returns Koa middleware function
 */
function crossOriginOpenerPolicy(options?: COOPOptions): Middleware;

/**
 * Set Cross-Origin-Resource-Policy header
 * @param options - CORP configuration options
 * @returns Koa middleware function
 */
function crossOriginResourcePolicy(options?: CORPOptions): Middleware;

DNS and Prefetch Control

Controls DNS prefetching behavior for performance and privacy.

/**
 * Control DNS prefetching via X-DNS-Prefetch-Control header
 * @param options - DNS prefetch configuration
 * @returns Koa middleware function
 */
function dnsPrefetchControl(options?: { allow?: boolean }): Middleware;

Usage Example:

// Disable DNS prefetching (default)
app.use(helmet.dnsPrefetchControl());

// Enable DNS prefetching
app.use(helmet.dnsPrefetchControl({ allow: true }));

Frame Protection

Prevents clickjacking attacks by controlling frame embedding.

/**
 * Set X-Frame-Options header to prevent clickjacking
 * @param options - Frame guard configuration
 * @returns Koa middleware function
 */
function frameguard(options?: FrameguardOptions): Middleware;

Usage Example:

// Default: SAMEORIGIN
app.use(helmet.frameguard());

// Deny all framing
app.use(helmet.frameguard({ action: "deny" }));

// Allow from specific origin
app.use(helmet.frameguard({ 
  action: "allow-from",
  domain: "https://example.com"
}));

Server Identity Protection

Removes server technology information from responses.

/**
 * Remove X-Powered-By header to hide server technology
 * @returns Koa middleware function
 */
function hidePoweredBy(): Middleware;

HTTPS Enforcement

Enforces secure HTTPS connections via Strict Transport Security.

/**
 * Set Strict-Transport-Security header to enforce HTTPS
 * @param options - HSTS configuration options
 * @returns Koa middleware function
 */
function hsts(options?: HSTSOptions): Middleware;

Usage Example:

// Default: max-age=15552000; includeSubDomains
app.use(helmet.hsts());

// Custom configuration
app.use(helmet.hsts({
  maxAge: 31536000, // 1 year in seconds
  includeSubDomains: true,
  preload: true
}));

IE Security Features

Configures Internet Explorer-specific security features.

/**
 * Set X-Download-Options header to prevent IE from executing downloads
 * @returns Koa middleware function
 */
function ieNoOpen(): Middleware;

MIME Type Protection

Prevents MIME type sniffing attacks.

/**
 * Set X-Content-Type-Options header to prevent MIME type sniffing
 * @returns Koa middleware function
 */
function noSniff(): Middleware;

Origin Agent Cluster

Provides origin-based process isolation for better security.

/**
 * Set Origin-Agent-Cluster header for process isolation
 * @returns Koa middleware function
 */
function originAgentCluster(): Middleware;

Cross-Domain Policies

Controls Adobe Flash and Silverlight cross-domain access policies.

/**
 * Set X-Permitted-Cross-Domain-Policies header
 * @param options - Cross-domain policy configuration
 * @returns Koa middleware function
 */
function permittedCrossDomainPolicies(options?: PermittedPoliciesOptions): Middleware;

Referrer Policy

Controls referrer information sent with requests.

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

Usage Example:

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

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

XSS Protection

Controls legacy XSS protection features (mostly deprecated).

/**
 * Set X-XSS-Protection header (legacy, mostly disabled by default)
 * @param options - XSS filter configuration
 * @returns Koa middleware function
 */
function xssFilter(options?: XSSFilterOptions): Middleware;

Method Aliases

Koa Helmet provides several method aliases for compatibility:

// HSTS aliases
function strictTransportSecurity(options?: HSTSOptions): Middleware;

// Content type aliases  
function xContentTypeOptions(): Middleware;

// DNS prefetch aliases
function xDnsPrefetchControl(options?: { allow?: boolean }): Middleware;

// Download options aliases
function xDownloadOptions(): Middleware;

// Frame options aliases
function xFrameOptions(options?: FrameguardOptions): Middleware;

// Cross-domain policies aliases
function xPermittedCrossDomainPolicies(options?: PermittedPoliciesOptions): Middleware;

// Powered-by aliases
function xPoweredBy(): Middleware;

// XSS protection aliases
function xXssProtection(options?: XSSFilterOptions): Middleware;

Types

import { Middleware } from "koa";
import { HelmetOptions } from "helmet";

interface KoaHelmet {
  // Main function
  (options?: HelmetOptions): Middleware;
  
  // Individual middleware methods
  contentSecurityPolicy(options?: CSPOptions): Middleware;
  crossOriginEmbedderPolicy(options?: COEPOptions): Middleware;
  crossOriginOpenerPolicy(options?: COOPOptions): Middleware;
  crossOriginResourcePolicy(options?: CORPOptions): Middleware;
  dnsPrefetchControl(options?: { allow?: boolean }): Middleware;
  frameguard(options?: FrameguardOptions): Middleware;
  hidePoweredBy(): Middleware;
  hsts(options?: HSTSOptions): Middleware;
  ieNoOpen(): Middleware;
  noSniff(): Middleware;
  originAgentCluster(): Middleware;
  permittedCrossDomainPolicies(options?: PermittedPoliciesOptions): Middleware;
  referrerPolicy(options?: ReferrerPolicyOptions): Middleware;
  xssFilter(options?: XSSFilterOptions): Middleware;
  
  // Method aliases (x-prefixed variants)
  strictTransportSecurity(options?: HSTSOptions): Middleware;
  xContentTypeOptions(): Middleware;
  xDnsPrefetchControl(options?: { allow?: boolean }): Middleware;
  xDownloadOptions(): Middleware;
  xFrameOptions(options?: FrameguardOptions): Middleware;
  xPermittedCrossDomainPolicies(options?: PermittedPoliciesOptions): Middleware;
  xPoweredBy(): Middleware;
  xXssProtection(options?: XSSFilterOptions): Middleware;
}

interface FrameguardOptions {
  action?: "deny" | "sameorigin" | "allow-from";
  domain?: string;
}

interface HSTSOptions {
  maxAge?: number;
  includeSubDomains?: boolean;
  preload?: boolean;
}

interface ReferrerPolicyOptions {
  policy?: "no-referrer" | "no-referrer-when-downgrade" | "origin" | 
           "origin-when-cross-origin" | "same-origin" | "strict-origin" | 
           "strict-origin-when-cross-origin" | "unsafe-url";
}

interface CSPDirectives {
  [directive: string]: string | string[];
}

interface CSPOptions {
  directives?: CSPDirectives;
  reportOnly?: boolean;
  useDefaults?: boolean;
}

interface COEPOptions {
  policy?: "require-corp" | "credentialless";
}

interface COOPOptions {
  policy?: "same-origin" | "same-origin-allow-popups" | "unsafe-none";
}

interface CORPOptions {
  policy?: "same-origin" | "same-site" | "cross-origin";
}

interface PermittedPoliciesOptions {
  permittedPolicies?: "none" | "master-only" | "by-content-type" | "by-ftp-filename" | "all";
}

interface XSSFilterOptions {
  mode?: "block" | null;
}

Security Headers Produced

When using helmet() with default settings, the following headers are set:

  • Content-Security-Policy: default-src 'self';base-uri 'self';font-src 'self' https: data:;form-action 'self';frame-ancestors 'self';img-src 'self' data:;object-src 'none';script-src 'self';script-src-attr 'none';style-src 'self' https: 'unsafe-inline';upgrade-insecure-requests
  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Resource-Policy: same-origin
  • X-DNS-Prefetch-Control: off
  • X-Frame-Options: SAMEORIGIN
  • Strict-Transport-Security: max-age=15552000; includeSubDomains
  • X-Download-Options: noopen
  • X-Content-Type-Options: nosniff
  • Referrer-Policy: no-referrer
  • X-Permitted-Cross-Domain-Policies: none
  • X-XSS-Protection: 0

Error Handling

Koa Helmet preserves Helmet's error handling behavior:

  • Configuration Errors: Invalid options throw errors during middleware setup
  • Runtime Errors: Middleware errors are passed through Koa's error handling system
  • Promise Handling: All middleware is properly promisified for Koa's async pattern
// Error handling example
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    console.error('Helmet middleware error:', err);
    ctx.status = 500;
    ctx.body = 'Internal Server Error';
  }
});

app.use(helmet());