8000 Add native single-user-first authentication by jasonmadigan · Pull Request #204 · tracefinity/tracefinity · GitHub
[go: up one dir, main page]

Skip to content

Add native single-user-first authentication - #204

Merged
jasonmadigan merged 1 commit into
mainfrom
197-native-auth
Aug 30, 2026
Merged

jasonmadigan merged 1 commit into
mainfrom
197-native-auth

Conversation

@jasonmadigan
@jasonmadigan jasonmadigan commented Aug 29, 2026 •
Copy link
Copy Markdown
Collaborator

Summary

  • 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. This adds native authentication and enforces isolation server side.
  • Three modes. 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; only open keeps the anonymous fallback.
  • Existing installs keep their data. The first administrator claims the existing default namespace by alias, so no files move and no stored path is rewritten.
  • Startup validates the mode against what the volume holds: a mode with no login refuses to start on an instance that has accounts, since it would publish the first administrator's data and strand the rest.
  • Two-factor authentication included: confirm-before-enable enrolment, two-step login through a single-use pending token, stdlib RFC 6238 verification with replay protection, secrets encrypted at rest with rotation support, single-use backup codes, and an administrator path to clear a locked-out account's second factor.
  • Administrators can also be created without the web flow, for containerised or automated deployments: python -m app.cli create-admin takes 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=false closes the web setup route for deployments that provision this way.
  • The generated API documentation is no longer served. The unauthenticated surface is the health check, the version, and the auth entry points.

Test evidence

backend/venv/bin/python -m pytest 617 passed (370 before this branch)
pnpm test 186 passed / 23 files (151 before)
make lint 0 errors, 9 pre-existing warnings in untouched files
npx tsc --noEmit clean

Coverage 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 /api and /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

  • proxy mode is deprecated here but unchanged in behaviour. Removal will be announced separately with a migration path.
  • open mode is unauthenticated by design, so namespace ids created under native mode become enumerable if an operator later switches to it. Documented in docs/auth.md.
  • Rate limiting and pending-login state are per process, which suits the single-worker deployment this ships with.
  • docs/auth.md is the conceptual model: modes, first run, claiming, 2FA, recovery, and the CLI. Worth reading before the diff.

Closes #197

@jasonmadigan
jasonmadigan force-pushed the 197-native-auth branch 2 times, most recently from 288a0a6 to 750d9ff Compare August 30, 2026 14:43
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
jasonmadigan marked this pull request as ready for review August 30, 2026 16:16
@jasonmadigan
jasonmadigan merged commit 090930d into main Aug 30, 2026
6 checks passed
@jasonmadigan
jasonmadigan deleted the 197-native-auth branch August 30, 2026 16:20
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.

Add native single-user-first authentication

1 participant

0