Cursor rules for Supabase (keys, RLS, auth)

---
description: Supabase keys, Row Level Security, auth checks and migrations. Use when touching Supabase clients, SQL, policies, auth or env vars.
alwaysApply: false
---

# Supabase: keys, RLS, auth and migrations

Stack: Supabase (Postgres + Auth) with `@supabase/supabase-js` and `@supabase/ssr`. If something here disagrees with the installed package's types or the Supabase docs, the docs win. Never invent a client method or config key.

## Keys: which one, where
- Browser, mobile, CLI or anything you ship: the **publishable** key (`sb_publishable_...`). It is public by design; Row Level Security is what protects data.
- Servers, Edge Functions, cron jobs and workers: the **secret** key (`sb_secret_...`). It bypasses RLS. It must never appear in client code, a `NEXT_PUBLIC_` variable, logs, URLs or source control.
- Env var names: `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` for client code; `SUPABASE_URL` + `SUPABASE_SECRET_KEY` (no public prefix) for server code.
- The legacy `anon` and `service_role` JWT keys (long strings starting with `eyJ`) are being deprecated. Don't add new code that uses them. If the project still does, flag it; don't migrate keys without asking.
- Only create a secret-key client in files that can never be imported by client code (for a Next.js app, put `import 'server-only'` at the top).

## Row Level Security
- Every table in an exposed schema has RLS enabled in the same migration that creates it. No exceptions without a written reason.
- Write policies for the `anon` and `authenticated` roles. Scope them to the user with `(select auth.uid())`, never with a user id sent by the client.
- Separate policies per operation (`select`, `insert`, `update`, `delete`). `update` needs both `using` and `with check`.
- Remember how failures look: a select blocked by RLS returns **an empty result, not an error**; a blocked insert or update errors with "violates row-level security policy"; a missing table grant returns a permission error. Check grants before debugging policies.
- Never "fix" an RLS problem by switching to the secret key, disabling RLS, or adding a `using (true)` policy. Find which policy is missing and say so.

## Auth checks on the server
- Server code, including the Next.js proxy/middleware, protects pages and data with `supabase.auth.getClaims()`, which verifies the token.
- Never trust `supabase.auth.getSession()` in server code for authorization: it reads the cookie without revalidating it. Use `getUser()` only when you need a fresh user record from the Auth server.
- Keep the session-refresh proxy (`proxy.ts` on Next.js 16, `middleware.ts` on 15 and earlier) and return the response object it built, or users get signed out.

## Schema changes
- All schema changes go through migration files (`supabase migration new <name>`), committed with the code that needs them. No dashboard-only edits.
- Never edit a migration that has already run in a shared environment. Add a new one.
- After changing the schema, regenerate types (`supabase gen types typescript ...`) and use them in the client instead of hand-written row types.
- Ask before anything destructive: dropping tables or columns, `truncate`, `delete` without `where`, `supabase db reset` against anything but a local stack.

## Queries
- Select only the columns you need (`.select('id, title')`, not `select('*')` for user-facing data).
- Always check `error` before using `data`. Don't assume a query succeeded.