Supabase Email Auth

# Spec: email/password auth with Supabase

Build signup, email confirmation, login, logout, and protected routes for
[app name] using Supabase Auth. Sessions are checked server-side; the
database enforces access with row-level security.

## Stack

- Framework: [e.g., Next.js 14 App Router with @supabase/ssr]
- Supabase project already exists; URL and keys below.

## Environment variables

```bash
NEXT_PUBLIC_SUPABASE_URL=https://[project].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...   # safe for the client; RLS is the guard
SUPABASE_SERVICE_ROLE_KEY=eyJ...       # server ONLY, bypasses RLS; never ships
                                       # to the browser, never NEXT_PUBLIC_
```

## Supabase dashboard settings (do these first, in Authentication)

- Email confirmation: ON. Unconfirmed users cannot sign in.
- Site URL: [http://localhost:3000] for dev; the production URL at deploy.
- Redirect URLs: add `[APP_URL]/auth/callback`.

## Pages and routes

- `/signup`: email + password form. On submit call `signUp` with
  `emailRedirectTo: [APP_URL]/auth/callback`. On success show "check your
  email", do NOT log the user in or redirect to the app.
- `/auth/callback`: route handler that exchanges the code in the
  confirmation link for a session, then redirects to `/[home or dashboard]`.
  Without this route, confirmation links dead-end.
- `/login`: email + password, `signInWithPassword`. On the "email not
  confirmed" error, show "confirm your email first" with a resend button.
- Logout: a POST action calling `signOut`, then redirect to `/login`.
  Logout via GET gets triggered by prefetchers; use POST.
- `/[dashboard]` and everything under it: protected (below).

## Protecting routes (server-side, non-negotiable)

- Middleware refreshes the session on every request (per @supabase/ssr docs).
- Every protected page and API route calls `supabase.auth.getUser()`
  server-side and redirects to `/login` (or returns 401) when null.
- `getUser()` validates against the Auth server. Do not substitute
  `getSession()` for authorization decisions; it reads the cookie without
  verifying it.
- Client-side redirects are UX polish on top of the server check, never a
  replacement for it.

## Profiles table with RLS

`auth.users` belongs to Supabase; app data lives in a `profiles` row created
automatically for each new user:

```sql
create table profiles (
  id uuid primary key references auth.users(id) on delete cascade,
  email text not null,
  display_name text,
  created_at timestamptz not null default now()
);

alter table profiles enable row level security;

create policy "read own profile" on profiles
  for select using (auth.uid() = id);
create policy "update own profile" on profiles
  for update using (auth.uid() = id);
-- No insert policy: the trigger below creates rows, users never insert directly.

create function public.handle_new_user()
returns trigger language plpgsql security definer set search_path = '' as $$
begin
  insert into public.profiles (id, email) values (new.id, new.email);
  return new;
end $$;

create trigger on_auth_user_created
  after insert on auth.users
  for each row execute function public.handle_new_user();
```

## Verification (before calling this done)

1. Sign up with a real inbox. Confirm you CANNOT log in before clicking the
   email link, and CAN after.
2. Confirm the `profiles` row exists after signup, created by the trigger.
3. While logged out, hit a protected page by URL and a protected API route
   with curl: redirect and 401 respectively.
4. In the SQL editor, as user A, select from profiles: exactly one row, yours.