docs(content-security-policy): improve README and rebuild docs

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); }

docs/content-security-policy/functions/cspDirectives.html

@@ -24,7 +24,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5>__namedParameters: <a href="../interfaces/Config.html" class="tsd-signature-type" data-tsd-kind="Interface">Config</a></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/csp-directives.ts#L24">csp-directives.ts:24</a></li></ul></aside></li></ul></section></div>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/csp-directives.ts#L24">csp-directives.ts:24</a></li></ul></aside></li></ul></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

docs/content-security-policy/functions/cspHeader.html

@@ -24,7 +24,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5>__namedParameters: <a href="../interfaces/Config.html" class="tsd-signature-type" data-tsd-kind="Interface">Config</a></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/csp-directives.ts#L107">csp-directives.ts:107</a></li></ul></aside></li></ul></section></div>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/csp-directives.ts#L107">csp-directives.ts:107</a></li></ul></aside></li></ul></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

docs/content-security-policy/functions/cspJSON.html

@@ -24,7 +24,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5>__namedParameters: <a href="../interfaces/Config.html" class="tsd-signature-type" data-tsd-kind="Interface">Config</a></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-symbol">{}</span><span class="tsd-signature-symbol">&gt;</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/csp-directives.ts#L119">csp-directives.ts:119</a></li></ul></aside></li></ul></section></div>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/csp-directives.ts#L119">csp-directives.ts:119</a></li></ul></aside></li></ul></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

docs/content-security-policy/functions/validationErrorOrWarnings.html

@@ -24,7 +24,7 @@ <h4 class="tsd-parameters-title">Parameters</h4>
 <h5>__namedParameters: <a href="../interfaces/ValidationErrorOrWarningsConfig.html" class="tsd-signature-type" data-tsd-kind="Interface">ValidationErrorOrWarningsConfig</a></h5></li></ul></div>
 <h4 class="tsd-returns-title">Returns <span class="tsd-signature-symbol">{ </span>error<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">undefined</span><span class="tsd-signature-symbol">; </span>warnings<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol"> }</span><span class="tsd-signature-symbol"> | </span><span class="tsd-signature-symbol">{ </span>error<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">Error</span><span class="tsd-signature-symbol">; </span>warnings<span class="tsd-signature-symbol">: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span><span class="tsd-signature-symbol"> }</span></h4><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/errors.ts#L15">errors.ts:15</a></li></ul></aside></li></ul></section></div>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/errors.ts#L15">errors.ts:15</a></li></ul></aside></li></ul></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

docs/content-security-policy/index.html

@@ -16,14 +16,25 @@ <h1>@jackdbd/content-security-policy</h1>
 </a>
 <p><a href="https://badge.fury.io/js/@jackdbd%2Fcontent-security-policy"><img src="https://badge.fury.io/js/@jackdbd%2Fcontent-security-policy.svg" alt="npm version"></a>
 <img src="https://img.shields.io/snyk/vulnerabilities/npm/@jackdbd%2Fcontent-security-policy" alt="Snyk Vulnerabilities for npm package"></p>
-<p>Description...</p>
+<p>Content-Security-Policy in JavaScript, with validation and automatic hashes.</p>
+<p>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.</p>
+<blockquote>
+<p>:information_source: <strong>Note:</strong></p>
+<p>:question: If your site is built with <a href="https://www.11ty.dev/">Eleventy</a>, you can also use <a href="https://www.npmjs.com/package/@jackdbd/eleventy-plugin-content-security-policy">@jackdbd/eleventy-plugin-content-security-policy</a>, which also take care of writing the Content-Security-Policy header in a <code>_headers</code> file.</p>
+</blockquote>
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 <details><summary>Table of Contents</summary>
 
 <ul>
 <li><a href="#installation">Installation</a></li>
+<li><a href="#usage">Usage</a></li>
+<li><a href="#configuration">Configuration</a><ul>
+<li><a href="#required-parameters">Required parameters</a></li>
+</ul>
+</li>
 <li><a href="#api">API</a></li>
+<li><a href="#prior-art">Prior art</a></li>
 </ul>
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 </details>
@@ -35,10 +46,48 @@ <h2>Installation</h2>
 <pre><code class="language-sh"><span class="hl-0">npm install @jackdbd/content-security-policy</span>
 </code></pre>
 
+<a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
+  <h2>Usage</h2>
+</a>
+<pre><code class="language-js"><span class="hl-1">import</span><span class="hl-0"> </span><span class="hl-2">path</span><span class="hl-0"> </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;node:path&#39;</span><br/><span class="hl-4">// pick the format you prefer: object, header (single string), directives (N strings)</span><br/><span class="hl-1">import</span><span class="hl-0"> {</span><br/><span class="hl-0">  </span><span class="hl-2">cspJSON</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-2">cspHeader</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-2">cspDirectives</span><br/><span class="hl-0">} </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/content-security-policy&#39;</span><br/><br/><span class="hl-4">// the Content-Security-Policy header is made of directives.</span><br/><span class="hl-4">// If you don&#39;t know where to start, use one of the following policies:</span><br/><span class="hl-1">import</span><span class="hl-0"> {</span><br/><span class="hl-0">  </span><span class="hl-2">starter_policy</span><span class="hl-0">,</span><br/><span class="hl-0">  </span><span class="hl-2">recommended_policy</span><br/><span class="hl-0">} </span><span class="hl-1">from</span><span class="hl-0"> </span><span class="hl-3">&#39;@jackdbd/content-security-policy/policies&#39;</span><br/><br/><span class="hl-5">const</span><span class="hl-0"> </span><span class="hl-6">directives</span><span class="hl-0"> = </span><span class="hl-2">recommended_policy</span><br/><br/><span class="hl-5">const</span><span class="hl-0"> </span><span class="hl-6">patterns</span><span class="hl-0"> = [</span><br/><span class="hl-0">  </span><span class="hl-4">// e.g. for a Eleventy site</span><br/><span class="hl-0">  </span><span class="hl-2">path</span><span class="hl-0">.</span><span class="hl-7">join</span><span class="hl-0">(</span><span class="hl-3">&#39;_site&#39;</span><span class="hl-0">, </span><span class="hl-3">&#39;**/*.html&#39;</span><span class="hl-0">)</span><br/><span class="hl-0">]</span><br/><br/><span class="hl-5">const</span><span class="hl-0"> </span><span class="hl-6">obj</span><span class="hl-0"> = </span><span class="hl-1">await</span><span class="hl-0"> </span><span class="hl-7">cspJSON</span><span class="hl-0">({ </span><span class="hl-2">directives</span><span class="hl-0">, </span><span class="hl-2">patterns</span><span class="hl-0"> })</span><br/><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-7">log</span><span class="hl-0">(</span><span class="hl-3">`Content-Security-Policy (as Object)`</span><span class="hl-0">)</span><br/><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-7">log</span><span class="hl-0">(</span><span class="hl-2">obj</span><span class="hl-0">)</span><br/><br/><span class="hl-5">const</span><span class="hl-0"> </span><span class="hl-6">header</span><span class="hl-0"> = </span><span class="hl-1">await</span><span class="hl-0"> </span><span class="hl-7">cspHeader</span><span class="hl-0">({ </span><span class="hl-2">directives</span><span class="hl-0">, </span><span class="hl-2">patterns</span><span class="hl-0"> })</span><br/><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-7">log</span><span class="hl-0">(</span><span class="hl-3">`Content-Security-Policy (as header)`</span><span class="hl-0">)</span><br/><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-7">log</span><span class="hl-0">(</span><span class="hl-2">header</span><span class="hl-0">)</span><br/><br/><span class="hl-5">const</span><span class="hl-0"> </span><span class="hl-6">strings</span><span class="hl-0"> = </span><span class="hl-1">await</span><span class="hl-0"> </span><span class="hl-7">cspDirectives</span><span class="hl-0">({ </span><span class="hl-2">directives</span><span class="hl-0">, </span><span class="hl-2">patterns</span><span class="hl-0"> })</span><br/><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-7">log</span><span class="hl-0">(</span><span class="hl-3">`Content-Security-Policy (as strings)`</span><span class="hl-0">)</span><br/><span class="hl-2">console</span><span class="hl-0">.</span><span class="hl-7">log</span><span class="hl-0">(</span><span class="hl-2">strings</span><span class="hl-0">)</span>
+</code></pre>
+
+<a href="#configuration" id="configuration" style="color: inherit; text-decoration: none;">
+  <h2>Configuration</h2>
+</a>
+
+<a href="#required-parameters" id="required-parameters" style="color: inherit; text-decoration: none;">
+  <h3>Required parameters</h3>
+</a>
+<table>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Explanation</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>directives</code></td>
+<td><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#directives">Directives</a> for the Content-Security-Policy (or Content-Security-Policy-Report-Only) header.</td>
+</tr>
+<tr>
+<td><code>patterns</code></td>
+<td>glob patterns for your <code>.html</code> files.</td>
+</tr>
+</tbody></table>
+
 <a href="#api" id="api" style="color: inherit; text-decoration: none;">
   <h2>API</h2>
 </a>
 <p><a href="https://jackdbd.github.io/calderone/content-security-policy/">API docs generated with TypeDoc</a></p>
+
+<a href="#prior-art" id="prior-art" style="color: inherit; text-decoration: none;">
+  <h2>Prior art</h2>
+</a>
+<ul>
+<li><a href="https://github.com/MarcelloTheArcane/netlify-plugin-csp-generator">netlify-plugin-csp-generator</a></li>
+<li><a href="https://github.com/papandreou/seespee">seespee</a></li>
+</ul>
 </div></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">

docs/content-security-policy/interfaces/Config.html

@@ -18,7 +18,7 @@ <h4>Hierarchy</h4>
 <ul class="tsd-hierarchy">
 <li><span class="target">Config</span></li></ul></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/csp-directives.ts#L16">csp-directives.ts:16</a></li></ul></aside>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/csp-directives.ts#L16">csp-directives.ts:16</a></li></ul></aside>
 <section class="tsd-panel-group tsd-index-group">
 <section class="tsd-panel tsd-index-panel">
 <details class="tsd-index-content tsd-index-accordion" open><summary class="tsd-accordion-summary tsd-index-summary">
@@ -35,12 +35,12 @@ <h2>Properties</h2>
 <h3 class="tsd-anchor-link"><span>directives</span><a href="#directives" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><path stroke="none" d="M0 0h24v24H0z" fill="none" id="icon-anchor-a"></path><path d="M10 14a3.5 3.5 0 0 0 5 0l4 -4a3.5 3.5 0 0 0 -5 -5l-.5 .5" id="icon-anchor-b"></path><path d="M14 10a3.5 3.5 0 0 0 -5 0l-4 4a3.5 3.5 0 0 0 5 5l.5 -.5" id="icon-anchor-c"></path></svg></a></h3>
 <div class="tsd-signature">directives<span class="tsd-signature-symbol">:</span> <a href="Directives.html" class="tsd-signature-type" data-tsd-kind="Interface">Directives</a></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/csp-directives.ts#L17">csp-directives.ts:17</a></li></ul></aside></section>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/csp-directives.ts#L17">csp-directives.ts:17</a></li></ul></aside></section>
 <section class="tsd-panel tsd-member tsd-kind-property tsd-parent-kind-interface"><a id="patterns" class="tsd-anchor"></a>
 <h3 class="tsd-anchor-link"><span>patterns</span><a href="#patterns" aria-label="Permalink" class="tsd-anchor-icon"><svg class="icon icon-tabler icon-tabler-link" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"><use href="#icon-anchor-a"></use><use href="#icon-anchor-b"></use><use href="#icon-anchor-c"></use></svg></a></h3>
 <div class="tsd-signature">patterns<span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span></div><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/csp-directives.ts#L18">csp-directives.ts:18</a></li></ul></aside></section></section></div>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/csp-directives.ts#L18">csp-directives.ts:18</a></li></ul></aside></section></section></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">

docs/content-security-policy/interfaces/Directives.html

@@ -21,7 +21,7 @@ <h4>Hierarchy</h4>
 <h4 class="tsd-before-signature">Indexable</h4>
 <div class="tsd-signature"><span class="tsd-signature-symbol">[</span>k: <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]: </span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">[]</span></div></section><aside class="tsd-sources">
 <ul>
-<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/8dc7aec/packages/content-security-policy/src/directives.ts#L90">directives.ts:90</a></li></ul></aside></div>
+<li>Defined in <a href="https://github.com/jackdbd/calderone/blob/05083d5/packages/content-security-policy/src/directives.ts#L90">directives.ts:90</a></li></ul></aside></div>
 <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
 <div class="tsd-navigation settings">
 <details class="tsd-index-accordion"><summary class="tsd-accordion-summary">