Registry / auth-security / content-security-policy-builder

content-security-policy-builder

library2.3.0jsnpmunverified

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.

auth-security http-networking

npm install content-security-policy-builder

github ↗package ↗

INSTALL

IMPORT

SIG · CONTENT-SECURITY-P

content-security-policy-builder

auth-securityjavascriptv2.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

builder

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

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

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

builder

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

✗ const builder = require('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

✓ import type { CSPDirectiveMap } from 'content-security-policy-builder';

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

Import types using `import type` to ensure they are stripped from the JavaScript output, preventing runtime errors.

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.

Debug

Known issues

breakingThe 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.

affects: <18.0.0

gotchaThe 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.

affects: >=2.0.0

gotchaThe 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.

affects: >=2.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

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

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';`.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/helmetjs/content-security-policy-builder ↗

packagehttps://www.npmjs.com/package/content-security-policy-builder ↗