Repository navigation
0017 better auth
Status: accepted · Implementation: done · Date: 2026-11-18
From LibreLifts ADR 0029, version 1.7.20. Better Auth had several security advisories in 2026, one of them critical. Built 2026-11-18 at 1.7.20, with the anonymous and Expo plugins and telemetry off. Two files in the API import it and one in the app.
The API owns LibreBars' accounts (0015), and every install starts as a guest (0016). Something has to create those accounts, keep their sessions, and later turn a guest into a full account without losing its data.
Writing this by hand means owning the security of it. Hosted sign-in services would put the project's accounts in someone else's hands. Better Auth is an open-source library that runs inside the API and keeps its data in the project's own Postgres.
- Accounts are handled by Better Auth, running inside the Fastify API and storing its data in Postgres.
- Guests use its anonymous accounts.
- The app uses its Expo support, which keeps the session in the device's secure storage. The website uses a session cookie from the API.
- Its version is pinned exactly. An update is a change of its own, made after reading what changed.
- As few files as possible import it: one in the app, and in the API the file that sets it up and the plugin that mounts it.
- It sends nothing to its makers. Its telemetry is switched off.
- The parts that are easy to get wrong, such as sessions and sign-in methods, are not written here.
- The project depends on a fast-moving library for something that must not break. Its advisories have to be watched.
- Its tables live in the project's database, in a schema of their own, and are migrated with the rest.
- If it has to be replaced, accounts are rows in the project's own Postgres and can be read without it.
Generated from docs/ on dev. Edit the docs there; changes made on the wiki are overwritten.
- Development
- Workflow
-
Decisions
- 0001 Decisions are recorded
- 0002 Apache License 2.0
- 0003 Changes land on dev by fast-forward; main is the last release
- 0004 Conventional Commits, Keep a Changelog and Semantic Versioning
- 0005 docs/ is for developers and is mirrored to the wiki
- 0006 LibreBars is a free workout log for calisthenics
- 0007 The tracker is an iOS and Android app; its web build stays until the store release
- 0008 LibreBars is an app and a crowd-sourced open database
- 0009 The database is ODbL, media is CC BY-SA, and neither can be closed later
- 0010 A hosted API with a free tier is the paid product
- 0011 The workspace is app, web and api, with engine, ui, data and contracts
- 0012 The engine is small pure functions, in the style of date-fns
- 0013 Web and app share a Tailwind theme, not components
- 0014 Postgres is the source of truth for all data
- 0015 The API is Fastify, and it owns LibreBars accounts
- 0016 Every install is a guest account, made in the background
- 0017 Accounts use Better Auth
- 0018 The on-device database is SQLite with Drizzle, on every platform
- 0019 Sync is our own push and pull
- 0020 The app says it backs up, and backup can be turned off
- 0021 Postgres 18, run with Docker Compose and tested on two databases
- 0022 expo-sqlite is patched so the web build reuses one buffer
- 0023 Seed data is TypeScript modules in packages/data, with permanent ids
- 0024 The first tables
- 0025 One TanStack Start app is the website, on GitHub Pages
- 0026 The catalog reaches the app as a snapshot plus updates, and the website through the API
- 0027 The app's first components are its own