Astro-Client-Islands unter strikter CSP

Warum Astro-Islands unter script-src 'self' still scheitern, wie ich die zwei Hydrations-Inlines per sha256-Hash erlaubt habe und ein Drift-Check beim Deploy.

Artikel Erstellt Aktualisiert Auch auf Englisch: Astro Client Islands under a Strict CSP

Geprüft von adrian am

Die Foto-Sektion meiner alten Seite hatte ein Lightbox-Karussell, eine React-Komponente mit client:load. Lokal lief alles. In Produktion passierte beim Klick auf ein Bild nichts, und die Browser-Konsole meldete:

Executing inline script violates the following Content Security Policy directive 'script-src 'self''.
Either the 'unsafe-inline' keyword, a hash ('sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c='),
or a nonce ('nonce-...') is required to enable inline execution.

Zwei solche Fehler, mit zwei verschiedenen Hashes. Die strikte CSP in Caddy tat genau das, wofür ich sie gebaut hatte, und blockierte genau das, was Astro für die Hydration braucht.

Was Astro inline einfügt

Die client:*-Direktiven (client:load, client:visible, client:idle und so weiter) brauchen einen winzigen Bootstrap. Er entscheidet, wann eine Komponente im Browser hydratisiert wird, und führt sie dann aus. Astro fügt ihn als zwei kleine Inline-<script>-Blöcke in jede Seite mit Islands ein:

<script>(()=>{var e=async t=>{await(await t())()};(self.Astro||(self.Astro={})).load=e;w...</script>
<script>(()=>{var A=Object.defineProperty;var g=(i,o,a)=>o in i?A(i,o,{enumerable:!0,con...</script>

Zusammen rund 1,5 kB. Bei script-src 'self' ohne 'unsafe-inline' blockt der Browser beide. Die Hydration startet nie, jede Island bleibt statisches HTML, und alle Event-Handler aus React, motion und Co. fehlen.

Der wichtige Punkt: Beide Blöcke sind pro Astro-Version deterministisch. Dasselbe npm run build erzeugt dieselben Bytes und damit dieselben sha256-Hashes. Astro schreibt keine zufälligen IDs, Zeitstempel oder Build-Hashes hinein.

Drei Auswege

  1. 'unsafe-inline' für Skripte erlauben. Damit ist die CSP nutzlos.
  2. Nonces. Die helfen nur, wenn Caddy pro Request einen frischen Nonce in HTML und Header einsetzt. Diese Infrastruktur wollte ich auf einer statischen Seite nicht haben.
  3. Hash-Pinning: die genauen sha256-Hashes der zwei Inlines in die CSP eintragen.

Hash-Pinning passt zu einer statischen Seite: keine Server-Logik, keine Arbeit pro Request, nur zwei zusätzliche Tokens in script-src.

Die Hashes berechnen

Direkt aus dem Build-Output, ohne weiteres Werkzeug:

python3 -c "
import re, hashlib, base64
from pathlib import Path
html = Path('dist/fotos/unterwegs/asien/malaysia/kuala-lumpur/index.html').read_text()
for body in dict.fromkeys(re.findall(r'<script(?![^]>]*\bsrc=)[^]>]*>(.*?)</script>', html, re.DOTALL)):
    if body.strip():
        print('sha256-' + base64.b64encode(hashlib.sha256(body.encode()).digest()).decode())
"

Jede Seite mit einer client:*-Island reicht, die zwei Inlines sind überall gleich. Das Skript gibt die zwei Hashes aus, die in die CSP gehören.

Die CSP in Caddy anpassen

In meiner Caddy-Konfiguration steht die CSP als ein einziger Wert in einem header-Block:

- script-src 'self';
+ script-src 'self' 'sha256-QzWFZi+FLIx23tnm9SBU4aEgx4x8DsuASP07mfqol/c=' 'sha256-QJZDUlo/qa5AJCrG6vHyWcatjwCeWidEHQfJc601lzw=';

Der Rest bleibt, wie er war: default-src 'none', img-src, style-src. Dann prüfen und neu laden:

sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

curl -sI https://adrian-altner.de/ | grep -i content-security zeigte direkt danach die neuen Hashes im Header. Beim nächsten Seitenaufruf hydratisierte die Island, und das Modal ging auf.

Wenn Astro aktualisiert wird

Die Hashes hängen an den Bytes der Inlines. Astro kann den Bootstrap zwischen Versionen umbauen, vor allem bei Major-Releases und manchmal bei Minor-Releases. Patch- und Minor-Updates innerhalb einer Major lassen ihn meist in Ruhe, aber „meist“ heißt nicht „immer“. Ohne Prüfung merkst du es erst, wenn in Produktion still etwas kaputtgeht.

Stand November 2026 gibt es einen anderen Weg: Mit Astro 6 (März 2026) ist die Content-Security-Policy-API von Astro stabil. Mit security: { csp: true } hasht Astro seine eigenen Skripte und Styles und schreibt die Policy selbst, die Hashes musst du dann nicht mehr von Hand eintragen.1

Drift-Check im Deploy-Workflow

Der richtige Moment für die Prüfung ist direkt nach dem Deploy: Der neue Build läuft, die alte CSP steht noch. Mein Forgejo-Runner hat dafür einen zusätzlichen Schritt im Workflow:

- name: Verify CSP script-src hashes
  run: |
    SAMPLE_PATH='/fotos/unterwegs/asien/malaysia/kuala-lumpur/'
    export LIVE_HTML="$(curl -fsSL "https://adrian-altner.de${SAMPLE_PATH}")"
    export LIVE_CSP="$(curl -fsSI "https://adrian-altner.de${SAMPLE_PATH}" \
      | tr -d '\r' | grep -i '^content-security-policy:')"

    python3 - <<'PY'
    import os, re, hashlib, base64, sys
    html = os.environ['LIVE_HTML']
    csp  = os.environ['LIVE_CSP']
    inlines = re.findall(r'<script(?![^]>]*\bsrc=)[^]>]*>(.*?)</script>', html, re.DOTALL)
    served = sorted({'sha256-' + base64.b64encode(hashlib.sha256(b.encode()).digest()).decode()
                     for b in inlines if b.strip()})
    configured = sorted(set(re.findall(r"sha256-[A-Za-z0-9+/=]+", csp)))
    if set(served) == set(configured):
        print(f"OK: CSP hashes match ({len(served)}).")
        sys.exit(0)
    print("::error title=CSP hash drift::live HTML and CSP no longer agree")
    # ... print missing/stale + ready-to-paste sed patch ...
    sys.exit(1)
    PY

Der Runner liest kein Build-Verzeichnis und braucht kein sudo für die Caddy-Datei. Er ruft nur die öffentliche Seite mit curl ab, holt die zwei Inlines aus dem HTML und vergleicht sie mit dem Content-Security-Policy-Header der Antwort. Das ist genau das, was auch der Browser sieht. Die sudoers-Regel des Runners konnte deshalb eng auf podman build und systemctl restart beschränkt bleiben.

Bei Drift schlägt der Schritt fehl, mit einer Forgejo-Annotation und einem fertigen sudo sed-Patch im Log. Dann:

  1. Der Forgejo-Lauf wird rot, die Annotation „CSP hash drift detected“ zeigt beide Hash-Sätze nebeneinander.
  2. ssh hetzner, den Patch aus dem Log einfügen: sed-Ersetzung, caddy validate, systemctl reload caddy.
  3. In der Forgejo-Oberfläche „Re-run workflow“, und der Schritt wird grün.

Der Deploy-Workflow lief ohnehin bei jedem Push und einmal täglich um 06:00 UTC. So wurde der Drift-Check zu einer kostenlosen täglichen Versicherung.

Inline-Styles

Astro fügt unter Umständen auch CSS inline in den <head> ein. Auf meiner Seite lief dafür style-src 'self' 'unsafe-inline'. Das war pragmatisch: Inline-CSS ist ein deutlich kleineres Risiko als Inline-JavaScript, und Astros CSS-Inlines sind zu zahlreich für Hash-Pinning.

Was ich bewusst nicht gemacht habe

  • Die Lightbox als schlichtes <dialog> neu schreiben. Ein natives <dialog> mit ein paar TypeScript-Handlern hätte keine React-Island, keine Hydrations-Inlines und keine CSP-Pflege gebraucht. Es wäre aber ein größerer Umbau gewesen, und ich hätte motion für die Slide- und Drag-Animationen verloren. Hash-Pinning war die kleinere Änderung mit winzigem Wartungsaufwand.
  • 'unsafe-inline' in script-src aufnehmen. Dann kannst du den Skript-Teil der CSP auch gleich löschen. Es ging ja gerade um eine harte Schranke gegen XSS und kompromittierte Dependencies.

Am Ende standen zwei Hash-Tokens in der CSP und ein Forgejo-Schritt, der sie nach jedem Deploy mit dem Live-Header vergleicht und bei Drift rot wird.

Beruht auf

  • Astro-Client-Islands unter strikter CSP: die Hydrations-Inlines per sha256-Hash erlauben (raw/2026/2026-04-29/astro-client-islands-unter-strikter-csp-die-hydrations-inlines-per-sha256-hash-erlauben.md) [post]
  • Astro 6 [astro6]

Mehr dazu

Thema

  • Statische Website Eine Website aus fertigen HTML-Dateien, die einmal gebaut und dann unverändert ausgeliefert werden. Kein Servercode, keine Datenbank.
  • Webentwicklung Wie diese und andere Websites entstehen und gefunden werden: statische Seiten, Suchmaschinen, IndieWeb und Karten im Browser.

Baut auf

  • Security-Header in Caddy Eine strikte Content Security Policy, HSTS und no-referrer in einem Caddy-Siteblock, geprüft mit Webbkoll, securityheaders.com und dem Mozilla Observatory.

Nutzt

  • Caddy Webserver und Reverse Proxy, der TLS-Zertifikate selbst holt und erneuert, eingerichtet in einem kurzen Caddyfile.
  • Forgejo Git-Plattform zum Selbsthosten: Repositories, Benutzer, SSH-Zugang und CI/CD mit Forgejo Actions und eigenen Runnern. Codeberg läuft damit.

Im Text erwähnt

  • Forgejo Actions Runner einrichten Push-to-Deploy mit einem eigenen Forgejo Actions Runner auf demselben VPS: eigener Benutzer, kein Docker, enge sudo-Rechte, Secrets in Forgejo.

In der Graph-Ansicht zeigen