Transporte
Wie eine Anfrage über stdio und über Streamable HTTP zu den Werkzeugen gelangt, welche Routen der HTTP-Server beantwortet und wie Werkzeuge in jedem Modus Dateien lesen und herausgeben. Die Seite richtet sich an Mitwirkende und Reviewer; Betreiber beginnen mit Fernzugriff.
stdio und HTTP
- stdio (Standard): für lokale Clients wie Claude Desktop, Claude Code, Cursor oder VS Code.
- Streamable HTTP (
--http,src/http/): für entfernte Clients wie benutzerdefinierte Connectoren in claude.ai. Der Server ist zum Selbstbetreiben gedacht; eine öffentliche gehostete Instanz gibt es nicht. Die Anleitung für Betreiber ist Fernzugriff (HTTP), die Entscheidungen sind ADR 0006 und ADR 0007.
Zustandsloses MCP, eine Instanz
POST /mcp geht an createMcpHandler(factory, {legacy: "stateless"}) des SDK: Jede Anfrage
bekommt eine frische Server-Instanz aus der Factory, es gibt keine MCP-Sitzung, und GET und DELETE
auf /mcp werden mit 405 beantwortet. Das Protokoll würde jede Instanz jede Anfrage bedienen
lassen, aber der Server unterstützt genau eine: Der Zugangsspeicher (mit einer Sperre auf seinem
Zustandsverzeichnis), ausstehende Freigaben, die Nonces und der Codec-Schlüssel der Bestätigungen
und die Ratenbegrenzungen leben im Prozess. Sie zu teilen bräuchte eine Datenbank, die der Entwurf
vermeidet.
Authentifizierung
Der HTTP-Modus startet nicht ohne sie:
bearer: ein gemeinsames Geheimnis (oder zwei während eines Wechsels), als HMACs in konstanter Zeit verglichen; der Server hält ein sevDesk-Token, es gibt also einen festen Kontokontext.oauth: Der Server ist sein eigener OAuth-2.1-Autorisierungsserver (src/http/oauth/): Clients, die sich über Client ID Metadata Documents (CIMD) aus einer Erlaubnisliste ausweisen, PKCE mit S256, eine genaue Prüfung der Zielgruppe nach RFC 8707,issin der Autorisierungsantwort (RFC 9207), versiegelte Tokens (AES-256-GCM, Schlüssel je Zweck mit HKDF ausSEVDESK_HTTP_SECRETabgeleitet), rotierende Refresh-Tokens mit Erkennung erneuter Vorlage und ein Zugangsspeicher, der keine Tokens hält. Der Benutzer fügt sein sevDesk-Token einmal auf der Zustimmungsseite ein; es reist versiegelt in seinen eigenen Tokens.
Weg einer Anfrage
Jede URL, die der Server ausgibt oder auf die er weiterleitet, wird aus der konfigurierten
öffentlichen Adresse (SEVDESK_HTTP_PUBLIC_URL) gebaut, nie aus Host- oder
X-Forwarded-*-Headern.
- Proxy. TLS endet an einem Reverse Proxy, am Rand einer Plattform oder an einem Tunnel.
SEVDESK_HTTP_TRUST_PROXYsagt, wie viele Einträge vonX-Forwarded-For(von rechts) Proxys hinzugefügt haben; die Client-IP für Ratenbegrenzungen und Logs ist der nächste. - Brücke (
node-bridge.ts,serve.ts): wandelt zwischennode:httpund Web-Request/Responseum, lehnt Bodys über der Grenze der Route mit 413 ab, bevor sie mehr liest (1 MiB an/mcp, 8 KiB an/authorize, 4 KiB an/tokenund/revoke), bricht das Signal der Anfrage ab, wenn der Client die Verbindung trennt, antwortet mit 408, wenn ein Body nicht rechtzeitig ankommt, und streamt Antworten ohne Pufferung, einen großen Block in Stücken von 64 KiB (ein Client, der eine Minute lang kein Stück abnimmt, wird getrennt). Zeitlimits des Servers: 15 s für die Header, 65 s Keep-alive und für eine ganze Anfrage das längste Body-Fenster aller Routen plus 30 s (45 s; 120 s mit der Upload-Seite, deren Body 90 s dauern darf); höchstens 256 Verbindungen. - Härtung (
router.ts,hardening.ts,rate-limit.ts): die Erlaubnisliste fürHost(der Validator des SDK;/healthzist für die Zustandsprüfungen von Plattformen ausgenommen), der Abgleich der Route (404, oder 405 mitAllowfür andere Methoden), Ratenbegrenzungen per Token-Bucket je Client-Adresse (IPv6 je /64; 429 mitRetry-After), Grenzen für gleichzeitige Anfragen (64 insgesamt, 8 je Client-Adresse, 8 je sevDesk-Konto an/mcp, und 8 der 64 bleiben den Routen außer/mcpvorbehalten), eine Frist von 120 s, dieOrigin-Regel der Route (/mcp: der Validator des SDK, der Hostnamen mit den erlaubten Origins vergleicht; es gibt kein CORS, Webseiten auf anderen Origins können/mcpalso nicht aufrufen; HTML-Formulare: nur POSTs vom selben Origin, nieOrigin: null) und Sicherheits-Header an jeder Antwort (nosniff,no-store, no-transform, eine Referrer-Policy, HSTS über https). Eine JSON-Logzeile je Anfrage, geschwärzt (log.ts). - Authentifizierung. Bearer:
bearer.ts. OAuth:requireBearerAuthdes SDK mit unserer Prüfung, die das Access-Token öffnet, Typ, Issuer, Ablauf und Zielgruppe prüft, den Zugang im Speicher nachschlägt (sodass ein Widerruf sofort wirkt), sein Konto und seinen Client gegen die aktuellen Erlaubnislisten prüft und einenVerifiedGrantinAuthInfolegt. Fehlschläge werden mit 401 undWWW-Authenticatebeantwortet (im OAuth-Modus mit Verweis auf die Metadaten der geschützten Ressource). - Kontoauflösung (
src/accounts/resolver.ts): Bearer und stdio haben einen festen Kontext. OAuth bekommt je Konto eine eingefroreneConfigmit den Stufen des Zugangs ∩SEVDESK_ALLOW, ohne lokale Ordner und ohne Öffnen des Browsers, und einen sevDesk-Client, dessen Drosselung alle Kontexte des Kontos teilen. Kontexte werden zwischengespeichert (64, 15 Minuten ohne Nutzung). - Server-Factory (
src/server.ts): registriert die Werkzeuge der Stufen des Kontexts mit dessenConfigund Client. Von hier an läuft ein Aufruf genau wie über stdio (Lebenszyklus eines Werkzeugaufrufs).
Routen
| Route | Was | Zugriff |
|---|---|---|
POST /mcp | MCP (Streamable HTTP, zustandslos) | Bearer-Geheimnis oder OAuth-Access-Token |
GET /healthz | {"status":"ok"}, 503 beim Herunterfahren | offen, keine Host-Prüfung |
GET /.well-known/oauth-protected-resource[/mcp], /.well-known/oauth-authorization-server | OAuth-Metadaten (404 im Bearer-Modus) | offen, CORS * |
GET/POST /authorize | Zustimmungsseite | CSRF-Cookie und -Token, POSTs vom selben Origin |
POST /token, POST /revoke | Austausch von Code und Refresh-Token, Widerruf (RFC 7009) | PKCE, die Tokens selbst |
GET /approvals, GET/POST /approvals/<id> | Freigabe-Postfach (nur mit SEVDESK_CONFIRM=browser) | Sitzungs-Cookie, CSRF-Token, POSTs vom selben Origin |
POST /approvals/login, POST /approvals/logout | Anmeldung im Browser (mit dem Postfach oder der Dateiübertragung) | sevDesk-Token, CSRF-Token, POSTs vom selben Origin |
GET/POST /uploads/<id> | Upload-Seite einer Upload-Anfrage (Dateiübertragung) | Sitzung des Kontos, dem der Eintrag gehört, CSRF-Token |
GET /files/<id> | Download-Link (Dateiübertragung), nur als Anhang | Sitzung des Kontos, dem der Eintrag gehört |
GET /assets/<name> | Schriften und Icon der Seiten (immer, wenn der Server Seiten anzeigt) | offen, mit Ratenbegrenzung, unveränderlich |
Herunterfahren
Bei SIGTERM antwortet /healthz mit 503, laufende Anfragen bekommen 10 Sekunden, dann wird der
Zugangsspeicher geschrieben und seine Sperre freigegeben.
Dateien
Werkzeuge bekommen Dateiinhalte und geben Dateien heraus über einen FileAccess
(src/safety/file-access.ts), den die Registry für jeden Aufruf aus der Konfiguration und dem
Prinzipal der Anfrage baut. Es gibt zwei Umsetzungen (src/safety/file-sources.ts):
- Lokal (stdio und HTTP mit ausgeschalteter Dateiübertragung): liest nur innerhalb von
SEVDESK_FILE_DIRS(src/safety/local-files.ts: echte Pfade, kein Ausbruch über symbolische Links,O_NOFOLLOWplus eine Prüfung der Inode, Erkennung des Typs am Inhalt, Größengrenzen); Auslieferungen sind neue Dateien inSEVDESK_OUTPUT_DIR(src/safety/output-files.ts: exklusives Anlegen, Modus 0600, nie überschreibend). - Entfernt (HTTP mit
SEVDESK_HTTP_FILES, standardmäßig an): Ein Dateiargument darf ein Verweisupload:<id>aussevdesk_upload_requestsein, für den der Mensch die Datei auf einer Seite des Servers hochlädt; Auslieferungen werden zu kurzlebigen Download-Links. Beide Seiten brauchen eine Browser-Sitzung des Kontos, dem der Eintrag gehört (src/http/browser-session.ts, geteilt mit dem Freigabe-Postfach), sodass ein Link, den das Modell weitergibt, keine Berechtigung ist. Die Einträge leben insrc/safety/transfer-store.ts(je Zugang und Konto, mit Grenzen je Konto und insgesamt, und nie wird etwas verdrängt); die Inhalte leben insrc/safety/blob-store.ts, verschlüsselt mit einem Schlüssel, der je Prozess erzeugt wird, im Speicher oder im Zustandsverzeichnis, und nach einem Neustart weg. Die Seiten sindsrc/http/transfer-routes.tsundtransfer-pages.ts. Der Bearer-Modus kann weiterhin lokale Ordner verwenden, undSEVDESK_OUTPUT_DIRhat, wenn gesetzt, Vorrang vor Download-Links.
Das Modell sieht und sendet nie Dateiinhalte, und es kann keinen Text auf die Upload-Seite setzen. Einzelheiten für Betreiber, Grenzen und Laufzeiten stehen unter Dateien über HTTP; die Entscheidungen in ADR 0008. Wie Werkzeuge auf diesem Weg gehalten werden, steht im Sicherheitsmodell.