Repository navigation
Add administrator API tokens - #206
Merged
Merged
Conversation
Administrative endpoints resolved identity only from the login cookie, so a deployment that provisions accounts programmatically had no way in. An automated caller cannot drive a browser login, and cannot supply a second factor at all. `AUTH_SETUP_ENABLED=false` and the `create-admin` command already acknowledge that some installs provision administrators out of band, but both address first run only. An administrator issues an opaque token from a logged-in session and presents it as `Authorization: Bearer`. That header is understood by every HTTP client, a browser never attaches it on its own, and it collides with neither the auth cookie nor `X-Proxy-Secret`. A request carrying a bearer token is decided by that token: an invalid one is 401 and never falls back to a cookie that happens to be present. The token reaches the user-provisioning routes only: list, create, disable, enable and reset password. Clearing a second factor, managing tokens, and instance storage stats stay session-only. A credential that authenticates without a second factor must not be able to remove second factors from accounts, which combined with a password reset would make every account takeable by whoever holds the token; nor mint a successor, because containing a leak should not mean chasing a chain. Routes opt in by declaring `get_admin_principal`, so a route added later reaches nothing until someone says otherwise. Tokens live beside login tokens in auth_tokens.json as sha256 hashes, compared in constant time, each with its own resolver so neither kind is accepted where the other belongs. They do not slide, default to never expiring, take an optional lifetime at issue time, and are revoked individually. A password change no longer takes them with it, since rotating a password is not evidence that a provisioning credential leaked. Disabling or demoting the issuing account makes them inert at once, checked against the live account on every use, and deleting the account destroys them. Every administrative mutation now records who acted and, when a token was used, which token. Only account creation did before. Native mode only: `open` and `proxy` return 404 for this surface as they always have, so nothing here extends `PROXY_SECRET`. Signed-off-by: Jason Madigan <jason@jasonmadigan.com>
An administrator API token could set is_admin on POST /api/admin/users, then log in interactively as the account it had just created. That account carries no second factor, so the token holder obtained a full session and with it successor tokens, clear-2fa and storage-stats: every containment decision the credential was built around. Resetting an existing administrator's password reached the same place in one step fewer. A token now neither creates an administrator nor writes to an account that is one. is_admin: true on create is refused with 403, as are reset-password, disable and enable whose target is an administrator, including the account that issued the token. The refusal is explicit rather than a downgrade to a member account: a provisioning script that asked for an administrator and got a 200 would carry on believing it had one. Disable and enable are included because suspending every other administrator locks out the people who could revoke the token, and because the rule is easier to rely on stated once than carved out per route. Ordinary accounts are unaffected, and an administrator session keeps every ability it had. The write guard runs inside the account store lock, against the live record, so it cannot race a change to the target's admin bit. The admin router now declares get_admin_principal as a default dependency, so a route added without an explicit one is authenticated rather than anonymous. FastAPI caches the dependency per request, so the routes that declare it themselves resolve their token once. docs/auth.md claimed a token could not mint another with no chain of successors to chase. That was false as written; it is true now, and the reasoning for each exclusion is recorded alongside it. Relates to #205 Signed-off-by: Jason Madigan <jason@jasonmadigan.com>
Python's `$` matches before a trailing newline, so `_USER_ID_RE` accepted `"<valid id>\n"`. The id becomes a directory name under the storage root, so an admin create, `create-admin --id`, or `--storage-namespace` could land a namespace with a newline in it. That is not cross-user exposure, the namespace is still distinct, but a newline in a path breaks shell globbing, log parsing, backup scripts, and anything that reads a list of namespaces a line at a time. `\A` and `\Z` now anchor the whole alternation rather than each branch, so the cuid and uuid shapes cannot drift apart the way they would if only one side were corrected. `_EMAIL_RE` had the same loose anchor and gets the same treatment; `normalise_email` strips before matching, so no behaviour changes there, but the expression no longer relies on its caller for the guarantee. Nothing legitimate is rejected. Ids come from `uuid4`, the literal "default", or a validated flag or field, and no code builds one from an unstripped line: the only `readline` in the backend is the CLI password prompt, which rstrips, and every store reads whole files as JSON. The one released version carrying this expression, 0.8.0, applies it solely to the proxy `x-user-id` header, where a bare newline cannot cross the wire. Tests cover leading, trailing, and embedded newlines and other trailing whitespace on all four paths through the validator, and on the validator itself. Relates to #205 Signed-off-by: Jason Madigan <jason@jasonmadigan.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Authorization: Bearer tfadm_…) scoped to account management: list, create, disable, enable, reset password. Issued only from an authenticated administrator session, stored hashed, individually revocable with effect on the next request, optional expiry that never slides.Notes for review
The containment rule is one invariant rather than a set of per-route exceptions, checked against the live record inside the account store lock. It exists because a credential that bypasses the second factor must not be able to remove second factors, reset an administrator's password, or mint an administrator it could then log in as: any of those turns a scoped token back into full authority.
Also here:
_USER_ID_REand_EMAIL_REanchored with\Zrather than$. Python's$matches before a trailing newline, so an id ending in one previously passed validation and produced a storage directory with an embedded newline. That expression is the path-safety contract for anything that becomes a directory name.Test evidence
backend/venv/bin/python -m pytest728 passed (617 before this branch)make lint0 errors, 9 pre-existing warnings in untouched filesCoverage includes every route's response to a token versus a session, bearer and cookie precedence, revocation and expiry, the disabled and demoted issuing account, hashing at rest, and the escalation chains above. Security-critical tests were mutation-checked; reverting a guard, weakening it to one alternative, or turning refusal into a silent downgrade each fail the suite.
Closes #205