So funktioniert es

Architektur für Entwickler

Was du wissen musst, um einen Request zu debuggen. Für Visualisierungen und Business-Framing siehe /how-it-works.

Jeder Request durch Lucairn durchläuft eine feste Sequenz von Services. Jeder hat genau eine Aufgabe, läuft in eigenem Netzwerk-Namespace und schreibt einen Audit-Eintrag. Wenn ein Request scheitert, lässt sich der Fehler genau einer Komponente zuordnen.

Request-Flow (oben nach unten)

  1. 1Client sendet POST /v1/messages mit Authorization: Bearer lcr_live_* und X-Upstream-Key: sk-ant-*.
  2. 2Gateway authentifiziert den Lucairn-Schlüssel und ermittelt den Tarif (Developer / Pro / Enterprise).
  3. 3Gateway leitet Body an Sanitizer (gRPC). Sanitizer gibt {redacted_text, manifest} zurück, das Manifest listet jede ersetzte Entität.
  4. 4Gateway ruft ID Bridge mit dem Manifest auf; Bridge persistiert Mapping-Zeilen mit Scope auf diese request_id und liefert einen Bridge Claim, signiert mit dem Ed25519-Schlüssel der Bridge.
  5. 5Gateway ruft Sandbox B mit dem bereinigten Body auf; Sandbox B leitet an dein Upstream-LLM weiter und nutzt deinen X-Upstream-Key-Header. Response kommt redigiert zurück.
  6. 6Gateway re-linkt optional auf dem Lucairn-nativen Endpunkt (nur Pro und Enterprise, opt-in). Free-Tier-Response behält die Platzhalter.
  7. 7Veil Witness baut das kanonische Signable: {request_id, sanitizer_manifest_hash, bridge_claim, sandbox_isolation_attestation, content_hash, witness_timestamp, protocol_version}. Signatur mit Ed25519.
  8. 8Gateway gibt die Response mit metadata.dsa_compliance.certificate_url zurück, der auf das Witness-signierte Zertifikat zeigt.

Komponenten

Gateway

Eintrittspunkt

Authentifiziert deinen lcr_live_*-API-Schlüssel, leitet deinen X-Upstream-Key-Header weiter, klassifiziert die Request-Form (Anthropic / OpenAI / Lucairn-native / MCP) und routet durch die Pipeline. Das Gateway sieht nie rohe Identitätswerte — es arbeitet auf Tokens nach dem Sanitizer.

  • → POST /v1/messages
  • → POST /v1/chat/completions
  • → POST /api/v1/proxy/messages
  • → POST /api/v1/scan

Sanitizer

PII-Erkennung + Redaktion

Drei Erkennungsschichten auf dem Request-Body: (L1) Presidio NER mit Custom Recognizers, (L2) Quasi-Identifier-Risikoscoring, (L3) On-GPU-LLM-PII-Shield. Jede erkannte Entität wird durch einen Platzhalter wie [PERSON_1] oder [EMAIL_2] ersetzt.

  • → Intern: gRPC :50055
  • → Layer-Toggles via `X-Lucairn-Sanitizer-Layers`-Header

ID Bridge (Sandbox A)

Halter der Identitäts-Mapping-Tabelle

Speichert die Platzhalter-↔-Rohwert-Mappings für die Lebensdauer des Requests. Die Mapping-Tabelle liegt hier, nicht in Sandbox B. Free-Tier-Responses werden mit Platzhaltern zurückgegeben. Pro und Enterprise können automatisches Re-Linking aktivieren; das passiert im Gateway-Speicher, nie persistent neben KI-Output.

  • → Intern: gRPC :50052
  • → Postgres `identity_mappings`-Tabelle — nur INSERT/SELECT

Sandbox B

KI-Inferenz

Läuft im eigenen Kubernetes-Namespace mit NetworkPolicies, die jeglichen Egress außer zum von dir gewählten Upstream-LLM-Provider blockieren. Erhält ausschließlich die bereinigte Payload — nie rohe PII. Wer diese Sandbox kompromittiert, bekommt Tokens, keine Identitäten.

  • → Nur ausgehend: api.anthropic.com / api.openai.com / dein Self-Hosted-Endpoint

Veil Witness

Zertifikats-Signierer

Beobachtet, wie das Gateway für jeden Request ein strukturiertes Event ausgibt — Sanitizer-Manifest, Sandbox-Isolation-Check, Content-Hash, Timestamps, Bridge Claim. Der Witness baut einen kanonischen 7-Key-Signable, signiert mit Ed25519 und speichert das Zertifikat. Der Public Key liegt unter /.well-known/veil-keys.json für Offline-Verifikation.

  • → GET /api/v1/veil/certificate/{request_id}
  • → GET /api/v1/veil/certificate/{request_id}/summary
  • → GET /.well-known/veil-keys.json

Audit Trail

Append-only-Event-Log

Jede Entscheidung (Auth, Sanitizer-Hit, Sandbox-Routing, Cert-Mint, Re-Linking-Versuch) bekommt eine Zeile in einer Append-only-Postgres-Tabelle mit Hash Chain. Die Anwendungsrolle hat nur INSERT und SELECT. Löschung läuft nur über eine SECURITY-DEFINER-Funktion für DSGVO-Art.-17-Löschungen, die einen separaten signierten Löschnachweis schreibt.

  • → GET /api/v1/account/audit (alle Tiers — Anzeige ist tier-unabhängig; CSV-Export ist nur Pro und Enterprise)
  • → POST /api/v1/audit/export

Debugging-Tipps

  • Wenn du [PERSON_N] in der Response siehst, hat der Sanitizer korrekt redigiert — du bist nur auf einem Tarif ohne Re-Linking. Entweder du fügst den Platzhalter selbst zurück, oder du upgradest auf Pro für opt-in Re-Linking.

  • 503 scanner_unavailable heißt: Sanitizer ist down. Das Gateway schließt fail-closed — das ist Absicht. Beobachte /changelog für Incident-Updates.

  • Wenn eine Zertifikats-URL 404 liefert, ist der Witness down oder die request_id ist fehlerhaft. Cert-IDs sind URL-safe Base64 von 16 Bytes.

  • Wenn deine lcr_live_*-Auth fehlschlägt: Prüfe, ob du den vollen Schlüssel kopiert hast (kein trailing Newline) und keinen alten dsa_*-Legacy-Schlüssel verwendest.

  • Das Gateway publiziert Plausible-freundliche Health-Metriken auf /healthz; Container-Logs sind die Quelle der Wahrheit.

Verwandt

Möchten Sie das in Aktion sehen?

Vereinbaren Sie einen Termin — wir gehen gemeinsam durch Ihren Anwendungsfall.

Kontakt