Skip to content

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.

License

Notifications You must be signed in to change notification settings

josh-hemphill/csp-typed-directives

Repository files navigation

CSP Typed Directives

version NPM Codecov Libraries.io dependency status for latest release Rate on Openbase Test Build Release

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

About

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.

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Contributors 4

  •  
  •  
  •  
  •