csp-typed-directives

CSP Typed Directives

Provides type information for all CSP directives and related headers' directives; as well as a basic utility funtion that helps convert the typed properties to key/values of each header content's policy string.

Kept up to date with Mozilla's CSP documentation of available directives.

Installation

Install with npm:

$ npm install --save-dev csp-typed-directives
# Or shorthand
npm i -D csp-typed-directives

Basic Usage

Either pass your CSP directives in at instatiation, or after.

const { CspDirectives } = require('csp-typed-directives')
// or ESM
import { CspDirectives } from 'csp-typed-directives';

const cspD = new CspDirectives({
  'child-src': 'none',
})

cspD.CSP['connect-src'] = 'example.com'

cspD.CSP['navigate-to'] = ['example.com','example2.com']

csp.headers === {
  'Content-Security-Policy-Report-Only': '',
  'Content-Security-Policy':
    "child-src 'none'; connect-src 'example.com'; navigate-to 'example.com' 'example2.com'",
  'Report-To': '',
  'Referrer-Policy': 'strict-origin-when-cross-origin',
}

The default configuration produces a referrer policy of strict-origin-when-cross-origin because that is the default, and is well suited to be explicitly stated.

Advanced Usage

const { CspDirectives } = require('csp-typed-directives')
// or ESM
import { CspDirectives } from 'csp-typed-directives';

const reportTo: ReportTo[] = [
  {
    max_age: 12000,
    group: 'example-group-name',
    endpoints: [{url:'https://example.com'}],
  },
]

const whichToReport = {
    'connect-src':'example.com'
}

const referrerPolicy = 'strict-origin'

const cspD = new CspDirectives(
  {
    'child-src': 'none',
    'connect-src':'example.com',
    'report-to': 'example-group-name'
  },
  reportTo,
  whichToReport,
  referrerPolicy
)

csp.headers === {
  'Content-Security-Policy-Report-Only': "connect-src 'example.com';",
  'Content-Security-Policy':
    "child-src 'none'; connect-src 'example.com'; report-to 'example-group-name';",
  'Report-To': '[{"max_age":12000,"group":"example-group-name","endpoints":[{"url":"https://example.com"}]}]',
  'Referrer-Policy': 'strict-origin',
}

For reading up on the descriptions and implications of all directives see Mozilla's CSP documentation

Iterate over all available directives

This also provides a map of constants of every available directive name and the category(s) of souces/directives it can be assigned.

import { directiveNamesList } from 'csp-typed-directives';

const myDirectives = directiveNamesList
  .reduce((acc,v) => {
    // ! Warning: not all directives allow the full set of directive parameters
    // Though as of 5/6/2021 they all support the 'none' directive, though would be kind of pointless to do this.
    acc[v] = 'none'
  },{})

import { DirectiveMap } from 'csp-typed-directives';

let myDirectives = DirectiveMap.get('report-to')
myDirectives === [
  {
    displayName: 'Any String',
    consumes: {
      'String': 'string',
    },
    compose: (args: {String:string}) => args.String,
  },
]

myDirectives = DirectiveMap.get('require-sri-for')
myDirectives === [
  'script', 'style', 'script style'
]

myDirectives = DirectiveMap.get('upgrade-insecure-requests')
myDirectives === [
  true, false,
]

Changelog

Take a look at the CHANGELOG.md.

Contribution

You're free to contribute to this project by submitting issues and/or pull requests.

Please keep in mind that every change and feature should be covered by tests.

License

This project is licensed under MIT.

Contributors