House-move inventory: Built, then deleted: authentication - Part 10

House-move inventory: Built, then deleted: authentication - Part 10

Building Inventory System

~8 min read

For a two-person app, a login system sounds like overkill. I built one anyway, over about three weeks, and then removed all of it. This post is the history, and what the app trusts today.

(If you've read the finance-system series, its post 9 "Handing authentication to identity-system" covers the same destination reached from a different starting point.)

Built it

On 6 September, Phase 3.9 added per-user accounts and server-side sessions with Argon2 hashing, a POST /api/auth/login and a cookie guarding every route except /health. Two days later came opt-in two-factor auth: TOTP from an authenticator app, ten single-use recovery codes, a lockout after ten consecutive bad codes, a QR-code enrolment screen in Settings.

Then I extracted it. The auth code became its own package, sessionkit, first in-tree (Phase 3.23, with a test that fails CI if it ever imports inventory or FastAPI), then published to its own repo and installed from GitHub (3.24). That was a satisfying piece of engineering. It was also the moment I should have asked the obvious question.

The question I should have asked sooner

Why does this app own accounts at all? I run other small tools at home. Each one that needed a login would carry its own user table, its own 2FA enrolment screen and its own password-change form, and a fix to how accounts work would have to be rolled out to every one of them. sessionkit made that rollout possible; it didn't make it unnecessary.

The alternative is a pattern nginx calls auth_request: one service, a separate project called identity-system, owns the accounts. nginx asks it about every request, and the app trusts the answer.

What the app does now

Browser --> nginx --auth_request--> identity-system GET /verify
                                          |
                      200 + X-Auth-User-Id / -Email / -Name
                                          |
            nginx injects those headers, then forwards to this app

The entire authentication surface of the inventory app is one file, api/identity.py. It reads three headers. X-Auth-User-Email is the signal: if it's blank or missing the request got here without going through nginx, and the answer is 401. There's no database lookup. X-Auth-User-Name falls back to the email, and X-Auth-User-Id may legitimately be empty - nothing in this schema references it any more.

For local development there's no proxy, so every route would 401. An explicit INVENTORY_DEV_AUTH_BYPASS=1 fakes a fixed user instead. It's opt-in and named loudly, because a "convenient" default-on bypass is how real ones ship.

The rule that makes it safe

Trusting request headers is only safe if clients cannot set them. The guarantee is in nginx: the proxy_set_header lines unconditionally overwrite all three X-Auth-User-* headers with what /verify returned, discarding anything a client sent under the same names. It's written into the project notes in bold:

Any new nginx location that proxies to this backend must set all three headers too, or it is an authentication bypass.

That is the kind of invariant I'd rather have in the docs and in a place a future me will trip over it, which is why it's in CLAUDE.md, docs/auth.md and a comment in the nginx file.

It was done in careful steps

The cutover went out as separate commits so each could be verified against the live container before the next:

  1. TLS first. identity-system's session cookie is Secure, scoped to a shared cookie domain. A Secure cookie is silently dropped over plain HTTP, which turns a missing certificate into an infinite redirect loop. TLS was a prerequisite, not a nicety. (The nginx file in the repo now sits behind a TLS-terminating layer in front, and an interim 443 listener was removed.)
  2. Forward-auth in nginx.
  3. Drop the in-app auth.

The third step was the satisfying one: the sessionkit dependency, the /api/auth/* and /api/users* routes, render/qr.py and the qrcode dependency (used for nothing but the TOTP QR), the login and 2FA screens, the account CLI. In the SPA, auth.tsx and App.tsx lost their login wall entirely - an unauthenticated browser never receives the app in the first place, so a 401 anywhere just reloads the page, which re-triggers the proxy's check on the document request.

The tail: migration 14

Dropping the code left the data: three tables. Migration 14 drops users, sessions and recovery_codes (children first), and in doing so exposed the baseline-schema bug from post 6 - the baseline would have quietly recreated them on next start. Deleting a feature properly is a migration, a guard, and a docs change, not just git rm.

What I'd say about the detour

Three weeks of auth work looks wasteful. It isn't quite: the realistic-fixture approach to migration 7 and the in-tree-first extraction are both things I'd reuse. But the lesson is cheap to state. Before building a capability inside an app, count how many apps will need it. If the answer is more than one, it's a service.

Next: the status, the "going?" decision, and the history that records them.


Previous: ← Slow PDFs as background jobs · Next: Status, going? and a history →