sultan/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Instruktionen

Lies die .ai/*.md Files. Diese liefern den Context für die App, die hier entstehen soll. Maßgeblich ist aktuell .ai/sultan-system-architecture.md (Netzwerk-, Sicherheits-, Daten- und Anwendungsmodell inkl. SQL-Schema, Event-Format und Referenz-Compose-Files). Bei Widersprüchen zwischen diesem File und der Spec gilt die Spec. Architekturentscheidungen werden in der Spec nachgepflegt (betroffene Abschnitte + Entscheidungslog in Abschnitt 8) – das gehört zu jeder Änderung, die Architektur festlegt.

Projektstatus

Go-Modul sultan (Go 1.26). main.go ist nur eine Hülle um pkg/cli; umgesetzt sind sultan server|agent|token|dump-landing|version|help. Packages:

• pkg/traefik – übersetzt flache traefik.*-Labels (FromLabels) in Traefiks dynamische Konfiguration, führt Knoten-Configs zusammen (Merge) und rendert JSON/YAML (Marshal) für /v1/traefik-config. Traefik pollt diesen Endpunkt über seinen HTTP-Provider; Sultan schreibt nie in Traefik und emuliert keinen Docker-Socket.

• pkg/stream – Server→Agent-Kanal als SSE: Hub (Server, ein Stream pro Knoten, Keepalive :\n\n, Neuverbindung ersetzt alte mit ErrReplaced, OnConnect/OnDisconnect nur bei echtem Online/Offline), Client (Agent, Idle-Timeout 90s, Run mit exponentiellem Backoff, Prepare zum Signieren), Decoder. Authentifizierung macht der Aufrufer vor Hub.Serve. Agent→Server (service_state) läuft nicht über diesen Stream, sondern über eigene Requests.

• pkg/store – SQLite-Persistenz (Schema Spec 4.3) über modernc.org/sqlite (reines Go, kein cgo → statisches Binary). Migrationen sind eine append-only Liste in store.go, Version in PRAGMA user_version; neuere DB-Version → ErrSchemaTooNew. Zeitstempel werden aus Go gesetzt (injizierbare Uhr Store.now) und als UTC-Text fester Breite gespeichert, damit SQL-Vergleiche funktionieren – keine CURRENT_TIMESTAMP-Defaults verwenden. Enrollment-Tokens nur als SHA-256; Enroll verbraucht Token und legt Knoten atomar an. Fehler: ErrNotFound/ErrExists/ErrInvalid/ErrTokenUsed/ErrTokenExpired.

• pkg/auth – Ed25519-Request-Signatur, in jedem Tier Pflicht (kein Bypass, auch nicht für community/Homelab). Signer.Sign (passt als stream.Client.Prepare) signiert Methode, Pfad+Query, Zeitstempel, Nonce und Body-Hash (X-Sultan-*-Header). Verifier.Verify prüft in der Reihenfolge TLS → Signatur → Zeitfenster (±5min) → Nonce → Store, liefert Identity{Node, Tenant}; die Knoten-ID für Hub.Serve kommt nur daraus. VerifyUnregistered für Enrollment (Besitznachweis des Schlüssels). Gesperrt (ErrForbidden) wird nur bei Quarantäne; Zahlungsverzug/Ablauf/Drain regelt die Policy über das Routing. StatusCode(err) für HTTP-Antworten. Schlüsseldateien: PKCS#8-PEM, 0600, werden nie überschrieben.

• Kein Klartext: Signer signiert nur https-URLs, Verifier lehnt Requests ohne r.TLS ab (ErrInsecureTransport, 426). Tests für Agent↔Server laufen daher über TLS-Testserver.

• pkg/crypto – Transport: LoadOrCreateServerCert(dataDir) (selbstsigniert ECDSA P-256, keine CA, 20 Jahre, server.key 0600; fehlt eine der Dateien → Fehler statt Neuerzeugung), ServerTLSConfig (nur TLS 1.3), PinnedTLSConfig(fingerprint) – Pinning im Handshake am Fingerprint, unabhängig von der Adresse; ohne Fingerprint ErrUnknownServer (kein blindes TOFU). Enrollment-Token sltn_enroll_<secret>.<fingerprint>[.<base64url(server-url)>] (NewEnrollmentToken(fp, url)/ParseEnrollmentToken, ValidateServerURL); in den Store kommt nur Token.Secret. Paketname kollidiert mit Stdlib-crypto – bei Bedarf beim Import aliasen.

• pkg/license – Lizenz nach Spec 4.1: Issuer.Issue (normalisiert + signiert mit Master-Key, Präfix SULTAN-LICENSE-V1), Parse (strikt, unbekannte Felder abgelehnt) / Verify, AllowsDomain (*.x.de = alle Subdomains, nicht Apex; *.<tld> verboten), AllowsRoutes (-1 = unbegrenzt), HasFeature, Expired/DaysLeft.

• pkg/policy – HostsFromRule (echter Parser für Traefik-Regeln; jeder ||-Zweig muss Host-beschränkt sein, HostRegexp verboten), StageFor (blocked/landing/paywall/firemark/watermark, Mahnwesen nur kommerziell) und Engine.Apply: prüft Router (Domain, Referenzen, Middleware-Gates, Routenlimit), Namensraum <tenant>__<node>__<name>, leitet bei Stufe ≠ normal oder Healthcheck-Ausfall zu sultan__interceptor um (Header X-Sultan-Stage/Tenant/Tier); bei watermark/firemark zusätzlich Durchlass-Router sultan__<tenant>__<node>__<router> per Cookie sultan_ack=<stufe>. DunningSchedule (8/25/32 Tage) berechnet die Mahnstufe. Wartung: Input.Maintenance (Knoten) und Input.ServiceMaintenance (Label sultan.maintenance), Vorrang Ablauf/Paywall > Wartung > Mahnhinweis, Header X-Sultan-Until/X-Sultan-Public-Reason (URL-kodiert). Andockstelle MiddlewareTargetCheck (+ EnforceMiddlewareTargets) für die geplante Middleware-Zielbegrenzung; nil = dulden.

• pkg/registry – Aggregator: Update(nodeID, NodeState) (vollständiger Schnappschuss: Workloads mit Host+Labels, DownServices), Remove (der Server ruft es beim Trennen nur ohne aktive Wartung auf; pruneDisconnected räumt nach Wartungsende), Refresh (zeitabhängige Stufen, Directory-Änderungen; fail-static bei Fehlern, ErrUnknownNode entfernt), Config, Handler für /v1/traefik-config. OnViolation meldet jeden Verstoß nur beim ersten Auftreten. Mandant/Lizenz kommen über das Directory-Interface (Server-Implementierung: pkg/server/directory.go). Verstöße entfernen nur den Router und landen in Result.Violations. Ergebnisse mehrerer Knoten mit traefik.Merge kombinieren.

• pkg/server – sultan server: New (Datenverzeichnis 0700, DB, Zertifikat, master.key), Start/Run/Shutdown (Hub zuerst schließen, sonst hängen SSE-Requests), Routen beider Ports (handlers.go), Knotenstatus über Hub-Callbacks, Refresh-Schleife, Audit-Log „Policy-Verstoß“ per slog. Tests laufen gegen echte Ports (127.0.0.1:0) mit Test-Agent (Pinning + Signatur).

• pkg/cli – Run(ctx, args, stdout, stderr) int; Flags/Defaults von sultan server; sultan token in token.go (Befehlstabelle tokenCmds, usageError → Exit 2, openDataDir verweigert nicht initialisierte Verzeichnisse). Version per -ldflags "-X sultan/pkg/cli.Version=…".

• pkg/docker – minimaler Docker-Engine-Client über Unix-Socket (List mit all=1, PortBindings für gestoppte Container, Events), bewusst ohne SDK.

• pkg/agent – sultan agent: Enroll (node.key, Pinning über Einladungs-Fingerprint, node.json mit server_fingerprint; Adresse: --server/SULTAN_SERVER > URL in der Einladung > node.json, neue Adresse wird nach erfolgreichem Verbinden übernommen), Run (Stream mit OnConnect → Zustand neu senden, Docker-Watcher, Sammelintervall, kein Senden bei Docker-API-Fehler), Workloads (Container-Port → veröffentlichter Host-Port, Default-Service, unerreichbare Ports weglassen; gestoppte Container bleiben mit ihren Services in down → Wartungsseite, entfernte verschwinden, laufende gewinnen bei Namensgleichheit), backendHost (explizit → Interface → Route zum Server). Dazu /etc/sultan.d-YAML (sultand.go: ParseServices, LoadServiceDir, FileWorkloads → Traefik-Labels; Polling über dirFingerprint) und Healthchecks (health.go: checkHealth, healthTracker mit Fehlerschwelle) → DownServices. Tests laufen gegen echten pkg/server mit gefälschtem Docker-Socket.

• pkg/lander – Interceptor-Seiten je X-Sultan-Stage (eingebettete templates/*.html, zweisprachig), Cookie sultan_ack bei watermark/firemark, localTarget erlaubt nur lokale Pfade (html/template filtert meta refresh nicht!), eigene Vorlagen aus <data-dir>/landing mit eingebettetem CSS/Bild, Dump. Läuft im Server auf --lander-addr; die Interceptor-URL der Policy folgt der gebundenen Adresse. Test-Server immer mit LanderAddr: "127.0.0.1:0" starten (sonst Portkonflikt auf 8081).

Leases & Befehle (Schritt 2): license.TermsFor/IssueLease/ParseLease (Präfix SULTAN-LEASE-V1); der Server stellt Leases beim Verbinden und im Refresh aus (pkg/server/leases.go: ensureLease, dispatchCommands, leaseValid), getrennte Knoten behalten Routen als Wartungsseite bis Lease-Ende (Disconnected → Policy-Stufe maintenance), drain entfernt sofort. Hub signiert alle Events (Hub.SigningKey, stream.SignEvent/VerifyEvent); der Agent verwirft unsignierte (pkg/agent/events.go). Befehle: Warteschlange node_commands (CLI reiht ein), feste Liste stream.Cmd*; rotate_key über node.key.new + POST /api/v1/rotate-key (abbruchsicher). Signer im Agent nur über currentSigner() lesen (wird im Betrieb getauscht). Tests mit kurzen Leases über Config.LeaseDuration.

Monitoring & Jobs (Schritt 3): pkg/checkmk (Render(State, now), reine Funktion, ASCII) hinter GET /metrics/checkmk; pkg/notify (Slack, Ntfy, Multi); pkg/server/jobs.go: runJobs bei jedem Refresh (kommerzielle Verträge → expired, Benachrichtigungen über sendOnce mit Schlüssel inkl. Bezugsdatum in Tabelle notifications, Aufräumen nach 10 Tagen). Policy-Verstöße werden asynchron gemeldet (OnViolation läuft unter der Registry-Sperre). Tests nutzen Config.Notify mit einem aufzeichnenden Ziel.

Mehrere Adressen (Schritt 4): Config.PublicURLs (gemerkt als settings.public_urls, server.LoadPublicURLs), Versand per config-Befehl in nodeOnline; Agent: Identity.ServerURLs, serverCandidates/nextServerURL (Wechsel in OnError des Stream-Clients), a.serverURL nur über currentServerURL() lesen.

• deploy/ – Auslieferung: Dockerfile im Root (distroless, nonroot 65532, Multi-Arch, kein ENTRYPOINT, WORKDIR /), build.sh (Binaries amd64/arm64 + SHA256SUMS nach dist/<version>/), push-image.sh (liest deploy/.env mit REGISTRY/REGISTRY_USER/REGISTRY_PASSWORD, Vorlage deploy/.env.example; buildx → Zot-Registry zot.chmln.de/sultan; ohne Passwort Exit 1), publish-static.sh (rsync nach sultan/releases/<version>/), compose/{server,agent} (Agent mit network_mode: host). Version überall aus git describe; -dirty wird nicht veröffentlicht. .dockerignore hält suldata/, .ai/, CLAUDE.md aus dem Build-Kontext.

CLI-Umgebung: pkg/cli/env.go – annotateEnv/applyEnv machen jedes Flag als SULTAN_<FLAG> setzbar (nach fs.Parse, nur für nicht gesetzte Flags; Listen-Flags stringList kommagetrennt). Neue Flags bekommen das automatisch. Rate-Limit: pkg/server/ratelimit.go (EnrollLimit, -1 = aus).

Betriebsdoku: docs/community.md, docs/wartung.md, docs/hoster.md – bei Verhaltensänderungen mitpflegen. Projekt gilt seit 2026-10-03 vorerst als fertig; offene Punkte (tenant update, systemd-Agent und kommerzieller Betrieb ungetestet, Lander-Design, Vanity-Registry, GitHub geparkt) und Fachfragen: Spec Abschnitt 9.

Tests werden zuerst als Vorgaben geschrieben, dann implementiert. Zeitabhängige Tests nutzen kurze Intervalle über die Konfigurationsfelder bzw. das injizierbare Client.sleep; mit -race -count=30 auf Stabilität prüfen.

go build -o sultan . && ./sultan server               # Daten in ./suldata (gitignored, enthält Schlüssel!)
go vet ./...
go test -race ./...                                   # alle Tests
go test -run TestFromLabels_Errors ./pkg/traefik      # einzelner Test
go test -cover ./...

Middleware-Optionen werden bewusst als unveränderte Label-Strings in verschachtelten Maps durchgereicht (Traefik parst sie beim Einlesen wie Labels); nur Router- und Service-Felder sind typisiert. Nicht unterstützte Labels (TCP/UDP, unbekannte Attribute) liefern ErrUnsupportedLabel statt still ignoriert zu werden.

Big Picture

Sultan ersetzt manuell gepflegtes Ingress-Routing (z. B. Nginx Proxy Manager): Backends deklarieren ihr Routing selbst (Traefik-Labels an Docker-Containern oder Drop-ins in /etc/sultan.d/*.conf für Bare-Metal/LAMP), ein Agent meldet das an einen zentralen Server, und Traefik auf dem Ingress-Knoten pollt daraus seine Konfiguration.

Single Binary in Go mit drei Subcommands:

• sultan server – Registry, Stream-Hub (hält Agent-Verbindungen im RAM, Dead-Node-Timeout 90s), Policy-Engine, Traefik-HTTP-Provider
• sultan agent – Watcher (Docker Events API auf traefik.*-Labels bzw. inotify auf /etc/sultan.d), State-Serializer (injiziert LAN- oder NetBird-IP 100.64.x.y als Backend-Ziel), Transport mit Reconnect + exponentiellem Backoff
• sultan token – CLI für Schlüssel, Enrollment-Tokens, Lizenzausstellung

Ports / Endpunkte des Servers:

• :8443 (TLS) – Control Plane, ausschließlich ausgehend vom Agent (NAT/CGNAT/DS-Lite-tauglich). Persistenter SSE-Stream (entschieden, siehe pkg/stream), 45s-Keepalive, Events werden sofort gepusht. Enrollment: POST /api/v1/enroll.
• 127.0.0.1:8080 – GET /v1/traefik-config (Traefik pollt alle 2–5s; flache Labels aller aktiven Nodes → verschachteltes Traefik-JSON) und GET /metrics/checkmk (Checkmk Local-Check-Format).

Sicherheitsmodell (Kerninvarianten):

• Server-TLS-Zertifikat self-signed (ECDSA P-256, TLS 1.3), Agent pinnt den SHA256-Fingerprint (aus der Einladung, danach server_fingerprint in node.json) – adressunabhängig, kein blindes TOFU. Kein Agent-Verkehr im Klartext.
• Agent-Keys (Ed25519) werden nur lokal erzeugt und verlassen den Host nie; Enrollment tauscht Public Key + einmaligen Token gegen Mandanten-Zuordnung und signierten Capability-Lease. Danach ist jeder Heartbeat mit node.key signiert.
• Jeder Agent-Payload wird serverseitig gegen die Mandanten-Policy geprüft: Hosts in Host(...)-Regeln müssen in allowed_domains stehen (sonst ablehnen + Audit-Log), Routen über max_routes werden verworfen.
• Lizenzen (license.json) sind mit dem Ed25519-Server-Master-Key signiert.

Stream-Events (JSON: event_id, timestamp, type, node_id, payload): service_state (Agent→Server, vollständiger Label-Snapshot, nicht Delta), node_command (re_enroll/drain/maintenance), lease_renew, error.

Persistenz: SQLite unter <data-dir>/sultan.db (Default-Datenverzeichnis ./suldata, auch beim Agent), Tabellen tenants, nodes, enrollment_tokens (Tokens nur als Hash gespeichert).

Policy/Lizenzablauf: Mandanten-Status steuert das generierte Routing – Zahlungsverzug → Router auf Bezahlseite (402), Backend down/service_down → Statusseite 503 mit Retry-After: 60. Checkmk-Schwellen: WARN bei 30, CRIT bei 14 Tagen Restlaufzeit, bei Ablauf Umleitung auf Landingpage.

Unstimmigkeiten in der Spec

Bisherige Widersprüche sind aufgelöst und im Entscheidungslog der Spec (Abschnitt 8) dokumentiert. Neue Unklarheiten vor der Implementierung mit dem User klären statt raten.