Row-Level Security & Tenant Isolation

The isolation problem

A multi-tenant platform stores many customers' data in shared infrastructure. The central security question is unforgiving: "Can tenant A ever see or modify tenant B's data?" Every affirmative answer is a reportable breach.

The conventional answer is to filter every query in application code — WHERE tenant_id = :current — added by hand or by an ORM scope. That works until the one place it is forgotten: a new endpoint, a background job, a raw report, an ORM method that bypasses the default scope, an injection flaw that strips the clause. A single missed filter is a cross-tenant leak, and the filter lives in exactly the layer that changes most and is written by the most people.

Row-Level Security (RLS) moves the boundary down a layer — into the database, below all application code. The rule that a query may only touch the current tenant's rows becomes a property of the table, enforced by PostgreSQL on every statement, regardless of what the application above it does or forgets to do. It converts "we always remember to filter" into "the database refuses to return anything else."

Three tenancy models — where Versus sits

The industry describes a spectrum, trading isolation strength against cost and density:

What Row-Level Security actually is

RLS is a native PostgreSQL feature (equivalent capabilities exist in Microsoft SQL Server, Oracle VPD, and others). Once enabled on a table, every SELECT, INSERT, UPDATE, andDELETE is transparently constrained by a policy — a boolean expression the database evaluates per row. A policy has two independent predicates:

• USING — the visibility predicate. Rows for which it is false simply do not exist for the query; they cannot be read, updated, or deleted.
• WITH CHECK — the write predicate. An insert or update whose values fail it errors. This is what stops a tenant from writing a row into another tenant.

The predicate reads "who am I" from a session variable the application sets at the start of each transaction — the canonical multi-tenant shape.

How Versus implements it

Versus enforces tenant isolation in two independent layers: a database policy that cannot be bypassed from application code, and a per-request mechanism that establishes who the caller is from a signed token — never from client input.

Layer one — the database policy (forced, fail-closed)

Every tenant-scoped table carries a tenant_id column and a uniform policy: enable and FORCE ROW LEVEL SECURITY, then a tenant_isolation policy whose USING and WITH CHECK predicates compare tenant_id against the session's tenant setting. Two deliberate choices make it fail-closed:

• FORCE is mandatory. The application's own database role is subject to the policy — it cannot read around it. Only a superuser or BYPASSRLS role is exempt, and the application never connects as one.
• The session lookup has no "missing OK" flag. If a query reaches a protected table without the tenant context set for that transaction, PostgreSQL raises an error and the query fails. There is no "context unset ⇒ see everything" path — an unscoped query on a scoped table is a hard failure, surfaced immediately rather than leaking.

Layer two — tenant context from a signed claim

Before any tenant-scoped query runs, Versus establishes the caller's tenant for the current transaction. The identity is taken from the authenticated token's tenant_id claim — minted and signed server-side at login — and applied with a transaction-local setting.

• The tenant is never client-supplied. It is not a URL parameter, header, or body field. It comes from the cryptographically signed session token, so a user cannot ask to act as another tenant by editing a request.
• The setting is transaction-scoped. It exists only for the current transaction and is discarded on commit or rollback — it cannot leak into the next request that reuses the same pooled connection.
• The scope wraps the whole request. Context is established after authentication and torn down when the response is finalized, so every query the view issues — including ones a developer forgot to filter — is covered.

The write path — server-side stamping + WITH CHECK

A database trigger stamps a new row's tenant_id from the session context when it is left empty, so application code never has to supply it and cannot get it wrong. Because the same policy's WITH CHECK runs on every insert and update, a caller cannot write a row bearing another tenant's id — the database rejects it. Reads and writes are governed by one predicate, so they cannot drift apart.

Threat model & the guarantees it makes

Residual risks & how they're controlled

• Privileged connections bypass RLS by design. Superuser / BYPASSRLS roles are exempt — a PostgreSQL invariant. The mitigation is architectural: tenant user traffic never flows over such a role; administrative operations use a separate connection with their own authorization and audit.
• Connection pooling. Versus uses transaction-scoped settings (cleared at transaction end) rather than session-level settings that would persist and could bleed between tenants.
• Unstamped rows. A row written with no tenant context is invisible to tenant users (the safe direction) rather than visible to the wrong one; background writers establish the tenant context or stamp explicitly so data surfaces for its owner.
• Policy drift. Every table's policy is generated from one shared definition, so the predicate shape cannot vary table to table.
• Proven, not assumed. An automated conformance suite asserts that a query under tenant A cannot read or write tenant B, that the missing-context case fails closed, and that FORCE holds against the app role — as regression tests, so a change that weakened isolation breaks the build.

How major SaaS platforms use the same idea

Row-scoped isolation is the mainstream approach to pooled multi-tenancy — a well-trodden, auditable pattern, not an in-house invention.

The consistent thread: a tenant discriminator on every row, an identity taken from a trusted server-side context, and a predicate applied beneath application code. Versus's implementation is a faithful, forced, fail-closed instance of this consensus pattern on PostgreSQL.

Evaluator's checklist