Modul-Marketplace: Verbindungen und Katalog

Zielbild

Die Modulverwaltung bietet neben installierten Modulen einen Marketplace. Administratoren verbinden dort GitHub oder eine Gitea-/Forgejo-Instanz, wählen ausdrücklich Repositories als Katalogquellen aus und installieren veröffentlichte Modul-Releases per Klick.

OAuth-Verbindung -> Repository auswählen -> Release-Katalog -> Paket prüfen -> Installieren

Verbindungen

OAuth Authorization Code mit state und PKCE (S256).
Tokens bleiben ausschließlich im Backend, werden verschlüsselt gespeichert, nie in API-Antworten aufgenommen und bei jeder Verwendung nur mit minimal notwendigen Leserechten eingesetzt.
Verbindung, Katalogquelle und installierte Module sind getrennte Datensätze. Trennen einer Verbindung entfernt keine installierten Module.
Selbst gehostete Gitea-/Forgejo-Instanzen benötigen eine OAuth-Anwendung auf der jeweiligen Instanz. Callback-URL ist die öffentliche MPM-URL plus /api/v1/marketplace/oauth/<anbieter>/callback.
OAuth-Client-Secrets und Verschlüsselungsschlüssel gehören in die Serverkonfiguration bzw. einen Secret Store, nie in das Frontend oder Repository.

Katalog und Installation

Der Katalog lädt öffentliche Repositories verbundener Forge-Konten. Installiert wird der aktuelle Stand des jeweiligen Standard-Branches.
MPM lädt das vom Forge erzeugte Quellarchiv serverseitig, entfernt den Archiv-Stammordner und erwartet module.json im Repository-Stamm.

Container-Vertrag für Module

Installierbare Module müssen neben module.json eine Compose-Datei und einen App-Service enthalten:

{
  "composeFile": "compose.yml",
  "appService": "app"
}

Der App-Service muss den Manifest-Port im Container bereitstellen (expose, kein ports) und auf 0.0.0.0 lauschen. Datenbanken gehören als weitere Services in dieselbe Compose-Datei. Die Dienste teilen ein privates Compose-Netz; nur der App-Service wird zusätzlich an das MPM-Gateway angeschlossen. Für SQLite kann der App-Service /var/lib/mpm-module als persistenten Speicher unter MPM_MODULE_DATA_DIR verwenden. Datenbankcontainer definieren eigene projektlokale named volumes.

MPM startet/stoppt den gesamten Stack gemeinsam. Beim Entfernen löscht Compose alle App- und Datenbankcontainer samt Projekt-Netzwerk; benannte Datenvolumes bleiben standardmäßig erhalten, damit ein Entfernen der App keine Daten vernichtet. Pakete dürfen keine Host-Ports, Host-Verzeichnisse, externen Docker-Ressourcen, privilegierten Optionen oder Docker-Socket-Mounts anfordern. Die Modulverwaltung benötigt Zugriff auf den Docker-Socket des Hosts; deshalb dürfen nur vertrauenswürdige Administratoren Module installieren.

Vor der Installation prüft MPM Downloadgröße, Archivpfade, Symlinks, Manifest und Modul-ID. Die bestehende ModuleInstaller-Validierung bleibt die letzte Instanz.
Der Browser übermittelt keine Download-URL; MPM erstellt sie aus Anbieter, Besitzer, Repository und Standard-Branch.
Die Installation registriert das Modul. Das Starten bleibt ein separater Lifecycle-Schritt und erfolgt erst nach Bestätigung durch den Administrator.
Verbindungen, Quellrepository, Release-Tag und Prüfsumme werden im Audit-Log erfasst; Secrets und Tokens niemals.

GitHub-Rechte

Für den ersten Verbindungs-Test wird eine GitHub OAuth App mit read:user verwendet. Das erlaubt MPM, das autorisierte Konto anzuzeigen; öffentliche Release-Kataloge können separat unauthentifiziert gelesen werden. Private GitHub-Repositories werden in dieser ersten Phase nicht abgerufen. Dafür soll später eine GitHub App mit Contents: read eingesetzt werden: OAuth Apps bieten für Quellcode keinen reinen Read-only-Scope und der klassische repo-Scope umfasst Schreibzugriff.

Gitea und Forgejo verwenden kompatible Release- und Repository-APIs, aber jede selbst gehostete Instanz bleibt eine eigene OAuth-Konfiguration und eine explizit vertrauenswürdige Quelle.

Umsetzungsschritte

OAuth-Provider-Konfiguration und verschlüsselte Zugangsdaten samt Datenbankmigration.
OAuth-Start/Callback mit zufälligem, einmalig verwendbarem state, Ablaufzeit, PKCE und Bindung an die anmeldende Admin-Session.
Verbindungen anzeigen und trennen; niemals Tokens zurückgeben.
Öffentliche Repositories verbundener Forge-Konten direkt als installierbaren Katalog anzeigen.
Repository-Archive vom Standard-Branch laden und vor dem Installieren sicher normalisieren.
Installation in die bestehende Modulregistrierung integrieren, auditieren und im UI anzeigen. Module starten nach der Installation nicht automatisch.

Aktueller Umfang

Der Marketplace in der Modulverwaltung unterstützt öffentliche Repositories von GitHub, Gitea und Forgejo. Private Repositories, Suche über fremde Katalogserver und Updates installierter Module sind noch nicht enthalten.

Voraussetzungen für den Betrieb

Für die OAuth-Anmeldung müssen je Provider/Instanz Client-ID und Client-Secret in MPM hinterlegt werden. Die öffentliche HTTPS-URL der Plattform muss stabil sein, da sie als OAuth-Callback registriert wird. Vor Aktivierung privater GitHub-Repositories ist die GitHub-App mit Read-only-Berechtigung zu konfigurieren.

5.1 KiB Raw Blame History