@jackdbd/content-security-policy

content-security-policy

Write your Content-Security-Policy header in JavaScript, so you can have validation and automatic hashes.

• About
• Installation
• Usage
• Configuration
• Docs
• Dependencies
• Troubleshooting
• Alternatives
• License

About

A strict Content-Security-Policy is probably the single most important line of defense against Cross-Site Scripting (XSS) and data injection attacks.

However, writing a good CSP header by hand is a pain. Here is why:

• You might write an invalid CSP directive (e.g. typos, incorrect values).
• You might write a CSP directive which is supported in one browser, but not in another one.
• You might want to allow some inline CSS/JS in your HTML page, but you neither:
  • want to compromise security by using unsafe-inline, nor...
  • want to compute the cryptographic hash of each snippet of CSS/JS that you inlined and whitelisting them by hand.

Also, you should:

• keep your CSP quite visible in your codebase, since it's such an important configuration for your website/app.
• generate your CSP in multiple format (JSON, JS array, plain text), so other tools can easily consume it.

This package validates your Content-Security-Policy directives and computes a cryptographic hash (SHA-256, SHA-384 or SHA-512) for each snippet of CSS/JS that you inline in your HTML file.

🛈 Note:

If your website is built with Eleventy, have a look at @jackdbd/eleventy-plugin-content-security-policy, which also takes care of writing the Content-Security-Policy header in a _headers file (useful if you website/app is hosted on Netlify or Cloudflare Pages).

Installation

npm install @jackdbd/content-security-policy

Usage

Write something like this in your build script:

import path from 'node:path'
// pick the format you prefer: object, header (single string), directives (N strings)
import {
  cspJSON,
  cspHeader,
  cspDirectives
} from '@jackdbd/content-security-policy'

// the Content-Security-Policy header is made of directives.
// If you don't know where to start, use one of the following policies:
import {
  starter_policy,
  recommended_policy
} from '@jackdbd/content-security-policy/policies'

const directives = recommended_policy

const patterns = [
  // e.g. for a Eleventy website
  path.join('_site', '**/*.html')
]

const obj = await cspJSON({ directives, patterns })
console.log(`Content-Security-Policy (as Object)`)
console.log(obj)

const header = await cspHeader({ directives, patterns })
console.log(`Content-Security-Policy (as header)`)
console.log(header)

const strings = await cspDirectives({ directives, patterns })
console.log(`Content-Security-Policy (as strings)`)
console.log(strings)

Configuration

The cspJSON, cspHeader and cspDirectives functions require an object that contains directives and patterns.

Parameter	Explanation
directives	Directives for the Content-Security-Policy (or Content-Security-Policy-Report-Only) header.
patterns	glob patterns for your .html files.

Docs

Docs generated by TypeDoc

📖 API Docs

This project uses API Extractor and api-documenter markdown to generate a bunch of markdown files and a .d.ts rollup file containing all type definitions consolidated into a single file. I don't find this .d.ts rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.

See Generating API docs if you want to know more.

Dependencies

Package	Version
debug	^4.3.4
globby	^14.0.0
himalaya	^1.1.0
zod	^3.22.4

This project is tested on Node.js >=14.21.3.

You can use a Node.js version manager like nvm, asdf or volta to manage your Node.js versions.

Troubleshooting

This project uses the debug library for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

# print all logging statements
export DEBUG=csp:*

Alternatives

• netlify-plugin-csp-generator. It uses jsdom to find all inlined CSS/JS snippets in your website, it computes a SHA-256 for each one of them, then it appends the CSP to your _headers file. Really cool, but you have to host you site on Netlify to use it.
• seespee. It uses AssetGraph to build a dependency graph of your website, then it computes hashes for the assets included in such graph.

License

© 2022 - 2024 Giacomo Debidda // MIT License