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

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