From 0abe7b7abc15f3df5b8ba8cc47b9b45a2f302f59 Mon Sep 17 00:00:00 2001 From: MPM Dev Date: Wed, 7 Oct 2026 16:19:20 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20Phase=206=20=E2=80=93=20Modul-API-Vertr?= =?UTF-8?q?ag=20mit=20platform-module-sdk?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 5 +- apps/platform-backend/jest.config.js | 2 +- .../src/users/users.module.ts | 2 + .../test/platform-module-sdk.spec.ts | 106 ++++++++++++++++++ docs/PHASES.md | 22 +++- modules/demo/backend/platform-module-sdk.js | 100 +++++++++++++++++ modules/demo/backend/server.js | 42 +++++-- modules/demo/demo-module.zip | Bin 1029 -> 2766 bytes 8 files changed, 261 insertions(+), 18 deletions(-) create mode 100644 apps/platform-backend/test/platform-module-sdk.spec.ts create mode 100644 modules/demo/backend/platform-module-sdk.js diff --git a/README.md b/README.md index ad37f84..5f69e1d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Zentrale, webbasierte Management-Plattform, über die eigenständige Web-Applikationen als **Module** integriert, verwaltet und Benutzern zugewiesen werden können. -**Status: Phase 5 – Berechtigungssystem (abgeschlossen)** +**Status: Phase 6 – Modul-API (abgeschlossen)** ## Architektur-Überblick @@ -106,6 +106,9 @@ Dynamisches Routing `/slug` über Nginx → Modul-Gateway (Middleware): Session- ### Phase 5 – Berechtigungssystem Zweistufiges Rechtekonzept: Plattform-Rollen (ADMIN/USER) + Modul-Berechtigungen (`user_module_permissions`, GRANTED/DENIED). Admin-API für Zuweisungen, Gateway prüft Berechtigungen fail-closed, Dashboard zeigt nur freigegebene Module als Kacheln. +### Phase 6 – Modul-API & SDK +Verbindlicher Modul-API-Vertrag (`/health`, `/api/manifest`, `/api/me`) mit `platform-module-sdk`: Module erhalten die Benutzer-Identität sicher über Gateway-Header (Session-Cookie wird nie weitergereicht). Demo-Modul als Referenzimplementierung. + ## Annahme „ChatCM" wurde als **shadcn-artige Komponentenbasis** interpretiert: Tailwind CSS plus zentral gepflegte, wiederverwendbare UI-Komponenten (`apps/platform-frontend/src/components/ui`). \ No newline at end of file diff --git a/apps/platform-backend/jest.config.js b/apps/platform-backend/jest.config.js index 59c57da..0d6cc32 100644 --- a/apps/platform-backend/jest.config.js +++ b/apps/platform-backend/jest.config.js @@ -2,7 +2,7 @@ module.exports = { preset: 'ts-jest', testEnvironment: 'node', - roots: ['/src'], + roots: ['/src', '/test'], testRegex: '.*\\.spec\\.ts$', moduleFileExtensions: ['ts', 'js', 'json'], collectCoverageFrom: ['src/**/*.ts', '!src/main.ts', '!src/**/*.module.ts'], diff --git a/apps/platform-backend/src/users/users.module.ts b/apps/platform-backend/src/users/users.module.ts index 29ea6e7..9178db1 100644 --- a/apps/platform-backend/src/users/users.module.ts +++ b/apps/platform-backend/src/users/users.module.ts @@ -3,6 +3,7 @@ import { ConfigModule } from '../config/config.module'; import { DatabaseModule } from '../database/database.module'; import { AuditModule } from '../audit/audit.module'; import { SessionService } from '../auth/session.service'; +import { ModulePermissionRepository } from '../modules/module-permission.repository'; import { ModulePermissionsService } from '../modules/module-permissions.service'; import { ModuleRepository } from '../modules/module.repository'; import { PasswordHasher } from './password-hasher'; @@ -25,6 +26,7 @@ import { UsersService } from './users.service'; ProfileService, SessionService, ModuleRepository, + ModulePermissionRepository, ModulePermissionsService, ], exports: [UserRepository, PasswordHasher], diff --git a/apps/platform-backend/test/platform-module-sdk.spec.ts b/apps/platform-backend/test/platform-module-sdk.spec.ts new file mode 100644 index 0000000..4b7d1cb --- /dev/null +++ b/apps/platform-backend/test/platform-module-sdk.spec.ts @@ -0,0 +1,106 @@ +/** + * SDK-Tests (Phase 6): Vertrags-Helper des Modul-SDKs. + * Das SDK ist CommonJS und wird direkt mit Node getestet. + */ +const { + GATEWAY_HEADERS, + extractIdentity, + healthResponse, + meResponse, +} = require('../../../modules/demo/backend/platform-module-sdk'); + +describe('platform-module-sdk', () => { + describe('extractIdentity', () => { + it('extrahiert die Identität aus korrekten Gateway-Headern', () => { + const identity = extractIdentity({ + [GATEWAY_HEADERS.userId]: 'user-123', + [GATEWAY_HEADERS.username]: 'max', + [GATEWAY_HEADERS.displayName]: 'Max Mustermann', + [GATEWAY_HEADERS.role]: 'USER', + }); + + expect(identity).toEqual({ + userId: 'user-123', + username: 'max', + displayName: 'Max Mustermann', + role: 'USER', + }); + }); + + it('ist case-insensitive bei Header-Namen', () => { + const identity = extractIdentity({ + 'X-User-Id': 'user-123', + 'X-User-Username': 'max', + 'X-User-Role': 'ADMIN', + }); + + expect(identity).not.toBeNull(); + expect(identity?.role).toBe('ADMIN'); + }); + + it('gibt null zurück, wenn Header fehlen (kein Gateway-Request)', () => { + expect(extractIdentity({})).toBeNull(); + expect(extractIdentity({ 'x-user-id': 'user-123' })).toBeNull(); + }); + + it('gibt null bei ungültiger Rolle zurück', () => { + const identity = extractIdentity({ + [GATEWAY_HEADERS.userId]: 'user-123', + [GATEWAY_HEADERS.username]: 'max', + [GATEWAY_HEADERS.role]: 'SUPERADMIN', + }); + expect(identity).toBeNull(); + }); + + it('verwendet den Benutzernamen als Fallback für den Anzeigenamen', () => { + const identity = extractIdentity({ + [GATEWAY_HEADERS.userId]: 'user-123', + [GATEWAY_HEADERS.username]: 'max', + [GATEWAY_HEADERS.role]: 'USER', + }); + expect(identity?.displayName).toBe('max'); + }); + }); + + describe('healthResponse', () => { + it('erzeugt eine vertragskonforme /health-Antwort', () => { + expect(healthResponse('demo', '1.0.0')).toEqual({ + moduleId: 'demo', + version: '1.0.0', + status: 'healthy', + }); + }); + }); + + describe('meResponse', () => { + it('erzeugt eine vertragskonforme /api/me-Antwort', () => { + const identity = { + userId: 'user-123', + username: 'max', + displayName: 'Max Mustermann', + role: 'USER' as const, + }; + + expect(meResponse(identity, 'demo', ['demo.read'])).toEqual({ + user: { + id: 'user-123', + username: 'max', + displayName: 'Max Mustermann', + platformRole: 'USER', + }, + module: { id: 'demo' }, + permissions: ['demo.read'], + }); + }); + + it('verwendet leere Permissions als Default', () => { + const identity = { + userId: 'user-123', + username: 'max', + displayName: 'Max', + role: 'ADMIN' as const, + }; + expect(meResponse(identity, 'demo').permissions).toEqual([]); + }); + }); +}); \ No newline at end of file diff --git a/docs/PHASES.md b/docs/PHASES.md index d6e715d..7431585 100644 --- a/docs/PHASES.md +++ b/docs/PHASES.md @@ -9,7 +9,7 @@ Der Arbeitsplan sieht zehn inkrementelle Phasen vor. Nach jeder Phase muss das S | 3 | Modul-System (Manifest, Installation, Lifecycle) | ✅ Abgeschlossen | | 4 | Gateway & dynamisches Routing (`/slug`) | ✅ Abgeschlossen | | 5 | Berechtigungssystem (User ↔ Module) | ✅ Abgeschlossen | -| 6 | Modul-API (`/health`, `/api/manifest`, `/api/me`) | ⏳ Geplant | +| 6 | Modul-API (`/health`, `/api/manifest`, `/api/me`) | ✅ Abgeschlossen | | 7 | Referenzmodul Kalender | ⏳ Geplant | | 8 | Modul-SDK (`platform-module-sdk`) | ⏳ Geplant | | 9 | Administration (Übersichten, Audit-UI, Einstellungen) | ⏳ Geplant | @@ -94,8 +94,20 @@ Definition of Done: User ↔ Module-Zuweisung, Access Control, Permission Middle - [x] Backend-Tests: 90 bestanden (inkl. ModulePermissionsService, Gateway GRANTED-Fall) - [x] Testszenarien aus Arbeitsplan abgedeckt: Admin → alle Module; User ohne Berechtigung → 403; User mit GRANTED → Proxy weitergeleitet -## Nächste Schritte (Phase 6 – Modul-API) +## Phase 6 – Modul-API (abgeschlossen) -- `GET /health`, `GET /api/manifest`, `GET /api/me` als verbindlicher Modul-Vertrag -- Zentrale Authentifizierung zwischen Plattform und Modul (Identitäts-Header validieren) -- Referenzmodul um den vollständigen API-Vertrag erweitern \ No newline at end of file +Definition of Done: `GET /health`, `GET /api/manifest`, `GET /api/me` plus zentrale Authentifizierung zwischen Plattform und Modul. + +- [x] Verbindlicher Modul-API-Vertrag definiert (health, manifest, me) +- [x] `platform-module-sdk` (CommonJS): `extractIdentity` (Gateway-Header, case-insensitive, Rollen-Validierung), `healthResponse`, `meResponse` +- [x] Identitätsübergabe über interne Header (`x-user-id`, `x-user-username`, `x-user-display-name`, `x-user-role`); Session-Cookie wird nie an Module weitergereicht +- [x] Demo-Modul als Referenzimplementierung des Vertrags +- [x] Backend-Tests: 98 bestanden (inkl. 8 SDK-Tests) +- [x] E2E verifiziert: `/demo/health` → vertragskonform, `/demo/api/manifest` → Manifest, `/demo/api/me` → Identität vom Gateway (admin/ADMIN, Permissions); direkter Aufruf ohne Identität → 401; ohne Login → 401 vom Gateway + +## Nächste Schritte (Phase 7 – Referenzmodul Kalender) + +- Vollständiges Kalender-Modul (Dashboard, Kalender, Termine, Teilnehmer, Einstellungen) +- Eigenes PostgreSQL-Schema (`calendar.*`) mit Migrationen +- Frontend mit eigener Oberfläche, integriert in das Plattform-Design +- Dient als Referenzimplementierung für zukünftige Module \ No newline at end of file diff --git a/modules/demo/backend/platform-module-sdk.js b/modules/demo/backend/platform-module-sdk.js new file mode 100644 index 0000000..b55e7a0 --- /dev/null +++ b/modules/demo/backend/platform-module-sdk.js @@ -0,0 +1,100 @@ +/** + * MPM Modul-SDK – Authentifizierungs-Helper (Phase 6). + * CommonJS-Variante (Module laufen als Node-CommonJS-Prozesse). + * + * Jedes Modul läuft hinter dem Modul-Gateway der Management-Plattform. + * Der Gateway authentifiziert den Benutzer zentral und übergibt die + * Identität über interne Header. Module dürfen diese Header NIE + * direkt von außen akzeptieren – deshalb stellt dieses SDK sicher, + * dass die Identität nur aus dem Gateway-Flow stammt. + * + * Sicherheitsregeln: + * - Module lauschen nur auf 127.0.0.1 (nie öffentlich erreichbar) + * - Der Gateway entfernt das Session-Cookie vor dem Proxy + * - Identitäts-Header werden vom Gateway gesetzt, nicht vom Client + */ + +/** Identitäts-Header, die der Modul-Gateway setzt. */ +const GATEWAY_HEADERS = { + userId: 'x-user-id', + username: 'x-user-username', + displayName: 'x-user-display-name', + role: 'x-user-role', +}; + +/** Vom Gateway übergebene Benutzer-Identität. */ +// interface GatewayIdentity { +// userId: string; +// username: string; +// displayName: string; +// role: 'ADMIN' | 'USER'; +// } + +/** + * Extrahiert die Benutzer-Identität aus den Gateway-Headern. + * @returns Identität oder null, wenn der Request nicht über den + * Gateway kam (z. B. direkter Aufruf ohne Plattform). + */ +function extractIdentity(headers) { + const userId = readHeader(headers, GATEWAY_HEADERS.userId); + const username = readHeader(headers, GATEWAY_HEADERS.username); + const displayName = readHeader(headers, GATEWAY_HEADERS.displayName); + const role = readHeader(headers, GATEWAY_HEADERS.role); + + if (!userId || !username || !role) { + return null; + } + if (role !== 'ADMIN' && role !== 'USER') { + return null; + } + + return { userId, username, displayName: displayName ?? username, role }; +} + +/** Liest einen Header (case-insensitive, erster Wert). */ +function readHeader(headers, name) { + const lowerName = name.toLowerCase(); + for (const [key, value] of Object.entries(headers)) { + if (key.toLowerCase() === lowerName) { + if (Array.isArray(value)) { + return value[0] ?? null; + } + return value ?? null; + } + } + return null; +} + +/** + * Standard-Antworten des Modul-API-Vertrags (Phase 6): + * Jedes Modul muss diese drei Endpunkte bereitstellen: + * GET /health → Liveness/Readiness + * GET /api/manifest → Manifest zur Laufzeit + * GET /api/me → Aktueller Benutzer (vom Gateway übergeben) + */ + +/** Erstellt die /health-Antwort nach Vertrag. */ +function healthResponse(moduleId, version) { + return { moduleId, version, status: 'healthy' }; +} + +/** Erstellt die /api/me-Antwort nach Vertrag. */ +function meResponse(identity, moduleId, permissions = []) { + return { + user: { + id: identity.userId, + username: identity.username, + displayName: identity.displayName, + platformRole: identity.role, + }, + module: { id: moduleId }, + permissions, + }; +} + +module.exports = { + GATEWAY_HEADERS, + extractIdentity, + healthResponse, + meResponse, +}; \ No newline at end of file diff --git a/modules/demo/backend/server.js b/modules/demo/backend/server.js index 82ccd77..f5067d9 100644 --- a/modules/demo/backend/server.js +++ b/modules/demo/backend/server.js @@ -1,9 +1,22 @@ /** - * Demo-Modul: Minimaler HTTP-Server, der den Modul-API-Vertrag erfüllt. + * Demo-Modul: Referenzimplementierung des Modul-API-Vertrags (Phase 6). * Läuft als eigener Node-Prozess im Management-Container (Port via ENV PORT). + * + * Vertrag (verbindlich für alle Module): + * GET /health → Liveness/Readiness + * GET /api/manifest → Manifest zur Laufzeit + * GET /api/me → Aktueller Benutzer (vom Gateway übergeben) + * + * Die Identität stammt ausschließlich aus den Gateway-Headern + * (siehe platform-module-sdk.js) – niemals aus der URL oder dem Body. */ const http = require('node:http'); +const { + extractIdentity, + healthResponse, + meResponse, +} = require('./platform-module-sdk'); const PORT = Number(process.env.PORT ?? 41001); @@ -19,7 +32,7 @@ const server = http.createServer((request, response) => { if (url.pathname === '/health') { response.writeHead(200, { 'Content-Type': 'application/json' }); - response.end(JSON.stringify({ moduleId: 'demo', version: '1.0.0', status: 'healthy' })); + response.end(JSON.stringify(healthResponse(MANIFEST.moduleId, MANIFEST.version))); return; } @@ -30,19 +43,26 @@ const server = http.createServer((request, response) => { } if (url.pathname === '/api/me') { + const identity = extractIdentity(request.headers); + if (!identity) { + // Request kam nicht über den Modul-Gateway → keine Identität. + response.writeHead(401, { 'Content-Type': 'application/json' }); + response.end(JSON.stringify({ statusCode: 401, message: 'Keine Identität übergeben' })); + return; + } response.writeHead(200, { 'Content-Type': 'application/json' }); - response.end( - JSON.stringify({ - user: { id: 'demo', username: 'demo' }, - module: { id: 'demo' }, - permissions: [], - }), - ); + response.end(JSON.stringify(meResponse(identity, MANIFEST.moduleId, ['demo.read']))); return; } - response.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' }); - response.end('Demo-Modul läuft'); + if (url.pathname === '/') { + response.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' }); + response.end('Demo-Modul läuft'); + return; + } + + response.writeHead(404, { 'Content-Type': 'application/json' }); + response.end(JSON.stringify({ statusCode: 404, message: 'Nicht gefunden' })); }); server.listen(PORT, '127.0.0.1', () => { diff --git a/modules/demo/demo-module.zip b/modules/demo/demo-module.zip index 123e415cccef01b47398897054dd69a8725f7a42..ee2ec8863f0675cf552acc641cb1593896dfaac8 100644 GIT binary patch delta 2575 zcmaKuX*3jU8^^~oOqL{~Y-JE)?7LL%>JVL^Ro(AMTm%)9^q00hv&7`u5m zF}CkB0|3$-0D#DG_a@xa4;g@P4Mf3jd)*55hxp$@grbm;5QLxHUm>Xuy#a#ir&?L^*g$!=bumYsGrwdUR_&TZM(uD$EslRUUui9^!^U+;%%?XZfg`NF(oA2(Lc&G?TaH_!5QD*B*TyGO$-x=gv+DQ%6BEv{SLxXf6r__!vqpiM=0V}rMN z{<{LYIH@8h^^-X8dRlHX?C7CJOQE%_>21RmGD{|S*z7yAXOKsFR4KIxB)W;?Zr-13 znv^&oVQTYq)Q=48^Bzlcz-x`gCg8;UH?g9j&q^?jIek)H;LwVq@d^2m ziI)Oma^2sA%?67Mo%w(~1qQE)te7wgiS&$Jidw~lB- zX-LB}A&P^WY45g?G}JC9dJPd6_65W0b8vaty(TL(d)R~ajZ|W%7TWpbYDTo2r%l($ zwpIPlUo8gNrujdpR!~PnzD|)7Mj+aZ%&%vnp@U@~vTtlwDRz-C$vo40ywPDB1v`e92q^NOaWG}ltCRrvwX4&gu2DWO^qC(F+Xc(`7{FO zs}=*O8&?_6hU*wqg!Cub{w!rxii-APW?FGNU|a`L?`m>#aaB2{A)=k~rW0ckG`}X_ zIye5+u=$q4LR*A9>{^Z2?2fzc^0|=i+|9UfiE5Y~HMAB+s?1-Gp0nU1pyNUU4B}kz zu%FtmbY4U(gydUGRqkPa;m(VdaTV=bl85^3EU2qrfd+JquI7l3XBW1<$qElz`VWiP zO0J;3s4KfhR(S-))!~iS2N%?ZmfCvMyK3!yKBvLcT{Cs3a6S+^_M&2TZngsc1{Jr5cHwvb(FPf6M4_v*A1xtDGe8*}2RY&WET1w=Mm8QbpzGcbb{xyQskRm-3>p(2Rm68R}yL?XE57nNThOhhCN~%H>M!=+{IriTc7uHW8&}N)06y)R$cpc)6&tsV%(9RN~kLM{R^sB@sC;7$R0?#RBmrqd27;^lsp%wMx**+pME%BGq zOI2}OY=VgW-Xd znDfpRov;-PI+Lkwo z!Mep;6;7sC^GL1eV}O_Clds_Erpa!JCsZw!$~UvM5EJRjnbcBDY81P&@a`PYx3gKRpf_ zel^iNk|pDO#471;{-DP+CV-8)<*o{+p#VV^U8~^9O#UL!U{APiaQpYv7Vb+jUc)9} z^eEvX1<}ab@!)VWUn*Lplhzv(2@hp;-N#t!j0vV}&vR+{Exv@1E31GL?~affRfCOH zqxy-1+L=c`RIpEZ#oyg}GPzqA?vFEa2*TcD8%&aU6^y>A^ z!i~k#(05T4M2WPnUtGU8{bodR3F9~PzX{Xv&i`@#zdl);GcfW3{*kYLgU9cW)PTQL z?0+b+`ZIqs!pKc@IFVR=9FkxF0N8(rk6&kxarBS59V6&gfVDZ0<-c>LT Gfd2r_Sh+9& delta 752 zcmV^GP)h>@6aWAK2msr7MqMsueyVH&006B8lTHN~e^kM4(?AftN6J6U z0m+-lUMCe2C{?H`C~8oXMs4T?A!Uij$s&7gcGoR!l#rINYGP{ZkLHjOS(U!x8oAs|5oO;mI|9Yt5Dtrkl_ zo!)=XGRvD(XZPQ#f7F7=44_=1BHE-#Fq-P(4vhhs!&oS>#2l54UKh#=>4Mm_&=#(x zfRo7;OwTW7ohD)2ZnayBLKzDyYfBh{#xIrB$O1)q2M!E6hubJerKm}je?rYlT`Z_9 zM|I7cFGol4yx;5fJtgjTogA4WF%vYtJp)WquU4AH3hpY%e;tVYvnf=EH9KV(?Pfl@d9^a5yBcmm73^Ie3)7Z?v>{iXveLy@6aWAK2msc2 zMqMG-lPC$;5!-l1T`p#Rs%!!P0IdZ801=ZB3K^4J1qqXX3Je0)c$19^93`6q003=o iWOZz1E^2dcZcs}F1^@s600IC40C)fZ0Cxib0001dHd1K-