# Client Magic Link Auth Replacement

**Date**: 2026-04-30
**Status**: Approved
**Supersedes**:
- `docs/superpowers/specs/2026-04-15-client-magic-links-design.md`
- `docs/superpowers/specs/2026-04-18-client-password-invite-flow-design.md`

## Overview

Replace the current `profiles.is_client` model and Supabase-auth-based client portal flow with a fully separate client authentication system owned by the application backend.

The new model is:

- client identity lives in `public.clients`, not `auth.users` or `public.profiles`
- client access to tablos lives in a dedicated access table, separate from collaborator access
- invitation and login both use magic links sent by email
- the magic link is a one-time identity proof
- successful exchange sets a persistent stateless JWT session cookie
- `apps/clients` authenticates against backend-owned cookies and backend APIs, not browser Supabase Auth sessions

This keeps Supabase as the database, but removes Supabase Auth from the client-portal trust model.

## Problem Statement

The current implementation couples client access to the main authentication system too tightly.

### Current issues

1. `profiles.is_client` models client users as a special subtype of main authenticated users.
2. Client identity currently depends on `auth.users` and `public.profiles`, which conflicts with the requirement for a separate client auth system.
3. `apps/clients` currently depends on Supabase Auth sessions and browser-side Supabase reads.
4. The existing invite flow is centered around onboarding a Supabase-authenticated account rather than establishing a standalone client session model.
5. The current architecture makes it hard to express a clean separation between collaborator auth and client auth.

## Goals

- Remove `profiles.is_client` as the source of truth for client identity
- Introduce a separate client identity table in the public schema
- Support one global client identity per email across all tablos
- Use email magic links for both invitations and later self-serve login
- Exchange a valid link for a persistent stateless JWT session cookie
- Keep client access independent from Supabase Auth tables and sessions
- Move `apps/clients` to backend-authorized APIs instead of direct browser Supabase data access

## Non-Goals

- Keeping client users represented in `auth.users`
- Using Supabase Auth sessions for the client portal
- Building immediate session revocation into v1
- Supporting self-service signup without invitation
- Embedding the complete authorization graph inside the session JWT

## Approved Product Decisions

The following decisions were explicitly approved during brainstorming:

- client auth is separate from Supabase Auth
- the invite flow uses a magic link
- successful link exchange results in a persistent browser session
- client identity is global by normalized email, not scoped per tablo
- the session mechanism starts simple with a stateless JWT cookie
- access revocation does not need to terminate active sessions immediately
- when a session expires, clients can re-enter their email and receive a new login link
- `BetterAuth` is not required for the first version

## Chosen Approach

Implement a custom minimal client-auth layer in the backend instead of introducing `BetterAuth` in v1.

The backend owns:

- client identity records
- client access grants
- magic-link issuance and one-time consumption
- session cookie creation and verification
- authorization checks for client routes and client data

`BetterAuth` remains a possible future evolution if richer auth lifecycle features become necessary, but it is not part of the first implementation.

This approach is recommended because it fits the current codebase better than introducing a second auth framework while `apps/clients` is still being migrated away from direct Supabase browser access.

## Architecture

### Core boundary

There are now two distinct auth systems:

- collaborator auth for `app.xtablo.com`
- client auth for `clients.xtablo.com`

They must not share session mechanisms or identity tables.

### Trust model

For the client portal:

- the browser does not hold a Supabase Auth session
- the browser does not use `supabase.auth` for login state
- the browser does not directly query protected client data from Supabase
- the backend verifies the client cookie and performs authorization on every protected client API request

### High-level flow

1. An admin invites a client email to a tablo.
2. The backend upserts a client identity and ensures a client access grant exists.
3. The backend creates a one-time magic-link record and emails the link.
4. The client clicks the link.
5. The backend validates and consumes the link, then sets a persistent JWT cookie.
6. `apps/clients` uses that cookie for authenticated access to backend APIs.
7. When the cookie expires, the client can request a fresh login link by email.

## Data Model

### `public.clients`

One row per normalized email.

Suggested columns:

| Column | Type | Notes |
|--------|------|-------|
| `id` | uuid or bigint PK | Stable client identity |
| `email` | text | Original or canonical email |
| `normalized_email` | text | Lowercased and normalized, unique |
| `first_name` | text nullable | Optional |
| `last_name` | text nullable | Optional |
| `phone` | text nullable | Optional |
| `last_login_at` | timestamptz nullable | Updated on successful login |
| `created_at` | timestamptz | Default `now()` |
| `updated_at` | timestamptz | Default `now()` |

Required constraints:

- unique index on `normalized_email`

### `public.client_access`

Source of truth for which tablos a client may access.

Suggested columns:

| Column | Type | Notes |
|--------|------|-------|
| `id` | bigint PK | |
| `client_id` | FK -> `clients.id` | |
| `tablo_id` | FK -> `tablos.id` | |
| `granted_by` | FK -> `profiles.id` | Collaborator/admin who granted access |
| `granted_at` | timestamptz | Default `now()` |
| `revoked_at` | timestamptz nullable | Null means active |
| `created_at` | timestamptz | Default `now()` |

Required constraints:

- one active access row per `(client_id, tablo_id)`

### `public.client_magic_links`

Tracks invite and login links and enforces one-time use.

Suggested columns:

| Column | Type | Notes |
|--------|------|-------|
| `id` | bigint PK | |
| `client_id` | FK -> `clients.id` | |
| `email` | text | Denormalized for audit/debugging |
| `purpose` | text | `invite` or `login` |
| `token_hash` | text nullable | Preferred if storing hashed token |
| `jti` | text nullable | Alternative lookup key if JWT carries `jti` |
| `redirect_to` | text nullable | Optional target route after exchange |
| `expires_at` | timestamptz | |
| `consumed_at` | timestamptz nullable | One-time-use marker |
| `created_by` | uuid nullable | Admin profile id for invite flow, null for self-serve login |
| `created_at` | timestamptz | Default `now()` |

Notes:

- even if the magic link payload is JWT-based, the backend still stores a row
- this table is required for one-time use, expiry enforcement, and auditability

### Optional audit table

`public.client_auth_events` is optional in v1 but recommended.

Suggested event types:

- `invite_issued`
- `login_link_issued`
- `magic_link_consumed`
- `login_failed`
- `logout`

## Session Model

### Cookie shape

The backend issues a stateless JWT session cookie after a successful magic-link exchange.

Recommended cookie settings:

- `HttpOnly`
- `Secure`
- `SameSite=Lax`
- scoped to the client portal domain

Suggested TTL:

- start with `7 days`

### JWT claims

The session JWT should stay minimal and represent identity, not the full access graph.

Suggested claims:

- `sub`: `client_id`
- `email`
- `type`: `client_session`
- `iat`
- `exp`

Optional future claim:

- `access_version`

### Revocation behavior

This design intentionally accepts eventual revocation.

If a client loses access while holding a still-valid cookie:

- the cookie may remain structurally valid until expiry
- a new login link should not be issued once the client has no active access
- authorization checks for protected resources should still evaluate access against `client_access`

This means the design does not need a server-stored session table to invalidate cookies early. The cookie lifecycle and the resource-authorization lifecycle remain separate.

The design does not require a `client_sessions` table in v1.

## End-To-End Flows

### Admin invite flow

1. A collaborator in `apps/main` invites a client email to a specific tablo.
2. The backend normalizes the email.
3. The backend upserts a row in `public.clients`.
4. The backend ensures an active `client_access` row exists for that `(client_id, tablo_id)`.
5. The backend creates a `client_magic_links` row with `purpose = 'invite'`.
6. The backend emails a one-time magic link pointing to a backend exchange endpoint or a portal route that immediately exchanges the token.
7. When consumed successfully, the link is marked used and cannot be reused.

### First access

1. The client clicks the invite link.
2. The backend validates:
   - the token signature or identity
   - the existence of the backing `client_magic_links` row
   - not expired
   - not already consumed
3. The backend sets the client session cookie.
4. The backend marks the link consumed.
5. The browser is redirected into `clients.xtablo.com`, ideally to the invited tablo route.

### Self-serve login flow

1. The client visits the client login page.
2. The client enters their email address.
3. The backend returns a neutral success response regardless of whether access exists.
4. If the email maps to a client with active access, the backend creates a `purpose = 'login'` magic link and sends the email.
5. The client clicks the link and goes through the same exchange path as an invite.

### Logout

1. The client chooses logout in the portal.
2. The backend clears the session cookie.
3. No DB session cleanup is required in v1.

## Authorization Model

### Principle

The cookie proves client identity. Authorization remains server-side.

The session JWT must not be treated as the source of truth for tablo-level permissions.

### Per-request behavior

On each protected client API request:

1. verify the JWT cookie
2. load the client identity
3. check requested resource access against `client_access`
4. allow or deny based on active access

### Why not store access in the JWT

Embedding tablo access claims in the session token would make revocation and multi-tablo growth harder to manage. It is simpler and safer to keep the JWT small and query `client_access` during authorization.

## API Design Implications

### New backend responsibilities

The backend needs a dedicated client-auth surface, for example:

- invite a client to a tablo
- request a login link by email
- exchange a magic link for a cookie
- clear a client session cookie
- fetch current client identity
- fetch client-visible tablos and tablo-scoped resources

### Client app data access

`apps/clients` should move from this model:

- browser Supabase session
- browser `supabase.from(...)`

to this model:

- browser requests to backend APIs
- cookie attached automatically by the browser
- backend performs identity resolution and authorization

This is the most important architectural migration in the proposal.

## Frontend Impact On `apps/clients`

### Login UI

The login page becomes an email-only form for magic-link requests.

Behavior:

- submit email
- show neutral confirmation state
- no password field
- no self-service signup

### Session bootstrap

The link target should perform an exchange step and then redirect into the client portal.

Possible shapes:

- backend endpoint directly exchanges and redirects
- frontend route receives the token and immediately calls the backend exchange endpoint

The backend-driven exchange-and-redirect path is preferred because it reduces client-side token handling.

### Auth gate

`apps/clients` should no longer check Supabase session state.

Instead it should:

- call a backend "current client" endpoint or equivalent
- treat cookie-backed success as authenticated
- redirect unauthenticated users to the email login page

### Protected data

Every client-visible page should be backed by backend endpoints that enforce `client_access`.

## Migration Strategy

### Phase 1: Schema introduction

- add `public.clients`
- add `public.client_access`
- add `public.client_magic_links`
- optionally add `public.client_auth_events`

### Phase 2: Auth backend

- add magic-link issuance endpoints
- add exchange endpoint
- add cookie verification middleware
- add logout endpoint

### Phase 3: Client portal backend surface

- add backend endpoints for client-visible data currently read directly from Supabase in `apps/clients`
- enforce client authorization there

### Phase 4: Client portal frontend migration

- replace Supabase Auth session handling with cookie-backed auth
- replace direct Supabase browser queries with backend API calls
- update logout behavior

### Phase 5: Invite flow switch

- stop creating or depending on `profiles.is_client`
- stop creating client auth users in Supabase Auth
- switch admin invite actions to the new client-auth flow

### Phase 6: Cleanup

- remove old `is_client` checks in middleware and frontend routing
- remove obsolete client invite/setup code that depends on Supabase Auth
- drop `profiles.is_client` when rollout is complete

## Security And Failure Handling

### Magic-link rules

- magic links must be one-time use
- magic links must expire quickly relative to the session cookie
- expired, missing, or consumed links must fail clearly

Suggested starting TTL:

- invite/login link: `15 minutes` to `1 hour`

### Login enumeration resistance

Self-serve login initiation must return a neutral response such as:

> If this email can access the client portal, a connection link has been sent.

This avoids exposing which emails exist in the client system.

### Rate limiting

Rate limit login-link issuance by:

- email
- source IP

### Cookie failure handling

If session verification fails:

- clear the cookie
- return an unauthorized response or redirect to the client login page

### Link reuse handling

If a link was already consumed:

- show a clear invalid-link state
- offer a way to request a fresh login link

## Testing Strategy

### Database tests

- unique normalized email in `clients`
- unique active access for `(client_id, tablo_id)`
- one-time consumption behavior for `client_magic_links`

### API tests

- inviting a new email upserts a client and grants access
- inviting an already-known email reuses the same global client identity
- self-serve login only issues a link when active access exists, while still returning a neutral response shape
- exchange endpoint consumes a valid link exactly once
- expired or already-consumed links are rejected
- protected client endpoints require a valid cookie
- protected client endpoints enforce `client_access`
- logout clears the cookie

### Frontend tests

- login page sends email-link requests and shows a neutral success state
- invalid or expired links show the right recovery path
- successful exchange redirects to the intended tablo
- authenticated portal routes rely on backend-authenticated cookie state
- logout returns the user to the login page

## Trade-Offs

### Why this is simpler

- no second auth framework in v1
- no session table in v1
- no dependency on Supabase Auth lifecycle for client users
- clean data separation between collaborators and clients

### What this defers

- immediate revocation of active sessions
- device/session inventory
- logout-all-devices
- richer account security features that a framework like `BetterAuth` could eventually help with

## Recommendation

Proceed with a custom backend-owned client auth system based on:

- `public.clients`
- `public.client_access`
- `public.client_magic_links`
- one-time magic links for invite and login
- stateless JWT session cookie
- backend-only authorization for client portal resources

This is the cleanest replacement for `profiles.is_client` and best matches the approved product direction.
