Next.js + Supabase SaaS

# AGENTS.md: Next.js + Supabase SaaS

You are working on a Next.js (App Router) SaaS backed by Supabase (Postgres, Auth, Storage).
Treat the database as production unless told otherwise.

## Stack and layout
- Next.js App Router in `app/`. TypeScript strict mode. No Pages Router code.
- Supabase clients live in `lib/supabase/`:
  - `server.ts` creates a server client with `@supabase/ssr` and the Next.js `cookies()` store.
  - `client.ts` creates a browser client. Only use it inside `"use client"` components.
  - `middleware.ts` (or `proxy.ts` on newer Next.js) refreshes the auth session cookie on each request.
- Schema lives in `supabase/migrations/`. Generated types live in `lib/database.types.ts`.

## Server vs client
- Components are Server Components by default. Add `"use client"` only for state, effects or browser APIs.
- Fetch data in Server Components or Route Handlers, not in `useEffect`, unless it is genuinely live data.
- Mutations go through Server Actions or Route Handlers. Validate every input with `zod` on the server,
  even if the form validated it already.
- Never import `lib/supabase/server.ts` or anything using secret env vars from a client component.

## Auth
- Get the user on the server with `supabase.auth.getUser()` (it verifies the JWT with Supabase).
  Do not trust `getSession()` on the server for authorisation decisions.
- Protect pages by checking the user in the layout or page, and redirect if missing. Middleware alone is not enough.
- Authorisation belongs in RLS policies. App code checks are a convenience, not the security boundary.

## Keys and environment
- `NEXT_PUBLIC_SUPABASE_URL` and the publishable (anon) key are safe in the browser *only because RLS is on*.
- The secret / `service_role` key bypasses RLS. It must only be used in server-only code for admin jobs,
  never prefixed `NEXT_PUBLIC_`, never logged, never committed.
- Keep `.env.local` out of git. Add any new variable to `.env.example` with a dummy value.

## Database changes
- Every schema change is a new migration: `supabase migration new <name>`. Never edit an applied migration.
- Every new table in an exposed schema gets `alter table ... enable row level security;` in the same migration,
  plus explicit policies for each operation it needs (select, insert, update, delete).
- Prefer `(select auth.uid())` in policies over bare `auth.uid()` so Postgres can cache it per statement.
- Add indexes on columns used in policies (for example `user_id`, `org_id`).
- After a schema change, regenerate types: `supabase gen types typescript --local > lib/database.types.ts`.

## Payments (if present)
- Stripe webhooks are verified with the signing secret before any database write.
- Entitlements (plan, seats) are written by the webhook handler, never by the client.

## Before you say "done"
1. `npm run lint` and `npm run build` pass.
2. No secret key reachable from client bundles (`grep -r SERVICE_ROLE app components` is empty).
3. Any new table has RLS enabled and at least one policy. Run the `supabase-rls-audit` skill if unsure.
4. Summarise what changed, any migration added, and anything the human must do (env vars, dashboard settings).

## Do not
- Do not disable RLS to "make it work". Fix the policy instead.
- Do not run destructive SQL (`drop`, `truncate`, `delete` without `where`) against a remote project.
- Do not add a new auth library. Supabase Auth is the auth system.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `supabase-rls-audit`. Use them when their description matches the task.
- MCP servers for this project are in `.mcp.json`. If a server is not connected, tell the human rather than working around it.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Next.js + Supabase SaaS" v1.0.0 — https://loadout.jnw-it.com/loadouts/nextjs-supabase-saas/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `supabase-rls-audit`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Next.js + Supabase SaaS" v1.0.0 — https://loadout.jnw-it.com/loadouts/nextjs-supabase-saas/ -->

---
description: Rules for writing Supabase SQL migrations safely
globs: supabase/migrations/**/*.sql
alwaysApply: false
---

# Supabase migrations

- One concern per migration file. Name it for what it does: `add_projects_table`, not `update`.
- Never edit a migration that has been applied anywhere. Write a new one.
- Every `create table` in `public` (or any exposed schema) is followed in the same file by:
  - `alter table <name> enable row level security;`
  - explicit `create policy` statements for each operation the app needs.
- Write policies with a `to` role (`authenticated` or `anon`) and both `using` and, for writes, `with check`.
- Use `(select auth.uid())` inside policies, not bare `auth.uid()`.
- Index foreign keys and every column referenced by a policy.
- `security definer` functions must set `search_path = ''` and fully qualify table names.
- Destructive changes (`drop column`, `drop table`, type changes) need a comment explaining the data impact,
  and should be split into expand → migrate data → contract steps when the table has real data.

Example:

```sql
create table public.projects (
  id uuid primary key default gen_random_uuid(),
  owner_id uuid not null references auth.users (id) on delete cascade,
  name text not null check (char_length(name) between 1 and 120),
  created_at timestamptz not null default now()
);

alter table public.projects enable row level security;

create index projects_owner_id_idx on public.projects (owner_id);

create policy "Owners can read their projects"
  on public.projects for select to authenticated
  using ((select auth.uid()) = owner_id);

create policy "Owners can create projects"
  on public.projects for insert to authenticated
  with check ((select auth.uid()) = owner_id);
```

---
name: supabase-rls-audit
description: Audit Supabase row level security. Use when asked to check database security, before launch, after adding tables, or when someone worries that users can see each other's data.
---

# Supabase RLS audit

Goal: find every way a signed-in or anonymous user could read or change rows they should not,
and report it in plain English with a fix for each.

## 1. Collect the facts
Use whichever source is available, in this order:
1. The Supabase MCP server (read-only) — run the SQL below with its query tool.
2. A local database: `supabase db dump --local --schema public` or `psql` against the local URL.
3. The migration files in `supabase/migrations/` (read them in order; later files win).

```sql
-- Tables in exposed schemas and whether RLS is on
select n.nspname as schema, c.relname as table, c.relrowsecurity as rls_enabled, c.relforcerowsecurity as rls_forced
from pg_class c join pg_namespace n on n.oid = c.relnamespace
where c.relkind = 'r' and n.nspname in ('public')
order by 1, 2;

-- Every policy
select schemaname, tablename, policyname, cmd, roles, qual as using_expr, with_check
from pg_policies where schemaname in ('public')
order by tablename, cmd;

-- Views (they bypass RLS unless created with security_invoker)
select table_schema, table_name from information_schema.views where table_schema = 'public';

-- Security definer functions callable through the API
select p.proname, p.prosecdef, p.proconfig
from pg_proc p join pg_namespace n on n.oid = p.pronamespace
where n.nspname = 'public' and p.prosecdef;
```

## 2. Check each table against these rules
Flag as **Critical**:
- RLS disabled on any table in `public`.
- A policy for `anon` or `public` roles that is `using (true)` on a table holding user data.
- An `update` policy without `with check`, letting users move rows to another owner.
- A view in `public` without `security_invoker = true` that selects from a protected table.

Flag as **High**:
- RLS enabled but no policies (the app is probably using the secret key to get round it — find out where).
- Policies that trust a column the user can write (for example `role` or `is_admin` on their own profile row).
- `security definer` functions without `set search_path = ''`.
- Storage buckets that are public but hold private uploads.

Flag as **Medium**:
- Bare `auth.uid()` instead of `(select auth.uid())` (performance, not security).
- Policy columns without indexes.

## 3. Check the app code
- Search for the secret / service role key: `grep -rn "SERVICE_ROLE\|sb_secret_" --include=*.ts --include=*.tsx .`
  Any hit outside server-only files is **Critical**.
- Check that no `NEXT_PUBLIC_` variable holds a secret.

## 4. Report
Write a short report:

```
RLS audit — <date>
Critical: <n>  High: <n>  Medium: <n>

[Critical] public.invoices — RLS is disabled. Anyone with the publishable key can read every invoice.
Fix: new migration with `alter table public.invoices enable row level security;` and an owner-only select policy.
```

Then offer to write the fix as a **new migration**. Do not apply changes to a remote database yourself.

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"
    }
  }
}