Supabase

Supabase — Postgres with RLS as the auth layer

Supabase is a managed Postgres database wrapped in thin SDKs, a PostgREST data API, Auth, Storage, Realtime, and Deno Edge Functions. The one sentence that explains every footgun below:

Your authorization lives in the database (Row Level Security), not in your app code.

The browser holds a key that can hit your database directly. That is safe only because RLS gates every row. Get that wrong and you either leak everything or see nothing. Everything in this skill is downstream of that fact. You can write SQL already — what you need is Supabase's specific abstractions and where the trust boundary sits.

Use the current packages: @supabase/supabase-js v2 (v1 is security-fixes only) and @supabase/ssr for server frameworks (it replaced the deprecated auth-helpers).

The two keys (the trust boundary)

Every Supabase project ships two classes of key. Confusing them is the one unrecoverable mistake.

The new sb_publishable_ / sb_secret_ format is rolling out alongside the legacy anon/service_role JWTs; treat them by the same rules. Why this matters: the service_role key is a master key with RLS turned off. One import into a client component is a full data breach.

// Bad — service_role key reachable from the browser bundle
"use client";
const supabase = createClient(URL, process.env.NEXT_PUBLIC_SERVICE_ROLE_KEY!); // leaked

// Good — service_role only in server-side env, never NEXT_PUBLIC_*
// server-only module / Edge Function:
const admin = createClient(URL, process.env.SUPABASE_SERVICE_ROLE_KEY!);

Pick your client

Wrong client = broken sessions (no cookie refresh) or leaked keys. For SSR frameworks you need both an @supabase/ssr browser client and a server client, plus middleware — see below.

Auth that actually protects

Cookie-based auth in an SSR framework has one hard constraint: Server Components cannot write cookies, so an expired access token can only be refreshed in middleware. Skip the middleware and sessions silently die mid-request.

The non-negotiable rule for server-side gating: never trust getSession() — it only reads the cookie, which a client can forge. What you reach for instead changed in late 2025.

Default: supabase.auth.getClaims(). It verifies the JWT signature locally against your project's published public keys (/.well-known/jwks.json, cached on the edge and in memory) — no network round-trip. The current SSR docs say to "always use supabase.auth.getClaims() to protect pages and user data." This works because new projects sign tokens with asymmetric keys by default since 2025-10-01 (RSA or Elliptic-Curve / ECC); the private key never leaves Auth, the public key is safe to verify with.

getClaims vs getUser — pick by signing key + freshness need

// Bad — getSession reads an unverified cookie; trivially spoofed
const { data: { session } } = await supabase.auth.getSession();
if (!session) redirect("/login"); // NOT a real check on the server

// Good (default) — getClaims verifies the JWT signature locally, no round-trip
const { data } = await supabase.auth.getClaims();
if (!data?.claims) redirect("/login");

// Good (strict fallback) — getUser revalidates against the Auth server every call;
// use only when you need live ban/delete detection
const { data: { user } } = await supabase.auth.getUser();
if (!user) redirect("/login");

Middleware token refresh is mandatory; full app-router code (browser client, server client, middleware.ts, server-action sign-in/out, OAuth/PKCE callback, and the auth-helpers→@supabase/ssr migration checklist) lives in references/auth-ssr.md. For the framework's own RSC/caching/server-action mechanics see ../nextjs/SKILL.md — this skill only covers the Supabase wiring inside it.

RLS recipes + the performance cliff

Enable RLS on every table the data API can reach, then write policies. Four rules that cover most real cases:

1. enable row level security on the table — without it, an exposed table is wide open to the anon key.
2. Scope with to authenticated — don't rely on auth.uid() alone to exclude the anon role; an anon request has a null uid and may slip through a sloppy predicate.
3. Wrap (select auth.uid()) — Postgres caches a select-wrapped call once per statement instead of re-evaluating per row. Bare auth.uid() turns a lookup into a per-row function call → table-scan latency.
4. Index the policy columns — a policy filtering user_id = (select auth.uid()) needs an index on user_id, or every query scans the table.

-- Bad — bare auth.uid() re-evaluated per row, no role scope, no index
create policy "owner reads" on documents
  for select using ( user_id = auth.uid() );

-- Good — cached subquery, role-scoped; pair with an index
create policy "owner reads" on documents
  for select to authenticated
  using ( user_id = (select auth.uid()) );

create index on documents (user_id);

For cross-table checks (is the user a member of this org?), use a security definer helper or a team_id filter rather than a correlated subquery inside the policy. Multi-tenant team_id patterns, public-read/private-write, storage policies, realtime.messages policies, and how to test policies with set role authenticated live in references/rls-cookbook.md. For engine-level index choice and EXPLAIN reading, see ../postgresdb/SKILL.md.

"My query returns nothing" — checklist

Silent empty results are the #1 confusion. Walk it in order:

1. Is RLS enabled but you have no policy? No policy = deny all. Add a select policy.
2. Is the policy too strict / role-scoped wrong? Test it: set role authenticated; with a faked request.jwt.claims (see the cookbook).
3. Is the table even exposed to the data API? This is the new trap. Supabase is flipping the "automatically expose new tables" default off: default for new projects since 2026-05-30, and enforced on all existing projects 2026-10-30. An unexposed table is unreachable through PostgREST even with perfect RLS — you get empty results, not an error. Expose it explicitly in the dashboard (Data API settings) or grant access in the relevant schema.