.. -*- coding: utf-8 -*-












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 2025, Wolfgang Scherer, <Wolfgang.Scherer at gmx.de>

.. This file is part of Netflix More More Info.

.. Permission is granted to copy, distribute and/or modify this document
.. under the terms of the GNU Free Documentation License, Version 1.3
.. or any later version published by the Free Software Foundation;
.. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.. A copy of the license is included in the section entitled "GNU
.. Free Documentation License".

.. inline comments (with du_comment_role)
.. role:: rem(comment)
.. role:: html(raw)
   :format: html
.. role:: shx(code)
   :language: js

.. rst-class:: narrow xmedium xlarge xhuge xultra

##################################################
:rem:`|||:sec:|||`\ The Trouble With CSS
##################################################

.. . (progn (forward-line 1) (snip-insert "rst_b.peek-a-boo" t t "rst") (insert ""))

.. >>CODD See `the components of a doctoral dissertation and their order <http://site.uit.no/english/writing-style/bookstructure/>`_
.. >>CODD Dedication
.. >>CODD Epigraph
.. >>CODD Abstract

**TL;DR**: Content Security Policy (CSP) takes the fun out of CSS and
inline style attributes. But do not fear! There is a remedy.

When developing a `browser extension`_ following the `WebExtensions
API`_, adding HTML elements can easily cause CSS pollution.
Conflicting CSS rules either put the host page or the extension
elements out of whack.

A simple solution is to use explicit *style* attributes on custom
extension elements.

A better solution is to use the `ShadowRoot`_.

The `WebExtensions API`_ provides for injecting CSS into web pages by various means, e.g.

- background task (`tabs.insertCSS()`_, `scripting.insertCSS()`_),
- content scripts (:file:`manifest.json`).

However, none of them can affect or target `ShadowRoot`_.

So, the method of choice used to be the simple JavaScript approach of
style elements with extension URLs or verbatim text, e.g.

- `<link rel="stylesheet" href="URL">`,
- `<style src="URL>"`,
- `<style>CSS rules</style>`.

Neither these methods, nor explicit *style* attributes work with CSP
`style-src 'self'` anymore.

The remedy is to use `constructable stylesheets (Web APIs)`_ (see also
`Constructable Stylesheets (web.dev)`_).

.. . |:here:|

.. _`Constructable Stylesheets (web.dev)`: https://web.dev/articles/constructable-stylesheets
.. _`constructable stylesheets (Web APIs)`: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#constructable_stylesheets
.. _`constructable stylesheets`: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#constructable_stylesheets
.. _`scripting.insertCSS()`: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/insertCSS
.. _`tabs.insertCSS()`: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/tabs/insertCSS
.. _`ShadowRoot`: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
.. _`browser extension`: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions
.. _`WebExtensions API`: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions
.. _`MDN`: https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot

.. \|:here:|

.. >>CODD Introduction
.. >>CODD Chapter

==================================================
:rem:`|||:sec:|||`\ ShadowRoot
==================================================


The element tree in the shadow root is independent from the element
tree in the main document. (See `Using shadow DOM
<https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM>`_).

The shadow root can be created programatically, e.g.

.. empty block
.. code-block:: js

.. code-block:: js
   :caption: Create shadow root

   const myStyleSheetText = "#kspan { color: blue; }";

   const myDiv = document.createElement("div");
   myDiv.setAttribute("id", "koeniglich");
   document.querySelector("body").appendChild(myDiv);

   const myShadow = myDiv.attachShadow({ mode: "open" });

   let mySpan = document.createElement("span");
   mySpan.setAttribute("id", "kspan");
   mySpan.textContent = "I'm in the shadow DOM";

   myShadow.appendChild(mySpan);

or with the *template* HTML element (see `<template>: The Content
Template element
<https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/template>`_)

.. code-block:: html

   <div id="koeniglich">
     <template shadowrootmode="open">
       <span id="kspan">I'm in the shadow DOM</span>
     </template>
   </div>

Shadow elements are not accessible from the main document, so

.. code-block:: js

   console.log("document #kspan:", document.querySelector("#kspan") ? document.querySelector("#kspan").textContent : document.querySelector("#kspan"));

returns `null`, while

.. code-block:: js

   console.log("myShadow #kspan:", myShadow.querySelector("#kspan") ? myShadow.querySelector("#kspan").textContent : myShadow.querySelector("#kspan"));

returns the shadow element

.. code-block:: html

   myShadow #kspan: I'm in the shadow DOM

After adding an element with the same ID in the regular DOM,

.. code-block:: js

   const myOuterDiv = document.createElement("div");
   myOuterDiv.setAttribute("id", "visible");
   document.querySelector("body").appendChild(myOuterDiv);
   mySpan = mySpan.cloneNode();
   mySpan.textContent = "So this is outside the shadow";
   myOuterDiv.appendChild(mySpan);

the query for the ID *kspan*,

.. code-block:: js

   console.log("document #kspan:", document.querySelector("#kspan") ? document.querySelector("#kspan").textContent : document.querySelector("#kspan"));

delivers the outer element:

.. code-block:: text

   document #kspan: So this is outside the shadow


===============================================================================
:rem:`|||:sec:|||`\ Violation of Content Security Policy "style-src 'self' ..."
===============================================================================

.. . -*- mode: rst;  truncate-lines: t; -*-
.. . |||:work:||| CSP from PyPi does not allow inline styles

Test Websites:

+-------------------------------------------------------+--------------------------------------------+
| Site                                                  | Problem                                    |
+=======================================================+============================================+
| https://www.pornhub.com/                              | assigns values to textarea, e.g. width     |
+-------------------------------------------------------+--------------------------------------------+
| https://developer.mozilla.org/en-US/docs/Web/CSS/flex | messes with the CSS                        |
+-------------------------------------------------------+--------------------------------------------+
| https://pypi.org                                      | Content Security Policy "style-src 'self'" |
+-------------------------------------------------------+--------------------------------------------+

Some Sources:

- CSP prevents inline stylesheets `Content security policy blocking
  injecting styles into pages - addons.mozilla.org - Mozilla Discourse
  <https://discourse.mozilla.org/t/content-security-policy-blocking-injecting-styles-into-pages/136127>`_
- `HTMLElement: style property - Web APIs | MDN
  <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style>`_,
- `How do you use Firefox Extensions to change CSS of a web site? -
  Stack Overflow
  <https://stackoverflow.com/questions/20878779/how-do-you-use-firefox-extensions-to-change-css-of-a-web-site>`_
- `Using dynamic styling information - Web APIs | MDN
  <https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information>`_

A CSS reference with an alphabetical index of all standard CSS
properties is available at `CSS reference - CSS | MDN
<https://developer.mozilla.org/en-US/docs/Web/CSS/Reference>`_

The Solution is to use CSSOM, see `Konstruierbare Stylesheets  | 
Articles  |  web.dev
<https://web.dev/articles/constructable-stylesheets>`_

Investigate `Window: getComputedStyle() method - Web APIs | MDN
<https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle>`_
in regard to automatic CSS rule generation from DOM elements.

--------------------------------------------------
:rem:`||:sec:||`\ CSP - The Problem
--------------------------------------------------

The standard method of constructing a *style* element,

.. code-block:: js

   const style = document.createElement("style");
   style.textContent = myStyleSheetText;
   myShadow.appendChild(style)

results in the error message

.. code-block:: text

   Content-Security-Policy: Die Einstellungen der Seite haben die
   Anwendung eines Styles (style-src-elem) blockiert, da er gegen
   folgende Direktive verstößt: "style-src 'self' ..."

Using a *link* element instead,

.. code-block:: js

   const link = document.createElement("link");
   link.setAttribute("rel", "stylesheet")
   link.setAttribute("href", "https://sw-amt.ws/not-there.css")
   document.querySelector("body").append(link)

also results in the error message

.. code-block:: text

   Content-Security-Policy: Die Einstellungen der Seite haben die
   Anwendung eines Styles (style-src-elem) blockiert, da er gegen
   folgende Direktive verstößt: "style-src 'self' ..."

Since the browser now hides the relevant CSP header, use wget(1) to
find the `Content-Security-Policy`:

.. code-block:: sh

   wget -O - --save-headers 'https://pypi.org/project/slimit/'

.. code-block:: text

   Content-Security-Policy:
    base-uri 'self';
    connect-src 'self' https://api.github.com/repos/ https://api.github.com/search/issues https://gitlab.com/api/ https://*.google-analytics.com https://*.analytics.google.com https://*.googletagmanager.com fastly-insights.com *.fastly-insights.com *.ethicalads.io https://api.pwnedpasswords.com https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/sre/mathmaps/ https://2p66nmmycsj3.statuspage.io;
    default-src 'none';
    font-src 'self' fonts.gstatic.com;
    form-action 'self' https://checkout.stripe.com;
    frame-ancestors 'none';
    frame-src 'none';
    img-src 'self' https://pypi-camo.freetls.fastly.net/ https://*.google-analytics.com https://*.googletagmanager.com *.fastly-insights.com *.ethicalads.io ethicalads.blob.core.windows.net;
    script-src 'self' https://*.googletagmanager.com https://www.google-analytics.com https://ssl.google-analytics.com *.fastly-insights.com *.ethicalads.io 'sha256-U3hKDidudIaxBDEzwGJApJgPEf2mWk6cfMWghrAa6i0=' https://cdn.jsdelivr.net/npm/mathjax@3.2.2/ 'sha256-1CldwzdEg2k1wTmf7s5RWVd7NMXI/7nxxjJM2C4DqII=' 'sha256-0POaN8stWYQxhzjKS+/eOfbbJ/u4YHO5ZagJvLpMypo=';
    style-src 'self' fonts.googleapis.com *.ethicalads.io 'sha256-2YHqZokjiizkHi1Zt+6ar0XJ0OeEy/egBnlm+MDMtrM=' 'sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=' 'sha256-JLEjeN9e5dGsz5475WyRaoA4eQOdNPxDIeUhclnJDCE=' 'sha256-mQyxHEuwZJqpxCw3SLmc4YOySNKXunyu2Oiz1r3/wAE=' 'sha256-OCf+kv5Asiwp++8PIevKBYSgnNLNUZvxAp4a7wMLuKA=' 'sha256-h5LOiLhk6wiJrGsG5ItM0KimwzWQH/yAcmoJDJL//bY=';
    worker-src *.fastly-insights.com

--------------------------------------------------
:rem:`||:sec:||`\ Element Style - Solution 1
--------------------------------------------------

One way around the CSS limitations is to programmatically access the
`style` attribute of a DOM node directly (source `javascript - How to
position a DIV at specific coordinates? - Stack Overflow
<https://stackoverflow.com/a/6802970/2127439>`_):

.. code-block:: javascript

   element.style.position = "absolute"
   element.style.top = "0"
   element.style.left = "99px"

--------------------------------------------------------
:rem:`||:sec:||`\ Constructable Stylesheets - Solution 2
--------------------------------------------------------

The bests remedy for CSP violations regarding styles, however, is to
use `constructable stylesheets`_, e.g:

.. code-block:: js

   const myStyleSheet = new CSSStyleSheet();
   myStyleSheet.replaceSync(myStyleSheetText);

The stylesheet is applied with

.. code-block:: js

   myShadow.adoptedStyleSheets.push(myStyleSheet);

Now the shadow text is blue, while the document text is still black.

The stylesheet can also be shared at other places, like

.. code-block:: js

   document.adoptedStyleSheets.push(myStyleSheet);

Now the outer text is also blue.

Using ths technique with firefox or chrome does not trigger a CSP violation.

.. . |||:work:|||

==================================================
:rem:`|||:sec:|||`\ Inner Workings of CSS
==================================================

Source `CSSStyleDeclaration - Web APIs <https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration>`_.

The `CSSStyleDeclaration` interface represents an object that is
a CSS declaration block, and exposes style information and various
style-related methods and properties.

A :class:`CSSStyleDeclaration` object can be exposed using three different
APIs:

- Via `HTMLElement.style
  <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style>`_,
  which deals with the inline styles of a single element (e.g., ``<div
  style="?">``).
- Via the `CSSStyleSheet
  <https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet>`_
  API. For example, :samp:`document.styleSheets[0].cssRules[0].style`
  returns a :class:`CSSStyleDeclaration` object on the first CSS rule
  in the document's first stylesheet.

  .. warning:: You cannot access cross-origin stylesheets
     (e.g. https://cdn.sstatic.net/Shared/stacks.css on
     https://stackoverflow.com). Doing so,

     .. code-block:: js

        console.log(document.styleSheets[0].cssRules[0].style.cssText);

     will throw an exception:

     .. code-block:: text

        Uncaught DOMException: CSSStyleSheet.cssRules getter: Not allowed to access cross-origin stylesheet

     See also `java - SecurityError: CSSStyleSheet.cssRules getter:
     Not allowed to access cross-origin stylesheet error
     ... <https://stackoverflow.com/questions/62475212/securityerror-cssstylesheet-cssrules-getter-not-allowed-to-access-cross-origin>`_

- Via `Window.getComputedStyle()
  <https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle>`_,
  which exposes the :class:`CSSStyleDeclaration` object as a
  **read-only** interface.

.. >>CODD Conclusion
.. >>CODD Appendix A

.. \|:here:|

.. >>CODD Notes
.. ==================================================
.. :rem:`|||:sec:|||`\ Footnotes
.. ==================================================

:html:`<hr>`

.. \[#]

.. \|:info:| put local references here
.. \|:info:| put local definitions here
.. include:: doc_defs.inc
.. include:: abbrev_defs.inc
.. include:: doc_defs_combined.inc
..
  .. \||<-snap->|| doc_standalone
  .. include:: doc/doc_defs_secret.inc
  .. \||<-snap->|| doc_standalone
  .. \||<-snap->|| not_doc_standalone
  .. include:: doc_defs_secret.inc
  .. \||<-snap->|| not_doc_standalone

.. _`Wolfgang Scherer`: wolfgang.scherer@gmx.de