Supabase's shared responsibility model says the same. It asks customers to "always apply Row Level Security (RLS)" and leaves the access rules on sensitive tables to them.
On the hosted platform, Supabase encrypts data at rest and in transit, signs the BAA and checks project settings. Its HIPAA guide asks for Point in Time Recovery, SSL enforcement, network restrictions and Postgres connection logging to be turned on, and for MFA on every account with access to the project. The Security Advisor raises a warning if any of these is switched off.
The advisor and the database linter also flag some risky patterns, such as a table in public with RLS turned off. Neither of them runs the policies, so neither can say whether a nurse at one clinic is able to read visits from another, or whether a deleted record left a trace in the audit table.
A HIPAA review asks three questions about the database.
These map onto the Security Rule. Access control falls under 164.312(a)(1), which requires that access go "only to those persons or software programs that have been granted access rights". Audit controls fall under 164.312(b). Integrity, under 164.312(c)(1), concerns protecting PHI "from improper alteration or destruction". 164.312(d) covers authentication, and 164.308(a)(8) requires all of this to be evaluated periodically and whenever the environment changes.
On Supabase, almost all of this lives in SQL written by the project team. A screenshot of the policies cannot show what the database actually does when authenticated calls one of those functions.
UnitAutogen covers this part with the unitautogen hipaa command, run from the project folder while the local stack is up.
supabase start
unitautogen --supabase hipaa --schema publicIt connects to the local database reported by supabase status. That database is built from the migrations, so no patient data is involved at any point. The tool generates the tests and the rows they need, runs them and rolls the rows back. The report is written to supabase/tests/seccover/hipaa/public/, and the security tests it generates go into supabase/tests/seccover/security/, where supabase test db picks them up.
PHI tables are identified from the schema. Where the tool gets one wrong, the correction goes in a unitautogen.toml file in the project folder. Every entry taken from that file is labelled in the report, so a declaration is never read as a finding.
[phi]
tables = ["public.patients", "public.visits"]
not = ["public.countries"]
[audit]
tables = ["audit.change_log"]Access. Functions, views and triggers that run as their owner bypass row policies. Each one is called as two different tenants, with data present on both sides, and reported as holding or leaking, along with the table, command and role. Row policies, column grants and personal data that escapes through error messages are covered as well.
The audit log. For every PHI table, and for each of insert, update and delete, the report states whether the change left an audit row. Each result is recorded, conditional, cancelled by the trigger, or untested. This matters on Supabase because connection logging, which the HIPAA guide asks to keep on, records only who connected and says nothing about which rows changed.
Tampering. For each audit table and each client role, the report checks whether that role can edit it, erase it or forge rows in it. One way this fails is a SECURITY DEFINER function exposed through .rpc() that writes to the audit table, which lets any logged-in user call it and write whatever they like.
Identity. Policies rely on auth.uid() and auth.jwt(). The report checks whether a client session is able to change what those return.
Everything goes into one HTML report with a JSON copy. Each safeguard is marked as evidence or partial, the gaps are ranked alongside the change that fixes each one, and the report is stamped with the database, the time, the role, the tool version and a SHA-256 of every file it drew on. If the report is edited afterwards, the hashes no longer match.
Most Supabase changes arrive as a migration in a pull request, and Supabase already documents a GitHub Action that runs supabase test db. Adding the hipaa command to the same job, and keeping the dated report as a build artifact, covers the evaluation safeguard and removes the rush before each audit.
The report is evidence for an auditor and does not certify anything. It does not look at encryption or transmission, which Supabase handles, and it does not review logs. It also cannot judge whether a policy is the right policy. If a rule is wrong by design, the report will say the database enforces it, because it does. The risk analysis, the written policies and the BAA itself remain the responsibility of the organization.
unitautogen hipaa is part of the Enterprise edition of UnitAutogen for PostgreSQL. Early-stage Supabase teams can ask about the startup rate, and a free trial is available for running it on a real schema first.Here's the uncomfortable part: most RLS ships untested. And an untested access control isn't a control. It's an assumption.
HIPAA's Security Rule requires technical access controls that allow access "only to those persons or software programs that have been granted access rights" (45 CFR §164.312(a)(1)). That's RLS's job description, and RLS is native PostgreSQL, enforced in the database on every deployment. If you're on Supabase, their HIPAA guidance points to RLS as the way to guarantee each provider, clinic, or patient sees only their own data; the same mechanism does the same job on RDS, Neon, or a self-hosted cluster.
SOC 2 says the same thing in different words. Common Criteria CC6.1 requires that logical access to protected information be restricted to authorized users. RLS is that restriction, enforced in the database, where an application bug can't route around it.
So the compliance question isn't "do you use RLS?" Everyone says yes. The question is "can you show it works?"
This is where untested RLS quietly fails. A policy with the wrong column, an OR that's too generous, a USING (true) left in from debugging: all of these pass code review and sit in production looking fine. Nothing errors. The dashboard is green. And a different tenant can read PHI.
You won't catch that by reading the policy. You catch it by exercising it: becoming each identity (the owner, another tenant, an anonymous visitor) and checking what each one can actually SELECT, INSERT, UPDATE, and DELETE. That's the difference between asserting a control exists and demonstrating that it enforces.
Evidence for an access-control safeguard is concrete and repeatable:
That's not a screenshot of a settings page. That's a test run you can hand to a reviewer: dated and reproducible.
rlsautotest generates exactly that evidence, without you hand-writing test SQL. Point it at a disposable copy of your database; it reads your RLS policies, generates both the tests and the seed data that make them mean something, probes each policy as each identity, and emits a native pgTAP suite plus a per-identity access report and a CI gate. (pgTAP ships on Supabase and loads on any other Postgres; the tool handles it for you.)
pip install rlsautotest
rlsautotest --db-url "$DATABASE_URL" --schema public --html rls-report.htmlOne command produces the access matrix. --emit writes the committable suite; wire it into CI and every pull request re-proves your access controls.
But within its lane, it turns "we use RLS" into "here's the test run that shows our RLS restricts access as designed." For a control that's one misplaced predicate away from a breach notification, that's the difference that matters.
]]>org_id for multi-tenancy or a role claim for RBAC, you've probably hit this: it works perfectly on Supabase Cloud, and then your local tests come back with empty tables or "new row violates row-level security policy." The policy is fine. The problem is how the claims reach auth.jwt() locally.
On a real request, the chain is: GoTrue mints a JWT (running your custom access-token hook, so the custom claims are in it) → PostgREST receives that JWT and puts the decoded payload into a Postgres setting called request.jwt.claims → your policy calls auth.jwt(), which simply reads that setting. So the custom claims are present, and RLS behaves.
The local Studio Dashboard breaks that chain. When you impersonate a user in the local dashboard, it isn't tightly integrated with GoTrue the way Cloud is. It gives you a session, but the JWT it puts in front of your query doesn't carry your custom claims. So auth.jwt() returns a payload with the custom claims empty, every policy that reads them evaluates false, and you get an empty result (or a denied insert). It looks like your RLS is broken; really, the test harness just isn't feeding it the claims your app feeds it.
The key insight is that auth.jwt() is not magic; it just reads the request.jwt.claims setting. So you can reproduce a real request exactly by setting that yourself, in a transaction, as the right role. No GoTrue, no PostgREST, no Dashboard involved:
begin;
-- become the role your app uses, and inject the claims GoTrue would have minted
set local role authenticated;
select set_config('request.jwt.claims',
'{"sub":"00000000-0000-0000-0000-0000000000aa",
"role":"authenticated",
"app_metadata":{"org_id":"org-a","role":"admin"}}', true);
-- auth.jwt()->'app_metadata'->>'org_id' now returns 'org-a' inside your policy
select * from documents; -- runs under RLS as this exact identity
rollback;Now the policy sees the same claims it sees in production, and you can assert what this identity should and shouldn't be able to do. Copy the exact JSON shape from a real API session's token (app_metadata vs user_metadata vs a top-level claim) so it matches what your hook actually emits.
For tenant isolation, the meaningful negative test isn't an outsider with no org; it's a legitimate user of a different org. Run the same block again with org-b in the claims and assert they see none of org A's rows. That's the test that catches a subtly-wrong predicate like org_id IS NOT NULL, which a no-org outsider would sail right through but a real second tenant would expose.
set_config(..., true) is transaction-local. It only lasts for the current transaction, so the set_config and the query have to be in the same transaction. Run them separately and the claim is already gone.set role. If you stay connected as the table owner or a superuser, RLS is bypassed entirely, so everything passes and proves nothing. Become authenticated or anon.auth.jwt()->'app_metadata'->>'org_id', the claims you set need that nesting exactly.The Dashboard will never run in your pipeline, but this does. Wrap the same pattern in pgTAP and you have RLS tests, including the custom-claim and multi-tenant cases, that run on every push, the same way the app actually executes them.
However you get there, the principle is the same: test RLS by setting the claims yourself at the database level, as the role your app uses. That's the only place the policy runs the way production runs it.
]]>This post is about how to actually test RLS with pgTAP: the mechanics, the traps, and the handful of cases that bite you. No tooling required to follow along, just psql and pgTAP (which Supabase ships, and you can CREATE EXTENSION pgtap anywhere else).
Four things make RLS testing different from normal unit testing:
1. You have to become each identity. A policy like USING (owner = auth.uid()) behaves completely differently depending on who's asking. So a real test has to impersonate each one (anonymous, authenticated user A, authenticated user B, the service role) and check what each can actually do. In Postgres/Supabase terms that's SET ROLE plus setting the request's JWT claims.
2. USING and WITH CHECK are not the same thing. USING controls which rows you can see/affect (SELECT, UPDATE, DELETE). WITH CHECK controls which rows you're allowed to write (INSERT, and the new value on UPDATE). A table can be perfectly locked down for reads and wide open for writes, or vice versa. You have to test both directions.
3. "Denied" has two completely different shapes. When someone can't do something, it's either filtered to zero rows (RLS silently hides rows, no error) or a hard permission error (42501; the role doesn't even have the table grant). These mean different things, and conflating them hides bugs. A test that just checks "got an error" will miss an RLS policy that's silently returning everyone's rows, because that path doesn't error; it returns data.
4. The seed-data trap. This is the big one. A test only proves something if the data driving it actually exercises the policy. If your table is empty, "user B sees 0 rows" passes whether or not the policy works. If the row you seeded isn't actually owned by the user you're impersonating, "owner sees their row" fails, or worse, accidentally passes for the wrong reason. The data has to match the identity and the predicate, or the green checkmark is a lie.
Here's an owner-scoped documents table tested by hand. The shape is Arrange → Act → Assert, wrapped in a transaction that rolls back so tests don't pollute each other.
begin;
select plan(3);
-- ARRANGE: seed as the test-runner role (superuser/owner -- bypasses RLS).
-- Two users, one document owned by user A.
insert into auth.users (id) values
('00000000-0000-0000-0000-00000000000a'),
('00000000-0000-0000-0000-00000000000b');
insert into documents (owner, title)
values ('00000000-0000-0000-0000-00000000000a', 'A''s doc');
-- ACT/ASSERT as user A (the owner) -- should see exactly their row
set local role authenticated;
select set_config('request.jwt.claims',
'{"sub":"00000000-0000-0000-0000-00000000000a","role":"authenticated"}', true);
select is( (select count(*) from documents)::int, 1, 'owner sees their own row' );
-- as user B (a different authenticated user) -- should see nothing
select set_config('request.jwt.claims',
'{"sub":"00000000-0000-0000-0000-00000000000b","role":"authenticated"}', true);
select is( (select count(*) from documents)::int, 0, 'another user sees nothing' );
-- as anon -- should see nothing
reset role;
set local role anon;
select set_config('request.jwt.claims', '', true);
select is( (select count(*) from documents)::int, 0, 'anon sees nothing' );
select * from finish();
rollback;Notice the two things that make this mean something: we seeded a row that is genuinely owned by user A (so "owner sees their row" is a real assertion, not a fluke against empty data), and the negative case is a real, different authenticated user, not just "logged out."
Once the basic shape is in place, these are the ones that catch people:
INSERT is governed by WITH CHECK, which constrains the row, not the caller. A user who can't see another tenant's data can usually still insert their own row, and that's correct, not a hole. The actual hole is WITH CHECK (true) (anyone can write anything) or RLS being off entirely. So an INSERT test should assert two things: the caller can insert a row that satisfies the check, and cannot insert one that violates it (e.g. a row attributed to someone else).
-- a different user inserting their OWN row: allowed (WITH CHECK passes)
select lives_ok(
$$ insert into documents (owner, title) values (auth.uid(), 'mine') $$,
'user can insert their own row'
);
-- inserting a row owned by someone ELSE: must be rejected
select throws_ok(
$$ insert into documents (owner, title)
values ('00000000-0000-0000-0000-00000000000a', 'not mine') $$,
'42501', null, 'user cannot insert a row for another owner'
);Tenant isolation needs a real rival tenant. The meaningful negative test for org_id = (auth.jwt() -> 'app_metadata' ->> 'org_id')::uuid isn't an outsider with no org; it's a legitimate user of a different org. That's the test that catches a subtly-wrong predicate like org_id IS NOT NULL, which a no-org outsider would pass right through.
RBAC via SECURITY DEFINER functions. Policies that delegate to authorize('documents.read') or has_role('admin') are opaque to a black-box test; you can't always drive them through the JWT. You test the wiring: set up the state the function reads (or control the function), then assert that the policy is allowed when it returns true and denied when it returns false.
Self-referential policies. A policy that queries its own table (a recursive folder tree, say) can throw infinite recursion detected in policy, which locks out every client role. Worth an explicit "the table is even readable" test.
None of the above is hard for one table. The problem is that a real app has dozens of tables, four commands each, and several identities, and every single combination needs its own seeded precondition to mean anything. That's a lot of careful, repetitive SQL, and the failure mode is silent: a test that passes against the wrong data tells you you're safe when you're not.
Become each identity, test both USING and WITH CHECK, distinguish "0 rows" from "denied," and make sure your seed data actually exercises the policy. Your RLS is your security boundary. Test it like one.