Skip to content

0030 spotcraft user pool

github-actions[bot] edited this page Nov 19, 2026 · 1 revision

Accounts are guests of Spotcraft's user pool, and the API runs on Spotcraft's contract

Status: accepted · Implementation: done · Date: 2026-11-19 · Supersedes: 0017

From LibreLifts ADR 0039. Partly supersedes 0015: the API no longer keeps accounts; the rest stands. Partly supersedes 0016: the session is a bearer token in secure storage (local storage in the web build), and the limit on new guests is the pool's; the rest stands. Partly supersedes 0021: Postgres for development and tests comes from spotcraft dev, not the repository's Compose file, and the tests no longer run on PGlite; Postgres 18 stands. Spotcraft 0.6, @kodentuzo/spotkit 0.1.0. The API isn't deployed yet: it goes to the LibreVitalis instance later.

Context

The API kept LibreBars' accounts itself, with Better Auth's anonymous accounts in its own auth schema (0015, 0016, 0017), on a Postgres the repository ran with Docker Compose and, in tests, on PGlite (0021).

The API will run on Spotcraft, which hosts the owner's apps. Since 0.6, a Spotcraft instance has one user pool for every app on it: Better Auth with guests, bearer tokens and signed JWTs, reached at /_spotcraft/auth on every app's domain. Each app gets a schema of its own, app_<slug>, in the instance's database, may point foreign keys at the pool's auth.users, and has its migrations run from an image label before a new version starts. spotcraft dev runs the same stack locally, one per repository. LibreLifts made the same move first.

Decision

  • Every account is a guest of the instance's user pool. The app makes its guest there, never the API. The API keeps no accounts and no sessions: @kodentuzo/spotkit checks the pool's token on each request and gives the account's id.
  • The app sends the pool's session token as Authorization: Bearer …, to the pool and to the API, on every platform. On a phone it's in the device's secure storage; in the temporary web build, in local storage. No cookies cross between sites.
  • The pool is at the API's own address, <API>/_spotcraft/auth, so the app needs one address. On Spotcraft, Caddy answers that path; locally the API passes it on to the stack's pool.
  • The personal tables are in the API's schema, app_librebars_api, and every user_id points at auth.users with on delete cascade: deleting a guest in the pool deletes their data.
  • Migrations start again from one that creates today's tables in that schema. A small runner applies drizzle-kit's files, because Drizzle's own migrator first tries to create a schema, which the API's role may not. The image's dev.spotcraft.migrate label runs it.
  • Development and tests use spotcraft dev: its Postgres and its pool, with the settings it writes to .env. The repository's Compose file and the in-process Postgres go. The API's tests make real guests in the pool.
  • The API has an image, built and checked in CI.

Consequences

  • The API has no account code to keep secure, and no Better Auth to pin; the pool does.
  • Running the API's tests needs Docker and spotcraft dev, in CI too.
  • The limit on new guests is the pool's, per address, and works with any number of API instances.
  • Guests made by the old API aren't carried over. None exist outside developers' machines: the API was never deployed.
  • Signing up, signing in and turning a guest into a full account are the pool's to add.

LibreBars

Clone this wiki locally