OpenCode Self-Service Access

Stand: 2026-05-27

Kurzfazit

OpenCode-Zugaenge werden ueber eine dedizierte browserfaehige Self-Service-Seite vorbereitet. OpenWebUI dient nur als Startpunkt; Tokenwerte duerfen nicht im Chatverlauf, Tool-Trace oder Modellkontext landen.

Gewaehlte Variante:

• OpenWebUI zeigt einen Link oder Button zum Self-Service.
• Die Self-Service-Seite liegt unter https://ai.lanstyle.de/opencode-access.
• Die Seite validiert die bestehende OpenWebUI-Session serverseitig ueber das OpenWebUI-Session-Cookie.
• Die Token-Erzeugung laeuft serverseitig ueber die Tools API.
• Neue Secrets werden nur einmalig als opencode.env oder ZIP ausgeliefert.
• Danach sind nur Status, Fingerprint, Erstellzeit und Ablauf sichtbar.

Nicht gewaehlt:

• kein OpenWebUI-LLM-Tool, das Tokenwerte im Chat ausgibt
• kein OAuth-Browserflow fuer Remote MCP
• keine Admin-Keys fuer normale Benutzer
• keine direkten 10.x-Ziele in OpenCode-Clientconfigs

Architektur

flowchart LR
  user["OpenWebUI Benutzer"] --> owui["OpenWebUI"]
  owui --> link["Button: OpenCode Zugriff"]
  link --> page["Browser Self-Service Seite"]
  page --> session["OpenWebUI Session Check"]
  session --> api["Lanstyle OpenCode Access API"]
  api --> rbac["RBAC / Policy"]
  api --> litellm["LiteLLM /key/generate"]
  api --> mcp["MCP Token Store"]
  api --> vw["Vaultwarden Source of Truth"]
  api --> delivery["One-Time Delivery"]
  api --> audit["Audit Log"]
  delivery --> env["opencode.env / ZIP"]

API

Endpoint	Zweck	Secrets in Response
GET /opencode-access/policy	Self-Service-Policy anzeigen	nein
GET /opencode-access/status	eigene Access-Records als Metadaten/Fingerprints	nein
POST /opencode-access/request	neuen Zugang erzeugen	nein, nur Delivery-ID
POST /opencode-access/download	Browser-only One-Time-Download	ja, nur in dieser Download-Antwort
POST /opencode-access/rotate	alten Zugang sperren, neuen erzeugen	nein, nur Delivery-ID
POST /opencode-access/revoke	Zugang sperren	nein

Der Download-Endpunkt wird absichtlich nicht in der OpenAPI-Toolbeschreibung veroeffentlicht. OpenWebUI/LLM-Tools duerfen den Secret-Download nicht selbst ausloesen, damit Tokenwerte nicht im Chatverlauf, Tool-Trace oder Modellkontext landen. Der Browser-Download ist POST-only, CSRF-geschuetzt und verwendet keine delivery_id in der URL. Ein OpenWebUI-Flow darf nur auf die Self-Service-Seite verlinken; die Ausgabe erfolgt ueber einen dedizierten One-Time-Download.

Die API gehoert zur Action-Klasse access_management. Normale Operatoren duerfen eigene OpenCode-Zugaenge erzeugen, aber keine scoped_write- oder destructive_execute-Rechte erhalten.

Token Scope

LiteLLM Virtual Key fuer Operatoren:

• erlaubt: lanstyle/agent-stable
• erlaubt: lanstyle/fast
• erlaubt: lanstyle/architect
• erlaubt: lanstyle/embed
• nicht erlaubt: lanstyle/agent
• nicht erlaubt: entfernt

MCP Token fuer Operatoren:

• read-only
• plan-only
• approval-preview
• keine echten Writes
• keine destruktiven Aktionen

One-Time Delivery

Der Request liefert keine Tokenwerte, sondern nur:

• access_id
• token_name
• expires_at
• Fingerprints
• delivery_id
• einmalige Download-URL

Der Download ist zeitlich begrenzt. Nach erfolgreichem Abruf wird das Artefakt serverseitig entfernt. Bei Verlust wird rotiert, nicht erneut angezeigt.

OpenWebUI Integration

Sicherste produktive Variante:

1. OpenWebUI zeigt einen nativen Banner OpenCode Zugriff.
2. Der Benutzer oeffnet https://ai.lanstyle.de/opencode-access.
3. Die Seite prueft die OpenWebUI-Session serverseitig und leitet daraus Benutzeridentitaet und Rolle ab.
4. Tokenwerte werden als Datei ausgeliefert, nicht in Chatnachrichten.
5. OpenWebUI-Chat zeigt keine Secretwerte und keine Downloadlinks.

Umgesetzte OpenWebUI-Variante:

• Native Banner-Konfiguration ui.banners
• Banner-ID: lanstyle-opencode-access
• Markdown-Link als klare Klickzeile: Hier klicken: [OpenCode Zugriff öffnen](/opencode-access)
• Keine Function/Action und kein Chat-Tool fuer Secret Delivery
• Keine statische UI-Datei gepatcht
• Keine NPM Access List erweitert

NPM-Routing:

• ai.lanstyle.de bleibt auf Open WebUI 10.222.70.10:8080.
• Nur die Custom Location /opencode-access wird auf die Tools API 10.222.70.20:3010 geroutet.
• Die bestehende NPM Access List des Proxy Hosts bleibt unveraendert.
• Die Self-Service-Seite fuehrt danach zusaetzlich den OpenWebUI-Session-Check aus.

Warum kein Chat-Tool fuer Secret-Ausgabe:

• Chatverlaeufe koennen gespeichert, exportiert oder im Kontext an Modelle weitergegeben werden.
• Tokenwerte duerfen nur einmalig und bewusst als Datei ausgeliefert werden.
• OpenWebUI API Keys erben die Rechte des jeweiligen Benutzers; normale User duerfen dadurch nicht indirekt Admin-Rechte erhalten.

User Flow

1. Benutzer oeffnet OpenWebUI.
2. Benutzer klickt OpenCode Zugriff erstellen.
3. Benutzer waehlt Geraet, z. B. macbook-pro oder windows-workstation.
4. Benutzer bestaetigt Security-Hinweise.
5. Backend erzeugt LiteLLM- und MCP-Token mit Operator-Scope.
6. Benutzer laedt das ZIP einmalig herunter.
7. Das Self-Service-ZIP enthaelt opencode.env, opencode.operator.jsonc, install-macos.sh, install-windows.ps1, FIRST-TEST-PROMPT.md und README-ONE-TIME.md.
8. Benutzer fuehrt je nach Betriebssystem den Installer aus:
9. macOS: bash install-macos.sh
10. Windows: PowerShell -ExecutionPolicy Bypass -File .\install-windows.ps1
11. Der Installer sichert vorhandene lokale OpenCode-Dateien, legt Secrets und OpenCode-Konfiguration lokal ab und setzt die benoetigten Umgebungsvariablen.
12. Benutzer startet OpenCode neu und fuehrt den First-Test-Prompt aus.

Die Self-Service-Seite zeigt nach dem Download eine kurze macOS- und Windows-Anleitung direkt im Browser an. Die Anleitung verweist nur auf lokale Dateien aus dem ZIP und enthaelt keine Tokenwerte.

opencode.operator.jsonc ist eine JSON-Konfigurationsdatei mit Kommentaren. Sie sagt OpenCode, dass LiteLLM unter https://litellm.lanstyle.de/v1 und Remote MCP unter https://mcphub.lanstyle.de/lanstyle-mcp genutzt werden. Der Installer kopiert sie als opencode.jsonc in das lokale OpenCode-Konfigurationsverzeichnis.

Admin Flow

Administratoren sehen keine Tokenwerte, sondern:

• Benutzer/Geraet
• Fingerprint
• Erstellzeit
• Ablaufzeit
• Status: pending_delivery, active, revoked, expired
• Audit-Referenz

Admin-Aktionen:

• Zugang sperren
• Zugang rotieren
• Ablauf verlaengern ueber neuen Request
• Audit pruefen

Security Controls

• Authentifizierter Benutzer erforderlich
• OpenWebUI-Session-Cookie wird serverseitig gegen OpenWebUI validiert
• RBAC erforderlich
• Rate Limit pro Benutzer
• Ablaufdatum standardmaessig 30 Tage
• One-time Download mit kurzer TTL
• Download nur per POST, keine Secrets oder Delivery-IDs in URL-Query-Strings
• CSRF-/Origin-Pruefung fuer Browser-POSTs
• Origin-Pruefung normalisiert Default-Ports, damit https://ai.lanstyle.de und https://ai.lanstyle.de:443 gleich behandelt werden.
• Browser-Origin null wird wie ein nicht verwertbarer Origin behandelt; der Schutz laeuft dann weiterhin ueber CSRF, SameSite/HttpOnly-Cookie und serverseitige OpenWebUI-Sessionvalidierung. Echte Fremd-Origins bleiben blockiert.
• Wenn OpenWebUI keinen Session-Cookie setzt, nutzt die Self-Service-Seite einen Browser-Session-Bridge-Flow: Der OpenWebUI-Token wird clientseitig aus dem Browser Storage gelesen, serverseitig gegen OpenWebUI validiert und danach als kurzlebiger, HttpOnly, Secure, SameSite-Cookie nur fuer /opencode-access gesetzt. Tokenwerte werden dabei nicht in URL, Chat oder OpenAPI-Toolausgaben geschrieben.
• Cache-Control: no-store, Pragma: no-cache, Referrer-Policy: no-referrer
• Status ohne Secretwerte
• Audit ohne Secretwerte
• MCP Server liest dynamische Tokens aus root-only Store
• bestehende Legacy-/Bootstrap-Tokens bleiben unveraendert
• Revocation deaktiviert MCP-Token und entfernt serverseitige Secret-Kopie

Betriebsstatus

Stand 2026-05-27: Der Codepfad ist produktiv auf der Agent Runtime ausgerollt und per NPM Custom Location unter https://ai.lanstyle.de/opencode-access angebunden.

Live geprueft:

• /opencode-access/policy liefert HTTP 200.
• /opencode-access/status liefert HTTP 200 fuer authentifizierte Tools-API-Clients.
• Geschuetzte Tools-API-Endpunkte liefern ohne Bearer Token HTTP 401.
• Die Browser-Seite liefert ohne gueltige OpenWebUI-Session HTTP 401 als HTML-Seite.
• Interne Testquellen ausserhalb der bestehenden NPM Access List erhalten auf https://ai.lanstyle.de/opencode-access HTTP 403; das ist erwartetes NPM-Access-List-Verhalten.
• Die NPM Custom Location /opencode-access zeigt auf 10.222.70.20:3010; Hauptbackend, Zertifikat und Access List von ai.lanstyle.de blieben unveraendert.
• OpenWebUI-Banner OpenCode Zugriff ist in ui.banners gesetzt und enthaelt keine Secretwerte.
• OpenWebUI nutzt den vorhandenen Toolserver-Bearer; die serverseitige Legacy-Rolle ist auf operator begrenzt.
• Testzugang wurde erzeugt, einmalig heruntergeladen, mit LiteLLM und MCP validiert und danach widerrufen.
• Zweiter Download derselben Delivery wurde blockiert.
• lanstyle/agent und entfernt sind fuer normale Self-Service-Operator-Keys nicht sichtbar.
• Remote MCP initialize, tools/list, ein read-only Tool Call und ein Preflight Tool Call wurden mit dem erzeugten Testtoken validiert.
• Nach Revocation liefern LiteLLM und MCP fuer den Testzugang HTTP 401.
• Rollout-Testrecords sind revoked; es gibt keine aktiven Rollout-Testtokens.

Live-Erzeugung von LiteLLM Virtual Keys ist fail-closed, wenn kein serverseitiger LiteLLM Admin-Key fuer die Tools API konfiguriert ist. Die Tools API nutzt fuer die interne LiteLLM-Key-Erzeugung den Compose-internen Pfad http://litellm:4000, nicht den oeffentlichen NPM-Pfad.

Vor produktiver Aktivierung pruefen:

• LANSTYLE_LITELLM_ADMIN_KEY oder LITELLM_MASTER_KEY ist nur serverseitig gesetzt.
• LANSTYLE_TOOLS_API_TOKEN ist serverseitig gesetzt und entspricht dem OpenWebUI-Toolserver-Bearer.
• LANSTYLE_RBAC_LEGACY_ROLE=operator, damit OpenWebUI keine Write-/Destructive-Rechte ueber den Legacy-Token bekommt.
• LANSTYLE_MCPHUB_TOKEN_STORE_FILE zeigt auf den gemeinsamen root-only Store.
• Vaultwarden-Workflow fuer die erzeugten Secrets ist aktiv.
• OpenWebUI startet nur Link/Status, keine Secret-Ausgabe im Chat.

Tests

Minimaltests:

• GET /opencode-access/policy
• GET /opencode-access/status
• POST /opencode-access/request
• einmaliger Download
• OpenAPI-Spec enthaelt keinen opencode_access_onboarding_package Tool-Eintrag
• zweiter Download muss blockieren
• POST /opencode-access/revoke
• Remote MCP mit gueltigem Token
• Remote MCP mit widerrufenem Token muss 401 liefern

Quellen

• OpenWebUI API Keys erben Benutzerrechte und sind nach Erstellung nicht erneut sichtbar: Open WebUI API Keys
• OpenWebUI Functions erweitern tiefer die UI/Message-Verarbeitung und sind deshalb fuer Secret-Ausgabe nicht der bevorzugte Pfad: Open WebUI Functions