CivicLoop by Ta-Tech Solutions All documents

Authentication & RBAC

How sign-in, roles, and row-level security work in CivicLoop County OS.

Sign-in flow

Staff go to /[locale]/login, enter email + password (Supabase Auth).
On success a session cookie (httpOnly) is set. requireStaff(locale, minRole) runs on every gated route/server action and redirects to /login (307) when there is no valid staff session.
Sensitive surfaces can additionally require AAL2 (TOTP MFA via /mfa).
Residents are never required to authenticate to file or track a 311 request.

Roles (ascending privilege)

Role	Can do
`agent`	Work the 311 queue, reply to residents, resolve with evidence
`supervisor`	All agent rights + agency modules (KPIs + manage records) + data feeds + assistant
`department_head`	Supervisor rights, scoped to their department
`director`	County-wide dashboard, council views, automations
`county_admin`	Admin console: staff, roles, 2FA status, locations

requireStaff takes a minimum role; a higher role satisfies a lower requirement.

Platform tier (TaTech engineers) - separate from tenants

The county boss is the tenant admin (county_admin, /admin). TaTech engineers are a separate tier: rows in platform_admins with access levels owner > engineer > support, gated by requirePlatformAdmin at /[locale]/platform (the Platform Console). They are not county staff and have no tenant role.

Kill-switch: owner/engineer can suspend or restore a tenant (county). A suspended tenant's staff are redirected to /suspended; platform admins can still inspect via impersonation. Enforced in requireStaff.
Impersonation: any platform admin can "view as" a tenant - a synthetic county_admin session with an amber banner and a one-tap exit. Every start/stop is written to platform_impersonations.
No self-promotion: platform admins are seeded via the service role (scripts/seed-platform-admins.mjs); an owner manages others but cannot change their own row.

Row-Level Security (defense in depth)

Every table has RLS enabled. Read policies scope rows to the staffer's county via county_id in (select county_id from staff where auth_user_id = auth.uid()).
Writes happen only inside server actions/routes that first call requireStaff, using the service-role admin client. A flaw in the UI cannot bypass the database boundary.
Public read paths (the /public portals, Open311) use the admin client on the server and return only public-record aggregates - never PII.

Secret-gated machine endpoints (no user session)

POST /api/automations, POST /api/cron/synthetic - header x-automation-secret: $AUTOMATION_SECRET.
POST /api/feeds/ingest - header x-feeds-secret: $FEEDS_INGEST_SECRET.
All return 503 when their secret is unset and 401 on a wrong secret.

Common outcomes

Situation	Result
No staff session on a gated route	307 redirect to `/login`
Role too low	redirect / not-authorized
Valid session, MFA required, not enrolled	nudge to `/mfa`
Machine endpoint, secret unset	503 `not_configured`
Machine endpoint, wrong secret	401 `unauthorized`

PreviousAutomation & Triggers NextTrust & Security

CivicLoop - Ta-Tech Solutions - Architecture & Design Documentation