From fdbc4dc0b7a473066e402fdf773d6e6cdb4f4556 Mon Sep 17 00:00:00 2001 From: Giacomo Debidda Date: Tue, 4 Oct 2022 17:33:04 +0200 Subject: [PATCH] docs(content-security-policy): improve README and rebuild docs --- .../assets/highlight.css | 49 ++++++ .../functions/cspDirectives.html | 2 +- .../functions/cspHeader.html | 2 +- .../functions/cspJSON.html | 2 +- .../functions/validationErrorOrWarnings.html | 2 +- docs/content-security-policy/index.html | 51 +++++- .../interfaces/Config.html | 6 +- .../interfaces/Directives.html | 2 +- .../ValidationErrorOrWarningsConfig.html | 6 +- .../variables/recommended_policy.html | 2 +- .../variables/starter_policy.html | 2 +- package.json | 1 + packages/content-security-policy/README.md | 64 +++++++- .../src/demo/content-security-policy.ts | 145 +++++++++++++----- 14 files changed, 281 insertions(+), 55 deletions(-) diff --git a/docs/content-security-policy/assets/highlight.css b/docs/content-security-policy/assets/highlight.css index 1b78686f..a799c3f1 100644 --- a/docs/content-security-policy/assets/highlight.css +++ b/docs/content-security-policy/assets/highlight.css @@ -1,29 +1,78 @@ :root { --light-hl-0: #000000; --dark-hl-0: #D4D4D4; + --light-hl-1: #AF00DB; + --dark-hl-1: #C586C0; + --light-hl-2: #001080; + --dark-hl-2: #9CDCFE; + --light-hl-3: #A31515; + --dark-hl-3: #CE9178; + --light-hl-4: #008000; + --dark-hl-4: #6A9955; + --light-hl-5: #0000FF; + --dark-hl-5: #569CD6; + --light-hl-6: #0070C1; + --dark-hl-6: #4FC1FF; + --light-hl-7: #795E26; + --dark-hl-7: #DCDCAA; --light-code-background: #FFFFFF; --dark-code-background: #1E1E1E; } @media (prefers-color-scheme: light) { :root { --hl-0: var(--light-hl-0); + --hl-1: var(--light-hl-1); + --hl-2: var(--light-hl-2); + --hl-3: var(--light-hl-3); + --hl-4: var(--light-hl-4); + --hl-5: var(--light-hl-5); + --hl-6: var(--light-hl-6); + --hl-7: var(--light-hl-7); --code-background: var(--light-code-background); } } @media (prefers-color-scheme: dark) { :root { --hl-0: var(--dark-hl-0); + --hl-1: var(--dark-hl-1); + --hl-2: var(--dark-hl-2); + --hl-3: var(--dark-hl-3); + --hl-4: var(--dark-hl-4); + --hl-5: var(--dark-hl-5); + --hl-6: var(--dark-hl-6); + --hl-7: var(--dark-hl-7); --code-background: var(--dark-code-background); } } :root[data-theme='light'] { --hl-0: var(--light-hl-0); + --hl-1: var(--light-hl-1); + --hl-2: var(--light-hl-2); + --hl-3: var(--light-hl-3); + --hl-4: var(--light-hl-4); + --hl-5: var(--light-hl-5); + --hl-6: var(--light-hl-6); + --hl-7: var(--light-hl-7); --code-background: var(--light-code-background); } :root[data-theme='dark'] { --hl-0: var(--dark-hl-0); + --hl-1: var(--dark-hl-1); + --hl-2: var(--dark-hl-2); + --hl-3: var(--dark-hl-3); + --hl-4: var(--dark-hl-4); + --hl-5: var(--dark-hl-5); + --hl-6: var(--dark-hl-6); + --hl-7: var(--dark-hl-7); --code-background: var(--dark-code-background); } .hl-0 { color: var(--hl-0); } +.hl-1 { color: var(--hl-1); } +.hl-2 { color: var(--hl-2); } +.hl-3 { color: var(--hl-3); } +.hl-4 { color: var(--hl-4); } +.hl-5 { color: var(--hl-5); } +.hl-6 { color: var(--hl-6); } +.hl-7 { color: var(--hl-7); } pre, code { background: var(--code-background); } diff --git a/docs/content-security-policy/functions/cspDirectives.html b/docs/content-security-policy/functions/cspDirectives.html index a653ccdf..9ff3fd32 100644 --- a/docs/content-security-policy/functions/cspDirectives.html +++ b/docs/content-security-policy/functions/cspDirectives.html @@ -24,7 +24,7 @@

Parameters

__namedParameters: Config

Returns Promise<string[]>

+
  • Defined in csp-directives.ts:24
    • diff --git a/docs/content-security-policy/functions/cspHeader.html b/docs/content-security-policy/functions/cspHeader.html index 06514089..0f0a9115 100644 --- a/docs/content-security-policy/functions/cspHeader.html +++ b/docs/content-security-policy/functions/cspHeader.html @@ -24,7 +24,7 @@

    Parameters

    __namedParameters: Config

    Returns Promise<string>

    +
  • Defined in csp-directives.ts:107
    • diff --git a/docs/content-security-policy/functions/cspJSON.html b/docs/content-security-policy/functions/cspJSON.html index f76757e0..74ccab4b 100644 --- a/docs/content-security-policy/functions/cspJSON.html +++ b/docs/content-security-policy/functions/cspJSON.html @@ -24,7 +24,7 @@

    Parameters

    __namedParameters: Config

    Returns Promise<{}>

    +
  • Defined in csp-directives.ts:119
    • diff --git a/docs/content-security-policy/functions/validationErrorOrWarnings.html b/docs/content-security-policy/functions/validationErrorOrWarnings.html index f3fe45f3..ad7d8c09 100644 --- a/docs/content-security-policy/functions/validationErrorOrWarnings.html +++ b/docs/content-security-policy/functions/validationErrorOrWarnings.html @@ -24,7 +24,7 @@

    Parameters

    __namedParameters: ValidationErrorOrWarningsConfig

    Returns { error: undefined; warnings: string[] } | { error: Error; warnings: string[] }

    +
  • Defined in errors.ts:15
    • diff --git a/docs/content-security-policy/index.html b/docs/content-security-policy/index.html index 1f04683e..3fdf3d2f 100644 --- a/docs/content-security-policy/index.html +++ b/docs/content-security-policy/index.html @@ -16,14 +16,25 @@

    @jackdbd/content-security-policy

    npm version Snyk Vulnerabilities for npm package

    -

    Description...

    +

    Content-Security-Policy in JavaScript, with validation and automatic hashes.

    +

    This package validates your Content-Security-Policy directives and calculates a crypographic hash (SHA-256, SHA-384 or SHA-512) for all inline scripts and styles that finds in each HTML file.

    +
    +

    :information_source: Note:

    +

    :question: If your site is built with Eleventy, you can also use @jackdbd/eleventy-plugin-content-security-policy, which also take care of writing the Content-Security-Policy header in a _headers file.

    +
    Table of Contents
    @@ -35,10 +46,48 @@

    Installation

    npm install @jackdbd/content-security-policy
    + +

    Usage

    +     +
    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 site
      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

    +     + + +

    Required parameters

    +     + + + + + + + + + + + + + + + +
    ParameterExplanation
    directivesDirectives for the Content-Security-Policy (or Content-Security-Policy-Report-Only) header.
    patternsglob patterns for your .html files.
    +

    API

    API docs generated with TypeDoc

    + + +

    Prior art

    +     +
    diff --git a/docs/content-security-policy/interfaces/Config.html b/docs/content-security-policy/interfaces/Config.html index ba841b27..133ac27b 100644 --- a/docs/content-security-policy/interfaces/Config.html +++ b/docs/content-security-policy/interfaces/Config.html @@ -18,7 +18,7 @@

    Hierarchy

    • Config
    +
  • Defined in csp-directives.ts:16
    • @@ -35,12 +35,12 @@

    Properties

    directives

    directives: Directives
    +
  • Defined in csp-directives.ts:17

    • patterns

    patterns: string[]
    +
  • Defined in csp-directives.ts:18
    • diff --git a/docs/content-security-policy/interfaces/Directives.html b/docs/content-security-policy/interfaces/Directives.html index 396ee8aa..bf01ced8 100644 --- a/docs/content-security-policy/interfaces/Directives.html +++ b/docs/content-security-policy/interfaces/Directives.html @@ -21,7 +21,7 @@

    Hierarchy

    Indexable

    [k: string]: string[]
    +
  • Defined in directives.ts:90
    • diff --git a/docs/content-security-policy/interfaces/ValidationErrorOrWarningsConfig.html b/docs/content-security-policy/interfaces/ValidationErrorOrWarningsConfig.html index 89468e07..4b521e26 100644 --- a/docs/content-security-policy/interfaces/ValidationErrorOrWarningsConfig.html +++ b/docs/content-security-policy/interfaces/ValidationErrorOrWarningsConfig.html @@ -18,7 +18,7 @@

    Hierarchy

    • ValidationErrorOrWarningsConfig
    +
  • Defined in errors.ts:7
    • @@ -35,12 +35,12 @@

    Properties

    allowDeprecatedDirectives

    allowDeprecatedDirectives: boolean
    +
  • Defined in errors.ts:8

    • error

    error: any
    +
  • Defined in errors.ts:9
    • diff --git a/docs/content-security-policy/variables/recommended_policy.html b/docs/content-security-policy/variables/recommended_policy.html index 7ccf429e..d6970d28 100644 --- a/docs/content-security-policy/variables/recommended_policy.html +++ b/docs/content-security-policy/variables/recommended_policy.html @@ -59,7 +59,7 @@
    style-src:
    upgrade-insecure-requests: boolean
    +
  • Defined in policies.ts:30
    • diff --git a/docs/content-security-policy/variables/starter_policy.html b/docs/content-security-policy/variables/starter_policy.html index 4d3d5033..889d2ade 100644 --- a/docs/content-security-policy/variables/starter_policy.html +++ b/docs/content-security-policy/variables/starter_policy.html @@ -35,7 +35,7 @@
    script-src:
    style-src: string[]
    +
  • Defined in policies.ts:5
    • diff --git a/package.json b/package.json index 8a1e6ed2..aa326973 100644 --- a/package.json +++ b/package.json @@ -37,6 +37,7 @@ "build:libs": "tsc --build --verbose", "build:libs:watch": "tsc --build --watch", "clean": "npm run clean --workspaces --if-present", + "demo:csp": "tsm packages/scripts/src/demo/content-security-policy.ts --policy custom", "dev:scripts": "run-p build:libs:watch build:scripts:watch", "format": "npm run format --workspaces --if-present", "lint": "npm run lint --workspaces --if-present", diff --git a/packages/content-security-policy/README.md b/packages/content-security-policy/README.md index 0548ab34..ed25aac3 100644 --- a/packages/content-security-policy/README.md +++ b/packages/content-security-policy/README.md @@ -3,14 +3,24 @@ [![npm version](https://badge.fury.io/js/@jackdbd%2Fcontent-security-policy.svg)](https://badge.fury.io/js/@jackdbd%2Fcontent-security-policy) ![Snyk Vulnerabilities for npm package](https://img.shields.io/snyk/vulnerabilities/npm/@jackdbd%2Fcontent-security-policy) -Description... +Content-Security-Policy in JavaScript, with validation and automatic hashes. + +This package validates your Content-Security-Policy directives and calculates a crypographic hash (SHA-256, SHA-384 or SHA-512) for all inline scripts and styles that finds in each HTML file. + +> :information_source: **Note:** +> +> :question: If your site is built with [Eleventy](https://www.11ty.dev/), you can also use [@jackdbd/eleventy-plugin-content-security-policy](https://www.npmjs.com/package/@jackdbd/eleventy-plugin-content-security-policy), which also take care of writing the Content-Security-Policy header in a `_headers` file.
    Table of Contents - [Installation](#installation) +- [Usage](#usage) +- [Configuration](#configuration) + - [Required parameters](#required-parameters) - [API](#api) +- [Prior art](#prior-art)
    @@ -21,6 +31,58 @@ Description... npm install @jackdbd/content-security-policy ``` +## Usage + +```js +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 site + 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 + +### Required parameters + +| Parameter | Explanation | +| --- | --- | +| `directives` | [Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives) for the Content-Security-Policy (or Content-Security-Policy-Report-Only) header. | +| `patterns` | glob patterns for your `.html` files. | + ## API [API docs generated with TypeDoc](https://jackdbd.github.io/calderone/content-security-policy/) + +## Prior art + +- [netlify-plugin-csp-generator](https://github.com/MarcelloTheArcane/netlify-plugin-csp-generator) +- [seespee](https://github.com/papandreou/seespee) diff --git a/packages/scripts/src/demo/content-security-policy.ts b/packages/scripts/src/demo/content-security-policy.ts index e481f426..c2dd9d71 100644 --- a/packages/scripts/src/demo/content-security-policy.ts +++ b/packages/scripts/src/demo/content-security-policy.ts @@ -1,54 +1,99 @@ import path from 'node:path' import PrettyError from 'pretty-error' -import { cspJSON } from '@jackdbd/content-security-policy' +import yargs from 'yargs' +import { + cspDirectives, + cspHeader, + cspJSON +} from '@jackdbd/content-security-policy' +import { + starter_policy, + recommended_policy +} from '@jackdbd/content-security-policy/policies' import { monorepoRoot } from '@jackdbd/utils/path' const pe = new PrettyError() +interface Argv { + format: string + policy: string +} + +const DEFAULT: Argv = { + format: 'json', + policy: 'recommeded' +} + const main = async () => { - const directives = { - 'base-uri': ['self'], + const argv = yargs(process.argv.slice(2)) + .choices('format', ['directives', 'header', 'json']) + .describe('policy', 'which CSP to use') + .choices('policy', ['starter', 'recommeded', 'custom']) + .default(DEFAULT).argv as Argv + + let directives = {} + switch (argv.policy) { + case 'custom': { + directives = { + 'base-uri': ['self'], + + 'connect-src': [ + 'self', + 'cloudflareinsights.com', + 'plausible.io', + 'res.cloudinary.com' + ], + + 'default-src': ['none'], + + 'font-src': ['self'], - 'connect-src': [ - 'self', - 'cloudflareinsights.com', - 'plausible.io', - 'res.cloudinary.com' - ], + 'frame-src': [ + 'https://www.youtube.com/embed/', + 'https://www.youtube-nocookie.com/', + 'https://player.vimeo.com/video/' + ], - 'default-src': ['none'], + 'img-src': [ + 'self', + 'github.com', + 'raw.githubusercontent.com', + 'res.cloudinary.com' + ], - 'font-src': ['self'], + // https://makandracards.com/makandra/503862-using-inline-event-handlers-with-a-strict-content-security-policy-csp + 'script-src-attr': ['self', 'unsafe-hashes', 'sha256'], - 'frame-src': [ - 'https://www.youtube.com/embed/', - 'https://www.youtube-nocookie.com/', - 'https://player.vimeo.com/video/' - ], + 'script-src-elem': [ + 'self', + 'https://plausible.io/js/plausible.js', + 'https://static.cloudflareinsights.com/beacon.min.js', + 'https://unpkg.com/htm/preact/standalone.module.js' + ], - 'img-src': [ - 'self', - 'github.com', - 'raw.githubusercontent.com', - 'res.cloudinary.com' - ], + // https://content-security-policy.com/examples/allow-inline-style/ + 'style-src-attr': ['self', 'unsafe-hashes', 'sha256'], - // https://makandracards.com/makandra/503862-using-inline-event-handlers-with-a-strict-content-security-policy-csp - 'script-src-attr': ['self', 'unsafe-hashes', 'sha256'], + 'style-src-elem': ['self', 'sha256'], - 'script-src-elem': [ - 'self', - 'https://plausible.io/js/plausible.js', - 'https://static.cloudflareinsights.com/beacon.min.js', - 'https://unpkg.com/htm/preact/standalone.module.js' - ], + 'worker-src': ['self'] + } + break + } - // https://content-security-policy.com/examples/allow-inline-style/ - 'style-src-attr': ['self', 'unsafe-hashes', 'sha256'], + case 'recommended': { + directives = recommended_policy + break + } - 'style-src-elem': ['self', 'sha256'], + case 'starter': { + directives = starter_policy + break + } - 'worker-src': ['self'] + default: { + directives = recommended_policy + } } // const patterns = ['assets/html-pages/**/*.html'] @@ -56,12 +101,32 @@ const main = async () => { path.join(monorepoRoot(), 'assets', 'html-pages', '**/*.html') ] - try { - const obj = await cspJSON({ directives, patterns }) - console.log(`\nHere is the Content-Security-Policy\n`) - console.log(obj) - } catch (err: any) { - console.log(pe.render(err)) + if (argv.format === 'json') { + try { + const obj = await cspJSON({ directives, patterns }) + console.log(`\nHere is the Content-Security-Policy (JSON)\n`) + console.log(obj) + } catch (err: any) { + console.log(pe.render(err)) + } + } else if (argv.format === 'directives') { + try { + const strings = await cspDirectives({ directives, patterns }) + console.log(`\nHere is the Content-Security-Policy (directives)\n`) + console.log(strings) + } catch (err: any) { + console.log(pe.render(err)) + } + } else if (argv.format === 'header') { + try { + const header = await cspHeader({ directives, patterns }) + console.log(`\nHere is the Content-Security-Policy (header)\n`) + console.log(header) + } catch (err: any) { + console.log(pe.render(err)) + } + } else { + throw new Error(`forma ${argv.format} not implemented`) } }