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.
JavaScript apple-watchbodyweightdockerfitnessfitness-trackergymhealthiosmcpnodejspasskeysprogressive-web-applicationspwareactself-hostedself-hostingvitewebauthnweightliftingworkout-tracker
SECURITY.md: the phone apps are in scope, one owner among the admins
Duarte Santos1fd2964aae14
diff --git a/SECURITY.md b/SECURITY.mdindex c85e9f8d9..799fb9184 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -1,8 +1,8 @@# Security policyopenGym 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. Thereis 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 missednotification than a decision. If a report goes unfixed and you want to disclose publicly, say soin 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/*` withoutbeing 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 thatis not yours, removing a profile's last way in, or redeeming a device code twice, after itexpired, 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 orchange 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 admindashboard, 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 theredemption of one-time device codes; nothing else. Volume against the rest, passkey sign-in andpairing included, belongs in the reverse proxy you put in front of it. A way past thatthrottle *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-timedevDependencies (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 inthat 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 passwordneeds a fresh passkey assertion by that profile, a change needs the current password (or thatassertion), 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 theprofile'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 bereset 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 additionis a way in that outlives "sign out everywhere", and a removal would let a stolen sessionchoose 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. Itnever 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 minuteper address; wrong passwords, reset codes and (on password signup) invite codes pause theaddress 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 switchingbetween 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 guessessent all at once get no more checks than guesses sent one by one. The two routes that redeem adevice code share that budget, and wrong codes pause the address the same way, for coderedemption 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 theAPI), 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 addan 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 takethe 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 passwordholder'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'ssession version, and every request a session authenticates checks the version in it against theone 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) stopsverifying 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 otherwisebe a request-forgery lever from inside the Docker network. It must be `https:`, and theconnection 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 toevery 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 tosix to a workout they logged. The serverdecides 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 everythingelse is refused. It never decodes a file, so there is no image or video parser to attack. Eachfile 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`. Uploadsneed 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`, andonce the Coach is set up `coach.json`. The Coach's provider credential is the one thing storedencrypted 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 otherpeople, 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 rememberingbefore 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 bythe server: photos are re-encoded (no EXIF or GPS survives) and the metadata boxes andtelemetry 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, andcan 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 persession: `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 takenbeforehand keeps working. Sessions last **90 days** by default, settable with `SESSION_DAYS`;each cookie carries the lifetime itwas 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 CSRFtokens. `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, onereverse proxy, several apps, i.e. the usual self-hosting layout) is the *same* site and doesget 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), orcarry 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 noambient authority to borrow. The token has to verify and be the only credential (no sessioncookie beside it), so a header that merely starts with `Bearer ` switches nothing off, and itbuys 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 asigned-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 theinstance runs `PASSWORD_LOGIN=1`, where an admin can issue a reset code that sets a password onit. 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 (neverby whom), at the rate the throttle allows. Only two password checks run at once, with 32 queued behindthem: 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 passwordpolicy is 10–256 characters and a short built-in list of the passwords guessing scripts tryfirst; 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, writesand 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 andreissue 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 IPaddress unless you set `AUDIT_IP` (`net` truncates to a /24 or /48; the default is `off`). When it is on, theaddress 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 webcontainer 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` (thesingle quotes stop Compose from expanding it to an empty string), which is correct only withCloudflare 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 callercould 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 stablehandle for one device, and storing it would let an admin follow an unknown device from attemptto 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-passkeybranches 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)) arereachable **without a session**, so anyonecan fill the log with noise. It is an append of ~110 bytes perevent 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 hostnameand 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.