ADR-0001: Multi-Tenant Isolation

Status: Accepted
Date: 2025-12-29

Context

• Platform serves multiple tenants (organizations) - currently SAMA, future: VFS Global, Allied Shielding
• Every database table with user data must include tenant_id for isolation
• Risk of cross-tenant data leakage if queries omit tenant filter

Decision

1. Tenant resolution via resolveTenantSecure() at server/routes.ts:107-159

2. Security rules at lines 90-98:

   • Session tenant is primary source
   • Query param override requires SUPER_ADMIN_MODE=true AND SUPER_ADMIN role
   • No silent fallbacks - missing tenant = 400/403

3. requireTenant() helper at server/routes.ts:161 enforces tenant presence

4. Every query must include tenant_id filter (verified in vector store: server/lib/vectorStore.ts:75)

5. Default tenant "sama" seeded at server/storage.ts:423-431

Alternatives Considered

1. Row-level security in PostgreSQL - Rejected: complexity, harder to debug
2. Separate databases per tenant - Rejected: operational overhead, cost

Consequences

• All new tables must include tenantId column with index
• All queries must filter by tenantId
• Cross-tenant access blocked at API layer with 403