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 123e415..ee2ec88 100644 Binary files a/modules/demo/demo-module.zip and b/modules/demo/demo-module.zip differ