From 4812eaf1ed153bee2630c425d40d9fe26cb51f46 Mon Sep 17 00:00:00 2001 From: Frederic Cabassut Date: Tue, 18 Aug 2026 12:19:14 +0200 Subject: [PATCH] docs: correct the admin user-management claims MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue #77 was caused by these docs. FEATURES.md promised "Reset passwords for any user" when no such control existed, so a user reasonably filed a bug against a promise the software never made. The docs were describing the API surface, not the UI. Now that the control ships, they describe what it actually does — and the same audit turned up three neighbouring claims that were already wrong. Corrected: - "Reset passwords for any user" — it is any user other than yourself, whose account signs in with a password, and Crumbs generates the password and shows it once rather than the admin choosing one. - "Revoke all sessions ... for any user" — Revoke has always been self-excluded in the UI. Wrong before this feature existed. - The AUTH.md sentence covering both capabilities in one breath, so fixing only the reset half would have left the revoke half wrong. - Two references to a "Settings > Users > Invite User" affordance that does not exist; the section is headed Create User. Same defect as #77 — documentation promising UI that was never built — one of them buried in the Authentik setup guide. Newly documented, all previously silent: - The sole-admin dead end, and its bound. There is no forgot-password flow, the reset control excludes your own row, and Profile requires your current password. Another admin can reset you. Failing that, an OAuth sign-in recovers the account when a provider is configured and the email matches — at the cost of handing the account to that provider permanently. Only with no second admin and no provider is there genuinely no way back in through the app. An earlier draft stated that absolutely, which would have pushed an operator toward restoring from backup when one OAuth sign-in would have done. - The OAuth pre-link trap: a password set during invite works only until the first OAuth sign-in, which hands the account to the provider. Ticking OAuth-only avoids the surprise. Tracked for a real fix in #78. - That the reset notification is best-effort. Both layers swallow send errors, so a successful reset is not evidence the user was told. - That a displayed password is only good until that account's password changes again, by any route, with nothing marking it stale. - That an unconfirmed reset shows the password anyway, and that one should be kept and retried. - That the control is also unavailable while a password is on screen — the one unavailable state that shows no reason, so an admin meeting a dead button has somewhere to look. No openapi.yaml or API.md change: neither documents /api/admin/* at all, so the new 400 needs no spec edit and pnpm docs:api regenerates nothing relevant. That gap predates this work. Verified: pnpm check 0 errors / 14 pre-existing warnings. Every factual claim traced to code by the author and again by an independent reviewer, which is how the false recovery claim was caught. Reviewed-by: adversarial-review (13 of 14 claims verified true on the first pass; failed for one false absolute, since bounded) Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01RbqJcFofZSbhbGwUwZP3wU --- docs/AUTH.md | 25 ++++++++++++++++++++++--- docs/FEATURES.md | 7 +++++-- 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/AUTH.md b/docs/AUTH.md index 37ccfb8..4522059 100644 --- a/docs/AUTH.md +++ b/docs/AUTH.md @@ -10,7 +10,24 @@ On first launch, Crumbs presents a setup screen to create the initial admin acco - Passwords are hashed with **Argon2** (argon2id variant) - Sessions use httpOnly cookies with 30-day expiry -- Admins can reset passwords and revoke sessions for any user via Settings +- Admins can revoke the sessions of, and reset the password of, users other than themselves via **Settings > Users** — see [Admin password resets](#admin-password-resets) + +### Admin password resets + +An admin can reset the password of any user other than themselves, provided that account signs in with a password. Crumbs generates the new password and shows it once in that user's row — copy it and pass it to the user out of band, because it is not stored anywhere and cannot be shown again once dismissed. If SMTP is configured Crumbs also tries to notify the user that their password was reset, but the attempt is best-effort: a delivery failure is logged on the server and never surfaced in the UI, so a successful reset is not evidence the user was told. The notification never contains the password. + +The control appears on every row, but is unavailable in two cases, each stating its reason on the row: + +- **Your own row** — change your own password in **Settings > Profile**, which verifies your current password first. +- **An account that signs in via OAuth/SSO** — it has no password the login form would accept, so setting one would hand the user a credential that cannot work. + +It is also unavailable while a generated password is still on screen, and that case gives no reason — dismiss the password first if you need to generate another. + +A reset does not sign the user out. **Revoke all sessions** is a separate action on the same row and, like the reset, is not offered for your own account. + +A displayed password is only good until that account's password changes again: any later reset — by another admin, or by the user themselves from **Settings > Profile** — silently invalidates one still on screen, and nothing marks it as stale. Separately, if Crumbs cannot confirm a reset it says so and shows the password anyway; keep that one, since it may or may not have been applied, and reset again if the user cannot sign in. + +> **No password recovery.** Crumbs has no forgot-password flow. An admin who forgets their own password cannot reset it themselves: the admin control excludes their own row, and the profile flow requires the current password. Another admin can reset you, so keep a second admin account as cheap insurance. Failing that, if an OAuth/SSO provider is configured and your account's email matches your identity there, signing in with that provider gets you back in without a password — at the cost of handing the account over to the provider permanently, after which your password no longer works. With no other admin and no provider configured, there is no way back in through the app. ## OAuth / SSO @@ -29,12 +46,14 @@ OAuth providers are **auto-enabled** when their environment variables are set OAuth does **not** auto-create accounts. Users must be pre-created by an admin: -1. Go to **Settings > Users > Invite User** +1. Go to **Settings > Users** and fill in the **Create User** form 2. Create the user with the **same email** they use on the OAuth provider 3. The user can now log in via OAuth — their account is automatically linked on first sign-in After initial linking, the user is identified by their provider-specific ID (`sub` claim), so email changes on the provider side won't break login. +Tick **OAuth-only (no password)** when creating these accounts — the provider is how they will sign in anyway. If you set a password instead, treat it as temporary: the first OAuth sign-in hands the account over to the provider, after which the password no longer works at the login form and the admin password reset is unavailable for that account. + ### Environment variables #### Google OAuth @@ -130,7 +149,7 @@ services: **4. Pre-create users:** -In Crumbs, go to **Settings > Users > Invite User** and create accounts with emails matching your Authentik users. They can then log in via the "Authentik" button on the login page. +In Crumbs, go to **Settings > Users** and create accounts with emails matching your Authentik users, ticking **OAuth-only (no password)**. They can then log in via the "Authentik" button on the login page. #### Keycloak diff --git a/docs/FEATURES.md b/docs/FEATURES.md index 0223249..793cdf0 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -142,8 +142,11 @@ ### User Management (admin) - Admin dashboard to create, list, and delete users - Assign roles (admin / user) -- Reset passwords for any user -- Revoke all sessions (force logout) for any user +- Reset another user's password — Crumbs generates a 20-character password and shows it once in that user's row, with a copy button; it cannot be shown again + - Only for accounts that sign in with a password — OAuth/SSO accounts show why the reset is unavailable + - Your own password is changed from Settings > Profile, not here + - A reset does not sign the user out — revoke their sessions separately to force a logout +- Revoke all sessions (force logout) for any user other than yourself ### PWA / Offline-First - Installable as standalone app