Reference Web Application — the pattern every governed project copies (GOV-B7.4, Standard v3.9)
Built under CR-010, 2026-09-01, as the acceptance evidence for REQ-SYS-13 / REQ-PIL-033 / REQ-UC-015 (the mandatory web-application function). Pure Python standard library — no pip installs — so it runs anywhere Python runs, and it containerises in one small image.
What it proves (and how to re-prove it)
| Claim | Evidence command |
|---|---|
| Starts from one command | python3 run.py --engine stub (or --engine glm with GLM_API_KEY set) |
| Serves a login page | open http://127.0.0.1:8000 — named-user login, scrypt-hashed at rest, 5-fail lockout |
| Completes an adapter round-trip | sign in, send a message → reply via the adapter interface (--engine stub echoes offline; --engine glm calls the real engine) |
| No key in any client-served file | tests/test_app.py::test_07 sets a canary GLM_API_KEY and crawls every client-reachable path |
| Outbound requests guarded | tests/test_app.py::TestGuard — http/https only, host validated, loopback/private/link-local refused, connection pinned to the validated IP (no DNS rebinding), redirects refused |
| Responsive, fills the screen | static/app.css — mobile-first fluid grid, 100dvh, centered wide-screen cap, @media breakpoints (the DEF-093 fix pattern) |
| Deploy-anywhere | docker build -t project-webapp . && docker run -p 8000:8000 -e GLM_API_KEY=… project-webapp |
Full suite: python3 -m unittest discover -s tests — 16 tests (also runs under pytest).
The rules it embodies
- GOV-B7.3 / PIL-WA-3: the API key is read from the server ENVIRONMENT at call time. It is never in a
file under static/, never in a response, never logged. Putting it anywhere client-reachable is a Class 1 defect.
- GOV-B7.1: named local user accounts (
users.json, server-side, scrypt hashes; first run prints a
one-time admin password, or seed with ADMIN_USER / ADMIN_PASS).
- Pluggable engines: add a module under
adapters/implementingBaseAdapterand register it in
app.ADAPTERS. GLM ships first; Kimi, Gemini, Claude and GPT adapters are per-project additions.
- INV-6 discipline client-side: engine output is rendered with
textContent, never as HTML.
Known state (honest)
- The real-engine round-trip with a real GLM key is NOT CLOSED — it needs Zaid's key at runtime
(GLM_API_KEY=… python3 run.py, then one message in the UI). The stub round-trip and the guard tests are verified.
users.py, the store and the demo once exposed a two-instance seeding bug (fixed 2026-09-01 after the live
demo caught it; the test suite was re-pointed at the handler's store so it can never mask that class again).