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.

docs: signing in with an e-mail, what it gives away, and the account pause behind name and e-mail

Duarte Santosdc6786b5ce40
diff --git a/SECURITY.md b/SECURITY.md
index 84a814afc..ecb13db45 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -52,7 +52,9 @@ in the thread; there's no objection, and no request to sit on it indefinitely.
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
have a password, setting a password on someone else's profile, or using a reset code twice or
- after it expired (`api/password.js`, `api/rate-limit.js`). Adding a passkey to a profile that
+ after it expired (`api/password.js`, `api/rate-limit.js`); reading another profile's sign-in
+ e-mail without being an admin, setting one without the owner's proof, or dodging the account
+ 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
@@ -127,14 +129,28 @@ Read this before hosting openGym for anyone other than yourself.
(`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 after 20 (30 s, doubling to 15 min); wrong passwords pause the *name* after 5 (1 min,
- doubling to 1 h), existing or not. A password check is counted the moment it starts, so guesses
+ address after 20 (30 s, doubling to 15 min); wrong passwords pause the *account* after 5 (1 min,
+ 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
`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
+ 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
+ email-taken` — only after the proof in Settings, and each refusal (Settings or signup) counts
+ against the caller's address and account like a wrong invite code, so probing which addresses
+ are registered costs a passkey prompt or a password check per try and runs out after about 20.
+ The full address is never logged or audited (masked to `a…@e…`) and is returned only to its
+ owner (`GET /api/account/password`) and to admins (`GET /api/admin/users`, `/api/admin/user`);
+ it is not in `/api/me`, Coach payloads, the MCP bridge or plan sharing.
- **Sessions are a signed cookie.** It carries `<uid>:<expiry>:<version>` plus an
HMAC-SHA256 tag over it, compared in constant time (`api/server.js:230-243`). The key is 32
random bytes generated on first run and written to `./data/secret` with mode `0600`
@@ -251,8 +267,11 @@ Read this before hosting openGym for anyone other than yourself.
would each keep their own. Behind a second proxy that hides the visitor's address every
visitor shares one per-address count, so one client can pause *password* sign-in for everybody
for up to 15 minutes at a time (the per-name pause still holds, and passkeys are never
- paused). Anyone who knows a name can keep its password sign-in paused, which the activity log
- shows as `auth.password.locked`. Only two password checks run at once, with 32 queued behind
+ paused). Anyone who knows a name or a sign-in e-mail can keep its password sign-in paused, which the activity log
+ shows as `auth.password.locked`. Because the pause is per account, a paused account also
+ answers `429` for a guessed e-mail that belongs to it, which links that address to the name
+ 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
policy is 10–256 characters and a short built-in list of the passwords guessing scripts try
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.md
index 8e53a24ba..cbe669a64 100644
--- a/docs/SELF_HOSTING.md
+++ b/docs/SELF_HOSTING.md
@@ -203,6 +203,8 @@ What changes when it is on:
- People sign in with their **profile name** — case and surrounding spaces do not matter — and the
password. Two profiles with a password cannot share a name; Settings says so when a name is
already taken that way.
+- Optionally with an **e-mail address** instead of the name: see *Signing in with an e-mail*
+ below.
- A password cannot be removed while it is the profile's only way in (a profile made with a
password has no passkey).
- The password also confirms the changes that need proof — adding or removing a passkey, making
@@ -215,15 +217,49 @@ browser that is still signed in. Before you switch it off, have those profiles a
(**Settings → Account → Passkeys → Add a passkey**, confirmed with their password); the admin
dashboard marks every profile that has a password.
+**Signing in with an e-mail.** Settings → Account also gets a **Sign-in e-mail** row, right under
+the password, and **Create new profile** with a password has an optional e-mail field. Whoever
+adds an address can type it at **Sign in with password** instead of their profile name (case and
+spaces do not matter). openGym has no mail server and **never sends anything** to it: there is no
+verification mail and no reset mail — a forgotten password is still reset with the admin's code
+below, which can be redeemed with the name or the e-mail. So the address is not proven to belong
+to anyone; it is only a second name that points at the account, and the password still opens it.
+
+- Adding, changing and removing it asks for the same proof as setting a password (the current
+ password or a passkey of the profile) — a session on its own may be a copied cookie.
+- An address belongs to one profile only, and can never be another password profile's name.
+ Taking one that is in use is refused ("Another profile already uses this e-mail address") — see
+ *What an e-mail gives away* below for what that says and how it is limited.
+- Wrong passwords count against the **account**, whether it was named by its name or its e-mail,
+ so switching between the two does not get around the pause.
+- Only the owner (in Settings) and admins (the user list and the user's page in the admin
+ dashboard) ever see the address. It is not written to the activity log (entries show it masked,
+ `a…@e…`) or the container log, is not part of what the Coach, the MCP server or plan sharing
+ see, and is not in `/api/me`. It is stored in `db.json` as `email` on the user, lower-cased.
+- With `PASSWORD_LOGIN` off, the row and the field are hidden and the address is not used; it
+ stays in `db.json` for when the flag comes back.
+
+**What an e-mail gives away.** A profile trying to take an address already in use is told so,
+which says "some profile on this instance uses this address" — never which one. The alternative,
+accepting it silently, would leave someone who typed their address on a second profile believing
+it worked. So the answer is made expensive instead: in Settings it comes only after the proof (a
+passkey prompt or a password check per try), and every such refusal — in Settings or on signup —
+counts against the visitor's address (and in Settings the account): 20 are free, then a pause of
+30 seconds doubling to 15 minutes. That leaves a few tries an hour, comparable to what the
+name-taken answer already says about names. The other thing to know: once someone has paused an
+account by wrong passwords under its name, trying a guessed address shows the same pause, which
+ties that address to that name — the price of not letting a switch to the e-mail skip the pause.
+
**Resetting a password.** There is no e-mail. In the admin dashboard open the user and choose
**Reset password**. You get a one-time code such as `K7WQ-2MZP-4HXA` to hand over in person or
by message: it is shown once, works once, is valid for 24 hours and is stored only as a hash.
Issuing it removes their current password and signs them out everywhere at once — their passkeys
-keep working. They enter their name, the code and a new password under **Sign in with password →
+keep working. They enter their name (or their sign-in e-mail), the code and a new password under **Sign in with password →
Have a reset code?**. The same code gets someone back in who lost their only passkey (#219).
Admin accounts cannot be reset from the dashboard, so one admin cannot take over another's login;
an admin sets their own password in Settings. Every step is in the activity log
-(`admin.password.reset`, `auth.password.reset`, `auth.password.ok` / `fail` / `locked`).
+(`admin.password.reset`, `auth.password.reset`, `auth.password.ok` / `fail` / `locked`, and
+`auth.email.set` / `change` / `remove` / `fail` for the sign-in e-mail).
**On a plain-HTTP LAN**, set `ORIGIN` to exactly the address people type, for example
`ORIGIN=http://192.168.1.20:8080`. Browsers do not send `Sec-Fetch-Site` to plain-http addresses,
@@ -239,9 +275,10 @@ a LAN-only address, see [SELF_HOSTING_HTTPS.md](./SELF_HOSTING_HTTPS.md).
- `db.json` holds a scrypt hash of each password (N=2^15, r=8, p=1, 16-byte random salt). Someone
with a copy of `./data` can try guesses offline, slowly; a passkey's public key gives them
nothing to try.
-- Guessing online is throttled. Five wrong passwords for a name pause password sign-in for that
- name for a minute, doubling up to an hour, whoever sends them — names that do not exist pause
- the same way, so a pause reveals nothing. Twenty wrong answers from one address pause that
+- Guessing online is throttled. Five wrong passwords for an account — named by its name or its
+ e-mail — pause password sign-in for that account for a minute, doubling up to an hour, whoever
+ sends them — names and addresses that do not exist pause the same way, so a pause reveals
+ nothing about whether they exist. Twenty wrong answers from one address pause that
address for 30 seconds, doubling up to 15 minutes, and every address gets 60 requests a minute
to the password routes. Guesses sent all at once count the same as guesses sent one by one.
Passkey sign-in, passkey signup and phone pairing are not throttled at all, so they are never