Skip to content

feat(deploy): gate the workbench behind a shared-account session - #21

Merged
Odiethebest merged 2 commits into
mainfrom
feat/auth-gate
Aug 3, 2026
Merged

Odiethebest merged 2 commits into
mainfrom
feat/auth-gate

Conversation

@Odiethebest

Copy link
Copy Markdown
Owner

Stacked on #18, #19, #20. Closes F-01 and F-05, partly closes F-03, and adds two findings of its own (F-19, F-20).

Delivers D-2 and D-6 in Deploy.md.

What is gated

Landing / and /methodology stay public — they are the part meant to be read. /workbench and every API route it consumes do not. /internal/* is untouched: it is service-to-service, keeps its own shared-key check, and the agent has no cookie to present.

No new dependency

passlib, pyjwt and itsdangerous are all absent from this workspace. Pulling one in to authenticate a single demo account would be the larger change, so this is stdlib: PBKDF2-HMAC-SHA256 at OWASP's 600k floor, and an HMAC-signed cookie that is HttpOnly, Secure, SameSite=Lax.

Off by default, hardcoded on in production

Local development, every current compose invocation and the existing tests are unaffected — require_session is a no-op while AUTH_ENABLED is false.

docker-compose.prod.yml hardcodes AUTH_ENABLED: "true" rather than defaulting it. A production gate that can be switched off by omitting a variable is not a gate. The credential and signing secret use :?, and the API refuses to start when the gate is on but unconfigured — an auth gate that fails open looks exactly like one that works. Pinned by a test.

Per-session daily query cap

On /query alone. The login wall removes anonymous callers; it does nothing about a signed-in one looping a question through three metered APIs. Counted before the agent is reached, and it fails open on a Redis error — a spend guard that takes the service down when a cache blips has traded a bounded bill for an outage.

Two findings from verifying this

F-19 — a $ in an env-file value never reaches the container. Docker Compose interpolates $VAR inside env-file values, so the conventional pbkdf2_sha256$600000$salt$hash arrived as 22 characters with three of its four segments gone. Nothing errored: the API booted, the health check passed, and every login failed forever, indistinguishable from a wrong password.

Fixed twice over, because either alone leaves the trap open: the format joins on . so the character never appears, and the hash is now parsed at startup rather than checked for non-emptiness, so corruption by any route stops the boot. This applies to every hand-picked secret containing $, not just this one — written up in Deploy.md §2.3.

F-20 — the test suite reads the developer's .env. Switching the gate on locally failed four unrelated tests, and the failures pointed nowhere near the cause. A root conftest.py pins the settings whose defaults tests assert.

Verification

48 tests (35 backend, 13 frontend), then a live container run with the gate on:

Without a session
/healthz, /auth/me, /auth/logout 200
/repos, /repos/{id}/status, /source, /neighbors, /query 401
/docs, /openapi.json 404
Wrong password 401, no cookie

With a session: hardened cookie, protected routes 200. Gate switched back off: everything open again.

Needs a human

The /workbench → /login redirect has not been seen in a real browser. Its logic has four unit tests — unknown / denied / allowed / network-failure — but headless screenshots do not work in this environment and that is not a reason to claim the check passed.

Please open /workbench signed out and confirm it lands on /login, then sign in and confirm it returns to the workbench.

One behaviour worth knowing rather than fixing: a body that is not JSON at all returns 422 before the gate runs, because Starlette parses the body before dependencies resolve. Valid JSON with wrong fields returns 401. The disclosure is "this endpoint takes JSON", against a path the caller already knows, with the schema off.

make check green: 350 passed / 5 skipped, 83 frontend tests, mypy strict over 86 files.

Deploy.md D-2 and D-6: the landing page and the evaluation write-up stay
public, the product does not. One shared account, so no user table and no
migration.

No new dependency. passlib, pyjwt and itsdangerous are all absent from this
workspace and pulling one in to authenticate a single demo account would be
the larger change, so this is stdlib: PBKDF2-HMAC-SHA256 at OWASP's 600k
floor, and an HMAC-signed session cookie that is HttpOnly, Secure and
SameSite=Lax.

The gate is off by default, so local development, every current compose
invocation and the existing tests are unaffected. docker-compose.prod.yml
HARDCODES it on rather than defaulting it — a production gate that can be
switched off by omitting a variable is not a gate — and the API refuses to
start when it is on but unconfigured, because an auth gate that fails open
looks exactly like one that works.

Also closes F-05: /docs, /redoc and /openapi.json enumerate the /internal/*
surface and are now off in production.

A per-session daily query cap sits on /query alone. The login wall removes
anonymous callers; it does nothing about a signed-in one looping a question
through three metered APIs. It is counted before the agent is reached and
it fails open on a Redis error, because a spend guard that takes the
service down when a cache blips has traded a bounded bill for an outage.

Two findings from verifying this, both fixed here and written up in
Deploy.md.

The first is a real trap. Docker Compose interpolates `$VAR` inside
env-file values, so the conventional `pbkdf2_sha256$600000$salt$hash`
reached the container as 22 characters with three of four segments eaten.
Nothing errored: the API booted, the health check passed, and every login
failed forever, indistinguishable from a wrong password. The format now
joins on "." so the character never appears, and the hash is parsed at
startup rather than checked for non-emptiness, so any corruption stops the
boot. This applies to every hand-picked secret containing `$`, not just
this one.

The second is that the test suite reads the developer's .env, so `make
check` is not hermetic. Switching the gate on locally failed four unrelated
tests and the failures pointed nowhere near the cause. A root conftest.py
pins the settings whose defaults tests assert.

Verified live on a gated container: protected routes 401, /healthz and the
session endpoints 200, /openapi.json 404, wrong password 401 with no
cookie, correct password sets the hardened cookie and opens the gate,
switching it back off restores everything. Not verified: the /workbench to
/login redirect in a real browser — it has four unit tests, but headless
screenshots do not work here and that is not a reason to claim otherwise.
Deploy.md says who needs to look at what.
The two verification items that need a human need the gate switched on
first, and nothing switches it on by default. That walkthrough existed only
in a conversation, which means the next person rediscovers it.

Records the part that actually decides whether the gate can be tested
locally at all: apps/frontend has no .env, so VITE_API_BASE_URL is
undefined and BASE_URL is the empty string, which makes the SPA call
same-origin /api/v1/* on 5173 with vite.config.ts proxying to the gateway.
No cross-origin request, so allow_credentials=False never comes into it.
Pointing VITE_API_BASE_URL at localhost:8000 breaks that, and the failure
would look like a cookie bug rather than a configuration one.

Plus the three things that otherwise cost time: the Secure-cookie fallback
on plain-HTTP localhost, not hand-editing the hash back to $ separators
(§2.3), and that make check is unaffected because conftest.py pins the
setting — which exists because a locally-enabled gate once failed four
unrelated tests with no hint of why.
@Odiethebest
Odiethebest merged commit be3a1fc into main Aug 3, 2026
1 of 2 checks passed
Odiethebest added a commit that referenced this pull request Aug 3, 2026
CI on main has been red since #21 and I did not look. Every report of
"make check green" in this series was true and insufficient: it passes
locally because a developer's .env supplies a real INTERNAL_API_KEY and a
Postgres is running. CI has neither, and CI is the hermetic environment that
exists to catch exactly this.

Two failures, both mine.

#21 added a test that asserted a protected route stops returning 401 by
hitting /repos/{id}/status, which connects to Postgres. The claim being
tested is "the cookie got past require_session", which is about the
dependency and not about the database. It now stubs the session and asserts
404 for an unknown repo — the request reached the handler, which is the
actual proof.

#23 added a startup guard refusing the placeholder INTERNAL_API_KEY, so on a
machine with no .env every test that boots a lifespan died with "still the
placeholder". conftest.py now pins it alongside AUTH_ENABLED and
DOCS_ENABLED. That file was written for precisely this asymmetry, and pinning
two settings and not the third left the hole open — the guard just made it
fatal instead of silent.

Verified in both environments rather than one: 394 passed with .env present,
and 394 passed with .env moved aside and DATABASE_URL pointed at a dead
port, which is the closest local reproduction of CI.
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.

1 participant