Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

SECURITY.md: the phone apps are in scope, one owner among the admins

Duarte Santos1fd2964aae14
diff --git a/SECURITY.md b/SECURITY.md
index c85e9f8d9..799fb9184 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,8 +1,8 @@
# Security policy
openGym is a self-hosted app: you run the server, you hold the data. This file says which
-versions get fixes, how to report something privately, and — the part most people actually
-need — what the app protects you from and what it doesn't.
+versions get fixes, how to report something privately, and (the part most people actually
+need) what the app protects you from and what it doesn't.
## Supported versions
@@ -37,13 +37,13 @@ what an attacker gets out of it.
**On response times:** this is a hobby project maintained by one person alongside school. There
is no SLA and no bounty. Expect days rather than hours, and longer during exam periods. If a
-week goes by with no reply, comment on the advisory thread — it's more likely to be a missed
+week goes by with no reply, comment on the advisory thread. It's more likely to be a missed
notification than a decision. If a report goes unfixed and you want to disclose publicly, say so
in the thread; there's no objection, and no request to sit on it indefinitely.
## In scope
-- **`api/server.js`** — forging or replaying a session cookie, bypassing passkey verification,
+- **`api/server.js`**: forging or replaying a session cookie, bypassing passkey verification,
reading or writing another user's data through `/api/data`, reaching `/api/admin/*` without
being an admin, or creating a profile without a valid code while `INVITE_ONLY=1`. With
`PASSWORD_LOGIN=1`: getting a password checked past the sign-in throttle, telling which names
@@ -53,22 +53,26 @@ in the thread; there's no objection, and no request to sit on it indefinitely.
pause by switching between name and e-mail. Adding a passkey to a profile that
is not yours, removing a profile's last way in, or redeeming a device code twice, after it
expired, or for a profile it was not made for (`api/passkeys-store.js`, `api/device-link.js`).
-- **Frontend** — XSS in the React app, or anything that lets a page on another origin read or
+- **Frontend**: XSS in the React app, or anything that lets a page on another origin read or
change a signed-in user's data.
-- **Shipped deployment config** — `docker-compose.yml`, `web/nginx.conf.template`, the two Dockerfiles:
+- **Shipped deployment config**: `docker-compose.yml`, `web/nginx.conf.template`, the two Dockerfiles:
a default that exposes something a self-hoster wouldn't expect to be exposed.
- **The published images** `registry.gitlab.com/duartesantos8/opengym/{api,web}` and
`ghcr.io/duartesantos8/opengym-{api,web}`.
+- **The phone apps** (Android APK and Google Play, the iPhone app with its Apple Watch app and
+ widgets): getting the pairing token or a Coach API key out of the phone's secure storage
+ (Android Keystore, iOS Keychain), another app or a web page reaching into openGym's data, or the
+ APK's self-updater installing something that isn't a signed openGym release.
## Out of scope
- Anything that already assumes access to the host, to `./data`, or to the Docker socket. The
- operator is trusted by design — see the security model below.
+ operator is trusted by design, see the security model below.
- Admins reading their users' workout history. That is the documented purpose of the admin
dashboard, not a leak.
- **Missing rate limiting** on anything but password sign-in and device codes, or "I sent 100k
- requests and it got slow". With `PASSWORD_LOGIN=1` the API throttles its password routes —
- sign-in, password signup, reset codes, changing a password — and it always throttles the
+ requests and it got slow". With `PASSWORD_LOGIN=1` the API throttles its password routes
+ (sign-in, password signup, reset codes, changing a password), and it always throttles the
redemption of one-time device codes; nothing else. Volume against the rest, passkey sign-in and
pairing included, belongs in the reverse proxy you put in front of it. A way past that
throttle *is* in scope, and so is genuine amplification (one small request causing unbounded
@@ -85,9 +89,10 @@ in the thread; there's no objection, and no request to sit on it indefinitely.
in the clear. That is the documented trade of running without TLS, not a finding.
- Scanner output with no working exploit, and `npm audit` findings in build-time
devDependencies (Vite, Vitest, Capacitor CLI) that never reach a running instance.
-- The demo build on the website and GitHub Pages — it has no backend at all, everything stays in
+- The demo build on the website and GitHub Pages: it has no backend at all, everything stays in
that browser.
-- Third-party content: the exercise image/GIF dataset and the CDN it's fetched from.
+- The exercise media as such: stills and animations licensed from Gym visual, served as static
+ files by your own instance. How the app handles them is in scope.
## Security model
@@ -106,15 +111,15 @@ Read this before hosting openGym for anyone other than yourself.
not it exists. At most two hashes run at once with a short queue behind them. A first password
needs a fresh passkey assertion by that profile, a change needs the current password (or that
assertion), and either ends every other session of the account. Removing it needs the same
- proof — the password itself or a fresh assertion — and it cannot be removed while it is the
+ proof (the password itself or a fresh assertion), and it cannot be removed while it is the
profile's only way in. Password routes keep the origin check below (no login CSRF).
- An admin can issue a one-time reset code — 60 random bits, stored as a SHA-256, 24 hours, single
- use — which also removes the old password and ends every session; admin accounts cannot be
+ An admin can issue a one-time reset code (60 random bits, stored as a SHA-256, 24 hours, single
+ use), which also removes the old password and ends every session; admin accounts cannot be
reset that way (`api/password.js`, the password block in `api/server.js`).
- **More than one passkey, and one-time device codes.** A profile can hold up to 20 passkeys.
Adding one from Settings, removing one, or making the code that lets another device add its
- own, needs proof that the owner is there right now — a fresh assertion by one of that
- profile's passkeys, made for that one request, or its current password — because an addition
+ own, needs proof that the owner is there right now (a fresh assertion by one of that
+ profile's passkeys, made for that one request, or its current password), because an addition
is a way in that outlives "sign out everywhere", and a removal would let a stolen session
choose which of the owner's ways in is left. The password counts as proof only while
`PASSWORD_LOGIN=1`: with the flag off, a password kept from before is not checked at all, so
@@ -123,24 +128,24 @@ Read this before hosting openGym for anyone other than yourself.
a newer code, signing out everywhere, a new password, an admin reset or a disable voids it. It
never opens a session by itself: redeeming it registers a passkey on that profile (bound to
`ORIGIN`/`RP_ID` like any other), and that passkey signs the device in. The redemption routes
- keep the origin check. A profile's last way in — its only passkey, unless a password can sign
- in — cannot be removed. Every addition, removal, code and redemption is audited
+ keep the origin check. A profile's last way in (its only passkey, unless a password can sign
+ in) cannot be removed. Every addition, removal, code and redemption is audited
(`api/passkeys-store.js`, `api/device-link.js`, the passkeys block in `api/server.js`).
- **Password sign-in is throttled.** Every password route spends a budget of 60 requests a minute
per address; wrong passwords, reset codes and (on password signup) invite codes pause the
address from the 21st on (30 s, doubling to 15 min); wrong passwords pause the *account* from the 6th on (1 min,
- doubling to 1 h) — keyed by the account the name or sign-in e-mail resolves to, so switching
+ doubling to 1 h), keyed by the account the name or sign-in e-mail resolves to, so switching
between the two does not reset it, and by the identifier as typed when it resolves to nobody. A password check is counted the moment it starts, so guesses
sent all at once get no more checks than guesses sent one by one. The two routes that redeem a
device code share that budget, and wrong codes pause the address the same way, for code
redemption only. Passkey sign-in, passkey signup and pairing are not throttled at all, so nobody
- can pause them — not even behind a proxy that shows the API one address for every visitor. The address is the socket peer unless
+ can pause them, not even behind a proxy that shows the API one address for every visitor. The address is the socket peer unless
`TRUST_PROXY=1` (set by the bundled compose file, where only the web container reaches the
API), and IPv6 is counted per /64 (`api/rate-limit.js`).
- **A sign-in e-mail is an identifier, never a channel.** With `PASSWORD_LOGIN=1` a profile may add
an e-mail address to type at the password sign-in instead of its name. Nothing is ever sent to it
(there is no mail server): no verification, no reset mail, so it is not proven to be anyone's
- and grants nothing on its own — the password still does. Adding, changing and removing it take
+ and grants nothing on its own; the password still does. Adding, changing and removing it take
the same proof as a password (`proveOwner`). It is folded like a name (NFKC, trimmed,
lower-cased; at most 254 characters), unique across profiles and never another password
holder's name, so an identifier never points at two accounts. Taking one in use answers `409
@@ -168,7 +173,7 @@ Read this before hosting openGym for anyone other than yourself.
- **Any user can end every session they have.** `POST /api/logout/all` increments that account's
session version, and every request a session authenticates checks the version in it against the
one on the user record (`sessionVersion`, `sessionOf`), so every cookie ever
- issued for the account — on every device, including a copy someone walked off with — stops
+ issued for the account (on every device, including a copy someone walked off with) stops
verifying at once. Passkeys are untouched; signing back in works immediately.
- **Data is isolated per user by the session's uid.** `GET`/`PUT /api/data` only ever touch
`state-<uid>.json` for the caller (both resolve it with `readSession`); no route lets a normal
@@ -179,9 +184,9 @@ Read this before hosting openGym for anyone other than yourself.
server connects out to and it comes from whoever is signed in, so `/api/push/*` would otherwise
be a request-forgery lever from inside the Docker network. It must be `https:`, and the
connection is refused at socket level if the host resolves to a loopback, private, link-local
- (including cloud metadata) or CGNAT address — enforced in the agent's DNS lookup for hostnames,
- so there is no rebinding window, and for literal IP addresses — which never go through that
- lookup — by the same address check at subscribe time and again before every send, applied to
+ (including cloud metadata) or CGNAT address. That is enforced in the agent's DNS lookup for hostnames,
+ so there is no rebinding window, and for literal IP addresses (which never go through that
+ lookup) by the same address check at subscribe time and again before every send, applied to
every textual form of the address (`isPrivateAddr`, `guardedLookup` and `pushEndpointError` in
`api/server.js`). Sends have a 10 s timeout
(a stalling endpoint used to hang the request handler indefinitely), run at most 6 at a time
@@ -192,11 +197,11 @@ Read this before hosting openGym for anyone other than yourself.
back.** People can attach one photo, GIF or short video to an exercise they made, and up to
six to a workout they logged. The server
decides what a file is from its first bytes, never from its name or the type the client
- declared, and stores JPEG, PNG, WebP, GIF, MP4, MOV and WebM only — SVG, HTML and everything
+ declared, and stores JPEG, PNG, WebP, GIF, MP4, MOV and WebM only; SVG, HTML and everything
else is refused. It never decodes a file, so there is no image or video parser to attack. Each
file is named by its SHA-256, which the upload has to match, and kept per profile in
`./data/uploads/<uid>/` (folders `0700`, files `0600`, out of the Coach runtime's reach). It is
- served to its owner only — no admin, Coach or plan-sharing route reads one — with a fixed
+ served to its owner only (no admin, Coach or plan-sharing route reads one), with a fixed
`Content-Type`, `nosniff`, `Content-Security-Policy: default-src 'none'; sandbox`,
`Cross-Origin-Resource-Policy: same-origin` and `Cache-Control: private, no-store`. Uploads
need the same session and origin check as every other write, are capped per file, per profile
@@ -218,11 +223,11 @@ Read this before hosting openGym for anyone other than yourself.
their complete workout history and body-weight log, `audit.log`, `secret`, and `vapid.json`, and
once the Coach is set up `coach.json`. The Coach's provider credential is the one thing stored
encrypted there, with a key derived from `secret` in the same folder, so it is no safer from
- whoever holds the folder. Anyone who can read that folder — you,
- whoever holds the backups, whoever gets into the host — can read every user's data, and with
+ whoever holds the folder. Anyone who can read that folder (you,
+ whoever holds the backups, whoever gets into the host) can read every user's data, and with
`secret` can mint a valid session cookie for any account. **If you host openGym for other
people, they are trusting you exactly as much as they'd trust any server operator.** With the
- activity log on, `./data/audit.log` adds everyone's sign-in times to that — worth remembering
+ activity log on, `./data/audit.log` adds everyone's sign-in times to that, worth remembering
before an archive of `./data` goes somewhere you don't run.
- **Photos and videos are not encrypted either, and a removed one lingers.** Whoever can read
`./data/uploads/` can see every profile's files. A file its owner stopped using is kept for
@@ -230,15 +235,17 @@ Read this before hosting openGym for anyone other than yourself.
"Reset everything". Location data is removed by the app before a file leaves the device, not by
the server: photos are re-encoded (no EXIF or GPS survives) and the metadata boxes and
telemetry tracks of MP4/MOV videos are blanked, but WebM videos are uploaded as recorded, and a
- client other than the app can upload a file with its metadata intact — readable, still, only by
- that same profile.
+ client other than the app can upload a file with its metadata intact (readable, still, only by
+ that same profile).
- **Admins can read everything.** A user listed in `ADMIN_UIDS` (or flagged `admin: true` in
`db.json`) gets every user's full history and body weight, can disable or delete accounts, and
can create or revoke invite codes (the `/api/admin/*` routes in `api/server.js`). Off by
- default — a fresh instance has no admin.
+ default: a fresh instance has no admin. One admin is the **owner** (on an existing instance, the
+ oldest admin): only the owner makes or removes admins, deletes an admin, hands the role on or
+ clears the activity log (`requireOwner`).
- **Sessions can't be revoked one device at a time.** Revocation is per *account*, not per
session: `POST /api/logout/all` kills all of them at once and there is no device list to pick
- from. `POST /api/logout` on its own only clears the cookie in that one browser — a copy taken
+ from. `POST /api/logout` on its own only clears the cookie in that one browser; a copy taken
beforehand keeps working. Sessions last **90 days** by default, settable with `SESSION_DAYS`;
each cookie carries the lifetime it
was issued with, so changing the setting doesn't reach cookies that are already out. Deleting
@@ -246,12 +253,12 @@ Read this before hosting openGym for anyone other than yourself.
still locks out one user completely.
- **CSRF protection is `SameSite=Lax` plus an origin check, not tokens.** There are no CSRF
tokens. `SameSite=Lax` alone was not enough: it keeps the cookie off a cross-*site* request but
- a sibling subdomain (`gym.example.com` vs anything else under `example.com` — one domain, one
+ a sibling subdomain (`gym.example.com` vs anything else under `example.com`: one domain, one
reverse proxy, several apps, i.e. the usual self-hosting layout) is the *same* site and does
get the cookie. So every state-changing request that a browser sent must also be
`Sec-Fetch-Site: same-origin` (or `none`, which only the user's own navigation produces), or
carry an `Origin` equal to `ORIGIN` where that header is missing (`csrfOk`). Requests a Bearer
- token authenticates skip the check — a browser never attaches one by itself, so there is no
+ token authenticates skip the check: a browser never attaches one by itself, so there is no
ambient authority to borrow. The token has to verify and be the only credential (no session
cookie beside it), so a header that merely starts with `Bearer ` switches nothing off, and it
buys nothing on the sign-in routes (passkey, password, reset code, device code), where what the
@@ -267,7 +274,7 @@ Read this before hosting openGym for anyone other than yourself.
unlocked device ≈ account access.
- **Recovery is another passkey, or an admin.** A profile can hold several passkeys, and a
signed-in device can give a new one its own with a device code; there is no email path. Lose
- every passkey (and every signed-in device) and that profile is unreachable — unless the
+ every passkey (and every signed-in device) and that profile is unreachable, unless the
instance runs `PASSWORD_LOGIN=1`, where an admin can issue a reset code that sets a password on
it. Without that, only direct surgery on `./data` gets it back.
- **A device code is a capability, and removing a passkey does not end sessions.** Anyone who
@@ -289,7 +296,7 @@ Read this before hosting openGym for anyone other than yourself.
that was paused; the `409 email-taken` answer says an address is in use on the instance (never
by whom), at the rate the throttle allows. Only two password checks run at once, with 32 queued behind
them: someone sending from enough addresses can keep that queue full, and every password
- sign-in then answers `503` until they stop — passkeys are unaffected. The only password
+ sign-in then answers `503` until they stop (passkeys are unaffected). The only password
policy is 10–256 characters and a short built-in list of the passwords guessing scripts try
first; no breached-password database is bundled.
- **Disabling someone isn't a ban.** They can still register a fresh profile with a new passkey
@@ -306,7 +313,7 @@ Read this before hosting openGym for anyone other than yourself.
the password routes and to device-code redemption; passkey sign-in and signup, pairing, writes
and everything else behind a session are not limited, so an instance on the open internet should have a rate limit in front of it. `POST
/api/register/options` still answers whether an invite code is valid, unthrottled. New invite
- codes are 16 hex characters — 64 bits — which makes guessing one impractical even unthrottled;
+ codes are 16 hex characters (64 bits), which makes guessing one impractical even unthrottled;
codes generated by earlier versions are 8 characters / 32 bits and still work, so revoke and
reissue any that are still unused. With the Coach on, its jobs are capped separately
(`perProfileDaily`, 10 by default; `instanceDaily`, unlimited by default). The other hard limit
@@ -314,22 +321,22 @@ Read this before hosting openGym for anyone other than yourself.
- **The activity log is not an audit archive, and it records less than you might assume.** No IP
address unless you set `AUDIT_IP` (`net` truncates to a /24 or /48; the default is `off`). When it is on, the
address comes from `CF-Connecting-IP`, `X-Forwarded-For`, `X-Real-IP` or, failing all three,
- the connecting socket — so it is only as trustworthy as whatever sits in front, which has to
+ the connecting socket, so it is only as trustworthy as whatever sits in front, which has to
*overwrite* those headers rather than pass a client-supplied one through. The bundled web
container now does: it replaces `X-Forwarded-For`/`X-Real-IP` with the real peer and drops
`CF-Connecting-IP` unless you set `CF_CONNECTING_IP='$http_cf_connecting_ip'` in `.env` (the
single quotes stop Compose from expanding it to an empty string), which is correct only with
Cloudflare genuinely in front. Before that it appended to `X-Forwarded-For` and
- passed `CF-Connecting-IP` straight through, and the API reads the first entry — so any caller
+ passed `CF-Connecting-IP` straight through, and the API reads the first entry, so any caller
could choose the address recorded against it. Never the browser's user-agent,
- and never the passkey id behind a failed sign-in — that id is a stable
+ and never the passkey id behind a failed sign-in: that id is a stable
handle for one device, and storing it would let an admin follow an unknown device from attempt
to attempt. So a failed sign-in from a passkey this instance doesn't know is recorded as a time
- and nothing else. Retention is a cap, not an archive: old events are dropped, not exported. Any
- admin can clear the whole log from the dashboard. And several of the paths that write to it —
- the invite check on `POST /api/register/options`, the expired-challenge and unknown-passkey
+ and nothing else. Retention is a cap, not an archive: old events are dropped, not exported. The
+ owner can clear the whole log from the dashboard. And several of the paths that write to it
+ (the invite check on `POST /api/register/options`, the expired-challenge and unknown-passkey
branches of the register/login handshakes, a pairing code that does not redeem, and, with
- passwords on, the failed password and reset-code attempts (within their throttle) — are
+ passwords on, the failed password and reset-code attempts (within their throttle)) are
reachable **without a session**, so anyone
can fill the log with noise. It is an append of ~110 bytes per
event to a capped file, never a rewrite of `db.json`, so the cost is a log full of noise rather
@@ -344,6 +351,6 @@ Read this before hosting openGym for anyone other than yourself.
instance only someone with a valid code gets that far.
- **Changing `RP_ID` invalidates every existing passkey.** They were bound to the old hostname
and will fail verification against the new one. The data stays on disk but is unreachable until
- each user registers again — as a *new* profile. Choose your hostname before anyone registers.
+ each user registers again, as a *new* profile. Choose your hostname before anyone registers.
- **Guest mode never reaches the backend.** That data lives unencrypted in the browser's
`localStorage` and is gone when the browser storage is cleared.