8000 Add administrator API tokens by jasonmadigan · Pull Request #206 · tracefinity/tracefinity · GitHub
[go: up one dir, main page]

Skip to content

Add administrator API tokens - #206

Merged
jasonmadigan merged 3 commits into
mainfrom
205-admin-api-tokens
Aug 30, 2026
Merged

jasonmadigan merged 3 commits into
mainfrom
205-admin-api-tokens

Conversation

@jasonmadigan
Copy link
Copy Markdown
Collaborator

Summary

  • Every administrative endpoint resolved identity from the auth cookie, so an automated process could not call the admin API without driving an interactive login, which is impossible for an account with a second factor enabled. Deployments that provision accounts programmatically had no way to authenticate.
  • Administrators can now issue bearer tokens (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.
  • A token holds strictly less authority than the session that issued it: it neither creates an administrator nor writes to an account that is one. Clear-2FA, the token endpoints themselves and instance storage statistics stay session-only.
  • Disabling or demoting the issuing account makes its tokens inert immediately; deleting it revokes them. A password change no longer revokes them, so automation survives routine credential rotation, while login sessions are still revoked as before.

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_RE and _EMAIL_RE anchored with \Z rather 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 pytest 728 passed (617 before this branch)
make lint 0 errors, 9 pre-existing warnings in untouched files

Coverage 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

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>
@jasonmadigan
jasonmadigan merged commit 37eef59 into main Aug 30, 2026
6 checks passed
@jasonmadigan
jasonmadigan deleted the 205-admin-api-tokens branch August 30, 2026 18:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support a non-interactive administrator credential for the admin API

1 participant

0