Architektur und Sicherheit

Single-Tenant-pro-Company-Datenmodell, auf jeder Ebene erzwungen. Postgres-Row-Isolation per Company-Scope. API-Keys tragen User-Identität. Agents sehen nur das, was der Owner-User sehen darf.

Stack

• Next.js 16 (App Router, Turbopack): Web-App und API.
• PostgreSQL: Primary Datastore. JSONB für Custom-Column-Werte und Webhook-Payloads.
• Prisma: ORM und Migrationen.
• better-auth: Sessions, Social-Login, API-Keys.
• mcp-handler: Model-Context-Protocol-Endpoint.
• TypeScript durchgängig, Zod-validiert an jeder Grenze.

Tenancy

Jeder Record gehört zu einer Company. Die Company-ID wird an drei Stellen erzwungen:

1. App-Layer: jeder Interactor löst den aktuellen User auf Company auf und filtert danach.
2. Prisma-Layer: Queries enthalten companyId in jedem where.
3. Decorator-Layer: @TenantInteractor stellt sicher, dass Interactors, die Scope vergessen, zur Laufzeit werfen.

Cross-Tenant-Reads sind über die Public-Oberfläche nicht möglich. Es gibt keinen Admin-Panel, das Scope umgeht.

Authentifizierung

Drei Wege:

• Session-Cookie (UI): signed, http-only, Secure unter HTTPS.
• API-Key im x-api-key: 64-Zeichen-Token, SHA-256-gehasht at-rest, an User gebunden.
• Social-Provider via better-auth.

Alle drei lösen auf denselben User- und Company-Kontext auf. API-Keys haben ein Display-Präfix für die Erkennung in Audit-Logs.

Autorisierung

Per User, Rollen-getrieben. Rollen tragen Permissions auf Resources (Contacts, Deals etc.) und Actions (Read, Create, Update, Delete). Jeder Interactor ruft userService.hasPermissionOrThrow(resource, action) vor dem Handeln.

API-Keys erben die Rechte ihres Users. Keine separaten Key-Level-ACLs heute.

Externer KI-Zugriff

MCP-Calls sind durch denselben API-Key-Check gegated. Wenn eine KI über MCP handelt:

• Sie ruft /api/v1/mcp mit dem API-Key des Users.
• Der Server löst User und Company aus dem Key auf.
• Jeder Tool-Call läuft in Tenant-Scope.
• Validation-Errors liefern strukturierte Meldungen mit Remediation-Hints; interne Schema-Details leaken nicht.

Sicherheits-Guardrails speziell für schwächere Modelle:

• null auf Relationship-Array wird vor der DB abgelehnt.
• Falsches Per-Type-Custom-Column-Update-Tool wird mit Pointer aufs richtige abgelehnt.
• Destruktive Tools brauchen explizite ID-Listen; kein "delete everything matching filter"-Shortcut.

Daten at-rest

• Postgres-Verschlüsselung hängt vom Provider ab. In unserer Managed-Cloud liegen die Daten in einer EU-Region mit Disk-Level-Encryption at-rest.
• Secrets in .env werden nie geloggt. Der Logger redacts alles, was wie Key, Token oder Passwort aussieht.
• Webhook-Secrets liegen in Postgres (müssen retrievable sein, um Requests zu signieren). Wenn dich das stört, eigenes Secret-Management nutzen.

Daten in-transit

• HTTPS überall in Managed-Cloud.
• Bei Self-Host bringst du TLS selbst. Caddy-Beispiel unter Self-Hosting.
• Webhook-Deliveries gehen nur an HTTPS-URLs. HTTP wird im Schema abgelehnt.

Audit-Logging (Enterprise)

Jeder Write geloggt: User, Action, Entity, Before/After. Aus UI queryable. Als JSON exportierbar.

Vulnerabilities melden

Verantwortungsvoll an security@customermates.com. PGP-Key im Repo. Ack-Ziel: 24 Stunden.

Weiter

• Self-Hosting: wenn du das selbst betreiben willst.
• API-Keys: Hygiene-Regeln.
• MCP: wie die KI-Oberfläche geformt ist.