Skip to main content

Security

Dockview runs under a strict Content Security Policy without 'unsafe-inline' or 'unsafe-eval'. This page covers the one part of Dockview that a strict policy affects, and how to configure it.

Where CSP matters​

Only one thing Dockview does interacts with CSP: opening a popout window. Dockview reads the parent window's stylesheets and recreates them in the popout's <head>, preserving the original cascade order. Stylesheets loaded via an href (external CSS files) are recreated as <link rel="stylesheet"> elements and are subject to your style-src source expressions. Stylesheets without an href (inline <style> or CSSOM-created sheets) are recreated as inline <style> elements, which is what needs a nonce.

Because external sheets are re-attached as <link> elements, the popout loads them asynchronously and may render unstyled for a frame before the network (or HTTP cache) resolves the request. For same-origin sheets this is generally invisible (the browser serves them from cache), but expect a brief flash if your CSS is hosted on a slow origin.

A policy like the following is enough to run Dockview with popouts:

Content-Security-Policy:
  default-src 'self';
  style-src   'self' 'nonce-RANDOM_NONCE';
  script-src  'self' 'nonce-RANDOM_NONCE';

Note that:

  • You do not need 'unsafe-inline' in style-src.
  • RANDOM_NONCE must be regenerated per response. It should be the same nonce that your server-rendered HTML applies to its own <script> / <style> tags.
  • The nonce only authorises the inline <style> elements Dockview injects. The <link rel="stylesheet"> elements are still matched against your style-src source expressions, so make sure those URLs are covered by 'self' or an explicit origin.
  • If your popout is same-origin (the default for window.open(url) where url is on your origin), the popout document inherits your CSP and nonce, so the same nonce works for both windows.

Passing the nonce to Dockview​

Dockview forwards a nonce option to every <style> element it creates. The nonce must be valid for the document the <style> lands in, which (for popout windows) is not the opener document. Because popout.html is a separate HTTP response with its own freshly-generated nonce, the parent page's nonce is never valid in the popout's CSP context.

For this reason nonce accepts either a string (when the same nonce is known to cover both documents, e.g. during local development with a static policy) or a function that is called with the target Document so you can read the nonce directly off the popout page.

The recommended setup is to have your popout.html emit a <meta name="csp-nonce"> element with its request nonce, then read it through the function form:

React
<DockviewReact
    nonce={(doc) =>
        doc.querySelector<HTMLMetaElement>('meta[name="csp-nonce"]')?.content
    }
    onReady={onReady}
    components={components}
/>
<!-- Vue -->
<dockview-vue :nonce="readCspNonce" @ready="onReady" />
Angular
<dockview-angular [nonce]="readCspNonce" (ready)="onReady($event)"></dockview-angular>
JavaScript
import { createDockview } from 'dockview';

const api = createDockview(element, {
    nonce: (doc) =>
        doc.querySelector<HTMLMetaElement>('meta[name="csp-nonce"]')?.content,
    createComponent: (options) => {
        /* ... */
    },
});

If your popout markup uses a different convention (for example a global like window.__CSP_NONCE__), return that from the function instead.

Checklist​

  • Add 'nonce-<value>' to your style-src directive on both the main page and the popout page.
  • Generate a fresh nonce per response (on both pages).
  • In the popout HTML, expose the nonce in a known location (a <meta name="csp-nonce"> tag is the most portable choice).
  • Provide the function form of nonce to Dockview so it reads the popout's own nonce at the moment styles are injected.
  • Serve the popout from the same origin as the host so it inherits your origin's CSP defaults.

Trusted Types​

Dockview is also compatible with Trusted Types (require-trusted-types-for 'script'). It writes no HTML strings to the DOM, so no policy or shim is required.

Project security​

  • The codebase is statically analysed by SonarCloud for security issues.
  • npm releases are published with provenance statements, so the source commit and workflow run behind a published package can be verified.
  • To report a vulnerability, use private vulnerability reporting rather than a public issue. The security policy covers supported versions, what is in scope, and response times.

See also​