as4-411/docs/adr/003-multi-tenancy-and-rls.md

ADR-003: Multi-Tenancy and RLS Strategy

Status

Accepted.

Context

Tenant scoping is required for isolation. Shared (global) data (e.g. BIC, LEI) and tenant-private data must be clearly separated, and access enforced at the database and application layer.

Decision

Model

• Global objects: Identifiers or metadata that are public or shared (e.g. BIC, LEI, BIN range metadata). Stored with tenant_id null or a dedicated global tenant. Readable by all tenants for resolution when the identifier is public.
• Tenant-private objects: All participant-specific data, contractual endpoints, MID/TID, and tenant-specific routing artifacts. Must be scoped by tenant_id; only the owning tenant can read/write.

Enforcement

• Postgres Row Level Security (RLS): Enable on tenant-scoped tables. Policy: restrict to rows where tenant_id matches the session/connection tenant (set after auth). Allow read of global rows (tenant_id IS NULL) where applicable.
• Application: Resolver and Admin API set tenant context from JWT or request; all queries filter by tenant. No cross-tenant data in responses.
• Per-tenant encryption: For confidential data (Tier 2+), use per-tenant keys so compromise is isolated (see ADR-004).

Caching

• Cache key includes tenant. Per-tenant TTL and invalidation optional.

Consequences

• Tenants cannot see each other's private data. Global data remains available for public identifier resolution. RLS provides defense in depth alongside application checks.