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: recovering from a lost passkey needs a password as proof, only admins read the activity log, and which passkey routes are throttled or CSRF-exempt (#95)

Duarte Santos50521c78f076
diff --git a/SECURITY.md b/SECURITY.md
index 67b9595a6..07d74b141 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -211,7 +211,8 @@ Read this before hosting openGym for anyone other than yourself.
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
reads a code off the screen within its ten minutes can add a passkey to that profile; the owner
- sees it in Settings → Passkeys and in the activity log (`auth.link.ok`) and can remove it.
+ sees it in Settings → Passkeys and can remove it. The instance's activity log records it as
+ `auth.link.ok`, but only an admin can read that log.
Sessions are `uid:expiry:version` and are not tied to the passkey that opened them, so removing
a passkey stops it signing in and drops an unused device code, but leaves any session it
opened running; "sign out everywhere" ends those.
diff --git a/api/openapi.yaml b/api/openapi.yaml
index fa905f42a..bd1a26567 100644
--- a/api/openapi.yaml
+++ b/api/openapi.yaml
@@ -33,10 +33,13 @@ info:
whether or not a profile has that name. A password check counts from the moment it
starts, so checks sent at once get no more tries than checks sent one by one. A
paused caller gets `429 {"error": …, "code": "locked", "retryAfter": <s>}` with a
- `Retry-After` header. The passkey and pairing routes are not throttled.
- The two routes that redeem a one-time device link (tag `passkeys`) share the
- per-address budget, and wrong codes pause the address for link redemption only,
- after 20, the way wrong reset codes do.
+ `Retry-After` header. Passkey sign-up and sign-in and the pairing routes are not
+ throttled. The two routes that redeem a one-time device link (tag `passkeys`) share
+ the per-address budget, and wrong codes pause the address for link redemption only,
+ after 20, the way wrong reset codes do. Adding a passkey in Settings
+ (`POST /api/account/passkeys/options`) and making a device code
+ (`POST /api/account/device-link`) spend the per-address budget too, and a current
+ password given there as proof counts like one given at sign-in.
The address is the socket's, or with `TRUST_PROXY=1` the one a trusted proxy put in
`CF-Connecting-IP` / the last `X-Forwarded-For` entry / `X-Real-IP`; IPv6 clients are
counted by /64. Counters live in memory and reset on restart.
@@ -52,8 +55,10 @@ info:
State-changing browser requests must come from the app's own origin. The server
checks `Sec-Fetch-Site` (falling back to `Origin` vs the configured `ORIGIN`);
a mismatch is refused with `403 {"error":"cross-origin request refused"}` on any
- non-GET route. Exempt: the WebAuthn and `pair/redeem` routes (each carries its own
- one-shot credential in the body) and any request authenticated with a Bearer token.
+ non-GET route. Exempt: passkey sign-up and sign-in (`register/options`,
+ `register/verify`, `login/options`, `login/verify`) and `pair/redeem`, each of which
+ carries its own one-shot credential in the body, and any request authenticated with a
+ Bearer token.
The password routes are **not** exempt: a hostile page knows a valid name and
password of its own, and could otherwise sign a visitor into it (login CSRF).
Neither are the device-link routes: a link is redeemed on the app's own origin,
diff --git a/docs/SELF_HOSTING.md b/docs/SELF_HOSTING.md
index d6a0d467c..3a788e8a5 100644
--- a/docs/SELF_HOSTING.md
+++ b/docs/SELF_HOSTING.md
@@ -502,9 +502,10 @@ Keychain to your Apple devices, a password manager to every device it runs on. A
only on one phone (or on a hardware key) goes with that phone.
**I lost my passkey.** If the profile has another passkey, sign in with that one and remove the
-lost one under **Settings → Account → Passkeys** (then **Sign out everywhere**). If a browser is
-still signed in, it can give a new device a passkey with **Add another device**. Otherwise there
-is no self-service recovery: with `PASSWORD_LOGIN=1` an admin can issue a reset code, and without
+lost one under **Settings → Account → Passkeys** (then **Sign out everywhere**). A browser that
+is still signed in can give a new device a passkey with **Add another device** only if the
+profile also has a password: making the code asks for a passkey or the current password first,
+because a session on its own may be a stolen cookie. Otherwise there is no self-service recovery: with `PASSWORD_LOGIN=1` an admin can issue a reset code, and without
it the only way back is a backup (**Settings → Export backup (JSON)**, from any device still
signed in) imported into a new profile. When you ask your admin for help, the id under
**Settings → Account → Account ID** tells them exactly which account is yours. Adding a second