Optional account system layered on top of the anonymous-first reporting flow from plan/06-mobile-app.md. Users can:
These are non-negotiable; every later decision derives from them.
POST
/v1/reports accepts an unauthenticated request and returns a
one-time claim_token.POST /v1/auth/claim. The default is to not attach.auth.users (private) and never appears on public.observation
or the public dashboard, even for reports the user has attached
to their account.@privaterelay.appleid.com)
is a first-class email format we must support.DELETE /v1/auth/me
removes the user record and detaches them from any reports they
had previously linked (the report itself stays in the graph; the
user_id ↔ observation_id edge is severed).| Route | Purpose |
|---|---|
/sign-in |
Email + password, magic-link, and three OAuth buttons (Google, Apple, Facebook — Apple first per Guideline 4.8). |
/sign-up |
Same component; just a toggle. Email-verification email goes out on submit. |
/auth/callback |
OAuth-provider redirect target. Reads code + state from the URL, hands off to the provider SDK. |
/account |
Authenticated profile: name (optional), home ZIP, contact channels, language, accessibility needs, consent toggles — all opt-in. |
/account/reports |
List of reports the user has attached to their account. The user can detach any one (severs the link, leaves the report intact). |
/account/delete |
Account deletion. Requires re-auth. Cascades to detach (not delete) attached reports. |
The pilot uses Supabase Auth.
Why:
supabase-js SDK works
against the hosted service or against a self-hosted Supabase
instance. The pilot uses the hosted service; v1 migrates to a
self-hosted Postgres + Supabase Auth if data sovereignty needs
demand it.consent_profile work from
schema/deep/application.sql.output: 'export';
the OAuth dance happens on Supabase’s domain, and the React
client only ever sees the resulting JWT.Alternatives considered:
| Option | Why not |
|---|---|
| Auth.js (NextAuth) | Needs Next.js API routes (server runtime). Breaks output: 'export'. |
| Clerk | Excellent DX but proprietary and costs money at scale. |
| Auth0 | Same — proprietary, paid. |
| Custom (PyJWT + Authlib + bcrypt) | Weeks of work to get OAuth + email-verify + password-reset + session-refresh right. Not worth it for the pilot. We can migrate later. |
┌────────────────────────────────────────────────────────────────┐
│ Next.js app (browser) │
│ │
│ @supabase/supabase-js ←─── OAuth + email + magic link │
│ │ │
│ ▼ │
│ Supabase JWT in HttpOnly cookie + memory │
│ │ │
│ ▼ │
│ fetch('/api/v1/...', { headers: { Authorization: 'Bearer …'}})│
└──────────────────────────────┬─────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────┐
│ FastAPI backend (agents/src/onehealth_agents/api/) │
│ │
│ • verify JWT against Supabase JWKS │
│ • look up user_id in auth.users (Postgres) │
│ • run the agent chain from plan/03 │
│ • write observation to DuckLake (precise zone or public) │
└────────────────────────────────────────────────────────────────┘
The React app never talks to our backend for sign-in. It uses the Supabase JS SDK directly, which handles every flow (email + password, magic-link, three OAuth providers, password reset, email verify, session refresh). The resulting JWT is then attached to every call to our backend.
The backend doesn’t trust the client. It validates each JWT against
Supabase’s published JWKS, extracts the sub claim (the user id),
and looks up the user in the same Postgres database (Supabase Auth
keeps auth.users rows alongside our public.* tables).
The Intake API supports four transition flows:
POST /v1/reports → { observation_id, claim_token }
GET /v1/reports/{id} ← Authorization: Claim <token>
PATCH /v1/reports/{id}/profile ← Authorization: Claim <token>
POST /v1/reports → { observation_id, claim_token }
... user later signs in ...
POST /v1/auth/claim { claim_token }
→ 204; observation_id is now linked
to auth.user_id
POST /v1/reports ← Authorization: Bearer <jwt>
payload includes { attach: false }
→ { observation_id, claim_token }
← observation has no user_id link
This is the workplace-whistleblower case: a signed-in user files an Environmental report anonymously even though we know who they are. The server still returns a claim_token so they can manage the report later (e.g. add a photo) without ever having touched their account.
POST /v1/reports ← Authorization: Bearer <jwt>
payload includes { attach: true }
→ { observation_id }
← observation.user_id = current user
email + openid scopes only. No profile.read,
no Drive, no Calendar, no Contacts.email only. No public_profile photo, no Friends
list, no Pages.<random>@privaterelay.appleid.com).
These addresses are stored exactly like any other; relay forwarding
is Apple’s concern.Supabase Auth gives us auth.users for free. We add a thin layer
on top in public.profile:
-- schema/deep/auth.sql (Phase 07.1 deliverable)
CREATE TABLE public.profile (
user_id uuid PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
display_name text,
home_zip text CHECK (home_zip ~ '^[0-9]{5}$'),
primary_language text,
accessibility_needs text[],
contact_email_opt_in boolean NOT NULL DEFAULT false,
contact_sms_phone text,
contact_sms_opt_in boolean NOT NULL DEFAULT false,
precise_location_consent boolean NOT NULL DEFAULT false,
share_photo_gps_animal_env boolean NOT NULL DEFAULT false,
share_photo_gps_human boolean NOT NULL DEFAULT false,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);
-- One-to-many: a user can attach many observations; an observation
-- has at most one user_id link. ON DELETE SET NULL preserves the
-- observation under right-to-erasure.
ALTER TABLE public.observation
ADD COLUMN user_id uuid REFERENCES auth.users(id) ON DELETE SET NULL;
Row-level security policies:
-- A user can read / update only their own profile row.
ALTER TABLE public.profile ENABLE ROW LEVEL SECURITY;
CREATE POLICY profile_self_read ON public.profile FOR SELECT USING (auth.uid() = user_id);
CREATE POLICY profile_self_update ON public.profile FOR UPDATE USING (auth.uid() = user_id);
-- A user can read only their own attached observations.
CREATE POLICY observation_self_read
ON public.observation
FOR SELECT
USING (auth.uid() = user_id);
Agency dashboards (MCDPH, ADHS, etc.) get separate Postgres roles that bypass RLS for governance-board-approved cohort queries; the tribal-data row-level suppression from plan/02 stays in force.
api/openapi.yaml gets a new auth tag with:
| Endpoint | Purpose |
|---|---|
GET /v1/auth/me |
Current user (JWT-authenticated). Returns the user and their public.profile row. |
PATCH /v1/auth/me |
Update the user’s profile. Per-field consent toggles default off; setting a value implies opt-in. |
DELETE /v1/auth/me |
Right to erasure. Cascades to detach (NOT delete) attached observations. |
POST /v1/auth/sign-out |
Invalidate the current session. (The Supabase JS SDK handles the local clear; this endpoint exists so server-side audit logs see the event.) |
POST /v1/auth/claim |
Attach a claim_token (from a previously anonymous report) to the current user. Optional and idempotent. |
The sign-in / sign-up / OAuth dance itself is not in our spec — the React client talks to Supabase directly for that. Our spec documents only the part our backend serves.
| Path | Component |
|---|---|
app/src/lib/auth.ts |
Supabase JS client + useSession() hook + useUser(). |
app/src/components/AuthProvider.tsx |
React context that subscribes to supabase.auth.onAuthStateChange and exposes the session to the rest of the app. |
app/src/app/sign-in/page.tsx |
Sign-in / sign-up page. Apple first, then Google, then Facebook. Email + magic-link below. |
app/src/app/auth/callback/page.tsx |
OAuth-callback handler. Reads the URL hash, calls supabase.auth.getSession(), redirects to / or to the next query param. |
app/src/app/account/page.tsx |
Authenticated settings page. |
app/src/app/account/reports/page.tsx |
Attached-reports list. |
The landing page (/) reads useSession() and shows a “Sign in”
button when signed out, or a small chip with the user’s display
name when signed in. The three-button picker is unchanged either
way.
.env.local (not committed)./v1/auth/me, /v1/auth/claim, /v1/auth/sign-out
to real Supabase JWT validation. Add schema/deep/auth.sql with
the public.profile table and RLS policies. Apple-private-relay
smoke test.public.observation RLS.