feat: Phase 6 – Modul-API-Vertrag mit platform-module-sdk

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`).

apps/platform-backend/jest.config.js

@@ -2,7 +2,7 @@
 module.exports = {
   preset: 'ts-jest',
   testEnvironment: 'node',
-  roots: ['<rootDir>/src'],
+  roots: ['<rootDir>/src', '<rootDir>/test'],
   testRegex: '.*\\.spec\\.ts$',
   moduleFileExtensions: ['ts', 'js', 'json'],
   collectCoverageFrom: ['src/**/*.ts', '!src/main.ts', '!src/**/*.module.ts'],

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],

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([]);
+    });
+  });
+});

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
+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

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,
+};

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', () => {