Repository navigation
Add native single-user-first authentication - #204
Merged
Merged
Conversation
jasonmadigan
force-pushed
the
197-native-auth
branch
2 times, most recently
from
August 30, 2026 14:43
288a0a6 to
750d9ff
Compare
Tracefinity had no accounts. A standalone install was a single anonymous user, and multi-user deployments relied on a trusted reverse proxy asserting identity through a header, so nothing inside the application knew who anyone was. Add native authentication with three modes. `native` is the default: a fresh install prompts for an initial administrator, there is no default password, and identity comes from a cookie. `proxy` preserves the existing trusted-header behaviour for deployments that use it and is deprecated. `open` keeps the current single-user behaviour for anyone running privately who wants no login at all. Absent identity fails closed in native and proxy; only open retains the anonymous fallback. Accounts live in users.json at the storage root, hashed with stdlib scrypt behind a scheme prefix so other schemes can be verified and transparently upgraded on the next login. Auth tokens are opaque, stored hashed, and revoked on logout, password change, disable and deletion. Isolation is enforced server side: the storage guard resolves identity per mode rather than trusting a path segment, and existing installs keep their data because the first administrator claims the default namespace by alias, so no files move and no stored path is rewritten. Two-factor authentication is included. Enrolment confirms a code before enabling, login becomes a two step exchange through a single-use pending token, verification is stdlib RFC 6238 with replay protection, and secrets are encrypted at rest under a key derived from AUTH_SECRET with rotation support. Backup codes are single use and regenerable, and an administrator can clear a locked-out account's second factor. Accounts can be created with an externally supplied id and credential so an installation migrating from another system keeps its storage keying and its users' existing passwords. The same is available without the web flow: `python -m app.cli create-admin` creates the first administrator from inside a container, for deployments that provision out of band and close the web setup route. It reads the password from a prompt or stdin, never from an argument, and hands anything it creates as root to the storage owner so the service can still read it. Startup now validates the mode against what the volume already holds. Serving an instance that has accounts in a mode with no login would publish the first administrator's data to anyone and strand the rest, so open and proxy refuse to start in that state unless explicitly overridden. A native start with no accounts on populated storage warns that setup is open on data somebody already owns. AUTH_SETUP_ENABLED closes the web setup route entirely for deployments that create administrators by other means. Instance storage statistics previously relied on the proxy secret alone, which is unset in native mode, leaving the per-user roster readable by anyone; that endpoint now requires an administrator and the secret comparison is constant time. Account writes use compare-and-set so a concurrent administrative change cannot be reverted by a slower request, and the store refuses any change that would leave no enabled administrator. Deleting the last administrator while other accounts remain is refused, and a namespace whose deletion did not complete is marked so a later account cannot inherit its files. The generated API documentation is no longer served, and the remaining unauthenticated surface is the health check, the version, and the auth entry points. Closes #197 Signed-off-by: Jason Madigan <jason@jasonmadigan.com>
jasonmadigan
force-pushed
the
197-native-auth
branch
from
August 30, 2026 15:03
750d9ff to
cddad4f
Compare
jasonmadigan
marked this pull request as ready for review
August 30, 2026 16:16
Th
6EFC
is 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
native(default): first run prompts for an administrator, no default password, cookie identity.proxy: the existing trusted-header behaviour, preserved for deployments that use it, now deprecated.open: today's single-user behaviour for anyone running privately. Absent identity fails closed in native and proxy; onlyopenkeeps the anonymous fallback.defaultnamespace by alias, so no files move and no stored path is rewritten.python -m app.cli create-admintakes an account id, storage namespace, an existing password hash and an existing second factor, so an installation migrating from another system keeps its keying, passwords and 2FA.AUTH_SETUP_ENABLED=falsecloses the web setup route for deployments that provision this way.Test evidence
backend/venv/bin/python -m pytest617 passed (370 before this branch)pnpm test186 passed / 23 files (151 before)make lint0 errors, 9 pre-existing warnings in untouched filesnpx tsc --noEmitcleanCoverage includes the mode matrix and its precedence, startup refusals and the legitimate startups that must not trip them, fail-closed behaviour, first-run races, cookie auth on
/apiand/storage, percent- and double-encoded traversal, RFC 6238 vectors with window and replay, backup code single use, import atomicity and idempotency, rehash on login under a concurrent disable, concurrent administrative writes, and namespace claim safety including a process-killed-between-steps path.Notes for review
proxymode is deprecated here but unchanged in behaviour. Removal will be announced separately with a migration path.openmode is unauthenticated by design, so namespace ids created under native mode become enumerable if an operator later switches to it. Documented indocs/auth.md.docs/auth.mdis the conceptual model: modes, first run, claiming, 2FA, recovery, and the CLI. Worth reading before the diff.Closes #197