diff --git a/developer-portal/app/development/byoeh/page.tsx b/developer-portal/app/development/byoeh/page.tsx index b3b49c6..3eb827e 100644 --- a/developer-portal/app/development/byoeh/page.tsx +++ b/developer-portal/app/development/byoeh/page.tsx @@ -3,148 +3,255 @@ import { DevPortalLayout, CodeBlock, InfoBox } from '@/components/DevPortalLayou export default function BYOEHDocsPage() { return ( {/* ============================================================ */} {/* 1. EINLEITUNG */} {/* ============================================================ */} -

1. Was ist das Namespace-System?

+

1. Was ist die Namespace-Technologie?

- Das BYOEH-System (Bring Your Own Expectation Horizon) ist eine - Datenschutz-Architektur, die es Lehrern ermoeglicht, Klausuren anonym und - verschluesselt von einer KI korrigieren zu lassen -- ohne dass jemals der Name - eines Schuelers den Rechner des Lehrers verlaesst. + Unsere Namespace-Technologie (intern BYOEH -- Bring Your Own Expectation Horizon) + ist eine Privacy-First-Architektur, die es Geschaeftskunden ermoeglicht, sensible Daten + anonym und verschluesselt von KI-Services in der Cloud verarbeiten zu lassen -- ohne dass + personenbezogene Informationen jemals den Client verlassen.

- “Die Klausuren gehen anonym in die Cloud, werden dort von KI korrigiert, - und kommen korrigiert zurueck. Nur der Lehrer kann die Ergebnisse wieder den - Schuelern zuordnen -- denn nur seine Hardware hat den Schluessel dafuer.” + “Daten gehen pseudonymisiert und verschluesselt in die Cloud, werden dort + von KI verarbeitet, und kommen verarbeitet zurueck. Nur der Kunde kann die Ergebnisse + wieder den Originaldaten zuordnen -- denn nur sein System hat den Schluessel dafuer.”

- Das System loest ein grundlegendes Problem: Klausurkorrektur mit KI-Unterstuetzung - ohne Datenschutzrisiko. Die Loesung besteht aus vier Bausteinen: + Das SDK loest ein grundlegendes Problem fuer Unternehmen: KI-gestuetzte + Datenverarbeitung ohne Datenschutzrisiko. Die Architektur basiert auf vier Bausteinen:

  1. - Pseudonymisierung: Namen werden durch zufaellige Codes ersetzt. - Niemand ausser dem Lehrer kennt die Zuordnung. + Pseudonymisierung: Personenbezogene Daten werden durch zufaellige + Tokens ersetzt. Nur der Kunde kennt die Zuordnung.
  2. - Verschluesselung: Alles wird im Browser des Lehrers - verschluesselt, bevor es den Rechner verlaesst. Der Server sieht nur unlesbaren - Datensalat. + Client-seitige Verschluesselung: Alle Daten werden auf dem System + des Kunden verschluesselt, bevor sie die Infrastruktur verlassen. Der Cloud-Server + sieht nur verschluesselte Blobs.
  3. - Namespace-Isolation: Jeder Lehrer hat einen eigenen, abgeschotteten - Bereich (Namespace). Kein Lehrer kann auf die Daten eines anderen zugreifen. + Namespace-Isolation: Jeder Kunde erhaelt einen eigenen, vollstaendig + abgeschotteten Namespace. Kein Kunde kann auf Daten eines anderen zugreifen.
  4. - KI-Korrektur: Die KI arbeitet mit den verschluesselten Daten - und dem Erwartungshorizont (EH) des Lehrers. Korrekturvorschlaege gehen zurueck - an den Lehrer. + KI-Verarbeitung in der Cloud: Die KI arbeitet mit den pseudonymisierten + Daten und den vom Kunden bereitgestellten Referenzdokumenten. Ergebnisse gehen zurueck + an den Kunden zur lokalen Entschluesselung und Re-Identifizierung.
- Breakpilot kann die Klausuren nicht lesen. Der Server sieht nur - verschluesselte Daten und einen Schluessel-Hash (nicht den Schluessel selbst). Die - Passphrase zum Entschluesseln existiert nur im Browser des Lehrers und - wird niemals uebertragen. Selbst ein Angriff auf den Server wuerde keine - Klausurtexte preisgeben. + Breakpilot kann die Kundendaten nicht lesen. Der Server sieht nur + verschluesselte Blobs und einen Schluessel-Hash (nicht den Schluessel selbst). Die + Passphrase zum Entschluesseln existiert ausschliesslich auf dem System des Kunden + und wird niemals uebertragen. Selbst ein Angriff auf die Cloud-Infrastruktur wuerde keine + Klartextdaten preisgeben. {/* ============================================================ */} - {/* 2. DER KOMPLETTE ABLAUF */} + {/* 2. ANWENDUNGSFAELLE */} {/* ============================================================ */} -

2. Der komplette Ablauf im Ueberblick

+

2. Typische Anwendungsfaelle

- Der Prozess laesst sich in sieben Schritte unterteilen. Stellen Sie sich vor, der - Lehrer sitzt an seinem Rechner und hat einen Stapel gescannter Klausuren: + Die Namespace-Technologie ist ueberall einsetzbar, wo sensible Daten von einer KI + verarbeitet werden sollen, ohne den Datenschutz zu gefaehrden:

- -{`SCHRITT 1: KLAUSUREN SCANNEN & HOCHLADEN -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Lehrer scannt Klausuren ein (PDF oder Bild) - → System erkennt automatisch den Kopfbereich mit Namen - → Kopfbereich wird permanent entfernt (Header-Redaction) - → Jede Klausur erhaelt einen zufaelligen Code (doc_token) +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
BrancheAnwendungsfallSensible Daten
BildungKI-gestuetzte KlausurkorrekturSchuelernamen, Noten, Leistungsdaten
GesundheitswesenMedizinische BefundanalysePatientennamen, Diagnosen, Befunde
RechtVertragsanalyse, Due DiligenceMandantendaten, Vertragsinhalte
PersonalwesenBewerbungsscreening, ZeugnisanalyseBewerberdaten, Gehaltsinformationen
FinanzwesenDokumentenpruefung, Compliance-ChecksKontodaten, Transaktionen, Identitaeten
+
-SCHRITT 2: VERSCHLUESSELUNG IM BROWSER -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Lehrer gibt eine Passphrase ein (z.B. "MeinGeheimesPasswort2025!") - → Browser leitet daraus einen 256-Bit-Schluessel ab (PBKDF2) - → Klausur wird mit AES-256-GCM verschluesselt + {/* ============================================================ */} + {/* 3. DER KOMPLETTE ABLAUF */} + {/* ============================================================ */} +

3. Der komplette Ablauf im Ueberblick

+

+ Der Prozess laesst sich in sieben Schritte unterteilen. Die gesamte + Pseudonymisierung und Verschluesselung geschieht auf dem System des Kunden, + bevor Daten in die Cloud gesendet werden: +

+ + +{`SCHRITT 1: DOKUMENTE ERFASSEN & PSEUDONYMISIEREN +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +SDK empfaengt Dokumente (PDF, Bild, Text) + → Personenbezogene Daten werden erkannt (Header, Namen, IDs) + → PII wird durch zufaellige Tokens ersetzt (doc_token, UUID4) + → Zuordnung "Token → Originalname" wird lokal gesichert + +SCHRITT 2: CLIENT-SEITIGE VERSCHLUESSELUNG +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Kunde konfiguriert eine Passphrase im SDK + → SDK leitet daraus einen 256-Bit-Schluessel ab (PBKDF2, 100k Runden) + → Dokumente werden mit AES-256-GCM verschluesselt → Nur der Hash des Schluessels wird an den Server gesendet - → Passphrase und Schluessel verlassen NIEMALS den Browser + → Passphrase und Schluessel verlassen NIEMALS das Kundensystem SCHRITT 3: IDENTITAETS-MAP SICHERN ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Die Zuordnung "doc_token → Schuelername" wird verschluesselt: - → Tabelle: "a7f3c2d1... = Max Mustermann, b9e4a1f8... = Anna Schmidt" - → Diese Tabelle wird mit dem gleichen Schluessel verschluesselt - → Ohne Passphrase kann niemand die Zuordnung wiederherstellen +Die Zuordnung "Token → Originaldaten" wird verschluesselt gespeichert: + → Nur mit der Passphrase des Kunden rekonstruierbar + → Ohne Passphrase ist keine Re-Identifizierung moeglich -SCHRITT 4: UPLOAD IN DEN NAMESPACE -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Die verschluesselten Dateien gehen in den persoenlichen Namespace: - → Jeder Lehrer hat eine eigene tenant_id - → Daten werden in MinIO (verschluesselt) + Qdrant (Vektoren) gespeichert +SCHRITT 4: UPLOAD IN DEN KUNDEN-NAMESPACE +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Verschluesselte Dateien gehen in den isolierten Namespace: + → Jeder Kunde hat eine eigene tenant_id + → Daten werden in MinIO (Storage) + Qdrant (Vektoren) gespeichert → Server sieht: verschluesselter Blob + Schluessel-Hash + Salt -SCHRITT 5: KI-KORREKTUR -━━━━━━━━━━━━━━━━━━━━━━━ -Der Lehrer startet die KI-Korrektur: - → RAG-System durchsucht den Erwartungshorizont (EH) - → KI generiert Korrekturvorschlaege pro Kriterium - → Vorschlaege basieren auf dem EH, nicht auf Halluzinationen +SCHRITT 5: KI-VERARBEITUNG IN DER CLOUD +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +KI verarbeitet die pseudonymisierten Daten: + → RAG-System durchsucht Referenzdokumente des Kunden + → KI generiert Ergebnisse basierend auf Kundenkontext + → Ergebnisse sind an den Namespace gebunden SCHRITT 6: ERGEBNISSE ZURUECK ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Korrekturvorschlaege gehen an den Lehrer: - → Lehrer gibt Passphrase ein - → Browser entschluesselt die Ergebnisse - → Lehrer sieht: Vorschlaege pro Kriterium + Gesamtnote +KI-Ergebnisse gehen an das Kundensystem: + → SDK entschluesselt die Ergebnisse mit der Passphrase + → Kunde sieht aufbereitete Ergebnisse im Klartext -SCHRITT 7: ZUORDNUNG & FINALISIERUNG -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -Lehrer ordnet Ergebnisse den Schuelern zu: +SCHRITT 7: RE-IDENTIFIZIERUNG & FINALISIERUNG +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +Kunde ordnet Ergebnisse den Originaldaten zu: → Identitaets-Map wird entschluesselt - → doc_token wird wieder dem echten Namen zugeordnet - → Lehrer ueberprueft/korrigiert KI-Vorschlaege - → Fertige Korrektur + Gutachten koennen exportiert werden`} + → Tokens werden wieder den echten Datensaetzen zugeordnet + → Fertige Ergebnisse stehen im Originalsystem bereit`} {/* ============================================================ */} - {/* 3. PSEUDONYMISIERUNG */} + {/* 4. SDK-INTEGRATION */} {/* ============================================================ */} -

3. Pseudonymisierung: Wie Namen verschwinden

+

4. SDK-Integration

- Pseudonymisierung bedeutet: personenbezogene Daten werden durch zufaellige - Codes ersetzt, sodass ohne Zusatzinformation kein Rueckschluss auf die Person - moeglich ist. Im BYOEH-System passiert das auf zwei Ebenen: + Die Integration in bestehende Systeme erfolgt ueber unser SDK. Nachfolgend ein + vereinfachtes Beispiel, wie ein Kunde das SDK nutzt:

-

3.1 Der doc_token: Ein zufaelliger Ausweis

+ +{`import { BreakpilotSDK, NamespaceClient } from '@breakpilot/compliance-sdk' + +// 1. SDK initialisieren mit API-Key +const sdk = new BreakpilotSDK({ + apiKey: process.env.BREAKPILOT_API_KEY, + endpoint: 'https://api.breakpilot.de' +}) + +// 2. Namespace-Client erstellen (pro Mandant/Abteilung) +const namespace = sdk.createNamespace({ + tenantId: 'kunde-firma-abc', + passphrase: process.env.ENCRYPTION_PASSPHRASE // Bleibt lokal! +}) + +// 3. Dokument pseudonymisieren & verschluesselt hochladen +const result = await namespace.upload({ + file: documentBuffer, + metadata: { type: 'vertrag', category: 'due-diligence' }, + pseudonymize: true, // PII automatisch ersetzen + headerRedaction: true // Kopfbereich entfernen +}) +// result.docToken = "a7f3c2d1-4e9b-4a5f-8c7d-..." + +// 4. Referenzdokument hochladen (z.B. Pruefkriterien) +await namespace.uploadReference({ + file: referenceBuffer, + title: 'Pruefkriterien Vertrag Typ A' +}) + +// 5. KI-Verarbeitung anstossen +const analysis = await namespace.analyze({ + docToken: result.docToken, + prompt: 'Pruefe den Vertrag gegen die Referenzkriterien', + useRAG: true +}) + +// 6. Ergebnisse entschluesseln (passiert automatisch im SDK) +console.log(analysis.findings) // Klartext-Ergebnisse +console.log(analysis.score) // Bewertung + +// 7. Re-Identifizierung (Token → Originalname) +const identityMap = await namespace.getIdentityMap() +const originalName = identityMap[result.docToken]`} + + + + Die Passphrase verlässt niemals das System des Kunden. Das SDK verschluesselt + und entschluesselt ausschliesslich lokal. Breakpilot hat zu keinem + Zeitpunkt Zugriff auf Klartextdaten oder den Verschluesselungsschluessel. + + + {/* ============================================================ */} + {/* 5. PSEUDONYMISIERUNG */} + {/* ============================================================ */} +

5. Pseudonymisierung: Wie personenbezogene Daten entfernt werden

- Jede Klausur erhaelt einen doc_token -- einen 128-Bit-Zufallscode im - UUID4-Format (z.B. a7f3c2d1-4e9b-4a5f-8c7d-6b2e1f0a9d3c). Dieser Code: + Pseudonymisierung bedeutet: personenbezogene Daten werden durch zufaellige + Tokens ersetzt, sodass ohne Zusatzinformation kein Rueckschluss auf die Person + moeglich ist. Das SDK bietet zwei Mechanismen: +

+ +

5.1 Der doc_token: Ein zufaelliger Identifikator

+

+ Jedes Dokument erhaelt einen doc_token -- einen 128-Bit-Zufallscode im + UUID4-Format (z.B. a7f3c2d1-4e9b-4a5f-8c7d-6b2e1f0a9d3c). Dieser Token:

-

3.2 Header-Redaction: Der Name wird entfernt

+

5.2 Header-Redaction: PII wird entfernt

- Bevor eine Klausur verarbeitet wird, entfernt das System den Kopfbereich - der gescannten Seite -- dort, wo typischerweise Name, Klasse und Datum stehen. Diese - Entfernung ist permanent: Die Originaldaten werden nicht gespeichert. + Bei Dokumenten mit erkennbarem Kopfbereich (Namen, Adressen, IDs) kann das SDK diesen + Bereich automatisch entfernen. Die Entfernung ist permanent: + Die Originaldaten werden nicht an den Server uebermittelt.

@@ -153,70 +260,67 @@ Lehrer ordnet Ergebnisse den Schuelern zu: Methode Wie es funktioniert - Wann verwendet + Wann verwenden Einfache Redaction - Obere ~2,5 cm der Seite werden weiss ueberschrieben - Standard bei allen Uploads + Definierter Bereich des Dokuments wird entfernt + Standardisierte Formulare mit festem Layout Smarte Redaction - OpenCV erkennt Textbereiche und entfernt gezielt den Kopf, verschont aber QR-Codes - Wenn QR-Codes auf der Klausur sind + OpenCV/NER erkennt Textbereiche mit PII und entfernt gezielt + Freitext-Dokumente, variable Layouts
-

3.3 Die Identitaets-Map: Nur der Lehrer kennt die Zuordnung

+

5.3 Die Identitaets-Map: Nur der Kunde kennt die Zuordnung

- Die Zuordnung doc_token → Schuelername wird als verschluesselte Tabelle - gespeichert. Das Datenbankmodell sieht so aus: + Die Zuordnung doc_token → Originaldaten wird als verschluesselte Tabelle + gespeichert. Das Datenmodell sieht vereinfacht so aus:

- -{`ExamSession -├── teacher_id = "lehrer-uuid-123" ← Pflichtfeld (Isolation) -├── encrypted_identity_map = [verschluesselte Bytes] ← Nur mit Passphrase lesbar -├── identity_map_iv = "a3f2c1..." ← Initialisierungsvektor (fuer AES) + +{`NamespaceSession +├── tenant_id = "kunde-firma-abc" ← Pflichtfeld (Isolation) +├── encrypted_identity_map = [verschluesselte Bytes] ← Nur mit Passphrase lesbar +├── identity_map_iv = "a3f2c1..." ← Initialisierungsvektor (fuer AES) │ -└── PseudonymizedDocument (pro Klausur) - ├── doc_token = "a7f3c2d1-..." ← Zufaelliger Code (Primary Key) - ├── exam_session_id = [Referenz] - └── (Kein Name, keine Klasse, kein persoenliches Datum)`} +└── PseudonymizedDocument (pro Dokument) + ├── doc_token = "a7f3c2d1-..." ← Zufaelliger Token (Primary Key) + ├── session_id = [Referenz] + └── (Kein Name, keine personenbezogenen Daten)`} - Die Pseudonymisierung erfuellt die Definition aus der DSGVO: Die personenbezogenen Daten - (Schuelernamen) koennen ohne Hinzuziehung zusaetzlicher Informationen - (der verschluesselten Identitaets-Map + der Passphrase des Lehrers) nicht mehr einer + Die Pseudonymisierung erfuellt die Definition der DSGVO: Personenbezogene Daten + koennen ohne Hinzuziehung zusaetzlicher Informationen + (der verschluesselten Identitaets-Map + der Passphrase des Kunden) nicht mehr einer bestimmten Person zugeordnet werden. {/* ============================================================ */} - {/* 4. VERSCHLUESSELUNG */} + {/* 6. VERSCHLUESSELUNG */} {/* ============================================================ */} -

4. Verschluesselung: Wie Daten geschuetzt werden

+

6. Ende-zu-Ende-Verschluesselung

- Die Verschluesselung ist das Herzsstueck des Datenschutzes. Sie findet vollstaendig - im Browser statt -- der Server bekommt nur verschluesselte Daten zu sehen. + Die Verschluesselung ist das Herzstueck des Datenschutzes. Sie findet vollstaendig + auf dem System des Kunden statt -- der Cloud-Server bekommt nur verschluesselte + Daten zu sehen.

-

4.1 Der Verschluesselungsvorgang

-

- Wenn der Lehrer eine Klausur oder einen Erwartungshorizont hochlaedt, passiert im - Browser folgendes: -

+

6.1 Der Verschluesselungsvorgang

- + {`┌─────────────────────────────────────────────────────────────────┐ -│ Browser des Lehrers │ +│ System des Kunden (SDK) │ ├─────────────────────────────────────────────────────────────────┤ │ │ -│ 1. Lehrer gibt Passphrase ein (z.B. "MeinGeheimesPasswort!") │ +│ 1. Kunde konfiguriert Passphrase im SDK │ │ │ ↑ │ │ │ │ Passphrase bleibt hier -- wird NIE gesendet │ │ ▼ │ @@ -224,11 +328,10 @@ Lehrer ordnet Ergebnisse den Schuelern zu: │ PBKDF2-SHA256(Passphrase, zufaelliger Salt, 100.000 Runden) │ │ │ │ │ │ → Ergebnis: 256-Bit-Schluessel (32 Bytes) │ -│ │ → Selbst bei Kenntnis des Salts sind 100.000 Runden │ -│ │ noetig, um den Schluessel zu erraten │ +│ │ → 100.000 Runden machen Brute-Force unpraktikabel │ │ ▼ │ │ 3. Verschluesselung: │ -│ AES-256-GCM(Schluessel, zufaelliger IV, Datei-Inhalt) │ +│ AES-256-GCM(Schluessel, zufaelliger IV, Dokument) │ │ │ │ │ │ → AES-256: Militaerstandard, 2^256 moegliche Schluessel │ │ │ → GCM: Garantiert Integritaet (Manipulation erkennbar) │ @@ -236,12 +339,12 @@ Lehrer ordnet Ergebnisse den Schuelern zu: │ 4. Schluessel-Hash: │ │ SHA-256(abgeleiteter Schluessel) → Hash fuer Verifikation │ │ │ │ -│ │ → Der Server speichert nur diesen Hash │ +│ │ → Server speichert nur diesen Hash │ │ │ → Damit kann geprueft werden ob die Passphrase stimmt │ -│ │ → Vom Hash kann der Schluessel NICHT zurueckgerechnet │ +│ │ → Vom Hash kann der Schluessel NICHT zurueckberechnet │ │ │ werden │ │ ▼ │ -│ 5. Upload: Nur diese Daten gehen an den Server: │ +│ 5. Upload: Nur diese Daten gehen an den Cloud-Server: │ │ • Verschluesselter Blob (unlesbar ohne Schluessel) │ │ • Salt (zufaellige Bytes, harmlos) │ │ • IV (Initialisierungsvektor, harmlos) │ @@ -254,7 +357,7 @@ Lehrer ordnet Ergebnisse den Schuelern zu: └─────────────────────────────────────────────────────────────────┘`} -

4.2 Warum ist das sicher?

+

6.2 Sicherheitsgarantien

@@ -266,18 +369,18 @@ Lehrer ordnet Ergebnisse den Schuelern zu: - + - + - + - + @@ -286,7 +389,7 @@ Lehrer ordnet Ergebnisse den Schuelern zu: - + @@ -295,46 +398,46 @@ Lehrer ordnet Ergebnisse den Schuelern zu: {/* ============================================================ */} - {/* 5. NAMESPACE / TENANT-ISOLATION */} + {/* 7. NAMESPACE / TENANT-ISOLATION */} {/* ============================================================ */} -

5. Namespace-Isolation: Jeder Lehrer hat seinen eigenen Bereich

+

7. Namespace-Isolation: Jeder Kunde hat seinen eigenen Bereich

- Ein Namespace (auch “Tenant” genannt) ist ein abgeschotteter - Bereich im System. Man kann es sich wie separate Schliessfaecher in einer - Bank vorstellen: Jeder Lehrer hat sein eigenes Fach, und kein Schluessel passt in ein - anderes Fach. + Ein Namespace (auch “Tenant” genannt) ist ein vollstaendig + abgeschotteter Bereich im System. Man kann es sich wie separate Tresorraeume + in einer Bank vorstellen: Jeder Kunde hat seinen eigenen Raum, und kein Schluessel + passt in einen anderen.

-

5.1 Wie die Isolation funktioniert

+

7.1 Wie die Isolation funktioniert

- Jeder Lehrer erhaelt beim ersten Login eine eindeutige tenant_id. Diese ID wird - bei jeder einzelnen Datenbankabfrage als Pflichtfilter mitgefuehrt: + Jeder Kunde erhaelt eine eindeutige tenant_id. Diese ID wird + bei jeder einzelnen Datenbankabfrage als Pflichtfilter verwendet:

-{`Lehrer A (tenant_id: "school-A-lehrer-1") -├── Klausur 1 (verschluesselt) -├── Klausur 2 (verschluesselt) -└── Erwartungshorizont Deutsch LK 2025 +{`Kunde A (tenant_id: "firma-alpha-001") +├── Dokument 1 (verschluesselt) +├── Dokument 2 (verschluesselt) +└── Referenz: Pruefkriterien 2025 -Lehrer B (tenant_id: "school-B-lehrer-2") -├── Klausur 1 (verschluesselt) -└── Erwartungshorizont Mathe GK 2025 +Kunde B (tenant_id: "firma-beta-002") +├── Dokument 1 (verschluesselt) +└── Referenz: Compliance-Vorgaben 2025 -Suchanfrage von Lehrer A: - "Wie soll die Einleitung strukturiert sein?" - → Suche NUR in tenant_id = "school-A-lehrer-1" - → Lehrer B's Daten sind UNSICHTBAR +Suchanfrage von Kunde A: + "Welche Klauseln weichen von den Referenzkriterien ab?" + → Suche NUR in tenant_id = "firma-alpha-001" + → Kunde B's Daten sind UNSICHTBAR Jede Qdrant-Query hat diesen Pflichtfilter: must_conditions = [ - FieldCondition(key="tenant_id", match="school-A-lehrer-1") + FieldCondition(key="tenant_id", match="firma-alpha-001") ] Es gibt KEINE Abfrage ohne tenant_id-Filter.`} -

5.2 Drei Ebenen der Isolation

+

7.2 Drei Ebenen der Isolation

Server wird gehacktCloud-Server wird gehackt Verschluesselte Blobs + HashesKeine lesbaren KlausurenKeine lesbaren Dokumente
Datenbank wird geleakt encrypted_identity_map (verschluesselt)Keine SchuelernamenKeine personenbezogenen Daten
Netzwerkverkehr abgefangenVerschluesselte Daten (HTTPS + AES)Verschluesselte Daten (TLS + AES) Doppelt verschluesselt
Operator Blindness
Anderer Lehrer versucht ZugriffAnderer Kunde versucht Zugriff Nichts (Tenant-Isolation) Namespace blockiert
@@ -348,7 +451,7 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} - + @@ -358,145 +461,115 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} - +
Dateisystem MinIO (S3-Storage)Eigener Ordner pro Lehrer: /tenant-id/eh-id/encrypted.binEigener Bucket/Pfad pro Kunde: /tenant-id/doc-id/encrypted.bin
Vektordatenbank
Metadaten-DB PostgreSQLJede Tabelle hat teacher_id als PflichtfeldJede Tabelle hat tenant_id als Pflichtfeld
- + Auf allen Vektoren in Qdrant ist das Flag training_allowed: false gesetzt. - Das bedeutet: Die Inhalte der Lehrer werden ausschliesslich fuer RAG-Suchen - (Abruf relevanter Textpassagen) verwendet und niemals zum Trainieren eines - KI-Modells eingesetzt. + Kundeninhalte werden ausschliesslich fuer RAG-Suchen innerhalb des + Kunden-Namespace verwendet und niemals zum Trainieren eines KI-Modells + eingesetzt. {/* ============================================================ */} - {/* 6. DER ERWARTUNGSHORIZONT (EH) */} + {/* 8. RAG-PIPELINE */} {/* ============================================================ */} -

6. Der Erwartungshorizont: Die Grundlage fuer KI-Korrektur

+

8. RAG-Pipeline: KI-Verarbeitung mit Kundenkontext

- Ein Erwartungshorizont (EH) ist das Dokument, das beschreibt, was in - einer Klausur erwartet wird: welche Inhalte in welcher Qualitaet vorkommen sollen. - Im BYOEH-System laedt der Lehrer seinen eigenen EH hoch, und die KI nutzt ihn als - Referenz fuer Korrekturvorschlaege. + Die KI nutzt die vom Kunden hochgeladenen Referenzdokumente als Wissensbasis. + Dieser Prozess heisst RAG (Retrieval Augmented Generation): + Die KI “liest” zuerst die relevanten Referenzen und generiert dann + kontextbezogene Ergebnisse.

-

6.1 Upload-Wizard (5 Schritte)

-
- - - - - - - - - - - - - - - -
SchrittWas passiertWarum
1. Datei waehlenPDF per Drag & Drop hochladenDer EH als digitales Dokument
2. MetadatenTitel, Fach, Niveau (eA/gA), JahrFuer Filterung und Organisation
3. RechtebestaetigungCheckbox: “Ich bin berechtigt”Rechtliche Absicherung (Urheberrecht)
4. VerschluesselungPassphrase eingeben (2x bestaetigen)Schluessel fuer Ende-zu-Ende-Verschluesselung
5. ZusammenfassungPruefen und bestaetigenLetzte Kontrolle vor dem Upload
-
- -

6.2 RAG-Pipeline: Wie der EH fuer die KI nutzbar wird

-

- Nach dem Upload wird der EH fuer die KI-Suche vorbereitet. Dieser Vorgang heisst - Indexierung und funktioniert wie das Erstellen eines Stichwortverzeichnisses - fuer ein Buch: -

- - -{`Erwartungshorizont (verschluesselt auf Server) +

8.1 Indexierung der Referenzdokumente

+ +{`Referenzdokument (verschluesselt auf Server) | v -┌────────────────────────────────┐ -│ 1. Passphrase-Verifikation │ ← Lehrer gibt Passphrase ein -│ Hash pruefen │ Server vergleicht mit gespeichertem Hash -└──────────┬─────────────────────┘ +┌────────────────────────────────────┐ +│ 1. Passphrase-Verifikation │ ← SDK sendet Schluessel-Hash +│ Hash pruefen │ Server vergleicht mit gespeichertem Hash +└──────────┬─────────────────────────┘ | v -┌────────────────────────────────┐ -│ 2. Entschluesselung │ ← Temporaer im Arbeitsspeicher -│ AES-256-GCM Decrypt │ (wird nach Verarbeitung geloescht) -└──────────┬─────────────────────┘ +┌────────────────────────────────────┐ +│ 2. Entschluesselung │ ← Temporaer im Arbeitsspeicher +│ AES-256-GCM Decrypt │ (wird nach Verarbeitung geloescht) +└──────────┬─────────────────────────┘ | v -┌────────────────────────────────┐ -│ 3. Text-Extraktion │ ← PDF → Klartext -│ Tabellen, Listen erkennen │ -└──────────┬─────────────────────┘ +┌────────────────────────────────────┐ +│ 3. Text-Extraktion │ ← PDF → Klartext +│ Tabellen, Listen, Absaetze │ +└──────────┬─────────────────────────┘ | v -┌────────────────────────────────┐ -│ 4. Chunking │ ← Text in 1.000-Zeichen-Abschnitte zerlegen -│ Ueberlappung: 200 Zeichen │ (mit Ueberlappung, damit kein Kontext -│ │ verloren geht) -└──────────┬─────────────────────┘ +┌────────────────────────────────────┐ +│ 4. Chunking │ ← Text in ~1.000-Zeichen-Abschnitte +│ Ueberlappung: 200 Zeichen │ (mit Ueberlappung fuer Kontexterhalt) +└──────────┬─────────────────────────┘ | v -┌────────────────────────────────┐ -│ 5. Embedding │ ← Jeder Abschnitt wird in einen -│ Text → 1.536 Zahlen │ Bedeutungsvektor umgewandelt -└──────────┬─────────────────────┘ +┌────────────────────────────────────┐ +│ 5. Embedding │ ← Jeder Abschnitt wird in einen +│ Text → 1.536 Zahlen │ Bedeutungsvektor umgewandelt +└──────────┬─────────────────────────┘ | v -┌────────────────────────────────┐ -│ 6. Re-Encryption │ ← Jeder Chunk wird ERNEUT verschluesselt -│ AES-256-GCM pro Chunk │ bevor er gespeichert wird -└──────────┬─────────────────────┘ +┌────────────────────────────────────┐ +│ 6. Re-Encryption │ ← Jeder Chunk wird ERNEUT verschluesselt +│ AES-256-GCM pro Chunk │ bevor er gespeichert wird +└──────────┬─────────────────────────┘ | v -┌────────────────────────────────┐ -│ 7. Qdrant-Indexierung │ ← Vektor + verschluesselter Chunk -│ tenant_id: "lehrer-123" │ werden mit Tenant-Filter gespeichert -│ training_allowed: false │ -└────────────────────────────────┘`} +┌────────────────────────────────────┐ +│ 7. Qdrant-Indexierung │ ← Vektor + verschluesselter Chunk +│ tenant_id: "firma-alpha-001" │ werden mit Tenant-Filter gespeichert +│ training_allowed: false │ +└────────────────────────────────────┘`} -

6.3 Wie die KI den EH nutzt (RAG-Query)

-

- Wenn der Lehrer bei der Korrektur einen Vorschlag anfordert, passiert folgendes: -

+

8.2 Wie die KI eine Anfrage bearbeitet (RAG-Query)

  1. - Frage formulieren: Das System erstellt eine Suchanfrage aus dem - Klausurtext und dem aktuellen Bewertungskriterium (z.B. “Wie gut ist die - Einleitung im Vergleich zum Erwartungshorizont?”). + Anfrage formulieren: Das SDK sendet eine Suchanfrage mit dem + zu verarbeitenden Dokument und den gewuenschten Kriterien.
  2. Semantische Suche: Die Anfrage wird in einen Vektor umgewandelt und - gegen die EH-Vektoren in Qdrant gesucht -- nur im Namespace des Lehrers. + gegen die Referenz-Vektoren in Qdrant gesucht -- nur im Namespace des Kunden.
  3. Entschluesselung: Die gefundenen Chunks werden mit der Passphrase - des Lehrers entschluesselt. + des Kunden entschluesselt.
  4. - KI-Antwort: Die entschluesselten EH-Passagen werden als Kontext - an die KI uebergeben, die daraus einen Korrekturvorschlag generiert. + KI-Antwort: Die entschluesselten Referenzpassagen werden als Kontext + an die KI uebergeben, die daraus ein Ergebnis generiert.
{/* ============================================================ */} - {/* 7. KEY SHARING */} + {/* 9. KEY SHARING */} {/* ============================================================ */} -

7. Key Sharing: Zweitkorrektur ermoeglichen

+

9. Key Sharing: Zusammenarbeit ermoeglichen

- Bei Abiturklausuren muss eine Zweitkorrektur durch einen anderen Lehrer - erfolgen. Das Key-Sharing-System ermoeglicht es dem Erstpruefer, seinen Erwartungshorizont - sicher mit dem Zweitpruefer zu teilen -- ohne die Verschluesselung aufzugeben. + In vielen Geschaeftsprozessen muessen mehrere Personen oder Abteilungen auf die gleichen + Daten zugreifen -- z.B. fuer Vier-Augen-Prinzip, Qualitaetskontrolle oder externe Audits. + Das Key-Sharing-System ermoeglicht es dem Eigentuemer, seinen Namespace sicher mit + anderen zu teilen.

-

7.1 Einladungs-Workflow

- -{`Erstpruefer Server Zweitpruefer +

9.1 Einladungs-Workflow

+ +{`Eigentuemer Server Eingeladener │ │ │ │ 1. Einladung senden │ │ - │ (E-Mail + Rolle + Klausur) │ │ + │ (E-Mail + Rolle + Scope) │ │ │─────────────────────────────────▶ │ │ │ │ │ │ 2. Einladung erstellt │ @@ -504,16 +577,16 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} │ │ │ │ │ 3. Benachrichtigung ──────▶│ │ │ │ - │ │ 4. Einladung annehmen + │ │ 4. Einladung annehmen │ │◀─────────────────────────────│ │ │ │ │ │ 5. Key-Share erstellt │ │ │ (verschluesselte │ │ │ Passphrase) │ │ │ │ - │ │ 6. Zweitpruefer kann ──────▶│ - │ │ jetzt RAG-Queries │ - │ │ ausfuehren │ + │ │ 6. Eingeladener kann ──────▶│ + │ │ jetzt Daten im │ + │ │ Namespace abfragen │ │ │ │ │ 7. Zugriff widerrufen │ │ │ (jederzeit moeglich) │ │ @@ -521,104 +594,64 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} │ │ Share deaktiviert │`} -

7.2 Rollen beim Key-Sharing

+

9.2 Rollen beim Key-Sharing

- + - - - - + + +
RolleWerTypischer Nutzer Rechte
Erstpruefer (EK)KurslehrerVollzugriff, kann teilen & widerrufen
Zweitpruefer (ZK)Anderer FachlehrerNur Lesen, RAG-Queries, eigene Annotations
Drittpruefer (DK)Bei Differenz ≥ 4 PunkteNur Lesen, RAG-Queries
FachvorsitzFachbereichsleitungNur Lesen (Aufsichtsfunktion)
OwnerProjektverantwortlicherVollzugriff, kann teilen & widerrufen
ReviewerQualitaetssicherungLesen, RAG-Queries, eigene Anmerkungen
AuditorExterner PrueferNur Lesen (Aufsichtsfunktion)
{/* ============================================================ */} - {/* 8. BEWERTUNGSKRITERIEN */} + {/* 10. AUDIT-TRAIL */} {/* ============================================================ */} -

8. KI-gestuetzte Bewertung: Wie die Korrektur funktioniert

+

10. Audit-Trail: Vollstaendige Nachvollziehbarkeit

- Die KI bewertet jede Klausur anhand von fuenf Kriterien, die - zusammen 100% ergeben: -

-
- - - - - - - - - - - - - - - -
KriteriumGewichtungWas geprueft wird
Rechtschreibung15%Orthographie, Zeichensetzung
Grammatik15%Satzbau, Kongruenz, Tempus
Inhalt40%Bezug zum EH, Vollstaendigkeit, Argumentation
Struktur15%Gliederung, Einleitung/Schluss, roter Faden
Stil15%Ausdruck, Wortwahl, Fachsprache
-
- -

- Die Bewertung folgt dem 15-Punkte-System (0-15 Notenpunkte), - das fuer die gymnasiale Oberstufe gilt. Aus den Teilbewertungen wird automatisch - eine Gesamtnote berechnet. -

- - - Alle KI-Bewertungen sind Vorschlaege. Der Lehrer hat bei jedem - Kriterium die volle Kontrolle: Er kann den Vorschlag annehmen, aendern oder - komplett ueberschreiben. Die finale Note setzt immer der Lehrer. - - - {/* ============================================================ */} - {/* 9. AUDIT-TRAIL */} - {/* ============================================================ */} -

9. Audit-Trail: Alles wird protokolliert

-

- Jede Aktion im System wird revisionssicher im Audit-Log gespeichert. - Das ist wichtig fuer die Nachvollziehbarkeit und fuer den Fall, dass Schueler oder - Eltern eine Korrektur anfechten. + Jede Aktion im Namespace wird revisionssicher im Audit-Log gespeichert. + Das ist essenziell fuer Compliance-Anforderungen und externe Audits.

- + - - - - + + + + + - - + +
AktionEvent Was protokolliert wird
uploadEH hochgeladen (Dateigroesse, Metadaten, Zeitstempel)
indexEH fuer RAG indexiert (Anzahl Chunks, Dauer)
rag_queryRAG-Suchanfrage ausgefuehrt (Query-Hash, Anzahl Ergebnisse, Score)
shareEH mit anderem Pruefer geteilt (Empfaenger, Rolle)
uploadDokument hochgeladen (Dateigroesse, Metadaten, Zeitstempel)
indexReferenzdokument indexiert (Anzahl Chunks, Dauer)
rag_queryRAG-Suchanfrage ausgefuehrt (Query-Hash, Anzahl Ergebnisse)
analyzeKI-Verarbeitung gestartet (Dokument-Token, Modell, Dauer)
shareNamespace mit anderem Nutzer geteilt (Empfaenger, Rolle)
revoke_shareZugriff widerrufen (wer, wann)
link_klausurEH mit Klausur verknuepft
deleteEH geloescht (Soft Delete, bleibt in Logs)
decryptErgebnis entschluesselt (durch wen, Zeitstempel)
deleteDokument geloescht (Soft Delete, bleibt in Logs)
{/* ============================================================ */} - {/* 10. API-ENDPUNKTE */} + {/* 11. API-ENDPUNKTE */} {/* ============================================================ */} -

10. API-Endpunkte (Technische Referenz)

+

11. API-Endpunkte (SDK-Referenz)

- Alle Endpunkte laufen ueber den klausur-service auf Port 8086. - Authentifizierung erfolgt ueber JWT-Token. + Die folgenden Endpunkte sind ueber das SDK oder direkt via REST ansprechbar. + Authentifizierung erfolgt ueber API-Key + JWT-Token.

-

10.1 Erwartungshorizont-Verwaltung

+

11.1 Namespace-Verwaltung

@@ -629,17 +662,15 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} - - - - - - + + + +
POST/api/v1/eh/uploadVerschluesselten EH hochladen
GET/api/v1/ehEigene EHs auflisten
GET/api/v1/eh/{'{id}'}Einzelnen EH abrufen
DELETE/api/v1/eh/{'{id}'}EH loeschen (Soft Delete)
POST/api/v1/eh/{'{id}'}/indexEH fuer RAG indexieren
POST/api/v1/eh/rag-queryRAG-Suchanfrage ausfuehren
POST/api/v1/namespace/uploadVerschluesseltes Dokument hochladen
GET/api/v1/namespace/documentsEigene Dokumente auflisten
GET/api/v1/namespace/documents/{'{id}'}Einzelnes Dokument abrufen
DELETE/api/v1/namespace/documents/{'{id}'}Dokument loeschen (Soft Delete)
-

10.2 Key Sharing

+

11.2 Referenzdokumente & RAG

@@ -650,15 +681,15 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} - - - - + + + +
POST/api/v1/eh/{'{id}'}/shareEH mit Pruefer teilen
GET/api/v1/eh/{'{id}'}/sharesGeteilte Zugriffe auflisten
DELETE/api/v1/eh/{'{id}'}/shares/{'{shareId}'}Zugriff widerrufen
GET/api/v1/eh/shared-with-meMit mir geteilte EHs
POST/api/v1/namespace/references/uploadReferenzdokument hochladen
POST/api/v1/namespace/references/{'{id}'}/indexReferenz fuer RAG indexieren
POST/api/v1/namespace/rag-queryRAG-Suchanfrage ausfuehren
POST/api/v1/namespace/analyzeKI-Verarbeitung anstossen
-

10.3 Klausur-Integration

+

11.3 Key Sharing

@@ -669,47 +700,18 @@ Es gibt KEINE Abfrage ohne tenant_id-Filter.`} - - - + + + +
POST/api/v1/eh/{'{id}'}/link-klausurEH mit Klausur verknuepfen
DELETE/api/v1/eh/{'{id}'}/link-klausur/{'{klausurId}'}Verknuepfung loesen
GET/api/v1/klausuren/{'{id}'}/linked-ehVerknuepften EH abrufen
POST/api/v1/namespace/shareNamespace mit anderem Nutzer teilen
GET/api/v1/namespace/sharesAktive Shares auflisten
DELETE/api/v1/namespace/shares/{'{shareId}'}Zugriff widerrufen
GET/api/v1/namespace/shared-with-meMit mir geteilte Namespaces
- {/* ============================================================ */} - {/* 11. DATEISTRUKTUR */} - {/* ============================================================ */} -

11. Dateistruktur im Code

- - -{`klausur-service/ -├── backend/ -│ ├── main.py # API-Endpunkte + Datenmodelle -│ ├── qdrant_service.py # Vektordatenbank-Operationen (Tenant-Filter) -│ └── eh_pipeline.py # Chunking, Embedding, Verschluesselung -│ -├── frontend/ -│ └── src/ -│ ├── components/ -│ │ └── EHUploadWizard.tsx # 5-Schritt-Upload-Wizard -│ └── services/ -│ ├── api.ts # API-Client -│ └── encryption.ts # Client-seitige Kryptographie -│ -└── docs/ - ├── BYOEH-Architecture.md # Technische Architektur - └── BYOEH-Developer-Guide.md # Entwickler-Handbuch - -backend/klausur/ -├── db_models.py # ExamSession, PseudonymizedDocument -└── services/ - └── pseudonymizer.py # QR-Codes, Header-Redaction, doc_tokens`} - - {/* ============================================================ */} {/* 12. ZUSAMMENFASSUNG */} {/* ============================================================ */} -

12. Zusammenfassung: Die Sicherheitsgarantien

+

12. Zusammenfassung: Compliance-Garantien

@@ -722,7 +724,7 @@ backend/klausur/ - + @@ -732,12 +734,12 @@ backend/klausur/ - + - + @@ -747,20 +749,20 @@ backend/klausur/ - - - + + +
Kein Name verlaesst den RechnerKeine PII verlaesst das Kundensystem Header-Redaction + verschluesselte Identity-Map DSGVO Art. 4 Nr. 5
DSGVO Art. 32
Kein Zugriff durch andere LehrerKein Zugriff durch andere Kunden Tenant-Isolation (Namespace) auf allen 3 Ebenen DSGVO Art. 25
Kein KI-Training mit SchuelerdatenKein KI-Training mit Kundendaten training_allowed: false auf allen Vektoren AI Act Art. 10
DSGVO Art. 5 Abs. 2
Lehrer behaelt volle KontrolleKI-Vorschlaege, keine KI-Entscheidungen + jederzeitiger WiderrufDSGVO Art. 22Kunde behaelt volle KontrolleJederzeitiger Widerruf, Loeschung, DatenexportDSGVO Art. 17, 20
- Das BYOEH-System ermoeglicht KI-gestuetzte Klausurkorrektur, bei der - kein Schuelername den Rechner des Lehrers verlaesst, alle Daten - Ende-zu-Ende verschluesselt sind, jeder Lehrer seinen - eigenen abgeschotteten Namespace hat, und die KI - nur Vorschlaege macht -- die finale Bewertung trifft immer der Lehrer. + Die Namespace-Technologie ermoeglicht KI-gestuetzte Datenverarbeitung in der Cloud, bei der + keine personenbezogenen Daten das Kundensystem verlassen, alle Daten + Ende-zu-Ende verschluesselt sind, jeder Kunde seinen + eigenen abgeschotteten Namespace hat, und ein + vollstaendiger Audit-Trail jede Aktion dokumentiert. )