Skip to content

Harden third-party JS: add CSP and pin MathJax with SRI - #9

Merged
McDic merged 1 commit into
masterfrom
harden/csp-sri-cdn-20260609
Jun 8, 2026
Merged

McDic merged 1 commit into
masterfrom
harden/csp-sri-cdn-20260609

Conversation

@McDic

@McDic McDic commented Jun 8, 2026

Copy link
Copy Markdown
Owner

Summary

Defense-in-depth follow-up to #8 (removing polyfill.io). Dependabot only scans dependency manifests (package.json, requirements.txt), so scripts loaded by raw URL — exactly the polyfill.io case — are invisible to it. This PR closes that blind spot for the whole site.

Changes

1. Content-Security-Policy <meta> tag (overrides/main.html)

Restricts which origins may load executable resources. This would have blocked the polyfill.io payload even while that line was still present, because polyfill.io was never on the allow list.

The script-src / frame-src / connect-src / font-src allow lists were derived empirically from the built site/, not guessed:

Directive Allowed origins (why)
script-src jsDelivr (MathJax), cdn.plot.ly (charts), utteranc.es (comments), w.soundcloud.com (player), googletagmanager (GA)
frame-src w.soundcloud.com, www.youtube.com (one post embeds a video), utteranc.es
style-src / font-src fonts.googleapis.com / fonts.gstatic.com (Material's Google Fonts)
connect-src Google Analytics beacon endpoints + utteranc.es

'unsafe-inline' is included for script-src/style-src because Material for MkDocs ships inline bootstrap blocks and static hosting (GitHub Pages) cannot mint a per-request nonce. This does not weaken the origin allow list — an external <script src> must still match an allowed host, so a rogue/new CDN stays blocked.

2. MathJax pinned to exact version + SRI

  • mathjax@3 (floating tag) → mathjax@3.2.2 (latest v3 line).
  • Added a sha384 Subresource Integrity hash (+ crossorigin) so a tampered CDN response is rejected by the browser.
  • Injected as a raw <script> via the Material scripts block because mkdocs extra_javascript can't set integrity. Config (window.MathJax) still loads before the library.

Verification (build-time)

  • mkdocs build succeeds; CSP meta present on every page; MathJax loads exactly once, pinned + SRI; floating @3 tag and polyfill.io both gone.

⚠️ Needs local browser testing before merge

CSP runtime effects can't be confirmed from the build alone. Please verify in mkdocs serve (DevTools console should show no CSP violations):

  • Math renders (e.g. series/cpp/3)
  • SoundCloud music player works
  • Utterances comments load
  • Search works (web worker)
  • The YouTube embed plays
  • Google Analytics fires (Network tab)

If any feature breaks, the offending origin just needs adding to the relevant directive. To roll out cautiously, the http-equiv value can temporarily be Content-Security-Policy-Report-Only to observe violations without enforcing.

Notes

  • GitHub Pages can't set HTTP headers, hence the <meta> delivery (note: frame-ancestors/report-uri are ignored in meta form — not relied upon here).
  • Plotly is already exact-pinned in generated raw_html/; CSP now also restricts its origin. SRI on those generated files was left out to avoid churn on regeneration.

🤖 Generated with Claude Code

Defense-in-depth follow-up to removing polyfill.io. Dependabot only
scans dependency manifests, so URL-loaded CDN scripts are an audit
blind spot; this closes it for the whole site.

- Add a Content-Security-Policy <meta> tag (overrides/main.html). The
  script-src/frame-src/connect-src origin allow lists were derived
  empirically from the built site (jsDelivr, cdn.plot.ly, utteranc.es,
  w.soundcloud.com, youtube.com, Google Fonts/Analytics). A rogue or
  newly-introduced external origin can no longer load scripts -- this
  would have blocked the polyfill.io payload even with the line present.
- Pin MathJax to an exact version (3.2.2) and add a Subresource
  Integrity hash so a tampered CDN response is rejected. Injected via a
  raw <script> tag because mkdocs `extra_javascript` cannot set
  `integrity`/`crossorigin`. Config still loads before the library.

CSP is delivered as a <meta> tag because GitHub Pages cannot set HTTP
headers. 'unsafe-inline' is required for Material's inline bootstrap
scripts/styles on static hosting, but the origin allow list (the part
that matters here) is unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@McDic McDic self-assigned this Jun 8, 2026
@McDic
McDic merged commit 3f184ad into master Jun 8, 2026
2 checks passed
@McDic
McDic deleted the harden/csp-sri-cdn-20260609 branch June 8, 2026 15:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant