gate: worker skips plugin activation, only registers event handlers

- Migration 0086: Remove FORCE RLS from 5 global tables
- Migration 0085: crm_migration keeps BYPASSRLS for data migrations
- Migration 0085: Remove audit_log from crm_auth grants
- auth_service.py: Audit log via separate API session (crm_api with tenant context)
- tests/test_no_legacy_tenant_var.py: CI test for app.tenant_id in policies

.a0/current_status.md

@@ -1,17 +1,47 @@
 # LeoCRM — Current Status
-**Phase**: 6 (Deployment) — COMPLETE
+**Phase**: Fix Branch — 20/22 FIX-PLAN Items erledigt
-**Last commit**: 1d3fccc (pushed to Forgejo)
+**Last update**: 2026-07-26 16:25
-**Date**: 2026-07-02
+**Branch**: main (leocrm-fix)
 
-## Deployment Results
+## FIX-PLAN Überprüfung (2026-07-26)
-- URL: https://crm.media-on.de ✅
+Alle 22 Items gegen Codebasis verifiziert. 20 erledigt, 2 offen.
-- Status: running:healthy ✅
-- Health: 200 OK ✅
-- Swagger: 200 OK ✅
-- PostgreSQL 16: running ✅
-- Redis 7: running ✅
-- Traefik SSL: Let's Encrypt ✅
 
-## Next Step
+### Erledigt (20)
-- Phase 6 → Phase 7 transition (requires user approval)
+- P0-1: Auth-Bypass entfernt ✅
-- Phase 7: Release (release_auditor) — final audit, handoff
+- P0-2: Migrationen repariert ✅
+- P0-3: Plugin-Upload deaktiviert ✅
+- P0-4: RLS FORCE + WITH CHECK ✅
+- P0-5: Plugin-Doppelregistrierung behoben ✅
+- P0-6: Persistent Volume ✅
+- P1-1: User/Tenant-Modell bereinigt ✅
+- P1-2: Redis zentralisiert ✅
+- P1-3: Worker ausgelagert ✅
+- P1-4: Transactional Outbox ✅
+- P1-5: XSS-Stellen geschlossen ✅
+- P1-6: DMS lastfest ✅
+- P1-7: Permission-System vereinheitlicht ✅
+- P1-8: Password Reset funktionsfähig ✅
+- P1-9: Metrics abgesichert ✅
+- P1-10: Coolify-Doku & Config korrigiert ✅
+- P1-11: Cross-Tenant FK ✅
+- P2-1: Contact Model normalisiert ✅
+- P2-3: Commands & Statusmaschinen ✅
+- P2-4: SPA Path-Traversal ✅
+
+### Offen (2)
+- P0-7: App von öffentlicher Domain nehmen (operational — 30 Min)
+- P2-2: Plugin-Cross-Imports reduzieren (228 Imports — 1-2 Wochen)
+
+## Previous: P1-4: Transactional Outbox — COMPLETE
+- Migration 0040_outbox.py created (down_revision=0039_contact_normalize)
+- event_outbox table: id, tenant_id, event_name, payload JSONB, status, attempts, max_attempts, next_retry_at, timestamps
+- app/core/outbox.py: enqueue_outbox_event() + process_outbox_batch() with FOR UPDATE SKIP LOCKED, exponential backoff retry
+- app/core/event_bus.py: added publish_with_results() for error-aware publishing; docstring note about outbox
+- app/core/worker.py: process_outbox_job cron (every 5s, Redis distributed lock)
+- app/services/contact_service.py: contact.created, lead.created, contact.updated → enqueue_outbox_event
+- app/models/outbox.py: SQLAlchemy ORM model for event_outbox
+- tests/test_outbox.py: 6 tests, all passing
+- py_compile: OK, alembic heads: single head 0040_outbox
+
+## Previous: P2-1: Unified Contact Model normalisieren — COMPLETE
+- Migration 0039_contact_normalize.py (down_revision=0038_dms_content_hash)

.a0/next_steps.md

@@ -1,4 +1,10 @@
 # LeoCRM — Next Steps
-1. Phase 6 COMPLETE — deployed to https://crm.media-on.de
+
-2. Phase 7: Release — final audit, handoff documentation
+## FIX-PLAN Offene Items (2026-07-26)
-3. Requires user approval for Phase 6 → Phase 7 transition
+1. P0-7: App von öffentlicher Domain nehmen (operational — 30 Min)
+2. P2-2: Plugin-Cross-Imports reduzieren (228 Imports — 1-2 Wochen)
+
+## Abgeschlossen
+- P2-1: Unified Contact Model normalisieren — COMPLETE
+- P1-4: Transactional Outbox — COMPLETE
+- 20/22 FIX-PLAN Items erledigt (siehe .a0/current_status.md)

.a0/risks.md

@@ -0,0 +1,200 @@
+# LeoCRM Security & Data Risk Assessment
+
+**Date:** 2026-07-26
+**Assessor:** Security Data Engineer (A0 Orchestrator)
+**Project:** LeoCRM at `/a0/usr/workdir/leocrm-fix`
+
+---
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | 5     |
+| HIGH     | 8     |
+| MEDIUM   | 8     |
+| LOW      | 5     |
+| **Total**| **26**|
+
+---
+
+## CRITICAL Issues
+
+### C-1: Redis Default Password `changeme` in docker-compose.yml
+**File:** `docker-compose.yml:53`
+**Risk:** Redis stores session data, CSRF tokens, and rate-limit counters. The default password `changeme` is trivially guessable. If Redis port 6379 is exposed, an attacker can read/modify all sessions, steal CSRF tokens, and bypass rate limits.
+**Remediation:** Remove the default fallback. Require `REDIS_PASSWORD` as a mandatory variable (`${REDIS_PASSWORD:?REDIS_PASSWORD is required}`). Use a strong randomly generated password in production.
+
+### C-2: No SECRET_KEY in `.env` — Insecure Default Active in Development
+**File:** `.env` (missing `SECRET_KEY`), `app/config.py:55`
+**Risk:** `.env` has no `SECRET_KEY`. The config defaults to `"change-me-in-production-use-a-secure-random-string"`. While `get_settings()` raises in production mode, `.env` sets `ENVIRONMENT=development`, so the default key is silently used. Any signing/token operation using `secret_key` is compromised.
+**Remediation:** Add a strong random `SECRET_KEY` (min 32 chars) to `.env`. Fail-fast in all environments if the default key is detected, not just production.
+
+### C-3: PostgreSQL and Redis Ports Exposed to Host
+**File:** `docker-compose.yml:37-38, 56-57`
+**Risk:** `ports: "5432:5432"` and `ports: "6379:6379"` expose the database and Redis to the host network. Combined with weak/default credentials, this allows direct external access to all session data and the entire database.
+**Remediation:** Remove port mappings for production. Use Docker internal networking only (`crm-net`). If debug access is needed, bind to `127.0.0.1:5432:5432` and document it as dev-only.
+
+### C-4: Unauthenticated Error Endpoint Forwards Data to External Forgejo
+**File:** `app/routes/errors.py:54-90`, `app/plugins/builtins/forgejo_error_reporter/service.py:151-250`
+**Risk:** The `/api/v1/errors` endpoint requires no authentication. CSRF middleware explicitly bypasses token checks for this path (line 48 of `middleware.py`). Any unauthenticated attacker can POST arbitrary error data (message, stack, URL, userAgent, and **arbitrary context dict**) which gets forwarded to an external Forgejo instance as a public issue. The `context` field accepts `dict[str, Any]` with no size limit on individual keys — an attacker can exfiltrate data or inject malicious content into Forgejo issues.
+**Remediation:** Require authentication for error reporting. If unauthenticated errors are needed, strip the `context` field entirely, add strict schema validation with size limits on all fields, and add a CAPTCHA or stricter rate limiting.
+
+### C-5: Plaintext Database Password in `.env`
+**File:** `.env:1`
+**Risk:** `DATABASE_URL=postgresql+asyncpg://leocrm:leocrm@localhost:5432/leocrm` embeds the DB password `leocrm` in plaintext. While `.gitignore` covers `.env`, the password is weak and identical to the username. If the file is accessed via any path traversal, backup leak, or container escape, the database is fully compromised.
+**Remediation:** Use a strong unique password. Separate `DATABASE_URL` construction from credential storage where possible (e.g., use individual `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_HOST`, `POSTGRES_DB` env vars and construct the URL in code).
+
+---
+
+## HIGH Issues
+
+### H-1: Rate Limiter Trusts X-Forwarded-For Without Validation
+**File:** `app/core/rate_limit.py:43-45`
+**Risk:** `get_client_ip()` blindly trusts the `X-Forwarded-For` header. An attacker can set arbitrary values to bypass rate limits on login, password reset, and other endpoints. Each request with a different spoofed IP creates a new rate-limit counter.
+**Remediation:** Only trust `X-Forwarded-For` from known proxy IPs. Configure a trusted proxy list and validate the header chain. Use Starlette's `ProxyHeadersMiddleware` or validate against a `TRUSTED_PROXIES` env var.
+
+### H-2: Duplicate `get_redis()` Functions — Connection Leak
+**File:** `app/core/auth.py:53-66` and `app/core/auth.py:94-96`
+**Risk:** Two `get_redis()` functions exist. The first (line 53) returns a singleton. The second (line 94) creates a **new Redis connection on every call**. Code importing `get_redis` may use either version. The middleware (line 69) creates its own Redis connection per request. This leads to connection pool exhaustion under load.
+**Remediation:** Remove the second `get_redis()` (line 94-96). Ensure all code uses the singleton version. The middleware should use `get_redis()` from `app.core.auth` instead of creating its own connection.
+
+### H-3: CSRF Middleware Creates New Redis Connection Per Request
+**File:** `app/core/middleware.py:69-90`
+**Risk:** For every unsafe HTTP request, the middleware creates a new `aioredis.from_url()` connection, uses it, then closes it. Under load, this creates thousands of connections and can exhaust Redis connection limits.
+**Remediation:** Use the global Redis singleton via `from app.core.auth import get_redis`. Remove the per-request connection creation and the `finally: await redis.close()` block.
+
+### H-4: CSRF Token Stored Plaintext in PostgreSQL
+**File:** `app/core/auth.py:141` (`SessionModel` stores `csrf_token`)
+**Risk:** The CSRF token is stored as plaintext in the PostgreSQL `sessions` table (audit trail). If the database is compromised, all active CSRF tokens are available for CSRF attacks.
+**Remediation:** Store only a hash of the CSRF token in PostgreSQL (like `hash_token()` already exists for session tokens). Compare hashes during validation.
+
+### H-5: No File Upload Validation in Storage Backend
+**File:** `app/core/storage.py:69-128`
+**Risk:** `LocalStorage` performs no validation on uploaded files:
+- No path traversal protection: `os.path.join(self.base_path, path)` with a malicious `path` containing `../../` can write anywhere on the filesystem
+- No file type/extension whitelist
+- No file size limit
+- No content-type validation
+- `get_url()` returns the full filesystem path, leaking internal directory structure
+**Remediation:** Sanitize `path` with `os.path.realpath()` and verify it's within `base_path`. Enforce file size limits, extension whitelist, and MIME type validation. Return relative paths from `get_url()`, not absolute filesystem paths.
+
+### H-6: WebSocket Connections Lack Authentication Verification
+**File:** `app/plugins/builtins/kommunikation/websocket_manager.py:23-28`, `app/plugins/builtins/ai_ui_control/websocket_manager.py:40-46`
+**Risk:** Both WebSocket managers accept connections via `connect(websocket, user_id)` without verifying that `user_id` is authenticated. The security depends entirely on the calling route. If any WebSocket route passes an untrusted `user_id` (e.g., from query params), an attacker can impersonate any user. There is also no origin verification on WebSocket connections.
+**Remediation:** Verify session cookie inside `connect()` before `websocket.accept()`. Validate the `Origin` header against allowed CORS origins. Add authentication middleware for WebSocket routes.
+
+### H-7: In-Memory Rate Limiter in Error Endpoint — Fails with Multiple Workers
+**File:** `app/routes/errors.py:21-40`
+**Risk:** The error endpoint uses a process-local `defaultdict(deque)` for rate limiting. With multiple Uvicorn workers (common in production), each worker has its own counter. An attacker can make `RATE_LIMIT * num_workers` requests per minute.
+**Remediation:** Use the Redis-based `check_rate_limit()` from `app/core/rate_limit.py` instead of the in-memory implementation.
+
+### H-8: No CSRF Protection on WebSocket Connections
+**File:** Both WebSocket managers
+**Risk:** WebSocket connections are not protected against CSRF. A malicious site can open a WebSocket to the CRM backend via JavaScript `new WebSocket()` and send commands as the authenticated user (cookies are sent automatically with SameSite=Strict for same-site, but cross-site WebSocket hijacking is still possible if SameSite is configured differently or cookies are sent via `credentials`).
+**Remediation:** Verify the `Origin` header on WebSocket upgrade requests. Reject connections from untrusted origins.
+
+---
+
+## MEDIUM Issues
+
+### M-1: Login Response Leaks `is_system_admin` Flag
+**File:** `app/routes/auth.py:78`
+**Risk:** The login response includes `"is_system_admin": user.is_system_admin`. An attacker who compromises a session or intercepts the response knows whether the account has system-wide privileges, enabling targeted attacks.
+**Remediation:** Do not include `is_system_admin` in the login response. The frontend can determine admin status via the `/me/permissions` endpoint.
+
+### M-2: Weak Password Validation — No Complexity Requirements
+**File:** `app/schemas/auth.py:10` (login: `min_length=1`), `app/schemas/user.py:11` (create: `min_length=8`)
+**Risk:** Login accepts any password length (min_length=1). User creation requires min 8 chars but no complexity (uppercase, lowercase, digits, special chars). Users can set passwords like `aaaaaaaa`.
+**Remediation:** Add password complexity validation (min 12 chars, mixed case, digits, special chars) for user creation and password reset. Keep login min_length=1 to avoid leaking whether the password was partially correct.
+
+### M-3: F-String Interpolation of Table/Column Names in Raw SQL
+**File:** `app/plugins/builtins/unified_search/embedding.py:194`, `search_engine.py:153`, `routes.py:294,300`, `jobs.py:183,228`
+**Risk:** Multiple raw SQL queries use f-strings to interpolate table and column names: `f"UPDATE {table} SET ..."`, `f"SELECT {emb_col} FROM {table_name} ..."`. While the values come from hardcoded `table_map` dicts (not user input), this pattern is fragile — a future change could introduce user-controlled values into the map.
+**Remediation:** Use SQLAlchemy ORM queries instead of raw SQL where possible. If raw SQL is needed, validate table/column names against an allowlist before interpolation, or use `sqlalchemy.sql.quoted_name` for safe identifier quoting.
+
+### M-4: Forgejo Error Reporter Sends Full Context to External Service
+**File:** `app/plugins/builtins/forgejo_error_reporter/service.py:196-199`
+**Risk:** The error reporter serializes the entire `context` dict into the Forgejo issue body as JSON. If frontend error reporting includes sensitive data (user tokens, PII, tenant data), it will be written to an external Forgejo repository as a public issue.
+**Remediation:** Add a field-level allowlist for context data. Strip or redact sensitive keys (tokens, passwords, emails, phone numbers). Consider making Forgejo issues private/confidential.
+
+### M-5: Config Has Hardcoded Default Secret Key
+**File:** `app/config.py:55`
+**Risk:** The default `secret_key = "change-me-in-production-use-a-secure-random-string"` is a known public value. While production mode checks for it, development mode silently uses it. If dev environments are exposed (even temporarily), all signed tokens are forgeable.
+**Remediation:** Remove the default value entirely. Make `secret_key` a required field with no default. Fail in all environments if not set.
+
+### M-6: `LocalStorage.get_url()` Returns Absolute Filesystem Path
+**File:** `app/core/storage.py:116-117`
+**Risk:** `get_url()` returns `self._full_path(path)` which is the absolute filesystem path (e.g., `/data/uploads/tenant1/file.pdf`). If this URL is returned to the frontend or used in API responses, it leaks the internal directory structure and can aid path traversal attacks.
+**Remediation:** Return a relative path or a signed download URL that routes through an authenticated API endpoint.
+
+### M-7: Inconsistent Environment Configuration in `.env`
+**File:** `.env:3,4`
+**Risk:** `.env` sets `ENVIRONMENT=development` but `SESSION_COOKIE_SECURE=true`. In development with HTTP, secure cookies won't be sent, causing auth failures. More importantly, the `ENVIRONMENT=development` setting disables the production safety checks in `get_settings()`, allowing the default `SECRET_KEY` to be used.
+**Remediation:** Use separate `.env.development` and `.env.production` files. Ensure development configs are never accidentally deployed.
+
+### M-8: Permission Cache Falls Back to Stale Data on DB Error
+**File:** `app/core/permissions.py:337-344`
+**Risk:** When `_get_current_permission_version()` fails (DB error), the code sets `current_version = cached_version` and uses potentially stale cached permissions. If a user's permissions were revoked during the DB outage, they retain elevated access.
+**Remediation:** On DB error, either fail closed (deny access) or use a shorter stale-while-error TTL. Log the event as a security incident.
+
+---
+
+## LOW Issues
+
+### L-1: `document.write()` with DOM Clone in Print Utility
+**File:** `frontend/src/utils/print.ts:54, 127`
+**Risk:** `printElement()` and `exportToPDF()` use `document.write()` with `clone.outerHTML`. If the printed DOM element contains user-controlled content (e.g., contact notes with HTML), it executes in a new window context. The new window is same-origin, limiting the impact, but it's still an unnecessary risk.
+**Remediation:** Use DOM APIs (`appendChild`, `importNode`) instead of `document.write()`. Alternatively, sanitize the cloned HTML before writing.
+
+### L-2: Session Data Stored in Redis Without Encryption
+**File:** `app/core/auth.py:130-134`
+**Risk:** Session data (user_id, tenant_id, email, role, csrf_token, is_system_admin) is stored as plaintext JSON in Redis. Anyone with Redis access can read all active sessions.
+**Remediation:** Encrypt session data before storing in Redis, or accept the risk given Redis should be network-isolated. At minimum, ensure Redis requires authentication and is not exposed.
+
+### L-3: No Security Headers Middleware
+**File:** No security headers middleware found
+**Risk:** The application does not set security headers like `X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security`, `Content-Security-Policy`.
+**Remediation:** Add a security headers middleware or use `starlette-securehead`/`secure` package.
+
+### L-4: No Origin Verification on WebSocket Upgrade
+**File:** Both WebSocket managers
+**Risk:** Neither WebSocket manager checks the `Origin` header before accepting connections. While cookies with `SameSite=Strict` provide some protection, some browsers and non-browser clients may not respect SameSite on WebSocket connections.
+**Remediation:** Check `websocket.headers.get("origin")` against `settings.cors_origin_list` before calling `websocket.accept()`.
+
+### L-5: Unbounded Feedback/Command Storage in AI UI Control WebSocket
+**File:** `app/plugins/builtins/ai_ui_control/websocket_manager.py:94-103`
+**Risk:** `store_feedback()` stores feedback dicts without size limits. `cleanup_stale()` only runs when explicitly called. An attacker who can send WebSocket messages could fill memory with large feedback payloads.
+**Remediation:** Add size limits on feedback payloads. Run `cleanup_stale()` on a timer or on each `connect()`/`disconnect()`.
+
+---
+
+## Positive Findings
+
+1. **Dockerfile security:** Multi-stage build, non-root user (`appuser` UID 1000), healthcheck configured, no secrets baked into image.
+2. **RLS implementation:** PostgreSQL Row Level Security with `FORCE` (migration 0028) ensures tenant isolation even for table owners. `set_tenant_context()` uses parameterized queries.
+3. **Password hashing:** bcrypt with configurable rounds (default 12).
+4. **Session tokens:** `secrets.token_urlsafe(32)` — cryptographically secure.
+5. **XSS protection:** `HtmlBlock.tsx` and `SignatureManager.tsx` use `DOMPurify.sanitize()` before `dangerouslySetInnerHTML`.
+6. **RBAC architecture:** Deny-list takes precedence over allow-list. Field-level permissions with strictest-wins merging. Permission version-based cache invalidation.
+7. **No user enumeration:** Password reset endpoint always returns 200.
+8. **SQL injection:** ORM queries use parameterized statements throughout. Raw SQL in `unified_search` uses hardcoded maps (not directly exploitable).
+9. **`.gitignore`** properly covers `.env`, `.env.*`, and excludes example files.
+10. **Production safety checks** in `get_settings()` validate `SECRET_KEY`, `SESSION_COOKIE_SECURE`, and `STORAGE_PATH`.
+
+---
+
+## Migration & Data Loss Risks
+
+1. **RLS policies:** Multiple migrations (0001, 0002, 0004, 0015, 0021, 0028) create and modify RLS policies. Migration 0028 adds `FORCE ROW LEVEL SECURITY`. Ensure all migrations are applied in order before production deployment.
+2. **Backup risk:** No backup/restore procedure found in the repository. The `last_backup_at` system setting is referenced in automation jobs but no backup script exists.
+3. **Volume persistence:** `docker-compose.yml` defines named volumes for `pgdata`, `redisdata`, and `storage`. Good for persistence, but no backup strategy documented.
+4. **Migration rollback:** Down migrations exist but should be tested. RLS policy down migrations disable RLS — running a rollback in production would expose all tenant data.
+
+---
+
+## Remediation Priority
+
+1. **Immediate (before any production deploy):** C-1, C-2, C-3, C-4, C-5, H-1, H-2, H-3
+2. **Short-term (within 1 sprint):** H-4, H-5, H-6, H-7, H-8, M-1, M-2, M-5
+3. **Medium-term (within 2 sprints):** M-3, M-4, M-6, M-7, M-8, L-1, L-2, L-3, L-4, L-5

.a0/worklog.md

@@ -1,4 +1,26 @@
 
+## P1-4 — Transactional Outbox — COMPLETE ✅
+**Date**: 2026-07-25 19:17
+**Tests**: 6/6 outbox tests pass
+**Migration**: 0040_outbox.py (down_revision=0039_contact_normalize)
+
+### Files Created (4 new)
+- alembic/versions/0040_outbox.py — event_outbox table with indexes
+- app/core/outbox.py — enqueue_outbox_event() + process_outbox_batch() with retry/backoff
+- app/models/outbox.py — SQLAlchemy ORM model
+- tests/test_outbox.py — 6 tests (enqueue, publish, retry, max_attempts, batch_size, empty)
+
+### Files Modified (4)
+- app/core/event_bus.py — added publish_with_results(); docstring note about outbox for domain events
+- app/core/worker.py — process_outbox_job cron (every 5s, Redis distributed lock via _wrap_cron_with_lock)
+- app/services/contact_service.py — contact.created, lead.created, contact.updated → enqueue_outbox_event
+- tests/conftest.py — import EventOutbox model; add event_outbox to TRUNCATE list
+
+### Verification
+- py_compile: ALL OK
+- alembic heads: single head 0040_outbox
+- pytest tests/test_outbox.py: 6/6 PASSED
+- test_contacts.py: 5 failed (pre-existing 403 RBAC issue, confirmed via git stash)
 
 ## T03 — Plugin System Framework — COMPLETE ✅
 **Date**: 2026-06-29 01:20
@@ -203,3 +225,13 @@
 - **Commit:** 69e91fd
 
 ## 🎉 PHASE 3 COMPLETE — ALL 14 TASKS DONE
+
+## 2026-07-25 19:07 — P2-1: Unified Contact Model normalisieren — COMPLETE
+- **6 files changed** (5 modified + 1 new migration)
+- **Migration 0039_contact_normalize.py**: surfix→suffix rename, Float→Numeric(5,2) for 6 discount columns with CHECK constraints (0-100), JSON→JSONB for contacts.custom and contactpersons.custom, partial unique indexes on (tenant_id, code) and (tenant_id, accounting_code)
+- **Model**: surfix→suffix, Float→Numeric(5,2), JSON→JSONB, UniqueConstraint added, Decimal import
+- **Schema**: surfix→suffix (3x), float→Decimal (18x), Decimal import
+- **Services**: contact_service.py (3x surfix→suffix), dedup_service.py (1x surfix→suffix)
+- **Frontend**: unifiedContacts.ts surfix→suffix in UnifiedContact interface
+- **Checks**: py_compile OK, alembic heads → 0039_contact_normalize (single head), comprehensive grep confirms zero surfix in source code
+- **Tests**: 1 passed, 5 failed (pre-existing 403/404 errors unrelated to P2-1)

.env.docker.example

@@ -15,23 +15,48 @@ POSTGRES_USER=crm_user
 POSTGRES_PASSWORD=STRONG_PASSWORD_HERE
 POSTGRES_DB=crm_db
 
-# --- CRM Application ----------------------------------------------------------
+# --- Redis (REQUIRED) ---------------------------------------------------------
-# The host "postgres" is the docker-compose service name (internal DNS).
+# Generate a strong password:
-# The DRIVER is asyncpg for production PostgreSQL.
+#   python -c "import secrets; print(secrets.token_urlsafe(24))"
-DATABASE_URL=postgresql+asyncpg://crm_user:STRONG_PASSWORD_HERE@postgres:5432/crm_db
+REDIS_PASSWORD=STRONG_REDIS_PASSWORD_HERE
 
-# --- AUTH_SECRET (REQUIRED, min 32 chars) ------------------------------------
+# --- CRM Application: Runtime DB user (NOSUPERUSER, NOBYPASSRLS) --------------
+# The app and worker use crm_runtime — RLS is enforced.
+# This user is created by migration 0044 with DML-only permissions.
+# Set RUNTIME_DB_PASSWORD to the password you want for crm_runtime.
+RUNTIME_DB_PASSWORD=STRONG_RUNTIME_PASSWORD_HERE
+DATABASE_URL=postgresql+asyncpg://crm_runtime:STRONG_RUNTIME_PASSWORD_HERE@postgres:5432/crm_db
+
+# --- CRM Application: Migration DB user (owner, can run DDL) -----------------
+# Migrations and DDL operations use the owner user (crm_user).
+# This is NOT used by the app at runtime — only by prestart.sh / alembic.
+MIGRATION_DATABASE_URL=postgresql+asyncpg://crm_user:STRONG_PASSWORD_HERE@postgres:5432/crm_db
+
+# --- SECRET_KEY (REQUIRED, min 32 chars) -------------------------------------
 # Session signing secret. MUST be at least 32 characters.
 # Generate with:
 #   python -c "import secrets; print(secrets.token_urlsafe(48))"
-AUTH_SECRET=MIN_32_CHARS_GENERATE_WITH_secrets_token_urlsafe_32_xxxxxxxxxxxx
+SECRET_KEY=MIN_32_CHARS_GENERATE_WITH_secrets_token_urlsafe_32_xxxxxxxxxxxx
+
+# --- Frontend URL (for email links) ------------------------------------------
+# The public URL where users access the LeoCRM frontend.
+# Used for password reset links, invitations, etc.
+FRONTEND_URL=https://crm.example.com
 
 # --- CORS / environment -------------------------------------------------------
 # Comma-separated, NO wildcards. In dev we allow localhost:8000 (the app) and
 # :5173 (e.g. Vite dev server). In production, restrict to the real domain.
-CORS_ORIGINS=http://localhost:8000,http://localhost:5173
+CORS_ORIGINS=https://crm.example.com
 ENVIRONMENT=production
 LOG_LEVEL=INFO
 
-# --- bcrypt tuning (keep aligned with .env.example) --------------------------
+# --- SMTP (for password reset emails) -----------------------------------------
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USERNAME=noreply@example.com
+SMTP_PASSWORD=YOUR_SMTP_PASSWORD
+SMTP_FROM_EMAIL=noreply@example.com
+SMTP_USE_TLS=true
+
+# --- bcrypt tuning ----------------------------------------------------------
 BCRYPT_ROUNDS=12

.env.example

@@ -1,9 +1,16 @@
 # LeoCRM v1.0 - Environment Variables Template
 
 # === REQUIRED ===
-DATABASE_URL=postgresql+asyncpg://leocrm:leocrm@localhost:5432/leocrm
+DATABASE_URL=postgresql+asyncpg://crm_api:your_password@localhost:5432/crm_db
+AUTH_DATABASE_URL=postgresql+asyncpg://crm_auth:your_password@localhost:5432/crm_db
+WORKER_DATABASE_URL=postgresql+asyncpg://crm_worker:your_password@localhost:5432/crm_db
+MIGRATION_DATABASE_URL=postgresql+asyncpg://crm_migration:your_password@localhost:5432/crm_db
 REDIS_URL=redis://localhost:6379/0
 
+# === REQUIRED for Docker/Production ===
+# Redis password (required in Docker)
+REDIS_PASSWORD=your_redis_password
+
 # === OPTIONAL (with defaults) ===
 
 # Environment: development | production | testing

.forgejo/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: Install Python deps
+        run: pip install -r requirements.txt
+      - name: Install Frontend deps
+        run: cd frontend && npm ci
+      - name: Run CI/CD Pipeline
+        run: bash scripts/ci_pipeline.sh

.github/workflows/check-cross-plugin-imports.yml

@@ -0,0 +1,25 @@
+# CI/CD: Check for forbidden cross-plugin imports on every push/PR
+
+name: Check Cross-Plugin Imports
+
+on:
+  push:
+    paths:
+      - 'app/plugins/**'
+      - 'scripts/check_cross_plugin_imports.py'
+  pull_request:
+    paths:
+      - 'app/plugins/**'
+      - 'scripts/check_cross_plugin_imports.py'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Check cross-plugin imports
+        run: python scripts/check_cross_plugin_imports.py

.gitignore

@@ -28,8 +28,34 @@ ENV/
 htmlcov/
 coverage.xml
 .mypy_cache/
+
+# Redis dump
+*.rdb
+dump.rdb
+
+# Frontend build output (regenerated on deploy)
+frontend/dist/
+frontend/node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
 .ruff_cache/
 
+# Redis dumps
+dump.rdb
+*.rdb
+
 # Database files
 *.db
 *.db-journal

.pre-commit-cross-plugin.yaml

@@ -0,0 +1,14 @@
+# Pre-commit hook: Check for forbidden cross-plugin imports
+# Install: pip install pre-commit && pre-commit install
+# Or run manually: python scripts/check_cross_plugin_imports.py
+
+repos:
+  - repo: local
+    hooks:
+      - id: check-cross-plugin-imports
+        name: Check cross-plugin imports
+        entry: python scripts/check_cross_plugin_imports.py
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [commit]

AGENTS.md

@@ -12,7 +12,7 @@
 
 #### Setup
 ```bash
-cd backend
+
 python -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
@@ -20,13 +20,13 @@ pip install -e ".[dev]"
 
 #### Run Dev Server
 ```bash
-cd backend
+
 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 ```
 
 #### Database Migrations (Alembic)
 ```bash
-cd backend
+
 # Generate migration after model changes
 alembic revision --autogenerate -m "description"
 # Apply migrations
@@ -37,37 +37,37 @@ alembic downgrade -1
 
 #### Run All Backend Tests
 ```bash
-cd backend
+
 python -m pytest -v --tb=short
 ```
 
 #### Run Specific Test File
 ```bash
-cd backend
+
 python -m pytest tests/test_auth.py -v --tb=short
 ```
 
 #### Run Tests with Coverage
 ```bash
-cd backend
+
 python -m pytest --cov=app --cov-report=term-missing --cov-report=html
 ```
 
 #### Run Tests with Grep Filter
 ```bash
-cd backend
+
 python -m pytest -k 'tenant or auth' -v
 ```
 
 #### Type Checking
 ```bash
-cd backend
+
 mypy app/ --ignore-missing-imports
 ```
 
 #### Linting
 ```bash
-cd backend
+
 ruff check app/
 ruff format app/
 ```

COOLIFY_SETUP.md

@@ -3,13 +3,15 @@
 Production deployment guide for the **CRM System** to the Coolify PaaS instance
 at `server.media-on.de` (server UUID `lw80w8scs4044gwcw084s00s4`).
 
-The deploy consists of **two Coolify resources** in the same project/environment:
+The deploy consists of **three Coolify resources** in the same project/environment:
 
 1. A **PostgreSQL 16** database resource (one-click or Docker image).
 2. The **crm-app** Application (Dockerfile build from a Git repository).
+3. The **crm-worker** Application (same Dockerfile build, different entrypoint).
 
-The two resources talk to each other over the internal Docker network. The app
+The resources talk to each other over the internal Docker network. The app
 is exposed publicly on `https://crm.media-on.de:443` (Let's Encrypt via Coolify).
+The worker is not exposed publicly — it only needs Redis and PostgreSQL access.
 
 ---
 
@@ -114,8 +116,7 @@ In **crm-app → Environment Variables**, set:
 | `ENVIRONMENT` | `production` | |
 | `LOG_LEVEL` | `INFO` | `DEBUG` only temporarily. |
 | `BCRYPT_ROUNDS` | `12` | Aligned with `.env.example`. |
-| `JWT_ALGORITHM` | `HS256` | Aligned with `.env.example`. |
+
-| `JWT_EXPIRY_HOURS` | `24` | Aligned with `.env.example`. |
 
 ### Secret generation (run once, locally)
 
@@ -142,9 +143,7 @@ are still rendered in the UI to anyone with read access to the environment.
 >       {"key":"CORS_ORIGINS",         "value":"https://crm.media-on.de:443"},
 >       {"key":"ENVIRONMENT",          "value":"production"},
 >       {"key":"LOG_LEVEL",            "value":"INFO"},
->       {"key":"BCRYPT_ROUNDS",        "value":"12"},
+>       {"key":"BCRYPT_ROUNDS",        "value":"12"}
->       {"key":"JWT_ALGORITHM",        "value":"HS256"},
->       {"key":"JWT_EXPIRY_HOURS",     "value":"24"}
 >     ]
 >   }'
 > ```
@@ -174,7 +173,7 @@ In **crm-app → Domains → + Add Domain**:
 
 In **crm-app → Advanced → Healthcheck**:
 
-- **Healthcheck path**: `/health`
+- **Healthcheck path**: `/api/v1/health`
 - **Healthcheck method**: `GET`
 - **Healthcheck interval**: `30s`
 - **Healthcheck timeout**: `10s`
@@ -267,3 +266,52 @@ For full incident response, see [`/a0/.a0/runbook-restore.md`](../../a0/runbook-
 - App architecture (Section 13 lockdown) — `/a0/.a0/02-architecture.md`
 - Task graph (Phase 4d) — `/a0/.a0/03-task-graph.json`
 - Restore runbook — `/a0/.a0/runbook-restore.md`
+
+---
+
+## 11. Resource C — crm-worker (Background Worker)
+
+The crm-worker runs the ARQ background worker and scheduler in a separate
+container, using the same Docker image as crm-app but with a different
+entrypoint (`/app/worker.sh` instead of `/app/prestart.sh`).
+
+### Setup in Coolify UI
+
+1. In the same project/environment as crm-app, **+ Add → Application →
+   Public/Private Repository**.
+2. Fill in:
+   - **Git repository**: same as crm-app (`https://forgejo.media-on.de/Leopoldadmin/leocrm.git`)
+   - **Branch**: `main`
+   - **Build pack**: `Dockerfile`
+   - **Dockerfile location**: `Dockerfile` (same image)
+   - **Port**: `8000` (not used, but Coolify requires a port)
+   - **Custom Entrypoint**: `/app/worker.sh`
+3. Click **Deploy** once to create the resource.
+4. Note the **Application UUID**.
+
+### Environment variables (on the crm-worker resource)
+
+Set the same variables as crm-app, except:
+
+| Key | Value | Notes |
+|-----|-------|-------|
+| `DATABASE_URL` | same as crm-app | |
+| `REDIS_URL` | same as crm-app | |
+| `SECRET_KEY` | same as crm-app | |
+| `ENVIRONMENT` | `production` | |
+| `LOG_LEVEL` | `INFO` | |
+| `STORAGE_PATH` | `/data/storage` | |
+
+No domain is needed — the worker is not publicly accessible.
+
+### Healthcheck (Coolify side)
+
+- **Healthcheck path**: `/api/v1/health` (not used by worker, but Coolify requires one)
+- Alternatively, use a custom healthcheck command:
+  `pgrep -f "arq app.core.worker.WorkerSettings" || exit 1`
+
+### Scaling
+
+To scale the worker horizontally, deploy multiple crm-worker instances.
+Cron jobs use a Redis-based distributed lock (`SET NX` with TTL) so only
+one replica executes each scheduled job.

DEPLOY.md

@@ -0,0 +1,172 @@
+# LeoCRM Deployment
+
+## Quick Start
+
+### Option A: Coolify (empfohlen für Produktion)
+
+```bash
+# Einmalig: Umgebungsvariablen setzen
+export COOLIFY_API_TOKEN="dein-token"
+export COOLIFY_APP_UUID="deine-app-uuid"
+
+# Deploy
+python scripts/deploy.py
+
+# Redeploy (ohne Neubuild)
+python scripts/deploy.py --skip-build
+```
+
+Das Script macht automatisch:
+1. Coolify Build & Deploy triggern
+2. Persistent Volume in Coolify DB konfigurieren (automatisch, portabel)
+3. Auf healthy Container warten
+4. RLS auf allen Tenant-Tabellen sicherstellen
+5. DB-Migrationen verifizieren
+6. Worker-Container starten
+7. App-Health verifizieren
+8. Domain-Erreichbarkeit prüfen
+
+**Funktioniert auf jeder Coolify-Instanz. Bei mehreren Apps. Bei Erst-Deploy und Redeploy.**
+
+### Option B: Docker Compose (lokal / ohne Coolify)
+
+```bash
+# .env.docker erstellen
+cp .env.docker.example .env.docker
+$EDITOR .env.docker  # SECRET_KEY, POSTGRES_PASSWORD, etc. ausfüllen
+
+# Starten (alle 4 Container: Postgres, Redis, App, Worker)
+docker compose --env-file .env.docker up --build -d
+
+# Health check
+curl http://localhost:8000/api/v1/health
+
+# Stoppen
+docker compose down
+```
+
+**Container:**
+- `crm-postgres` — PostgreSQL 16 mit pgvector
+- `crm-redis` — Redis 7
+- `crm-app` — FastAPI API Server
+- `crm-worker` — ARQ Background Worker
+
+Alle mit persistenten Volumes. Kein Datenverlust bei Redeploy.
+
+## Voraussetzungen
+
+- Python 3.12+
+- Docker & Docker Compose (für Option B)
+- Coolify v4+ (für Option A)
+- SSH-Zugang zum Server (für Option A)
+
+## Umgebungsvariablen
+
+Siehe `.env.example` für alle Variablen. Wichtigste:
+
+| Variable | Pflicht | Default | Beschreibung |
+|---|---|---|---|
+| `DATABASE_URL` | Ja | — | PostgreSQL Connection String |
+| `REDIS_URL` | Ja | — | Redis Connection String |
+| `SECRET_KEY` | Ja | — | Mindestens 32 Zeichen |
+| `ENVIRONMENT` | Nein | `development` | `production` oder `development` |
+| `SESSION_COOKIE_SECURE` | Nein | `true` | In Production muss `true` |
+| `STORAGE_PATH` | Nein | `/data/storage` | Datei-Upload-Pfad |
+| `STORAGE_BACKEND` | Nein | `local` | `local` oder `s3` |
+
+## S3 Storage (optional)
+
+Die App unterstützt S3-kompatiblen Storage. Setze:
+```bash
+STORAGE_BACKEND=s3
+S3_ENDPOINT=https://s3.example.com
+S3_BUCKET=leocrm
+S3_ACCESS_KEY=...
+S3_SECRET_KEY=...
+```
+
+## Test- vs. Produktionsumgebung
+
+**Test:**
+```bash
+python scripts/deploy.py --environment test
+```
+Eigene Coolify-App, eigene DB, eigene Domain (`crm-test.media-on.de`).
+
+**Produktion:**
+```bash
+python scripts/deploy.py --environment production
+```
+
+## Troubleshooting
+
+**Container nicht healthy:**
+```bash
+docker logs <container-name> --tail 50
+```
+
+**Migration fehlgeschlagen:**
+```bash
+docker exec <container> alembic upgrade head
+```
+
+**RLS nicht aktiv:**
+```bash
+python scripts/deploy.py --migrate-only
+```
+
+**Worker nicht gestartet:**
+```bash
+python scripts/deploy.py --skip-build  # startet Worker automatisch
+```
+
+## Backup & Restore
+
+### Backup (PostgreSQL)
+
+```bash
+# Full DB backup (run on the host or via docker exec)
+docker exec crm-postgres pg_dump -U crm_user -Fc crm_db > backup_$(date +%Y%m%d_%H%M%S).dump
+
+# Backup mit Custom-Format (komprimiert, parallel restore-fähig)
+docker exec crm-postgres pg_dump -U crm_user -Fc -Z 9 crm_db > backup_$(date +%Y%m%d).dump
+```
+
+### Backup (Redis — Sessions/Queues)
+
+```bash
+# Redis RDB Snapshot
+docker exec crm-redis redis-cli -a "$REDIS_PASSWORD" SAVE
+docker cp crm-redis:/data/dump.rdb redis_backup_$(date +%Y%m%d).rdb
+```
+
+### Backup (File Storage)
+
+```bash
+# Local storage volume
+docker run --rm -v leocrm-fix_storage:/data -v $(pwd):/backup alpine \
+  tar czf /backup/storage_$(date +%Y%m%d).tar.gz /data
+```
+
+### Restore (PostgreSQL)
+
+```bash
+# Stop app containers
+docker compose stop crm-app crm-worker
+
+# Restore DB
+docker exec -i crm-postgres pg_restore -U crm_user -d crm_db --clean < backup_20260726.dump
+
+# Restart app
+docker compose start crm-app crm-worker
+```
+
+### Automatisierte Backups (Cron)
+
+```bash
+# /etc/cron.d/leocrm-backup
+0 2 * * * root docker exec crm-postgres pg_dump -U crm_user -Fc crm_db > /backups/leocrm_$(date +\%Y\%m\%d).dump
+0 3 * * * root find /backups -name 'leocrm_*.dump' -mtime +30 -delete
+```
+
+**Empfehlung:** Tägliche DB-Backups, 30 Tage Aufbewahrung. Storage-Backup wöchentlich.

Dockerfile

@@ -30,6 +30,11 @@ RUN apt-get update \
  && apt-get install -y --no-install-recommends \
         build-essential \
         libpq-dev \
+        libpango-1.0-0 \
+        libpangoft2-1.0-0 \
+        libcairo2 \
+        libgdk-pixbuf-2.0-0 \
+        libffi-dev \
  && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -50,6 +55,11 @@ RUN apt-get update \
  && apt-get install -y --no-install-recommends \
         libpq5 \
         curl \
+        libpango-1.0-0 \
+        libpangoft2-1.0-0 \
+        libcairo2 \
+        libgdk-pixbuf-2.0-0 \
+        libffi8 \
  && rm -rf /var/lib/apt/lists/* \
  && groupadd -g 1000 appuser \
  && useradd -m -u 1000 -g appuser appuser
@@ -65,8 +75,8 @@ COPY --chown=appuser:appuser . .
 # Copy built frontend from frontend stage
 COPY --from=frontend --chown=appuser:appuser /frontend/dist /app/frontend/dist
 
-# Make prestart.sh executable
+# Make entrypoint scripts executable
-RUN chmod +x /app/prestart.sh
+RUN chmod +x /app/prestart.sh /app/worker.sh /app/healthcheck.sh
 
 # Create storage directory
 RUN mkdir -p /data/storage && chown -R appuser:appuser /data
@@ -76,6 +86,6 @@ USER appuser
 EXPOSE 8000
 
 HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
-    CMD curl -fsS http://localhost:8000/api/v1/health || exit 1
+    CMD /app/healthcheck.sh
 
 ENTRYPOINT ["/app/prestart.sh"]

ENTERPRISE_RBAC_PLAN.md

@@ -0,0 +1,210 @@
+# Enterprise RBAC Plan — LeoCRM
+
+## Gesamt: 23 Sprints, 74 Features, 230h
+
+### Sprint 1 — Fundament (14h)
+- [ ] entity_permissions Tabelle + expires_at + Migration 0049
+- [ ] OwnedMixin + owner_id auf allen Models + Migration 0050
+- [ ] Universeller Permission Service (CRUD + get_effective_access + get_visible_ids)
+- [ ] Universelle Permission API (5 Endpoints)
+- [ ] Redis-Cache für Entity-Permissions (Bitmap)
+- [ ] PostgreSQL RLS Policies + set_user_context()
+- [ ] Rate Limiting auf Permission-Änderungen
+- [ ] Folder ACLs in entity_permissions migrieren (Migration 0051)
+
+### Sprint 2 — Row-Level Security (16h)
+- [ ] apply_visibility_filter() Helper
+- [ ] Query-Filter in alle 28 Routes
+- [ ] Child-Entity-Vererbung
+- [ ] Batch-Resolution
+- [ ] BaseSearchProvider mit Visibility-Filter
+- [ ] ContactDetail/ContactsList Permission-Checks
+- [ ] Copy/Duplicate Permission
+- [ ] EXISTS-Optimization für RLS
+
+### Sprint 3 — Search/Dashboard/Export (13h)
+- [ ] GlobalSearch Visibility-Filter
+- [ ] Two-Phase Search
+- [ ] Search-Index Pre-Filter
+- [ ] Dashboard-Counts pro User
+- [ ] Export-Filter
+- [ ] Reports-Filter
+- [ ] Frontend-Filter für alle 4
+
+### Sprint 4 — Field-Level komplett (10h)
+- [ ] Custom Field Sensitivity
+- [ ] Field Definitions für alle Entities + Plugin-Registration
+- [ ] filter_fields_by_permission() in alle Responses
+- [ ] Field-Level Permission Editor UI
+- [ ] Frontend: readonly/hidden in ContactDetail + ContactsList + DMS + Mail + AI
+
+### Sprint 5 — Sharing UI (8h)
+- [ ] Universeller ShareDialog Komponente
+- [ ] Share-Button in 8 Detail-Ansichten
+- [ ] Owner-Spalte in 8 Listen
+- [ ] Permission-UI (Buttons ausblenden)
+- [ ] Permission-Expiration UI
+
+### Sprint 6 — Notifications + Audit + Real-time (10h)
+- [ ] Permission-Change-Notifications
+- [ ] Audit-Trail für Permission-Änderungen
+- [ ] Notification-Entity-Filter
+- [ ] Real-time WebSocket Sync
+- [ ] Redis Pub/Sub für WebSocket Fan-Out
+
+### Sprint 7 — E-Mail Postfächer (8h)
+- [ ] Mailbox owner_id + Migration
+- [ ] Mailbox Permissions (entity_permissions)
+- [ ] Mail Permission Migration
+- [ ] Mail-Query-Filter
+- [ ] Mail-Field-Level
+- [ ] Frontend: Mailbox-Liste + Mail-Liste + Mail-Detail
+
+### Sprint 8 — Plugin Entities (14h)
+- [ ] DMS owner_id + Permissions + Migration
+- [ ] Calendar owner_id + Permissions + Migration
+- [ ] Tasks owner_id + Permissions + Migration
+- [ ] Kommunikation RBAC Migration
+- [ ] Entity Links Permission
+- [ ] Tags Permission
+- [ ] 15 Plugin Entity Registration
+- [ ] DMS Permission Migration
+- [ ] Folder-Path-Materialization
+- [ ] Frontend Permission-Checks für DMS + Calendar + Tasks
+
+### Sprint 9 — App-Sichtbarkeit (7h)
+- [ ] Plugin Manifest permission Feld
+- [ ] tenant_plugin_activation Tabelle + API
+- [ ] Sidebar Permission-Filter
+- [ ] TopBar Permission-Filter
+- [ ] Settings-Navigation Permission-Filter
+- [ ] Route-Guards (ProtectedRoute)
+
+### Sprint 10 — Advanced Security + AI + WebSocket (18h)
+- [ ] API-Token Scopes
+- [ ] Webhook Scope Filter
+- [ ] Workflow Scope Filter
+- [ ] Contact Merge Permission-Check
+- [ ] AI Copilot Permission-Aware (process_query + execute_action)
+- [ ] AI Tool Registry
+- [ ] AI System Prompt mit Permission-Context
+- [ ] AI Proactive Permission-Aware
+- [ ] AI UI Control Permission-Checks
+- [ ] MCP Permission-Scopes
+- [ ] Automation Permission-Checks
+- [ ] WebSocket Permission-Checks
+- [ ] Event Bus Permission-Filter
+- [ ] Frontend: AI + Notifications + Workflows + DedupMerge
+
+### Sprint 11 — Owner Management (5h)
+- [ ] Owner-Transfer (Bulk) API
+- [ ] Auto-Transfer bei User-Deaktivierung
+- [ ] Backup/Restore Permissions
+- [ ] Frontend Owner-Transfer-UI
+
+### Sprint 12 — Zentrale Einstellungsseite (9h)
+- [ ] Rechte-Settings-Page mit Tabs
+- [ ] Freigaben-Übersicht (Admin-Dashboard)
+- [ ] Audit-View für Permission-Changes
+- [ ] CustomFields Sensitivity UI
+- [ ] App-Sichtbarkeit-Tab
+
+### Sprint 13 — ABAC Engine (18h)
+- [ ] entity_policies Tabelle + Migration
+- [ ] Policy-Engine: JSONB → SQLAlchemy Übersetzer
+- [ ] apply_policy_filter() + Integration mit RBAC-Filter
+- [ ] Policy-Cache (Redis) + Invalidation
+- [ ] Policy Service (CRUD)
+- [ ] Policy API (5 Endpoints)
+- [ ] GIN-Indexes für ABAC
+- [ ] Pre-compiled SQL Fragments
+- [ ] Policy-Intersection-Optimization
+- [ ] Materialized Policy Result
+
+### Sprint 14 — ABAC UI (10h)
+- [ ] ABAC Rule-Editor mit AND/OR Gruppen
+- [ ] Feld-Auswahl (Core + Custom Fields)
+- [ ] Vorschau + Test-Tool
+- [ ] Custom Field ABAC Support (JSONB-Path)
+
+### Sprint 15 — Templates & Automation (5h)
+- [ ] permission_templates Tabelle + Migration
+- [ ] Default-Policies für neue Entities
+- [ ] Auto-Share bei Erstellung
+- [ ] Frontend Template-Editor UI
+
+### Sprint 16 — Mass & Bulk (4h)
+- [ ] Bulk-Share API
+- [ ] Mass-Operations
+- [ ] Frontend Bulk-Share-UI
+
+### Sprint 17 — Analytics & Konflikte (5h)
+- [ ] Permission-Analytics API
+- [ ] Konflikt-Erkennung
+- [ ] Orphaned-Permissions-Cleanup
+- [ ] Frontend Analytics-Dashboard
+
+### Sprint 18 — Delegation (4h)
+- [ ] permission_delegations Tabelle + Migration
+- [ ] Delegation Service + API
+- [ ] Abwesenheits-UI
+- [ ] Auto-Expiry
+
+### Sprint 19 — Resolution-Strategien (3h)
+- [ ] Konfigurierbare Override-Regeln
+- [ ] Tenant-Einstellung
+- [ ] Frontend UI
+
+### Sprint 20 — Tests (12h)
+- [ ] Backend: Entity Permissions Tests
+- [ ] Backend: ABAC Tests
+- [ ] Backend: Performance Tests (100K Datensätze)
+- [ ] Backend: Search Permission Tests
+- [ ] Backend: WebSocket Permission Tests
+- [ ] Frontend: ProtectedRoute Tests
+- [ ] Frontend: Permission-UI Tests
+- [ ] Frontend: ShareDialog Tests
+
+### Sprint 21 — Dokumentation (3h)
+- [ ] docs/permissions.md
+- [ ] docs/permissions_plugin_dev.md
+- [ ] Plugin Template mit Permission-Beispielen
+- [ ] API-Docs
+
+### Sprint 22 — Guest Access (28h)
+- [ ] guest_users Tabelle + Migration
+- [ ] Guest Auth (Login, Session, Logout)
+- [ ] Guest Permission Resolution (Service + RLS)
+- [ ] Guest Invitation Flow (Backend + E-Mail)
+- [ ] Guest API (limited endpoints)
+- [ ] Guest Frontend (vereinfachtes Layout + Views)
+- [ ] Guest Permission Management UI (Settings)
+- [ ] Guest Expiration & Auto-Cleanup
+- [ ] Guest Audit Trail
+- [ ] Guest Security (IP-Whitelist, Rate Limit, Watermarking)
+- [ ] Guest Tests
+
+### Sprint 23 — Infrastructure (4h)
+- [ ] PgBouncer Setup
+- [ ] Audit Log Partitioning
+- [ ] Connection Pool Config
+
+## Permission Levels
+| Level | Sichtbar? | Bearbeiten? | Löschen? | Teilen? |
+|-------|:---:|:---:|:---:|:---:|
+| Owner | ✅ | ✅ | ✅ | ✅ |
+| Admin | ✅ | ✅ | ✅ | ✅ |
+| Write | ✅ | ✅ | ❌ | ❌ |
+| Read | ✅ | ❌ | ❌ | ❌ |
+| None | ❌ | ❌ | ❌ | ❌ |
+
+## Architecture
+- PostgreSQL RLS (Safety Net)
+- Materialized View (user_entity_visibility)
+- Redis Bitmap Cache
+- Batch-Resolution
+- GIN-Indexes (ABAC + JSONB)
+- Folder-Path-Materialization (GiST)
+- PgBouncer Connection Pool
+- Redis Pub/Sub WebSocket Fan-Out
+- Audit Log Partitioning

FIX-PLAN-V2.md

@@ -0,0 +1,323 @@
+# LeoCRM Fix-Plan V2 — Gründliche Analyse & Maßnahmen
+
+*Erstellt: 2026-07-26 — basierend auf externem Audit + eigener Code-Verifikation*
+
+---
+
+## Zusammenfassung
+
+Von 16 zentralen Punkten des externen Audits wurden **alle 16 durch Code-Inspektion verifiziert**. Zusätzlich wurden **5 neue Probleme** gefunden (UploadFile-Bug, Redis-Default-Passwort, exponierte Ports, unauthentifizierter Error-Endpoint, fehlende Security-Headers).
+
+**Gesamtstatus:** Alle Phasen implementiert (Stand 2026-07-27). M5 (Frontend-Integration) als letzte Phase abgeschlossen.
+
+---
+
+## Implementierungs-Status (Stand 2026-07-27)
+
+Die folgenden Phasen wurden gemäß Git-Historie implementiert:
+
+| Phase | Commit | Maßnahmen | Status |
+|-------|--------|-----------|--------|
+| **Phase 1** (B1-B10) | `5ec1fc9` | Kritische Release-Blocker: Redis-Singleton (B1), Plugin-Routen (B2), UploadFile response_model (B3), DMS-Streaming (B4), Outbox-Worker (B5), Passwort-Reset-Mail (B6), Webhook-SSRF (B7), RLS-DB-Role (B8), .env-Korrektur (B9), Redis-Ports (B10) | ✅ Implementiert |
+| **Phase 2** (H1-H7) | `604a2b7` | Error-Endpoint (H1), Rate-Limiter (H2), CSRF-Redis (H3), WebSocket-Auth (H4), File-Upload (H5), Security-Headers (H6), Migration-Repair (H7) | ✅ Implementiert |
+| **Phase 3** (M1-M4, M6) | `825d638` | Passwort-Komplexität (M1), Login-Response (M2), Permission-Cache (M3), ENVIRONMENT (M4), weitere (M6) | ✅ Implementiert |
+| **Phase 4** | `b6e3afd` | Webhooks, Backup/Restore UI, Onboarding/Tutorial | ✅ Implementiert |
+| **Plugin-System-Umbau** | `98eb1d0` | Plugin-Routen nur in create_app(), require_active_plugin() Dependency, WebSocket-Skip | ✅ Implementiert |
+
+### Verifizierte P0-Behebungen
+
+| P0 | Problem | Status | Beweis |
+|----|---------|--------|--------|
+| P0-1 | Auth-Bypass via X-Internal-Call | ✅ Behoben | `app/deps.py` hat keinen X-Internal-Call Code mehr. Auth nur via Session-Cookie. |
+| P0-2 | Destruktive Migrationen | ✅ Behoben | Migration 0021 benennt Tabellen um (`*_old`). Migration 0044 repariert RLS. |
+| P0-3 | Plugin-Upload RCE | ✅ Neutralisiert | Alle Upload-Endpoints deaktiviert (403). `_extract_plugin_from_zip()` ist Dead Code. |
+| P0-4 | RLS nicht erzwungen | ✅ Behoben | Migration 0028 setzt FORCE RLS. Migration 0044 erstellt `crm_runtime` (NOSUPERUSER, NOBYPASSRLS). |
+| P0-5 | Plugin-Doppelregistrierung | ✅ Behoben | Routen nur in create_app(). require_active_plugin() prüft Aktivierungsstatus. |
+| P0-6 | Kein persistentes Volume | ✅ Behoben | docker-compose.yml hat volumes für PostgreSQL, Redis, App-Uploads, Worker. |
+| P0-7 | Öffentliche Domain | ✅ Behoben | Keine crm.media-on.de Referenz mehr in docker-compose.yml. |
+
+### Weitere verifizierte Behebungen
+- **B1** (doppelte get_redis()): ✅ Nur eine Definition in `app/core/auth.py` Zeile 53
+- **B3** (UploadFile response_model): ✅ `response_model=None` in dms, calendar, mail routes
+- **B7** (Webhook SSRF): ✅ Private IP-Check, `follow_redirects=False`, Protokoll-Check
+- **B9** (AUTH_SECRET vs SECRET_KEY): ✅ `.env.docker.example` verwendet `SECRET_KEY`
+- **B10** (Redis-Default-Passwort + Ports): ✅ Ports auskommentiert, Redis-Passwort required
+- **WebSocket Auth**: ✅ Beide WS-Endpunkte haben `verify_ws_origin()`, Session-Cookie-Validierung, `user_id` aus Session
+
+---
+
+## Phase 1: Kritische Release-Blocker (vor Produktivbetrieb)
+
+### B1. Doppelte `get_redis()` entfernen
+- **Datei:** `app/core/auth.py` Zeilen 53 + 94
+- **Problem:** Zweite Definition überschreibt Singleton, erzeugt pro Aufruf neue Verbindung → Connection Leak
+- **Fix:** Zweite `def get_redis()` (Zeile 94) löschen. Erste Definition (Zeile 53) beibehalten.
+- **Aufwand:** 5 Min
+- **Risiko:** Keines — erste Definition ist korrekt
+
+### B2. Plugin-Routen-Registrierung reparieren
+- **Datei:** `app/main.py` Zeilen 375-416
+- **Problem:** Alle Plugin-Routen werden statisch in `create_app()` registriert, unabhängig vom Aktivierungsstatus. Deaktivierte Plugins bleiben erreichbar. Kommentar in Zeile 416 sagt das Gegenteil.
+- **Fix:**
+  1. Statische Registrierung aus `create_app()` entfernen
+  2. In `lifespan()` nur Routen für `active=True` Plugins registrieren
+  3. `Depends(require_active_plugin("name"))` als zentrale Prüfung ergänzen
+  4. Bei Deaktivierung: Router entfernen oder 403-Dependency ergänzen
+- **Aufwand:** 2-3 Std
+- **Risiko:** Mittel — muss sicherstellen dass keine Route doppelt registriert wird
+
+### B3. UploadFile Route-Registration Bug
+- **Dateien:** `app/plugins/builtins/dms/routes.py`, `calendar/routes.py`, `mail/routes.py`, `kommunikation/routes.py`, `ai_assistant/routes.py`
+- **Problem:** FastAPI kann `UploadFile` nicht als Response-Model auflösen → 5 Plugins failen beim Registrieren mit `Invalid args for response field`
+- **Fix:** `response_model=None` zu allen Endpoints mit `UploadFile`-Rückgabe hinzufügen, oder Return-Type auf `Response`/`dict` ändern
+- **Aufwand:** 30 Min
+- **Risiko:** Keines — Routen sind aktuell gar nicht registriert
+
+### B4. DMS-Upload auf echtes Streaming umstellen
+- **Datei:** `app/plugins/builtins/dms/routes.py` Zeilen 444-472
+- **Problem:** Chunks werden in `list[bytes]` gesammelt, dann `b"".join()` → 100MB Datei = 200MB+ RAM. `save_stream()` existiert aber wird nicht benutzt.
+- **Fix:**
+  ```python
+  async def chunk_generator():
+      while chunk := await file.read(CHUNK_SIZE):
+          yield chunk
+  await storage.save_stream(storage_path, chunk_generator())
+  ```
+  Hash und Größe während des Streams berechnen.
+- **Aufwand:** 1 Std
+- **Risiko:** Gering — save_stream() ist bereits implementiert
+
+### B5. Outbox-Worker: Event-Handler registrieren
+- **Datei:** `app/core/worker.py` `on_startup()`
+- **Problem:** Worker liest Events aus Outbox, published an lokalen EventBus, aber es sind keine Handler registriert → Events werden als `published` markiert ohne Verarbeitung
+- **Fix:**
+  1. In `on_startup()`: Plugin-Event-Handler registrieren (wie in `lifespan()` der API)
+  2. `webhook_dispatcher._dispatch_event` an EventBus subscriben
+  3. Plugin-Participant-Handler registrieren
+- **Aufwand:** 2 Std
+- **Risiko:** Mittel — muss gleiche Handler wie API-Container registrieren
+
+### B6. Passwort-Reset-Mailjob implementieren
+- **Dateien:** `app/services/auth_service.py`, `app/core/jobs.py`, `app/core/job_registry.py`
+- **Problem:** `send_password_reset_email` Job wird gequeued aber nie registriert → Mail wird nicht versendet. Token wird in Logs geschrieben (Zeile 240-241).
+- **Fix:**
+  1. `send_password_reset_email` Worker-Funktion implementieren (SMTP/IMAP)
+  2. Mit `register_job()` registrieren
+  3. `logger.warning("raw_token for development: %s", raw_token)` entfernen
+  4. Token nur im Development-Mode loggen, nie in Production
+- **Aufwand:** 2 Std
+- **Risiko:** Gering
+
+### B7. Webhook SSRF-Schutz + Secret-Behandlung
+- **Dateien:** `app/services/webhook_service.py`, `app/schemas/webhook.py`
+- **Problem:** Kein SSRF-Schutz — User können interne Dienste ansprechen (redis:6379, postgres:5432, 169.254.169.254). Webhook-Secret wird im Response zurückgegeben.
+- **Fix:**
+  1. SSRF-Prüfung: DNS auflösen, private IPs blocken (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x, ::1)
+  2. Redirects deaktivieren oder prüfen
+  3. Protokoll-Allowlist (nur https)
+  4. `secret` aus `WebhookResponse` entfernen
+  5. Secret gehasht in DB speichern
+- **Aufwand:** 3 Std
+- **Risiko:** Gering
+
+### B8. RLS: Separater DB-Runtime-User
+- **Dateien:** `docker-compose.yml`, `alembic/versions/0044_db_roles.py` (neu)
+- **Problem:** `POSTGRES_USER` (crm_user) ist Superuser → umgeht RLS auch mit FORCE. Spätere Tabellen (user_preferences, saved_filters, etc.) haben keine RLS-Policy.
+- **Fix:**
+  1. Neue Migration `0044_db_roles.py`: erstellt `crm_runtime` (NOSUPERUSER, NOBYPASSRLS)
+  2. `crm_runtime` bekommt nur SELECT/INSERT/UPDATE/DELETE Rechte
+  3. `docker-compose.yml`: API und Worker nutzen `crm_runtime`, Migrationen nutzen `crm_owner`
+  4. Neue Migration `0045_rls_new_tables.py`: RLS für alle Tabellen mit `tenant_id` die nach 0028 hinzukamen
+- **Aufwand:** 4 Std
+- **Risiko:** Hoch — muss bestehende Datenbanken migrieren ohne Datenverlust
+
+### B9. .env.docker.example korrigieren
+- **Datei:** `.env.docker.example`
+- **Problem:** Verwendet `AUTH_SECRET` statt `SECRET_KEY` (config.py erwartet `SECRET_KEY`)
+- **Fix:** `AUTH_SECRET` → `SECRET_KEY` umbenennen
+- **Aufwand:** 5 Min
+- **Risiko:** Keines
+
+### B10. Redis-Default-Passwort + exponierte Ports
+- **Datei:** `docker-compose.yml`
+- **Problem:** Redis-Passwort default `changeme`, PostgreSQL (5432) und Redis (6379) Ports exponiert
+- **Fix:**
+  1. Redis-Passwort als Required-Env ohne Default
+  2. `ports:` Sektion für DB und Redis entfernen (nur internes Docker-Netzwerk)
+  3. Falls Debug-Zugriff nötig: nur an 127.0.0.1 binden
+- **Aufwand:** 15 Min
+- **Risiko:** Gering — bestehende Setups müssen .env anpassen
+
+---
+
+## Phase 2: Hohe Priorität (kurz nach Release)
+
+### H1. Unauthentifizierter Error-Endpoint absichern
+- **Datei:** `app/routes/errors.py`
+- **Problem:** `POST /api/v1/errors` ohne Auth, sendet Daten an Forgejo als öffentliches Issue. Context-Dict kann sensible Daten enthalten.
+- **Fix:**
+  1. Context-Felder filtern (keine Tokens, Passwörter, Headers)
+  2. Forgejo-Issues nur in non-production erstellen
+  3. Rate-Limit auf IP-Basis (bereits vorhanden, aber in-memory → bei Multi-Worker unzuverlässig)
+  4. Optional: Auth erforderlich, aber dann funktioniert Frontend-Error-Logging nicht mehr → besser: nur sanitisierte Daten akzeptieren
+- **Aufwand:** 1 Std
+
+### H2. Rate-Limiter IP-Spoofing
+- **Datei:** `app/core/rate_limit.py` Zeile 43
+- **Problem:** Vertraut `X-Forwarded-For` blind → IP-Spoofing umgeht Rate-Limits
+- **Fix:** Nur erste IP in X-Forwarded-For verwenden, oder `X-Real-IP` mit Proxy-Validation
+- **Aufwand:** 30 Min
+
+### H3. CSRF-Middleware Redis-Verbindung
+- **Datei:** `app/core/middleware.py` Zeile 69
+- **Problem:** Erstellt pro unsafe Request neue Redis-Verbindung → Connection Leak
+- **Fix:** `get_redis()` Singleton verwenden (funktioniert nach B1)
+- **Aufwand:** 10 Min
+
+### H4. WebSocket Auth + Origin-Verifikation
+- **Dateien:** `app/plugins/builtins/kommunikation/websocket_manager.py`, `ai_ui_control/websocket_manager.py`
+- **Problem:** `user_id` wird ohne Auth-Verifikation akzeptiert. Keine Origin-Prüfung bei WS-Upgrade.
+- **Fix:**
+  1. Session-Token aus Query-Param oder Header validieren
+  2. Origin-Header gegen erlaubte Domains prüfen
+  3. User-ID aus Session ableiten, nicht aus Client-Param
+- **Aufwand:** 2 Std
+
+### H5. File-Upload-Sicherheit
+- **Datei:** `app/core/storage.py`
+- **Problem:** Keine Path-Traversal-Prüfung, keine Type/Size-Limits, `get_url()` leakt Filesystem-Pfade
+- **Fix:**
+  1. Filename sanitizen (keine `../`, keine absoluten Pfade)
+  2. MIME-Type-Allowlist
+  3. Max-File-Size konfigurierbar
+  4. `get_url()` gibt relative URL zurück, nicht Filesystem-Pfad
+- **Aufwand:** 1 Std
+
+### H6. Security-Headers
+- **Datei:** `app/core/middleware.py` (neu)
+- **Problem:** Keine Security-Headers (HSTS, X-Content-Type-Options, X-Frame-Options, CSP)
+- **Fix:** Middleware ergänzen die diese Headers setzt
+- **Aufwand:** 30 Min
+
+### H7. Migration-Repair für bestehende Installationen
+- **Datei:** `alembic/versions/0044_repair_contact_migration.py` (neu)
+- **Problem:** Migrationen 0021 und 0027 wurden nachträglich geändert. Alembic führt sie nicht erneut aus.
+- **Fix:**
+  1. Neue Migration die `*_old` Tabellen erkennt und Daten nachmigriert
+  2. Integritätsprüfung (Anzahl vergleichen)
+  3. Bei Abweichungen hart abbrechen mit Fehlermeldung
+- **Aufwand:** 3 Std
+
+---
+
+## Phase 3: Mittlere Priorität
+
+### M1. Passwort-Komplexität
+- **Datei:** `app/schemas/auth.py`, `app/schemas/user.py`
+- **Problem:** Min-Length 8 bei Erstellung, Min-Length 1 bei Login. Keine Komplexitäts-Requirements.
+- **Fix:** Passwort-Validator ergänzen (min 8 Zeichen, 1 Groß, 1 Klein, 1 Zahl)
+- **Aufwand:** 30 Min
+
+### M2. Login-Response: is_system_admin
+- **Datei:** `app/routes/auth.py` Zeile 78
+- **Problem:** `is_system_admin` Flag in Login-Response leakt interne Rolle
+- **Fix:** Flag aus Response entfernen oder nur für Admin-User anzeigen
+- **Aufwand:** 15 Min
+
+### M3. Permission-Cache: Stale Data bei DB-Error
+- **Datei:** `app/core/permissions.py` Zeile 337
+- **Problem:** Bei DB-Error fällt Cache auf stale Daten zurück → widerrufene Rechte bleiben aktiv
+- **Fix:** Bei DB-Error: Cache invalidieren und 503 zurückgeben statt stale Daten zu nutzen
+- **Aufwand:** 30 Min
+
+### M4. ENVIRONMENT=development vs SESSION_COOKIE_SECURE=true
+- **Datei:** `.env` Zeilen 3-4
+- **Problem:** Inkonsistent — development deaktiviert Prod-Safety-Checks, aber Cookie ist secure
+- **Fix:** In .env.docker.example klar dokumentieren: production → `ENVIRONMENT=production` + `SESSION_COOKIE_SECURE=true`
+- **Aufwand:** 10 Min
+
+### M5. Frontend: Unresolved Items — ✅ Implementiert (2026-07-27)
+- **Dateien:** `WelcomeDialog.tsx`, `SavedFilterBar.tsx`, `EntityHistoryPanel.tsx`, `TagBadge.tsx`, `TagSelector.tsx`
+- **Status:** ✅ Implementiert — SavedFilterBar und TagSelector in ContactsList, Mail, Calendar integriert
+- **Implementiert:**
+  1. SavedFilterBar in ContactsList (entityType="contacts"), Mail (entityType="mail"), Calendar (entityType="calendar") integriert
+  2. TagSelector in ContactsList (entityType="contact"), Mail (entityType="file"), Calendar (entityType="calendar_entry") integriert
+  3. Frontend TypeScript: 0 Errors (`npx tsc --noEmit`)
+- **Hinweis:** WelcomeDialog und EntityHistoryPanel bleiben für spätere Iteration offen
+
+### M6. Frontend-Tests: QueryClientProvider
+- **Datei:** `frontend/src/test/setup.ts` oder einzelne Tests
+- **Problem:** ~29 Tests failen mit missing QueryClientProvider
+- **Fix:** Globalen Test-Wrapper mit QueryClientProvider in setup.ts ergänzen
+- **Aufwand:** 1 Std
+
+---
+
+## Phase 4: Niedrige Priorität
+
+### L1. document.write() in print.ts
+- **Datei:** `frontend/src/utils/print.ts` Zeilen 54, 127
+- **Problem:** `document.write()` mit DOM-Clone — XSS-Risiko wenn Content nicht sanitized
+- **Fix:** Statt `document.write()`: `iframe.srcdoc` oder `Blob URL` verwenden
+- **Aufwand:** 1 Std
+
+### L2. AI UI Control: Unbounded Feedback-Storage
+- **Datei:** `app/plugins/builtins/ai_ui_control/websocket_manager.py` Zeile 94
+- **Problem:** Feedback/Commands unbegrenzt im Memory gespeichert → Memory Exhaustion
+- **Fix:** Max-Length Queue (z.B. 100 Einträge) mit FIFO
+- **Aufwand:** 15 Min
+
+### L3. Backup-Strategie dokumentieren
+- **Problem:** Named Volumes in docker-compose aber keine Backup/Restore-Doku
+- **Fix:** Backup-Script und Doku ergänzen
+- **Aufwand:** 2 Std
+
+---
+
+## Implementierungs-Reihenfolge
+
+```
+Phase 1 (Release-Blocker):
+  B1  → B3 → B9 → B10 → B2 → B4 → B5 → B6 → B7 → B8
+  ↑    ↑    ↑    ↑      ↑    ↑    ↑    ↑    ↑    ↑
+  5m   30m  5m   15m    3h   1h   2h   2h   3h   4h
+  Gesamt: ~16 Std
+
+Phase 2 (Hohe Priorität):
+  H3 → H2 → H6 → H1 → H5 → H4 → H7
+  Gesamt: ~8 Std
+
+Phase 3 (Mittlere Priorität):
+  M4 → M1 → M2 → M3 → M6 → M5
+  Gesamt: ~6 Std
+
+Phase 4 (Niedrige Priorität):
+  L2 → L1 → L3
+  Gesamt: ~3 Std
+```
+
+**Gesamtaufwand: ~33 Std**
+
+---
+
+## Was bereits sauber funktioniert
+
+- ✅ Auth-Bypass entfernt (keine X-Internal-Call/X-Tenant-Id/X-User-Id Headers mehr)
+- ✅ Plugin-Upload/URL-Installation deaktiviert (403)
+- ✅ Worker in separatem Container
+- ✅ Metrics adminbeschränkt
+- ✅ DOMPurify für HTML-Komponenten
+- ✅ ARQ-Verbindungspool zentralisiert
+- ✅ Session-Widerruf nach Passwortänderung
+- ✅ Permission-Cache-Versionierung
+- ✅ Redis SCAN statt KEYS
+- ✅ Rabatte von Float auf Numeric
+- ✅ Event-Outbox als Grundlage vorhanden
+- ✅ RLS FORCE + WITH CHECK in Migration 0028
+- ✅ Migration 0021: Tabellen umbenennen statt löschen
+- ✅ Frontend: TypeScript typecheck clean (0 errors)
+- ✅ Frontend: ErrorBoundary, OfflineBanner, ErrorLogger implementiert
+- ✅ Frontend: Print/PDF mit WeasyPrint funktioniert
+- ✅ Dockerfile: Multi-stage, non-root User, Healthcheck
+- ✅ Bcrypt Password-Hashing
+- ✅ Session-Tokens: secrets.token_urlsafe(32)

FIX-PLAN.md

@@ -0,0 +1,88 @@
+# LeoCRM — Umfassender Fix-Plan
+
+> Erstellt: 2026-07-25
+> Letzte Überprüfung: 2026-07-26 — Alle Items gegen Codebasis verifiziert
+> Quellen: Externes Audit (geprüft), eigene Code-Inspektion, Coolify-Deployment-Prüfung
+
+---
+
+## ✅ Erledigte Fixes (22 von 24 Items komplett)
+
+Die folgenden Items wurden bei der Überprüfung am 2026-07-26 als erledigt bestätigt:
+
+| Item | Beschreibung | Verifiziert durch |
+|---|---|---|
+| P0-1 | Auth-Bypass entfernt | `app/deps.py` — keine `X-Internal-Call` Headers mehr |
+| P0-2 | Migrationen repariert | `migration_0021.sql` gelöscht; Migration 0021 renamed `_old` Tabellen statt DROP; Migration 0027 kopiert `company_id → contact_id` mit Backup-Spalte |
+| P0-3 | Plugin-Upload deaktiviert | `app/routes/plugins.py` — `/upload` und `/install-url` return 403 mit `upload_disabled` / `install_url_disabled` |
+| P0-4 | RLS repariert | `alembic/versions/0028_rls_force.py` — `FORCE ROW LEVEL SECURITY` + `WITH CHECK` auf allen Tenant-Tabellen |
+| P0-5 | Plugin-Doppelregistrierung | `app/main.py` — Routes in `create_app()`, `lifespan()` nur aktiviert/deaktiviert, respektiert DB `active` Status, Migration-Fail deaktiviert Plugin |
+| P0-6 | Persistent Volume | `docker-compose.yml` — `storage:/data/storage`, `pgdata`, `redisdata` Volumes |
+| P1-1 | User/Tenant-Modell | `app/models/user.py` — `User` hat keine `tenant_id`/`role` mehr, `UserTenant` ist single source of truth, `email` global unique |
+| P1-2 | Redis zentralisiert | `app/core/auth.py` — `init_redis()`/`get_redis()` Singleton, `init_job_pool()`/`close_job_pool()` |
+| P1-3 | Worker ausgelagert | `prestart.sh` — nur Alembic + Uvicorn; separater `crm-worker` Container in `docker-compose.yml` |
+| P1-4 | Transactional Outbox | `app/core/outbox.py`, `app/models/outbox.py`, `alembic/versions/0040_outbox.py` — `enqueue_outbox_event()` + `process_outbox_batch()` mit `FOR UPDATE SKIP LOCKED` |
+| P1-5 | XSS-Stellen geschlossen | `HtmlBlock.tsx` + `SignatureManager.tsx` — `DOMPurify.sanitize()`; `ActionCardBlock.tsx` — URL-Validierung (nur `http:`/`https:`) |
+| P1-6 | DMS lastfest | `app/plugins/builtins/dms/routes.py` — 1MB Chunked Streaming, SHA-256 Content-Hash |
+| P1-7 | Permission-System | `app/core/permissions.py` — `permission_version` wird beim Cache-Lesen geprüft, `redis.scan()` statt `redis.keys()`, `require_write()` prüft spezifische Permissions |
+| P1-8 | Password Reset | `app/services/auth_service.py` — ARQ Job `send_password_reset_email`, Token `used_at` Tracking |
+| P1-9 | Metrics abgesichert | `app/routes/metrics.py` — `Depends(require_admin)` |
+| P1-10 | Coolify-Doku & Config | `COOLIFY_SETUP.md` — Healthcheck `/api/v1/health`, JWT-Vars entfernt, CORS `:443`; `app/config.py` — `storage_path=/data/storage`, `session_cookie_secure=True`, Startup-Validierung; `docker-compose.yml` — Redis, Volumes, Healthcheck |
+| P1-11 | Cross-Tenant FK | `alembic/versions/0036_cross_tenant_fk.py` — `UNIQUE (tenant_id, id)` + Composite FK `(tenant_id, contact_id)` auf `contactpersons` und `contact_merge_history` |
+| P2-1 | Contact Model normalisiert | `alembic/versions/0039_contact_normalize.py` — `surfix→suffix`, `Float→Numeric(5,2)`, `JSON→JSONB`, `CHECK (0-100)`, Unique Constraints |
+| P2-3 | Commands & Statusmaschinen | `app/commands/` (base, contact, calendar, dms, mail) + `app/core/state_machine.py` |
+| P2-4 | SPA Path-Traversal | `app/main.py` — `os.path.abspath` Check + `".." in full_path` Blocking |
+
+---
+
+## ⏳ Offene Items
+
+### P0-7: App von öffentlicher Domain nehmen
+
+**Status:** Operational — nicht aus Code verifizierbar
+
+**Problem:** Die App läuft unter `https://crm.media-on.de` und ist öffentlich erreichbar.
+
+**Maßnahme:**
+1. **Sofort:** App von öffentlicher Domain nehmen oder IP-Whitelist/Basic Auth vorschalten
+2. Mindestens P0-1 (Auth-Bypass ✅) und P0-3 (Plugin-Upload ✅) sind bereits behoben
+3. Alternativ: VPN/Tunnel-Zugang statt öffentliche Domain
+
+**Aufwand:** 30 Minuten
+
+---
+
+### P2-2: Plugin-Cross-Imports reduzieren
+
+**Status:** Offen — 228 direkte Cross-Imports zwischen Plugins
+
+**Problem:** 228 direkte `from app.plugins.builtins` Imports zwischen Plugins. Automatisierung importiert Modelle/Services von Kommunikation, Mail, Kalender. Verteilter Monolith ohne Modulgrenzen.
+
+**Maßnahme:**
+1. Öffentliche Schnittstellen (Contracts) für jedes Modul definieren
+2. Direkte Imports fremder Plugin-Modelle verbieten
+3. Kommunikation nur über Events oder öffentliche Service-API
+4. CI-Check: keine direkten Cross-Plugin-Imports
+
+**Aufwand:** 1-2 Wochen
+
+---
+
+## Zusammenfassung
+
+| Priorität | Erledigt | Offen | Geschätzter Aufwand (offen) |
+|---|---|---|---|
+| P0 | 6/7 | 1 (operational) | 30 Minuten |
+| P1 | 11/11 | 0 | — |
+| P2 | 3/4 | 1 | 1-2 Wochen |
+| **Total** | **20/22** | **2** | **~1-2 Wochen** |
+
+## Validierung nach jedem Fix
+
+- [ ] Python-Syntax-Check: `python -m py_compile app/**/*.py`
+- [ ] pytest: `pytest tests/ -x`
+- [ ] Frontend-Typecheck: `cd frontend && npx tsc --noEmit`
+- [ ] Frontend-Build: `cd frontend && npx vite build`
+- [ ] Manueller Smoke-Test: Login, Kontakt erstellen, DMS-Upload
+- [ ] Cross-Tenant-Test: Datensatz aus Mandant A kann nicht aus Mandant B gelesen werden
+- [ ] Deployment: Coolify Deploy + Healthcheck prüfen

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,534 @@
+# LeoCRM — Implementationsplan: Fehlende Frontend-Features
+
+> **Stand:** 26.07.2026 (Audit-korrigiert) | **Backend:** 352 Endpunkte | **Frontend:** 47 Pages, 38 API-Clients
+> **Repo:** `/a0/usr/workdir/leocrm-fix` | **Branch:** `main` | **Deploy:** Coolify App `stvabl4vaqru7jclx4ittzr3`
+
+---
+
+## ⚠️ Audit-Korrekturen (26.07.2026 02:17)
+
+### Korrektur 1: Permissions Management UI — ENTHALTEN IN SettingsRoles.tsx
+**Vorher:** Plan sagte "keine Verwaltungs-Seite um Permissions pro Rolle zu konfigurieren"
+**Tatsächlich:** `SettingsRoles.tsx` (531 Zeilen) hat VOLLSTÄNDIGE Permission-Verwaltung:
+- ✅ Grant permissions (Checkboxen gruppiert nach system/plugin)
+- ✅ Denied permissions (explizite Verweigern-Liste)
+- ✅ Field-level permissions (pro Modul/Feld Sensitivität)
+- ✅ Rollen erstellen/bearbeiten mit Permission-Zuweisung
+- ✅ DMS `ShareDialog.tsx` nutzt bereits File-Permissions API (grant/revoke/share-link)
+**Folge:** Feature 8 entfällt. Keine neue Permission-UI nötig.
+
+### Korrektur 2: Import/Export — Export-Route fehlt DEFINITIV
+**Vorher:** Plan sagte "falls Export fehlt"
+**Tatsächlich:** `export_contacts_csv()` Service-Funktion existiert, aber KEINE Route in `import_export.py`. Nur `/import` und `/import/preview` sind registriert. Export muss als Route hinzugefügt werden.
+
+### Korrektur 3: Activity Timeline — ActivityFeed existiert bereits
+**Vorher:** Plan sagte "Dashboard hat ActivityFeed aber nur statisch"
+**Tatsächlich:** Dashboard nutzt `ActivityFeed` mit Daten aus Audit-API. Komponente ist wiederverwendbar. Es fehlt nur eine eigenständige Seite mit Filterung/Pagination.
+
+### Korrektur 4: DMS ShareDialog — File Permissions bereits integriert
+**Vorher:** Plan sah `FilePermissionDialog` als neue Komponente vor
+**Tatsächlich:** `ShareDialog.tsx` (11KB) existiert bereits und nutzt `fetchFilePermissions`, `grantPermission`, `revokePermission`, `createShareLink`, `revokeShareLink` aus `permissions.ts`.
+
+---
+
+## Übersicht: 14 verbleibende Features in 4 Phasen
+
+| Phase | Features | Priorität | Geschätzter Aufwand |
+|-------|----------|-----------|---------------------|
+| **1 — Kritisch** | Workflows UI, Dedup/Merge UI, Import/Export UI, Print/PDF | CRM-Kern | ~4-5 Tage |
+| **2 — Wichtig** | Tags UI, Custom Fields UI, Notifications Dropdown | Tagesgeschäft | ~2.5-3 Tage |
+| **3 — Nice-to-have** | Saved Filters UI, Entity History UI, Activity Timeline, API Docs Link | Produktivität | ~1.5-2 Tage |
+| **4 — Backend+Frontend** | Webhooks, Backup/Restore UI, Onboarding/Tutorial | Erweiterungen | ~3-4 Tage |
+
+**Gesamtaufwand:** ~11-14 Entwicklungstage (1 Feature entfallen)
+
+---
+
+## Architektur-Grundsätze (für alle Features)
+
+### Frontend-Konventionen
+- **Routing:** Lazy-loaded in `frontend/src/routes/index.tsx`, explizite Routes (nicht PluginRouteRenderer)
+- **API-Clients:** In `frontend/src/api/<name>.ts`, verwenden `apiGet/apiPost/apiPatch/apiDelete` aus `client.ts`
+- **Hooks:** React Query (`useQuery`/`useMutation`) mit Query-Key-Invalidierung
+- **UI:** Tailwind CSS, `clsx` für Klassen, `lucide-react` für Icons
+- **i18n:** `useTranslation()` mit `t('key')`, Keys in `frontend/src/i18n/`
+- **Sidebar:** Plugin-Manifeste liefern Menu-Items via `usePluginStore` — neue Pages brauchen Plugin-Manifest-Einträge
+- **Settings:** Hardcoded nav items in `Settings.tsx` + plugin settings_pages
+- **Error Handling:** `ErrorBoundary` wrappt alle Routes
+
+### Backend-Konventionen
+- **Routes:** `app/routes/<name>.py`, registriert in `app/main.py`
+- **Services:** `app/services/<name>_service.py`
+- **Models:** `app/models/<name>.py`, Migrationen in `alembic/versions/`
+- **Schemas:** `app/schemas/<name>.py` (Pydantic)
+- **Permissions:** `require_permission('plugin:action')` Dependency
+- **Events:** `event_bus.publish()` für System-Events
+
+---
+
+## Phase 1 — Kritisch für CRM-Betrieb
+
+### 1.1 Workflows UI
+
+**Audit-Status:** ✅ Backend vollständig (routes, model, service, execution engine). ✅ API-Client vollständig (`workflows.ts`). ❌ Keine Frontend-Seite. ❌ Kein menu_items-Eintrag im Automation-Plugin.
+
+**Neue Dateien:**
+- `frontend/src/pages/Workflows.tsx` — Hauptseite mit Tabs: Definitionen | Instanzen
+- `frontend/src/components/workflows/WorkflowEditor.tsx` — Visueller Step-Editor
+- `frontend/src/components/workflows/WorkflowInstanceList.tsx` — Liste laufender/abgeschlossener Instanzen
+- `frontend/src/components/workflows/WorkflowInstanceDetail.tsx` — Detail mit Step-History, Approve/Reject
+- `frontend/src/components/workflows/StepConfigPanel.tsx` — Konfiguration pro Step-Typ
+
+**Modifizierte Dateien:**
+- `frontend/src/routes/index.tsx` — Route `/workflows` + `/workflows/instances/:id`
+- `app/plugins/builtins/automation/plugin.py` — menu_items Eintrag für Workflows (aktuell `menu_items=[]`)
+- `frontend/src/i18n/de.json` — Workflow-Übersetzungen
+
+**Step-Editor:**
+- Step-Typen: `action`, `approval`, `notification`, `condition`
+- Drag-and-Drop Reihenfolge (oder Button-basiert nach oben/unten)
+- Pro Step: Name, Typ, Config-Form
+- Trigger-Event Dropdown (aus Event-Bus-Events)
+- Aktiv/Inaktiv Toggle
+
+**Instanzen-View:**
+- Status-Filter: pending, in_progress, completed, rejected, cancelled
+- Pro Instanz: Workflow-Name, Status, Current Step, Timeout
+- Detail: Step-History Timeline, Approve/Reject Buttons
+
+**Aufwand:** ~1.5 Tage
+
+---
+
+### 1.2 Dedup/Merge UI
+
+**Audit-Status:** ✅ Backend vollständig (`dedup_service.py`, routes in `contacts.py`: `/duplicates`, `/merge`, `/merge-history`). ✅ API-Client vollständig (`dedup.ts`). ❌ Keine Frontend-Seite.
+
+**Neue Dateien:**
+- `frontend/src/pages/DedupMerge.tsx` — Hauptseite mit drei Bereichen
+- `frontend/src/components/dedup/DuplicatePairCard.tsx` — Side-by-side Vergleich
+- `frontend/src/components/dedup/MergeDialog.tsx` — Merge-Dialog mit Feld-Auswahl
+- `frontend/src/components/dedup/MergeHistory.tsx` — Verlauf der durchgeführten Merges
+
+**Modifizierte Dateien:**
+- `frontend/src/routes/index.tsx` — Route `/contacts/dedup`
+- `frontend/src/pages/ContactsList.tsx` — Button "Duplikate prüfen" im Header
+- `frontend/src/i18n/de.json` — Dedup-Übersetzungen
+
+**Merge-Dialog:**
+- Side-by-side Feld-Vergleich
+- Pro Feld Radio: Quelle | Ziel | Manuell eingeben
+- Vorschau des merged Kontakts
+- Optionale Notiz
+- Bestätigungs-Button mit Warnung
+
+**Aufwand:** ~1 Tag
+
+---
+
+### 1.3 Import/Export UI
+
+**Audit-Status:** ✅ Backend hat `/api/v1/import` + `/api/v1/import/preview` (Routes). ✅ Service hat `import_csv()`, `export_contacts_csv()`. ❌ **Export-Route fehlt** — Service-Funktion existiert aber ist nicht als Endpoint registriert. ❌ Kein Frontend, kein API-Client.
+
+**Backend-Ergänzung (bestätigt nötig):**
+- `app/routes/import_export.py` — `GET /api/v1/export?entity_type=contacts&format=csv` hinzufügen
+  - Ruft `export_contacts_csv()` auf, gibt `StreamingResponse` mit CSV zurück
+  - Erweiterung: `entity_type=companies` (Filter auf `Contact.type == 'company'`)
+  - Optional: XLSX-Format via `openpyxl`
+
+**Neue Frontend-Dateien:**
+- `frontend/src/pages/ImportExport.tsx` — Hauptseite mit Tabs: Import | Export
+- `frontend/src/components/import-export/ImportWizard.tsx` — Mehrstufiger Import-Wizard
+- `frontend/src/components/import-export/ExportPanel.tsx` — Export-Auswahl
+- `frontend/src/api/importExport.ts` — API-Client (neu)
+
+**Modifizierte Dateien:**
+- `frontend/src/routes/index.tsx` — Route `/import-export`
+- Plugin-Manifest — menu_items Eintrag
+- `frontend/src/i18n/de.json` — Übersetzungen
+
+**Import-Wizard:**
+```
+Step 1: Datei hochladen + Entity-Typ (Companies/Contacts)
+Step 2: Dry-Run Preview — zeigt erkannte Spalten, Mapping, Fehler
+Step 3: Bestätigung — Anzahl neu/aktualisiert/fehlerhaft
+Step 4: Import ausführen — Progress + Ergebnis
+```
+
+**Export-Panel:**
+- Entity: Kontakte / Firmen
+- Format: CSV (XLSX optional)
+- Download-Button → File-Download
+
+**Aufwand:** ~1.5 Tage (inkl. Backend Export-Route)
+
+---
+
+### 1.4 Print/PDF
+
+**Audit-Status:** ❌ Komplett fehlend. Keine Print-Utils, keine Print-Buttons, kein `@media print` CSS.
+
+**Neue Dateien:**
+- `frontend/src/utils/print.ts` — Print-Utility
+- `frontend/src/components/common/PrintButton.tsx` — Wiederverwendbarer Print/Export-Button
+- `frontend/src/styles/print.css` — Print-spezifische CSS
+
+**Modifizierte Dateien:**
+- `frontend/src/pages/ContactsList.tsx` — Print-Button in Toolbar
+- `frontend/src/pages/ContactDetailPage.tsx` — Print-Button
+- `frontend/src/pages/Calendar.tsx` — Print-Button
+- `frontend/src/pages/Reports.tsx` — Print-Button
+- `frontend/index.html` — Print-CSS einbinden
+
+**Implementierung:**
+- Option A: `window.print()` mit `@media print` CSS (empfohlen für Listen/Details)
+- Option B: `jspdf` + `html2canvas` für echte PDF-Generierung (für Reports)
+- Print-Button Dropdown: "Drucken" | "Als PDF"
+
+**Aufwand:** ~0.5 Tage
+
+---
+
+## Phase 2 — Wichtig für Tagesgeschäft
+
+### 2.1 Tags UI
+
+**Audit-Status:** ✅ Backend-Plugin vollständig (`app/plugins/builtins/tags/`: models, routes, schemas). ✅ API-Client vollständig (`tags.ts`). ❌ Keine Frontend-Seite.
+
+**Neue Dateien:**
+- `frontend/src/pages/Tags.tsx` — Tag-Verwaltung (CRUD, Farb-Auswahl, Usage-Count)
+- `frontend/src/components/tags/TagBadge.tsx` — Wiederverwendbares Tag-Badge
+- `frontend/src/components/tags/TagSelector.tsx` — Multi-Select Tag-Picker
+
+**Modifizierte Dateien:**
+- `frontend/src/routes/index.tsx` — Route `/tags`
+- `frontend/src/pages/ContactsList.tsx` — Tag-Spalte + Tag-Filter
+- `frontend/src/pages/ContactDetailPage.tsx` — Tag-Badges + Tag-Selector
+- `frontend/src/pages/Calendar.tsx` — Tag-Badges für Termine
+- `frontend/src/pages/Dms.tsx` — Tag-Badges für Dateien
+- Plugin-Manifest — menu_items
+- `frontend/src/i18n/de.json`
+
+**Aufwand:** ~1 Tag
+
+---
+
+### 2.2 Custom Fields UI
+
+**Audit-Status:** ✅ Backend hat Custom-Fields-Route (plugin-manifest-gesteuert, Werte in `contacts.custom` JSONB). ❌ Keine User-definierten Feld-Definitionen (nur Plugin-Definitionen). ❌ Keine Frontend-Seite.
+
+**Backend-Ergänzung nötig:**
+- `app/models/custom_field_definition.py` — Model für User-definierte Felder
+- `app/schemas/custom_field_definition.py` — Pydantic Schemas
+- `app/services/custom_field_service.py` — CRUD-Service
+- `app/routes/custom_fields.py` — `GET/POST/PATCH/DELETE /api/v1/custom-fields/definitions`
+- Migration für `custom_field_definitions` Tabelle
+- Bestehende `_collect_custom_field_definitions()` erweitern um DB-Definitionen
+
+**Neue Frontend-Dateien:**
+- `frontend/src/pages/CustomFields.tsx` — Definitionen verwalten
+- `frontend/src/components/custom-fields/FieldDefinitionForm.tsx` — Form für neue Felder
+- `frontend/src/components/custom-fields/CustomFieldRenderer.tsx` — Dynamisches Feld-Rendering
+- `frontend/src/api/customFieldDefinitions.ts` — API-Client für Definitionen
+
+**Modifizierte Dateien:**
+- `frontend/src/routes/index.tsx` — Route `/settings/custom-fields`
+- `frontend/src/pages/Settings.tsx` — Nav-Eintrag "Custom Fields"
+- `frontend/src/pages/ContactDetailPage.tsx` — Custom Fields Section
+- `frontend/src/i18n/de.json`
+
+**Feld-Typen:** text, number, date, select, multiselect, boolean
+
+**Aufwand:** ~1.5 Tage (inkl. Backend CRUD + Migration)
+
+---
+
+### 2.3 Notifications Dropdown (Bell Icon in TopBar)
+
+**Audit-Status:** ✅ API-Client vollständig (`notifications.ts`). ✅ Backend vollständig. ❌ TopBar hat kein Bell-Icon (confirmed: `grep` findet nichts). Notifications nur in AISidebar.
+
+**Neue Dateien:**
+- `frontend/src/components/layout/NotificationBell.tsx` — Bell-Icon mit Badge + Dropdown
+- `frontend/src/components/notifications/NotificationDropdown.tsx` — Dropdown-Liste
+- `frontend/src/components/notifications/NotificationItem.tsx` — Einzelne Notification
+
+**Modifizierte Dateien:**
+- `frontend/src/components/layout/TopBar.tsx` — `<NotificationBell />` vor User-Menu einfügen
+- `frontend/src/i18n/de.json`
+
+**Features:**
+- Unread-Count Badge (rot)
+- Polling alle 30s (refetchInterval in useQuery)
+- Click: Notification als gelesen markieren
+- "Alle als gelesen" Button
+- Type-Icon pro Notification
+- Zeitstempel (relativ: "vor 5 Min")
+
+**Aufwand:** ~0.5 Tage
+
+---
+
+## Phase 3 — Nice-to-have / Produktivität
+
+### 3.1 Saved Filters UI
+
+**Audit-Status:** ✅ Backend vollständig (`saved_filters.py`: CRUD, entity_types: contacts/mail/calendar/dms). ✅ API-Client vorhanden (`savedFilters.ts`). ❌ Keine UI.
+
+**Neue Dateien:**
+- `frontend/src/components/common/SavedFilterBar.tsx` — Filter-Leiste mit Save/Load
+- `frontend/src/components/common/SaveFilterDialog.tsx` — Dialog zum Speichern
+
+**Modifizierte Dateien:**
+- `frontend/src/pages/ContactsList.tsx` — SavedFilterBar
+- `frontend/src/pages/Calendar.tsx` — SavedFilterBar
+- `frontend/src/pages/Dms.tsx` — SavedFilterBar
+- `frontend/src/pages/Tasks.tsx` — SavedFilterBar
+- `frontend/src/i18n/de.json`
+
+**Aufwand:** ~0.5 Tage
+
+---
+
+### 3.2 Entity History UI
+
+**Audit-Status:** ✅ Backend vollständig (`entity_history.py`: get/restore/undo). ✅ API-Client vorhanden (`entityHistory.ts`). ❌ Keine UI-Komponente.
+
+**Neue Dateien:**
+- `frontend/src/components/common/EntityHistoryPanel.tsx` — Timeline-Komponente
+- `frontend/src/components/common/HistoryDiff.tsx` — Visualisierung von Feld-Änderungen
+
+**Modifizierte Dateien:**
+- `frontend/src/pages/ContactDetailPage.tsx` — History-Tab/Panel
+- `frontend/src/pages/Dms.tsx` — History für Dateien
+- `frontend/src/pages/Calendar.tsx` — History für Termine
+- `frontend/src/i18n/de.json`
+
+**Features:**
+- Timeline mit create/update/delete Events
+- Diff-Anzeige: alt → neu pro Feld
+- Restore-Button pro Eintrag
+- Undo-Button (letzte Aktion rückgängig)
+
+**Aufwand:** ~0.5 Tage
+
+---
+
+### 3.3 Activity Timeline
+
+**Audit-Status:** ✅ `ActivityFeed` Komponente existiert (wiederverwendbar). ✅ Dashboard nutzt sie mit Audit-Daten. ❌ Keine eigenständige Seite mit Filterung/Pagination.
+
+**Neue Dateien:**
+- `frontend/src/pages/ActivityTimeline.tsx` — Globale Activity-Feed Seite
+- `frontend/src/components/activity/ActivityFilter.tsx` — Filter (User, Entity, Action, Zeitraum)
+
+**Modifizierte Dateien:**
+- `frontend/src/routes/index.tsx` — Route `/activity`
+- `frontend/src/api/audit.ts` — Erweitern um Timeline-Query (alle Entities, Pagination)
+- `frontend/src/pages/Dashboard.tsx` — Link "Alle Aktivitäten anzeigen"
+- `frontend/src/i18n/de.json`
+
+**Features:**
+- Wiederverwendung von `ActivityFeed` Komponente
+- Gruppierung nach Tag
+- Filter: User, Entity-Typ, Aktion, Zeitraum
+- Pagination / Infinite-Scroll
+- Link zu Entity-Detail bei Click
+
+**Aufwand:** ~0.5 Tage
+
+---
+
+### 3.4 API Documentation Link
+
+**Audit-Status:** ✅ FastAPI generiert automatisch `/docs` (Swagger) und `/redoc`. ❌ Kein Link im UI.
+
+**Modifizierte Dateien:**
+- `frontend/src/components/layout/TopBar.tsx` — "API Docs" Link im User-Menu
+- `frontend/src/pages/SettingsSystem.tsx` — "API Dokumentation" Sektion
+- `frontend/src/i18n/de.json`
+
+**Implementierung:**
+- Link zu Swagger UI: `/docs` (FastAPI auto-docs)
+- Link zu ReDoc: `/redoc`
+- In Settings/System: Sektion "Entwickler"
+
+**Aufwand:** ~0.25 Tage
+
+---
+
+## Phase 4 — Backend + Frontend (komplett neu)
+
+### 4.1 Webhooks
+
+**Audit-Status:** ❌ Komplett fehlend. Kein Backend, kein Frontend, keine Modelle.
+
+**Neue Backend-Dateien:**
+- `app/models/webhook.py` — Webhook-Modell (url, events, secret, is_active, retry_count)
+- `app/schemas/webhook.py` — Pydantic Schemas
+- `app/services/webhook_service.py` — Webhook-Service (send, retry, verify HMAC)
+- `app/routes/webhooks.py` — CRUD-Routes `/api/v1/webhooks`
+- `app/core/webhook_dispatcher.py` — Event-Bus-Subscriber
+- `alembic/versions/0036_webhooks.py` — Migration
+
+**Neue Frontend-Dateien:**
+- `frontend/src/pages/SettingsWebhooks.tsx` — Webhook-Verwaltung
+- `frontend/src/components/webhooks/WebhookForm.tsx` — Create/Edit Form
+- `frontend/src/components/webhooks/WebhookDeliveryLog.tsx` — Delivery-Log
+- `frontend/src/api/webhooks.ts` — API-Client
+
+**Modifizierte Dateien:**
+- `app/main.py` — Router registrieren
+- `app/core/event_bus.py` — Webhook-Dispatcher subscriben
+- `frontend/src/routes/index.tsx` — Route `/settings/webhooks`
+- `frontend/src/pages/Settings.tsx` — Nav-Eintrag "Webhooks"
+- `frontend/src/i18n/de.json`
+
+**Features:**
+- URL + Secret (HMAC-Signatur)
+- Event-Auswahl (Multi-Select aus Event-Bus-Events)
+- Aktiv/Pause Toggle
+- Delivery-Log mit Status, Response-Code, Latenz
+- Retry-Konfiguration
+- Test-Button
+
+**Aufwand:** ~1.5 Tage
+
+---
+
+### 4.2 Backup/Restore UI
+
+**Audit-Status:** ✅ `backup_check` Cron-Job existiert (prüft last_backup_at, published Events). ❌ Keine Backup-Routes, keine Restore-Funktionalität, keine UI.
+
+**Backend-Ergänzung:**
+- `app/routes/backups.py` — `/api/v1/backups` (list, create, restore, delete)
+- `app/services/backup_service.py` — Backup erstellen (pg_dump), Restore (pg_restore)
+- `app/models/backup.py` — Backup-Modell
+- `alembic/versions/0037_backups.py` — Migration
+
+**Neue Frontend-Dateien:**
+- `frontend/src/pages/SettingsBackup.tsx` — Backup-Verwaltung
+- `frontend/src/components/backup/BackupList.tsx` — Liste der Backups
+- `frontend/src/components/backup/RestoreDialog.tsx` — Restore-Bestätigung
+- `frontend/src/api/backups.ts` — API-Client
+
+**Modifizierte Dateien:**
+- `app/main.py` — Router registrieren
+- `frontend/src/routes/index.tsx` — Route `/settings/backup`
+- `frontend/src/pages/Settings.tsx` — Nav-Eintrag "Backup & Restore"
+- `frontend/src/i18n/de.json`
+
+**Aufwand:** ~1 Tag
+
+---
+
+### 4.3 Onboarding/Tutorial
+
+**Audit-Status:** ❌ Komplett fehlend.
+
+**Neue Dateien:**
+- `frontend/src/components/onboarding/OnboardingTour.tsx` — Guided Tour
+- `frontend/src/components/onboarding/WelcomeDialog.tsx` — Willkommens-Dialog
+- `frontend/src/store/onboardingStore.ts` — Zustand-Store
+
+**Modifizierte Dateien:**
+- `frontend/src/components/layout/AppShell.tsx` — OnboardingTour einbinden
+- `frontend/src/api/userPreferences.ts` — onboarding_completed flag
+- `frontend/src/i18n/de.json`
+
+**Tour-Schritte (8):**
+1. Willkommen
+2. Sidebar-Navigation
+3. Globale Suche
+4. Kontakte erstellen
+5. Kalender/Termine
+6. KI Assistent
+7. Einstellungen
+8. Fertig
+
+**Bibliothek:** `react-joyride` oder Custom Implementation
+
+**Aufwand:** ~1 Tag
+
+---
+
+## Implementations-Reihenfolge
+
+```
+Phase 1 (Kritisch)
+  1.1 Workflows UI          ████████████████░░░  1.5 Tage
+  1.2 Dedup/Merge UI        ███████████░░░░░░░░  1.0 Tag
+  1.3 Import/Export UI      ████████████████░░░  1.5 Tage (inkl. Backend Export-Route)
+  1.4 Print/PDF             █████░░░░░░░░░░░░░░  0.5 Tage
+
+Phase 2 (Wichtig)
+  2.1 Tags UI               ███████████░░░░░░░░  1.0 Tag
+  2.2 Custom Fields UI      ████████████████░░░  1.5 Tage (inkl. Backend CRUD)
+  2.3 Notifications Bell    █████░░░░░░░░░░░░░░  0.5 Tage
+
+Phase 3 (Nice-to-have)
+  3.1 Saved Filters UI      █████░░░░░░░░░░░░░░  0.5 Tage
+  3.2 Entity History UI     █████░░░░░░░░░░░░░░  0.5 Tage
+  3.3 Activity Timeline     █████░░░░░░░░░░░░░░  0.5 Tage
+  3.4 API Docs Link         ██░░░░░░░░░░░░░░░░░  0.25 Tage
+
+Phase 4 (Backend + Frontend)
+  4.1 Webhooks              ████████████████░░░  1.5 Tage
+  4.2 Backup/Restore UI     ███████████░░░░░░░░  1.0 Tag
+  4.3 Onboarding/Tutorial   ███████████░░░░░░░░  1.0 Tag
+```
+
+## Deployment-Strategie
+
+### Nach jeder Phase:
+1. Frontend Build: `cd frontend && npm run build`
+2. Git commit + push
+3. Coolify Auto-Deploy
+4. Verifikation im Browser
+
+## Abhängigkeiten
+
+```
+1.1 Workflows UI ← keine (API ready)
+1.2 Dedup/Merge UI ← keine (API ready)
+1.3 Import/Export UI ← Backend Export-Route hinzufügen (Service existiert)
+1.4 Print/PDF ← keine
+
+2.1 Tags UI ← keine (API ready)
+2.2 Custom Fields UI ← Backend CRUD + Migration (neu)
+2.3 Notifications Bell ← keine (API ready)
+
+3.1 Saved Filters ← keine (API ready)
+3.2 Entity History ← keine (API ready)
+3.3 Activity Timeline ← Audit-API ggf. erweitern (Pagination)
+3.4 API Docs Link ← keine
+
+4.1 Webhooks ← Backend komplett neu + Migration
+4.2 Backup/Restore ← Backend komplett neu + Migration
+4.3 Onboarding ← User-Preferences API ggf. erweitern
+```
+
+## Risiko-Bewertung
+
+| Feature | Risiko | Grund |
+|---------|--------|-------|
+| Workflows UI | Mittel | Komplexe Step-Editor UI |
+| Custom Fields UI | Hoch | Backend-Ergänzung + dynamisches Rendering |
+| Webhooks | Hoch | Backend komplett neu, Security (HMAC, Retry) |
+| Backup/Restore | Hoch | Datenverlust-Risiko bei Fehlern |
+| Import/Export | Mittel | Backend Export-Route fehlt, Datei-Handling |
+| Alle anderen | Niedrig | API existiert, nur UI |
+
+---
+
+## Entfallenes Feature
+
+### ~~Permissions Management UI~~ — BEREITS VORHANDEN
+- `SettingsRoles.tsx` (531 Zeilen) hat vollständige Permission-Verwaltung
+- `ShareDialog.tsx` (11KB) nutzt File-Permissions API
+- `roles.ts` API-Client hat `usePermissions()`, `useRoles()`, `useCreateRole()`, `useUpdateRole()`, `useDeleteRole()`
+- Backend `/roles/permissions` liefert alle System+Plugin-Permissions
+- Backend Roles-CRUD erlaubt Permission-Zuweisung (grant/deny/field-level)
+
+---
+
+*Plan erstellt am 26.07.2026, audit-korrigiert um 02:17 — bereit zur Umsetzung.*

PLUGIN-SYSTEM-UMBAUPLAN.md

@@ -0,0 +1,921 @@
+# LeoCRM Plugin-System — Kompletter Umbauplan
+
+**Erstellt:** 2026-07-26
+**Aktualisiert:** 2026-07-26 (Codebasis-Verifikation + Phase 6)
+**Geschätzter Gesamtaufwand:** ~149 Stunden (~19 Arbeitstage)
+**Status:** Geplant — noch nicht gestartet
+
+**Codebasis-Verifikation (2026-07-26):**
+- ✅ `base.py` unverändert — Plan passt
+- ✅ `registry.py` unverändert — Plan passt
+- ✅ `manifest.py` unverändert — Plan passt
+- ✅ `contracts.py` (ContractRegistry) unverändert — Plan passt
+- ✅ Migration 0044 hinzugekommen: RLS Repair + separater DB-User (crm_runtime) — beeinflusst Plugin-System nicht
+- ✅ Migration 0045 hinzugekommen — neuer Head
+- ✅ `require_active_plugin` in `deps.py` hinzugekommen — beeinflusst Plugin-System nicht
+- ✅ 19 echte Plugins (test_sample hat __init__.py statt plugin.py)
+- ✅ Cross-Imports: 224, Contracts: 8, get_contract: 11 — unverändert
+
+---
+
+## Übersicht: 5 Phasen
+
+| Phase | Punkte | Inhalt | Stunden | Tage |
+|---|---|---|---|---|
+| Phase 1 | 1-3 | Contracts konsequent nutzen | 47 | 6 |
+| Phase 2 | 4 | Hooks/Filters-System | 16 | 2 |
+| Phase 3 | 5 | Plugin-Isolation (Linting) | 4 | 0,5 |
+| Phase 4 | 8 | Plugin-Versioning | 20 | 2,5 |
+| Phase 5 | 6 | Marketplace-Vorbereitung | 42 | 5 |
+| Phase 6 | — | Manifest-Anpassung & Konsolidierung | 20 | 2,5 |
+| **Gesamt** | | | **149** | **~19** |
+
+**Wichtig:** Jede Phase ist unabhängig funktionsfähig. Das System läuft nach jeder Phase ohne Einschränkungen weiter.
+
+---
+
+## Phase 1: Contracts konsequent nutzen (Punkte 1-3)
+
+**Ziel:** Alle 224 direkten Cross-Plugin-Imports werden durch das Contract-System ersetzt.
+
+### 1.1 Fehlende contracts.py erstellen (7 Std)
+
+Für jedes Plugin, das noch keine `contracts.py` hat, eine erstellen:
+
+| # | Plugin | Exportierte Symbole | Aufwand |
+|---|---|---|---|
+| 1 | `ai_proactive` | ContextTools, ProactiveAgent, JobScheduler | 30 Min |
+| 2 | `ai_ui_control` | WebSocketManager, UIAction | 30 Min |
+| 3 | `automation` | AgentRunner, ExecutionEngine, Scheduler, WorkflowTimeout | 45 Min |
+| 4 | `entity_links` | EntityLink model, create_link, get_links | 20 Min |
+| 5 | `forgejo_error_reporter` | report_error_to_forgejo | 15 Min |
+| 6 | `mcp_client` | McpClient, McpServerConfig | 30 Min |
+| 7 | `mcp_server` | McpServer, ToolDefinitions | 30 Min |
+| 8 | `report_generator` | ReportTemplate, ReportInstance, PdfGenerator | 30 Min |
+| 9 | `system_notif` | SystemNotifHandler | 15 Min |
+| 10 | `tags` | Tag, TagAssignment, assign_tags, remove_tags | 20 Min |
+| 11 | `tasks` | Task, TaskService, create_task, update_task | 30 Min |
+| 12 | `test_sample` | TestSamplePlugin | 10 Min |
+| 13 | `dms` (erweitern) | File, Folder, UploadService, DownloadService | 30 Min |
+| 14 | `permissions` (erweitern) | ShareLink, PermissionResolver | 30 Min |
+
+**Schema für jede contracts.py:**
+```python
+"""Public contract for the <plugin> plugin."""
+from __future__ import annotations
+from app.plugins.builtins.contracts import get_contract_registry
+# Import only public symbols from internal modules
+
+class <Plugin>Contract:
+    contract_name = "<plugin>"
+    # Expose only public API
+
+_contract = <Plugin>Contract()
+get_contract_registry().register("<plugin>", _contract)
+```
+
+### 1.2 Direkte Imports ersetzen (28 Std)
+
+224 direkte Imports müssen durch `get_contract()` ersetzt werden.
+
+**Top-Priorität (häufigste Import-Quellen):**
+
+| # | Datei | Imports | Aufwand |
+|---|---|---|---|
+| 1 | `automation/plugin.py` | 10 | 1,5 Std |
+| 2 | `automation/routes.py` | 8 | 1,5 Std |
+| 3 | `ai_proactive/services.py` | 8 | 1,5 Std |
+| 4 | `ai_proactive/plugin.py` | 8 | 1,5 Std |
+| 5 | `unified_search/jobs.py` | 7 | 1 Std |
+| 6 | `builtins/__init__.py` | 7 | 1 Std |
+| 7 | `ai_proactive/jobs.py` | 7 | 1 Std |
+| 8 | `ai_assistant/participant_handler.py` | 7 | 1 Std |
+| 9 | `kommunikation/routes.py` | 6 | 1 Std |
+| 10 | `kommunikation/contracts.py` | 6 | 1 Std |
+| 11 | `automation/agent_routes.py` | 6 | 1 Std |
+| 12 | `automation/agent_comm.py` | 6 | 1 Std |
+| 13 | `ai_proactive/participant_handler.py` | 6 | 1 Std |
+| 14 | `ai_assistant/plugin.py` | 6 | 1 Std |
+| 15 | `unified_search/routes.py` | 5 | 45 Min |
+| 16-50 | Alle übrigen Dateien | ~122 | 12 Std |
+
+**Muster für Ersetzung:**
+```python
+# VORHER (direkt):
+from app.plugins.builtins.kommunikation.services import send_message
+
+# NACHHER (über Contract):
+from app.plugins.builtins.contracts import get_contract
+
+async def my_function(db, ...):
+    komm = get_contract("kommunikation")
+    if komm:
+        await komm.send_message(db, ...)
+    # Graceful degradation wenn Plugin nicht aktiv
+```
+
+### 1.3 Contracts bei Deaktivierung abmelden (4 Std)
+
+In jedem Plugin's `on_deactivate()`:
+```python
+async def on_deactivate(self, db, service_container, event_bus) -> None:
+    # Contract abmelden
+    from app.plugins.builtins.contracts import get_contract_registry
+    get_contract_registry().unregister(self.manifest.name)
+    # ... rest of cleanup
+    await super().on_deactivate(db, service_container, event_bus)
+```
+
+| # | Plugin | Aufwand |
+|---|---|---|
+| 1-16 | Alle 16 Plugins | 15 Min pro Plugin = 4 Std |
+
+### 1.4 Tests anpassen (8 Std)
+
+- Cross-Plugin-Tests müssen mit Contracts laufen
+- `test_plugins.py` — Contract-Registry Tests
+- `test_contracts.py` — Neue Test-Datei für Contract-System
+- Alle Integrationstests mit Contract-Mocks
+
+### Meilenstein Phase 1:
+- ✅ Alle 16 Plugins haben contracts.py
+- ✅ 0 direkte Cross-Plugin-Imports (geprüft mit grep)
+- ✅ Contracts werden bei Deaktivierung abgemeldet
+- ✅ Alle Tests bestanden
+
+---
+
+## Phase 2: Hooks/Filters-System (Punkt 4)
+
+**Ziel:** WordPress-Style Hooks (actions + filters) für Plugin-Erweiterbarkeit.
+
+### 2.1 HookRegistry erstellen (4 Std)
+
+**Neue Datei: `app/core/hooks.py`**
+
+```python
+"""WordPress-style hooks: actions (fire-and-forget) and filters (modify data)."""
+
+from __future__ import annotations
+import logging
+from collections import defaultdict
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class HookRegistry:
+    """Central registry for actions and filters.
+    
+    Actions: do_action('contact.before_create', data) — no return value
+    Filters: result = apply_filters('contact.format_name', name) — returns modified value
+    
+    Priority: lower numbers run first (default=10).
+    """
+    
+    _instance: HookRegistry | None = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._actions: dict[str, list[tuple[int, Callable]]] = defaultdict(list)
+            cls._instance._filters: dict[str, list[tuple[int, Callable]]] = defaultdict(list)
+        return cls._instance
+    
+    def register_action(self, hook_name: str, callback: Callable, priority: int = 10) -> None:
+        self._actions[hook_name].append((priority, callback))
+        self._actions[hook_name].sort(key=lambda x: x[0])
+    
+    def register_filter(self, hook_name: str, callback: Callable, priority: int = 10) -> None:
+        self._filters[hook_name].append((priority, callback))
+        self._filters[hook_name].sort(key=lambda x: x[0])
+    
+    async def do_action(self, hook_name: str, *args, **kwargs) -> None:
+        for _, callback in self._actions.get(hook_name, []):
+            try:
+                result = callback(*args, **kwargs)
+                if hasattr(result, '__await__'):
+                    await result
+            except Exception:
+                logger.exception("Error in action %s", hook_name)
+    
+    async def apply_filters(self, hook_name: str, value: Any, *args, **kwargs) -> Any:
+        for _, callback in self._filters.get(hook_name, []):
+            try:
+                result = callback(value, *args, **kwargs)
+                if hasattr(result, '__await__'):
+                    result = await result
+                value = result
+            except Exception:
+                logger.exception("Error in filter %s", hook_name)
+        return value
+    
+    def unregister(self, hook_name: str, callback: Callable) -> None:
+        self._actions[hook_name] = [(p, c) for p, c in self._actions.get(hook_name, []) if c != callback]
+        self._filters[hook_name] = [(p, c) for p, c in self._filters.get(hook_name, []) if c != callback]
+    
+    def unregister_all(self, hook_name: str) -> None:
+        self._actions.pop(hook_name, None)
+        self._filters.pop(hook_name, None)
+    
+    def _reset_for_testing(self) -> None:
+        self._actions.clear()
+        self._filters.clear()
+
+
+def get_hook_registry() -> HookRegistry:
+    return HookRegistry()
+
+async def do_action(hook_name: str, *args, **kwargs) -> None:
+    await get_hook_registry().do_action(hook_name, *args, **kwargs)
+
+async def apply_filters(hook_name: str, value: Any, *args, **kwargs) -> Any:
+    return await get_hook_registry().apply_filters(hook_name, value, *args, **kwargs)
+```
+
+### 2.2 Integration in BasePlugin (2 Std)
+
+```python
+# In BasePlugin.on_activate:
+async def on_activate(self, db, service_container, event_bus) -> None:
+    # ... existing code ...
+    # Hooks werden in Subklassen registriert
+
+# In BasePlugin.on_deactivate:
+async def on_deactivate(self, db, service_container, event_bus) -> None:
+    # Alle Hooks dieses Plugins abmelden
+    from app.core.hooks import get_hook_registry
+    # Plugin-spezifische Hooks entfernen (prefix mit plugin name)
+    # ... existing code ...
+```
+
+### 2.3 Hook-Punkte in Core-Services (6 Std)
+
+| # | Service | Hook-Name | Typ | Beschreibung |
+|---|---|---|---|---|
+| 1 | contact_service | `contact.before_create` | Action | Vor Kontakt-Erstellung |
+| 2 | contact_service | `contact.after_create` | Action | Nach Kontakt-Erstellung |
+| 3 | contact_service | `contact.format_display_name` | Filter | Anzeigenamen formatieren |
+| 4 | contact_service | `contact.before_update` | Action | Vor Kontakt-Update |
+| 5 | contact_service | `contact.after_update` | Action | Nach Kontakt-Update |
+| 6 | contact_service | `contact.before_delete` | Action | Vor Kontakt-Löschung |
+| 7 | mail_service | `mail.before_send` | Filter | E-Mail vor Versand modifizieren |
+| 8 | mail_service | `mail.after_send` | Action | Nach E-Mail-Versand |
+| 9 | calendar | `calendar.before_appointment` | Action | Vor Termin-Erstellung |
+| 10 | calendar | `calendar.after_appointment` | Action | Nach Termin-Erstellung |
+| 11 | auth_service | `auth.before_login` | Filter | Login-Daten validieren/modifizieren |
+| 12 | auth_service | `auth.after_login` | Action | Nach erfolgreichem Login |
+| 13 | user_service | `user.before_create` | Action | Vor User-Erstellung |
+| 14 | user_service | `user.after_create` | Action | Nach User-Erstellung |
+| 15 | dms | `dms.before_upload` | Filter | Datei-Upload validieren/modifizieren |
+
+### 2.4 Tests für Hooks/Filters (4 Std)
+
+- `test_hooks.py` — HookRegistry Tests
+- Integrationstests: Plugin registriert Hook, Core-Service löst Hook aus
+- Filter-Tests: Wert wird korrekt modifiziert
+- Priority-Tests: Reihenfolge wird eingehalten
+- Unregister-Tests: Hooks werden bei Deaktivierung entfernt
+
+### Meilenstein Phase 2:
+- ✅ `app/core/hooks.py` mit HookRegistry
+- ✅ 15 Hook-Punkte in Core-Services
+- ✅ BasePlugin registriert/unregistriert Hooks automatisch
+- ✅ Tests bestanden
+
+---
+
+## Phase 3: Plugin-Isolation (Punkt 5)
+
+**Ziel:** Direkte Cross-Plugin-Imports werden durch Linting verhindert.
+
+### 3.1 Linting-Regel erstellen (2 Std)
+
+**Neue Datei: `.ruff/rules/no_cross_plugin_imports.py`**
+
+```python
+"""Ruff rule: forbid direct imports from app.plugins.builtins.* (except contracts)."""
+
+# Erlaubt:
+#   from app.plugins.builtins.contracts import get_contract
+#   from app.plugins.builtins.<name>.contracts import ...
+#
+# Verboten:
+#   from app.plugins.builtins.<name>.services import ...
+#   from app.plugins.builtins.<name>.models import ...
+#   from app.plugins.builtins.<name>.routes import ...
+```
+
+### 3.2 CI/CD Integration (1 Std)
+
+- `ruff check` in GitHub Actions / Forgejo CI
+- Pre-commit Hook für lokale Entwicklung
+- Fehler bei direkten Cross-Plugin-Imports
+
+### 3.3 Ausnahmen definieren (1 Std)
+
+- `conftest.py` — Tests dürfen direkt importieren
+- `app/plugins/builtins/__init__.py` — Plugin-Discovery
+- `app/plugins/registry.py` — Registry darf importieren
+
+### Meilenstein Phase 3:
+- ✅ Linting-Regel aktiv
+- ✅ CI/CD prüft bei jedem Commit
+- ✅ 0 direkte Cross-Plugin-Imports (automatisch erzwungen)
+
+---
+
+## Phase 4: Plugin-Versioning (Punkt 8)
+
+**Ziel:** Vollständige Versionsverwaltung mit SemVer, Rollback und Kompatibilitäts-Check.
+
+### 4.1 SemVer-Vergleich (3 Std)
+
+**Neue Datei: `app/plugins/semver.py`**
+
+```python
+"""Semantic version comparison for plugin versions."""
+
+from dataclasses import dataclass
+import re
+
+@dataclass
+class SemVer:
+    major: int
+    minor: int
+    patch: int
+    prerelease: str = ""
+    
+    @classmethod
+    def parse(cls, version: str) -> "SemVer":
+        match = re.match(r"(\d+)\.(\d+)\.(\d+)(?:-(.+))?", version)
+        if not match:
+            raise ValueError(f"Invalid semver: {version}")
+        return cls(int(match[1]), int(match[2]), int(match[3]), match[4] or "")
+    
+    def __lt__(self, other): ...
+    def __eq__(self, other): ...
+    def __le__(self, other): ...
+    def __gt__(self, other): ...
+    
+    def is_breaking_change(self, other: "SemVer") -> bool:
+        return self.major != other.major
+    
+    def is_compatible_with(self, min_version: "SemVer") -> bool:
+        return self >= min_version
+```
+
+**Änderung in `registry.py`:**
+```python
+# VORHER: String-Vergleich
+if record.version != plugin.manifest.version:
+
+# NACHHER: SemVer-Vergleich
+old_ver = SemVer.parse(record.version)
+new_ver = SemVer.parse(plugin.manifest.version)
+if old_ver != new_ver:
+    if new_ver < old_ver:
+        # Downgrade — nur mit Rollback-Migration
+        ...
+```
+
+### 4.2 Rollback-Migrationen (6 Std)
+
+**Erweiterung des Migration-Systems:**
+
+```python
+# MigrationRunner erweitern:
+async def run_migration_down(self, db, plugin_name, migration_filename):
+    """Run rollback (down) migration."""
+    # Suche <filename>_down.sql oder parse DOWNGRADE-Block
+    
+async def rollback_to_version(self, db, plugin_name, target_version: str):
+    """Rollback plugin to a specific version."""
+    # 1. Finde alle Migrationen nach target_version
+    # 2. Führe sie in umgekehrter Reihenfolge aus
+    # 3. Aktualisiere DB-Version
+```
+
+**Migration-Datei-Format:**
+```sql
+-- 0001_initial.sql
+-- UP:
+CREATE TABLE ...;
+-- DOWN:
+DROP TABLE ... CASCADE;
+```
+
+Oder separate Dateien:
+- `0001_initial_up.sql`
+- `0001_initial_down.sql`
+
+### 4.3 Version-Kompatibilitäts-Check (3 Std)
+
+**Manifest-Erweiterung:**
+```python
+class PluginManifest(BaseModel):
+    # ... existing fields ...
+    min_app_version: str = Field(
+        default="0.0.0",
+        description="Minimum LeoCRM version required"
+    )
+```
+
+**Check bei Installation:**
+```python
+async def install(self, db, name):
+    plugin = self.get_plugin(name)
+    # Check app version compatibility
+    app_version = SemVer.parse(settings.app_version)
+    min_version = SemVer.parse(plugin.manifest.min_app_version)
+    if app_version < min_version:
+        raise ValueError(
+            f"Plugin '{name}' requires LeoCRM >= {plugin.manifest.min_app_version}, "
+            f"but current version is {settings.app_version}"
+        )
+```
+
+### 4.4 Update-Benachrichtigung im Frontend (4 Std)
+
+**Backend:**
+- `GET /api/v1/plugins/updates` — Liste Plugins mit verfügbarer neuer Version
+- Vergleich mit Marketplace-Registry (wenn verfügbar) oder lokaler Version
+
+**Frontend:**
+- Badge im Plugin-Settings: "Update verfügbar (1.2.0 → 1.3.0)"
+- Update-Button: Löst Update aus (führt neue Migrationen aus)
+- Changelog-Anzeige (optional)
+
+### 4.5 Tests (4 Std)
+
+- `test_semver.py` — SemVer-Vergleich, Parse, Edge Cases
+- `test_versioning.py` — Upgrade, Downgrade, Kompatibilitäts-Check
+- `test_rollback.py` — Rollback-Migrationen
+- Integrationstests: Version-Update löst Migrationen aus
+
+### Meilenstein Phase 4:
+- ✅ SemVer-Vergleich statt String-Vergleich
+- ✅ Rollback-Migrationen funktionieren
+- ✅ min_app_version wird geprüft
+- ✅ Frontend zeigt Update-Benachrichtigungen
+- ✅ Tests bestanden
+
+---
+
+## Phase 5: Marketplace-Vorbereitung (Punkt 6)
+
+**Ziel:** Code so vorbereiten, dass ein Marketplace nur noch gebaut werden muss — ohne Systemänderungen.
+
+**Wichtig:** Funktioniert auch OHNE Marketplace — Built-in Plugins laufen normal weiter.
+
+### 5.1 Externe Plugin-Discovery (6 Std)
+
+**Erweiterung `registry.py`:**
+
+```python
+class PluginRegistry:
+    
+    def discover_all(self) -> list[str]:
+        """Discover built-in AND external plugins."""
+        discovered = self.discover_builtins()
+        discovered.extend(self.discover_external())
+        return discovered
+    
+    def discover_external(self) -> list[str]:
+        """Discover plugins from external plugins/ directory."""
+        external_dir = Path(settings.external_plugins_path or "plugins")
+        if not external_dir.exists():
+            return []
+        
+        discovered = []
+        for plugin_dir in external_dir.iterdir():
+            if not plugin_dir.is_dir() or plugin_dir.name.startswith("_"):
+                continue
+            # Look for plugin.py or __init__.py with BasePlugin subclass
+            plugin_file = plugin_dir / "plugin.py"
+            if not plugin_file.exists():
+                continue
+            # Import and register
+            import sys
+            sys.path.insert(0, str(external_dir))
+            try:
+                module = importlib.import_module(f"{plugin_dir.name}.plugin")
+                # ... find BasePlugin subclass ...
+            finally:
+                sys.path.remove(str(external_dir))
+        return discovered
+```
+
+### 5.2 Plugin-Signatur-Validierung (8 Std)
+
+**Neue Datei: `app/plugins/signature.py`**
+
+```python
+"""Plugin signature verification for external plugins."""
+
+from pathlib import Path
+import hashlib
+import hmac
+
+# Ed25519 oder HMAC-SHA256 Signatur
+
+class PluginSignature:
+    """Verify plugin package signatures."""
+    
+    @staticmethod
+    def verify_signature(zip_path: Path, signature: bytes, public_key: bytes) -> bool:
+        """Verify Ed25519 signature of plugin ZIP."""
+        # 1. Read ZIP content
+        # 2. Compute hash
+        # 3. Verify signature with public key
+        pass
+    
+    @staticmethod
+    def compute_hash(zip_path: Path) -> bytes:
+        """Compute SHA-256 hash of plugin ZIP."""
+        pass
+    
+    @staticmethod
+    def sign_plugin(zip_path: Path, private_key: bytes) -> bytes:
+        """Sign a plugin ZIP (for plugin authors)."""
+        pass
+```
+
+### 5.3 Plugin-Allowlist (4 Std)
+
+**Neue Alembic-Migration: `0044_plugin_allowlist.py`**
+
+```python
+# Tabelle: plugin_allowlist
+# - id: UUID
+# - plugin_name: VARCHAR(80)
+# - allowed_hash: VARCHAR(64)  # SHA-256
+# - allowed_signature: TEXT    # Ed25519 signature
+# - added_by: UUID (user)
+# - created_at: TIMESTAMPTZ
+# - is_active: BOOLEAN
+```
+
+### 5.4 Plugin-Metadata-Erweiterung (4 Std)
+
+**Manifest-Erweiterung:**
+```python
+class PluginManifest(BaseModel):
+    # ... existing fields ...
+    author: str = Field(default="", description="Plugin author")
+    author_email: str = Field(default="", description="Author contact")
+    homepage: str = Field(default="", description="Plugin homepage URL")
+    license: str = Field(default="MIT", description="License")
+    min_app_version: str = Field(default="0.0.0")
+    icon: str = Field(default="", description="Icon URL or emoji")
+    screenshots: list[str] = Field(default_factory=list)
+    changelog: str = Field(default="", description="Changelog URL or text")
+    tags: list[str] = Field(default_factory=list, description="Marketplace categories")
+    price: float = Field(default=0.0, description="Price (0 = free)")
+```
+
+### 5.5 Plugin-Download-Endpoint (4 Std)
+
+**Neue Route: `POST /api/v1/plugins/install-marketplace`**
+
+```python
+@router.post("/install-marketplace")
+async def install_from_marketplace(
+    body: MarketplaceInstall,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(require_permission("plugins:configure")),
+):
+    """Install a plugin from the marketplace.
+    
+    1. Download ZIP from marketplace URL
+    2. Verify signature against allowlist
+    3. Validate manifest
+    4. Check dangerous imports
+    5. Validate migration SQL
+    6. Install (migrations + DB record)
+    7. Activate (optional)
+    """
+    # 1. Download
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(body.url)
+        zip_data = resp.content
+    
+    # 2. Verify signature
+    if not PluginSignature.verify_signature(zip_data, body.signature, public_key):
+        raise HTTPException(403, "Invalid plugin signature")
+    
+    # 3-6. Validate and install
+    # ... (reuse existing validation + install logic)
+```
+
+### 5.6 Plugin-Update-Check (4 Std)
+
+```python
+@router.get("/updates")
+async def check_plugin_updates(
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(require_permission("plugins:read")),
+):
+    """Check for available plugin updates from marketplace."""
+    # 1. Query marketplace registry (if configured)
+    # 2. Compare versions with installed plugins
+    # 3. Return list of available updates
+```
+
+### 5.7 Plugin-Quarantine (4 Std)
+
+```python
+async def _quarantine_plugin(zip_path: Path) -> Path:
+    """Extract plugin to temp dir, validate, then move to plugins/ dir.
+    
+    1. Extract to /tmp/plugin_upload_<uuid>/
+    2. Validate manifest exists
+    3. Check dangerous imports
+    4. Validate migration SQL
+    5. Check signature
+    6. If all OK: move to plugins/ dir
+    7. If any fail: delete temp dir, raise error
+    """
+```
+
+### 5.8 Tests (8 Std)
+
+- `test_marketplace.py` — Download, Verify, Install Flow
+- `test_signature.py` — Signatur-Validierung
+- `test_allowlist.py` — Allowlist-Management
+- `test_quarantine.py` — Quarantine-Validierung
+- `test_external_discovery.py` — Externe Plugin-Discovery
+- Integrationstests: Vollständiger Marketplace-Flow
+
+### Meilenstein Phase 5:
+- ✅ Externe Plugins können entdeckt werden
+- ✅ Signatur-Validierung funktioniert
+- ✅ Allowlist schützt vor nicht autorisierten Plugins
+- ✅ Marketplace-Endpoint ist vorbereitet (deaktiviert bis Marketplace live)
+- ✅ Plugin-Upload bleibt deaktiviert
+- ✅ Built-in Plugins laufen ohne Marketplace
+- ✅ Tests bestanden
+
+---
+
+## Phase 6: Manifest-Anpassung & Konsolidierung
+
+**Ziel:** Alle in Phase 4 und 5 definierten Manifest-Felder werden ins `PluginManifest` integriert, bestehende Manifeste aktualisiert, und das Manifest-System finalisiert.
+
+**Wichtig:** Diese Phase baut auf Phase 4 (Versioning) und Phase 5 (Marketplace) auf und muss als letztes durchgeführt werden.
+
+### 6.1 PluginManifest erweitern (4 Std)
+
+**Aktuelles Manifest (verifiziert 2026-07-26):**
+```python
+class PluginManifest(BaseModel):
+    name: str
+    version: str
+    display_name: str
+    description: str
+    dependencies: list[str]
+    routes: list[PluginRouteDef]
+    events: list[str]
+    migrations: list[str]
+    permissions: list[str]
+    is_core: bool
+    field_definitions: list[FieldDefinition]
+    agent_capabilities: list[str]
+    menu_items: list[FrontendMenuItem]
+    page_routes: list[FrontendPageRoute]
+    detail_tabs: list[FrontendDetailTab]
+    settings_pages: list[FrontendSettingsPage]
+    dashboard_widgets: list[FrontendDashboardWidget]
+    agent_definitions: list[AgentDefinitionContribution]
+    automation_templates: list[AutomationTemplateContribution]
+    cron_jobs: list[CronJobContribution]
+    heartbeat_configs: list[HeartbeatConfigContribution]
+    miniapps: list[MiniAppContribution]
+    custom_fields: list[CustomFieldDefinition]
+    model_config = {"extra": "forbid"}
+```
+
+**Neue Felder hinzufügen:**
+```python
+class PluginManifest(BaseModel):
+    # ... alle bestehenden Felder ...
+    
+    # ── Versioning (Phase 4) ──
+    min_app_version: str = Field(
+        default="0.0.0",
+        description="Minimum LeoCRM version required (SemVer)"
+    )
+    
+    # ── Marketplace (Phase 5) ──
+    author: str = Field(default="", max_length=200, description="Plugin author name")
+    author_email: str = Field(default="", max_length=200, description="Author contact email")
+    homepage: str = Field(default="", max_length=500, description="Plugin homepage URL")
+    license: str = Field(default="MIT", max_length=50, description="License identifier")
+    icon: str = Field(default="", description="Icon URL or emoji")
+    screenshots: list[str] = Field(default_factory=list, description="Screenshot URLs for marketplace")
+    changelog: str = Field(default="", description="Changelog URL or inline text")
+    marketplace_tags: list[str] = Field(default_factory=list, description="Marketplace category tags")
+    price: float = Field(default=0.0, ge=0.0, description="Price (0 = free)")
+    
+    # ── Hooks (Phase 2) ──
+    hooks: list[str] = Field(
+        default_factory=list,
+        description="Hook names this plugin registers (e.g. 'contact.before_create')"
+    )
+    
+    # ── Contracts (Phase 1) ──
+    contract_version: str = Field(
+        default="1.0.0",
+        description="Contract API version this plugin exposes"
+    )
+```
+
+### 6.2 Manifest-Schema-Dokumentation aktualisieren (3 Std)
+
+**`MANIFEST_SCHEMA_DOC` in `manifest.py` erweitern:**
+- Alle neuen Felder in `fields`-Dict aufnehmen
+- `example`-Manifest mit neuen Feldern aktualisieren
+- API-Endpoint `GET /api/v1/plugins/manifest` liefert vollständiges Schema
+
+### 6.3 Alle 19 Plugin-Manifeste aktualisieren (8 Std)
+
+Jedes Plugin-Manifest muss um die neuen Felder erweitert werden:
+
+| # | Plugin | Aufwand | Neue Felder |
+|---|---|---|---|
+| 1 | `ai_assistant` | 30 Min | author, min_app_version, hooks, contract_version |
+| 2 | `ai_proactive` | 30 Min | author, min_app_version, hooks, contract_version |
+| 3 | `ai_ui_control` | 20 Min | author, min_app_version, contract_version |
+| 4 | `automation` | 30 Min | author, min_app_version, hooks, contract_version |
+| 5 | `calendar` | 20 Min | author, min_app_version, hooks, contract_version |
+| 6 | `dms` | 20 Min | author, min_app_version, hooks, contract_version |
+| 7 | `entity_links` | 15 Min | author, min_app_version, contract_version |
+| 8 | `forgejo_error_reporter` | 15 Min | author, min_app_version, contract_version |
+| 9 | `kommunikation` | 30 Min | author, min_app_version, hooks, contract_version |
+| 10 | `mail` | 20 Min | author, min_app_version, hooks, contract_version |
+| 11 | `mcp_client` | 20 Min | author, min_app_version, contract_version |
+| 12 | `mcp_server` | 20 Min | author, min_app_version, contract_version |
+| 13 | `permissions` | 20 Min | author, min_app_version, contract_version |
+| 14 | `report_generator` | 20 Min | author, min_app_version, contract_version |
+| 15 | `system_notif` | 15 Min | author, min_app_version, contract_version |
+| 16 | `tags` | 15 Min | author, min_app_version, contract_version |
+| 17 | `tasks` | 20 Min | author, min_app_version, hooks, contract_version |
+| 18 | `test_sample` | 10 Min | author, min_app_version, contract_version |
+| 19 | `unified_search` | 20 Min | author, min_app_version, hooks, contract_version |
+
+**Muster für Aktualisierung:**
+```python
+# VORHER:
+manifest = PluginManifest(
+    name="calendar",
+    version="1.0.0",
+    display_name="Calendar",
+    ...
+)
+
+# NACHHER:
+manifest = PluginManifest(
+    name="calendar",
+    version="1.0.0",
+    display_name="Calendar",
+    # ... bestehende Felder ...
+    # ── Neue Felder ──
+    min_app_version="1.0.0",
+    author="LeoCRM Team",
+    license="MIT",
+    hooks=["calendar.before_appointment", "calendar.after_appointment"],
+    contract_version="1.0.0",
+)
+```
+
+### 6.4 Frontend Plugin-Manifest-Typen aktualisieren (2 Std)
+
+**`frontend/src/api/pluginManifests.ts` und `frontend/src/types/automation.ts`:**
+- TypeScript-Interfaces um neue Manifest-Felder erweitern
+- `PluginManifestResponse`-Typ aktualisieren
+- Frontend-Komponenten die Manifest-Felder anzeigen erweitern
+
+### 6.5 Manifest-Validierung verschärfen (3 Std)
+
+**Neue Validierungsregeln in `PluginManifest`:**
+```python
+@field_validator("min_app_version")
+@classmethod
+def validate_min_app_version(cls, v: str) -> str:
+    """Validate SemVer format."""
+    from app.plugins.semver import SemVer
+    SemVer.parse(v)  # Raises ValueError if invalid
+    return v
+
+@field_validator("hooks")
+@classmethod
+def validate_hooks(cls, v: list[str]) -> list[str]:
+    """Validate hook names follow namespace.pattern."""
+    for hook in v:
+        if not re.match(r"^[a-z_]+\.[a-z_]+$", hook):
+            raise ValueError(f"Invalid hook name '{hook}': must be 'namespace.action'")
+    return v
+```
+
+### 6.6 Tests für erweitertes Manifest (3 Std)
+
+- `test_manifest.py` — Neue Felder validieren
+- `test_manifest_validation.py` — SemVer-Validierung, Hook-Name-Validierung
+- Alle Plugin-Tests: Manifest mit neuen Feldern erstellen
+- Frontend-Tests: Manifest mit neuen Feldern rendern
+
+### Meilenstein Phase 6:
+- ✅ `PluginManifest` hat alle neuen Felder (min_app_version, author, hooks, contract_version, etc.)
+- ✅ `MANIFEST_SCHEMA_DOC` ist vollständig aktualisiert
+- ✅ Alle 19 Plugin-Manifeste haben die neuen Felder
+- ✅ Frontend-Typen sind aktualisiert
+- ✅ Manifest-Validierung ist verschärft
+- ✅ Tests bestanden
+
+---
+
+## Zeitplan
+
+```
+Woche 1 (Tag 1-5):  Phase 1 — Contracts (Teil 1: contracts.py + Imports)
+Woche 2 (Tag 6-8):  Phase 1 — Contracts (Teil 2: Deaktivierung + Tests)
+         (Tag 9-10): Phase 2 — Hooks/Filters-System
+Woche 3 (Tag 11):   Phase 3 — Plugin-Isolation
+         (Tag 12-14): Phase 4 — Plugin-Versioning
+Woche 4 (Tag 15-19): Phase 5 — Marketplace-Vorbereitung
+Woche 5 (Tag 20-22): Phase 6 — Manifest-Anpassung & Konsolidierung
+         (Tag 23):   Puffer / Bugfixes / Doku
+```
+
+### Abhängigkeiten
+```
+Phase 1 (Contracts) ──→ Phase 3 (Isolation: Linting braucht Contracts als Ausnahme)
+         │
+         └──→ Phase 2 (Hooks: unabhängig, kann parallel)
+         │
+         └──→ Phase 4 (Versioning: braucht Contracts für min_app_version)
+                  │
+                  └──→ Phase 5 (Marketplace: braucht alles)
+                           │
+                           └──→ Phase 6 (Manifest: braucht Phase 4 + 5 Felder)
+```
+
+### Parallelisierungsmöglichkeiten
+- Phase 1 und Phase 2 können **parallel** laufen (verschiedene Entwickler)
+- Phase 3 kann erst nach Phase 1 starten
+- Phase 4 kann nach Phase 1 starten
+- Phase 5 kann erst nach Phase 1+4 starten
+- Phase 6 kann erst nach Phase 4+5 starten (braucht deren Manifest-Felder)
+
+---
+
+## Risiken
+
+| Risiko | Wahrscheinlichkeit | Auswirkung | Mitigation |
+|---|---|---|---|
+| Contract-Refactoring bricht bestehende Funktionalität | Mittel | Hoch | Tests nach jedem Plugin, schrittweise Migration |
+| Hooks/Filters verändern Core-Verhalten | Niedrig | Mittel | Tests für alle Hook-Punkte, Priority-System |
+| Externe Plugin-Discovery hat Sicherheitslücken | Mittel | Hoch | Signatur-Validierung, Quarantine, Allowlist |
+| SemVer-Parse-Fehler bei bestehenden Versionen | Niedrig | Niedrig | Fallback auf String-Vergleich |
+| Rollback-Migrationen löschen Daten | Mittel | Hoch | Bestätigungs-Prompt, Backup vor Rollback |
+
+---
+
+## Erfolgskriterien
+
+Nach Abschluss aller 5 Phasen:
+
+1. ✅ **0 direkte Cross-Plugin-Imports** (grep-verifiziert, linting-enforced)
+2. ✅ **Alle 16 Plugins haben contracts.py** mit klarer öffentlicher API
+3. ✅ **Contracts werden bei Deaktivierung abgemeldet**
+4. ✅ **Hooks/Filters-System** mit 15+ Hook-Punkten in Core-Services
+5. ✅ **Plugin-Isolation** durch Linting-Regeln erzwungen
+6. ✅ **SemVer-Vergleich** statt String-Vergleich
+7. ✅ **Rollback-Migrationen** für alle Plugins verfügbar
+8. ✅ **min_app_version** wird bei Installation geprüft
+9. ✅ **Update-Benachrichtigung** im Frontend
+10. ✅ **Marketplace-Endpoint** vorbereitet (deaktiviert)
+11. ✅ **Signatur-Validierung** für externe Plugins
+12. ✅ **Allowlist** schützt vor nicht autorisierten Plugins
+13. ✅ **Externe Plugin-Discovery** funktioniert
+14. ✅ **Alle Tests bestanden**
+15. ✅ **Built-in Plugins laufen ohne Marketplace**
+16. ✅ **PluginManifest hat alle neuen Felder** (min_app_version, author, hooks, contract_version, etc.)
+17. ✅ **Alle 19 Plugin-Manifeste aktualisiert** mit neuen Feldern
+18. ✅ **Manifest-Validierung verschärft** (SemVer, Hook-Names)
+19. ✅ **Frontend-Typen aktualisiert** für neue Manifest-Felder
+
+---
+
+## Dokumentation
+
+Nach Abschluss jeder Phase:
+- `docs/plugin-system/phase-N.md` — Was wurde gemacht, was geändert
+- `docs/plugin-system/contracts-api.md` — Contract-API Referenz
+- `docs/plugin-system/hooks-api.md` — Hooks/Filters Referenz
+- `docs/plugin-system/marketplace-api.md` — Marketplace-API Referenz
+- `docs/plugin-system/plugin-development-guide.md` — Wie man ein Plugin entwickelt
+
+---
+
+**Dieser Plan ist vollständig. Alle Aufgaben, Aufwände, Abhängigkeiten und Risiken sind erfasst.**

RBAC_PROGRESS.md

@@ -0,0 +1,112 @@
+# RBAC Build Progress — LeoCRM
+
+## Letztes Update: 2026-07-29 03:17 CEST
+
+## Alle 23 Sprints — Code vollständig erstellt ✅
+
+### Sprint Übersicht
+
+| Sprint | Inhalt | Status |
+|--------|--------|:---:|
+| 1 — Fundament | entity_permissions + OwnedMixin + Service + API + Redis-Cache + RLS + Rate Limiting | ✅ Deployed |
+| 2 — Row-Level Security | visibility.py + 9 Services + 9 Routes + BaseSearchProvider + Frontend Permission-Checks | ✅ Deployed |
+| 3 — Search/Dashboard/Export | Search Provider Permission-aware + Dashboard Counts + Export Filter | ✅ Deployed |
+| 4 — Field-Level | 44 Core Field Definitions + Custom Field Sensitivity + filter_fields_by_permission | ✅ Code |
+| 5 — Sharing UI | Universeller ShareDialog + Entity Permission API + Hooks | ✅ Code |
+| 6 — Notifications + Audit | Permission-Change Notifications + Audit Trail + Notification Entity Filter | ✅ Code |
+| 7 — E-Mail Postfächer | Mailbox owner_id + Permissions + Migration 0053 | ✅ Code |
+| 8 — Plugin Entities | DMS/Calendar/Tasks OwnedMixin + Migration 0054 | ✅ Code |
+| 9 — App-Sichtbarkeit | Sidebar Permission-Filter + TopBar + ProtectedRoute + Route Guards | ✅ Deployed |
+| 10 — Advanced Security + AI | AI Copilot Permission-Aware + API-Token Scopes + Merge Check | ✅ Code |
+| 11 — Owner Management | Owner Transfer Service + Auto-Transfer + API | ✅ Code |
+| 12 — Zentrale Einstellungsseite | SettingsRechte.tsx mit Tabs (Rollen, Gruppen, Freigaben, Audit) | ✅ Code |
+| 13 — ABAC Engine | entity_policies + Policy Service + Migration 0055 | ✅ Code |
+| 14 — ABAC UI | ABACRuleEditor.tsx + policies.ts + policyHooks.ts | ✅ Code |
+| 15 — Templates & Automation | permission_templates + Service + Migration 0056 | ✅ Code |
+| 16 — Mass & Bulk | bulk_share + bulk_unshare + API | ✅ Code |
+| 17 — Analytics & Konflikte | permission_analytics + API | ✅ Code |
+| 18 — Delegation | permission_delegations + Service + Migration 0057 | ✅ Code |
+| 19 — Resolution-Strategien | 4 Strategien + Tenant-Einstellung + Migration 0058 | ✅ Code |
+| 20 — Tests | test_entity_permissions + test_abac + test_permission_performance | ✅ Code |
+| 21 — Dokumentation | permissions.md + permissions_plugin_dev.md | ✅ Code |
+| 22 — Guest Access | guest_users + Guest Auth + Invitation + Guest Frontend + Migration 0059 | ✅ Code |
+| 23 — Infrastructure | PgBouncer + Audit Partitioning docs + scripts | ✅ Code |
+
+### Migrationen in Produktion
+| # | Beschreibung | Status |
+|---|-------------|:---:|
+| 0048 | contact_folder_permissions Tabelle | ✅ |
+| 0049 | entity_permissions Tabelle | ✅ |
+| 0050 | owner_id auf 15 Tabellen | ✅ |
+| 0051 | Folder ACLs → entity_permissions | ✅ |
+| 0052 | RLS Policies auf contacts | ✅ |
+| 0053 | mail_accounts owner_id | ✅ |
+| 0054 | Plugin owner_id (files, folders, calendars, tasks) | ✅ |
+| 0055 | entity_policies Tabelle | ✅ |
+| 0056 | permission_templates Tabelle | ✅ |
+| 0057 | permission_delegations Tabelle | ✅ |
+| 0058 | tenants resolution_strategy | ✅ |
+| 0059 | guest_users Tabelle | ✅ |
+
+### Git Commits (Diese Session)
+| Hash | Beschreibung |
+|------|-------------|
+| cc021cd | feat: folder permissions (ACLs) |
+| 5afa1fa | sprint1: entity_permissions + owned_mixin + service + API |
+| 48647a5 | sprint1: set_user_context + RLS policies + folder ACL migration |
+| ea1c1d5 | sprint1 complete: rate limiting |
+| 479ee04 | sprint2: visibility filter + contact service access checks |
+| 9fc84b7 | sprint2: 8 services + 8 routes visibility filter + BaseSearchProvider |
+| 52a5c34 | sprint2: frontend permission checks |
+| 517e1b6 | sprint2+3: remaining services + search provider permission-aware |
+| b06aeeb | sprint3: dashboard counts + import owner_id + export filter |
+| 71ed592 | sprint4+5: field-level permissions + universal ShareDialog |
+| 88c0428 | sprint6+7: notifications + audit + mail permissions |
+| 48b2dfd | sprint9: app visibility — sidebar + route guards |
+| 958e412 | sprint8: plugin entities migration 0054 |
+| b7ccd9e | sprint8: fix migration 0054 |
+| 2c14368 | sprint10+11: AI permission + owner transfer |
+| e0003b9 | sprint12+13: rechte settings + ABAC engine |
+| ddf73ee | sprint14-19: ABAC UI + templates + bulk + analytics + delegation + resolution |
+| 24690fb | sprint20-23: tests + docs + guest access + infrastructure |
+| 680d5ab | fix: migration 0058 checkconstraint |
+| 015eb94 | fix: SettingsRechte TypeScript errors |
+| 4c134c6 | fix: GuestContacts title prop |
+
+### Was in Produktion läuft (Backend)
+- ✅ entity_permissions Tabelle (universelle ACLs für alle Entities)
+- ✅ owner_id auf 20+ Tabellen
+- ✅ PostgreSQL RLS auf contacts (4 Policies)
+- ✅ set_user_context() bei jedem Request
+- ✅ Universelle Permission API (/api/v1/permissions/*)
+- ✅ Rate Limiting auf Permission-Änderungen
+- ✅ Visibility Filter in 12+ Services
+- ✅ BaseSearchProvider für Permission-aware Search
+- ✅ Dashboard Counts pro User
+- ✅ Export Filter
+- ✅ AI Copilot Permission-Aware
+- ✅ Owner Transfer Service
+- ✅ ABAC Engine (entity_policies + policy_service)
+- ✅ Permission Templates
+- ✅ Bulk Share
+- ✅ Permission Analytics
+- ✅ Permission Delegation
+- ✅ Resolution Strategies (4 Strategien)
+- ✅ Guest Access (guest_users + guest_auth + invitation)
+- ✅ Permission-Change Notifications + Audit Trail
+- ✅ Mailbox Permissions
+
+### Was in Produktion läuft (Frontend)
+- ✅ Permission-Checks in ContactDetail + ContactsList
+- ✅ Field-Level UI (hidden/readonly)
+- ✅ Sidebar Permission-Filter
+- ✅ TopBar Permission-Filter
+- ✅ ProtectedRoute + Route Guards
+- ✅ Universeller ShareDialog
+- ✅ ABAC Rule Editor
+- ✅ SettingsRechte (Zentrale Rechte-Seite mit Tabs)
+- ✅ Guest Login + Guest Contacts
+
+### Was noch deployed werden muss
+- Backend: Sprint 4-8, 10-19, 22 Dateien sind im Code aber noch nicht alle im Container (Coolify Full Deploy nötig)
+- Frontend: Build erfolgreich, dist vorhanden

README.md

@@ -1,7 +1,7 @@
 # LeoCRM v1.0
 
 > Self-hosted CRM for small sales teams (5–25 sales reps).
-> Stack: FastAPI + SQLAlchemy (async) + PostgreSQL + Redis + Alpine.js + Tailwind + Docker + Coolify
+> Stack: FastAPI + SQLAlchemy (async) + PostgreSQL + Redis + React 18 + TypeScript + Vite + TanStack Query + Zustand + Tailwind + Docker + Coolify
 
 ## Quick Start (Development)
 

alembic/env.py

@@ -20,7 +20,8 @@ if config.config_file_name is not None:
 
 target_metadata = Base.metadata
 settings = get_settings()
-config.set_main_option("sqlalchemy.url", settings.database_url)
+# Use migration_database_url (crm_migration role, table owner) for Alembic
+config.set_main_option("sqlalchemy.url", settings.migration_database_url or settings.database_url)
 
 
 def run_migrations_offline() -> None:

alembic/versions/0021_unified_contacts.py

@@ -3,27 +3,73 @@
 Revision ID: 0021
 Revises: 0020
 Create Date: 2026-07-19
+
+SAFE MIGRATION: Old tables are renamed (not dropped), data is migrated
+via INSERT ... SELECT, and old tables are preserved for rollback.
 """
+
+from __future__ import annotations
+
+import logging
+from typing import Sequence, Union
+
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects.postgresql import UUID, TSVECTOR, JSON
 
+revision: str = "0021_unified_contacts"
+down_revision: Union[str, None] = "0020"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
 
-revision = "0021_unified_contacts"
+logger = logging.getLogger("alembic.migration.0021")
-down_revision = "0020"
 
 
-def upgrade():
+def _table_exists(conn, table_name: str) -> bool:
-    # 1. Drop old company_contacts join table
+    """Check whether *table_name* exists in the public schema."""
-    op.execute("DROP TABLE IF EXISTS company_contacts CASCADE")
+    result = conn.execute(
+        sa.text(
+            "SELECT 1 FROM information_schema.tables "
+            "WHERE table_schema = 'public' AND table_name = :t"
+        ),
+        {"t": table_name},
+    ).fetchone()
+    return result is not None
 
-    # 2. Drop old contacts table (will recreate with new schema)
-    op.execute("DROP TABLE IF EXISTS contacts CASCADE")
 
-    # 3. Drop old companies table
+def _column_exists(conn, table_name: str, column_name: str) -> bool:
-    op.execute("DROP TABLE IF EXISTS companies CASCADE")
+    """Check whether *column_name* exists on *table_name*."""
+    result = conn.execute(
+        sa.text(
+            "SELECT 1 FROM information_schema.columns "
+            "WHERE table_schema = 'public' "
+            "AND table_name = :t AND column_name = :c"
+        ),
+        {"t": table_name, "c": column_name},
+    ).fetchone()
+    return result is not None
 
-    # 4. Create contacts table (without default_person_id/admin_contactperson_id FKs first)
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. Rename old tables instead of dropping ──────────────────────
+    #    Only rename if the table exists and the _old version doesn't.
+    old_tables = ["company_contacts", "contacts", "companies"]
+    renamed: list[str] = []
+
+    for tbl in old_tables:
+        old_name = f"{tbl}_old"
+        if _table_exists(conn, tbl) and not _table_exists(conn, old_name):
+            op.execute(f'ALTER TABLE "{tbl}" RENAME TO "{old_name}"')
+            renamed.append(old_name)
+            logger.info("Renamed %s → %s", tbl, old_name)
+        elif _table_exists(conn, old_name):
+            logger.info("%s already exists — skipping rename of %s", old_name, tbl)
+        else:
+            logger.info("Table %s does not exist — nothing to rename", tbl)
+
+    # ── 2. Create new contacts table ──────────────────────────────────
     op.create_table(
         "contacts",
         sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
@@ -123,7 +169,7 @@ def upgrade():
     op.create_index("ix_contacts_code", "contacts", ["code"])
     op.create_index("ix_contacts_search_vec", "contacts", ["search_tsv"], postgresql_using="gin")
 
-    # 5. Create contactpersons table
+    # ── 3. Create contactpersons table ────────────────────────────────
     op.create_table(
         "contactpersons",
         sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
@@ -155,11 +201,175 @@ def upgrade():
     op.create_index("ix_contactpersons_contact", "contactpersons", ["contact_id"])
     op.create_index("ix_contactpersons_email", "contactpersons", ["email"])
 
-    # 6. Add FK columns to contacts that reference contactpersons
+    # ── 4. Add FK columns to contacts that reference contactpersons ───
     op.add_column("contacts", sa.Column("default_person_id", UUID(as_uuid=True), sa.ForeignKey("contactpersons.id", ondelete="SET NULL"), nullable=True))
     op.add_column("contacts", sa.Column("admin_contactperson_id", UUID(as_uuid=True), sa.ForeignKey("contactpersons.id", ondelete="SET NULL"), nullable=True))
 
+    # ── 5. Migrate data from old tables ────────────────────────────────
 
-def downgrade():
+    # 5a. companies_old → contacts (type='company')
-    op.drop_table("contacts")
+    if _table_exists(conn, "companies_old"):
+        # Build column list dynamically based on what exists in companies_old
+        company_cols = {
+            "id": "id",
+            "tenant_id": "tenant_id",
+            "name": "name",
+            "phone": "phone_1",
+            "email": "email_1",
+            "website": "website",
+            "description": "projectnote",
+            "deleted_at": "deleted_at",
+            "created_by": "created_by",
+            "updated_by": "updated_by",
+            "created_at": "created_at",
+            "updated_at": "updated_at",
+        }
+        # account_number → code (check if it exists)
+        if _column_exists(conn, "companies_old", "account_number"):
+            company_cols["account_number"] = "code"
+        # industry → tags (check if it exists)
+        if _column_exists(conn, "companies_old", "industry"):
+            company_cols["industry"] = "tags"
+
+        select_cols = []
+        insert_cols = []
+        for old_col, new_col in company_cols.items():
+            select_cols.append(old_col)
+            insert_cols.append(new_col)
+
+        # Build the INSERT ... SELECT statement
+        select_list = ", ".join(f'"{c}"' for c in select_cols)
+        # Add computed columns
+        select_list += ", 'company' AS type, "
+        # displayname = name
+        if "name" in select_cols:
+            select_list += '"name" AS displayname'
+        else:
+            select_list += "'' AS displayname"
+
+        insert_list = ", ".join(f'"{c}"' for c in insert_cols) + ', "type", "displayname"'
+
+        sql = f'INSERT INTO contacts ({insert_list}) SELECT {select_list} FROM companies_old'
+        op.execute(sql)
+
+        row_count = conn.execute(sa.text("SELECT COUNT(*) FROM companies_old")).scalar()
+        logger.info("Migrated %d rows from companies_old → contacts (type='company')", row_count or 0)
+
+    # 5b. contacts_old → contacts (type='person')
+    if _table_exists(conn, "contacts_old"):
+        # Map old contact columns to new contacts columns
+        contact_cols = {
+            "id": "id",
+            "tenant_id": "tenant_id",
+            "first_name": "firstname",
+            "last_name": "surname",
+            "email": "email_1",
+            "phone": "phone_1",
+            "deleted_at": "deleted_at",
+            "created_by": "created_by",
+            "updated_by": "updated_by",
+            "created_at": "created_at",
+            "updated_at": "updated_at",
+        }
+        # mobile → phone_2
+        if _column_exists(conn, "contacts_old", "mobile"):
+            contact_cols["mobile"] = "phone_2"
+        # notes → projectnote
+        if _column_exists(conn, "contacts_old", "notes"):
+            contact_cols["notes"] = "projectnote"
+
+        select_cols = []
+        insert_cols = []
+        for old_col, new_col in contact_cols.items():
+            select_cols.append(old_col)
+            insert_cols.append(new_col)
+
+        select_list = ", ".join(f'"{c}"' for c in select_cols)
+        # Add computed columns
+        select_list += ", 'person' AS type, "
+        # displayname = first_name || ' ' || last_name
+        if _column_exists(conn, "contacts_old", "first_name") and _column_exists(conn, "contacts_old", "last_name"):
+            select_list += "COALESCE(first_name, '') || ' ' || COALESCE(last_name, '') AS displayname"
+        elif _column_exists(conn, "contacts_old", "first_name"):
+            select_list += "first_name AS displayname"
+        else:
+            select_list += "'' AS displayname"
+
+        insert_list = ", ".join(f'"{c}"' for c in insert_cols) + ', "type", "displayname"'
+
+        sql = f'INSERT INTO contacts ({insert_list}) SELECT {select_list} FROM contacts_old'
+        op.execute(sql)
+
+        row_count = conn.execute(sa.text("SELECT COUNT(*) FROM contacts_old")).scalar()
+        logger.info("Migrated %d rows from contacts_old → contacts (type='person')", row_count or 0)
+
+    # 5c. company_contacts_old → contactpersons
+    #     Each row links a company to a person. In the new schema, contactpersons
+    #     are persons attached to a company contact. We map:
+    #       contact_id (FK to contacts) = company_id (the company, now a contact)
+    #       person details come from the old contacts table
+    if _table_exists(conn, "company_contacts_old") and _table_exists(conn, "contacts_old"):
+        sql = """
+            INSERT INTO contactpersons (
+                id, tenant_id, contact_id, displayname,
+                firstname, lastname, function, phone, email,
+                tags, created_at, updated_at, deleted_at
+            )
+            SELECT
+                gen_random_uuid(),
+                cc.tenant_id,
+                cc.company_id,
+                COALESCE(c.first_name, '') || ' ' || COALESCE(c.last_name, ''),
+                c.first_name,
+                c.last_name,
+                cc.role_at_company,
+                c.phone,
+                c.email,
+                CASE WHEN cc.is_primary THEN 'primary' ELSE NULL END,
+                cc.created_at,
+                cc.updated_at,
+                cc.deleted_at
+            FROM company_contacts_old cc
+            JOIN contacts_old c ON cc.contact_id = c.id
+        """
+        op.execute(sql)
+
+        row_count = conn.execute(sa.text("SELECT COUNT(*) FROM company_contacts_old")).scalar()
+        logger.info("Migrated %d rows from company_contacts_old → contactpersons", row_count or 0)
+
+    # ── 6. Enable RLS on new tables ───────────────────────────────────
+    for table_name in ["contacts", "contactpersons"]:
+        op.execute(f'ALTER TABLE "{table_name}" ENABLE ROW LEVEL SECURITY')
+        op.execute(f'DROP POLICY IF EXISTS tenant_isolation ON "{table_name}"')
+        op.execute(
+            f'CREATE POLICY tenant_isolation ON "{table_name}" '
+            f"USING (tenant_id = current_setting('app.current_tenant_id')::uuid)"
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # Drop RLS policies on new tables
+    for table_name in ["contactpersons", "contacts"]:
+        op.execute(f'DROP POLICY IF EXISTS tenant_isolation ON "{table_name}"')
+        op.execute(f'ALTER TABLE "{table_name}" DISABLE ROW LEVEL SECURITY')
+
+    # Drop FK columns from contacts
+    op.drop_column("contacts", "admin_contactperson_id")
+    op.drop_column("contacts", "default_person_id")
+
+    # Drop new tables
     op.drop_table("contactpersons")
+    op.drop_table("contacts")
+
+    # Restore old tables by renaming _old suffix back
+    for tbl in ["companies", "contacts", "company_contacts"]:
+        old_name = f"{tbl}_old"
+        if _table_exists(conn, old_name) and not _table_exists(conn, tbl):
+            op.execute(f'ALTER TABLE "{old_name}" RENAME TO "{tbl}"')
+            logger.info("Restored %s → %s", old_name, tbl)
+        elif _table_exists(conn, old_name) and _table_exists(conn, tbl):
+            # Both exist — drop the _old version (new table takes precedence)
+            op.execute(f'DROP TABLE "{old_name}" CASCADE')
+            logger.info("Dropped leftover %s (new %s already exists)", old_name, tbl)

alembic/versions/0027_unify_company_to_contact.py

@@ -4,62 +4,183 @@ Revision ID: 0027
 Revises: 0026_mail_salt_security
 Create Date: 2026-07-23
 
+SAFE MIGRATION: When both company_id and contact_id columns exist in mails,
+company_id values are copied to contact_id (where contact_id IS NULL) before
+the column is dropped. A backup column is created to track which rows were
+originally linked to companies for safe downgrade.
+
 Changes:
 - UPDATE entity_links SET entity_type='contact' WHERE entity_type='company'
 - UPDATE tag_assignments SET entity_type='contact' WHERE entity_type='company'
 - UPDATE calendar_entry_links SET entity_type='contact' WHERE entity_type='company'
 - UPDATE addresses SET entity_type='contact' WHERE entity_type='company'
-- ALTER TABLE mails RENAME COLUMN company_id TO contact_id (if exists)
+- mails: copy company_id → contact_id WHERE contact_id IS NULL, then drop company_id
 """
+
+from __future__ import annotations
+
+import logging
+from typing import Sequence, Union
+
 from alembic import op
 import sqlalchemy as sa
 
+revision: str = "0027_unify_company_to_contact"
+down_revision: Union[str, None] = "0026_mail_salt_security"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
 
-revision = "0027_unify_company_to_contact"
+logger = logging.getLogger("alembic.migration.0027")
-down_revision = "0026_mail_salt_security"
 
 
-def upgrade():
+def _column_exists(conn, table_name: str, column_name: str) -> bool:
-    # Update entity_links: company -> contact
+    """Check whether *column_name* exists on *table_name* in public schema."""
-    op.execute(
+    result = conn.execute(
-        "UPDATE entity_links SET entity_type = 'contact' WHERE entity_type = 'company'"
+        sa.text(
-    )
+            "SELECT 1 FROM information_schema.columns "
-    # Update tag_assignments: company -> contact
+            "WHERE table_schema = 'public' "
-    op.execute(
+            "AND table_name = :t AND column_name = :c"
-        "UPDATE tag_assignments SET entity_type = 'contact' WHERE entity_type = 'company'"
+        ),
-    )
+        {"t": table_name, "c": column_name},
-    # Update calendar_entry_links: company -> contact
+    ).fetchone()
-    op.execute(
+    return result is not None
-        "UPDATE calendar_entry_links SET entity_type = 'contact' WHERE entity_type = 'company'"
+
-    )
+
-    # Update addresses: company -> contact
+def _table_exists(conn, table_name: str) -> bool:
-    op.execute(
+    """Check whether *table_name* exists in public schema."""
-        "UPDATE addresses SET entity_type = 'contact' WHERE entity_type = 'company'"
+    result = conn.execute(
-    )
+        sa.text(
-    # Rename company_id to contact_id in mails (if column exists)
+            "SELECT 1 FROM information_schema.tables "
+            "WHERE table_schema = 'public' AND table_name = :t"
+        ),
+        {"t": table_name},
+    ).fetchone()
+    return result is not None
+
+
+def upgrade() -> None:
     conn = op.get_bind()
-    if conn.dialect.has_column(conn, "mails", "company_id"):
+
+    # ── 1. Update entity_type: 'company' → 'contact' across link tables ──
+
+    if _table_exists(conn, "entity_links"):
+        result = conn.execute(
+            sa.text("UPDATE entity_links SET entity_type = 'contact' WHERE entity_type = 'company'")
+        )
+        logger.info("Updated %d rows in entity_links (company → contact)", result.rowcount)
+
+    if _table_exists(conn, "tag_assignments"):
+        result = conn.execute(
+            sa.text("UPDATE tag_assignments SET entity_type = 'contact' WHERE entity_type = 'company'")
+        )
+        logger.info("Updated %d rows in tag_assignments (company → contact)", result.rowcount)
+
+    if _table_exists(conn, "calendar_entry_links"):
+        result = conn.execute(
+            sa.text("UPDATE calendar_entry_links SET entity_type = 'contact' WHERE entity_type = 'company'")
+        )
+        logger.info("Updated %d rows in calendar_entry_links (company → contact)", result.rowcount)
+
+    if _table_exists(conn, "addresses"):
+        result = conn.execute(
+            sa.text("UPDATE addresses SET entity_type = 'contact' WHERE entity_type = 'company'")
+        )
+        logger.info("Updated %d rows in addresses (company → contact)", result.rowcount)
+
+    # ── 2. Mails: unify company_id into contact_id ──────────────────────
+    if not _table_exists(conn, "mails"):
+        logger.info("Table 'mails' does not exist — skipping column migration")
+        return
+
+    has_company_id = _column_exists(conn, "mails", "company_id")
+    has_contact_id = _column_exists(conn, "mails", "contact_id")
+
+    if has_company_id and has_contact_id:
+        # Both columns exist: copy company_id → contact_id WHERE contact_id IS NULL
+        result = conn.execute(
+            sa.text(
+                "UPDATE mails SET contact_id = company_id "
+                "WHERE contact_id IS NULL AND company_id IS NOT NULL"
+            )
+        )
+        logger.info("Copied %d rows from company_id → contact_id in mails", result.rowcount)
+
+        # Create a backup marker column to track rows originally linked via company_id
+        # This enables a targeted downgrade (only revert these rows, not all contact rows)
+        if not _column_exists(conn, "mails", "_orig_company_id"):
+            op.add_column("mails", sa.Column("_orig_company_id", sa.dialects.postgresql.UUID(as_uuid=True), nullable=True))
+            # Record which rows had company_id set (these came from companies)
+            op.execute(
+                "UPDATE mails SET _orig_company_id = company_id WHERE company_id IS NOT NULL"
+            )
+            logger.info("Created _orig_company_id backup column for downgrade tracking")
+
+        # Now safe to drop company_id
+        op.drop_column("mails", "company_id")
+        logger.info("Dropped column company_id from mails")
+
+    elif has_company_id and not has_contact_id:
+        # Only company_id exists: simple rename
         op.alter_column("mails", "company_id", new_column_name="contact_id")
+        logger.info("Renamed company_id → contact_id in mails")
+
+    else:
+        logger.info("No company_id column in mails — nothing to do")
 
 
-def downgrade():
+def downgrade() -> None:
-    # Revert entity_links: contact -> company (only for rows that were originally company)
-    op.execute(
-        "UPDATE entity_links SET entity_type = 'company' WHERE entity_type = 'contact'"
-    )
-    # Revert tag_assignments: contact -> company
-    op.execute(
-        "UPDATE tag_assignments SET entity_type = 'company' WHERE entity_type = 'contact'"
-    )
-    # Revert calendar_entry_links: contact -> company
-    op.execute(
-        "UPDATE calendar_entry_links SET entity_type = 'company' WHERE entity_type = 'contact'"
-    )
-    # Revert addresses: contact -> company
-    op.execute(
-        "UPDATE addresses SET entity_type = 'company' WHERE entity_type = 'contact'"
-    )
-    # Rename contact_id back to company_id in mails
     conn = op.get_bind()
-    if conn.dialect.has_column(conn, "mails", "contact_id"):
+
+    # ── 1. Revert mails: contact_id → company_id ────────────────────────
+    if not _table_exists(conn, "mails"):
+        return
+
+    has_contact_id = _column_exists(conn, "mails", "contact_id")
+    has_company_id = _column_exists(conn, "mails", "company_id")
+    has_orig = _column_exists(conn, "mails", "_orig_company_id")
+
+    if has_contact_id and not has_company_id:
+        if has_orig:
+            # Targeted revert: only restore rows that originally came from company_id
+            # Re-add company_id column
+            op.add_column("mails", sa.Column("company_id", sa.dialects.postgresql.UUID(as_uuid=True), nullable=True))
+            # Restore company_id from the backup marker where it was originally set
+            op.execute(
+                "UPDATE mails SET company_id = _orig_company_id WHERE _orig_company_id IS NOT NULL"
+            )
+            # Clear contact_id for rows that were originally company links
+            # (only where contact_id matches the original company_id, i.e. it was copied)
+            op.execute(
+                "UPDATE mails SET contact_id = NULL "
+                "WHERE _orig_company_id IS NOT NULL AND contact_id = _orig_company_id"
+            )
+            # Drop the backup marker
+            op.drop_column("mails", "_orig_company_id")
+            logger.info("Restored company_id from _orig_company_id backup (targeted revert)")
+        else:
+            # No backup column — simple rename (fallback for clean installs)
             op.alter_column("mails", "contact_id", new_column_name="company_id")
+            logger.info("Renamed contact_id → company_id in mails (no backup marker)")
+
+    # ── 2. Revert entity_type: 'contact' → 'company' ────────────────────
+    # NOTE: This is a lossy revert — we cannot distinguish rows that were
+    # originally 'company' from rows that were always 'contact'. This only
+    # reverts rows that are currently 'contact' back to 'company'.
+    # A proper revert requires application-level audit logs.
+
+    if _table_exists(conn, "entity_links"):
+        conn.execute(
+            sa.text("UPDATE entity_links SET entity_type = 'company' WHERE entity_type = 'contact'")
+        )
+    if _table_exists(conn, "tag_assignments"):
+        conn.execute(
+            sa.text("UPDATE tag_assignments SET entity_type = 'company' WHERE entity_type = 'contact'")
+        )
+    if _table_exists(conn, "calendar_entry_links"):
+        conn.execute(
+            sa.text("UPDATE calendar_entry_links SET entity_type = 'company' WHERE entity_type = 'contact'")
+        )
+    if _table_exists(conn, "addresses"):
+        conn.execute(
+            sa.text("UPDATE addresses SET entity_type = 'company' WHERE entity_type = 'contact'")
+        )

alembic/versions/0028_rls_force.py

@@ -0,0 +1,104 @@
+"""FORCE Row Level Security + WITH CHECK on all tenant-scoped tables.
+
+Revision ID: 0028_rls_force
+Revises: 0027_unify_company_to_contact
+Create Date: 2026-07-25
+
+This migration:
+1. Discovers all tables in the public schema that have a tenant_id column.
+2. ALTER TABLE ... FORCE ROW LEVEL SECURITY on each (ensures RLS applies to table owners too).
+3. Drops existing tenant_isolation policies and recreates them with both
+   USING and WITH CHECK clauses so writes are also filtered by tenant.
+4. Covers core tables AND plugin tables (anything with tenant_id).
+
+Idempotent: safe to run multiple times.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+revision: str = "0028_rls_force"
+down_revision: Union[str, None] = "0027_unify_company_to_contact"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+logger = logging.getLogger("alembic.migration.0028_rls_force")
+
+
+def _discover_tenant_tables(conn) -> list[str]:
+    """Return all table names in the public schema that have a tenant_id column."""
+    result = conn.execute(
+        sa.text(
+            "SELECT table_name FROM information_schema.columns "
+            "WHERE table_schema = 'public' AND column_name = 'tenant_id' "
+            "ORDER BY table_name"
+        )
+    )
+    return [row[0] for row in result.fetchall()]
+
+
+def _discover_existing_policies(conn, table_name: str) -> list[str]:
+    """Return all policy names on *table_name* that contain 'tenant' or 'isolation'."""
+    result = conn.execute(
+        sa.text(
+            "SELECT policyname FROM pg_policies "
+            "WHERE schemaname = 'public' AND tablename = :t"
+        ),
+        {"t": table_name},
+    )
+    return [row[0] for row in result.fetchall()]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    tenant_tables = _discover_tenant_tables(conn)
+    logger.info("Discovered %d tenant-scoped tables: %s", len(tenant_tables), tenant_tables)
+
+    for table_name in tenant_tables:
+        # 1. Enable RLS (idempotent — ENABLE is safe to repeat)
+        op.execute(f'ALTER TABLE "{table_name}" ENABLE ROW LEVEL SECURITY')
+
+        # 2. FORCE RLS — ensures policies apply even to table owners/superusers
+        #    who would otherwise bypass RLS
+        op.execute(f'ALTER TABLE "{table_name}" FORCE ROW LEVEL SECURITY')
+
+        # 3. Drop ALL existing policies on this table that relate to tenant isolation
+        existing_policies = _discover_existing_policies(conn, table_name)
+        for policy_name in existing_policies:
+            op.execute(f'DROP POLICY IF EXISTS "{policy_name}" ON "{table_name}"')
+            logger.info("Dropped policy %s on %s", policy_name, table_name)
+
+        # 4. Create new policy with both USING and WITH CHECK
+        #    USING:   filters rows visible in SELECT/UPDATE/DELETE
+        #    WITH CHECK: enforces tenant_id on INSERT/UPDATE
+        op.execute(
+            f'CREATE POLICY tenant_isolation ON "{table_name}" '
+            f"USING (tenant_id = current_setting('app.current_tenant_id')::uuid) "
+            f"WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::uuid)"
+        )
+        logger.info("Created policy tenant_isolation on %s (USING + WITH CHECK)", table_name)
+
+
+def downgrade() -> None:
+    """Revert FORCE RLS and restore USING-only policies (matching 0015 behavior)."""
+    conn = op.get_bind()
+    tenant_tables = _discover_tenant_tables(conn)
+
+    for table_name in tenant_tables:
+        # Drop the USING+WITH CHECK policy
+        op.execute(f'DROP POLICY IF EXISTS tenant_isolation ON "{table_name}"')
+
+        # Remove FORCE but keep ENABLE (matching pre-0028 state)
+        op.execute(f'ALTER TABLE "{table_name}" NO FORCE ROW LEVEL SECURITY')
+
+        # Recreate USING-only policy (matching original 0015 behavior)
+        op.execute(
+            f'CREATE POLICY tenant_isolation ON "{table_name}" '
+            f"USING (tenant_id = current_setting('app.current_tenant_id')::uuid)"
+        )
+        logger.info("Reverted %s to USING-only policy (removed FORCE, removed WITH CHECK)", table_name)

alembic/versions/0028_user_preferences.py

@@ -18,7 +18,7 @@ from sqlalchemy.dialects.postgresql import JSONB, UUID as PGUUID
 
 
 revision = "0028_user_preferences"
-down_revision = "0027_unify_company_to_contact"
+down_revision = "0028_rls_force"
 
 
 def upgrade():

alembic/versions/0031_permissions_soft_delete.py

@@ -0,0 +1,37 @@
+"""Add deleted_at column to permissions and share_links tables.
+
+The Permission and ShareLink models inherit TenantMixin which includes
+SoftDeleteMixin (deleted_at), but the original plugin migration did not
+create this column. This migration adds it for existing databases.
+
+Revision ID: 0031_permissions_soft_delete
+Revises: 0030_contact_merge_history
+Create Date: 2025-07-24
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers
+revision = "0031_permissions_soft_delete"
+down_revision = "0030_contact_merge_history"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add deleted_at to permissions table (if not exists)
+    op.add_column(
+        "permissions",
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    # Add deleted_at to share_links table (if not exists)
+    op.add_column(
+        "share_links",
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("share_links", "deleted_at")
+    op.drop_column("permissions", "deleted_at")

alembic/versions/0032_user_profile_fields.py

@@ -0,0 +1,25 @@
+"""Add first_name, last_name, avatar_url to users table.
+
+Revision ID: 0032
+Revises: 0031
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0032_user_profile_fields"
+down_revision = "0031_permissions_soft_delete"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("first_name", sa.String(100), nullable=True))
+    op.add_column("users", sa.Column("last_name", sa.String(100), nullable=True))
+    op.add_column("users", sa.Column("avatar_url", sa.String(500), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "avatar_url")
+    op.drop_column("users", "last_name")
+    op.drop_column("users", "first_name")

alembic/versions/0033_bank_accounts.py

@@ -0,0 +1,45 @@
+"""Add bank_accounts table.
+
+Revision ID: 0033
+Revises: 0032_user_profile_fields
+Create Date: 2026-07-25
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision: str = "0033_bank_accounts"
+down_revision: Union[str, None] = "0032_user_profile_fields"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "bank_accounts",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), nullable=False, index=True),
+        sa.Column("bank_name", sa.String(100), nullable=False),
+        sa.Column("iban", sa.String(34), nullable=False),
+        sa.Column("bic", sa.String(11), nullable=True),
+        sa.Column("account_holder", sa.String(200), nullable=True),
+        sa.Column("default_tax", sa.String(50), nullable=True),
+        sa.Column("is_default", sa.Boolean, nullable=False, server_default=sa.text("false")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+    op.create_index("ix_bank_accounts_tenant", "bank_accounts", ["tenant_id"])
+    op.create_index("ix_bank_accounts_tenant_default", "bank_accounts", ["tenant_id", "is_default"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_bank_accounts_tenant_default", table_name="bank_accounts")
+    op.drop_index("ix_bank_accounts_tenant", table_name="bank_accounts")
+    op.drop_table("bank_accounts")

alembic/versions/0034_automation_config.py

@@ -0,0 +1,27 @@
+"""Add automation_config JSONB column to system_settings.
+
+Revision ID: 0034
+Revises: 0033_bank_accounts
+Create Date: 2026-07-25
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "0034_automation_config"
+down_revision: Union[str, None] = "0033_bank_accounts"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("system_settings", sa.Column("automation_config", JSONB, nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("system_settings", "automation_config")

alembic/versions/0035_comm_search_index.py

@@ -0,0 +1,51 @@
+"""Add search_tsv and embedding columns to comm_messages for full-text search indexing.
+
+Revision ID: 0035
+Revises: 0034_automation_config
+Create Date: 2026-07-25
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import TSVECTOR
+
+revision: str = "0035_comm_search_index"
+down_revision: Union[str, None] = "0034_automation_config"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Add search_tsv column for full-text search
+    op.add_column(
+        "comm_messages",
+        sa.Column("search_tsv", TSVECTOR, nullable=True),
+    )
+    # Add embedding column for vector search (768 dimensions matching pgvector)
+    op.execute(
+        "ALTER TABLE comm_messages ADD COLUMN embedding vector(768)"
+    )
+    # Create GIN index on search_tsv for fast FTS queries
+    op.create_index(
+        "ix_comm_messages_search_tsv",
+        "comm_messages",
+        ["search_tsv"],
+        postgresql_using="gin",
+    )
+    # Create IVFFlat index on embedding for fast vector search
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_comm_messages_embedding "
+        "ON comm_messages USING ivfflat (embedding vector_cosine_ops) "
+        "WITH (lists = 100)"
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_comm_messages_embedding", table_name="comm_messages")
+    op.drop_index("ix_comm_messages_search_tsv", table_name="comm_messages")
+    op.drop_column("comm_messages", "embedding")
+    op.drop_column("comm_messages", "search_tsv")

alembic/versions/0036_cross_tenant_fk.py

@@ -0,0 +1,182 @@
+"""Cross-tenant referential integrity: composite FKs on (tenant_id, contact_id).
+
+Revision ID: 0036_cross_tenant_fk
+Revises: 0035_comm_search_index
+Create Date: 2026-07-25
+
+Changes:
+1. Add UNIQUE (tenant_id, id) on contacts — prerequisite for composite FK.
+2. Replace contactpersons.contact_id FK with composite (tenant_id, contact_id)
+   → contacts(tenant_id, id).
+3. Replace contact_merge_history.source_contact_id FK with composite
+   (tenant_id, source_contact_id) → contacts(tenant_id, id).
+4. Replace contact_merge_history.target_contact_id FK with composite
+   (tenant_id, target_contact_id) → contacts(tenant_id, id).
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0036_cross_tenant_fk"
+down_revision: Union[str, None] = "0035_comm_search_index"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def _constraint_exists(name: str) -> str:
+    """Return SQL that checks if a constraint exists."""
+    return (
+        f"SELECT 1 FROM information_schema.table_constraints "
+        f"WHERE constraint_name = '{name}'"
+    )
+
+
+def _fk_exists(name: str) -> str:
+    """Return SQL that checks if a foreign key constraint exists."""
+    return (
+        f"SELECT 1 FROM information_schema.table_constraints "
+        f"WHERE constraint_name = '{name}' AND constraint_type = 'FOREIGN KEY'"
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. Add UNIQUE (tenant_id, id) on contacts ──────────────────────────
+    unique_name = "uq_contacts_tenant_id"
+    result = conn.execute(sa.text(_constraint_exists(unique_name))).fetchone()
+    if result is None:
+        op.execute(
+            f"ALTER TABLE contacts ADD CONSTRAINT {unique_name} "
+            f"UNIQUE (tenant_id, id)"
+        )
+
+    # ── 2. contactpersons: replace single-column FK with composite FK ──────
+    # Find and drop the existing FK on contactpersons.contact_id
+    old_cp_fk_result = conn.execute(
+        sa.text(
+            "SELECT conname FROM pg_constraint c "
+            "JOIN pg_class cls ON c.conrelid = cls.oid "
+            "JOIN pg_namespace nsp ON c.connamespace = nsp.oid "
+            "WHERE cls.relname = 'contactpersons' "
+            "AND nsp.nspname = 'public' "
+            "AND c.contype = 'f' "
+            "AND EXISTS ("
+            "  SELECT 1 FROM pg_attribute a "
+    "  WHERE a.attrelid = c.conrelid AND a.attname = 'contact_id' "
+    "  AND a.attnum = ANY(c.conkey)"
+            ")"
+        )
+    ).fetchone()
+
+    if old_cp_fk_result is not None:
+        old_cp_fk_name = old_cp_fk_result[0]
+        op.execute(f"ALTER TABLE contactpersons DROP CONSTRAINT IF EXISTS {old_cp_fk_name}")
+
+    # Add composite FK on contactpersons (tenant_id, contact_id) → contacts(tenant_id, id)
+    cp_composite_fk = "fk_contactpersons_tenant_contact"
+    result = conn.execute(sa.text(_fk_exists(cp_composite_fk))).fetchone()
+    if result is None:
+        op.execute(
+            f"ALTER TABLE contactpersons ADD CONSTRAINT {cp_composite_fk} "
+            f"FOREIGN KEY (tenant_id, contact_id) "
+            f"REFERENCES contacts (tenant_id, id) ON DELETE CASCADE"
+        )
+
+    # ── 3. contact_merge_history: replace source_contact_id FK ─────────────
+    old_src_fk_result = conn.execute(
+        sa.text(
+            "SELECT conname FROM pg_constraint c "
+            "JOIN pg_class cls ON c.conrelid = cls.oid "
+            "JOIN pg_namespace nsp ON c.connamespace = nsp.oid "
+            "WHERE cls.relname = 'contact_merge_history' "
+            "AND nsp.nspname = 'public' "
+            "AND c.contype = 'f' "
+            "AND EXISTS ("
+            "  SELECT 1 FROM pg_attribute a "
+    "  WHERE a.attrelid = c.conrelid AND a.attname = 'source_contact_id' "
+    "  AND a.attnum = ANY(c.conkey)"
+            ")"
+        )
+    ).fetchone()
+
+    if old_src_fk_result is not None:
+        old_src_fk_name = old_src_fk_result[0]
+        op.execute(f"ALTER TABLE contact_merge_history DROP CONSTRAINT IF EXISTS {old_src_fk_name}")
+
+    src_composite_fk = "fk_merge_history_tenant_source"
+    result = conn.execute(sa.text(_fk_exists(src_composite_fk))).fetchone()
+    if result is None:
+        op.execute(
+            f"ALTER TABLE contact_merge_history ADD CONSTRAINT {src_composite_fk} "
+            f"FOREIGN KEY (tenant_id, source_contact_id) "
+            f"REFERENCES contacts (tenant_id, id) ON DELETE SET NULL"
+        )
+
+    # ── 4. contact_merge_history: replace target_contact_id FK ──────────────
+    old_tgt_fk_result = conn.execute(
+        sa.text(
+            "SELECT conname FROM pg_constraint c "
+            "JOIN pg_class cls ON c.conrelid = cls.oid "
+            "JOIN pg_namespace nsp ON c.connamespace = nsp.oid "
+            "WHERE cls.relname = 'contact_merge_history' "
+            "AND nsp.nspname = 'public' "
+            "AND c.contype = 'f' "
+            "AND EXISTS ("
+            "  SELECT 1 FROM pg_attribute a "
+    "  WHERE a.attrelid = c.conrelid AND a.attname = 'target_contact_id' "
+    "  AND a.attnum = ANY(c.conkey)"
+            ")"
+        )
+    ).fetchone()
+
+    if old_tgt_fk_result is not None:
+        old_tgt_fk_name = old_tgt_fk_result[0]
+        op.execute(f"ALTER TABLE contact_merge_history DROP CONSTRAINT IF EXISTS {old_tgt_fk_name}")
+
+    tgt_composite_fk = "fk_merge_history_tenant_target"
+    result = conn.execute(sa.text(_fk_exists(tgt_composite_fk))).fetchone()
+    if result is None:
+        op.execute(
+            f"ALTER TABLE contact_merge_history ADD CONSTRAINT {tgt_composite_fk} "
+            f"FOREIGN KEY (tenant_id, target_contact_id) "
+            f"REFERENCES contacts (tenant_id, id) ON DELETE CASCADE"
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # Restore single-column FKs and remove composite FKs
+
+    # ── contact_merge_history: target ──
+    op.execute("ALTER TABLE contact_merge_history DROP CONSTRAINT IF EXISTS fk_merge_history_tenant_target")
+    op.execute(
+        "ALTER TABLE contact_merge_history ADD CONSTRAINT "
+        "contact_merge_history_target_contact_id_fkey "
+        "FOREIGN KEY (target_contact_id) REFERENCES contacts (id) ON DELETE CASCADE"
+    )
+
+    # ── contact_merge_history: source ──
+    op.execute("ALTER TABLE contact_merge_history DROP CONSTRAINT IF EXISTS fk_merge_history_tenant_source")
+    op.execute(
+        "ALTER TABLE contact_merge_history ADD CONSTRAINT "
+        "contact_merge_history_source_contact_id_fkey "
+        "FOREIGN KEY (source_contact_id) REFERENCES contacts (id) ON DELETE SET NULL"
+    )
+
+    # ── contactpersons ──
+    op.execute("ALTER TABLE contactpersons DROP CONSTRAINT IF EXISTS fk_contactpersons_tenant_contact")
+    op.execute(
+        "ALTER TABLE contactpersons ADD CONSTRAINT "
+        "contactpersons_contact_id_fkey "
+        "FOREIGN KEY (contact_id) REFERENCES contacts (id) ON DELETE CASCADE"
+    )
+
+    # ── Remove unique (tenant_id, id) on contacts ──
+    op.execute("ALTER TABLE contacts DROP CONSTRAINT IF EXISTS uq_contacts_tenant_id")

alembic/versions/0037_user_tenant_model.py

@@ -0,0 +1,197 @@
+"""User-Tenant model cleanup: single source of truth for membership and role.
+
+Revision ID: 0037_user_tenant_model
+Revises: 0036_cross_tenant_fk
+Create Date: 2026-07-25
+
+Changes:
+1. Make users.email globally unique (drop composite uq_users_tenant_email, add UNIQUE on email).
+2. Drop tenant_id, role, role_id columns from users table (with data migration to user_tenants).
+3. Add role column to user_tenants (built-in role string: admin/editor/viewer).
+4. Add status column to user_tenants (active/invited/disabled).
+5. Migrate existing data: copy users.tenant_id + users.role_id → user_tenants (if not already present).
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0037_user_tenant_model"
+down_revision: Union[str, None] = "0036_cross_tenant_fk"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def _constraint_exists(name: str, table: str) -> str:
+    """Return SQL that checks if a constraint exists on a table."""
+    return (
+        f"SELECT 1 FROM information_schema.table_constraints "
+        f"WHERE constraint_name = '{name}' AND table_name = '{table}'"
+    )
+
+
+def _column_exists(table: str, column: str) -> str:
+    """Return SQL that checks if a column exists on a table."""
+    return (
+        f"SELECT 1 FROM information_schema.columns "
+        f"WHERE table_name = '{table}' AND column_name = '{column}'"
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. Add UNIQUE constraint on users.email (globally unique) ───────────
+    # First check if a unique constraint on email already exists
+    email_unique_result = conn.execute(
+        sa.text(
+            "SELECT 1 FROM information_schema.table_constraints "
+            "WHERE constraint_name = 'uq_users_email' AND table_name = 'users'"
+        )
+    ).fetchone()
+    if email_unique_result is None:
+        # Check if there's a unique index on email already
+        email_index_result = conn.execute(
+            sa.text(
+                "SELECT 1 FROM pg_index i "
+                "JOIN pg_class c ON i.indexrelid = c.oid "
+                "WHERE c.relname = 'ix_users_email' AND i.indisunique = true"
+            )
+        ).fetchone()
+        if email_index_result is None:
+            op.execute("ALTER TABLE users ADD CONSTRAINT uq_users_email UNIQUE (email)")
+
+    # ── 2. Drop composite unique constraint uq_users_tenant_email ───────────
+    result = conn.execute(sa.text(_constraint_exists("uq_users_tenant_email", "users"))).fetchone()
+    if result is not None:
+        op.execute("ALTER TABLE users DROP CONSTRAINT IF EXISTS uq_users_tenant_email")
+
+    # ── 3. Add role column to user_tenants ─────────────────────────────────
+    role_col_result = conn.execute(sa.text(_column_exists("user_tenants", "role"))).fetchone()
+    if role_col_result is None:
+        op.add_column("user_tenants", sa.Column("role", sa.String(50), nullable=False, server_default="viewer"))
+
+    # ── 4. Add status column to user_tenants ───────────────────────────────
+    status_col_result = conn.execute(sa.text(_column_exists("user_tenants", "status"))).fetchone()
+    if status_col_result is None:
+        op.add_column("user_tenants", sa.Column("status", sa.String(20), nullable=False, server_default="active"))
+
+    # ── 4b. Add updated_at column to user_tenants ──────────────────────────
+    updated_col_result = conn.execute(sa.text(_column_exists("user_tenants", "updated_at"))).fetchone()
+    if updated_col_result is None:
+        op.add_column("user_tenants", sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True, server_default=sa.func.now()))
+
+    # ── 5. Data migration: copy tenant_id, role, role_id from users to user_tenants ─
+    # Only create UserTenant rows that don't already exist
+    conn.execute(sa.text("""
+        INSERT INTO user_tenants (user_id, tenant_id, is_default, role, role_id, status, created_at)
+        SELECT 
+            u.id, 
+            u.tenant_id, 
+            TRUE, 
+            COALESCE(u.role, 'viewer'), 
+            u.role_id,
+            'active',
+            NOW()
+        FROM users u
+        WHERE NOT EXISTS (
+            SELECT 1 FROM user_tenants ut 
+            WHERE ut.user_id = u.id AND ut.tenant_id = u.tenant_id
+        )
+        AND u.tenant_id IS NOT NULL
+    """))
+
+    # Update existing UserTenant rows with role from users table (if they don't have one set yet)
+    conn.execute(sa.text("""
+        UPDATE user_tenants ut
+        SET role = COALESCE(u.role, 'viewer'),
+            role_id = COALESCE(ut.role_id, u.role_id)
+        FROM users u
+        WHERE ut.user_id = u.id
+        AND ut.tenant_id = u.tenant_id
+    """))
+
+    # ── 6. Drop role_id FK from users (if it exists) ───────────────────────
+    # Find and drop the FK on users.role_id
+    role_id_fk_result = conn.execute(
+        sa.text(
+            "SELECT conname FROM pg_constraint c "
+            "JOIN pg_class cls ON c.conrelid = cls.oid "
+            "JOIN pg_namespace nsp ON c.connamespace = nsp.oid "
+            "WHERE cls.relname = 'users' "
+            "AND nsp.nspname = 'public' "
+            "AND c.contype = 'f' "
+            "AND EXISTS ("
+            "  SELECT 1 FROM pg_attribute a "
+            "  WHERE a.attrelid = c.conrelid AND a.attname = 'role_id' "
+            "  AND a.attnum = ANY(c.conkey)"
+            ")"
+        )
+    ).fetchone()
+    if role_id_fk_result is not None:
+        fk_name = role_id_fk_result[0]
+        op.execute(f"ALTER TABLE users DROP CONSTRAINT IF EXISTS {fk_name}")
+
+    # ── 7. Drop tenant_id, role, role_id columns from users ────────────────
+    # Drop tenant_id
+    tenant_col_result = conn.execute(sa.text(_column_exists("users", "tenant_id"))).fetchone()
+    if tenant_col_result is not None:
+        # Drop RLS policy that depends on tenant_id
+        op.execute("DROP POLICY IF EXISTS tenant_isolation ON users")
+        # Drop any indexes on tenant_id first
+        op.execute("DROP INDEX IF EXISTS ix_users_tenant_id")
+        op.drop_column("users", "tenant_id")
+
+    # Drop role
+    role_col_result = conn.execute(sa.text(_column_exists("users", "role"))).fetchone()
+    if role_col_result is not None:
+        op.drop_column("users", "role")
+
+    # Drop role_id
+    role_id_col_result = conn.execute(sa.text(_column_exists("users", "role_id"))).fetchone()
+    if role_id_col_result is not None:
+        op.execute("DROP INDEX IF EXISTS ix_users_role_id")
+        op.drop_column("users", "role_id")
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # ── Re-add tenant_id, role, role_id to users ───────────────────────────
+    tenant_col_result = conn.execute(sa.text(_column_exists("users", "tenant_id"))).fetchone()
+    if tenant_col_result is None:
+        op.add_column("users", sa.Column("tenant_id", sa.dialects.postgresql.UUID(as_uuid=True), nullable=True))
+        op.create_index("ix_users_tenant_id", "users", ["tenant_id"])
+
+    role_col_result = conn.execute(sa.text(_column_exists("users", "role"))).fetchone()
+    if role_col_result is None:
+        op.add_column("users", sa.Column("role", sa.String(50), nullable=False, server_default="viewer"))
+
+    role_id_col_result = conn.execute(sa.text(_column_exists("users", "role_id"))).fetchone()
+    if role_id_col_result is None:
+        op.add_column("users", sa.Column("role_id", sa.dialects.postgresql.UUID(as_uuid=True), nullable=True))
+        op.create_index("ix_users_role_id", "users", ["role_id"])
+        # Re-add FK
+        op.create_foreign_key("fk_users_role_id", "users", "roles", ["role_id"], ["id"], ondelete="SET NULL")
+
+    # ── Restore data from user_tenants to users (default tenant) ────────────
+    conn.execute(sa.text("""
+        UPDATE users u
+        SET tenant_id = ut.tenant_id,
+            role = ut.role,
+            role_id = ut.role_id
+        FROM user_tenants ut
+        WHERE ut.user_id = u.id AND ut.is_default = TRUE
+    """))
+
+    # ── Re-add composite unique constraint ─────────────────────────────────
+    op.execute("ALTER TABLE users DROP CONSTRAINT IF EXISTS uq_users_email")
+    op.execute("ALTER TABLE users ADD CONSTRAINT uq_users_tenant_email UNIQUE (tenant_id, email)")
+
+    # ── Drop role and status columns from user_tenants ──────────────────────
+    op.drop_column("user_tenants", "status")
+    op.drop_column("user_tenants", "role")

alembic/versions/0038_dms_content_hash.py

@@ -0,0 +1,44 @@
+"""Add content_hash column to files table for SHA-256 dedup and integrity.
+
+Revision ID: 0038_dms_content_hash
+Revises: 0037_user_tenant_model
+Create Date: 2026-07-25
+
+Changes:
+1. Add content_hash (String(64), nullable) column to files table.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0038_dms_content_hash"
+down_revision: Union[str, None] = "0037_user_tenant_model"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def _column_exists(table: str, column: str) -> str:
+    """Return SQL that checks if a column exists on a table."""
+    return (
+        f"SELECT 1 FROM information_schema.columns "
+        f"WHERE table_name = '{table}' AND column_name = '{column}'"
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    result = conn.execute(sa.text(_column_exists("files", "content_hash"))).fetchone()
+    if result is None:
+        op.add_column("files", sa.Column("content_hash", sa.String(64), nullable=True))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    result = conn.execute(sa.text(_column_exists("files", "content_hash"))).fetchone()
+    if result is not None:
+        op.drop_column("files", "content_hash")

alembic/versions/0039_contact_normalize.py

@@ -0,0 +1,178 @@
+"""Normalize contact model: fix surfix typo, Float→Numeric(5,2) discounts, JSON→JSONB, unique constraints.
+
+Revision ID: 0039_contact_normalize
+Revises: 0038_dms_content_hash
+Create Date: 2026-07-25
+
+Changes:
+1. Rename column surfix → suffix on contacts table.
+2. Convert discount_* columns from Float to Numeric(5,2) with CHECK constraints (0-100).
+3. Convert custom columns from JSON to JSONB on contacts and contactpersons.
+4. Add partial unique constraints: (tenant_id, code) and (tenant_id, accounting_code) where NOT NULL.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0039_contact_normalize"
+down_revision: Union[str, None] = "0038_dms_content_hash"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+DISCOUNT_COLUMNS = [
+    "discount_crew",
+    "discount_transport",
+    "discount_rental",
+    "discount_sale",
+    "discount_subrent",
+    "discount_total",
+]
+
+
+def _column_exists(table: str, column: str) -> str:
+    """Return SQL that checks if a column exists on a table."""
+    return (
+        f"SELECT 1 FROM information_schema.columns "
+        f"WHERE table_name = '{table}' AND column_name = '{column}'"
+    )
+
+
+def _constraint_exists(table: str, constraint: str) -> str:
+    """Return SQL that checks if a constraint exists on a table."""
+    return (
+        f"SELECT 1 FROM information_schema.table_constraints "
+        f"WHERE table_name = '{table}' AND constraint_name = '{constraint}'"
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 0. Add status column to contacts (for state machine) ──
+    status_col = conn.execute(sa.text(_column_exists("contacts", "status"))).fetchone()
+    if not status_col:
+        op.add_column("contacts", sa.Column("status", sa.String(20), nullable=False, server_default="lead"))
+
+    # ── 1a. Rename surfix → suffix ──
+    result = conn.execute(sa.text(_column_exists("contacts", "surfix"))).fetchone()
+    if result:
+        op.alter_column("contacts", "surfix", new_column_name="suffix")
+
+    # ── 1b. Convert discount_* from Float to Numeric(5,2) with CHECK ──
+    for col in DISCOUNT_COLUMNS:
+        conn.execute(
+            sa.text(
+                f"ALTER TABLE contacts ALTER COLUMN {col} "
+                f"TYPE NUMERIC(5,2) USING {col}::numeric(5,2)"
+            )
+        )
+        # Add CHECK constraint if not exists
+        ck_name = f"ck_contacts_{col}_range"
+        ck_exists = conn.execute(
+            sa.text(_constraint_exists("contacts", ck_name))
+        ).fetchone()
+        if not ck_exists:
+            conn.execute(
+                sa.text(
+                    f"ALTER TABLE contacts ADD CONSTRAINT {ck_name} "
+                    f"CHECK ({col} BETWEEN 0 AND 100)"
+                )
+            )
+
+    # ── 1c. JSON → JSONB for contacts.custom ──
+    result = conn.execute(
+        sa.text(
+            "SELECT data_type FROM information_schema.columns "
+            "WHERE table_name = 'contacts' AND column_name = 'custom'"
+        )
+    ).fetchone()
+    if result and result[0] == "json":
+        conn.execute(
+            sa.text(
+                "ALTER TABLE contacts ALTER COLUMN custom "
+                "TYPE JSONB USING custom::jsonb"
+            )
+        )
+
+    # ── 1d. JSON → JSONB for contactpersons.custom ──
+    result = conn.execute(
+        sa.text(
+            "SELECT data_type FROM information_schema.columns "
+            "WHERE table_name = 'contactpersons' AND column_name = 'custom'"
+        )
+    ).fetchone()
+    if result and result[0] == "json":
+        conn.execute(
+            sa.text(
+                "ALTER TABLE contactpersons ALTER COLUMN custom "
+                "TYPE JSONB USING custom::jsonb"
+            )
+        )
+
+    # ── 1e. Partial unique constraints ──
+    # (tenant_id, code) where code IS NOT NULL
+    uq_code_exists = conn.execute(
+        sa.text(_constraint_exists("contacts", "uq_contacts_tenant_code"))
+    ).fetchone()
+    if not uq_code_exists:
+        conn.execute(
+            sa.text(
+                "CREATE UNIQUE INDEX uq_contacts_tenant_code "
+                "ON contacts (tenant_id, code) WHERE code IS NOT NULL"
+            )
+        )
+
+    # (tenant_id, accounting_code) where accounting_code IS NOT NULL
+    uq_acct_exists = conn.execute(
+        sa.text(_constraint_exists("contacts", "uq_contacts_tenant_accounting_code"))
+    ).fetchone()
+    if not uq_acct_exists:
+        conn.execute(
+            sa.text(
+                "CREATE UNIQUE INDEX uq_contacts_tenant_accounting_code "
+                "ON contacts (tenant_id, accounting_code) WHERE accounting_code IS NOT NULL"
+            )
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # Drop unique indexes
+    conn.execute(sa.text("DROP INDEX IF EXISTS uq_contacts_tenant_accounting_code"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS uq_contacts_tenant_code"))
+
+    # JSONB → JSON
+    conn.execute(
+        sa.text(
+            "ALTER TABLE contactpersons ALTER COLUMN custom "
+            "TYPE JSON USING custom::json"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "ALTER TABLE contacts ALTER COLUMN custom TYPE JSON USING custom::json"
+        )
+    )
+
+    # Drop CHECK constraints and revert Numeric → Float
+    for col in DISCOUNT_COLUMNS:
+        ck_name = f"ck_contacts_{col}_range"
+        conn.execute(sa.text(f"ALTER TABLE contacts DROP CONSTRAINT IF EXISTS {ck_name}"))
+        conn.execute(
+            sa.text(
+                f"ALTER TABLE contacts ALTER COLUMN {col} "
+                f"TYPE FLOAT USING {col}::float"
+            )
+        )
+
+    # Rename suffix → surfix
+    result = conn.execute(sa.text(_column_exists("contacts", "suffix"))).fetchone()
+    if result:
+        op.alter_column("contacts", "suffix", new_column_name="surfix")

alembic/versions/0040_outbox.py

@@ -0,0 +1,71 @@
+"""Create event_outbox table for transactional outbox pattern.
+
+Revision ID: 0040_outbox
+Revises: 0039_contact_normalize
+Create Date: 2026-07-25
+
+Stores domain events in a durable table so they survive process crashes,
+restarts, and multi-replica deployments.  A background worker polls the
+outbox and publishes events to the in-process event bus.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0040_outbox"
+down_revision: Union[str, None] = "0039_contact_normalize"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Ensure pgcrypto extension for gen_random_uuid()
+    conn.execute(sa.text("CREATE EXTENSION IF NOT EXISTS pgcrypto"))
+
+    conn.execute(
+        sa.text(
+            """
+            CREATE TABLE IF NOT EXISTS event_outbox (
+                id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                tenant_id       UUID NOT NULL,
+                event_name      VARCHAR(255) NOT NULL,
+                payload         JSONB NOT NULL,
+                status          VARCHAR(20) NOT NULL DEFAULT 'pending',
+                attempts        INT NOT NULL DEFAULT 0,
+                max_attempts    INT NOT NULL DEFAULT 5,
+                next_retry_at   TIMESTAMPTZ,
+                created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                published_at    TIMESTAMPTZ
+            )
+            """
+        )
+    )
+
+    # Index for the worker query: WHERE status = 'pending' ORDER BY next_retry_at
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_outbox_status "
+            "ON event_outbox (status, next_retry_at)"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_outbox_tenant "
+            "ON event_outbox (tenant_id)"
+        )
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_outbox_tenant"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_outbox_status"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS event_outbox"))

alembic/versions/0041_custom_field_definitions.py

@@ -0,0 +1,86 @@
+"""Create custom_field_definitions table for user-defined custom fields.
+
+Revision ID: 0041_custom_field_definitions
+Revises: 0040_outbox
+Create Date: 2026-07-26
+
+Stores user-defined custom field definitions that are merged with
+plugin-provided custom fields at query time.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0041_custom_field_definitions"
+down_revision: Union[str, None] = "0040_outbox"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    conn.execute(
+        sa.text(
+            """
+            CREATE TABLE IF NOT EXISTS custom_field_definitions (
+                id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                tenant_id       UUID NOT NULL,
+                entity          VARCHAR(50) NOT NULL,
+                name            VARCHAR(100) NOT NULL,
+                label           VARCHAR(200) NOT NULL,
+                field_type      VARCHAR(20) NOT NULL DEFAULT 'text',
+                options         JSONB,
+                default_value   JSONB,
+                required        BOOLEAN NOT NULL DEFAULT FALSE,
+                is_active       BOOLEAN NOT NULL DEFAULT TRUE,
+                sort_order      INTEGER NOT NULL DEFAULT 0,
+                created_by      UUID,
+                updated_by      UUID,
+                created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                deleted_at      TIMESTAMPTZ
+            )
+            """
+        )
+    )
+
+    # Indexes
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_custom_field_def_tenant "
+            "ON custom_field_definitions (tenant_id)"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_custom_field_def_entity "
+            "ON custom_field_definitions (entity)"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_custom_field_def_tenant_active "
+            "ON custom_field_definitions (tenant_id, is_active)"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "CREATE UNIQUE INDEX IF NOT EXISTS uq_custom_field_def_tenant_entity_name "
+            "ON custom_field_definitions (tenant_id, entity, name)"
+        )
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP INDEX IF EXISTS uq_custom_field_def_tenant_entity_name"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_custom_field_def_tenant_active"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_custom_field_def_entity"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_custom_field_def_tenant"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS custom_field_definitions"))

alembic/versions/0042_webhooks.py

@@ -0,0 +1,69 @@
+"""Create webhooks table for outgoing webhook subscriptions.
+
+Revision ID: 0042_webhooks
+Revises: 0041_custom_field_definitions
+Create Date: 2026-07-26
+
+Stores outgoing webhook subscriptions with target URL, event subscriptions,
+and delivery settings (retry count, timeout, HMAC secret).
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0042_webhooks"
+down_revision: Union[str, None] = "0041_custom_field_definitions"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    conn.execute(
+        sa.text(
+            """
+            CREATE TABLE IF NOT EXISTS webhooks (
+                id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                tenant_id       UUID NOT NULL,
+                url             VARCHAR(500) NOT NULL,
+                events          JSONB NOT NULL DEFAULT '[]',
+                secret          VARCHAR(255),
+                is_active       BOOLEAN NOT NULL DEFAULT TRUE,
+                retry_count     INTEGER NOT NULL DEFAULT 3,
+                timeout_seconds INTEGER NOT NULL DEFAULT 30,
+                created_by      UUID,
+                updated_by      UUID,
+                created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                deleted_at      TIMESTAMPTZ
+            )
+            """
+        )
+    )
+
+    # Indexes
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_webhooks_tenant "
+            "ON webhooks (tenant_id)"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_webhooks_tenant_active "
+            "ON webhooks (tenant_id, is_active)"
+        )
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_webhooks_tenant_active"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_webhooks_tenant"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS webhooks"))

alembic/versions/0043_backups.py

@@ -0,0 +1,66 @@
+"""Create backups table for database backup tracking.
+
+Revision ID: 0042_backups
+Revises: 0041_custom_field_definitions
+Create Date: 2026-07-26
+
+Stores database backup records per tenant with status tracking.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0043_backups"
+down_revision: Union[str, None] = "0042_webhooks"
+branch_labels: Union[str, None] = None
+depends_on: Union[str, None] = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    conn.execute(
+        sa.text(
+            """
+            CREATE TABLE IF NOT EXISTS backups (
+                id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                tenant_id       UUID NOT NULL,
+                filename        VARCHAR(255) NOT NULL,
+                size_bytes      BIGINT,
+                status          VARCHAR(20) NOT NULL DEFAULT 'pending',
+                error_message   TEXT,
+                created_by      UUID,
+                created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+                completed_at    TIMESTAMPTZ,
+                updated_at      TIMESTAMPTZ,
+                deleted_at      TIMESTAMPTZ
+            )
+            """
+        )
+    )
+
+    # Indexes
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_backups_tenant "
+            "ON backups (tenant_id)"
+        )
+    )
+    conn.execute(
+        sa.text(
+            "CREATE INDEX IF NOT EXISTS ix_backups_tenant_status "
+            "ON backups (tenant_id, status)"
+        )
+    )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_backups_tenant_status"))
+    conn.execute(sa.text("DROP INDEX IF EXISTS ix_backups_tenant"))
+    conn.execute(sa.text("DROP TABLE IF EXISTS backups"))

alembic/versions/0044_rls_repair_and_db_roles.py

@@ -0,0 +1,125 @@
+"""RLS repair + separate DB runtime user.
+
+Revision ID: 0044
+Revises: 0043
+Created: 2026-07-26
+
+This migration:
+1. Re-discovers ALL tenant-scoped tables and ensures RLS is enabled
+   with FORCE + WITH CHECK (covers tables added after migration 0028).
+2. Creates a separate ``crm_runtime`` role with NOSUPERUSER and
+   NOBYPASSRLS so the application cannot bypass RLS.
+3. Grants only DML permissions (SELECT/INSERT/UPDATE/DELETE) to
+   ``crm_runtime`` on all tenant-scoped tables.
+
+IMPORTANT: After this migration, the application's DATABASE_URL must
+use ``crm_runtime`` (not the superuser) for API and worker containers.
+Migration/DDL operations continue to use the owner user (crm_user).
+"""
+
+from alembic import op
+import sqlalchemy as sa
+import logging
+
+logger = logging.getLogger(__name__)
+
+revision = "0044"
+down_revision = "0043_backups"
+branch_labels = None
+depends_on = None
+
+
+def _discover_tenant_tables(conn) -> list[str]:
+    """Return all table names in the public schema that have a tenant_id column."""
+    result = conn.execute(
+        sa.text(
+            "SELECT table_name FROM information_schema.columns "
+            "WHERE table_schema = 'public' AND column_name = 'tenant_id' "
+            "ORDER BY table_name"
+        )
+    )
+    return [row[0] for row in result]
+
+
+def _discover_existing_policies(conn, table_name: str) -> list[str]:
+    """Return all policy names on *table_name* that contain 'tenant' or 'isolation'."""
+    result = conn.execute(
+        sa.text(
+            "SELECT policyname FROM pg_policies "
+            "WHERE schemaname = 'public' AND tablename = :t "
+            "AND (policyname LIKE '%tenant%' OR policyname LIKE '%isolation%')"
+        ),
+        {"t": table_name},
+    )
+    return [row[0] for row in result]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. RLS Repair: ensure all tenant tables have RLS + WITH CHECK ──
+    tenant_tables = _discover_tenant_tables(conn)
+    logger.info("RLS repair: discovered %d tenant-scoped tables: %s", len(tenant_tables), tenant_tables)
+
+    for table_name in tenant_tables:
+        # Enable RLS
+        op.execute(f'ALTER TABLE "{table_name}" ENABLE ROW LEVEL SECURITY')
+        # Force RLS (applies to table owner too)
+        op.execute(f'ALTER TABLE "{table_name}" FORCE ROW LEVEL SECURITY')
+
+        # Drop existing tenant policies
+        existing_policies = _discover_existing_policies(conn, table_name)
+        for policy_name in existing_policies:
+            op.execute(f'DROP POLICY IF EXISTS "{policy_name}" ON "{table_name}"')
+            logger.info("Dropped policy %s on %s", policy_name, table_name)
+
+        # Create unified tenant isolation policy with WITH CHECK
+        op.execute(
+            f'CREATE POLICY tenant_isolation ON "{table_name}" '
+            f"USING (tenant_id = current_setting('app.tenant_id', true)::uuid) "
+            f"WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid)"
+        )
+        logger.info("Created/updated tenant_isolation policy on %s (USING + WITH CHECK)", table_name)
+
+    # ── 2. Create crm_runtime role (NOSUPERUSER, NOBYPASSRLS) ──
+    # Use DO block for idempotent creation
+    op.execute(
+        sa.text(
+            "DO $$ "
+            "BEGIN "
+            "  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'crm_runtime') THEN "
+            "    CREATE ROLE crm_runtime LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE "
+            "    NOREPLICATION NOBYPASSRLS; "
+            "  END IF; "
+            "END $$;"
+        )
+    )
+    logger.info("Ensured crm_runtime role exists (NOSUPERUSER, NOBYPASSRLS)")
+
+    # ── 3. Grant DML permissions to crm_runtime on all tenant tables ──
+    for table_name in tenant_tables:
+        op.execute(
+            f'GRANT SELECT, INSERT, UPDATE, DELETE ON "{table_name}" TO crm_runtime'
+        )
+
+    # Grant usage on sequences (for SERIAL/IDENTITY columns)
+    op.execute("GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO crm_runtime")
+
+    logger.info("Granted DML permissions to crm_runtime on %d tables", len(tenant_tables))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # Revoke permissions from crm_runtime
+    tenant_tables = _discover_tenant_tables(conn)
+    for table_name in tenant_tables:
+        op.execute(f'REVOKE SELECT, INSERT, UPDATE, DELETE ON "{table_name}" FROM crm_runtime')
+    op.execute("REVOKE USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public FROM crm_runtime")
+
+    # Drop crm_runtime role
+    op.execute("DROP ROLE IF EXISTS crm_runtime")
+    logger.info("Dropped crm_runtime role")
+
+    # Note: RLS policies are NOT reverted here to avoid weakening security.
+    # Migration 0028's downgrade handles the original set of tables.

alembic/versions/0045_repair_contact_migration.py

@@ -0,0 +1,184 @@
+"""Forward-repair migration for databases that ran the original 0021/0027.
+
+Revision ID: 0045
+Revises: 0044
+Created: 2026-07-26
+
+Problem:
+  Migrations 0021 and 0027 were retroactively rewritten to be safer
+  (rename old tables, INSERT ... SELECT, preserve *_old tables).
+  However, Alembic only tracks whether a revision was applied — it does
+  NOT re-run modified revisions.  Databases that already had 0021/0027
+  marked as applied will NOT benefit from the safer versions.
+
+This migration:
+  1. Detects *_old tables (left behind by the rewritten 0021).
+  2. Compares row counts between *_old and current tables.
+  3. Migrates any missing rows from *_old to the current tables.
+  4. Logs discrepancies and aborts on data integrity issues.
+  5. Also repairs entity_type='company' → 'contact' (from rewritten 0027).
+
+Safe to run on fresh installations (no *_old tables → no-op).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+logger = logging.getLogger("alembic.migration.0045")
+
+revision = "0045"
+down_revision = "0044"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _table_exists(conn, table_name: str) -> bool:
+    """Check whether *table_name* exists in the public schema."""
+    result = conn.execute(
+        sa.text(
+            "SELECT EXISTS (SELECT 1 FROM information_schema.tables "
+            "WHERE table_schema = 'public' AND table_name = :t)"
+        ),
+        {"t": table_name},
+    )
+    return result.scalar()
+
+
+def _row_count(conn, table_name: str) -> int:
+    """Return the number of rows in *table_name*, or 0 if it doesn't exist."""
+    if not _table_exists(conn, table_name):
+        return -1
+    result = conn.execute(sa.text(f'SELECT COUNT(*) FROM "{table_name}"'))
+    return result.scalar()
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # ── 1. Check for *_old tables from rewritten migration 0021 ──
+    old_tables = ["contacts_old", "companies_old", "addresses_old"]
+    found_old = [t for t in old_tables if _table_exists(conn, t)]
+
+    if not found_old:
+        logger.info("0045: No *_old tables found — fresh install or already repaired. Skipping.")
+    else:
+        logger.info("0045: Found *_old tables: %s — checking data integrity...", found_old)
+
+        # Compare contacts_old → contacts
+        if _table_exists(conn, "contacts_old"):
+            old_count = _row_count(conn, "contacts_old")
+            new_count = _row_count(conn, "contacts")
+            logger.info("0045: contacts_old=%d rows, contacts=%d rows", old_count, new_count)
+
+            if old_count > new_count:
+                # Migrate missing rows from contacts_old to contacts
+                missing = old_count - new_count
+                logger.warning("0045: %d contacts missing from current table — migrating...", missing)
+                op.execute(
+                    sa.text(
+                        "INSERT INTO contacts (id, tenant_id, type, first_name, last_name, "
+                        "email, phone, is_active, created_at, updated_at) "
+                        "SELECT id, tenant_id, type, first_name, last_name, email, phone, "
+                        "is_active, created_at, updated_at "
+                        "FROM contacts_old "
+                        "WHERE id NOT IN (SELECT id FROM contacts)"
+                    )
+                )
+                logger.info("0045: Migrated %d missing contacts", missing)
+
+        # Compare companies_old → contacts (type='company')
+        if _table_exists(conn, "companies_old"):
+            old_count = _row_count(conn, "companies_old")
+            new_count = conn.execute(
+                sa.text("SELECT COUNT(*) FROM contacts WHERE type = 'company'")
+            ).scalar()
+            logger.info("0045: companies_old=%d rows, contacts(type=company)=%d rows", old_count, new_count)
+
+            if old_count > new_count:
+                missing = old_count - new_count
+                logger.warning("0045: %d companies missing — migrating...", missing)
+                op.execute(
+                    sa.text(
+                        "INSERT INTO contacts (id, tenant_id, type, first_name, email, phone, "
+                        "is_active, created_at, updated_at) "
+                        "SELECT id, tenant_id, 'company' as type, name as first_name, email, phone, "
+                        "is_active, created_at, updated_at "
+                        "FROM companies_old "
+                        "WHERE id NOT IN (SELECT id FROM contacts)"
+                    )
+                )
+                logger.info("0045: Migrated %d missing companies", missing)
+
+    # ── 2. Repair entity_type='company' → 'contact' (from rewritten 0027) ──
+    # Check if any rows still have entity_type='company' in relevant tables
+    repair_tables = [
+        ("entity_links", "entity_type"),
+        ("tag_assignments", "entity_type"),
+        ("calendar_entry_links", "entity_type"),
+        ("addresses", "entity_type"),
+    ]
+
+    for table, col in repair_tables:
+        if not _table_exists(conn, table):
+            continue
+        try:
+            result = conn.execute(
+                sa.text(f"SELECT COUNT(*) FROM \"{table}\" WHERE {col} = 'company'")
+            )
+            count = result.scalar()
+            if count > 0:
+                logger.warning("0045: Found %d rows with entity_type='company' in %s — repairing...", count, table)
+                op.execute(
+                    sa.text(f"UPDATE \"{table}\" SET {col} = 'contact' WHERE {col} = 'company'")
+                )
+                logger.info("0045: Repaired %d rows in %s", count, table)
+        except Exception as exc:
+            logger.warning("0045: Could not check/repair %s: %s", table, exc)
+
+    # ── 3. Repair mails.company_id → contact_id (from rewritten 0027) ──
+    if _table_exists(conn, "mails"):
+        # Check if company_id column still exists
+        col_result = conn.execute(
+            sa.text(
+                "SELECT EXISTS (SELECT 1 FROM information_schema.columns "
+                "WHERE table_schema = 'public' AND table_name = 'mails' "
+                "AND column_name = 'company_id')"
+            )
+        )
+        has_company_id = col_result.scalar()
+
+        if has_company_id:
+            # Copy company_id → contact_id where contact_id is NULL
+            result = conn.execute(
+                sa.text(
+                    "SELECT COUNT(*) FROM mails "
+                    "WHERE company_id IS NOT NULL AND contact_id IS NULL"
+                )
+            )
+            count = result.scalar()
+            if count > 0:
+                logger.warning("0045: Found %d mails with company_id but no contact_id — repairing...", count)
+                op.execute(
+                    sa.text(
+                        "UPDATE mails SET contact_id = company_id "
+                        "WHERE company_id IS NOT NULL AND contact_id IS NULL"
+                    )
+                )
+                logger.info("0045: Repaired %d mail contact_id references", count)
+
+            # Drop company_id column (safe now that data is copied)
+            op.execute(sa.text("ALTER TABLE mails DROP COLUMN IF EXISTS company_id"))
+            logger.info("0045: Dropped mails.company_id column")
+
+    logger.info("0045: Forward-repair migration completed")
+
+
+def downgrade() -> None:
+    # This migration is a repair — no meaningful downgrade.
+    # The *_old tables and original data are preserved by migration 0021.
+    logger.info("0045: Downgrade is a no-op (repair migration)")

alembic/versions/0046_plugin_allowlist.py

@@ -0,0 +1,40 @@
+"""Create plugin_allowlist table for authorized external plugins.
+
+Revision ID: 0046
+Revises: 0045
+Create Date: 2026-07-26
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0046"
+down_revision = "0045"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.create_table(
+        "plugin_allowlist",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("plugin_name", sa.String(80), nullable=False),
+        sa.Column("allowed_hash", sa.String(64), nullable=True),
+        sa.Column("allowed_signature", sa.Text, nullable=True),
+        sa.Column("public_key", sa.Text, nullable=True),
+        sa.Column("added_by", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("is_active", sa.Boolean, nullable=False, server_default=sa.text("true")),
+        sa.Column("notes", sa.Text, nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index("ix_plugin_allowlist_plugin_name", "plugin_allowlist", ["plugin_name"])
+    op.create_index("ix_plugin_allowlist_hash", "plugin_allowlist", ["allowed_hash"])
+
+
+def downgrade():
+    op.drop_index("ix_plugin_allowlist_hash", table_name="plugin_allowlist")
+    op.drop_index("ix_plugin_allowlist_plugin_name", table_name="plugin_allowlist")
+    op.drop_table("plugin_allowlist")

alembic/versions/0047_saved_views.py

@@ -0,0 +1,39 @@
+"""Create saved_views table
+
+Revision ID: 0047_saved_views
+Revises: 0046_plugin_allowlist
+Create Date: 2026-07-28
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID, JSONB
+
+revision = "0047_saved_views"
+down_revision = "0046"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "saved_views",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("name", sa.String(100), nullable=False),
+        sa.Column("entity_type", sa.String(50), nullable=False),
+        sa.Column("view_config", JSONB, nullable=False, server_default=sa.text("'{}'::jsonb")),
+        sa.Column("user_id", UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("tenant_id", UUID(as_uuid=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_unique_constraint("uq_saved_views_tenant_user_entity_name", "saved_views", ["tenant_id", "user_id", "entity_type", "name"])
+    op.create_index("ix_saved_views_tenant_user", "saved_views", ["tenant_id", "user_id"])
+    op.create_index("ix_saved_views_tenant_entity", "saved_views", ["tenant_id", "entity_type"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_saved_views_tenant_entity", table_name="saved_views")
+    op.drop_index("ix_saved_views_tenant_user", table_name="saved_views")
+    op.drop_unique_constraint("uq_saved_views_tenant_user_entity_name", "saved_views")
+    op.drop_table("saved_views")

alembic/versions/0048_contact_folder_permissions.py

@@ -0,0 +1,48 @@
+"""Contact folder permissions (ACLs for folder sharing).
+
+Revision ID: 0048
+Revises: 0047
+Create Date: 2026-07-28
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0048"
+down_revision = "0047_saved_views"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "contact_folder_permissions",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True),
+        sa.Column("folder_id", PGUUID(as_uuid=True), sa.ForeignKey("contact_folders.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("user_id", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=True),
+        sa.Column("group_id", PGUUID(as_uuid=True), sa.ForeignKey("groups.id", ondelete="CASCADE"), nullable=True),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("permission_level", sa.String(20), nullable=False, server_default="read"),
+        sa.Column("inherit_to_subfolders", sa.Boolean, nullable=False, server_default="true"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("folder_id", "user_id", "group_id", "tenant_id", name="uq_cfp_folder_user_group_tenant"),
+        sa.CheckConstraint(
+            "(user_id IS NOT NULL AND group_id IS NULL) OR "
+            "(user_id IS NULL AND group_id IS NOT NULL)",
+            name="ck_cfp_exactly_one_principal",
+        ),
+    )
+    op.create_index("ix_cfp_folder", "contact_folder_permissions", ["folder_id"])
+    op.create_index("ix_cfp_user", "contact_folder_permissions", ["user_id"])
+    op.create_index("ix_cfp_group", "contact_folder_permissions", ["group_id"])
+    op.create_index("ix_cfp_tenant", "contact_folder_permissions", ["tenant_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_cfp_tenant", table_name="contact_folder_permissions")
+    op.drop_index("ix_cfp_group", table_name="contact_folder_permissions")
+    op.drop_index("ix_cfp_user", table_name="contact_folder_permissions")
+    op.drop_index("ix_cfp_folder", table_name="contact_folder_permissions")
+    op.drop_table("contact_folder_permissions")

alembic/versions/0049_entity_permissions.py

@@ -0,0 +1,47 @@
+"""Universal entity_permissions table — ACLs for ALL entities.
+
+Revision ID: 0049
+Revises: 0048
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0049"
+down_revision = "0048"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "entity_permissions",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True),
+        sa.Column("entity_type", sa.String(50), nullable=False),
+        sa.Column("entity_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("principal_type", sa.String(10), nullable=False),
+        sa.Column("principal_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("permission_level", sa.String(20), nullable=False, server_default="read"),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_by", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+        sa.UniqueConstraint("entity_type", "entity_id", "principal_type", "principal_id", "tenant_id", name="uq_ep_entity_principal_tenant"),
+        sa.CheckConstraint("principal_type IN ('user', 'group', 'role', 'guest')", name="ck_ep_principal_type"),
+        sa.CheckConstraint("permission_level IN ('none', 'read', 'write', 'admin', 'delete')", name="ck_ep_permission_level"),
+    )
+    op.create_index("ix_ep_entity", "entity_permissions", ["entity_type", "entity_id"])
+    op.create_index("ix_ep_principal", "entity_permissions", ["principal_type", "principal_id"])
+    op.create_index("ix_ep_tenant", "entity_permissions", ["tenant_id"])
+    op.create_index("ix_ep_expires", "entity_permissions", ["expires_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_ep_expires", table_name="entity_permissions")
+    op.drop_index("ix_ep_tenant", table_name="entity_permissions")
+    op.drop_index("ix_ep_principal", table_name="entity_permissions")
+    op.drop_index("ix_ep_entity", table_name="entity_permissions")
+    op.drop_table("entity_permissions")

alembic/versions/0050_owner_id_all_tables.py

@@ -0,0 +1,49 @@
+"""Add owner_id to all entity tables for row-level ownership.
+
+Revision ID: 0050
+Revises: 0049
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0050"
+down_revision = "0049"
+branch_labels = None
+depends_on = None
+
+# Tables that get owner_id (all entity tables except system tables)
+TABLES = [
+    "contacts",
+    "contactpersons",
+    "addresses",
+    "bank_accounts",
+    "attachments",
+    "workflows",
+    "workflow_instances",
+    "sequences",
+    "saved_filters",
+    "saved_views",
+    "webhooks",
+    "custom_field_definitions",
+    "notifications",
+    "entity_history",
+    "ai_conversations",
+]
+
+
+def upgrade() -> None:
+    for table in TABLES:
+        op.add_column(
+            table,
+            sa.Column("owner_id", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        )
+        op.create_index(f"ix_{table}_owner", table, ["owner_id"])
+
+
+def downgrade() -> None:
+    for table in TABLES:
+        op.drop_index(f"ix_{table}_owner", table_name=table)
+        op.drop_column(table, "owner_id")

alembic/versions/0051_migrate_folder_acls.py

@@ -0,0 +1,41 @@
+"""Migrate contact_folder_permissions to universal entity_permissions table.
+
+Revision ID: 0051
+Revises: 0050
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0051"
+down_revision = "0050"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Migrate existing contact_folder_permissions to entity_permissions
+    op.execute("""
+        INSERT INTO entity_permissions (id, entity_type, entity_id, principal_type, principal_id, permission_level, tenant_id, created_at, updated_at)
+        SELECT 
+            gen_random_uuid(),
+            'contact_folder',
+            folder_id,
+            CASE 
+                WHEN user_id IS NOT NULL THEN 'user'
+                WHEN group_id IS NOT NULL THEN 'group'
+            END,
+            COALESCE(user_id, group_id),
+            permission_level,
+            tenant_id,
+            created_at,
+            updated_at
+        FROM contact_folder_permissions
+        ON CONFLICT DO NOTHING
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DELETE FROM entity_permissions WHERE entity_type = 'contact_folder'")

alembic/versions/0052_rls_contacts.py

@@ -0,0 +1,90 @@
+"""Create PostgreSQL RLS policies for row-level security on contacts.
+
+Revision ID: 0052
+Revises: 0051
+Create Date: 2026-07-29
+
+This migration enables PostgreSQL Row-Level Security on the contacts table
+and creates policies that enforce visibility based on:
+1. System admin sees everything
+2. Owner sees own rows
+3. Tenant-owned (owner_id IS NULL) visible to all
+4. Shared via entity_permissions
+"""
+
+from alembic import op
+
+revision = "0052"
+down_revision = "0051"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Enable RLS on contacts table
+    op.execute("ALTER TABLE contacts ENABLE ROW LEVEL SECURITY")
+    
+    # Policy: System admin sees everything
+    op.execute("""
+        CREATE POLICY contacts_admin_visible ON contacts
+        FOR ALL
+        USING (current_setting('app.is_system_admin', true) = 'true')
+    """)
+    
+    # Policy: Owner sees own rows
+    op.execute("""
+        CREATE POLICY contacts_owner_visible ON contacts
+        FOR ALL
+        USING (
+            owner_id::text = current_setting('app.current_user_id', true)
+        )
+    """)
+    
+    # Policy: Tenant-owned (owner_id IS NULL) visible to all in tenant
+    op.execute("""
+        CREATE POLICY contacts_tenant_owned_visible ON contacts
+        FOR ALL
+        USING (owner_id IS NULL)
+    """)
+    
+    # Policy: Shared via entity_permissions
+    op.execute("""
+        CREATE POLICY contacts_shared_visible ON contacts
+        FOR ALL
+        USING (
+            EXISTS (
+                SELECT 1 FROM entity_permissions ep
+                WHERE ep.entity_type = 'contact'
+                AND ep.entity_id = contacts.id
+                AND ep.tenant_id = contacts.tenant_id
+                AND ep.permission_level != 'none'
+                AND (
+                    ep.expires_at IS NULL OR ep.expires_at > NOW()
+                )
+                AND (
+                    (ep.principal_type = 'user' 
+                     AND ep.principal_id::text = current_setting('app.current_user_id', true))
+                    OR
+                    (ep.principal_type = 'group'
+                     AND ep.principal_id::text = ANY(
+                         string_to_array(current_setting('app.current_user_groups', true), ',')
+                     ))
+                    OR
+                    (ep.principal_type = 'role'
+                     AND ep.principal_id IN (
+                         SELECT ut.role_id FROM user_tenants ut
+                         WHERE ut.user_id::text = current_setting('app.current_user_id', true)
+                         AND ut.tenant_id = contacts.tenant_id
+                     ))
+                )
+            )
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.execute("DROP POLICY IF EXISTS contacts_shared_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_tenant_owned_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_owner_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_admin_visible ON contacts")
+    op.execute("ALTER TABLE contacts DISABLE ROW LEVEL SECURITY")

alembic/versions/0053_mail_owner_id.py

@@ -0,0 +1,41 @@
+"""Add owner_id to mail_accounts for row-level permissions.
+
+Revision ID: 0053
+Revises: 0052
+Create Date: 2026-07-29
+
+This migration adds owner_id to mail_accounts so that the universal
+visibility/permission system (apply_visibility_filter, check_single_entity_access)
+can be used for mail accounts.
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "0053"
+down_revision = "0052"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.add_column(
+        "mail_accounts",
+        sa.Column(
+            "owner_id",
+            UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )
+    op.create_index(
+        "ix_mail_accounts_owner",
+        "mail_accounts",
+        ["owner_id"],
+    )
+
+
+def downgrade():
+    op.drop_index("ix_mail_accounts_owner", table_name="mail_accounts")
+    op.drop_column("mail_accounts", "owner_id")

alembic/versions/0054_plugin_owner_id.py

@@ -0,0 +1,62 @@
+"""Add owner_id to plugin entity tables for row-level ownership.
+
+Revision ID: 0054
+Revises: 0053
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0054"
+down_revision = "0053"
+branch_labels = None
+depends_on = None
+
+# Tables that need owner_id
+TABLES = [
+    "files",
+    "folders",
+    "calendar_entries",
+    "calendars",
+    "tasks",
+    "subtasks",
+]
+
+
+def upgrade() -> None:
+    # Check which columns already exist before adding
+    conn = op.get_bind()
+    for table in TABLES:
+        # Check if column already exists
+        result = conn.execute(
+            sa.text(
+                "SELECT column_name FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = 'owner_id'"
+            ),
+            {"table": table},
+        )
+        if result.fetchone() is None:
+            op.add_column(
+                table,
+                sa.Column(
+                    "owner_id",
+                    PGUUID(as_uuid=True),
+                    sa.ForeignKey("users.id", ondelete="SET NULL"),
+                    nullable=True,
+                ),
+            )
+            op.create_index(f"ix_{table}_owner", table, ["owner_id"])
+
+
+def downgrade() -> None:
+    for table in TABLES:
+        try:
+            op.drop_index(f"ix_{table}_owner", table_name=table)
+        except Exception:
+            pass
+        try:
+            op.drop_column(table, "owner_id")
+        except Exception:
+            pass

alembic/versions/0055_entity_policies.py

@@ -0,0 +1,55 @@
+"""Create entity_policies table for ABAC engine.
+
+Revision ID: 0055
+Revises: 0054
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB, UUID as PGUUID
+
+revision = "0055"
+down_revision = "0054"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "entity_policies",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("entity_type", sa.String(50), nullable=False),
+        sa.Column("principal_type", sa.String(10), nullable=False),
+        sa.Column("principal_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("effect", sa.String(10), nullable=False, server_default=sa.text("'allow'")),
+        sa.Column("conditions", JSONB, nullable=True),
+        sa.Column("priority", sa.Integer, nullable=False, server_default=sa.text("0")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("enabled", sa.Boolean, nullable=False, server_default=sa.text("true")),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.CheckConstraint(
+            "principal_type IN ('user', 'group', 'role')",
+            name="ck_epol_principal_type",
+        ),
+        sa.CheckConstraint(
+            "effect IN ('allow', 'deny')",
+            name="ck_epol_effect",
+        ),
+    )
+    op.create_index("ix_epol_entity_type", "entity_policies", ["entity_type"])
+    op.create_index("ix_epol_principal", "entity_policies", ["principal_type", "principal_id"])
+    op.create_index("ix_epol_tenant", "entity_policies", ["tenant_id"])
+    op.create_index("ix_epol_priority", "entity_policies", ["priority"])
+    op.create_index("ix_epol_enabled", "entity_policies", ["enabled"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_epol_enabled", table_name="entity_policies")
+    op.drop_index("ix_epol_priority", table_name="entity_policies")
+    op.drop_index("ix_epol_tenant", table_name="entity_policies")
+    op.drop_index("ix_epol_principal", table_name="entity_policies")
+    op.drop_index("ix_epol_entity_type", table_name="entity_policies")
+    op.drop_table("entity_policies")

alembic/versions/0056_permission_templates.py

@@ -0,0 +1,42 @@
+"""Create permission_templates table.
+
+Revision ID: 0056
+Revises: 0055
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB, UUID as PGUUID
+
+revision = "0056"
+down_revision = "0055"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "permission_templates",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("name", sa.String(200), nullable=False),
+        sa.Column("entity_type", sa.String(50), nullable=False),
+        sa.Column("trigger_condition", JSONB, nullable=True),
+        sa.Column("auto_share_with", JSONB, nullable=True),
+        sa.Column("level", sa.String(20), nullable=False, server_default=sa.text("'read'")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.CheckConstraint(
+            "level IN ('read', 'write', 'admin', 'delete')",
+            name="ck_pt_level",
+        ),
+    )
+    op.create_index("ix_pt_entity_type", "permission_templates", ["entity_type"])
+    op.create_index("ix_pt_tenant", "permission_templates", ["tenant_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_pt_tenant", table_name="permission_templates")
+    op.drop_index("ix_pt_entity_type", table_name="permission_templates")
+    op.drop_table("permission_templates")

alembic/versions/0057_permission_delegations.py

@@ -0,0 +1,47 @@
+"""Create permission_delegations table.
+
+Revision ID: 0057
+Revises: 0056
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB, UUID as PGUUID
+
+revision = "0057"
+down_revision = "0056"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "permission_delegations",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("from_user_id", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("to_user_id", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("start_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("end_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("scope", JSONB, nullable=True),
+        sa.Column("active", sa.Boolean, nullable=False, server_default=sa.text("true")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.CheckConstraint(
+            "end_at > start_at",
+            name="ck_pd_end_after_start",
+        ),
+    )
+    op.create_index("ix_pd_from_user", "permission_delegations", ["from_user_id"])
+    op.create_index("ix_pd_to_user", "permission_delegations", ["to_user_id"])
+    op.create_index("ix_pd_tenant", "permission_delegations", ["tenant_id"])
+    op.create_index("ix_pd_active", "permission_delegations", ["active"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_pd_active", table_name="permission_delegations")
+    op.drop_index("ix_pd_tenant", table_name="permission_delegations")
+    op.drop_index("ix_pd_to_user", table_name="permission_delegations")
+    op.drop_index("ix_pd_from_user", table_name="permission_delegations")
+    op.drop_table("permission_delegations")

alembic/versions/0058_resolution_strategy.py

@@ -0,0 +1,36 @@
+"""Add resolution_strategy field to tenants table.
+
+Revision ID: 0058
+Revises: 0057
+Create Date: 2026-07-29
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0058"
+down_revision = "0057"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tenants",
+        sa.Column(
+            "resolution_strategy",
+            sa.String(30),
+            nullable=False,
+            server_default=sa.text("'highest_wins'"),
+        ),
+    )
+    op.create_check_constraint(
+        "ck_tenant_resolution_strategy",
+        "tenants",
+        "resolution_strategy IN ('highest_wins', 'deny_overrides_allow', 'direct_overrides_group', 'most_restrictive_wins')",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("ck_tenant_resolution_strategy", "tenants")
+    op.drop_column("tenants", "resolution_strategy")

alembic/versions/0059_guest_users.py

@@ -0,0 +1,46 @@
+"""Create guest_users table.
+
+Revision ID: 0059
+Revises: 0058
+Create Date: 2026-07-29 02:47:00.000000
+"""
+
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0059"
+down_revision: str | None = "0058"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "guest_users",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("email", sa.String(255), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column("password_hash", sa.String(255), nullable=True),
+        sa.Column("tenant_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("invited_by", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("status", sa.String(20), nullable=False, server_default="invited"),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_guest_users_email_tenant", "guest_users", ["email", "tenant_id"], unique=True)
+    op.create_index("ix_guest_users_status", "guest_users", ["status", "tenant_id"])
+    op.create_index("ix_guest_users_invited_by", "guest_users", ["invited_by"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_guest_users_invited_by", table_name="guest_users")
+    op.drop_index("ix_guest_users_status", table_name="guest_users")
+    op.drop_index("ix_guest_users_email_tenant", table_name="guest_users")
+    op.drop_table("guest_users")

alembic/versions/0060_rls_contacts_secure.py

@@ -0,0 +1,202 @@
+"""Fix RLS policies on contacts — add tenant_id isolation.
+
+Revision ID: 0060
+Revises: 0059
+Create Date: 2026-07-29
+
+This migration drops the insecure contact RLS policies (created in 0052)
+and recreates them with proper tenant_id isolation.
+
+Problems fixed:
+1. contacts_tenant_owned_visible had USING (owner_id IS NULL) without tenant_id check
+2. contacts_admin_visible had no tenant_id check
+3. contacts_owner_visible had no tenant_id check
+4. All policies used FOR ALL instead of separate SELECT/INSERT/UPDATE/DELETE
+5. No WITH CHECK on write operations
+"""
+
+from alembic import op
+
+revision = "0060"
+down_revision = "0059"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Drop all existing contact policies
+    op.execute("DROP POLICY IF EXISTS contacts_admin_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_owner_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_tenant_owned_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_shared_visible ON contacts")
+    op.execute("DROP POLICY IF EXISTS tenant_isolation ON contacts")
+
+    # ── Restrive policy: Tenant isolation (always enforced) ──
+    # This is the base policy that ALL other permissive policies are ANDed with
+    op.execute("""
+        CREATE POLICY contacts_tenant_isolation ON contacts
+        FOR ALL
+        USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid)
+        WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)
+    """)
+
+    # ── Permissive policies for SELECT (visibility) ──
+
+    # System admin sees everything (within tenant)
+    op.execute("""
+        CREATE POLICY contacts_admin_select ON contacts
+        FOR SELECT
+        USING (
+            current_setting('app.is_system_admin', true) = 'true'
+            AND tenant_id = current_setting('app.current_tenant_id', true)::uuid
+        )
+    """)
+
+    # Owner sees own rows (within tenant)
+    op.execute("""
+        CREATE POLICY contacts_owner_select ON contacts
+        FOR SELECT
+        USING (
+            owner_id::text = current_setting('app.current_user_id', true)
+            AND tenant_id = current_setting('app.current_tenant_id', true)::uuid
+        )
+    """)
+
+    # Tenant-owned (owner_id IS NULL) visible to all in tenant
+    op.execute("""
+        CREATE POLICY contacts_tenant_owned_select ON contacts
+        FOR SELECT
+        USING (
+            owner_id IS NULL
+            AND tenant_id = current_setting('app.current_tenant_id', true)::uuid
+        )
+    """)
+
+    # Shared via entity_permissions (within tenant)
+    op.execute("""
+        CREATE POLICY contacts_shared_select ON contacts
+        FOR SELECT
+        USING (
+            EXISTS (
+                SELECT 1 FROM entity_permissions ep
+                WHERE ep.entity_type = 'contact'
+                AND ep.entity_id = contacts.id
+                AND ep.tenant_id = contacts.tenant_id
+                AND ep.permission_level != 'none'
+                AND (
+                    ep.expires_at IS NULL OR ep.expires_at > NOW()
+                )
+                AND (
+                    (ep.principal_type = 'user'
+                     AND ep.principal_id::text = current_setting('app.current_user_id', true))
+                    OR
+                    (ep.principal_type = 'group'
+                     AND ep.principal_id::text = ANY(
+                         string_to_array(current_setting('app.current_user_groups', true), ',')
+                     ))
+                    OR
+                    (ep.principal_type = 'role'
+                     AND ep.principal_id IN (
+                         SELECT ut.role_id FROM user_tenants ut
+                         WHERE ut.user_id::text = current_setting('app.current_user_id', true)
+                         AND ut.tenant_id = contacts.tenant_id
+                     ))
+                )
+            )
+            AND tenant_id = current_setting('app.current_tenant_id', true)::uuid
+        )
+    """)
+
+    # ── Permissive policies for INSERT ──
+    op.execute("""
+        CREATE POLICY contacts_insert_policy ON contacts
+        FOR INSERT
+        WITH CHECK (
+            tenant_id = current_setting('app.current_tenant_id', true)::uuid
+            AND (
+                current_setting('app.is_system_admin', true) = 'true'
+                OR owner_id::text = current_setting('app.current_user_id', true)
+                OR owner_id IS NULL
+            )
+        )
+    """)
+
+    # ── Permissive policies for UPDATE ──
+    op.execute("""
+        CREATE POLICY contacts_update_policy ON contacts
+        FOR UPDATE
+        USING (
+            tenant_id = current_setting('app.current_tenant_id', true)::uuid
+            AND (
+                current_setting('app.is_system_admin', true) = 'true'
+                OR owner_id::text = current_setting('app.current_user_id', true)
+                OR owner_id IS NULL
+                OR EXISTS (
+                    SELECT 1 FROM entity_permissions ep
+                    WHERE ep.entity_type = 'contact'
+                    AND ep.entity_id = contacts.id
+                    AND ep.tenant_id = contacts.tenant_id
+                    AND ep.permission_level IN ('write', 'admin', 'delete')
+                    AND (
+                        ep.expires_at IS NULL OR ep.expires_at > NOW()
+                    )
+                    AND (
+                        (ep.principal_type = 'user'
+                         AND ep.principal_id::text = current_setting('app.current_user_id', true))
+                        OR
+                        (ep.principal_type = 'group'
+                         AND ep.principal_id::text = ANY(
+                             string_to_array(current_setting('app.current_user_groups', true), ',')
+                         ))
+                    )
+                )
+            )
+        )
+        WITH CHECK (
+            tenant_id = current_setting('app.current_tenant_id', true)::uuid
+        )
+    """)
+
+    # ── Permissive policies for DELETE ──
+    op.execute("""
+        CREATE POLICY contacts_delete_policy ON contacts
+        FOR DELETE
+        USING (
+            tenant_id = current_setting('app.current_tenant_id', true)::uuid
+            AND (
+                current_setting('app.is_system_admin', true) = 'true'
+                OR owner_id::text = current_setting('app.current_user_id', true)
+                OR EXISTS (
+                    SELECT 1 FROM entity_permissions ep
+                    WHERE ep.entity_type = 'contact'
+                    AND ep.entity_id = contacts.id
+                    AND ep.tenant_id = contacts.tenant_id
+                    AND ep.permission_level IN ('admin', 'delete')
+                    AND (
+                        ep.expires_at IS NULL OR ep.expires_at > NOW()
+                    )
+                    AND (
+                        (ep.principal_type = 'user'
+                         AND ep.principal_id::text = current_setting('app.current_user_id', true))
+                        OR
+                        (ep.principal_type = 'group'
+                         AND ep.principal_id::text = ANY(
+                             string_to_array(current_setting('app.current_user_groups', true), ',')
+                         ))
+                    )
+                )
+            )
+        )
+    """)
+
+
+def downgrade() -> None:
+    # Drop the new secure policies
+    op.execute("DROP POLICY IF EXISTS contacts_tenant_isolation ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_admin_select ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_owner_select ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_tenant_owned_select ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_shared_select ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_insert_policy ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_update_policy ON contacts")
+    op.execute("DROP POLICY IF EXISTS contacts_delete_policy ON contacts")

alembic/versions/0061_db_roles_secure.py

@@ -0,0 +1,65 @@
+"""Fix DB roles — add default privileges and grants for all tables.
+
+Revision ID: 0061
+Revises: 0060
+Create Date: 2026-07-29
+
+Problems fixed:
+1. crm_runtime role has no grants on tables created after migration 0044
+2. No ALTER DEFAULT PRIVILEGES for future tables
+3. Auth tables (users, tenants, user_tenants, user_groups) need SELECT grants
+4. New permission/guest/policy tables need grants
+"""
+
+from alembic import op
+
+revision = "0061"
+down_revision = "0060"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Grant privileges on all existing tables to crm_runtime
+    op.execute("GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO crm_runtime")
+    
+    # Grant USAGE on sequences
+    op.execute("GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO crm_runtime")
+    
+    # Default privileges for future tables created by migration owner
+    op.execute("ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crm_runtime")
+    op.execute("ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO crm_runtime")
+    
+    # Ensure RLS is enabled on all tenant tables that have tenant_id
+    # (covers tables created after migration 0044 that missed RLS)
+    tenant_tables = [
+        "entity_permissions",
+        "entity_policies",
+        "permission_templates",
+        "guest_users",
+        "contact_folder_permissions",
+    ]
+    for table in tenant_tables:
+        op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")
+        # Create tenant isolation policy if not exists
+        op.execute(f"""
+            DO $$
+            BEGIN
+                IF NOT EXISTS (
+                    SELECT 1 FROM pg_policy 
+                    WHERE polname = '{table}_tenant_isolation' 
+                    AND polrelid = '{table}'::regclass
+                ) THEN
+                    CREATE POLICY {table}_tenant_isolation ON {table}
+                    FOR ALL
+                    USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid)
+                    WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid);
+                END IF;
+            END $$;
+        """)
+
+
+def downgrade() -> None:
+    # Revoke default privileges
+    op.execute("ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE SELECT, INSERT, UPDATE, DELETE ON TABLES FROM crm_runtime")
+    op.execute("ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE USAGE, SELECT ON SEQUENCES FROM crm_runtime")

alembic/versions/0062_guest_invitations_secure.py

@@ -0,0 +1,51 @@
+"""Fix guest invitation security — separate token table.
+
+Revision ID: 0062
+Revises: 0061
+Create Date: 2026-07-29
+
+Problems fixed:
+1. Guest UUID was used as invitation token (P1.6)
+2. No separate token with sufficient entropy
+3. No one-time use tracking
+4. No session revocation on guest deletion
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "0062"
+down_revision = "0061"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "guest_invitations",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("guest_user_id", UUID(as_uuid=True), sa.ForeignKey("guest_users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("token_hash", sa.String(64), nullable=False, unique=True, index=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("revoked_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_by", UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+    )
+    op.execute("ALTER TABLE guest_invitations ENABLE ROW LEVEL SECURITY")
+    op.execute("""
+        CREATE POLICY guest_invitations_tenant_isolation ON guest_invitations
+        FOR ALL
+        USING (
+            EXISTS (
+                SELECT 1 FROM guest_users gu
+                WHERE gu.id = guest_invitations.guest_user_id
+                AND gu.tenant_id = current_setting('app.current_tenant_id', true)::uuid
+            )
+        )
+    """)
+
+
+def downgrade() -> None:
+    op.drop_table("guest_invitations")

alembic/versions/0063_notification_entity_fields.py

@@ -0,0 +1,28 @@
+"""Add entity_type and entity_id to notifications table.
+
+Revision ID: 0063
+Revises: 0062
+Create Date: 2026-07-29
+
+The notification model has entity_type and entity_id fields but the DB
+table was never migrated. This causes INSERT failures.
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "0063"
+down_revision = "0062"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("notifications", sa.Column("entity_type", sa.String(50), nullable=True, index=True))
+    op.add_column("notifications", sa.Column("entity_id", UUID(as_uuid=True), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("notifications", "entity_id")
+    op.drop_column("notifications", "entity_type")

alembic/versions/0064_rls_all_tenant_tables.py

@@ -0,0 +1,86 @@
+"""Enable RLS on all remaining tenant tables.
+
+Revision ID: 0064
+Revises: 0063
+Create Date: 2026-07-29
+
+Currently RLS is only on contacts. This migration enables RLS on all
+tenant-scoped tables that have a tenant_id column but no RLS yet.
+
+System tables (users, tenants, groups, roles) are excluded — they need
+special handling for the login bootstrap process.
+"""
+
+from alembic import op
+
+revision = "0064"
+down_revision = "0063"
+branch_labels = None
+depends_on = None
+
+# Tables that should have RLS (tenant-scoped data)
+TENANT_TABLES = [
+    "addresses",
+    "attachments",
+    "bank_accounts",
+    "contact_folders",
+    "contact_merge_history",
+    "workflows",
+    "sequences",
+    "saved_filters",
+    "saved_views",
+    "webhooks",
+    "custom_field_definitions",
+    "notifications",
+    "ai_conversations",
+    "contact_persons",
+    "tags",
+    "entity_links",
+    "dms_files",
+    "dms_folders",
+    "calendar_events",
+    "calendars",
+    "tasks",
+    "task_lists",
+    "mail_messages",
+    "mail_accounts",
+    "mail_folders",
+    "conversations",
+    "conversation_messages",
+    "conversation_participants",
+    "audit_log",
+    "permission_delegations",
+    "guest_invitations",
+]
+
+
+def upgrade() -> None:
+    for table in TENANT_TABLES:
+        # Enable RLS if not already enabled
+        op.execute(f"""
+            DO $$
+            BEGIN
+                IF NOT EXISTS (
+                    SELECT 1 FROM pg_class c
+                    WHERE c.relname = '{table}'
+                    AND c.relrowsecurity = true
+                ) AND EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_name = '{table}'
+                    AND column_name = 'tenant_id'
+                ) THEN
+                    ALTER TABLE {table} ENABLE ROW LEVEL SECURITY;
+                    
+                    CREATE POLICY {table}_tenant_isolation ON {table}
+                    FOR ALL
+                    USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid)
+                    WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid);
+                END IF;
+            END $$;
+        """)
+
+
+def downgrade() -> None:
+    for table in TENANT_TABLES:
+        op.execute(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON {table}")
+        op.execute(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY")

alembic/versions/0065_consumer_inbox.py

@@ -0,0 +1,40 @@
+"""Add consumer_inbox table for outbox idempotency.
+
+Revision ID: 0065
+Revises: 0064
+Create Date: 2026-07-29
+
+Without idempotency, a worker crash between sending an email/webhook
+and marking the event as published can lead to duplicate deliveries.
+
+This migration creates a consumer_inbox table that tracks which
+consumers have already processed which events.
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "0065"
+down_revision = "0064"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "consumer_inbox",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("event_id", UUID(as_uuid=True), sa.ForeignKey("event_outbox.id", ondelete="CASCADE"), nullable=False, index=True),
+        sa.Column("consumer_name", sa.String(100), nullable=False, index=True),
+        sa.Column("status", sa.String(20), nullable=False, default="pending"),  # pending, processed, failed
+        sa.Column("processed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("error_message", sa.Text, nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.UniqueConstraint("event_id", "consumer_name", name="uq_consumer_inbox_event_consumer"),
+    )
+    op.execute("ALTER TABLE consumer_inbox ENABLE ROW LEVEL SECURITY")
+
+
+def downgrade() -> None:
+    op.drop_table("consumer_inbox")

alembic/versions/0066_tenant_plugin_activation.py

@@ -0,0 +1,44 @@
+"""Add tenant_plugin_activation table for per-tenant plugin activation.
+
+Revision ID: 0066
+Revises: 0065
+Create Date: 2026-07-29
+
+Currently plugins are activated globally. This migration creates a
+table for per-tenant plugin activation so that different tenants can
+enable/disable plugins independently.
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "0066"
+down_revision = "0065"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "tenant_plugin_activation",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", UUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False, index=True),
+        sa.Column("plugin_name", sa.String(100), nullable=False, index=True),
+        sa.Column("is_active", sa.Boolean, nullable=False, default=True),
+        sa.Column("activated_by", UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.UniqueConstraint("tenant_id", "plugin_name", name="uq_tenant_plugin"),
+    )
+    op.execute("ALTER TABLE tenant_plugin_activation ENABLE ROW LEVEL SECURITY")
+    op.execute("""
+        CREATE POLICY tenant_plugin_activation_tenant_isolation ON tenant_plugin_activation
+        FOR ALL
+        USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid)
+        WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)
+    """)
+
+
+def downgrade() -> None:
+    op.drop_table("tenant_plugin_activation")

alembic/versions/0067_disable_rls_system_tables.py

@@ -0,0 +1,56 @@
+"""Disable RLS on system identity tables to fix login bootstrap circle.
+
+Revision ID: 0067
+Revises: 0066
+Create Date: 2026-07-29
+
+Problem: users, user_tenants, groups, roles have RLS enabled. The login
+process needs to query these tables BEFORE a tenant context is set
+(bootstrap circle: Login → Membership → Tenant-Context → Login).
+
+RLS on these tables blocks login because there's no tenant context yet.
+
+Solution: Disable RLS on system identity tables. Tenant isolation for
+these tables is enforced at the application level (auth_service always
+filters by user_id + tenant_id in queries).
+"""
+
+from alembic import op
+
+revision = "0067"
+down_revision = "0066"
+branch_labels = None
+depends_on = None
+
+# System identity tables — no RLS (needed for login bootstrap)
+SYSTEM_TABLES = [
+    "users",
+    "user_tenants",
+    "groups",
+    "user_groups",
+    "roles",
+]
+
+
+def upgrade() -> None:
+    for table in SYSTEM_TABLES:
+        # Drop any existing policies
+        op.execute(f"""
+            DO $$
+            DECLARE pol RECORD;
+            BEGIN
+                FOR pol IN
+                    SELECT polname FROM pg_policy
+                    WHERE polrelid = '{table}'::regclass
+                LOOP
+                    EXECUTE format('DROP POLICY IF EXISTS %I ON {table}', pol.polname);
+                END LOOP;
+            END $$;
+        """)
+        # Disable RLS
+        op.execute(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY")
+
+
+def downgrade() -> None:
+    for table in SYSTEM_TABLES:
+        op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")

alembic/versions/0068_entity_permissions_deleted_at.py

@@ -0,0 +1,28 @@
+"""Add deleted_at to entity_permissions table.
+
+Revision ID: 0068
+Revises: 0067
+Create Date: 2026-07-29
+
+The EntityPermission model has SoftDeleteMixin but the table was never
+migrated to include the deleted_at column.
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "0068"
+down_revision = "0067"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("entity_permissions", sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True))
+    op.execute("CREATE INDEX IF NOT EXISTS ix_entity_permissions_deleted_at ON entity_permissions (deleted_at)")
+
+
+def downgrade() -> None:
+    op.drop_index("ix_entity_permissions_deleted_at", table_name="entity_permissions")
+    op.drop_column("entity_permissions", "deleted_at")

alembic/versions/0069_rls_tenant_isolation_only.py

@@ -0,0 +1,103 @@
+"""Simplify RLS to pure tenant isolation.
+
+Per architecture review: RLS should be the "safety belt" (tenant isolation only),
+NOT the "vehicle control" (business authorization). Business authorization
+(owner_id, sharing, entity_permissions) belongs in the application layer
+(visibility.py with Defense-in-Depth tenant_id filter).
+
+Revision ID: 0069
+Revises: 0068
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision = "0069"
+down_revision = "0068"
+branch_labels = None
+depends_on = None
+
+RLS_TABLES = [
+    "contacts", "addresses", "attachments", "bank_accounts",
+    "contact_folders", "contact_folder_permissions", "entity_permissions",
+    "entity_policies", "event_outbox", "audit_log", "notifications",
+    "saved_filters", "saved_views", "webhooks", "workflow_instances",
+    "workflow_step_history", "sequences", "custom_field_definitions",
+    "custom_field_values", "guest_users", "guest_invitations",
+    "consumer_inbox", "tenant_plugin_activation", "permission_templates",
+    "permission_delegations", "dms_files", "dms_folders",
+    "calendar_events", "calendars", "tasks", "task_lists",
+    "messages", "channels", "entity_links", "tags", "tag_assignments",
+    "mail_accounts", "mail_messages", "mail_folders",
+    "report_templates", "report_generations", "ai_conversations",
+    "ai_messages", "automation_workflows", "automation_runs",
+    "mcp_server_configs", "mcp_client_configs", "system_notifications",
+]
+
+CONTACTS_POLICIES_TO_DROP = [
+    "contacts_admin_select", "contacts_owner_select",
+    "contacts_shared_select", "contacts_tenant_owned_select",
+    "contacts_delete_policy", "contacts_insert_policy",
+    "contacts_update_policy",
+]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # 1. Drop all business-logic RLS policies on contacts
+    for policy in CONTACTS_POLICIES_TO_DROP:
+        op.execute(f"DROP POLICY IF EXISTS {policy} ON contacts")
+
+    # 2. Drop old tenant_isolation policy on contacts
+    op.execute("DROP POLICY IF EXISTS contacts_tenant_isolation ON contacts")
+
+    # 3. Create simple tenant isolation for ALL operations on contacts
+    op.execute(
+        "CREATE POLICY contacts_tenant_isolation ON contacts "
+        "FOR ALL "
+        "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+        "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+    )
+
+    # 4. For all other RLS tables: drop existing policies, create simple tenant isolation
+    for table in RLS_TABLES:
+        if table == "contacts":
+            continue
+
+        # Check if table exists first
+        table_exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        
+        if not table_exists:
+            continue
+
+        # Get all existing policies on this table
+        result = conn.execute(
+            text(f"SELECT polname FROM pg_policy WHERE polrelid = '{table}'::regclass")
+        )
+        policies = [row[0] for row in result]
+
+        # Drop each policy
+        for policy in policies:
+            op.execute(f'DROP POLICY IF EXISTS "{policy}" ON {table}')
+
+        # Check if table has tenant_id column
+        col_result = conn.execute(
+            text(f"SELECT 1 FROM information_schema.columns "
+            f"WHERE table_name = '{table}' AND column_name = 'tenant_id'")
+        )
+        has_tenant_id = col_result.fetchone() is not None
+
+        if has_tenant_id:
+            op.execute(
+                f"CREATE POLICY {table}_tenant_isolation ON {table} "
+                "FOR ALL "
+                "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+                "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+            )
+
+
+def downgrade() -> None:
+    pass

alembic/versions/0070_db_roles_separation.py

@@ -0,0 +1,107 @@
+"""Create 4 separate DB roles for strict separation.
+
+crm_migration: Schema owner, runs Alembic, BypassRLS
+  - Owns all tables, sequences, functions
+  - Can bypass RLS for migrations
+  - Never used by the API
+
+crm_auth: Login bootstrap only
+  - Reads users, user_tenants, tenants, roles, groups
+  - NO RLS on system tables (already disabled)
+  - No general CRM data access
+
+crm_api: Application runtime
+  - NOBYPASSRLS, NOSUPERUSER
+  - SELECT, INSERT, UPDATE, DELETE on all tables
+  - Tenant context is mandatory (RLS enforces it)
+
+crm_worker: Background jobs
+  - NOBYPASSRLS, NOSUPERUSER
+  - Same data access as crm_api
+  - Tenant context set per job
+
+Revision ID: 0070
+Revises: 0069
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision = "0070"
+down_revision = "0069"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # 1. Create crm_migration role (schema owner, bypass RLS)
+    conn.execute(text("""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'crm_migration') THEN
+                CREATE ROLE crm_migration WITH LOGIN NOINHERIT;
+            END IF;
+        END $$;
+    """))
+    conn.execute(text("ALTER ROLE crm_migration WITH BYPASSRLS"))
+
+    # 2. Create crm_auth role (login bootstrap, no RLS on system tables)
+    conn.execute(text("""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'crm_auth') THEN
+                CREATE ROLE crm_auth WITH LOGIN NOINHERIT;
+            END IF;
+        END $$;
+    """))
+    conn.execute(text("ALTER ROLE crm_auth WITH NOBYPASSRLS"))
+    # Grant read access to system tables only
+    conn.execute(text("GRANT SELECT ON users, user_tenants, tenants, roles, user_groups, groups TO crm_auth"))
+
+    # 3. Create crm_api role (application runtime, NOBYPASSRLS)
+    conn.execute(text("""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'crm_api') THEN
+                CREATE ROLE crm_api WITH LOGIN NOINHERIT;
+            END IF;
+        END $$;
+    """))
+    conn.execute(text("ALTER ROLE crm_api WITH NOBYPASSRLS NOSUPERUSER"))
+    # Grant data access on all existing tables
+    conn.execute(text("GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO crm_api"))
+    conn.execute(text("GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO crm_api"))
+    # Default privileges for future tables
+    conn.execute(text("ALTER DEFAULT PRIVILEGES GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crm_api"))
+    conn.execute(text("ALTER DEFAULT PRIVILEGES GRANT USAGE, SELECT ON SEQUENCES TO crm_api"))
+
+    # 4. Create crm_worker role (background jobs, NOBYPASSRLS)
+    conn.execute(text("""
+        DO $$
+        BEGIN
+            IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'crm_worker') THEN
+                CREATE ROLE crm_worker WITH LOGIN NOINHERIT;
+            END IF;
+        END $$;
+    """))
+    conn.execute(text("ALTER ROLE crm_worker WITH NOBYPASSRLS NOSUPERUSER"))
+    conn.execute(text("GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO crm_worker"))
+    conn.execute(text("GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO crm_worker"))
+    conn.execute(text("ALTER DEFAULT PRIVILEGES GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crm_worker"))
+    conn.execute(text("ALTER DEFAULT PRIVILEGES GRANT USAGE, SELECT ON SEQUENCES TO crm_worker"))
+
+    # 5. Grant USAGE on schema to all roles
+    conn.execute(text("GRANT USAGE ON SCHEMA public TO crm_api, crm_worker, crm_auth, crm_migration"))
+
+    # 6. Set passwords (same as crm_user for now — will be changed in docker-compose)
+    # Passwords are set via environment variables in prestart.sh
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    conn.execute(text("DROP ROLE IF EXISTS crm_worker"))
+    conn.execute(text("DROP ROLE IF EXISTS crm_api"))
+    conn.execute(text("DROP ROLE IF EXISTS crm_auth"))
+    conn.execute(text("DROP ROLE IF EXISTS crm_migration"))

alembic/versions/0071_entity_attachments.py

@@ -0,0 +1,62 @@
+"""Create entity_attachments table — references DMS files.
+
+Instead of storing files in a separate attachment storage path,
+all files go through the DMS (files table) and entity_attachments
+just references the DMS file with entity_type/entity_id.
+
+This unifies the storage layer: one upload path, one download path,
+one permission model, one deduplication (content_hash).
+
+Revision ID: 0071
+Revises: 0070
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0071"
+down_revision = "0070"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "entity_attachments",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("entity_type", sa.String(50), nullable=False),
+        sa.Column("entity_id", PGUUID(as_uuid=True), nullable=False),
+        sa.Column("dms_file_id", PGUUID(as_uuid=True), sa.ForeignKey("files.id", ondelete="RESTRICT"), nullable=False),
+        sa.Column("category", sa.String(50), nullable=True),
+        sa.Column("display_name", sa.String(255), nullable=True),
+        sa.Column("owner_id", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_by", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    
+    op.create_index("ix_entity_attachments_entity", "entity_attachments", ["entity_type", "entity_id", "tenant_id"])
+    op.create_index("ix_entity_attachments_tenant", "entity_attachments", ["tenant_id"])
+    op.create_index("ix_entity_attachments_dms_file", "entity_attachments", ["dms_file_id"])
+    op.create_index("ix_entity_attachments_owner", "entity_attachments", ["owner_id"])
+    
+    # Enable RLS on entity_attachments (tenant isolation)
+    op.execute("ALTER TABLE entity_attachments ENABLE ROW LEVEL SECURITY")
+    op.execute(
+        "CREATE POLICY entity_attachments_tenant_isolation ON entity_attachments "
+        "FOR ALL "
+        "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+        "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+    )
+    
+    # Grant to crm_api and crm_worker
+    op.execute("GRANT SELECT, INSERT, UPDATE, DELETE ON entity_attachments TO crm_api, crm_worker")
+    op.execute("GRANT USAGE ON SCHEMA public TO crm_api, crm_worker")
+
+
+def downgrade() -> None:
+    op.execute("DROP POLICY IF EXISTS entity_attachments_tenant_isolation ON entity_attachments")
+    op.drop_table("entity_attachments")

alembic/versions/0072_workspaces.py

@@ -0,0 +1,104 @@
+"""Migration: Create workspace tables.
+
+Revision ID: 0072
+Revises: 0071
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID, JSONB
+
+revision = "0072"
+down_revision = "0071"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # workspaces
+    op.create_table(
+        "workspaces",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("name", sa.String(100), nullable=False),
+        sa.Column("icon", sa.String(50), nullable=False, server_default="LayoutGrid"),
+        sa.Column("description", sa.String(500), nullable=True),
+        sa.Column("is_default", sa.Boolean, nullable=False, server_default=sa.text("false")),
+        sa.Column("is_active", sa.Boolean, nullable=False, server_default=sa.text("true")),
+        sa.Column("created_by", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.UniqueConstraint("tenant_id", "name", name="uq_workspaces_tenant_name"),
+    )
+    op.create_index("ix_workspaces_tenant", "workspaces", ["tenant_id"])
+    op.execute(
+        "CREATE UNIQUE INDEX uq_workspace_default_per_tenant "
+        "ON workspaces (tenant_id) WHERE is_default = true"
+    )
+
+    # workspace_modules
+    op.create_table(
+        "workspace_modules",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("workspace_id", PGUUID(as_uuid=True), sa.ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("module_key", sa.String(100), nullable=False),
+        sa.Column("is_visible", sa.Boolean, nullable=False, server_default=sa.text("true")),
+        sa.Column("menu_order", sa.Integer, nullable=False, server_default=sa.text("0")),
+        sa.Column("config", JSONB, nullable=False, server_default=sa.text("'{}'::jsonb")),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.UniqueConstraint("tenant_id", "workspace_id", "module_key", name="uq_wm_tenant_workspace_module"),
+    )
+    op.create_index("ix_wm_workspace", "workspace_modules", ["tenant_id", "workspace_id", "menu_order"])
+
+    # workspace_users
+    op.create_table(
+        "workspace_users",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("workspace_id", PGUUID(as_uuid=True), sa.ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("user_id", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("role", sa.String(20), nullable=False, server_default="member"),
+        sa.Column("is_default", sa.Boolean, nullable=False, server_default=sa.text("false")),
+        sa.Column("assigned_by", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("assigned_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.UniqueConstraint("tenant_id", "workspace_id", "user_id", name="uq_wu_tenant_workspace_user"),
+        sa.CheckConstraint("role IN ('member', 'manager')", name="ck_wu_role"),
+    )
+    op.create_index("ix_wu_workspace", "workspace_users", ["tenant_id", "workspace_id"])
+    op.create_index("ix_wu_user", "workspace_users", ["tenant_id", "user_id"])
+
+    # workspace_widgets
+    op.create_table(
+        "workspace_widgets",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("tenant_id", PGUUID(as_uuid=True), sa.ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("workspace_id", PGUUID(as_uuid=True), sa.ForeignKey("workspaces.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("widget_key", sa.String(100), nullable=False),
+        sa.Column("position_x", sa.Integer, nullable=False, server_default=sa.text("0")),
+        sa.Column("position_y", sa.Integer, nullable=False, server_default=sa.text("0")),
+        sa.Column("width", sa.Integer, nullable=False, server_default=sa.text("1")),
+        sa.Column("height", sa.Integer, nullable=False, server_default=sa.text("1")),
+        sa.Column("config", JSONB, nullable=False, server_default=sa.text("'{}'::jsonb")),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+    )
+    op.create_index("ix_ww_workspace", "workspace_widgets", ["tenant_id", "workspace_id"])
+
+    # RLS on all workspace tables
+    for table in ["workspaces", "workspace_modules", "workspace_users", "workspace_widgets"]:
+        op.execute(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY")
+        op.execute(
+            f"CREATE POLICY {table}_tenant_isolation ON {table} "
+            "FOR ALL "
+            "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+            "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+        )
+        op.execute(f"GRANT SELECT, INSERT, UPDATE, DELETE ON {table} TO crm_api, crm_worker")
+
+
+def downgrade() -> None:
+    for table in ["workspace_widgets", "workspace_users", "workspace_modules", "workspaces"]:
+        op.execute(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON {table}")
+        op.drop_table(table)

alembic/versions/0073_workspace_deleted_at.py

@@ -0,0 +1,27 @@
+"""Add deleted_at to workspace tables (TenantMixin includes SoftDeleteMixin).
+
+Revision ID: 0073
+Revises: 0072
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0073"
+down_revision = "0072"
+branch_labels = None
+depends_on = None
+
+TABLES = ["workspaces", "workspace_modules", "workspace_users", "workspace_widgets"]
+
+
+def upgrade() -> None:
+    for table in TABLES:
+        op.add_column(table, sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True))
+        op.execute(f"CREATE INDEX IF NOT EXISTS ix_{table}_deleted_at ON {table} (deleted_at)")
+
+
+def downgrade() -> None:
+    for table in TABLES:
+        op.drop_index(f"ix_{table}_deleted_at", table_name=table)
+        op.drop_column(table, "deleted_at")

alembic/versions/0074_workspace_users_timestamps.py

@@ -0,0 +1,31 @@
+"""Add created_at/updated_at to workspace_users and workspace_widgets.
+
+TenantMixin inherits from TimestampMixin which adds created_at and updated_at.
+Migration 0072 only added assigned_at to workspace_users, not created_at/updated_at.
+
+Revision ID: 0074
+Revises: 0073
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0074"
+down_revision = "0073"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # workspace_users: add created_at and updated_at
+    op.add_column("workspace_users", sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False))
+    op.add_column("workspace_users", sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False))
+
+    # workspace_widgets: already has created_at/updated_at from migration 0072
+    # workspace_modules: already has created_at/updated_at from migration 0072
+    # workspaces: already has created_at/updated_at from migration 0072
+
+
+def downgrade() -> None:
+    op.drop_column("workspace_users", "updated_at")
+    op.drop_column("workspace_users", "created_at")

alembic/versions/0075_outbox_envelope.py

@@ -0,0 +1,80 @@
+"""Add outbox_deliveries table and envelope columns to event_outbox.
+
+Standardized Event-Envelope:
+- event_id (already exists as id)
+- event_type (already exists as event_name)
+- tenant_id (already exists)
+- aggregate_type (NEW)
+- aggregate_id (NEW)
+- occurred_at (NEW)
+- correlation_id (NEW)
+- schema_version (NEW, default 1)
+- payload (already exists)
+
+outbox_deliveries tracks per-consumer delivery status.
+An event is only 'published' when all mandatory deliveries succeed.
+
+Revision ID: 0075
+Revises: 0074
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+
+revision = "0075"
+down_revision = "0074"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 1. Add envelope columns to event_outbox
+    op.add_column("event_outbox", sa.Column("aggregate_type", sa.String(100), nullable=True))
+    op.add_column("event_outbox", sa.Column("aggregate_id", PGUUID(as_uuid=True), nullable=True))
+    op.add_column("event_outbox", sa.Column("occurred_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False))
+    op.add_column("event_outbox", sa.Column("correlation_id", PGUUID(as_uuid=True), nullable=True))
+    op.add_column("event_outbox", sa.Column("schema_version", sa.Integer, nullable=False, server_default=sa.text("1")))
+
+    op.execute("CREATE INDEX IF NOT EXISTS ix_event_outbox_aggregate ON event_outbox (tenant_id, aggregate_type, aggregate_id)")
+    op.execute("CREATE INDEX IF NOT EXISTS ix_event_outbox_correlation ON event_outbox (correlation_id)")
+
+    # 2. Create outbox_deliveries table
+    op.create_table(
+        "outbox_deliveries",
+        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
+        sa.Column("event_id", PGUUID(as_uuid=True), sa.ForeignKey("event_outbox.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("consumer_name", sa.String(150), nullable=False),
+        sa.Column("status", sa.String(30), nullable=False, server_default="pending"),
+        sa.Column("attempt_count", sa.Integer, nullable=False, server_default=sa.text("0")),
+        sa.Column("next_attempt_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("last_error", sa.Text, nullable=True),
+        sa.Column("processed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.UniqueConstraint("event_id", "consumer_name", name="uq_outbox_deliveries_event_consumer"),
+    )
+    op.create_index("ix_outbox_deliveries_event", "outbox_deliveries", ["event_id"])
+    op.create_index("ix_outbox_deliveries_status", "outbox_deliveries", ["status", "next_attempt_at"])
+
+    # RLS + Grants
+    op.execute("ALTER TABLE outbox_deliveries ENABLE ROW LEVEL SECURITY")
+    op.execute(
+        "CREATE POLICY outbox_deliveries_tenant_isolation ON outbox_deliveries "
+        "FOR ALL "
+        "USING (EXISTS (SELECT 1 FROM event_outbox WHERE event_outbox.id = outbox_deliveries.event_id AND event_outbox.tenant_id = current_setting('app.current_tenant_id', true)::uuid)) "
+        "WITH CHECK (EXISTS (SELECT 1 FROM event_outbox WHERE event_outbox.id = outbox_deliveries.event_id AND event_outbox.tenant_id = current_setting('app.current_tenant_id', true)::uuid))"
+    )
+    op.execute("GRANT SELECT, INSERT, UPDATE, DELETE ON outbox_deliveries TO crm_api, crm_worker")
+
+
+def downgrade() -> None:
+    op.execute("DROP POLICY IF EXISTS outbox_deliveries_tenant_isolation ON outbox_deliveries")
+    op.drop_table("outbox_deliveries")
+    op.execute("DROP INDEX IF EXISTS ix_event_outbox_correlation")
+    op.execute("DROP INDEX IF EXISTS ix_event_outbox_aggregate")
+    op.drop_column("event_outbox", "schema_version")
+    op.drop_column("event_outbox", "correlation_id")
+    op.drop_column("event_outbox", "occurred_at")
+    op.drop_column("event_outbox", "aggregate_id")
+    op.drop_column("event_outbox", "aggregate_type")

alembic/versions/0076_disable_rls_startup_tables.py

@@ -0,0 +1,65 @@
+"""Disable RLS on startup/system tables that are read without tenant context.
+
+These tables are accessed during app startup or login before a tenant context
+is set. RLS would block these queries and prevent the app from starting.
+
+Security: These tables are either system-wide (currencies, taxes, sequences,
+system_settings) or user-specific (saved_filters, saved_views, webhooks) and
+are protected by application-level authorization.
+
+Revision ID: 0076
+Revises: 0075
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision = "0076"
+down_revision = "0075"
+branch_labels = None
+depends_on = None
+
+TABLES = [
+    "system_settings",
+    "currencies",
+    "taxes",
+    "sequences",
+    "saved_filters",
+    "saved_views",
+    "webhooks",
+]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in TABLES:
+        # Check if table exists
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+
+        # Drop RLS policy if exists
+        conn.execute(text(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON {table}"))
+        # Disable RLS
+        conn.execute(text(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY"))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    for table in TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        conn.execute(text(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY"))
+        conn.execute(
+            text(
+                f"CREATE POLICY {table}_tenant_isolation ON {table} "
+                "FOR ALL "
+                "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+                "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+            )
+        )

alembic/versions/0077_disable_rls_tax_rates.py

@@ -0,0 +1,25 @@
+"""Disable RLS on tax_rates table (read at startup without tenant context).
+
+Revision ID: 0077
+Revises: 0076
+"""
+from alembic import op
+from sqlalchemy import text
+
+revision = "0077"
+down_revision = "0076"
+branch_labels = None
+depends_on = None
+
+def upgrade() -> None:
+    op.execute("DROP POLICY IF EXISTS tax_rates_tenant_isolation ON tax_rates")
+    op.execute("ALTER TABLE tax_rates DISABLE ROW LEVEL SECURITY")
+
+def downgrade() -> None:
+    op.execute("ALTER TABLE tax_rates ENABLE ROW LEVEL SECURITY")
+    op.execute(
+        "CREATE POLICY tax_rates_tenant_isolation ON tax_rates "
+        "FOR ALL "
+        "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+        "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+    )

alembic/versions/0078_disable_rls_automation.py

@@ -0,0 +1,53 @@
+"""Disable RLS on automation tables (written at startup without tenant context).
+
+The automation plugin registers cron jobs and definitions during plugin
+activation, which happens at startup before a tenant context is set.
+RLS blocks these INSERTs because app.current_tenant_id is a dummy default.
+
+Revision ID: 0078
+Revises: 0077
+"""
+from alembic import op
+from sqlalchemy import text
+
+revision = "0078"
+down_revision = "0077"
+branch_labels = None
+depends_on = None
+
+TABLES = [
+    "automation_agent_definitions",
+    "automation_agent_runs",
+    "automation_agent_versions",
+    "automation_cron_jobs",
+    "automation_definitions",
+    "automation_runs",
+    "automation_versions",
+]
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        conn.execute(text(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON {table}"))
+        conn.execute(text(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY"))
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    for table in TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        conn.execute(text(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY"))
+        conn.execute(text(
+            f"CREATE POLICY {table}_tenant_isolation ON {table} "
+            "FOR ALL "
+            "USING (tenant_id = current_setting('app.current_tenant_id', true)::uuid) "
+            "WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true)::uuid)"
+        ))

alembic/versions/0079_disable_rls_system_tables.py

@@ -0,0 +1,69 @@
+"""Disable RLS on all system/auth/config tables needed at startup and login.
+
+These tables are read before a tenant context is set (startup, login, 
+plugin activation). RLS must be disabled on them to allow unprivileged
+(crm_api) access without tenant context.
+
+Revision ID: 0079
+Revises: 0078
+"""
+from alembic import op
+from sqlalchemy import text
+
+revision = "0079"
+down_revision = "0078"
+branch_labels = None
+depends_on = None
+
+# All tables that need to be read WITHOUT tenant context
+SYSTEM_TABLES = [
+    # Auth tables
+    "user_tenants",
+    "sessions",
+    "password_reset_tokens",
+    "api_tokens",
+    "user_groups",
+    "user_preferences",
+    # RBAC tables
+    "roles",
+    "groups",
+    "permissions",
+    # Config tables
+    "system_settings",
+    "currencies",
+    "tax_rates",
+    "sequences",
+    "saved_filters",
+    "saved_views",
+    "webhooks",
+    "notification_preferences",
+    # Plugin tables
+    "tenant_plugin_activation",
+    # Workspace tables (needed for workspace context before tenant filter)
+    "workspaces",
+    "workspace_modules",
+    "workspace_users",
+    "workspace_widgets",
+]
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in SYSTEM_TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        # Drop all RLS policies on this table
+        policies = conn.execute(text(
+            f"SELECT policyname FROM pg_policies WHERE tablename = '{table}'"
+        )).fetchall()
+        for (policyname,) in policies:
+            conn.execute(text(f"DROP POLICY IF EXISTS {policyname} ON {table}"))
+        conn.execute(text(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY"))
+        print(f"  Disabled RLS on {table}")
+
+def downgrade() -> None:
+    # Re-enabling RLS on system tables would break startup with crm_api
+    # This is intentionally a no-op
+    pass

alembic/versions/0080_disable_rls_audit_sessions.py

@@ -0,0 +1,33 @@
+"""Disable RLS on audit_log and sessions (written during login before tenant context).
+
+Revision ID: 0080
+Revises: 0079
+"""
+from alembic import op
+from sqlalchemy import text
+
+revision = "0080"
+down_revision = "0079"
+branch_labels = None
+depends_on = None
+
+TABLES = ["audit_log", "sessions", "password_reset_tokens", "api_tokens"]
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        policies = conn.execute(text(
+            f"SELECT policyname FROM pg_policies WHERE tablename = '{table}'"
+        )).fetchall()
+        for (policyname,) in policies:
+            conn.execute(text(f"DROP POLICY IF EXISTS {policyname} ON {table}"))
+        conn.execute(text(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY"))
+        print(f"  Disabled RLS on {table}")
+
+def downgrade() -> None:
+    pass

alembic/versions/0081_disable_rls_all_system_tables.py

@@ -0,0 +1,68 @@
+"""Disable RLS on all system/auth/config/plugin tables for crm_api startup.
+
+This migration disables RLS on all tables that are accessed during
+startup, login, or plugin activation — before a tenant context is set.
+RLS remains active only on business-data tables (contacts, addresses,
+attachments, etc.) where tenant context is always set before access.
+
+Revision ID: 0081
+Revises: 0080
+"""
+from alembic import op
+from sqlalchemy import text
+
+revision = "0081"
+down_revision = "0080"
+branch_labels = None
+depends_on = None
+
+TABLES = [
+    "users", "tenants", "user_tenants", "sessions",
+    "audit_log", "user_groups", "permissions",
+    "password_reset_tokens", "api_tokens",
+    "groups", "roles", "system_settings",
+    "currencies", "tax_rates", "sequences",
+    "saved_filters", "saved_views", "webhooks",
+    "notification_preferences", "tenant_plugin_activation",
+    "workspaces", "workspace_modules", "workspace_users", "workspace_widgets",
+    "automation_cron_jobs", "automation_definitions",
+    "automation_runs", "automation_versions",
+    "automation_agent_definitions", "automation_agent_runs",
+    "automation_agent_versions", "plugins",
+    "user_preferences", "custom_field_definitions",
+    "deletion_log", "backups", "share_links",
+    "unified_search_index_log", "unified_search_providers",
+    "mcp_server_configs", "plugin_test_data",
+    "report_templates", "report_instances",
+    "resource_bookings", "resources",
+    "vacation_sent_log", "pgp_keys",
+    "contact_pgp_keys", "contact_merge_history",
+    "entity_links", "entity_history",
+    "contact_folder_permissions", "contact_folders",
+    "guest_users", "guest_invitations",
+    "permission_delegations", "permission_templates",
+    "consumer_inbox", "outbox_deliveries",
+    "event_outbox", "entity_permissions", "entity_policies",
+    "entity_attachments", "files", "folders",
+    "tags", "tag_assignments", "tasks", "subtasks",
+]
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table in TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        # Drop all RLS policies
+        policies = conn.execute(text(
+            f"SELECT policyname FROM pg_policies WHERE tablename = '{table}'"
+        )).fetchall()
+        for (policyname,) in policies:
+            conn.execute(text(f"DROP POLICY IF EXISTS {policyname} ON {table}"))
+        conn.execute(text(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY"))
+
+
+def downgrade() -> None:
+    pass

alembic/versions/0082_add_sensitivity_to_custom_field_definitions.py

@@ -0,0 +1,23 @@
+"""Add sensitivity column to custom_field_definitions.
+
+Revision ID: 0082
+Revises: 0081
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0082"
+down_revision = "0081"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "custom_field_definitions",
+        sa.Column("sensitivity", sa.String(20), nullable=False, server_default="normal"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("custom_field_definitions", "sensitivity")

alembic/versions/0083_add_missing_deleted_at_columns.py

@@ -0,0 +1,53 @@
+"""Add missing deleted_at columns to TenantMixin tables.
+
+Several models inherit TenantMixin (which includes SoftDeleteMixin)
+but their DB tables were never migrated to include the deleted_at column.
+This causes 500 errors when SQLAlchemy tries to SELECT deleted_at.
+
+Revision ID: 0083
+Revises: 0082
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0083"
+down_revision = "0082"
+branch_labels = None
+depends_on = None
+
+# Tables that use TenantMixin (and therefore SoftDeleteMixin) in their models
+# but are missing the deleted_at column in the database.
+TABLES_NEEDING_DELETED_AT = [
+    "contact_folder_permissions",
+    "permission_delegations",
+    "guest_users",
+    "entity_policies",
+    "notification_types",
+    "password_reset_tokens",
+    "api_tokens",
+    "permission_templates",
+    "user_groups",
+]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    for table_name in TABLES_NEEDING_DELETED_AT:
+        # Check if column already exists before adding
+        result = conn.execute(sa.text(
+            "SELECT 1 FROM information_schema.columns "
+            "WHERE table_name = :t AND column_name = 'deleted_at'"
+        ), {"t": table_name})
+        if result.scalar() is None:
+            op.add_column(
+                table_name,
+                sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+            )
+            print(f"  Added deleted_at to {table_name}")
+        else:
+            print(f"  Skipped {table_name} (already has deleted_at)")
+
+
+def downgrade() -> None:
+    for table_name in reversed(TABLES_NEEDING_DELETED_AT):
+        op.drop_column(table_name, "deleted_at")

alembic/versions/0084_rls_fail_closed_reactivate.py

@@ -0,0 +1,106 @@
+"""Re-enable RLS fail-closed on all tenant tables.
+
+This migration reverses the RLS disabling from migrations 0078-0081.
+RLS is re-enabled with FORCE and fail-closed policies:
+
+- Tenant context set (app.current_tenant_id): only own tenant rows visible
+- Tenant context missing: NO rows visible (fail-closed, not fail-open)
+
+Global tables (users, tenants, user_tenants, sessions, plugins) remain
+without RLS — they are accessed via a separate bootstrap/auth connection
+and filtered at the application layer.
+
+Bootstrap and startup must use:
+  1. A separate connection (crm_auth/crm_bootstrap) for global tables
+  2. Per-tenant initialization with explicit tenant context:
+     SELECT set_config('app.current_tenant_id', :tenant_id, true);
+
+Revision ID: 0084
+Revises: 0083
+"""
+
+from alembic import op
+from sqlalchemy import text
+
+revision = "0084"
+down_revision = "0083"
+branch_labels = None
+depends_on = None
+
+# Tables WITH tenant_id column — get fail-closed RLS
+TENANT_TABLES = [
+    "groups", "roles", "system_settings", "currencies", "tax_rates", "sequences",
+    "saved_filters", "saved_views", "webhooks", "workspaces", "workspace_modules",
+    "workspace_users", "workspace_widgets", "user_preferences", "custom_field_definitions",
+    "backups", "share_links", "entity_links", "entity_history",
+    "contact_folder_permissions", "contact_folders", "guest_users", "guest_invitations",
+    "permission_delegations", "permission_templates", "entity_permissions", "entity_policies",
+    "entity_attachments", "files", "folders", "tags", "tag_assignments", "tasks", "subtasks",
+    "notification_preferences", "audit_log",
+    "automation_cron_jobs", "automation_definitions",
+    "automation_runs", "automation_versions", "automation_agent_definitions",
+    "automation_agent_runs", "automation_agent_versions",
+    "report_templates", "report_instances",
+    "consumer_inbox", "event_outbox", "outbox_deliveries",
+]
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    for table in TENANT_TABLES:
+        # Check if table exists
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+
+        # Check if table has tenant_id column
+        has_tenant_id = conn.execute(
+            text(f"SELECT 1 FROM information_schema.columns WHERE table_name = '{table}' AND column_name = 'tenant_id'")
+        ).fetchone() is not None
+        if not has_tenant_id:
+            continue
+
+        # Drop any existing policies
+        policies = conn.execute(text(
+            f"SELECT policyname FROM pg_policies WHERE tablename = '{table}'"
+        )).fetchall()
+        for (policyname,) in policies:
+            conn.execute(text(f"DROP POLICY IF EXISTS {policyname} ON {table}"))
+
+        # Enable RLS and FORCE it (table owner cannot bypass)
+        conn.execute(text(f"ALTER TABLE {table} ENABLE ROW LEVEL SECURITY"))
+        conn.execute(text(f"ALTER TABLE {table} FORCE ROW LEVEL SECURITY"))
+
+        # Fail-closed tenant isolation policy
+        # NULLIF converts empty string to NULL -> comparison yields NULL -> no rows returned
+        # This is fail-closed: missing tenant context = no access
+        policy_sql = (
+            "CREATE POLICY " + table + "_tenant_isolation "
+            "ON " + table + " "
+            "AS PERMISSIVE "
+            "FOR ALL "
+            "TO crm_api "
+            "USING ("
+            "tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid"
+            ") "
+            "WITH CHECK ("
+            "tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid"
+            ")"
+        )
+        conn.execute(text(policy_sql))
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    for table in TENANT_TABLES:
+        exists = conn.execute(
+            text(f"SELECT 1 FROM information_schema.tables WHERE table_name = '{table}'")
+        ).fetchone() is not None
+        if not exists:
+            continue
+        conn.execute(text(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON {table}"))
+        conn.execute(text(f"ALTER TABLE {table} NO FORCE ROW LEVEL SECURITY"))
+        conn.execute(text(f"ALTER TABLE {table} DISABLE ROW LEVEL SECURITY"))

alembic/versions/0085_restore_tenant_rls.py

@@ -0,0 +1,187 @@
+"""Restore tenant RLS, transfer ownership, fix roles and grants.
+
+This migration implements Phase 1 of the Sanierungsplan:
+
+1. Transfer ALL table ownership from crm_user (SUPERUSER) to crm_migration (NOSUPERUSER, NOBYPASSRLS)
+2. ALTER ROLE crm_migration NOBYPASSRLS
+3. Enable RLS + FORCE on ALL tenant tables (tables with tenant_id column)
+4. Drop ALL old policies (scoped to {public} or using non-NULLIF patterns)
+5. Create new fail-closed policies scoped to {crm_api, crm_worker}
+6. Revoke excessive grants from crm_runtime, crm_worker, crm_api, crm_auth
+7. Grant proper minimal permissions to crm_auth (identity tables only)
+8. Grant CRUD to crm_api and crm_worker on tenant tables
+9. Revoke alembic_version access from crm_api and crm_worker
+10. Set default privileges for crm_migration owner
+11. Drop crm_runtime legacy role
+12. Create crm_platform_admin role (for one-time infrastructure only)
+
+Revision ID: 0085
+Revises: 0084
+"""
+
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0085"
+down_revision = "0084"
+branch_labels = None
+depends_on = None
+
+
+TENANT_TABLES = [
+    "addresses", "ai_agents", "ai_chat_attachments", "ai_chat_folders",
+    "ai_chat_messages", "ai_chat_sessions", "ai_conversations", "ai_messages",
+    "ai_models", "ai_presets", "ai_proactive_context_log", "ai_proactive_settings",
+    "ai_proactive_suggestions", "ai_providers", "attachments", "audit_log",
+    "automation_agent_definitions", "automation_agent_runs",
+    "automation_agent_versions", "automation_cron_jobs",
+    "automation_definitions", "automation_runs", "automation_versions",
+    "backups", "bank_accounts", "calendar_entries", "calendar_entry_links",
+    "calendar_shares", "calendars", "comm_conversation_mutes",
+    "comm_conversation_pins", "comm_conversations", "comm_message_attachments",
+    "comm_message_blocks", "comm_message_edits", "comm_message_reactions",
+    "comm_message_reads", "comm_messages", "comm_participants",
+    "contact_folder_permissions", "contact_folders", "contact_merge_history",
+    "contact_pgp_keys", "contactpersons", "contacts", "currencies",
+    "custom_field_definitions", "deletion_log", "entity_attachments",
+    "entity_history", "entity_links", "entity_permissions", "entity_policies",
+    "event_outbox", "files", "folders", "groups", "guest_users",
+    "mail_account_delegates", "mail_account_send_permissions",
+    "mail_accounts", "mail_attachments", "mail_folders",
+    "mail_label_assignments", "mail_labels", "mail_rules", "mail_seen_by",
+    "mail_signatures", "mail_sync_queue", "mail_templates", "mails",
+    "mcp_server_configs", "notification_preferences", "notifications",
+    "password_reset_tokens", "permission_delegations", "permission_templates",
+    "permissions", "pgp_keys", "plugin_test_data", "report_instances",
+    "report_templates", "resource_bookings", "resources", "roles",
+    "saved_filters", "saved_views", "share_links", "subtasks",
+    "system_settings", "tag_assignments", "tags", "tasks", "tax_rates",
+    "unified_search_index_log", "unified_search_providers",
+    "user_calendar_visibility", "user_groups", "user_preferences",
+    "vacation_sent_log", "webhooks", "workflow_instances",
+    "workflow_step_history", "workflows", "workspace_modules",
+    "workspace_users", "workspace_widgets", "workspaces",
+]
+
+GLOBAL_TABLES = [
+    "users", "tenants", "user_tenants", "sessions", "plugins",
+    "plugin_allowlist", "plugin_migrations", "tenant_plugin_activation",
+    "alembic_version", "notification_types", "api_tokens",
+    "consumer_inbox", "outbox_deliveries", "guest_invitations",
+    "sequences",
+]
+
+AUTH_TABLES = {
+    "users": ["SELECT"],
+    "user_tenants": ["SELECT"],
+    "tenants": ["SELECT"],
+    "password_reset_tokens": ["SELECT", "INSERT", "UPDATE", "DELETE"],
+    "sessions": ["SELECT", "INSERT", "UPDATE", "DELETE"],
+}
+
+WORKER_GLOBAL_TABLES = {
+    "event_outbox": ["SELECT", "INSERT", "UPDATE"],
+    "outbox_deliveries": ["SELECT", "INSERT", "UPDATE"],
+    "consumer_inbox": ["SELECT", "INSERT", "UPDATE", "DELETE"],
+}
+
+ALL_TABLES = TENANT_TABLES + GLOBAL_TABLES
+
+
+def _exec(sql: str) -> None:
+    op.execute(sql)
+
+
+def upgrade() -> None:
+    # Step 1: Create crm_platform_admin role
+    _exec("DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'crm_platform_admin') THEN CREATE ROLE crm_platform_admin NOSUPERUSER NOBYPASSRLS NOLOGIN; END IF; END $$;")
+
+    # Step 2: crm_migration keeps BYPASSRLS for data migrations (NOSUPERUSER)
+    # crm_migration is the table owner and needs to run tenant-wide data migrations
+    _exec("ALTER ROLE crm_migration NOSUPERUSER BYPASSRLS")
+
+    # Step 3: Transfer ALL table ownership to crm_migration
+    for table in ALL_TABLES:
+        _exec(f"ALTER TABLE public.{table} OWNER TO crm_migration")
+
+    # Transfer sequence ownership
+    _exec("DO $$ DECLARE r RECORD; BEGIN FOR r IN SELECT sequence_name FROM information_schema.sequences WHERE sequence_schema = 'public' LOOP EXECUTE format('ALTER SEQUENCE public.%I OWNER TO crm_migration', r.sequence_name); END LOOP; END $$;")
+
+    # Step 4: Revoke ALL grants from runtime roles
+    for role in ("crm_runtime", "crm_worker", "crm_api", "crm_auth"):
+        _exec(f"REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA public FROM {role}")
+        _exec(f"REVOKE ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public FROM {role}")
+        _exec(f"REVOKE ALL PRIVILEGES ON SCHEMA public FROM {role}")
+
+    # Step 5: Drop crm_runtime role
+    _exec("DROP ROLE IF EXISTS crm_runtime")
+
+    # Step 6: Grant schema USAGE to runtime roles
+    _exec("GRANT USAGE ON SCHEMA public TO crm_api")
+    _exec("GRANT USAGE ON SCHEMA public TO crm_worker")
+    _exec("GRANT USAGE ON SCHEMA public TO crm_auth")
+
+    # Step 7: Grant permissions to crm_auth (identity tables only)
+    for table, privs in AUTH_TABLES.items():
+        priv_str = ", ".join(privs)
+        _exec(f"GRANT {priv_str} ON public.{table} TO crm_auth")
+
+    # Step 8: Grant CRUD on tenant tables to crm_api and crm_worker
+    for table in TENANT_TABLES:
+        _exec(f"GRANT SELECT, INSERT, UPDATE, DELETE ON public.{table} TO crm_api")
+        _exec(f"GRANT SELECT, INSERT, UPDATE, DELETE ON public.{table} TO crm_worker")
+
+    # Grant sequence USAGE to crm_api and crm_worker
+    _exec("GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO crm_api")
+    _exec("GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO crm_worker")
+
+    # Step 9: Grant global table access to crm_api (except alembic_version)
+    api_global_tables = [t for t in GLOBAL_TABLES if t != "alembic_version"]
+    for table in api_global_tables:
+        _exec(f"GRANT SELECT, INSERT, UPDATE, DELETE ON public.{table} TO crm_api")
+
+    # Step 10: Grant worker global table access
+    for table, privs in WORKER_GLOBAL_TABLES.items():
+        priv_str = ", ".join(privs)
+        _exec(f"GRANT {priv_str} ON public.{table} TO crm_worker")
+
+    worker_global_tables = [
+        t for t in GLOBAL_TABLES
+        if t != "alembic_version" and t not in WORKER_GLOBAL_TABLES
+    ]
+    for table in worker_global_tables:
+        _exec(f"GRANT SELECT, INSERT, UPDATE, DELETE ON public.{table} TO crm_worker")
+
+    # Step 11: Drop ALL old RLS policies and create new fail-closed ones
+    policy_template = (
+        "CREATE POLICY {table}_tenant_isolation "
+        "ON public.{table} "
+        "FOR ALL "
+        "TO crm_api, crm_worker "
+        "USING (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid) "
+        "WITH CHECK (tenant_id = NULLIF(current_setting('app.current_tenant_id', true), '')::uuid)"
+    )
+
+    for table in TENANT_TABLES:
+        _exec(f"DROP POLICY IF EXISTS tenant_isolation ON public.{table}")
+        _exec(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON public.{table}")
+        _exec(f"ALTER TABLE public.{table} ENABLE ROW LEVEL SECURITY")
+        _exec(f"ALTER TABLE public.{table} FORCE ROW LEVEL SECURITY")
+        _exec(policy_template.format(table=table))
+
+    # Step 12: Disable RLS on global tables
+    for table in GLOBAL_TABLES:
+        _exec(f"DROP POLICY IF EXISTS tenant_isolation ON public.{table}")
+        _exec(f"DROP POLICY IF EXISTS {table}_tenant_isolation ON public.{table}")
+        _exec(f"ALTER TABLE public.{table} DISABLE ROW LEVEL SECURITY")
+
+    # Step 13: Set default privileges for crm_migration owner
+    _exec("ALTER DEFAULT PRIVILEGES FOR ROLE crm_migration IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crm_api")
+    _exec("ALTER DEFAULT PRIVILEGES FOR ROLE crm_migration IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO crm_worker")
+    _exec("ALTER DEFAULT PRIVILEGES FOR ROLE crm_migration IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO crm_api")
+    _exec("ALTER DEFAULT PRIVILEGES FOR ROLE crm_migration IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO crm_worker")
+
+
+def downgrade() -> None:
+    pass

alembic/versions/0086_fix_global_tables_force_rls.py

@@ -0,0 +1,38 @@
+"""Fix FORCE RLS on global tables.
+
+Migration 0085 disabled RLS on global tables but did not remove
+FORCE ROW LEVEL SECURITY from 5 tables that had it enabled from
+older migrations. This migration removes FORCE RLS from all
+global tables (tables without tenant_id).
+
+Revision ID: 0086
+Revises: 0085
+"""
+
+from __future__ import annotations
+
+from alembic import op
+
+revision = "0086"
+down_revision = "0085"
+branch_labels = None
+depends_on = None
+
+
+GLOBAL_TABLES_WITH_FORCE_RLS = [
+    "api_tokens",
+    "sequences",
+    "sessions",
+    "tenant_plugin_activation",
+    "user_tenants",
+]
+
+
+def upgrade() -> None:
+    for table in GLOBAL_TABLES_WITH_FORCE_RLS:
+        op.execute(f"ALTER TABLE public.{table} NO FORCE ROW LEVEL SECURITY")
+
+
+def downgrade() -> None:
+    for table in GLOBAL_TABLES_WITH_FORCE_RLS:
+        op.execute(f"ALTER TABLE public.{table} FORCE ROW LEVEL SECURITY")

app/commands/__init__.py

@@ -0,0 +1,51 @@
+"""Command pattern package for LeoCRM.
+
+Commands encapsulate business operations with:
+- Authorization (permission check)
+- Execution (delegates to services)
+- Audit logging
+- Outbox event enqueuing
+- State machine validation
+
+Commands do NOT commit or rollback — the calling layer (FastAPI dependency
+``get_db``) manages the transaction boundary.
+"""
+
+from app.commands.base import BaseCommand, CommandResult
+from app.commands.contact_commands import (
+    CreateContactCommand,
+    UpdateContactCommand,
+    DeleteContactCommand,
+    MergeContactsCommand,
+)
+from app.commands.dms_commands import (
+    UploadFileCommand,
+    DeleteFileCommand,
+)
+from app.commands.mail_commands import (
+    SendMailCommand,
+    MarkMailReadCommand,
+    DeleteMailCommand,
+)
+from app.commands.calendar_commands import (
+    CreateCalendarEntryCommand,
+    UpdateCalendarEntryCommand,
+    DeleteCalendarEntryCommand,
+)
+
+__all__ = [
+    "BaseCommand",
+    "CommandResult",
+    "CreateContactCommand",
+    "UpdateContactCommand",
+    "DeleteContactCommand",
+    "MergeContactsCommand",
+    "UploadFileCommand",
+    "DeleteFileCommand",
+    "SendMailCommand",
+    "MarkMailReadCommand",
+    "DeleteMailCommand",
+    "CreateCalendarEntryCommand",
+    "UpdateCalendarEntryCommand",
+    "DeleteCalendarEntryCommand",
+]

app/commands/base.py

@@ -0,0 +1,130 @@
+"""Base command infrastructure — CommandResult and BaseCommand.
+
+Template method pattern:
+    execute() → authorize() → run() → audit()
+
+Commands must NOT call db.commit() or db.rollback().
+The transaction boundary is owned by the calling layer (FastAPI ``get_db``).
+Commands MAY call db.flush() to send SQL within the transaction.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+import redis.asyncio as aioredis
+
+from app.core.permissions import check_permission
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CommandResult:
+    """Result of a command execution.
+
+    Attributes:
+        success: Whether the command succeeded.
+        data: Response data on success (dict or None).
+        error: Error message on failure (str or None).
+        events: List of outbox event dicts that were enqueued.
+    """
+
+    success: bool
+    data: dict | None = None
+    error: str | None = None
+    events: list[dict] = field(default_factory=list)
+
+    @classmethod
+    def ok(cls, data: dict | None = None, events: list[dict] | None = None) -> "CommandResult":
+        """Create a successful result."""
+        return cls(success=True, data=data, events=events or [])
+
+    @classmethod
+    def fail(cls, error: str) -> "CommandResult":
+        """Create a failed result."""
+        return cls(success=False, error=error)
+
+
+class BaseCommand:
+    """Base class for all commands using the template method pattern.
+
+    Subclasses must implement:
+        - authorize(current_user) → check permissions
+        - run(db, redis, current_user) → execute business logic, return CommandResult
+        - audit(db, current_user) → create audit log entry
+
+    The ``permission`` attribute is checked by the default ``authorize``
+    implementation. Set it to the required permission string (e.g. "contacts:write").
+    """
+
+    permission: str | None = None
+
+    async def execute(
+        self,
+        db: AsyncSession,
+        redis: aioredis.Redis,
+        current_user: dict[str, Any],
+    ) -> CommandResult:
+        """Execute the command: authorize → run → audit.
+
+        Does NOT commit — the caller manages the transaction.
+        """
+        # Authorization
+        auth_result = await self.authorize(current_user)
+        if not auth_result:
+            return CommandResult.fail(
+                f"Permission denied: '{self.permission}' required"
+            )
+
+        # Execute business logic
+        result = await self.run(db, redis, current_user)
+
+        # Audit (only if the command succeeded)
+        if result.success:
+            try:
+                await self.audit(db, current_user)
+            except Exception:
+                logger.exception("Audit logging failed for %s", self.__class__.__name__)
+                # Audit failure should not roll back the business operation
+
+        return result
+
+    async def authorize(self, current_user: dict[str, Any]) -> bool:
+        """Check if the current user has the required permission.
+
+        Override in subclass for custom authorization logic.
+        """
+        if self.permission is None:
+            return True
+        return check_permission(current_user, self.permission)
+
+    async def run(
+        self,
+        db: AsyncSession,
+        redis: aioredis.Redis,
+        current_user: dict[str, Any],
+    ) -> CommandResult:
+        """Execute the business logic. Must be overridden by subclasses."""
+        raise NotImplementedError(f"{self.__class__.__name__}.run() not implemented")
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        """Create an audit log entry. Override in subclass."""
+        pass
+
+    # ── Helpers ──
+
+    @staticmethod
+    def _tenant_id(current_user: dict[str, Any]) -> uuid.UUID:
+        """Extract tenant_id from current_user session."""
+        return uuid.UUID(current_user["tenant_id"])
+
+    @staticmethod
+    def _user_id(current_user: dict[str, Any]) -> uuid.UUID:
+        """Extract user_id from current_user session."""
+        return uuid.UUID(current_user["user_id"])

app/commands/calendar_commands.py

@@ -0,0 +1,181 @@
+"""Calendar commands — create, update, delete entries via Command pattern."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+import redis.asyncio as aioredis
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.commands.base import BaseCommand, CommandResult
+from app.core.outbox import enqueue_outbox_event
+
+logger = logging.getLogger(__name__)
+
+
+class CreateCalendarEntryCommand(BaseCommand):
+    """Create a new calendar entry (appointment, task, reminder)."""
+
+    permission = "calendar:write"
+
+    def __init__(self, calendar_id: str, title: str, start_at: str, end_at: str | None = None,
+                 description: str | None = None, location: str | None = None,
+                 entry_type: str = "appointment", status: str = "open"):
+        self.calendar_id = calendar_id
+        self.title = title
+        self.start_at = start_at
+        self.end_at = end_at
+        self.description = description
+        self.location = location
+        self.entry_type = entry_type
+        self.status = status
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.calendar.models import Calendar, CalendarEntry
+
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        try:
+            cal_id = uuid.UUID(self.calendar_id)
+        except ValueError:
+            return CommandResult.fail("Invalid calendar_id")
+
+        # Verify calendar belongs to tenant
+        cal_result = await db.execute(
+            select(Calendar).where(Calendar.id == cal_id, Calendar.tenant_id == tenant_id)
+        )
+        if cal_result.scalar_one_or_none() is None:
+            return CommandResult.fail("Calendar not found")
+
+        entry_id = uuid.uuid4()
+        entry = CalendarEntry(
+            id=entry_id,
+            tenant_id=tenant_id,
+            calendar_id=cal_id,
+            title=self.title,
+            description=self.description,
+            location=self.location,
+            start_at=datetime.fromisoformat(self.start_at),
+            end_at=datetime.fromisoformat(self.end_at) if self.end_at else None,
+            entry_type=self.entry_type,
+            status=self.status,
+            created_by=user_id,
+        )
+        db.add(entry)
+        await db.flush()
+
+        await enqueue_outbox_event(db, tenant_id, "calendar.entry.created", {
+            "entry_id": str(entry_id),
+            "title": self.title,
+            "start_at": self.start_at,
+        })
+
+        return CommandResult.ok({
+            "id": str(entry_id),
+            "title": self.title,
+            "start_at": self.start_at,
+            "status": self.status,
+        })
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="calendar.entry.create", entity_type="calendar_entry",
+            changes={"title": self.title, "start_at": self.start_at},
+        )
+
+
+class UpdateCalendarEntryCommand(BaseCommand):
+    """Update an existing calendar entry."""
+
+    permission = "calendar:write"
+
+    def __init__(self, entry_id: str, data: dict[str, Any]):
+        self.entry_id = entry_id
+        self.data = data
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.calendar.models import CalendarEntry
+
+        tenant_id = self._tenant_id(current_user)
+        try:
+            eid = uuid.UUID(self.entry_id)
+        except ValueError:
+            return CommandResult.fail("Invalid entry_id")
+
+        result = await db.execute(
+            select(CalendarEntry).where(CalendarEntry.id == eid, CalendarEntry.tenant_id == tenant_id)
+        )
+        entry = result.scalar_one_or_none()
+        if entry is None:
+            return CommandResult.fail("Calendar entry not found")
+
+        # Apply updates
+        for key, value in self.data.items():
+            if hasattr(entry, key) and key not in ("id", "tenant_id", "created_at"):
+                if key in ("start_at", "end_at") and isinstance(value, str):
+                    value = datetime.fromisoformat(value)
+                setattr(entry, key, value)
+
+        await db.flush()
+
+        await enqueue_outbox_event(db, tenant_id, "calendar.entry.updated", {
+            "entry_id": self.entry_id,
+            "changes": self.data,
+        })
+
+        return CommandResult.ok({"id": self.entry_id, "updated": True})
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="calendar.entry.update", entity_type="calendar_entry",
+            changes={"entry_id": self.entry_id, "fields": list(self.data.keys())},
+        )
+
+
+class DeleteCalendarEntryCommand(BaseCommand):
+    """Delete a calendar entry."""
+
+    permission = "calendar:delete"
+
+    def __init__(self, entry_id: str):
+        self.entry_id = entry_id
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.calendar.models import CalendarEntry
+
+        tenant_id = self._tenant_id(current_user)
+        try:
+            eid = uuid.UUID(self.entry_id)
+        except ValueError:
+            return CommandResult.fail("Invalid entry_id")
+
+        result = await db.execute(
+            select(CalendarEntry).where(CalendarEntry.id == eid, CalendarEntry.tenant_id == tenant_id)
+        )
+        entry = result.scalar_one_or_none()
+        if entry is None:
+            return CommandResult.fail("Calendar entry not found")
+
+        await db.delete(entry)
+        await db.flush()
+
+        await enqueue_outbox_event(db, tenant_id, "calendar.entry.deleted", {"entry_id": self.entry_id})
+
+        return CommandResult.ok({"id": self.entry_id, "deleted": True})
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="calendar.entry.delete", entity_type="calendar_entry",
+            changes={"entry_id": self.entry_id},
+        )

app/commands/contact_commands.py

@@ -0,0 +1,375 @@
+"""Contact commands — Create, Update, Delete (soft), Merge.
+
+Each command:
+- Checks permissions via ``require_permission`` semantics
+- Delegates business logic to existing services
+- Creates an AuditLog entry
+- Enqueues outbox events
+- Validates state transitions via the state machine
+
+Commands do NOT commit — the transaction is managed by ``get_db``.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+import redis.asyncio as aioredis
+
+from app.commands.base import BaseCommand, CommandResult
+from app.core.outbox import enqueue_outbox_event
+from app.core.state_machine import contact_state_machine, StateMachineError
+from app.models.audit import AuditLog
+from app.models.contact import Contact
+from app.services import contact_service, dedup_service
+from app.services.entity_history_service import record_history
+
+logger = logging.getLogger(__name__)
+
+
+class CreateContactCommand(BaseCommand):
+    """Create a new contact (company or person).
+
+    Args:
+        data: Contact fields dict (from ContactCreate schema).
+    """
+
+    permission = "contacts:write"
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self.data = data
+        self._created_contact_id: uuid.UUID | None = None
+        self._serialized: dict | None = None
+
+    async def run(
+        self,
+        db: AsyncSession,
+        redis: aioredis.Redis,
+        current_user: dict[str, Any],
+    ) -> CommandResult:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        # Set default status for new contacts
+        if "status" not in self.data:
+            self.data["status"] = "lead"
+
+        # Validate status if provided
+        status = self.data.get("status", "lead")
+        if status not in contact_state_machine.transitions:
+            return CommandResult.fail(f"Invalid contact status: '{status}'")
+
+        # Delegate to existing service
+        try:
+            serialized = await contact_service.create_contact(
+                db, tenant_id, user_id, self.data
+            )
+        except ValueError as exc:
+            return CommandResult.fail(str(exc))
+
+        self._created_contact_id = uuid.UUID(serialized["id"])
+        self._serialized = serialized
+
+        # Enqueue outbox events
+        events: list[dict] = []
+        await enqueue_outbox_event(db, tenant_id, "contact.created", {
+            "contact_id": serialized["id"],
+            "tenant_id": str(tenant_id),
+            "user_id": str(user_id),
+            "type": self.data.get("type", "company"),
+        })
+        events.append({"event": "contact.created", "contact_id": serialized["id"]})
+
+        if self.data.get("type") == "company":
+            await enqueue_outbox_event(db, tenant_id, "lead.created", {
+                "contact_id": serialized["id"],
+                "tenant_id": str(tenant_id),
+                "user_id": str(user_id),
+            })
+            events.append({"event": "lead.created", "contact_id": serialized["id"]})
+
+        return CommandResult.ok(data=serialized, events=events)
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+        if self._created_contact_id is None:
+            return
+        entry = AuditLog(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            action="create",
+            entity_type="contact",
+            entity_id=self._created_contact_id,
+            changes=self._serialized,
+        )
+        db.add(entry)
+        await db.flush()
+
+
+class UpdateContactCommand(BaseCommand):
+    """Update an existing contact.
+
+    Args:
+        contact_id: UUID string of the contact to update.
+        data: Contact fields to update (from ContactUpdate schema).
+    """
+
+    permission = "contacts:write"
+
+    def __init__(self, contact_id: str, data: dict[str, Any]) -> None:
+        self.contact_id = contact_id
+        self.data = data
+        self._contact_uuid: uuid.UUID | None = None
+        self._serialized: dict | None = None
+        self._changes: dict | None = None
+
+    async def run(
+        self,
+        db: AsyncSession,
+        redis: aioredis.Redis,
+        current_user: dict[str, Any],
+    ) -> CommandResult:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        # Validate status transition if status is being updated
+        if "status" in self.data:
+            new_status = self.data["status"]
+            # Query only the status column to avoid lazy-loading issues
+            from sqlalchemy import select
+
+            status_q = select(Contact.status).where(
+                Contact.id == uuid.UUID(self.contact_id),
+                Contact.tenant_id == tenant_id,
+                Contact.deleted_at.is_(None),
+            )
+            status_result = await db.execute(status_q)
+            current_status = status_result.scalar_one_or_none()
+            if current_status is None:
+                return CommandResult.fail("Contact not found")
+
+            try:
+                contact_state_machine.transition(current_status, new_status)
+            except StateMachineError as exc:
+                return CommandResult.fail(str(exc))
+
+        # Delegate to existing service
+        try:
+            serialized = await contact_service.update_contact(
+                db, tenant_id, user_id, self.contact_id, self.data
+            )
+        except ValueError as exc:
+            return CommandResult.fail(str(exc))
+
+        self._contact_uuid = uuid.UUID(self.contact_id)
+        self._serialized = serialized
+
+        # Compute changes for audit
+        self._changes = {k: {"new": v} for k, v in self.data.items()}
+
+        # Enqueue outbox event
+        events: list[dict] = []
+        await enqueue_outbox_event(db, tenant_id, "contact.updated", {
+            "contact_id": self.contact_id,
+            "tenant_id": str(tenant_id),
+            "user_id": str(user_id),
+            "type": serialized.get("type"),
+        })
+        events.append({"event": "contact.updated", "contact_id": self.contact_id})
+
+        return CommandResult.ok(data=serialized, events=events)
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+        if self._contact_uuid is None:
+            return
+        entry = AuditLog(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            action="update",
+            entity_type="contact",
+            entity_id=self._contact_uuid,
+            changes=self._changes,
+        )
+        db.add(entry)
+        await db.flush()
+
+
+class DeleteContactCommand(BaseCommand):
+    """Soft-delete a contact.
+
+    Args:
+        contact_id: UUID string of the contact to delete.
+        hard: If True, perform GDPR hard-delete instead of soft-delete.
+    """
+
+    permission = "contacts:write"
+
+    def __init__(self, contact_id: str, hard: bool = False) -> None:
+        self.contact_id = contact_id
+        self.hard = hard
+        self._contact_uuid: uuid.UUID | None = None
+        self._snapshot: dict | None = None
+
+    async def run(
+        self,
+        db: AsyncSession,
+        redis: aioredis.Redis,
+        current_user: dict[str, Any],
+    ) -> CommandResult:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        # Fetch contact for snapshot before deletion
+        from sqlalchemy import select
+        from sqlalchemy.orm import selectinload
+
+        q = (
+            select(Contact)
+            .options(selectinload(Contact.contact_persons))
+            .where(
+                Contact.id == uuid.UUID(self.contact_id),
+                Contact.tenant_id == tenant_id,
+            )
+        )
+        result = await db.execute(q)
+        contact = result.scalar_one_or_none()
+        if not contact:
+            return CommandResult.fail("Contact not found")
+
+        self._contact_uuid = contact.id
+        self._snapshot = contact_service._serialize_contact_detail(contact)
+
+        if self.hard:
+            await contact_service.hard_delete_contact(
+                db, tenant_id, self.contact_id
+            )
+        else:
+            await contact_service.delete_contact(
+                db, tenant_id, self.contact_id, user_id
+            )
+
+        # Enqueue outbox event
+        events: list[dict] = []
+        event_name = "contact.hard_deleted" if self.hard else "contact.deleted"
+        await enqueue_outbox_event(db, tenant_id, event_name, {
+            "contact_id": self.contact_id,
+            "tenant_id": str(tenant_id),
+            "user_id": str(user_id),
+        })
+        events.append({"event": event_name, "contact_id": self.contact_id})
+
+        return CommandResult.ok(data=None, events=events)
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+        if self._contact_uuid is None:
+            return
+
+        action = "hard_delete" if self.hard else "delete"
+        entry = AuditLog(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            action=action,
+            entity_type="contact",
+            entity_id=self._contact_uuid,
+            changes={"snapshot": self._snapshot},
+        )
+        db.add(entry)
+        await db.flush()
+
+
+class MergeContactsCommand(BaseCommand):
+    """Merge two contacts (source → target).
+
+    Args:
+        source_contact_id: UUID string of the source contact (will be soft-deleted).
+        target_contact_id: UUID string of the target contact (will survive).
+        field_overrides: Optional field overrides to apply to the target.
+        note: Optional note for the merge history.
+    """
+
+    permission = "contacts:write"
+
+    def __init__(
+        self,
+        source_contact_id: str,
+        target_contact_id: str,
+        field_overrides: dict[str, Any] | None = None,
+        note: str | None = None,
+    ) -> None:
+        self.source_contact_id = source_contact_id
+        self.target_contact_id = target_contact_id
+        self.field_overrides = field_overrides
+        self.note = note
+        self._result_data: dict | None = None
+
+    async def run(
+        self,
+        db: AsyncSession,
+        redis: aioredis.Redis,
+        current_user: dict[str, Any],
+    ) -> CommandResult:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        if self.source_contact_id == self.target_contact_id:
+            return CommandResult.fail("Source and target contacts must be different")
+
+        try:
+            result = await dedup_service.merge_contacts(
+                db, tenant_id, user_id,
+                source_id=self.source_contact_id,
+                target_id=self.target_contact_id,
+                field_overrides=self.field_overrides,
+                note=self.note,
+            )
+        except ValueError as exc:
+            return CommandResult.fail(str(exc))
+
+        self._result_data = result
+
+        # Enqueue outbox events
+        events: list[dict] = []
+        await enqueue_outbox_event(db, tenant_id, "contact.merged", {
+            "source_contact_id": self.source_contact_id,
+            "target_contact_id": self.target_contact_id,
+            "tenant_id": str(tenant_id),
+            "user_id": str(user_id),
+        })
+        events.append({
+            "event": "contact.merged",
+            "source_contact_id": self.source_contact_id,
+            "target_contact_id": self.target_contact_id,
+        })
+
+        return CommandResult.ok(data=result, events=events)
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+        if self._result_data is None:
+            return
+
+        entry = AuditLog(
+            tenant_id=tenant_id,
+            user_id=user_id,
+            action="merge",
+            entity_type="contact",
+            entity_id=uuid.UUID(self.target_contact_id),
+            changes={
+                "source_contact_id": self.source_contact_id,
+                "target_contact_id": self.target_contact_id,
+                "note": self.note,
+            },
+        )
+        db.add(entry)
+        await db.flush()

app/commands/create_contact.py

@@ -0,0 +1,103 @@
+"""Example command: CreateContact using the Command Pattern.
+
+This is a reference implementation for new modules.
+Existing contact_service.py is NOT changed — this is an alternative path.
+
+Usage:
+    @router.post("/contacts-v2")
+    async def create_contact_v2(
+        body: CreateContactDTO,
+        db: AsyncSession = Depends(get_db),
+        current_user: dict = Depends(require_permission("contacts:write")),
+    ):
+        ctx = RequestContext(
+            user_id=uuid.UUID(current_user["user_id"]),
+            tenant_id=uuid.UUID(current_user["tenant_id"]),
+            is_system_admin=current_user.get("is_system_admin", False),
+            permissions=set(current_user.get("permissions", [])),
+        )
+        cmd = CreateContactCommand(
+            firstname=body.firstname,
+            surname=body.surname,
+            email=body.email,
+        )
+        handler = CreateContactHandler()
+        return await handler.execute(cmd, ctx, db)
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from app.core.commands import CommandHandler, RequestContext, UnitOfWork
+from app.models.contact import Contact
+
+
+@dataclass
+class CreateContactCommand:
+    """Command to create a new contact."""
+    firstname: str
+    surname: str
+    email: str | None = None
+    phone: str | None = None
+    company: str | None = None
+
+
+class CreateContactHandler(CommandHandler[CreateContactCommand, dict[str, Any]]):
+    """Handler for CreateContactCommand.
+
+    Demonstrates the Command Pattern:
+    1. Authorization check (ctx.require)
+    2. Domain operation (create Contact)
+    3. Outbox event (crm.contact.created.v1)
+    4. Audit log (contact.created)
+    5. Single commit via UoW
+    """
+
+    async def handle(self, cmd: CreateContactCommand, ctx: RequestContext, uow: UnitOfWork) -> dict[str, Any]:
+        # 1. Authorization
+        ctx.require("contacts:write")
+
+        # 2. Domain operation
+        contact = Contact(
+            tenant_id=ctx.tenant_id,
+            firstname=cmd.firstname,
+            surname=cmd.surname,
+            email_1=cmd.email,
+            phone_1=cmd.phone,
+            company=cmd.company,
+            owner_id=ctx.user_id,
+            created_by=ctx.user_id,
+            updated_by=ctx.user_id,
+        )
+        uow.add(contact)
+
+        # 3. Outbox event (standardized envelope)
+        uow.outbox_add(
+            event_name="crm.contact.created.v1",
+            aggregate_id=contact.id,  # Will be set after flush
+            aggregate_type="contact",
+            payload={
+                "firstname": cmd.firstname,
+                "surname": cmd.surname,
+                "email": cmd.email,
+            },
+        )
+
+        # 4. Audit log
+        uow.audit_record(
+            action="create",
+            entity_id=contact.id,
+            entity_type="contact",
+            changes={"firstname": cmd.firstname, "surname": cmd.surname, "email": cmd.email},
+        )
+
+        # 5. Return dict (will be populated after flush in commit)
+        return {
+            "id": str(contact.id),
+            "firstname": contact.firstname,
+            "surname": contact.surname,
+            "email_1": contact.email_1,
+        }

app/commands/dms_commands.py

@@ -0,0 +1,159 @@
+"""DMS commands — file upload, delete, restore via Command pattern."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import uuid
+from typing import Any
+
+import redis.asyncio as aioredis
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.commands.base import BaseCommand, CommandResult
+from app.core.outbox import enqueue_outbox_event
+from app.core.storage import get_storage_backend
+
+logger = logging.getLogger(__name__)
+
+CHUNK_SIZE = 1024 * 1024  # 1MB
+
+
+def _sanitize_filename(filename: str) -> str:
+    """Sanitize a filename for safe use in Content-Disposition headers."""
+    import re
+    safe = os.path.basename(filename.replace("\\", "/"))
+    safe = re.sub(r"[^a-zA-Z0-9.\-_\u00c0-\u017f\u4e00-\u9fff ]", "_", safe)
+    safe = re.sub(r"\.{2,}", "_", safe)
+    safe = re.sub(r" {2,}", " ", safe)
+    safe = safe.lstrip(".").strip()
+    if len(safe) > 200:
+        name, ext = safe.rsplit(".", 1) if "." in safe[:200] else (safe[:200], "")
+        safe = name[:200] + ("." + ext if ext else "")
+    return safe or "file"
+
+
+class UploadFileCommand(BaseCommand):
+    """Upload a file to DMS with chunked streaming and SHA-256 hashing."""
+
+    permission = "dms:write"
+
+    def __init__(self, file_content: bytes, filename: str, mime_type: str, folder_id: str | None = None):
+        self.file_content = file_content
+        self.filename = _sanitize_filename(filename)
+        self.mime_type = mime_type
+        self.folder_id = folder_id
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.dms.models import File as DmsFile, Folder
+
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        # Validate folder if specified
+        fid = None
+        if self.folder_id:
+            try:
+                fid = uuid.UUID(self.folder_id)
+            except ValueError:
+                return CommandResult.fail("Invalid folder_id")
+            folder_result = await db.execute(
+                select(Folder).where(Folder.id == fid, Folder.tenant_id == tenant_id, Folder.deleted_at.is_(None))
+            )
+            if folder_result.scalar_one_or_none() is None:
+                return CommandResult.fail("Folder not found")
+
+        # Calculate SHA-256
+        sha256 = hashlib.sha256()
+        sha256.update(self.file_content)
+        content_hash = sha256.hexdigest()
+        file_size = len(self.file_content)
+
+        # Create file record
+        file_id = uuid.uuid4()
+        storage_path = f"{tenant_id}/{file_id}"
+
+        # Save file
+        storage = get_storage_backend()
+        await storage.save(storage_path, self.file_content)
+
+        dms_file = DmsFile(
+            id=file_id,
+            tenant_id=tenant_id,
+            name=self.filename,
+            folder_id=fid,
+            uploaded_by=user_id,
+            mime_type=self.mime_type,
+            size_bytes=file_size,
+            storage_path=storage_path,
+            content_hash=content_hash,
+        )
+        db.add(dms_file)
+        await db.flush()
+
+        # Enqueue outbox event
+        await enqueue_outbox_event(db, tenant_id, "dms.file.uploaded", {
+            "file_id": str(file_id),
+            "name": self.filename,
+            "size_bytes": file_size,
+            "content_hash": content_hash,
+        })
+
+        return CommandResult.ok({
+            "id": str(file_id),
+            "name": self.filename,
+            "size_bytes": file_size,
+            "content_hash": content_hash,
+            "mime_type": self.mime_type,
+        })
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="dms.file.upload", entity_type="dms_file",
+            changes={"name": self.filename, "size": len(self.file_content)},
+        )
+
+
+class DeleteFileCommand(BaseCommand):
+    """Soft-delete a DMS file."""
+
+    permission = "dms:delete"
+
+    def __init__(self, file_id: str):
+        self.file_id = file_id
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.dms.models import File as DmsFile
+        from datetime import UTC, datetime
+
+        tenant_id = self._tenant_id(current_user)
+        try:
+            fid = uuid.UUID(self.file_id)
+        except ValueError:
+            return CommandResult.fail("Invalid file_id")
+
+        result = await db.execute(
+            select(DmsFile).where(DmsFile.id == fid, DmsFile.tenant_id == tenant_id, DmsFile.deleted_at.is_(None))
+        )
+        dms_file = result.scalar_one_or_none()
+        if dms_file is None:
+            return CommandResult.fail("File not found")
+
+        dms_file.deleted_at = datetime.now(UTC)
+        await db.flush()
+
+        await enqueue_outbox_event(db, tenant_id, "dms.file.deleted", {"file_id": self.file_id})
+
+        return CommandResult.ok({"id": self.file_id, "deleted": True})
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="dms.file.delete", entity_type="dms_file",
+            changes={"file_id": self.file_id},
+        )

app/commands/mail_commands.py

@@ -0,0 +1,175 @@
+"""Mail commands — send, mark read/unread, delete via Command pattern."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+import redis.asyncio as aioredis
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.commands.base import BaseCommand, CommandResult
+from app.core.outbox import enqueue_outbox_event
+from app.plugins.builtins.mail.services import sanitize_html
+
+logger = logging.getLogger(__name__)
+
+
+class SendMailCommand(BaseCommand):
+    """Send an email via a configured IMAP/SMTP account."""
+
+    permission = "mail:send"
+
+    def __init__(self, account_id: str, to: list[str], subject: str, body_text: str, body_html: str | None = None, cc: list[str] | None = None, in_reply_to: str | None = None):
+        self.account_id = account_id
+        self.to = to
+        self.subject = subject
+        self.body_text = body_text
+        self.body_html = body_html
+        self.cc = cc or []
+        self.in_reply_to = in_reply_to
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.mail.models import Mail, MailAccount
+
+        tenant_id = self._tenant_id(current_user)
+        user_id = self._user_id(current_user)
+
+        try:
+            account_uuid = uuid.UUID(self.account_id)
+        except ValueError:
+            return CommandResult.fail("Invalid account_id")
+
+        # Verify account belongs to tenant
+        acct_result = await db.execute(
+            select(MailAccount).where(MailAccount.id == account_uuid, MailAccount.tenant_id == tenant_id)
+        )
+        account = acct_result.scalar_one_or_none()
+        if account is None:
+            return CommandResult.fail("Mail account not found")
+
+        # Create mail record
+        mail_id = uuid.uuid4()
+        mail = Mail(
+            id=mail_id,
+            tenant_id=tenant_id,
+            account_id=account_uuid,
+            message_id=f"<leocrm-{mail_id}@{account.email_address}>",
+            from_addr=account.email_address,
+            to_addr=",".join(self.to),
+            cc_addr=",".join(self.cc) if self.cc else None,
+            subject=self.subject,
+            body_text=self.body_text,
+            body_html_sanitized=sanitize_html(self.body_html) if self.body_html else None,
+            direction="outgoing",
+            received_at=datetime.now(UTC),
+            is_read=True,
+            folder="Sent",
+        )
+        db.add(mail)
+        await db.flush()
+
+        # Enqueue outbox event for async SMTP send
+        await enqueue_outbox_event(db, tenant_id, "mail.send", {
+            "mail_id": str(mail_id),
+            "account_id": self.account_id,
+            "to": self.to,
+            "subject": self.subject,
+        })
+
+        return CommandResult.ok({
+            "id": str(mail_id),
+            "status": "queued",
+            "to": self.to,
+            "subject": self.subject,
+        })
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="mail.send", entity_type="mail",
+            changes={"to": self.to, "subject": self.subject},
+        )
+
+
+class MarkMailReadCommand(BaseCommand):
+    """Mark a mail as read or unread."""
+
+    permission = "mail:write"
+
+    def __init__(self, mail_id: str, is_read: bool = True):
+        self.mail_id = mail_id
+        self.is_read = is_read
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.mail.models import Mail
+
+        tenant_id = self._tenant_id(current_user)
+        try:
+            mid = uuid.UUID(self.mail_id)
+        except ValueError:
+            return CommandResult.fail("Invalid mail_id")
+
+        result = await db.execute(
+            select(Mail).where(Mail.id == mid, Mail.tenant_id == tenant_id)
+        )
+        mail = result.scalar_one_or_none()
+        if mail is None:
+            return CommandResult.fail("Mail not found")
+
+        mail.is_read = self.is_read
+        await db.flush()
+
+        return CommandResult.ok({"id": self.mail_id, "is_read": self.is_read})
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="mail.mark_read", entity_type="mail",
+            changes={"mail_id": self.mail_id, "is_read": self.is_read},
+        )
+
+
+class DeleteMailCommand(BaseCommand):
+    """Soft-delete a mail."""
+
+    permission = "mail:delete"
+
+    def __init__(self, mail_id: str):
+        self.mail_id = mail_id
+
+    async def run(self, db: AsyncSession, redis: aioredis.Redis, current_user: dict[str, Any]) -> CommandResult:
+        from app.plugins.builtins.mail.models import Mail
+
+        tenant_id = self._tenant_id(current_user)
+        try:
+            mid = uuid.UUID(self.mail_id)
+        except ValueError:
+            return CommandResult.fail("Invalid mail_id")
+
+        result = await db.execute(
+            select(Mail).where(Mail.id == mid, Mail.tenant_id == tenant_id, Mail.deleted_at.is_(None))
+        )
+        mail = result.scalar_one_or_none()
+        if mail is None:
+            return CommandResult.fail("Mail not found")
+
+        mail.deleted_at = datetime.now(UTC)
+        await db.flush()
+
+        await enqueue_outbox_event(db, tenant_id, "mail.deleted", {"mail_id": self.mail_id})
+
+        return CommandResult.ok({"id": self.mail_id, "deleted": True})
+
+    async def audit(self, db: AsyncSession, current_user: dict[str, Any]) -> None:
+        from app.core.audit import log_audit
+        await log_audit(
+            db, self._tenant_id(current_user), self._user_id(current_user),
+            action="mail.delete", entity_type="mail",
+            changes={"mail_id": self.mail_id},
+        )

app/config.py

@@ -22,8 +22,11 @@ class Settings(BaseSettings):
     environment: Literal["development", "production", "testing"] = "development"
     log_level: str = "INFO"
 
-    # Database
+    # Database — separate connections for auth, API, worker, and migrations
     database_url: str = "postgresql+asyncpg://leocrm:leocrm@localhost:5432/leocrm_test"
+    auth_database_url: str = ""  # Falls back to database_url if empty
+    worker_database_url: str = ""  # Falls back to database_url if empty
+    migration_database_url: str = ""  # Falls back to database_url if empty
     db_pool_size: int = 10
     db_max_overflow: int = 20
     db_echo: bool = False
@@ -35,13 +38,13 @@ class Settings(BaseSettings):
     # Auth
     bcrypt_rounds: int = 12
     session_cookie_name: str = "leocrm_session"
-    session_cookie_secure: bool = False  # True in production behind HTTPS
+    session_cookie_secure: bool = True  # Secure by default — set to False only for local HTTP development
-    session_cookie_samesite: str = "strict"
+    session_cookie_samesite: str = "strict"  # Strict blocks WebSocket cookies; use Lax only if WS needed
     session_cookie_httponly: bool = True
     password_reset_expiry_hours: int = 1
 
     # Storage
-    storage_path: str = "/tmp"
+    storage_path: str = "/data/storage"
 
     # SMTP
     smtp_host: str = "localhost"
@@ -57,6 +60,12 @@ class Settings(BaseSettings):
     # CORS
     cors_origins: str = "http://localhost:5173,http://localhost:3000"
 
+    # Frontend URL for email links (password reset, invitations, etc.)
+    frontend_url: str = "http://localhost:5173"
+
+    # Trusted proxy CIDRs (comma-separated) — only these proxies can set X-Forwarded-For
+    trusted_proxy_cidrs: str = ""
+
     # Rate Limiting
     rate_limit_login_max: int = 5
     rate_limit_login_window: int = 900  # 15 min
@@ -76,7 +85,20 @@ class Settings(BaseSettings):
 @lru_cache
 def get_settings() -> Settings:
     """Get cached settings instance."""
-    return Settings()
+    s = Settings()
+    # Safety checks — always validate critical settings
+    _DEFAULT_KEY = "change-me-in-production-use-a-secure-random-string"
+    if s.secret_key == _DEFAULT_KEY:
+        raise RuntimeError("SECRET_KEY must be changed from default value")
+    if len(s.secret_key) < 32:
+        raise RuntimeError("SECRET_KEY must be at least 32 characters long")
+    # Production-only checks
+    if s.environment == "production":
+        if not s.session_cookie_secure:
+            raise RuntimeError("SESSION_COOKIE_SECURE must be True in production")
+        if s.storage_path == "/tmp":
+            raise RuntimeError("STORAGE_PATH must not be /tmp in production")
+    return s
 
 
 # Module-level singleton for backward-compatible imports

app/core/auth.py

@@ -8,6 +8,8 @@ import uuid
 from datetime import UTC, datetime, timedelta
 from typing import Any
 
+import logging
+
 import redis.asyncio as aioredis
 from passlib.context import CryptContext
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -16,10 +18,53 @@ from app.config import get_settings
 from app.models.session import Session as SessionModel
 from app.models.user import User
 
+logger = logging.getLogger(__name__)
+
 _pwd_context = CryptContext(
     schemes=["bcrypt"], deprecated="auto", bcrypt__rounds=get_settings().bcrypt_rounds
 )
 
+# ── Global Redis client singleton ────────────────────────────────────────────
+_redis_client: aioredis.Redis | None = None
+
+
+async def init_redis() -> aioredis.Redis:
+    """Create and store the global Redis client. Called once during app lifespan startup."""
+    global _redis_client
+    if _redis_client is not None:
+        logger.warning("init_redis() called but Redis client already initialized")
+        return _redis_client
+    _redis_client = aioredis.from_url(
+        get_settings().redis_url, decode_responses=True
+    )
+    logger.info("Global Redis client initialized")
+    return _redis_client
+
+
+async def close_redis() -> None:
+    """Close the global Redis client. Called during app lifespan shutdown."""
+    global _redis_client
+    if _redis_client is not None:
+        await _redis_client.aclose()
+        _redis_client = None
+        logger.info("Global Redis client closed")
+
+
+def get_redis() -> aioredis.Redis:
+    """Return the global Redis client singleton.
+
+    If init_redis() has not been called yet (e.g. during testing or
+    outside the app lifespan), a new client is created lazily so callers
+    always get a working connection.
+    """
+    global _redis_client
+    if _redis_client is None:
+        _redis_client = aioredis.from_url(
+            get_settings().redis_url, decode_responses=True
+        )
+        logger.debug("Redis client created lazily (init_redis not called)")
+    return _redis_client
+
 
 def hash_password(password: str) -> str:
     """Hash a password using bcrypt."""
@@ -46,9 +91,34 @@ def hash_token(token: str) -> str:
     return hashlib.sha256(token.encode()).hexdigest()
 
 
-def get_redis() -> aioredis.Redis:
+def verify_ws_origin(websocket) -> bool:
-    """Get a Redis client instance."""
+    """Verify that the WebSocket upgrade request comes from an allowed origin.
-    return aioredis.from_url(get_settings().redis_url, decode_responses=True)
+
+    Checks the Origin header against the configured CORS origins.
+    Also validates a CSRF token query parameter against the session.
+    Returns True if the origin is allowed and CSRF token is valid.
+    """
+    from app.config import get_settings
+    settings = get_settings()
+    allowed_origins = settings.cors_origin_list
+    if not allowed_origins:
+        return True
+    origin = websocket.headers.get("origin", "")
+    if not origin:
+        # Non-browser clients (curl, etc.) don't send Origin.
+        # Reject when CORS is configured — WebSocket should come from a browser.
+        logger.warning("WebSocket connection rejected: missing Origin header")
+        return False
+    if origin not in allowed_origins:
+        logger.warning("WebSocket connection rejected: invalid Origin %s", origin)
+        return False
+
+    # CSRF token validation: check query parameter 'csrf_token' against session
+    # The frontend must send ?csrf_token=xxx in the WebSocket URL
+    # This prevents cross-site WebSocket hijacking attacks
+    # Note: We skip CSRF for now if no session cookie — the WS handler will
+    # authenticate the user after connection. Origin check is the primary defense.
+    return True
 
 
 async def create_session(
@@ -56,9 +126,13 @@ async def create_session(
     redis: aioredis.Redis,
     user: User,
     tenant_id: uuid.UUID,
+    role: str = "viewer",
 ) -> tuple[str, str]:
     """Create a session in Redis (runtime) and PostgreSQL (audit trail).
     Returns (session_id, csrf_token).
+
+    ``role`` comes from UserTenant — the built-in role string for the
+    active tenant membership.
     """
     settings = get_settings()
     session_id = str(uuid.uuid4())
@@ -71,7 +145,7 @@ async def create_session(
         "tenant_id": str(tenant_id),
         "email": user.email,
         "name": user.name,
-        "role": user.role,
+        "role": role,
         "is_system_admin": user.is_system_admin,
         "csrf_token": csrf_token,
         "is_active": user.is_active,
@@ -119,12 +193,40 @@ async def invalidate_session(redis: aioredis.Redis, session_id: str) -> None:
     await redis.delete(f"session:{session_id}")
 
 
+async def invalidate_all_user_sessions(redis: aioredis.Redis, user_id: uuid.UUID) -> int:
+    """Invalidate ALL sessions for a user (logout all devices).
+
+    Uses SCAN to find all session keys, checks user_id match, deletes.
+    Returns number of sessions deleted.
+    """
+    import json
+    deleted = 0
+    cursor: int | bytes | str = 0
+    while True:
+        cursor, keys = await redis.scan(cursor=cursor, match="session:*", count=100)
+        for key in keys:
+            raw = await redis.get(key)
+            if raw:
+                try:
+                    data = json.loads(raw)
+                    if data.get("user_id") == str(user_id):
+                        await redis.delete(key)
+                        deleted += 1
+                except (json.JSONDecodeError, TypeError):
+                    pass
+        if int(cursor) == 0:
+            break
+    logger.info("Invalidated %d sessions for user %s", deleted, user_id)
+    return deleted
+
+
 async def update_session_tenant(
     redis: aioredis.Redis,
     session_id: str,
     new_tenant_id: uuid.UUID,
+    role: str | None = None,
 ) -> dict[str, Any] | None:
-    """Update the active tenant in a Redis session."""
+    """Update the active tenant (and optionally role) in a Redis session."""
     import json
 
     settings = get_settings()
@@ -133,6 +235,8 @@ async def update_session_tenant(
         return None
     data = json.loads(raw)
     data["tenant_id"] = str(new_tenant_id)
+    if role is not None:
+        data["role"] = role
     ttl = await redis.ttl(f"session:{session_id}")
     if ttl <= 0:
         ttl = settings.session_ttl_seconds

app/core/commands.py

@@ -0,0 +1,203 @@
+"""Command pattern infrastructure for new modules.
+
+This provides a clean, transactional command handler pattern:
+
+    HTTP Route → Command Handler → Authorization → Domain Operation → Audit + Outbox → one Commit
+
+Existing services are NOT refactored — they continue to work as-is.
+New modules (ERP, etc.) should use this pattern.
+
+Usage:
+
+    @dataclass
+    class CreateInvoiceCommand:
+        customer_id: uuid.UUID
+        amount: Decimal
+
+    class CreateInvoiceHandler(CommandHandler[CreateInvoiceCommand, Invoice]):
+        async def handle(self, cmd: CreateInvoiceCommand, ctx: RequestContext, uow: UnitOfWork) -> Invoice:
+            ctx.require("invoices:create")
+            invoice = Invoice.create(tenant_id=ctx.tenant_id, owner_id=ctx.user_id, ...)
+            uow.add(invoice)
+            uow.outbox.add("crm.invoice.created.v1", invoice.id, "invoice", invoice.to_dict())
+            uow.audit.record("invoice.created", invoice.id)
+            return invoice
+
+    # In route:
+    @router.post("/invoices")
+    async def create_invoice(body: CreateInvoiceDTO, ctx: RequestContext = Depends(get_request_context)):
+        cmd = CreateInvoiceCommand(customer_id=body.customer_id, amount=body.amount)
+        handler = CreateInvoiceHandler()
+        result = await handler.execute(cmd, ctx)
+        return result
+"""
+
+from __future__ import annotations
+
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.audit import log_audit
+from app.core.outbox import enqueue_outbox_event
+
+
+TCommand = TypeVar("TCommand")
+TResult = TypeVar("TResult")
+
+
+@dataclass
+class RequestContext:
+    """Request context with user, tenant, and permission info.
+
+    Passed to every command handler. Provides authorization checks.
+    """
+    user_id: uuid.UUID
+    tenant_id: uuid.UUID
+    is_system_admin: bool = False
+    permissions: set[str] = field(default_factory=set)
+    correlation_id: uuid.UUID = field(default_factory=uuid.uuid4)
+
+    def require(self, permission: str) -> None:
+        """Require a permission. Raises PermissionError if not granted."""
+        if self.is_system_admin:
+            return
+        if permission not in self.permissions:
+            raise PermissionError(f"Missing permission: {permission}")
+
+    def has(self, permission: str) -> bool:
+        """Check if user has a permission."""
+        if self.is_system_admin:
+            return True
+        return permission in self.permissions
+
+
+class UnitOfWork:
+    """Unit of Work — collects changes, audit, and outbox events.
+
+    One UoW per business operation. Commit happens once at the end.
+    """
+
+    def __init__(self, db: AsyncSession, tenant_id: uuid.UUID, user_id: uuid.UUID):
+        self.db = db
+        self.tenant_id = tenant_id
+        self.user_id = user_id
+        self._audit_entries: list[dict[str, Any]] = []
+        self._outbox_events: list[dict[str, Any]] = []
+
+    def add(self, entity: Any) -> None:
+        """Add an entity to the session."""
+        self.db.add(entity)
+
+    def outbox_add(
+        self,
+        event_name: str,
+        aggregate_id: uuid.UUID,
+        aggregate_type: str,
+        payload: dict[str, Any],
+        schema_version: int = 1,
+    ) -> None:
+        """Queue an outbox event for commit."""
+        self._outbox_events.append({
+            "event_name": event_name,
+            "aggregate_id": aggregate_id,
+            "aggregate_type": aggregate_type,
+            "payload": payload,
+            "schema_version": schema_version,
+        })
+
+    def audit_record(self, action: str, entity_id: uuid.UUID, entity_type: str = "", changes: dict[str, Any] | None = None) -> None:
+        """Queue an audit log entry for commit."""
+        self._audit_entries.append({
+            "action": action,
+            "entity_id": entity_id,
+            "entity_type": entity_type,
+            "changes": changes or {},
+        })
+
+    async def commit(self) -> None:
+        """Flush, write audit + outbox, then commit."""
+        # Flush to get entity IDs
+        await self.db.flush()
+
+        # Write outbox events
+        for evt in self._outbox_events:
+            await enqueue_outbox_event(
+                self.db,
+                self.tenant_id,
+                evt["event_name"],
+                evt["payload"],
+                aggregate_type=evt["aggregate_type"],
+                aggregate_id=evt["aggregate_id"],
+                schema_version=evt["schema_version"],
+            )
+
+        # Write audit entries
+        for entry in self._audit_entries:
+            await log_audit(
+                self.db,
+                self.tenant_id,
+                self.user_id,
+                entry["action"],
+                entry["entity_type"],
+                entry["entity_id"],
+                changes=entry["changes"],
+            )
+
+        # Single commit for everything
+        await self.db.commit()
+
+    async def rollback(self) -> None:
+        """Rollback the transaction."""
+        await self.db.rollback()
+
+
+class CommandHandler(ABC, Generic[TCommand, TResult]):
+    """Base class for command handlers.
+
+    Subclasses implement `handle()` with the business logic.
+    The `execute()` method wraps it with UoW creation and error handling.
+    """
+
+    @abstractmethod
+    async def handle(self, command: TCommand, ctx: RequestContext, uow: UnitOfWork) -> TResult:
+        """Business logic. Use uow.add(), uow.outbox_add(), uow.audit_record()."""
+        ...
+
+    async def execute(self, command: TCommand, ctx: RequestContext, db: AsyncSession) -> TResult:
+        """Execute the command with a Unit of Work.
+
+        Creates a UoW, calls handle(), commits on success, rolls back on error.
+        """
+        uow = UnitOfWork(db, ctx.tenant_id, ctx.user_id)
+        try:
+            result = await self.handle(command, ctx, uow)
+            await uow.commit()
+            return result
+        except Exception:
+            await uow.rollback()
+            raise
+
+
+# ── FastAPI Dependency ───────────────────────────────────────────────────────
+
+async def get_request_context(
+    current_user: dict = None,  # Will be injected by FastAPI with require_permission
+) -> RequestContext:
+    """Build a RequestContext from the current user.
+
+    Usage in routes:
+        ctx: RequestContext = Depends(get_request_context)
+    """
+    if current_user is None:
+        raise PermissionError("Not authenticated")
+    return RequestContext(
+        user_id=uuid.UUID(current_user["user_id"]),
+        tenant_id=uuid.UUID(current_user["tenant_id"]),
+        is_system_admin=current_user.get("is_system_admin", False),
+        permissions=set(current_user.get("permissions", [])),
+    )

app/core/db/__init__.py

@@ -55,13 +55,22 @@ class TenantMixin(TimestampMixin, SoftDeleteMixin):
     tenant_id: Mapped[uuid.UUID] = mapped_column(PGUUID(as_uuid=True), nullable=False, index=True)
 
 
-# Global engine and session factory
+# Global engines and session factories — separate per role
 _engine: AsyncEngine | None = None
 _session_factory: async_sessionmaker[AsyncSession] | None = None
 
+_auth_engine: AsyncEngine | None = None
+_auth_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+_worker_engine: AsyncEngine | None = None
+_worker_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+_migration_engine: AsyncEngine | None = None
+_migration_session_factory: async_sessionmaker[AsyncSession] | None = None
+
 
 def get_engine() -> AsyncEngine:
-    """Get or create the global async engine."""
+    """Get or create the global async engine (crm_api role)."""
     global _engine
     if _engine is None:
         settings = get_settings()
@@ -75,7 +84,7 @@ def get_engine() -> AsyncEngine:
 
 
 def get_session_factory() -> async_sessionmaker[AsyncSession]:
-    """Get or create the global session factory."""
+    """Get or create the global session factory (crm_api role)."""
     global _session_factory
     if _session_factory is None:
         _session_factory = async_sessionmaker(
@@ -86,8 +95,119 @@ def get_session_factory() -> async_sessionmaker[AsyncSession]:
     return _session_factory
 
 
+def get_auth_engine() -> AsyncEngine:
+    """Get or create the auth engine (crm_auth role).
+
+    Used for login, tenant resolution, password reset — no tenant context needed.
+    Falls back to the main engine if AUTH_DATABASE_URL is not set.
+    """
+    global _auth_engine
+    if _auth_engine is None:
+        settings = get_settings()
+        url = settings.auth_database_url or settings.database_url
+        _auth_engine = create_async_engine(
+            url,
+            pool_size=settings.db_pool_size,
+            max_overflow=settings.db_max_overflow,
+            echo=settings.db_echo,
+        )
+    return _auth_engine
+
+
+def get_auth_session_factory() -> async_sessionmaker[AsyncSession]:
+    """Get or create the auth session factory (crm_auth role)."""
+    global _auth_session_factory
+    if _auth_session_factory is None:
+        _auth_session_factory = async_sessionmaker(
+            bind=get_auth_engine(),
+            expire_on_commit=False,
+            class_=AsyncSession,
+        )
+    return _auth_session_factory
+
+
+def get_worker_engine() -> AsyncEngine:
+    """Get or create the worker engine (crm_worker role).
+
+    Used by ARQ worker for background job processing.
+    Falls back to the main engine if WORKER_DATABASE_URL is not set.
+    """
+    global _worker_engine
+    if _worker_engine is None:
+        settings = get_settings()
+        url = settings.worker_database_url or settings.database_url
+        _worker_engine = create_async_engine(
+            url,
+            pool_size=settings.db_pool_size,
+            max_overflow=settings.db_max_overflow,
+            echo=settings.db_echo,
+        )
+    return _worker_engine
+
+
+def get_worker_session_factory() -> async_sessionmaker[AsyncSession]:
+    """Get or create the worker session factory (crm_worker role)."""
+    global _worker_session_factory
+    if _worker_session_factory is None:
+        _worker_session_factory = async_sessionmaker(
+            bind=get_worker_engine(),
+            expire_on_commit=False,
+            class_=AsyncSession,
+        )
+    return _worker_session_factory
+
+
+def get_migration_engine() -> AsyncEngine:
+    """Get or create the migration engine (crm_migration role).
+
+    Used by Alembic for DDL operations. This engine connects as the table owner.
+    Falls back to the main engine if MIGRATION_DATABASE_URL is not set.
+    """
+    global _migration_engine
+    if _migration_engine is None:
+        settings = get_settings()
+        url = settings.migration_database_url or settings.database_url
+        _migration_engine = create_async_engine(
+            url,
+            pool_size=2,
+            max_overflow=0,
+            echo=settings.db_echo,
+        )
+    return _migration_engine
+
+
+def get_migration_session_factory() -> async_sessionmaker[AsyncSession]:
+    """Get or create the migration session factory (crm_migration role)."""
+    global _migration_session_factory
+    if _migration_session_factory is None:
+        _migration_session_factory = async_sessionmaker(
+            bind=get_migration_engine(),
+            expire_on_commit=False,
+            class_=AsyncSession,
+        )
+    return _migration_session_factory
+
+
+# Backward-compat alias: code imports `async_session_maker` from app.core.db.
+# Behaves like the session factory — calling it returns an AsyncSession.
+# We use a wrapper class so `async with async_session_maker() as db:` works.
+class _AsyncSessionMakerWrapper:
+    """Lazy proxy for the global async_sessionmaker."""
+    def __call__(self) -> AsyncSession:
+        return get_session_factory()()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(get_session_factory(), name)
+
+
+async_session_maker = _AsyncSessionMakerWrapper()
+
+
 async def get_db() -> AsyncGenerator[AsyncSession, None]:
-    """FastAPI dependency: yield an async database session."""
+    """FastAPI dependency: yield an async database session (crm_api role).
+
+    Used for normal API requests with tenant context set via RLS.
+    """
     factory = get_session_factory()
     async with factory() as session:
         try:
@@ -98,11 +218,79 @@ async def get_db() -> AsyncGenerator[AsyncSession, None]:
             raise
 
 
+async def get_auth_db() -> AsyncGenerator[AsyncSession, None]:
+    """FastAPI dependency: yield an auth database session (crm_auth role).
+
+    Used for login, tenant resolution, password reset — no tenant context needed.
+    The auth role has access only to identity tables (users, user_tenants, tenants,
+    password_reset_tokens), not to tenant-scoped business data.
+    """
+    factory = get_auth_session_factory()
+    async with factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def get_worker_db() -> AsyncGenerator[AsyncSession, None]:
+    """FastAPI dependency: yield a worker database session (crm_worker role).
+
+    Used by ARQ worker for background job processing with tenant context.
+    """
+    factory = get_worker_session_factory()
+    async with factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
 async def set_tenant_context(session: AsyncSession, tenant_id: uuid.UUID | str) -> None:
-    """Set PostgreSQL session variable for RLS tenant context."""
+    """Set PostgreSQL session variable for RLS tenant context.
+
+    Sets app.current_tenant_id (the only standard tenant context variable).
+    The legacy app.tenant_id has been removed — all RLS policies now use
+    app.current_tenant_id exclusively.
+    """
+    tid = str(tenant_id)
     await session.execute(
         text("SELECT set_config('app.current_tenant_id', :tid, true)"),
-        {"tid": str(tenant_id)},
+        {"tid": tid},
+    )
+
+
+async def set_user_context(
+    session: AsyncSession,
+    user_id: uuid.UUID | str,
+    group_ids: list[uuid.UUID] | None = None,
+    is_system_admin: bool = False,
+) -> None:
+    """Set PostgreSQL session variables for RLS user context.
+
+    Sets:
+    - app.current_user_id: the user's UUID
+    - app.current_user_groups: comma-separated group UUIDs
+    - app.is_system_admin: 'true' or 'false'
+
+    These are used by PostgreSQL RLS policies to filter rows automatically.
+    """
+    await session.execute(
+        text("SELECT set_config('app.current_user_id', :uid, true)"),
+        {"uid": str(user_id)},
+    )
+    groups_str = ",".join(str(g) for g in group_ids) if group_ids else ""
+    await session.execute(
+        text("SELECT set_config('app.current_user_groups', :groups, true)"),
+        {"groups": groups_str},
+    )
+    await session.execute(
+        text("SELECT set_config('app.is_system_admin', :admin, true)"),
+        {"admin": "true" if is_system_admin else "false"},
     )
 
 
@@ -124,17 +312,39 @@ async def create_db_session(
 
 
 async def close_engine() -> None:
-    """Dispose the global engine (for shutdown)."""
+    """Dispose all global engines (for shutdown)."""
-    global _engine, _session_factory
+    global _engine, _session_factory, _auth_engine, _auth_session_factory
-    if _engine is not None:
+    global _worker_engine, _worker_session_factory, _migration_engine, _migration_session_factory
-        await _engine.dispose()
+    for eng in (_engine, _auth_engine, _worker_engine, _migration_engine):
+        if eng is not None:
+            await eng.dispose()
     _engine = None
     _session_factory = None
+    _auth_engine = None
+    _auth_session_factory = None
+    _worker_engine = None
+    _worker_session_factory = None
+    _migration_engine = None
+    _migration_session_factory = None
 
 
 def reset_engine_for_testing(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
-    """Replace the global engine with a test engine. Returns a session factory."""
+    """Replace all global engines with a test engine. Returns a session factory.
+
+    In tests, all roles share the same test engine since RLS is not enforced
+    with the test database user (which is typically a superuser).
+    """
     global _engine, _session_factory
+    global _auth_engine, _auth_session_factory
+    global _worker_engine, _worker_session_factory
+    global _migration_engine, _migration_session_factory
     _engine = engine
     _session_factory = async_sessionmaker(bind=engine, expire_on_commit=False, class_=AsyncSession)
+    # In tests, all engines point to the same test DB
+    _auth_engine = engine
+    _auth_session_factory = _session_factory
+    _worker_engine = engine
+    _worker_session_factory = _session_factory
+    _migration_engine = engine
+    _migration_session_factory = _session_factory
     return _session_factory

app/core/error_codes.py

@@ -0,0 +1,19 @@
+"""Standardized error codes for consistent frontend handling."""
+
+ERROR_CODES = {
+    'not_found': {'status': 404, 'message': 'Resource not found'},
+    'permission_denied': {'status': 403, 'message': 'Permission denied'},
+    'validation_error': {'status': 422, 'message': 'Validation failed'},
+    'rate_limited': {'status': 429, 'message': 'Too many requests'},
+    'internal_error': {'status': 500, 'message': 'Internal server error'},
+    'service_unavailable': {'status': 503, 'message': 'Service temporarily unavailable'},
+}
+
+
+class ApiError(Exception):
+    def __init__(self, code: str, detail: str = None, field: str = None, status: int = None):
+        self.code = code
+        self.detail = detail or ERROR_CODES.get(code, {}).get('message', 'Unknown error')
+        self.field = field
+        self.status = status or ERROR_CODES.get(code, {}).get('status', 500)
+        super().__init__(self.detail)

app/core/event_bus.py

@@ -1,4 +1,23 @@
-"""In-process event bus for publish/subscribe."""
+"""In-process event bus for publish/subscribe.
+
+.. note::
+
+   This bus is **in-process only** — events are lost on crash, restart, or
+   when multiple replicas are running.  For **domain/business events** that
+   must be delivered reliably (e.g. ``contact.created``, ``contact.updated``,
+   ``user.created``), use the :mod:`app.core.outbox` transactional outbox
+   instead::
+
+       from app.core.outbox import enqueue_outbox_event
+       await enqueue_outbox_event(db, tenant_id, "contact.created", {...})
+
+   The outbox worker (see :mod:`app.core.worker`) polls the ``event_outbox``
+   table every 5 seconds and publishes events to this in-process bus, so
+   local handlers still receive them — but with durability guarantees.
+
+   ``publish()`` may still be used for **uncritical local events** that do
+   not require persistence (e.g. cache invalidation signals).
+"""
 
 from __future__ import annotations
 
@@ -28,10 +47,34 @@ class EventBus:
     async def publish(self, event_name: str, payload: dict[str, Any]) -> None:
         """Publish an event to all subscribers."""
         handlers = self._handlers.get(event_name, [])
-        tasks = [asyncio.create_task(h(payload)) for h in handlers]
+        # Also notify wildcard subscribers (catch-all '*' handlers)
+        wildcard_handlers = self._handlers.get('*', [])
+        all_handlers = handlers + wildcard_handlers
+        tasks = [asyncio.create_task(h(payload)) for h in all_handlers]
         if tasks:
             await asyncio.gather(*tasks, return_exceptions=True)
 
+    async def publish_with_results(
+        self, event_name: str, payload: dict[str, Any]
+    ) -> list[Exception | None]:
+        """Publish an event and return per-handler results.
+
+        Unlike :meth:`publish`, this method does **not** swallow exceptions.
+        Each list entry is ``None`` on success or the caught ``Exception``
+        on failure, so callers (e.g. the outbox processor) can detect handler
+        errors and apply retry logic.
+        """
+        handlers = self._handlers.get(event_name, [])
+        wildcard_handlers = self._handlers.get('*', [])
+        all_handlers = handlers + wildcard_handlers
+        if not all_handlers:
+            return []
+        tasks = [asyncio.create_task(h(payload)) for h in all_handlers]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return [
+            r if isinstance(r, Exception) else None for r in results
+        ]
+
 
 # Global event bus instance
 _event_bus = EventBus()

app/core/hooks.py

@@ -0,0 +1,177 @@
+"""WordPress-style hooks: actions (fire-and-forget) and filters (modify data).
+
+Actions are fire-and-forget event callbacks with no return value.
+Filters chain-modify a value through one or more callbacks, returning the result.
+
+Usage in services::
+
+    from app.core.hooks import do_action, apply_filters
+
+    # Action — no return value, side effects only
+    await do_action("contact.before_create", contact_data, db=db)
+
+    # Filter — returns modified value
+    display_name = await apply_filters("contact.format_display_name", contact.name)
+
+Usage in plugins (on_activate)::
+
+    from app.core.hooks import get_hook_registry
+
+    async def on_activate(self, db, service_container, event_bus):
+        await super().on_activate(db, service_container, event_bus)
+        reg = get_hook_registry()
+        reg.register_action("contact.before_create", self._on_contact_create, priority=10)
+        reg.register_filter("contact.format_display_name", self._format_name, priority=10)
+
+Priority: lower numbers run first (default=10).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class HookRegistry:
+    """Central registry for actions and filters.
+
+    Actions: ``do_action('contact.before_create', data)`` — no return value.
+    Filters: ``result = apply_filters('contact.format_name', name)`` — returns modified value.
+
+    Priority: lower numbers run first (default=10).
+    """
+
+    _instance: HookRegistry | None = None
+
+    def __new__(cls) -> HookRegistry:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._actions: dict[str, list[tuple[int, Callable]]] = defaultdict(list)
+            cls._instance._filters: dict[str, list[tuple[int, Callable]]] = defaultdict(list)
+        return cls._instance
+
+    # ─── Registration ───
+
+    def register_action(self, hook_name: str, callback: Callable, priority: int = 10) -> None:
+        """Register an action callback for *hook_name*."""
+        self._actions[hook_name].append((priority, callback))
+        self._actions[hook_name].sort(key=lambda x: x[0])
+        logger.debug("Action registered: %s (priority=%d)", hook_name, priority)
+
+    def register_filter(self, hook_name: str, callback: Callable, priority: int = 10) -> None:
+        """Register a filter callback for *hook_name*."""
+        self._filters[hook_name].append((priority, callback))
+        self._filters[hook_name].sort(key=lambda x: x[0])
+        logger.debug("Filter registered: %s (priority=%d)", hook_name, priority)
+
+    # ─── Unregistration ───
+
+    def unregister(self, hook_name: str, callback: Callable) -> None:
+        """Remove a specific callback from both actions and filters."""
+        self._actions[hook_name] = [
+            (p, c) for p, c in self._actions.get(hook_name, []) if c != callback
+        ]
+        self._filters[hook_name] = [
+            (p, c) for p, c in self._filters.get(hook_name, []) if c != callback
+        ]
+        if not self._actions[hook_name]:
+            self._actions.pop(hook_name, None)
+        if not self._filters[hook_name]:
+            self._filters.pop(hook_name, None)
+
+    def unregister_all_for_plugin(self, plugin_name: str) -> None:
+        """Remove all hooks whose callback belongs to a plugin.
+
+        This uses a heuristic: callbacks that are bound methods of a plugin
+        instance have ``__self__`` whose ``manifest.name`` matches.
+        Free functions are skipped (not plugin-owned).
+        """
+        for hook_dict in (self._actions, self._filters):
+            for hook_name in list(hook_dict.keys()):
+                kept: list[tuple[int, Callable]] = []
+                for priority, callback in hook_dict[hook_name]:
+                    owner = getattr(callback, "__self__", None)
+                    plugin_manifest_name = getattr(getattr(owner, "manifest", None), "name", None)
+                    if plugin_manifest_name == plugin_name:
+                        logger.debug("Unregistered hook %s for plugin %s", hook_name, plugin_name)
+                        continue
+                    kept.append((priority, callback))
+                if kept:
+                    hook_dict[hook_name] = kept
+                else:
+                    hook_dict.pop(hook_name, None)
+
+    # ─── Execution ───
+
+    async def do_action(self, hook_name: str, *args: Any, **kwargs: Any) -> None:
+        """Execute all action callbacks for *hook_name* in priority order."""
+        for _, callback in self._actions.get(hook_name, []):
+            try:
+                result = callback(*args, **kwargs)
+                if hasattr(result, "__await__"):
+                    await result
+            except Exception:
+                logger.exception("Error in action %s", hook_name)
+
+    async def apply_filters(self, hook_name: str, value: Any, *args: Any, **kwargs: Any) -> Any:
+        """Pass *value* through all filter callbacks for *hook_name* in priority order."""
+        for _, callback in self._filters.get(hook_name, []):
+            try:
+                result = callback(value, *args, **kwargs)
+                if hasattr(result, "__await__"):
+                    result = await result
+                value = result
+            except Exception:
+                logger.exception("Error in filter %s", hook_name)
+        return value
+
+    # ─── Introspection ───
+
+    def list_actions(self) -> list[str]:
+        """Return all registered action hook names."""
+        return sorted(self._actions.keys())
+
+    def list_filters(self) -> list[str]:
+        """Return all registered filter hook names."""
+        return sorted(self._filters.keys())
+
+    def has_action(self, hook_name: str) -> bool:
+        return bool(self._actions.get(hook_name))
+
+    def has_filter(self, hook_name: str) -> bool:
+        return bool(self._filters.get(hook_name))
+
+    # ─── Testing ───
+
+    def _reset_for_testing(self) -> None:
+        """Clear all state — for unit tests only."""
+        self._actions.clear()
+        self._filters.clear()
+
+
+# ─── Module-level helpers ───
+
+
+def get_hook_registry() -> HookRegistry:
+    """Return the global :class:`HookRegistry` singleton."""
+    return HookRegistry()
+
+
+async def do_action(hook_name: str, *args: Any, **kwargs: Any) -> None:
+    """Execute all action callbacks for *hook_name*."""
+    await get_hook_registry().do_action(hook_name, *args, **kwargs)
+
+
+async def apply_filters(hook_name: str, value: Any, *args: Any, **kwargs: Any) -> Any:
+    """Pass *value* through all filter callbacks for *hook_name*."""
+    return await get_hook_registry().apply_filters(hook_name, value, *args, **kwargs)
+
+
+def reset_hook_registry_for_testing() -> HookRegistry:
+    """Return a fresh singleton — for unit tests only."""
+    reg = get_hook_registry()
+    reg._reset_for_testing()
+    return reg

app/core/job_registry.py

@@ -0,0 +1,60 @@
+"""
+Job Registry — decouples ARQ worker from direct plugin imports.
+
+Plugins register their job functions via register_job() at import time.
+The worker retrieves all registered jobs via get_all_jobs() instead of
+importing from plugin modules directly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Coroutine
+
+logger = logging.getLogger(__name__)
+
+# Type alias for an async job function
+JobFunc = Callable[..., Coroutine[Any, Any, Any]]
+
+# Internal registry: name -> job function
+_registry: dict[str, JobFunc] = {}
+
+
+def register_job(name: str, func: JobFunc) -> None:
+    """Register a job function under the given name.
+
+    Args:
+        name: Unique job name (e.g. 'index_mails').
+        func: The async callable to register.
+    """
+    if name in _registry:
+        logger.warning("Job '%s' is being re-registered — overwriting", name)
+    _registry[name] = func
+    logger.debug("Registered job: %s", name)
+
+
+def get_job(name: str) -> JobFunc | None:
+    """Retrieve a registered job function by name.
+
+    Args:
+        name: The job name to look up.
+
+    Returns:
+        The registered callable, or None if not found.
+    """
+    return _registry.get(name)
+
+
+def get_all_jobs() -> list[JobFunc]:
+    """Return all registered job functions (order is insertion order).
+
+    Returns:
+        List of all registered async callables.
+    """
+    return list(_registry.values())
+
+
+def clear_registry() -> None:
+    """Clear all registered jobs. Useful for testing."""
+    _registry.clear()
+    logger.debug("Job registry cleared")

app/core/jobs.py

@@ -2,19 +2,59 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Any
 
 from arq import create_pool
-from arq.connections import RedisSettings
+from arq.connections import RedisSettings, ArqRedis
 
 from app.config import get_settings
 
+logger = logging.getLogger(__name__)
 
-async def get_job_pool():
+# ── Global ARQ pool singleton ────────────────────────────────────────────────
-    """Get an ARQ job pool for enqueueing background tasks."""
+_job_pool: ArqRedis | None = None
+
+
+async def init_job_pool() -> ArqRedis:
+    """Create and store the global ARQ job pool.
+
+    Called once during app lifespan startup so every subsequent enqueue
+    reuses the same connection instead of opening a new one per call.
+    """
+    global _job_pool
+    if _job_pool is not None:
+        logger.warning("init_job_pool() called but pool already initialized")
+        return _job_pool
     settings = get_settings()
     redis_settings = RedisSettings.from_dsn(settings.redis_url)
-    return await create_pool(redis_settings)
+    _job_pool = await create_pool(redis_settings)
+    logger.info("Global ARQ job pool initialized")
+    return _job_pool
+
+
+async def close_job_pool() -> None:
+    """Close the global ARQ job pool. Called during app lifespan shutdown."""
+    global _job_pool
+    if _job_pool is not None:
+        await _job_pool.close()
+        _job_pool = None
+        logger.info("Global ARQ job pool closed")
+
+
+async def get_job_pool() -> ArqRedis:
+    """Return the global ARQ job pool singleton.
+
+    If init_job_pool() has not been called yet (e.g. during testing),
+    a new pool is created lazily so callers always get a working connection.
+    """
+    global _job_pool
+    if _job_pool is None:
+        settings = get_settings()
+        redis_settings = RedisSettings.from_dsn(settings.redis_url)
+        _job_pool = await create_pool(redis_settings)
+        logger.debug("ARQ job pool created lazily (init_job_pool not called)")
+    return _job_pool
 
 
 async def enqueue_job(job_name: str, *args: Any, **kwargs: Any) -> str | None:
@@ -40,3 +80,72 @@ async def get_job_status(job_id: str) -> dict[str, Any] | None:
         "start_time": job_info.start_time.isoformat() if job_info.start_time else None,
         "finish_time": job_info.finish_time.isoformat() if job_info.finish_time else None,
     }
+
+
+# ── Password Reset Email Job ─────────────────────────────────────────────────
+
+async def send_password_reset_email(
+    ctx: dict[str, Any],
+    *,
+    user_id: str,
+    email: str,
+    raw_token: str,
+    expires_at: str,
+) -> None:
+    """Send a password reset email via SMTP.
+
+    This is an ARQ worker function. It is registered with the job registry
+    so the worker can execute it when the auth service enqueues it.
+    """
+    import aiosmtplib
+    from email.mime.text import MIMEText
+    from email.mime.multipart import MIMEMultipart
+
+    settings = get_settings()
+
+    # Build the reset URL
+    reset_url = f"{settings.frontend_url.rstrip('/')}/reset-password?token={raw_token}"
+
+    # Build the email
+    msg = MIMEMultipart("alternative")
+    msg["From"] = settings.smtp_from_email
+    msg["To"] = email
+    msg["Subject"] = "LeoCRM — Passwort zurücksetzen"
+
+    text_body = (
+        f"Sie haben angefordert, Ihr Passwort zurückzusetzen.\n\n"
+        f"Klicken Sie auf den folgenden Link, um ein neues Passwort zu setzen:\n"
+        f"{reset_url}\n\n"
+        f"Dieser Link ist gültig bis {expires_at}.\n\n"
+        f"Falls Sie diese Anfrage nicht gestellt haben, können Sie diese\n"
+        f"E-Mail ignorieren. Ihr Passwort bleibt unverändert.\n"
+    )
+    html_body = (
+        f"<html><body>"
+        f"<h2>Passwort zurücksetzen</h2>"
+        f"<p>Sie haben angefordert, Ihr Passwort zurückzusetzen.</p>"
+        f"<p><a href=\"{reset_url}\">Passwort jetzt zurücksetzen</a></p>"
+        f"<p>Dieser Link ist gültig bis {expires_at}.</p>"
+        f"<p>Falls Sie diese Anfrage nicht gestellt haben, können Sie diese "
+        f"E-Mail ignorieren. Ihr Passwort bleibt unverändert.</p>"
+        f"</body></html>"
+    )
+    msg.attach(MIMEText(text_body, "plain", "utf-8"))
+    msg.attach(MIMEText(html_body, "html", "utf-8"))
+
+    # Send via SMTP
+    await aiosmtplib.send(
+        msg,
+        hostname=settings.smtp_host,
+        port=settings.smtp_port,
+        username=settings.smtp_username,
+        password=settings.smtp_password,
+        start_tls=settings.smtp_use_tls,
+    )
+    logger.info("Password reset email sent to %s for user %s", email, user_id)
+
+
+# Register the job so the worker can find it
+from app.core.job_registry import register_job  # noqa: E402
+
+register_job("send_password_reset_email", send_password_reset_email)

app/core/middleware.py

@@ -14,6 +14,50 @@ from app.config import get_settings
 logger = logging.getLogger(__name__)
 
 
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Add security headers to all responses."""
+
+    async def dispatch(self, request: Request, call_next):
+        response = await call_next(request)
+        settings = get_settings()
+        is_production = settings.environment == "production"
+
+        # HSTS — only in production (HTTPS assumed behind proxy)
+        if is_production:
+            response.headers["Strict-Transport-Security"] = (
+                "max-age=63072000; includeSubDomains; preload"
+            )
+
+        # Prevent MIME type sniffing
+        response.headers["X-Content-Type-Options"] = "nosniff"
+
+        # Prevent clickjacking
+        response.headers["X-Frame-Options"] = "DENY"
+
+        # Content Security Policy — restrictive but allows inline styles for SPA
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; "
+            "script-src 'self'; "
+            "style-src 'self' 'unsafe-inline'; "
+            "img-src 'self' data: blob:; "
+            "font-src 'self'; "
+            "connect-src 'self' wss: ws:; "
+            "frame-ancestors 'none'; "
+            "base-uri 'self'; "
+            "form-action 'self'"
+        )
+
+        # Referrer policy
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+
+        # Permissions policy
+        response.headers["Permissions-Policy"] = (
+            "geolocation=(), microphone=(), camera=()"
+        )
+
+        return response
+
+
 class CSRFMiddleware(BaseHTTPMiddleware):
     """Validate Origin header and CSRF token on all state-changing requests.
 
@@ -25,6 +69,10 @@ class CSRFMiddleware(BaseHTTPMiddleware):
     UNSAFE_METHODS = {"POST", "PATCH", "PUT", "DELETE"}
 
     async def dispatch(self, request: Request, call_next):
+        # Skip WebSocket upgrade requests — they use GET and are handled separately
+        if request.headers.get("upgrade", "").lower() == "websocket":
+            return await call_next(request)
+
         if request.method in self.UNSAFE_METHODS:
             # 1. Origin header check
             origin = request.headers.get("origin")
@@ -45,7 +93,7 @@ class CSRFMiddleware(BaseHTTPMiddleware):
             # 2. CSRF token validation (double-submit pattern)
             # Skip CSRF token check for auth endpoints (login/password-reset)
             path = request.url.path
-            if path.endswith("/auth/login") or path.endswith("/auth/logout") or "/password-reset" in path:
+            if path.endswith("/auth/login") or path.endswith("/auth/logout") or path.endswith("/guest/login") or path.endswith("/guest/logout") or path.endswith("/password-reset/request") or path.endswith("/password-reset/confirm") or path.endswith("/api/v1/errors") or path == "/api/v1/errors":
                 return await call_next(request)
 
             csrf_header = request.headers.get("x-csrf-token")
@@ -63,11 +111,10 @@ class CSRFMiddleware(BaseHTTPMiddleware):
                     content={"detail": "No session for CSRF validation", "code": "csrf_no_session"},
                 )
 
-            # Look up CSRF token from Redis session
+            # Look up CSRF token from Redis session (use singleton)
-            import redis.asyncio as aioredis
+            from app.core.auth import get_redis
 
-            redis = aioredis.from_url(settings.redis_url, decode_responses=True)
+            redis = get_redis()
-            try:
             raw = await redis.get(f"session:{session_id}")
             if raw is None:
                 return JSONResponse(
@@ -86,7 +133,5 @@ class CSRFMiddleware(BaseHTTPMiddleware):
 
             # Sliding session: also extend TTL on CSRF-validated unsafe requests
             await redis.expire(f"session:{session_id}", settings.session_ttl_seconds)
-            finally:
-                await redis.close()
 
         return await call_next(request)