Sucukdeluxe c8beaf96ed Ferndiagnose (MCP): Verbindungscode + abgesicherter Fernzugriff + stdio-Bridge

Neue Funktion, um Diagnose eines laufenden Servers aus der Ferne zu ermoeglichen:
Hilfe -> Remote-Support -> "Ferndiagnose (MCP)". Erzeugt einen Verbindungscode,
den der Assistent nutzt, um Status, Logs, Fehler und Accounts read-only zu lesen.

App-Seite:
- Live (re)startbarer Debug-Server ohne App-Neustart (restartDebugServer wartet auf
  'close' + closeAllConnections, behandelt EADDRINUSE).
- IP-Allowlist (debug_allowlist.txt, exakte IP + CIDR), erzwungen VOR der Auth.
  Fail-closed: Netzwerk-Bind (0.0.0.0) ohne Allowlist akzeptiert nur Loopback.
- One-Click Aktivieren/Aktualisieren/Deaktivieren + Token-Rotation (alter Code sofort
  ungueltig). Sichtbarkeit waehlbar: "Nur lokal" (Tunnel-Empfehlung) vs "Im Netzwerk".
- Verbindungscode rddiag:v1:base64url({v,h,p,t,n?,fp?,s?}); oeffentlicher Host frei
  waehlbar, Netzwerk-IPs als Schnellauswahl.
- Neue IPC: get/enable/disable/rotate Remote-Diagnostics; Controller-Methoden; Typen.

Bridge (tools/rd-diagnostics-mcp, standalone, KEINE App-Dependency):
- stdio MCP-Server (@modelcontextprotocol/sdk) mit 14 Tools, proxyt die bestehende
  HTTP-Debug-API. Multi-Server ueber code/server/RDDIAG_CODE/RDDIAG_SERVERS.
- TLS-Fingerprint-Pinning auf secureConnect (vor Token-Versand), falls https genutzt.
- test/harness.mjs: faehrt einen Fake-Debug-Server hoch und treibt die Bridge als
  echten stdio-Child per JSON-RPC -> voller Protokollpfad gruen.

Sicherheit (Audit): keine persistenten Secrets in den Logs der Debug-API (Passwoerter
redigiert, keine Debrid-Keys/aufgeloesten Download-URLs geloggt; settings/accounts
redigiert). Empfohlener Transport: Loopback + privater Tunnel; Direkt-Bind nur mit
Allowlist in vertrauenswuerdigen Netzen.

Tests: connection-code-Cross-Check (App-Encoder <-> Bridge-Decoder), Allowlist-Matrix
(Loopback, exakt, CIDR, fail-closed, Live-Restart). Volle Suite 905 gruen, tsc=6.

2026-06-19 17:05:28 +02:00

2.9 KiB

Raw Blame History

rd-diagnostics-mcp

Standalone stdio MCP bridge to the Real-Debrid-Downloader debug-server. It runs on the machine where the AI assistant (Claude Code) runs, takes a connection code for a downloader server, and exposes that server's read-only HTTP diagnostics API (/diagnostics, /status, /errors, /logs/*, /accounts, …) as MCP tools. One bridge serves all 5–6 servers; you pass a code (or a configured server name) per call.

This bridge is not bundled into the Electron app and adds no dependencies to it.

Setup

cd tools/rd-diagnostics-mcp
npm install

claude mcp add rd-diag -- node "<repo>/tools/rd-diagnostics-mcp/src/bridge.mjs"

Provide servers via environment variables (codes contain a token — treat like passwords):

RDDIAG_CODE — a single default connection code (rddiag:v1:...)
RDDIAG_SERVERS — JSON map of name → code, e.g. {"berlin":"rddiag:v1:...","fra":"rddiag:v1:..."}

Without env config, every tool simply takes a code argument.

Tools

rd_servers, rd_ping, rd_diagnostics, rd_status, rd_items, rd_packages, rd_errors, rd_logs, rd_history, rd_accounts, rd_host, rd_self_check, rd_get (raw escape-hatch, any read-only path).

Each tool accepts code or server to pick the target.

Connection code

Format: rddiag:v1:<base64url(JSON)> with { v:1, h:host, p:port, t:token, n?:name, fp?:certFingerprint, s?:scheme }. Generated by the app (Hilfe → Remote-Support → Ferndiagnose (MCP)) or via node src/gen-code.mjs --host H --port P --token T.

Security model (read before exposing a server)

The debug surface is read-only for state/logs; the one control endpoint is /trace/config (toggles the optional, time-bounded support trace). No persistent secrets are written into the logs it serves: passwords are redacted, debrid API keys/tokens and resolved download URLs are never logged; /settings and /accounts are redacted.
Auth is a bearer token (24 random bytes). Over plain HTTP on a public network the token is sniffable, so:
- Preferred: keep the server bound to 127.0.0.1 ("Nur lokal") and reach it through a private tunnel (Tailscale / SSH / Cloudflare Tunnel). The tunnel encrypts and authenticates; no public exposure.
- Direct network bind (0.0.0.0) requires a non-empty IP allowlist (enforced fail-closed: with an empty allowlist only loopback is accepted). Use only inside a trusted LAN/VPN.
Revoke instantly from the app ("Token neu" or "Deaktivieren") — the old code stops working immediately.
fp pins a self-signed cert fingerprint and is verified on secureConnect (before the token is sent). HTTPS is not the v1 default; plain HTTP behind a tunnel is the recommended transport.

Test

npm test    # spins a fake debug-server, runs the bridge as a stdio child, asserts the full protocol path

2.9 KiB Raw Blame History Unescape Escape