Content Security Policy Builder

2.3.0 · maintenance · verified Tue Apr 21

The `content-security-policy-builder` package, currently at version 2.3.0, provides a focused utility for programmatically constructing Content Security Policy (CSP) strings from a JavaScript object or Map. It streamlines the process of defining CSP directives by supporting various input formats, including `camelCased` or `dash-separated` directive names, and accepting both strings and arrays for directive values. The module is explicitly designated as feature-complete, with the maintainer indicating that future development will be limited to maintenance. This means no new features or breaking changes are planned, making it a stable, though static, choice for generating CSP headers. Its key differentiator lies in its robust input parsing and its singular, complete focus on translating structured input into a valid CSP string.

Common errors

```
ReferenceError: require is not defined in ES module scope
```
cause Attempting to use `require()` to import the library in a modern Node.js project configured for ES Modules.

fix Change your import statement from `const builder = require('content-security-policy-builder');` to `import builder from 'content-security-policy-builder';`.
```
TypeError: content_security_policy_builder_1.builder is not a function
```
cause Attempting to use `import { builder } from 'content-security-policy-builder';` when the package exports a default function.

fix Change your import statement to `import builder from 'content-security-policy-builder';`.

Warnings

breaking The package explicitly requires Node.js version 18.0.0 or higher. Running in older Node.js environments will result in errors.
Fix: Upgrade your Node.js environment to version 18.0.0 or newer.
gotcha The module is considered 'feature-complete' by its maintainer. This means no new CSP directives or features are planned to be added, which could lead to an outdated CSP if new standards or directives emerge in the future.
Fix: Regularly review your generated CSP against the latest W3C Content Security Policy specification to ensure it remains effective and secure, manually updating directives as needed.
gotcha The builder constructs the CSP string based on the input provided but does not perform semantic validation of the directive values (e.g., ensuring URLs are valid, or that `'self'` is correctly quoted). Supplying syntactically incorrect or insecure values will still produce a string, but the resulting CSP may be ineffective or even introduce vulnerabilities.
Fix: Thoroughly test and review your generated CSP using browser developer tools and online CSP validators (e.g., CSP Evaluator) to ensure its correctness and effectiveness.

Install

npm install content-security-policy-builder npm
yarn add content-security-policy-builder yarn
pnpm add content-security-policy-builder pnpm

Imports

builder

wrong:

import { builder } from 'content-security-policy-builder';

correct:

import builder from 'content-security-policy-builder';

The library exports a default function. Attempting a named import will fail.

builder
wrong:
```
const builder = require('content-security-policy-builder');
```
correct:
```
import builder from 'content-security-policy-builder';
```
While CommonJS `require` might work in some environments, the package's primary export is ESM. Using `require` in an ESM-first project can lead to `ReferenceError` or unexpected behavior. Stick to `import`.
CSPDirectiveMap
wrong:
```
import { CSPDirectiveMap } from 'content-security-policy-builder';
```
correct:
```
import type { CSPDirectiveMap } from 'content-security-policy-builder';
```
Import types using `import type` to ensure they are stripped from the JavaScript output, preventing runtime errors.

Quickstart

This quickstart demonstrates how to use the `content-security-policy-builder` to construct CSP strings from both a plain JavaScript object and a Map, showcasing its flexibility with different directive naming conventions and value types.

import builder from "content-security-policy-builder";

// --- Example 1: Basic directives with different input styles ---
const policy1 = builder({
  directives: {
    defaultSrc: ["'self'", "default.com"],
    scriptSrc: "scripts.com",
    "style-src": ["'self'", "styles.com", "*.cdn.com"], // dash-separated
    imgSrc: ["'self'", "data:", "images.example.com"],
    fontSrc: ["'self'", "fonts.gstatic.com"],
    objectSrc: ["'none'"], // Explicitly disable object sources
    baseUri: ["'self'"]
  }
});
console.log("Policy 1:", policy1);
// Expected output: default-src 'self' default.com; script-src scripts.com; style-src 'self' styles.com *.cdn.com; img-src 'self' data: images.example.com; font-src 'self' fonts.gstatic.com; object-src 'none'; base-uri 'self'

// --- Example 2: Using a Map for directives (useful for dynamic scenarios) ---
const dynamicDirectives = new Map([
  ["defaultSrc", ["'self'"]],
  ["scriptSrc", ["'self'", "https://cdn.example.com"]],
  ["connectSrc", ["'self'", "wss://api.example.com"]],
  ["reportUri", "/csp-report-endpoint"]
]);
const policy2 = builder({ directives: dynamicDirectives });
console.log("Policy 2:", policy2);
// Expected output: default-src 'self'; script-src 'self' https://cdn.example.com; connect-src 'self' wss://api.example.com; report-uri /csp-report-endpoint

// This demonstrates building complex CSP strings with various directive types and sources,
// including handling both camelCase and dash-separated directive names, and array/string values.

view raw JSON →