Repository navigation
ADR 0035
Status: accepted · Built: planned · Date: 2026-11-19 · Supersedes: 0016, 0018 · Superseded by: 0051
Built: the auth service (Better Auth behind Node's HTTP server, not Fastify) with guests, bearer tokens and EdDSA JWTs in the auth schema of the apps database, the deploy's roles and schema, idle-guest cleanup and a nightly dump of auth. Found while building: Better Auth's dynamic base URL trusts every origin its host patterns match, so the service keeps one Better Auth per host, each with that host as its base URL; the guest limit is therefore per host. Apps may read only id, is_anonymous, created_at and updated_at of auth.users. Better Auth turns its origin check off under a test runner, so it is set on explicitly. Also built: the Caddy route on every app domain and auth.<APPS_DOMAIN>/main, and the dashboard's Users page for the pool (the agent reads users and sessions and deletes users through grants from the pool). Also built: moving an app that kept its own guests (POST /apps/:name/move, a form in the dashboard). Its cookies are signed with its own AUTH_SECRET, which the pool lacks, so that secret goes into auth.former_secrets and the pool re-signs such cookies with its own. The old database is kept, not dropped. To build: moving sokobanko and vinskiano themselves. Sign-in, sign-out and turning a guest into a user come later. Partly superseded by 0051: the one-time move (POST /apps/:name/move and the dashboard's form) is removed; an instance moves its apps with 0.14 before upgrading.
ADR 0016 put guest accounts in a library, the kit, with an auth schema in each app's own
database. ADR 0018 let the dashboard read and delete those rows. Since then:
- An owner's apps belong together (LibreLifts and LibreBars, say), and a person should have one account across them, as in a Supabase project.
- The LibreLifts and LibreBars APIs, client-side apps with Expo clients, run their own Better Auth. The kit could not serve them, because it is for server-rendered apps only.
- Every app database had its own copy of the
authtables, migrated by the platform.
Apps now share one instance database with a schema each (ADR 0034). This record replaces ADRs 0016 and 0018.
-
One pool per instance, called
main, served by a small auth service in Spotcraft's image (ADR 0025 pattern): Fastify with Better Auth. The pool's name appears in its paths and key ids, so more pools can be added later without breaking anything. -
Storage: the
authschema of the instance database, owned by the auth service's role,spotcraft_auth, which also runs its migrations. Apps (thespotcraft_approle every app role belongs to) maySELECTandREFERENCESauth.users, and nothing else inauth. Backups dump it on its own. -
For now, users are guests. Better Auth plugins:
anonymous,bearer(for clients without cookies) andjwt(short-lived tokens and a JWKS). Ids are UUIDs. -
Two ways to reach the pool:
- On every app's domain, Caddy proxies
/_spotcraft/auth/*to the pool. Cookies stay first-party on the app's domain, and there's no CORS.AUTH_URLis this address. -
https://auth.<instance domain>/mainis for clients without such a domain (Expo apps, sites not on Spotcraft yet). It uses bearer tokens, and CORS allows the instance's app domains plus a list of extra origins in the instance's settings.
- On every app's domain, Caddy proxies
-
Apps trust a JWT. Claims:
iss(the pool),sub(the user id),is_anonymous,iat,exp. Apps check the signature againstAUTH_JWKS_URLand the issuer againstAUTH_ISSUER. -
App tables reference users with
user_id uuid references auth.users (id) on delete cascade(orset null), as in Supabase. Deleting a user deletes their rows in every app. A foreign key that would block the delete (restrict,no action) is a bug in that app: the delete fails and the dashboard says which table blocked it. - Limits: a cap on new guests per client address (Better Auth's rate limit, with the address from Caddy's X-Forwarded-For, ADR 0031). Guests unused for 180 days are deleted (an instance setting).
-
The dashboard has a Pool page: guest count, users, delete. The per-app Users tab and the
agent's
/apps/:name/usersroutes go away. -
Moving the existing guests: the kit's
authtables already follow Better Auth's model. A one-time move copies an app's users and sessions into the pool with the same ids and tokens, and its own tables into its schema, with their foreign keys pointing at the pool'sauth.users. The pool uses the kit's cookie name, so a guest keeps their cookie and their data. The app's old database is then dropped.
- One account across an owner's apps, and client-side and mobile apps can have users too.
- No deletion events to deliver, retry or handle: the database keeps app data consistent with the pool.
- Apps can read every user of the instance, not only their own. For guests that is an id and timestamps; when sign-in adds emails, the columns apps may read get decided again.
- The auth service is shared: when it's down, apps can't create guests or refresh tokens. Apps that only verify JWTs keep working until the tokens expire.
- Guests in one app are not guests in another: each app creates its own until sign-in links them to one account, which a later record decides.
Published from docs/. Edit the files there; changes here are overwritten.