diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..a38a99b
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,57 @@
+# Build-context exclusions for the repo-root images (api, worker, agent,
+# railway-agent-worker, the two model sidecars).
+#
+# Every one of those Dockerfiles COPYs a handful of named paths, so anything
+# here was being sent to the daemon and then ignored. The root context measured
+# ~391 MB, most of it node_modules and .git.
+#
+# Nothing here is COPYed by any Dockerfile — check before adding a path that
+# is, since the failure would be a missing file at build time rather than a
+# slow build.
+
+.git
+.github
+.gitignore
+
+# Environments and secrets. .env is gitignored, but a build context is not a
+# git operation: without this line it would be sent to the daemon and could
+# land in an image layer.
+.env
+.env.*
+!.env.example
+!.env.production.example
+.venv
+venv/
+
+# Caches and build output
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg-info/
+node_modules/
+dist/
+build/
+.vite/
+coverage/
+*.tsbuildinfo
+
+# The frontend is built from its own context (apps/frontend); the backend
+# images have no use for it.
+apps/frontend/
+
+# Documentation, prototypes, and 6.6 MB of recorded evaluation runs. The
+# services read none of them at runtime — the figures are baked into the
+# frontend bundle at build time by scripts/sync_eval_artifacts.py.
+docs/
+design/
+results/
+*.md
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
diff --git a/.env.production.example b/.env.production.example
index f9760a8..b93ae99 100644
--- a/.env.production.example
+++ b/.env.production.example
@@ -35,6 +35,40 @@ REDIS_URL=redis://redis:6379/0
RABBITMQ_URL=amqp://__SET_PROD_RABBITMQ_USER__:__SET_PROD_RABBITMQ_PASSWORD__@rabbitmq:5672/
AGENT_URL=http://agent:8001
+# ============================================================
+# The shared-account gate (Deploy.md D-2 / D-6)
+#
+# docker-compose.prod.yml hardcodes AUTH_ENABLED=true, so production is gated
+# whether or not this file says so, and the API refuses to start if the two
+# required values below are missing. Both are secrets: they belong here, in a
+# gitignored file, and never in a committed one.
+#
+# Generate the hash (prompts without echoing, never takes an argument, so the
+# password stays out of shell history and the process list):
+#
+# python -m dcode_api.hash_password
+#
+# One shared account. There is no user table and no per-person revocation —
+# to remove someone's access, rotate the password. That is the cost of D-6 and
+# it is recorded there rather than discovered here.
+# ============================================================
+AUTH_USERNAME=reviewer
+AUTH_PASSWORD_HASH=__SET_PROD_AUTH_PASSWORD_HASH__
+AUTH_SESSION_SECRET=
+
+# 12 hours. A reviewer session outliving a sitting is the intent.
+# AUTH_SESSION_TTL_SECONDS=43200
+
+# Leave true on Railway and anywhere else serving HTTPS. Set false ONLY for a
+# plain-HTTP staging host: browsers silently drop a Secure cookie over http,
+# so logins there appear to succeed and never stick.
+# AUTH_COOKIE_SECURE=true
+
+# The gate stops anonymous callers; it does nothing about a signed-in one
+# looping a question through three metered APIs. Counted per session per UTC
+# day, checked before the agent is reached.
+# AUTH_DAILY_QUERY_LIMIT=200
+
# --- Internal service auth ---
# Protects every /internal/* retrieval and graph route. The code default is a
# placeholder published in this repository, so this must be set to a real
diff --git a/Deploy.md b/Deploy.md
index d8669e3..cd8a574 100644
--- a/Deploy.md
+++ b/Deploy.md
@@ -25,7 +25,7 @@ Outstanding Work list in the same PR, not tracked in two places.
is written from an approved plan, and plans outrun implementations. Verify before
relying on a claim here, and correct it when it is wrong.
-**Status: PR 1 and PR 2 landed. PR 3–5 not started.** The pre-deployment state
+**Status: PR 1–4 landed. PR 5 not started, and nothing is deployed yet.** The pre-deployment state
is frozen at tag `v1.0-submission` (`a4612b8`). Nothing is deployed anywhere
yet. Both hosted model APIs have been exercised end to end from a running local
stack — see § 2.1 and § 6 PR 2 for the observed values — but **no index has been
@@ -403,7 +403,7 @@ The capability behind D-1.
83 files, 310 passed / 5 skipped, 73 frontend tests. All four modes in § 5.1
still resolve, and `sidecar` remains the default everywhere.
-### PR 3 — `feat/auth-gate`
+### PR 3 — `feat/auth-gate` — **done**
D-2. Also closes F-01 and F-03.
@@ -420,13 +420,36 @@ D-2. Also closes F-01 and F-03.
- A per-session daily query cap. The login wall removes anonymous abuse; it does
not remove a logged-in user looping a query against a metered API.
-**Acceptance.** An unauthenticated request to each protected route returns 401.
-`/`, `/methodology` and `/healthz` are reachable without a session. The
-`/workbench` redirect is verified **by a human in a browser** — headless
-screenshots do not work in this environment, and that limitation is not a reason
-to claim the check passed.
+**Acceptance — met, except the one item that needs eyes.**
-### PR 4 — `feat/railway-deploy`
+48 tests (35 backend, 13 frontend). Then a live container run with the gate on:
+
+| Without a session | |
+|---|---|
+| `/healthz`, `/api/v1/auth/me`, `/api/v1/auth/logout` | 200 — a login endpoint cannot require a login |
+| `/api/v1/repos` (valid body), `/repos/{id}/status`, `/source`, `/neighbors`, `/query` | **401** |
+| `/docs`, `/openapi.json` | **404** — F-05 closed |
+| Wrong password | 401, no cookie set |
+
+| With a session | |
+|---|---|
+| Cookie flags | `HttpOnly; Max-Age=43200; Path=/; SameSite=lax` (`Secure` was off only because the probe ran over local HTTP) |
+| `/repos/{id}/status` | 200 |
+| Gate switched back off | `auth_required:false`, every route open again |
+
+**Not verified: the `/workbench` → `/login` redirect in a real browser.** Its
+logic has four unit tests covering unknown / denied / allowed / failure, but
+headless screenshots do not work in this environment and that is not a reason to
+claim otherwise. **A human should open `/workbench` signed out and confirm it
+lands on `/login`, then sign in and confirm it lands back on the workbench.**
+
+One behaviour worth knowing rather than fixing: a request body that is not JSON
+at all returns 422 before the gate runs, because Starlette parses the body
+before dependencies resolve. A body that is valid JSON with wrong fields returns
+401. The disclosure is "this endpoint takes JSON", against an endpoint whose
+path the caller already knows, with the OpenAPI schema off.
+
+### PR 4 — `feat/railway-deploy` — **built and locally verified; not deployed**
The only Railway-specific PR. Mostly additive files.
@@ -450,10 +473,28 @@ The only Railway-specific PR. Mostly additive files.
(`apps/frontend/src/lib/recentRepos.ts:8`) and there is no default repository,
so a first-time visitor on a new device sees an empty workbench.
-**Acceptance.** A live deployment reachable over HTTPS; login works; one indexed
-repository is selectable; a query streams to completion with verified citations;
-clicking a citation opens real indexed source. Every one of those is confirmed by
-a human in a browser and reported with what was actually seen.
+**Acceptance — the code is built and verified locally; the deployment is not
+done.** Everything below was observed; the row that needs Railway needs Railway.
+
+| Verified locally | How |
+|---|---|
+| The nginx template renders correctly under both shapes | Built the image and read `/etc/nginx/conf.d/default.conf` inside it. Defaults gave `listen 80` / `resolver 127.0.0.11` / `http://api:8000`; overriding the three variables gave `listen 8080` / `[fd12::10]` / `api.railway.internal`. **`$api_upstream` and `$request_uri` survived** — `NGINX_ENVSUBST_FILTER` is what stops envsubst eating nginx's own variables, and without it the config would be valid and quietly broken |
+| gzip | 760,088 → 269,497 bytes on the built main chunk |
+| Cache headers | one `Cache-Control` on hashed assets (the first attempt emitted two), `no-store` on `index.html` |
+| SPA fallback and `/healthz` | 200 from the running container |
+| `GET /api/v1/repos` | live against the local database: 8 repositories, `truncated: false` |
+| Heartbeats and the request budget | 5 tests, including that `close()` still ends a stream while the heartbeat loop runs, and that an overrun emits `TIMEOUT` and **no** `final_answer` |
+| The local stack is unchanged | `docker compose up -d --build api` still healthy; `make check` green |
+
+**Not done: no Railway deployment exists.** The runbook is § 10.2, written from
+the code rather than from a completed deploy — read it as intended sequence and
+correct it against what happens. These are unverified until then: private
+networking over IPv6, the platform's request limits against real heartbeats, the
+pgvector template, and the first hosted-provider index (§ 6 PR 2).
+
+The combined `agent-worker` container has **not been run**, locally or
+otherwise. Its entrypoint is Railway-only and the developer stack does not use
+it, so nothing here exercises it.
### PR 5 — `fix/audit-followups`
@@ -476,29 +517,58 @@ as leads to verify when the PR touches them, not as established fact.
| # | Finding | Where | Severity | PR | Verified |
|---|---|---|---|---|---|
-| F-01 | No authentication of any kind on `/api/v1/*`; no user or tenant concept, so any caller can read any indexed repo by `repo_id` | `apps/api/src/dcode_api/main.py:45-47` | blocker | 3 | audit |
+| F-01 | ~~No authentication of any kind on `/api/v1/*`~~ **— closed in PR 3.** A shared-account session gate now covers repos, query and inspector; `/internal/*` keeps its own shared-key check. Still one principal, not a tenant model (D-6) | `apps/api/src/dcode_api/main.py` | blocker | 3 | **direct** |
| F-02 | ~~The `api` service in the production Compose file has no embedding or reranker configuration~~ **— fixed in PR 1, and it was wider than this row said: `worker` and `agent` were short too. See § 6 PR 1.** | `docker-compose.prod.yml` | blocker | 1 | **direct** |
-| F-03 | No rate limiting, no request-size limit, no quota. `QueryRequest.query` has `min_length` but no `max_length` | `packages/shared/src/dcode_shared/schemas.py:132` | blocker | 3 | audit |
+| F-03 | **Partly closed in PR 3.** Anonymous access is gone and a per-session daily query cap bounds the metered path. **Still open: no request-size limit** — `QueryRequest.query` has `min_length` and no `max_length` | `packages/shared/src/dcode_shared/schemas.py:132` | blocker → medium | 3 → 5 | audit |
| F-04 | `INTERNAL_API_KEY` defaults to a literal published in this repository, with no startup guard outside Compose's `:?` operator — and Railway sets variables per service, so that operator does not protect the deployment | `packages/shared/src/dcode_shared/settings.py:33` | high | 5 | audit |
-| F-05 | `/docs`, `/redoc` and `/openapi.json` are publicly served and advertise the `/internal/*` surface | `apps/api/src/dcode_api/main.py:31-35` | high | 3 | audit |
+| F-05 | ~~`/docs`, `/redoc` and `/openapi.json` are publicly served~~ **— closed in PR 3**, off in production and pinned by a test; observed 404 on a gated container | `apps/api/src/dcode_api/main.py` | high | 3 | **direct** |
| F-06 | SSRF: repository URL validation rejects literal private IPs but has no host allowlist and no resolution check, so a hostname resolving to an internal address passes | `apps/api/src/dcode_api/routes/repos.py:203-224` | high | 5 | audit |
| F-07 | The agent tool cache key omits `index_revision`, so re-indexing a repository does not invalidate cached tool results for up to 24 h | `apps/agent/src/dcode_agent/graph.py:119` | high | 5 | audit |
| F-08 | Cloned workdirs are never cleaned up, for any repository, ever. On a fixed Railway volume this is unbounded growth | `apps/worker/src/dcode_worker/stages/clone.py:17-22` | high | 5 | audit |
-| F-09 | No repository list endpoint; the switcher reads `localStorage` only and there is no default repository | `apps/frontend/src/lib/recentRepos.ts:8` | high | 4 | **direct** |
+| F-09 | ~~No repository list endpoint~~ **— fixed in PR 4.** `GET /api/v1/repos`, merged behind the localStorage recents so a reader on a new device sees what is indexed. Verified live against the local database: 8 repositories returned | `apps/api/src/dcode_api/routes/repos.py` | high | 4 | **direct** |
| F-10 | `/healthz` returns `ok` unconditionally — it reports healthy with every dependency down. No readiness probe exists | `apps/api/src/dcode_api/main.py:51-54` | medium | 5 | audit |
| F-11 | ~~The two documented production Compose invocations disagree; one of them republishes Postgres, Redis and the RabbitMQ UI~~ **— fixed in PR 1.** | `README.md`, `.env.production.example` | medium | 1 | **direct** |
| F-12 | ~~`RERANKER_ENDPOINT` defaults to a dead loopback address in the production template~~ **— fixed in PR 1, pinned by a test.** | `docker-compose.prod.yml`, `.env.production.example` | medium | 1 | **direct** |
| F-13 | Embedding retries are 12 attempts against a 300 s timeout; with `prefetch_count=1` one bad batch stalls the entire indexing queue. **Knob added in PR 1 (`EMBEDDING_TIMEOUT_SECONDS`); the values are set in PR 2, where the path that needs them exists.** | `packages/shared/src/dcode_shared/embedding.py:19-20` | medium | 1 → 2 | audit |
| F-14 | `git clone` receives the repository URL with no `--` separator, so a URL beginning with `-` is parsed as an option. Gateway validation is the only defence; the worker has none | `apps/worker/src/dcode_worker/stages/clone.py:22` | medium | 5 | audit |
| F-15 | The `grep` tool runs `rg` with no timeout and buffers all output in memory; the pure-Python fallback compiles a user-supplied regex with no timeout | `apps/agent/src/dcode_agent/tools/grep.py:44-58`, `:79-101` | medium | 5 | audit |
-| F-16 | nginx serves the bundle uncompressed — gzip is commented out in the base image and not enabled in the site config. Main chunk 752.53 kB / 226.74 kB gzipped | `apps/frontend/nginx.conf` | low | 4 | **direct** |
-| F-17 | No `.dockerignore` anywhere; the frontend build context ships 227 MB of `node_modules` | repository root | low | 4 | **direct** |
+| F-16 | ~~nginx serves the bundle uncompressed~~ **— fixed in PR 4**, measured on the built image at 760,088 → 269,497 bytes. Also fixed a duplicate `Cache-Control` header the first attempt introduced | `apps/frontend/nginx.conf.template` | low | 4 | **direct** |
+| F-17 | ~~No `.dockerignore` anywhere~~ **— fixed in PR 4**, one at the root and one for `apps/frontend` | repository root | low | 4 | **direct** |
+| F-21 | ~~A copy-pasteable setup block in § 10.1 contained placeholders, was pasted verbatim, and the placeholder became the credential — the API then refused to boot~~ **— fixed in PR 4** by rewriting the block to substitute its own values. The refusal was correct; the instructions were the defect | `Deploy.md` §10.1 | low | 4 | **direct** |
+| F-19 | ~~A `$` in an env-file value is silently eaten by Compose interpolation, so a `$`-separated password hash reached the container as 22 of ~100 characters and every login failed while the service reported healthy~~ **— fixed in PR 3** (format changed, and the hash is now parsed at startup). Applies to any hand-picked secret containing `$` — see § 2.3 | `apps/api/src/dcode_api/auth.py` | high | 3 | **direct** |
+| F-20 | ~~The test suite reads the developer's `.env`, so `make check` is not hermetic — enabling the gate locally failed four unrelated tests with no hint of the cause~~ **— fixed in PR 3** by a root `conftest.py` pinning the settings whose defaults tests assert | `conftest.py` | medium | 3 | **direct** |
| F-18 | Model sidecars download weights from Hugging Face at runtime with no cache volume | `infra/docker/embedding.Dockerfile`, `infra/docker/reranker.Dockerfile` | low | — | **direct** |
F-18 is recorded but **not scheduled**: D-1 removes the sidecars from the
deployment path, so it only affects local Docker-profile use. It is left as a
known cost of that mode rather than fixed speculatively.
+### 2.3 A `$` in an env-file value is eaten before the container sees it
+
+Found while verifying PR 3, and it had already produced a working-looking
+failure. Docker Compose interpolates `${VAR}` **and bare `$VAR`** inside
+env-file values. A PBKDF2 hash of the conventional
+`pbkdf2_sha256$600000$salt$hash` form therefore reached the container as 22
+characters with three of its four segments gone.
+
+Nothing errored. Compose printed interpolation warnings among its normal
+output, the API booted, the health check passed, and **every login failed
+forever** — indistinguishable from a wrong password.
+
+Two changes, because either alone leaves the trap open:
+
+- the hash format joins its segments with `.` instead of `$`, so the character
+ never appears in the value (base64url contains no `.`, so it stays
+ unambiguous). Escaping as `$$` would also work and would be remembered by
+ nobody;
+- `auth_configuration_error()` now parses the hash rather than checking it is
+ non-empty, so a value corrupted by any means stops the boot instead of
+ producing a service that is up and unopenable.
+
+**This applies to every secret, not just this one.** A Postgres or RabbitMQ
+password containing `$` will be corrupted the same way. `secrets.token_urlsafe`
+output is safe (`A-Za-z0-9_-`); anything hand-picked is not.
+
### Already correct, recorded so nobody "fixes" it
- SSE anti-buffering headers are set on both hops — `Cache-Control: no-cache` and
@@ -589,6 +659,145 @@ Before calling the deployment done:
---
+### 10.1 Seeing the auth gate locally
+
+The two checks above that need a human need the gate switched on first, and
+nothing switches it on by default. This is how, written down because otherwise
+the next person rediscovers it.
+
+**The login page itself needs none of this.** `/login` is a public route and
+renders whatever the gate is doing: `http://localhost:5173/login`. What that
+does *not* show you is the behaviour — the redirect, the refusal, the error —
+which is the part worth looking at.
+
+**One command, and it does the substitution itself.** An earlier version of
+this section was a `cat >> .env` block with `` inside it.
+It got pasted verbatim, the placeholder became the value, and the API refused
+to boot — correctly, and with the right message, but the walkthrough should not
+be the thing that breaks the stack. A copy-pasteable block containing
+placeholders is a trap; this one has none.
+
+```bash
+# Prompts for the password (unechoed), generates the secret, appends nothing
+# you have to edit afterwards. Run from the repository root.
+python3 - <<'SETUP'
+import getpass, pathlib, secrets, subprocess, sys
+password = getpass.getpass("Gate password: ")
+if not password or password != getpass.getpass("Confirm: "):
+ sys.exit("passwords empty or do not match")
+digest = subprocess.run(
+ [sys.executable, "-c",
+ "import sys; sys.path[:0]=['apps/api/src','packages/shared/src'];"
+ "from dcode_api.auth import hash_password; print(hash_password(sys.argv[1]))",
+ password],
+ capture_output=True, text=True, check=True,
+).stdout.strip()
+pathlib.Path(".env").open("a").write(
+ "\n# --- local auth-gate check; delete this block afterwards ---\n"
+ "AUTH_ENABLED=true\n"
+ "AUTH_USERNAME=reviewer\n"
+ f"AUTH_PASSWORD_HASH={digest}\n"
+ f"AUTH_SESSION_SECRET={secrets.token_urlsafe(48)}\n"
+)
+print("appended to .env")
+SETUP
+
+# Recreate the API. No --build: the image already carries the code and only
+# the environment changed.
+docker compose up -d api
+```
+
+If the API exits on boot with `AUTH_PASSWORD_HASH is not a valid hash`, the
+value in `.env` is not one — the fail-closed check in § 6 PR 3 doing its job.
+Fix the line rather than the check.
+
+The Vite dev server does not need restarting. There is no build-time switch —
+the SPA asks `/api/v1/auth/me` at runtime and renders accordingly.
+
+**Then look at four things in a real browser:**
+
+| Do this | Expect |
+|---|---|
+| Open `/workbench` signed out | a brief `checking session…`, then a redirect to `/login` |
+| Submit a wrong password | `Incorrect username or password.` under the form, no navigation |
+| Submit the right password | lands on `/workbench`, workbench works |
+| Open `/` and `/methodology` | load normally, **no** sign-in |
+
+Rows one and three are the items § 10 records as unverified.
+
+**Why the cookie works here at all**, since it is the question that decides
+whether any of this can be tested locally: `apps/frontend` has no `.env`, so
+`VITE_API_BASE_URL` is undefined and `BASE_URL` is the empty string
+(`src/api/client.ts`). The SPA therefore calls **same-origin** `/api/v1/*` on
+port 5173 and `vite.config.ts` proxies `/api` to the gateway. No cross-origin
+request, so `allow_credentials=False` on the CORS middleware never comes into
+it. Point `VITE_API_BASE_URL` at `http://localhost:8000` and that stops being
+true — the browser would refuse to send the cookie and the CORS policy would
+refuse the credentialed request.
+
+**Three things that will otherwise waste your time:**
+
+- `AUTH_COOKIE_SECURE` defaults to true, and browsers treat `http://localhost`
+ as a trustworthy origin, so it should hold. If a successful sign-in bounces
+ straight back to `/login`, the cookie is not being stored — set
+ `AUTH_COOKIE_SECURE=false` and recreate the API.
+- **Do not hand-edit the hash back to `$` separators.** That is § 2.3, and its
+ symptom is a login that fails forever with nothing in the logs.
+- `make check` is unaffected. The root `conftest.py` pins `AUTH_ENABLED=false`
+ for tests, which exists precisely because a locally-enabled gate once failed
+ four unrelated tests with no hint of why (F-20).
+
+**Afterwards**, delete the block from `.env` and `docker compose up -d api`.
+`curl -s localhost:8000/api/v1/auth/me` returning `"auth_required":false`
+confirms you are back.
+
+---
+
+### 10.2 Railway runbook
+
+Written from the code, not from a completed deployment — **nothing has been
+deployed yet** (§ 6 PR 4). Treat it as the intended sequence, and correct it
+against what actually happens.
+
+**Services.** Six. Only `frontend` gets a public domain.
+
+| Service | Image | Notes |
+|---|---|---|
+| `frontend` | `infra/docker/frontend.Dockerfile`, context `apps/frontend` | Public. Set `API_UPSTREAM=http://api.railway.internal:8000` and `DNS_RESOLVER` to Railway's internal resolver. `PORT` is injected. |
+| `api` | `infra/docker/api.Dockerfile`, context repo root | Private. Set `HOST=::` — Railway's private network is IPv6 and a service bound to `0.0.0.0` is reachable by nothing there. |
+| `agent-worker` | `infra/docker/railway-agent-worker.Dockerfile`, context repo root | Private. **Owns the only volume**, mounted at `WORKDIR_BASE`. Set `HOST=::`. |
+| Postgres | Railway **pgvector** template | Not the plain Postgres template — R-3. |
+| Redis | Railway template | |
+| RabbitMQ | Railway template | |
+
+**Order.** Postgres/Redis/RabbitMQ first, then `api`, then run the migration
+against it, then `agent-worker`, then `frontend`. The migration reads
+`EMBEDDING_DIM` from the `api` service (§ 6 PR 1), so that variable has to be
+right *before* it runs — afterwards the column dimension is fixed and changing
+it means a new volume.
+
+**Variables that must agree across `api`, `agent-worker` and each other**:
+`EMBEDDING_*`, `RERANKER_*`, `INTERNAL_API_KEY`, `EMBEDDING_DIM`. § 5.4 explains
+what a mismatch looks like, which is nothing — no error, just worse retrieval.
+
+**Values with a `$` in them will be corrupted** if they pass through an env
+file (§ 2.3). Railway's dashboard is not an env file, so pasting there is safe;
+a `railway.json` or a bulk import is not.
+
+**Set on `api`:** `AUTH_ENABLED=true`, `AUTH_USERNAME`, `AUTH_PASSWORD_HASH`,
+`AUTH_SESSION_SECRET`, `AUTH_COOKIE_SECURE=true`, `DOCS_ENABLED=false`.
+Railway serves HTTPS, so the Secure cookie is correct there.
+
+**Then walk § 10's checklist.** The rows that need a browser need a browser.
+
+**Two things this project has not solved and will meet here.** The first index
+runs through the hosted embedding API for real — roughly 23 requests for
+`psf/requests` — and that path has never been exercised (§ 6 PR 2). The second
+is that cloned workdirs are never cleaned up (F-08), so the volume grows with
+every distinct repository anyone indexes, forever.
+
+---
+
## 11. Open Questions
Carried here rather than answered by assumption.
diff --git a/apps/agent/src/dcode_agent/main.py b/apps/agent/src/dcode_agent/main.py
index b405e91..6ca0b32 100644
--- a/apps/agent/src/dcode_agent/main.py
+++ b/apps/agent/src/dcode_agent/main.py
@@ -103,7 +103,7 @@ async def internal_query(
)
)
return StreamingResponse(
- emitter.iter_bytes(),
+ emitter.iter_bytes(heartbeat_seconds=agent_settings.sse_heartbeat_seconds),
media_type="text/event-stream",
headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
)
@@ -119,23 +119,28 @@ async def _run_graph_pipeline(
llm_client: Any = None,
) -> None:
"""Invoke the compiled graph and flush terminal SSE events."""
+ budget = agent_settings.request_budget_seconds
try:
- async with db_session_factory() as db:
- final_state = await compiled_graph.ainvoke(
- AgentState(
- repo_id=state.repo_id,
- query=state.query,
- mode=state.mode,
- history=state.history,
- runtime={
- "emitter": emitter,
- "tool_registry": tool_registry,
- "tool_cache": tool_cache,
- "db": db,
- "llm": llm_client,
- },
+ # A ceiling on the whole walk, not just each hop. Without it a query
+ # can outlive the platform's request limit, and the reader sees a
+ # stream that stops rather than one that says why.
+ async with asyncio.timeout(budget if budget > 0 else None):
+ async with db_session_factory() as db:
+ final_state = await compiled_graph.ainvoke(
+ AgentState(
+ repo_id=state.repo_id,
+ query=state.query,
+ mode=state.mode,
+ history=state.history,
+ runtime={
+ "emitter": emitter,
+ "tool_registry": tool_registry,
+ "tool_cache": tool_cache,
+ "db": db,
+ "llm": llm_client,
+ },
+ )
)
- )
state_dict = _state_dict(final_state)
citations = _citation_events(state_dict)
@@ -159,6 +164,20 @@ async def _run_graph_pipeline(
citations=citations,
groundedness=float(state_dict.get("groundedness_score") or 0.0),
)
+ except TimeoutError:
+ # Distinct from INTERNAL on purpose: "this took too long" is a
+ # different thing for a reader to know than "something broke", and the
+ # honest answer here is that no answer was produced. Nothing
+ # half-finished is emitted — a partial walk has not been through the
+ # groundedness verifier, so presenting it would claim a check that
+ # never ran (Honesty_Constraints §3).
+ await emitter.emit_error(
+ code="TIMEOUT",
+ message=(
+ f"the agent exceeded its {agent_settings.request_budget_seconds:.0f}s budget "
+ "for one question"
+ ),
+ )
except Exception as exc: # noqa: BLE001 — surface any unexpected failure as SSE error
await emitter.emit_error(code="INTERNAL", message=str(exc))
finally:
diff --git a/apps/agent/src/dcode_agent/settings.py b/apps/agent/src/dcode_agent/settings.py
index b7469e3..7f3496b 100644
--- a/apps/agent/src/dcode_agent/settings.py
+++ b/apps/agent/src/dcode_agent/settings.py
@@ -24,5 +24,20 @@ class AgentSettings(SharedSettings):
synthesis_max_tokens: int = 700
synthesis_temperature: float = 0.1
+ # --- Stream lifetime (Deploy.md R-2) ---
+ # A query had no overall ceiling: /internal/query spawns a task and returns
+ # a stream, and only the individual hops were bounded, so 14 steps x 30s
+ # plus rerank and synthesis could run past eight minutes with nothing to
+ # stop it. An abandoned request kept spending on three metered APIs with
+ # nobody draining the queue.
+ #
+ # 240s is chosen to expire *inside* the hosting platform's 5-minute cut, so
+ # the client gets a labelled `error` event instead of a connection that
+ # simply stops. 0 disables the ceiling.
+ request_budget_seconds: float = 240.0
+ # Comment frames while the queue is quiet. Below both the platform's
+ # 5-minute idle cut and the gateway client's 60s read timeout.
+ sse_heartbeat_seconds: float = 20.0
+
agent_settings = AgentSettings()
diff --git a/apps/agent/src/dcode_agent/sse.py b/apps/agent/src/dcode_agent/sse.py
index ec9d940..b75e9b8 100644
--- a/apps/agent/src/dcode_agent/sse.py
+++ b/apps/agent/src/dcode_agent/sse.py
@@ -90,10 +90,31 @@ async def close(self) -> None:
"""Signal end-of-stream; iter_bytes() will exit on the next loop."""
await self._queue.put(None)
- async def iter_bytes(self) -> AsyncIterator[bytes]:
- """Drain the queue. Caller streams these bytes to the client."""
+ async def iter_bytes(self, *, heartbeat_seconds: float = 0.0) -> AsyncIterator[bytes]:
+ """Drain the queue. Caller streams these bytes to the client.
+
+ With `heartbeat_seconds` above zero, a comment frame is emitted
+ whenever the queue stays quiet that long. Two reasons it has to exist:
+ a hosting platform in front of this closes a request that transfers no
+ data for five minutes, and the gateway's own client has a 60-second
+ read timeout. The agent can legitimately be silent for longer than
+ either while a slow tool or a synthesis call runs.
+
+ A `:`-prefixed line is a comment in the SSE grammar. The frontend
+ parser already skips them (`src/api/client.ts`), so this changes no
+ client contract and adds no event type.
+ """
while True:
- chunk = await self._queue.get()
+ if heartbeat_seconds <= 0:
+ chunk = await self._queue.get()
+ else:
+ try:
+ chunk = await asyncio.wait_for(
+ self._queue.get(), timeout=heartbeat_seconds
+ )
+ except TimeoutError:
+ yield b": keep-alive\n\n"
+ continue
if chunk is None:
return
yield chunk
diff --git a/apps/agent/tests/test_stream_lifetime.py b/apps/agent/tests/test_stream_lifetime.py
new file mode 100644
index 0000000..98c89b0
--- /dev/null
+++ b/apps/agent/tests/test_stream_lifetime.py
@@ -0,0 +1,120 @@
+"""Stream keep-alive and the whole-request ceiling (Deploy.md R-2).
+
+Both exist because of one platform fact: a request that transfers no data for
+five minutes is closed, and even with data it is capped at about fifteen. The
+agent previously had per-hop timeouts only, so a query could outlive both and
+the reader would see a stream that simply stopped.
+"""
+
+import asyncio
+
+import pytest
+from dcode_agent.sse import SSEEmitter
+
+
+async def _drain(emitter: SSEEmitter, *, heartbeat_seconds: float) -> list[bytes]:
+ return [chunk async for chunk in emitter.iter_bytes(heartbeat_seconds=heartbeat_seconds)]
+
+
+async def test_no_heartbeat_when_disabled() -> None:
+ """Zero keeps the original behaviour, so nothing changes where it is not wanted."""
+ emitter = SSEEmitter()
+ await emitter.emit_thought(1, "hello")
+ await emitter.close()
+
+ chunks = await _drain(emitter, heartbeat_seconds=0)
+
+ assert len(chunks) == 1
+ assert b"thought" in chunks[0]
+ assert not any(chunk.startswith(b":") for chunk in chunks)
+
+
+async def test_a_quiet_stream_emits_comment_frames() -> None:
+ emitter = SSEEmitter()
+
+ async def finish_later() -> None:
+ await asyncio.sleep(0.25)
+ await emitter.emit_thought(1, "finally")
+ await emitter.close()
+
+ task = asyncio.create_task(finish_later())
+ chunks = await _drain(emitter, heartbeat_seconds=0.05)
+ await task
+
+ heartbeats = [chunk for chunk in chunks if chunk.startswith(b":")]
+ assert heartbeats, "a stream quiet for longer than the interval must be kept alive"
+ assert all(chunk == b": keep-alive\n\n" for chunk in heartbeats)
+ assert b"thought" in chunks[-1]
+
+
+async def test_heartbeats_are_sse_comments_the_client_already_skips() -> None:
+ """A `:`-prefixed line is a comment in the SSE grammar.
+
+ The frontend parser drops those already (src/api/client.ts), so this adds
+ no event type and changes no client contract. If the frame ever stops
+ starting with ':' it becomes an unparseable event instead.
+ """
+ emitter = SSEEmitter()
+ await emitter.close()
+ assert b": keep-alive\n\n".startswith(b":")
+ assert (await _drain(emitter, heartbeat_seconds=10)) == []
+
+
+async def test_heartbeat_does_not_swallow_the_end_of_stream() -> None:
+ """close() must still terminate while the heartbeat loop is running."""
+ emitter = SSEEmitter()
+ await emitter.emit_partial_answer("x")
+ await emitter.close()
+
+ chunks = await asyncio.wait_for(_drain(emitter, heartbeat_seconds=0.01), timeout=2.0)
+
+ assert b"partial_answer" in chunks[0]
+
+
+@pytest.mark.parametrize("budget", [0.05])
+async def test_the_request_budget_emits_a_labelled_error(budget: float) -> None:
+ """A query that overruns says so, rather than the connection just ending.
+
+ TIMEOUT is distinct from INTERNAL because "this took too long" is a
+ different thing for a reader to know than "something broke". Nothing
+ half-finished is emitted: a partial walk has not been through the
+ groundedness verifier, and presenting it would claim a check that never
+ ran (Honesty_Constraints §3).
+ """
+ from dcode_agent import main as agent_main
+ from dcode_agent.settings import agent_settings
+ from dcode_agent.state import AgentState
+
+ class _NeverFinishes:
+ async def ainvoke(self, _state: object) -> object:
+ await asyncio.sleep(30)
+ raise AssertionError("should have been cancelled")
+
+ class _Session:
+ async def __aenter__(self) -> object:
+ return object()
+
+ async def __aexit__(self, *_: object) -> None:
+ return None
+
+ original = agent_settings.request_budget_seconds
+ agent_settings.request_budget_seconds = budget
+ try:
+ emitter = SSEEmitter()
+ await agent_main._run_graph_pipeline(
+ emitter,
+ AgentState(repo_id="r", query="q", mode="full", history=[]),
+ _NeverFinishes(),
+ None,
+ None,
+ _Session,
+ None,
+ )
+ chunks = await _drain(emitter, heartbeat_seconds=0)
+ finally:
+ agent_settings.request_budget_seconds = original
+
+ body = b"".join(chunks)
+ assert b"event: error" in body
+ assert b"TIMEOUT" in body
+ assert b"final_answer" not in body
diff --git a/apps/api/src/dcode_api/auth.py b/apps/api/src/dcode_api/auth.py
new file mode 100644
index 0000000..a535ffe
--- /dev/null
+++ b/apps/api/src/dcode_api/auth.py
@@ -0,0 +1,245 @@
+"""Single shared-account session auth for the gated deployment.
+
+Deploy.md D-6 chose one shared account over per-reviewer accounts: no user
+table, no migration, no account lifecycle. This module is what that decision
+costs — roughly a hundred lines of stdlib and 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.
+
+What it is not: an authorization model. There is one principal, a shared secret
+cannot be revoked for one holder, and the daily query cap is therefore per
+*session* rather than per person. Those limits are recorded in Deploy.md rather
+than papered over here.
+
+**Auth is off by default** (`AUTH_ENABLED=false`) so local development, the
+existing test suite and every current compose invocation are unaffected
+(Deploy.md §5.1). Production turns it on, and `docker-compose.prod.yml` hard-
+codes it rather than defaulting it, so a deployment cannot forget. If it is on
+and unconfigured the app refuses to start — an auth gate that fails open is
+worse than none, because it looks like one.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from fastapi import Cookie, Depends, HTTPException, status
+
+from dcode_api.settings import api_settings
+
+SESSION_COOKIE_NAME = "dcode_session"
+
+_HASH_SCHEME = "pbkdf2_sha256"
+# Segments are joined with "." and NOT with passlib's conventional "$".
+#
+# Docker Compose interpolates `${VAR}` *and* bare `$VAR` inside env-file
+# values. A `$`-separated hash therefore arrives at the container mangled:
+# `pbkdf2_sha256$600000$salt$hash` lost three of its four segments in testing
+# and shrank to 22 characters. Nothing errors — the value is still non-empty,
+# the app still boots, and every login just fails forever. Escaping as `$$` in
+# the env file would work and would be remembered by nobody, so the format
+# avoids the character instead. The base64url alphabet has no ".", so this is
+# unambiguous.
+_HASH_SEPARATOR = "."
+# OWASP's 2023 floor for PBKDF2-HMAC-SHA256. Encoded into the hash string, so
+# raising it later does not invalidate credentials already issued.
+_DEFAULT_ITERATIONS = 600_000
+_SALT_BYTES = 16
+
+
+# --- password hashing ----------------------------------------------------
+
+
+def _parse_hash(encoded: str) -> tuple[int, bytes, bytes] | None:
+ """Split an encoded hash, or None if it is not one."""
+ try:
+ scheme, raw_iterations, salt_b64, expected_b64 = encoded.split(_HASH_SEPARATOR)
+ if scheme != _HASH_SCHEME:
+ return None
+ return int(raw_iterations), _b64decode(salt_b64), _b64decode(expected_b64)
+ except (ValueError, TypeError):
+ return None
+
+
+def hash_password(password: str, *, iterations: int = _DEFAULT_ITERATIONS) -> str:
+ """Encode a password as ``pbkdf2_sha256$iterations$salt$hash``."""
+ salt = secrets.token_bytes(_SALT_BYTES)
+ derived = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, iterations)
+ return _HASH_SEPARATOR.join(
+ [_HASH_SCHEME, str(iterations), _b64encode(salt), _b64encode(derived)]
+ )
+
+
+def verify_password(password: str, encoded: str) -> bool:
+ """Check a password against an encoded hash, in constant time.
+
+ Returns False rather than raising on a malformed hash: a misconfigured
+ `AUTH_PASSWORD_HASH` must deny access, not crash the request handler into
+ a 500 that a caller could tell apart from a wrong password.
+ """
+ parsed = _parse_hash(encoded)
+ if parsed is None:
+ return False
+ iterations, salt, expected = parsed
+
+ derived = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), salt, iterations)
+ return hmac.compare_digest(derived, expected)
+
+
+# --- session tokens ------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SessionClaims:
+ """A validated session. `jti` scopes the per-session daily query budget."""
+
+ sub: str
+ jti: str
+ issued_at: int
+ expires_at: int
+
+
+def issue_session(username: str, *, ttl_seconds: int, secret: str) -> str:
+ """Mint a signed ``payload.signature`` token. Not encrypted — only signed.
+
+ The payload is readable by the holder, which is fine: it carries a username
+ they just typed and two timestamps. What matters is that they cannot change
+ it, and that a stolen token expires.
+ """
+ now = int(time.time())
+ payload = {
+ "sub": username,
+ "jti": secrets.token_urlsafe(12),
+ "iat": now,
+ "exp": now + ttl_seconds,
+ }
+ encoded = _b64encode(json.dumps(payload, separators=(",", ":")).encode("utf-8"))
+ return f"{encoded}.{_sign(encoded, secret)}"
+
+
+def read_session(token: str, *, secret: str, now: int | None = None) -> SessionClaims | None:
+ """Validate a token and return its claims, or None for any failure.
+
+ Every rejection collapses to None on purpose. Distinguishing "bad
+ signature" from "expired" in the response would tell an attacker which half
+ of a forgery attempt worked.
+ """
+ encoded, separator, signature = token.partition(".")
+ if not separator or not encoded or not signature:
+ return None
+ if not hmac.compare_digest(signature, _sign(encoded, secret)):
+ return None
+
+ try:
+ payload = json.loads(_b64decode(encoded))
+ except (ValueError, TypeError):
+ return None
+ if not isinstance(payload, dict):
+ return None
+
+ sub, jti = payload.get("sub"), payload.get("jti")
+ issued_at, expires_at = payload.get("iat"), payload.get("exp")
+ if not isinstance(sub, str) or not isinstance(jti, str):
+ return None
+ if not isinstance(issued_at, int) or not isinstance(expires_at, int):
+ return None
+ if (now if now is not None else int(time.time())) >= expires_at:
+ return None
+
+ return SessionClaims(sub=sub, jti=jti, issued_at=issued_at, expires_at=expires_at)
+
+
+# --- configuration -------------------------------------------------------
+
+
+def auth_configuration_error() -> str | None:
+ """Return why auth cannot be enforced, or None when it is ready.
+
+ Called at startup so an unconfigured production container dies on boot
+ instead of serving the workbench to anyone who asks.
+ """
+ if not api_settings.auth_enabled:
+ return None
+ if not api_settings.auth_username.strip():
+ return "AUTH_USERNAME is required when AUTH_ENABLED is true"
+ if not api_settings.auth_password_hash.strip():
+ return (
+ "AUTH_PASSWORD_HASH is required when AUTH_ENABLED is true "
+ "(generate one with: python -m dcode_api.hash_password)"
+ )
+ # Checked for shape, not just presence. A hash that arrives corrupted —
+ # the historical case is an env-file interpolation eating it — leaves a
+ # non-empty value that rejects every login while the service reports
+ # healthy. Refusing to boot is the only honest response to that.
+ if _parse_hash(api_settings.auth_password_hash.strip()) is None:
+ return (
+ "AUTH_PASSWORD_HASH is not a valid hash. Regenerate it with "
+ "`python -m dcode_api.hash_password`, and if the value passes "
+ "through an env file check that nothing rewrote it"
+ )
+ if len(api_settings.auth_session_secret.strip()) < 32:
+ return "AUTH_SESSION_SECRET must be at least 32 characters when AUTH_ENABLED is true"
+ return None
+
+
+# --- request dependencies ------------------------------------------------
+
+
+def current_session(
+ dcode_session: str | None = Cookie(default=None, alias=SESSION_COOKIE_NAME),
+) -> SessionClaims | None:
+ """Read and validate the session cookie. None when absent, invalid, or off."""
+ if not api_settings.auth_enabled or not dcode_session:
+ return None
+ return read_session(dcode_session, secret=api_settings.auth_session_secret)
+
+
+def require_session(
+ session: SessionClaims | None = Depends(current_session),
+) -> SessionClaims | None:
+ """Router-level gate. A no-op when auth is disabled, 401 otherwise."""
+ if not api_settings.auth_enabled:
+ return None
+ if session is None:
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail={"code": "NOT_AUTHENTICATED", "message": "sign in to use this endpoint"},
+ )
+ return session
+
+
+# --- per-session daily query budget --------------------------------------
+
+
+def quota_key(session: SessionClaims, *, today: str | None = None) -> str:
+ """Redis key for one session's spend on one UTC day.
+
+ Keyed by `jti`, so the budget is per sign-in rather than per account —
+ which is the only granularity a shared account can offer (D-6).
+ """
+ day = today or datetime.now(UTC).strftime("%Y-%m-%d")
+ return f"authquota:{session.jti}:{day}"
+
+
+# --- helpers -------------------------------------------------------------
+
+
+def _sign(payload: str, secret: str) -> str:
+ digest = hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).digest()
+ return _b64encode(digest)
+
+
+def _b64encode(raw: bytes) -> str:
+ return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _b64decode(encoded: str) -> bytes:
+ padding = "=" * (-len(encoded) % 4)
+ return base64.urlsafe_b64decode(encoded + padding)
diff --git a/apps/api/src/dcode_api/hash_password.py b/apps/api/src/dcode_api/hash_password.py
new file mode 100644
index 0000000..23c6f79
--- /dev/null
+++ b/apps/api/src/dcode_api/hash_password.py
@@ -0,0 +1,37 @@
+"""Generate an ``AUTH_PASSWORD_HASH`` value.
+
+ python -m dcode_api.hash_password
+
+Prompts without echoing, confirms, and prints the line to paste. Reading the
+password from an argument was rejected deliberately: it would put the
+credential in shell history and in the process list.
+"""
+
+import getpass
+import sys
+
+from dcode_api.auth import hash_password
+
+
+def main() -> int:
+ password = getpass.getpass("Password: ")
+ if not password:
+ print("empty password refused", file=sys.stderr)
+ return 1
+ if password != getpass.getpass("Confirm: "):
+ print("passwords do not match", file=sys.stderr)
+ return 1
+
+ print()
+ print("Add to .env.production (never to a committed file):")
+ print()
+ print(f"AUTH_PASSWORD_HASH={hash_password(password)}")
+ print()
+ print("And a session secret, at least 32 characters:")
+ print()
+ print("AUTH_SESSION_SECRET=$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/apps/api/src/dcode_api/main.py b/apps/api/src/dcode_api/main.py
index 95303ab..c84966c 100644
--- a/apps/api/src/dcode_api/main.py
+++ b/apps/api/src/dcode_api/main.py
@@ -8,16 +8,24 @@
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
-from fastapi import FastAPI
+from fastapi import Depends, FastAPI
from fastapi.middleware.cors import CORSMiddleware
from dcode_api import deps
-from dcode_api.routes import inspector, internal, query, repos
+from dcode_api.auth import auth_configuration_error, require_session
+from dcode_api.routes import auth, inspector, internal, query, repos
from dcode_api.settings import api_settings
@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+ # Refuse to start a gate that cannot be enforced. Serving the workbench
+ # openly because a secret was missing is the failure this prevents, and it
+ # is one that looks fine from the outside.
+ misconfigured = auth_configuration_error()
+ if misconfigured is not None:
+ raise RuntimeError(misconfigured)
+
# Own the shared Redis + agent-client lifecycle: warm at startup, release on
# shutdown. (DB uses the shared SQLAlchemy engine pool; RabbitMQ connects per
# publish on the submit path.)
@@ -28,27 +36,52 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
await deps.close_pools()
-app = FastAPI(
- title="Dcode API Gateway",
- version="0.0.0",
- lifespan=lifespan,
-)
+def create_app() -> FastAPI:
+ """Build the gateway. A function so the docs switch is testable.
+
+ `app` below is what uvicorn imports; nothing else should call this except
+ tests that need a second instance under different settings.
+ """
+ application = FastAPI(
+ title="Dcode API Gateway",
+ version="0.0.0",
+ lifespan=lifespan,
+ # /docs, /redoc and /openapi.json enumerate the /internal/* retrieval
+ # and graph surface. Handy locally, an advertisement in production.
+ docs_url="/docs" if api_settings.docs_enabled else None,
+ redoc_url="/redoc" if api_settings.docs_enabled else None,
+ openapi_url="/openapi.json" if api_settings.docs_enabled else None,
+ )
+
+ application.add_middleware(
+ CORSMiddleware,
+ allow_origins=api_settings.cors_origins_list,
+ allow_methods=["GET", "POST", "OPTIONS"],
+ allow_headers=["*"],
+ allow_credentials=False,
+ )
+
+ # The gate. `require_session` is a no-op while AUTH_ENABLED is false, so
+ # the default local stack and the existing tests see no change; with it on,
+ # every route below returns 401 without a valid session cookie.
+ gated = [Depends(require_session)]
+
+ # Not gated: signing in cannot require being signed in.
+ application.include_router(auth.router, prefix="/api/v1")
+
+ application.include_router(repos.router, prefix="/api/v1", dependencies=gated)
+ application.include_router(query.router, prefix="/api/v1", dependencies=gated)
+ application.include_router(inspector.router, prefix="/api/v1", dependencies=gated)
+ # /internal/* is not part of the session gate: it is service-to-service and
+ # carries its own shared-key check, and the agent has no cookie to present.
+ application.include_router(internal.router, prefix="/internal")
-app.add_middleware(
- CORSMiddleware,
- allow_origins=api_settings.cors_origins_list,
- allow_methods=["GET", "POST", "OPTIONS"],
- allow_headers=["*"],
- allow_credentials=False,
-)
+ @application.get("/healthz", tags=["meta"])
+ async def healthz() -> dict[str, str]:
+ """Shallow liveness probe — does not check dependent services."""
+ return {"status": "ok"}
-app.include_router(repos.router, prefix="/api/v1")
-app.include_router(query.router, prefix="/api/v1")
-app.include_router(inspector.router, prefix="/api/v1")
-app.include_router(internal.router, prefix="/internal")
+ return application
-@app.get("/healthz", tags=["meta"])
-async def healthz() -> dict[str, str]:
- """Shallow liveness probe — does not check dependent services."""
- return {"status": "ok"}
+app = create_app()
diff --git a/apps/api/src/dcode_api/routes/auth.py b/apps/api/src/dcode_api/routes/auth.py
new file mode 100644
index 0000000..0290857
--- /dev/null
+++ b/apps/api/src/dcode_api/routes/auth.py
@@ -0,0 +1,106 @@
+"""Session endpoints for the shared-account gate.
+
+These three routes are deliberately **not** behind the gate — a login endpoint
+that requires a login is a locked door with the key inside. Everything else
+under /api/v1 is protected in main.py.
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, Response, status
+from pydantic import BaseModel, Field
+
+from dcode_api.auth import (
+ SESSION_COOKIE_NAME,
+ SessionClaims,
+ current_session,
+ issue_session,
+ verify_password,
+)
+from dcode_api.settings import api_settings
+
+router = APIRouter(tags=["auth"], prefix="/auth")
+
+
+class LoginRequest(BaseModel):
+ """Credentials for the single shared account."""
+
+ username: str = Field(..., min_length=1, max_length=200)
+ password: str = Field(..., min_length=1, max_length=400)
+
+
+class SessionState(BaseModel):
+ """What the SPA needs to decide whether to show a gate.
+
+ `auth_required` is separate from `authenticated` so the frontend behaves
+ correctly in both deployments: with the gate off it must not redirect to a
+ login page that would accept anything.
+ """
+
+ auth_required: bool
+ authenticated: bool
+ username: str | None = None
+
+
+@router.post("/login", response_model=SessionState)
+async def login(body: LoginRequest, response: Response) -> SessionState:
+ """Exchange credentials for a signed session cookie."""
+ if not api_settings.auth_enabled:
+ # Nothing to sign in to. Report the state rather than minting a cookie
+ # that would imply a gate exists.
+ return SessionState(auth_required=False, authenticated=True, username=None)
+
+ username_ok = body.username.strip() == api_settings.auth_username.strip()
+ password_ok = verify_password(body.password, api_settings.auth_password_hash)
+ # Both checks always run. Returning early on an unknown username would let
+ # the response time distinguish "wrong user" from "wrong password".
+ if not (username_ok and password_ok):
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail={"code": "INVALID_CREDENTIALS", "message": "incorrect username or password"},
+ )
+
+ token = issue_session(
+ api_settings.auth_username.strip(),
+ ttl_seconds=api_settings.auth_session_ttl_seconds,
+ secret=api_settings.auth_session_secret,
+ )
+ response.set_cookie(
+ SESSION_COOKIE_NAME,
+ token,
+ max_age=api_settings.auth_session_ttl_seconds,
+ httponly=True,
+ secure=api_settings.auth_cookie_secure,
+ samesite="lax",
+ path="/",
+ )
+ return SessionState(
+ auth_required=True, authenticated=True, username=api_settings.auth_username.strip()
+ )
+
+
+@router.post("/logout", response_model=SessionState)
+async def logout(response: Response) -> SessionState:
+ """Clear the session cookie.
+
+ The token stays valid until it expires — there is no server-side session
+ store to revoke it in, which is the cost of D-6 and is recorded there.
+ """
+ response.delete_cookie(SESSION_COOKIE_NAME, path="/")
+ return SessionState(
+ auth_required=api_settings.auth_enabled, authenticated=not api_settings.auth_enabled
+ )
+
+
+@router.get("/me", response_model=SessionState)
+async def me(session: SessionClaims | None = Depends(current_session)) -> SessionState:
+ """Report session state. Always 200 — the SPA decides what to do with it.
+
+ A 401 here would be indistinguishable from a network failure at the point
+ where the frontend is deciding whether to render a gate at all.
+ """
+ if not api_settings.auth_enabled:
+ return SessionState(auth_required=False, authenticated=True, username=None)
+ return SessionState(
+ auth_required=True,
+ authenticated=session is not None,
+ username=session.sub if session else None,
+ )
diff --git a/apps/api/src/dcode_api/routes/query.py b/apps/api/src/dcode_api/routes/query.py
index bfd7ccc..fae0868 100644
--- a/apps/api/src/dcode_api/routes/query.py
+++ b/apps/api/src/dcode_api/routes/query.py
@@ -14,28 +14,35 @@
from dcode_shared.cache import query_cache_key
from dcode_shared.events import ErrorEvent, ThoughtEvent, sse_encode
from dcode_shared.schemas import QueryRequest, QueryTurn
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.responses import StreamingResponse
from redis.asyncio import Redis
from redis.exceptions import RedisError
+from dcode_api.auth import SessionClaims, current_session, quota_key
from dcode_api.deps import get_agent_client, get_redis
from dcode_api.settings import api_settings
router = APIRouter(tags=["query"])
+# A day, so the counter disappears on its own rather than accumulating a key
+# per session per day forever.
+_QUOTA_TTL_SECONDS = 24 * 60 * 60
+
@router.post("/query")
async def query(
body: QueryRequest,
agent: httpx.AsyncClient = Depends(get_agent_client),
redis: Redis = Depends(get_redis),
+ session: SessionClaims | None = Depends(current_session),
) -> StreamingResponse:
"""Stream SSE events from the agent service back to the client.
Successful streams are cached in Redis under the documented
`query:{repo_id}:{hash(query)}` key for a short replay window.
"""
+ await _enforce_daily_quota(redis, session)
return StreamingResponse(
_stream_query(agent, redis, body),
media_type="text/event-stream",
@@ -46,6 +53,41 @@ async def query(
)
+async def _enforce_daily_quota(redis: Redis, session: SessionClaims | None) -> None:
+ """Bound one session's spend for the day, or 429.
+
+ 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, because the cost is incurred there.
+
+ A Redis failure lets the request through. The counter is a spend guard, not
+ a security control, and refusing every query because a cache is down would
+ trade a bounded bill for a total outage.
+ """
+ if session is None or api_settings.auth_daily_query_limit <= 0:
+ return
+
+ key = quota_key(session)
+ try:
+ used = await redis.incr(key)
+ if used == 1:
+ await redis.expire(key, _QUOTA_TTL_SECONDS)
+ except RedisError:
+ return
+
+ if used > api_settings.auth_daily_query_limit:
+ raise HTTPException(
+ status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+ detail={
+ "code": "DAILY_QUERY_LIMIT",
+ "message": (
+ f"this session has used its {api_settings.auth_daily_query_limit} "
+ "queries for today"
+ ),
+ },
+ )
+
+
async def _stream_query(
agent: httpx.AsyncClient,
redis: Redis,
diff --git a/apps/api/src/dcode_api/routes/repos.py b/apps/api/src/dcode_api/routes/repos.py
index 2d35285..e9f3f50 100644
--- a/apps/api/src/dcode_api/routes/repos.py
+++ b/apps/api/src/dcode_api/routes/repos.py
@@ -12,8 +12,10 @@
from dcode_shared.schemas import (
RepoCreateRequest,
RepoCreateResponse,
+ RepoListResponse,
RepoStatus,
RepoStatusResponse,
+ RepoSummary,
StagesStatus,
StageState,
)
@@ -151,6 +153,35 @@ async def _find_reusable_repo(db: AsyncSession, url: str) -> Repo | None:
)
+# One page, capped. There is no pagination API and inventing one for a demo
+# with a handful of repositories would be scope the product does not have —
+# but returning "everything" from a table that only grows is how a list
+# endpoint becomes a slow query later, so the cap is explicit and reported.
+_REPO_LIST_LIMIT = 50
+
+
+@router.get("/repos", response_model=RepoListResponse)
+async def list_repos(db: AsyncSession = Depends(get_db)) -> RepoListResponse:
+ """List indexed repositories, most recently created first.
+
+ Reads Postgres only. Deliberately no Redis overlay: this answers "what can
+ I select?", and per-stage live progress belongs to the status route for the
+ one repository actually being watched.
+ """
+ result = await db.execute(
+ select(Repo).order_by(Repo.created_at.desc()).limit(_REPO_LIST_LIMIT + 1)
+ )
+ rows = list(result.scalars().all())
+ truncated = len(rows) > _REPO_LIST_LIMIT
+ return RepoListResponse(
+ repos=[
+ RepoSummary(repo_id=repo.id, url=repo.url, status=_coerce_status(repo.status))
+ for repo in rows[:_REPO_LIST_LIMIT]
+ ],
+ truncated=truncated,
+ )
+
+
@router.get(
"/repos/{repo_id}/status",
response_model=RepoStatusResponse,
@@ -242,6 +273,19 @@ async def _read_job_state(redis: Redis, repo_id: UUID) -> dict[str, object]:
return parsed if isinstance(parsed, dict) else {}
+def _coerce_status(db_status: str) -> RepoStatus:
+ """Row status as an enum, falling back to `failed` for an unknown value.
+
+ `failed` rather than `ready`: a status this code does not recognise is not
+ something to present as selectable. The list would otherwise offer a
+ repository that cannot answer anything.
+ """
+ try:
+ return RepoStatus(db_status)
+ except ValueError:
+ return RepoStatus.failed
+
+
def _status_from(db_status: str, live_state: dict[str, object]) -> RepoStatus:
raw = live_state.get("status", db_status)
try:
diff --git a/apps/api/src/dcode_api/settings.py b/apps/api/src/dcode_api/settings.py
index c13ff28..67683f9 100644
--- a/apps/api/src/dcode_api/settings.py
+++ b/apps/api/src/dcode_api/settings.py
@@ -16,6 +16,28 @@ class APISettings(SharedSettings):
query_history_max_chars: int = 2000
query_history_max_turn_chars: int = 4000
+ # --- Single shared-account gate (Deploy.md D-6) ---
+ # Off by default so local development, the test suite and every current
+ # compose invocation are unaffected. docker-compose.prod.yml hardcodes it
+ # on, and a config-hardening test pins that, so a deployment cannot forget.
+ # When on but unconfigured the app refuses to start: an auth gate that
+ # fails open is worse than none, because it looks like one.
+ auth_enabled: bool = False
+ auth_username: str = "dcode"
+ auth_password_hash: str = ""
+ auth_session_secret: str = ""
+ auth_session_ttl_seconds: int = 12 * 60 * 60
+ # Browsers treat http://localhost as a trustworthy origin, so a Secure
+ # cookie still works there; this exists for a plain-HTTP staging host.
+ auth_cookie_secure: bool = True
+ # The login wall stops anonymous callers. It does not stop a signed-in one
+ # looping a query against three metered APIs, which is what this bounds.
+ auth_daily_query_limit: int = 200
+
+ # /docs, /redoc and /openapi.json advertise the /internal/* surface.
+ # Useful locally, so on by default; prod compose turns it off.
+ docs_enabled: bool = True
+
@property
def cors_origins_list(self) -> list[str]:
"""Comma-separated CORS_ORIGINS env var → list."""
diff --git a/apps/api/tests/test_auth.py b/apps/api/tests/test_auth.py
new file mode 100644
index 0000000..473b434
--- /dev/null
+++ b/apps/api/tests/test_auth.py
@@ -0,0 +1,382 @@
+"""Tests for the single shared-account gate.
+
+The gate is off by default, so most of these turn it on explicitly. That
+asymmetry is the point: the default path must be unchanged, and the gated path
+must actually refuse.
+
+PBKDF2 runs at a low iteration count here. 600k iterations is right for a login
+endpoint and wrong for a test suite that hashes a dozen times.
+"""
+
+import time
+
+import httpx
+import pytest
+from dcode_api.auth import (
+ SESSION_COOKIE_NAME,
+ auth_configuration_error,
+ hash_password,
+ issue_session,
+ read_session,
+ verify_password,
+)
+from dcode_api.deps import get_agent_client, get_redis
+from dcode_api.main import app, create_app
+from dcode_api.settings import api_settings
+from fastapi.testclient import TestClient
+from redis.exceptions import RedisError
+
+_TEST_ITERATIONS = 10
+_SECRET = "s" * 48
+_PASSWORD = "correct horse battery staple"
+
+
+@pytest.fixture
+def gated(monkeypatch: pytest.MonkeyPatch) -> TestClient:
+ """A client with the gate on and a known credential.
+
+ The base URL is https on purpose. The cookie is issued `Secure`, so over
+ plain http a client correctly refuses to send it back and every
+ post-login assertion would fail for a reason that has nothing to do with
+ the gate. Weakening the cookie to make the test pass would delete the
+ property being tested — this is also a real operational note: a
+ plain-HTTP staging host needs `AUTH_COOKIE_SECURE=false` or logins will
+ appear to succeed and never stick.
+ """
+ monkeypatch.setattr(api_settings, "auth_enabled", True)
+ monkeypatch.setattr(api_settings, "auth_username", "reviewer")
+ monkeypatch.setattr(
+ api_settings,
+ "auth_password_hash",
+ hash_password(_PASSWORD, iterations=_TEST_ITERATIONS),
+ )
+ monkeypatch.setattr(api_settings, "auth_session_secret", _SECRET)
+ # Set rather than inherited: a test that asserts the cookie is Secure has
+ # to establish that, or it passes or fails on the developer's .env.
+ monkeypatch.setattr(api_settings, "auth_cookie_secure", True)
+ return TestClient(app, base_url="https://testserver")
+
+
+# --- password hashing ----------------------------------------------------
+
+
+def test_password_roundtrip() -> None:
+ encoded = hash_password(_PASSWORD, iterations=_TEST_ITERATIONS)
+ assert verify_password(_PASSWORD, encoded)
+ assert not verify_password("wrong", encoded)
+
+
+def test_password_hash_is_salted() -> None:
+ """Two hashes of the same password must differ, or the salt is not doing its job."""
+ a = hash_password(_PASSWORD, iterations=_TEST_ITERATIONS)
+ b = hash_password(_PASSWORD, iterations=_TEST_ITERATIONS)
+ assert a != b
+ assert verify_password(_PASSWORD, a) and verify_password(_PASSWORD, b)
+
+
+@pytest.mark.parametrize("encoded", ["", "not-a-hash", "bcrypt$1$x$y", "pbkdf2_sha256$abc$x$y"])
+def test_malformed_hash_denies_rather_than_raises(encoded: str) -> None:
+ """A misconfigured hash must deny access, not 500.
+
+ A crash is distinguishable from a wrong password by the caller, which turns
+ a configuration mistake into an oracle.
+ """
+ assert verify_password(_PASSWORD, encoded) is False
+
+
+# --- session tokens ------------------------------------------------------
+
+
+def test_session_roundtrip() -> None:
+ token = issue_session("reviewer", ttl_seconds=60, secret=_SECRET)
+ claims = read_session(token, secret=_SECRET)
+ assert claims is not None
+ assert claims.sub == "reviewer"
+ assert claims.jti
+
+
+def test_session_rejects_a_tampered_payload() -> None:
+ token = issue_session("reviewer", ttl_seconds=60, secret=_SECRET)
+ payload, _, signature = token.partition(".")
+ forged = f"{payload[:-4]}AAAA.{signature}"
+ assert read_session(forged, secret=_SECRET) is None
+
+
+def test_session_rejects_another_secret() -> None:
+ token = issue_session("reviewer", ttl_seconds=60, secret=_SECRET)
+ assert read_session(token, secret="d" * 48) is None
+
+
+def test_session_expires() -> None:
+ token = issue_session("reviewer", ttl_seconds=1, secret=_SECRET)
+ now = int(time.time())
+ assert read_session(token, secret=_SECRET, now=now) is not None
+ assert read_session(token, secret=_SECRET, now=now + 2) is None
+
+
+@pytest.mark.parametrize("token", ["", "nodot", ".", "a.", ".b"])
+def test_session_rejects_malformed_tokens(token: str) -> None:
+ assert read_session(token, secret=_SECRET) is None
+
+
+# --- fail closed ---------------------------------------------------------
+
+
+def test_configuration_error_is_none_when_disabled() -> None:
+ assert auth_configuration_error() is None
+
+
+def test_enabled_without_a_password_hash_is_a_startup_error(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(api_settings, "auth_enabled", True)
+ monkeypatch.setattr(api_settings, "auth_password_hash", "")
+ monkeypatch.setattr(api_settings, "auth_session_secret", _SECRET)
+ error = auth_configuration_error()
+ assert error is not None and "AUTH_PASSWORD_HASH" in error
+
+
+def test_a_corrupted_password_hash_is_a_startup_error(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Presence is not enough — the hash is checked for shape.
+
+ Found live: Docker Compose interpolates `$VAR` inside env-file values, so a
+ `$`-separated hash reached the container as 22 characters with three of its
+ four segments eaten. Nothing errored. The service reported healthy and
+ every login failed forever, with no way to tell that from a wrong password.
+
+ The format now uses "." so the character never appears, and this check is
+ the second line: any hash that will not parse stops the boot.
+ """
+ monkeypatch.setattr(api_settings, "auth_enabled", True)
+ monkeypatch.setattr(api_settings, "auth_session_secret", _SECRET)
+ for corrupted in ("pbkdf2_sha256", "pbkdf2_sha256.600000", "garbage", "a.b.c.d"):
+ monkeypatch.setattr(api_settings, "auth_password_hash", corrupted)
+ error = auth_configuration_error()
+ assert error is not None, f"{corrupted!r} was accepted as a password hash"
+ assert "AUTH_PASSWORD_HASH" in error
+
+
+def test_password_hash_contains_no_dollar_sign() -> None:
+ """The encoded hash must survive an env file unescaped.
+
+ `$` is what Docker Compose expands. A hash carrying one is a credential
+ that silently arrives wrong.
+ """
+ assert "$" not in hash_password(_PASSWORD, iterations=_TEST_ITERATIONS)
+
+
+def test_enabled_with_a_weak_session_secret_is_a_startup_error(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr(api_settings, "auth_enabled", True)
+ monkeypatch.setattr(api_settings, "auth_password_hash", hash_password("x", iterations=10))
+ monkeypatch.setattr(api_settings, "auth_session_secret", "short")
+ error = auth_configuration_error()
+ assert error is not None and "AUTH_SESSION_SECRET" in error
+
+
+# --- the gate ------------------------------------------------------------
+
+
+_PROTECTED = [
+ ("post", "/api/v1/repos", {"json": {"url": "https://github.com/psf/requests.git"}}),
+ (
+ "post",
+ "/api/v1/query",
+ {"json": {"repo_id": "00000000-0000-0000-0000-000000000000", "query": "hi"}},
+ ),
+ ("get", "/api/v1/repos/00000000-0000-0000-0000-000000000000/status", {}),
+ ("get", "/api/v1/repos/00000000-0000-0000-0000-000000000000/source?file_path=a.py", {}),
+ ("get", "/api/v1/repos/00000000-0000-0000-0000-000000000000/neighbors?symbol=x", {}),
+]
+
+
+@pytest.mark.parametrize(("method", "path", "kwargs"), _PROTECTED)
+def test_protected_routes_refuse_without_a_session(
+ gated: TestClient, method: str, path: str, kwargs: dict[str, object]
+) -> None:
+ response = getattr(gated, method)(path, **kwargs)
+ assert response.status_code == 401
+ assert response.json()["detail"]["code"] == "NOT_AUTHENTICATED"
+
+
+def test_open_routes_stay_open_with_the_gate_on(gated: TestClient) -> None:
+ """Liveness and the session endpoints cannot require a session."""
+ assert gated.get("/healthz").status_code == 200
+ assert gated.get("/api/v1/auth/me").status_code == 200
+ assert gated.post("/api/v1/auth/logout").status_code == 200
+
+
+def test_me_reports_unauthenticated_before_login(gated: TestClient) -> None:
+ body = gated.get("/api/v1/auth/me").json()
+ assert body == {"auth_required": True, "authenticated": False, "username": None}
+
+
+def test_me_reports_no_gate_when_disabled() -> None:
+ body = TestClient(app).get("/api/v1/auth/me").json()
+ assert body["auth_required"] is False
+ assert body["authenticated"] is True
+
+
+def test_login_rejects_a_wrong_password(gated: TestClient) -> None:
+ response = gated.post(
+ "/api/v1/auth/login", json={"username": "reviewer", "password": "nope"}
+ )
+ assert response.status_code == 401
+ assert response.json()["detail"]["code"] == "INVALID_CREDENTIALS"
+ assert SESSION_COOKIE_NAME not in response.cookies
+
+
+def test_login_rejects_a_wrong_username(gated: TestClient) -> None:
+ response = gated.post(
+ "/api/v1/auth/login", json={"username": "someone-else", "password": _PASSWORD}
+ )
+ assert response.status_code == 401
+
+
+def test_login_sets_a_hardened_cookie_and_opens_the_gate(gated: TestClient) -> None:
+ response = gated.post(
+ "/api/v1/auth/login", json={"username": "reviewer", "password": _PASSWORD}
+ )
+ assert response.status_code == 200
+ assert response.json() == {
+ "auth_required": True,
+ "authenticated": True,
+ "username": "reviewer",
+ }
+
+ cookie_header = response.headers["set-cookie"].lower()
+ assert "httponly" in cookie_header
+ assert "secure" in cookie_header
+ assert "samesite=lax" in cookie_header
+
+ # The client keeps the cookie, so a previously-401 route now resolves.
+ assert gated.get("/api/v1/auth/me").json()["authenticated"] is True
+ assert (
+ gated.get("/api/v1/repos/00000000-0000-0000-0000-000000000000/status").status_code
+ != 401
+ )
+
+
+def test_logout_clears_the_session(gated: TestClient) -> None:
+ gated.post("/api/v1/auth/login", json={"username": "reviewer", "password": _PASSWORD})
+ assert gated.get("/api/v1/auth/me").json()["authenticated"] is True
+
+ gated.post("/api/v1/auth/logout")
+ assert gated.get("/api/v1/auth/me").json()["authenticated"] is False
+
+
+def test_an_expired_cookie_is_refused(gated: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(api_settings, "auth_session_ttl_seconds", -1)
+ gated.post("/api/v1/auth/login", json={"username": "reviewer", "password": _PASSWORD})
+ assert gated.get("/api/v1/auth/me").json()["authenticated"] is False
+
+
+# --- per-session daily query budget --------------------------------------
+
+
+class _CountingRedis:
+ """Enough Redis for the quota path, and it fails where asked to."""
+
+ def __init__(self, *, fail: bool = False) -> None:
+ self.counters: dict[str, int] = {}
+ self.expires: list[tuple[str, int]] = []
+ self.fail = fail
+
+ async def incr(self, key: str) -> int:
+ if self.fail:
+ raise RedisError("down")
+ self.counters[key] = self.counters.get(key, 0) + 1
+ return self.counters[key]
+
+ async def expire(self, key: str, ttl: int) -> None:
+ self.expires.append((key, ttl))
+
+ async def get(self, key: str) -> str | None:
+ return None
+
+ async def setex(self, key: str, ttl: int, value: str) -> None:
+ return None
+
+
+def _sign_in(client: TestClient) -> None:
+ response = client.post(
+ "/api/v1/auth/login", json={"username": "reviewer", "password": _PASSWORD}
+ )
+ assert response.status_code == 200
+
+
+def _query(client: TestClient) -> int:
+ return client.post(
+ "/api/v1/query",
+ json={"repo_id": "00000000-0000-0000-0000-000000000000", "query": "hi"},
+ ).status_code
+
+
+def test_daily_query_budget_is_enforced_per_session(
+ gated: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The login wall stops anonymous callers, not a signed-in loop.
+
+ Counted before the agent is reached, because that is where the metered
+ APIs are.
+ """
+ monkeypatch.setattr(api_settings, "auth_daily_query_limit", 2)
+ redis = _CountingRedis()
+ app.dependency_overrides[get_redis] = lambda: redis
+ app.dependency_overrides[get_agent_client] = lambda: _NeverCalledAgent()
+ try:
+ _sign_in(gated)
+ assert _query(gated) != 429
+ assert _query(gated) != 429
+ assert _query(gated) == 429
+ finally:
+ app.dependency_overrides.clear()
+
+ assert len(redis.counters) == 1, "the budget must be one counter per session per day"
+ assert redis.expires and redis.expires[0][1] == 24 * 60 * 60
+
+
+def test_quota_failure_lets_the_request_through(
+ gated: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """A spend guard is not a security control.
+
+ Refusing every query because Redis is down trades a bounded bill for a
+ total outage, which is the worse failure.
+ """
+ monkeypatch.setattr(api_settings, "auth_daily_query_limit", 1)
+ app.dependency_overrides[get_redis] = lambda: _CountingRedis(fail=True)
+ app.dependency_overrides[get_agent_client] = lambda: _NeverCalledAgent()
+ try:
+ _sign_in(gated)
+ assert _query(gated) != 429
+ assert _query(gated) != 429
+ finally:
+ app.dependency_overrides.clear()
+
+
+class _NeverCalledAgent:
+ """The quota check runs before the agent, so this only has to exist."""
+
+ def stream(self, method: str, url: str, json: dict[str, object]) -> object:
+ raise httpx.ConnectError("agent not part of this test")
+
+
+# --- docs surface --------------------------------------------------------
+
+
+def test_docs_are_served_by_default() -> None:
+ assert app.openapi_url == "/openapi.json"
+
+
+def test_docs_can_be_switched_off(monkeypatch: pytest.MonkeyPatch) -> None:
+ """F-05: /docs and /openapi.json enumerate the /internal/* surface."""
+ monkeypatch.setattr(api_settings, "docs_enabled", False)
+ closed = create_app()
+ assert closed.openapi_url is None
+ assert closed.docs_url is None
+ assert closed.redoc_url is None
+ assert TestClient(closed).get("/openapi.json").status_code == 404
diff --git a/apps/api/tests/test_repos_route.py b/apps/api/tests/test_repos_route.py
index be55c40..0fb1ec7 100644
--- a/apps/api/tests/test_repos_route.py
+++ b/apps/api/tests/test_repos_route.py
@@ -1,7 +1,8 @@
"""POST /repos contract tests — URL validation and idempotency."""
import uuid
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterator
+from contextlib import contextmanager
from datetime import datetime, timedelta
from typing import Any
from uuid import UUID
@@ -213,3 +214,112 @@ def test_rejects_a_non_git_url() -> None:
assert response.status_code == 400
assert response.json()["detail"]["code"] == "INVALID_REPO_URL"
+
+
+class _FakeScalars:
+ def __init__(self, rows: list[object]) -> None:
+ self._rows = rows
+
+ def all(self) -> list[object]:
+ return self._rows
+
+
+class _FakeResult:
+ def __init__(self, rows: list[object]) -> None:
+ self._rows = rows
+
+ def scalars(self) -> _FakeScalars:
+ return _FakeScalars(self._rows)
+
+
+class _ListOnlyDb:
+ """Answers the one SELECT the list route makes, with a fixed page.
+
+ The route applies `.limit(_REPO_LIST_LIMIT + 1)` itself, so the fake honours
+ it rather than handing back everything — otherwise the truncation test would
+ be asserting against a query that never ran.
+ """
+
+ def __init__(self, rows: list[object]) -> None:
+ from dcode_api.routes.repos import _REPO_LIST_LIMIT
+
+ self._rows = rows[: _REPO_LIST_LIMIT + 1]
+
+ async def execute(self, _statement: object) -> _FakeResult:
+ return _FakeResult(self._rows)
+
+
+def _repo_row(repo_id: str, url: str, status: str) -> object:
+ from types import SimpleNamespace
+ from uuid import UUID
+
+ return SimpleNamespace(id=UUID(repo_id), url=url, status=status)
+
+
+@contextmanager
+def _repo_list_client(rows: list[object]) -> Iterator[TestClient]:
+ from dcode_api.deps import get_db
+ from dcode_api.main import app
+
+ app.dependency_overrides[get_db] = lambda: _ListOnlyDb(rows)
+ try:
+ yield TestClient(app)
+ finally:
+ app.dependency_overrides.clear()
+
+
+# --- GET /api/v1/repos (F-09) --------------------------------------------
+
+
+def test_repo_list_returns_newest_first_and_reports_no_truncation() -> None:
+ """The endpoint that stops a fresh browser opening an empty workbench."""
+ from dcode_shared.schemas import RepoListResponse
+
+ rows = [
+ _repo_row("11111111-1111-1111-1111-111111111111", "https://github.com/a/one.git", "ready"),
+ _repo_row("22222222-2222-2222-2222-222222222222", "https://github.com/b/two.git", "queued"),
+ ]
+ with _repo_list_client(rows) as client:
+ body = RepoListResponse.model_validate(client.get("/api/v1/repos").json())
+
+ assert [str(repo.repo_id) for repo in body.repos] == [
+ "11111111-1111-1111-1111-111111111111",
+ "22222222-2222-2222-2222-222222222222",
+ ]
+ assert body.truncated is False
+
+
+def test_repo_list_caps_the_page_and_says_so() -> None:
+ """Truncation is reported, not inferred from a full page.
+
+ A caller cannot tell a page that happens to be full from one that was cut,
+ and quietly showing a subset is the kind of unstated claim this project
+ avoids everywhere else.
+ """
+ from dcode_api.routes.repos import _REPO_LIST_LIMIT
+ from dcode_shared.schemas import RepoListResponse
+
+ rows = [
+ _repo_row(f"{index:08d}-0000-0000-0000-000000000000", f"https://x/{index}.git", "ready")
+ for index in range(_REPO_LIST_LIMIT + 5)
+ ]
+ with _repo_list_client(rows) as client:
+ body = RepoListResponse.model_validate(client.get("/api/v1/repos").json())
+
+ assert len(body.repos) == _REPO_LIST_LIMIT
+ assert body.truncated is True
+
+
+def test_repo_list_does_not_offer_a_row_whose_status_is_unreadable() -> None:
+ """An unrecognised status becomes `failed`, not `ready`.
+
+ Offering a repository as selectable when this code cannot tell what state
+ it is in would put a reader in a workbench that answers nothing.
+ """
+ from dcode_shared.schemas import RepoListResponse
+
+ rows = [_repo_row("33333333-3333-3333-3333-333333333333", "https://x/y.git", "who-knows")]
+ with _repo_list_client(rows) as client:
+ body = RepoListResponse.model_validate(client.get("/api/v1/repos").json())
+
+ assert body.repos[0].status == "failed"
diff --git a/apps/frontend/.dockerignore b/apps/frontend/.dockerignore
new file mode 100644
index 0000000..c6c617a
--- /dev/null
+++ b/apps/frontend/.dockerignore
@@ -0,0 +1,15 @@
+# Build-context exclusions for the frontend image.
+#
+# `npm ci` reinstalls dependencies inside the image, so shipping the local
+# tree is pure transfer cost — it measured ~227 MB, and it is also the wrong
+# platform's binaries.
+node_modules/
+dist/
+.vite/
+coverage/
+*.tsbuildinfo
+
+.env
+.env.*
+
+.DS_Store
diff --git a/apps/frontend/nginx.conf b/apps/frontend/nginx.conf
deleted file mode 100644
index 4f6fd55..0000000
--- a/apps/frontend/nginx.conf
+++ /dev/null
@@ -1,25 +0,0 @@
-server {
- listen 80;
- server_name _;
-
- root /usr/share/nginx/html;
- index index.html;
-
- location = /healthz {
- add_header Content-Type text/plain;
- return 200 'ok';
- }
-
- location /api/ {
- proxy_pass http://api:8000;
- proxy_http_version 1.1;
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- }
-
- location / {
- try_files $uri $uri/ /index.html;
- }
-}
diff --git a/apps/frontend/nginx.conf.template b/apps/frontend/nginx.conf.template
new file mode 100644
index 0000000..6d33b16
--- /dev/null
+++ b/apps/frontend/nginx.conf.template
@@ -0,0 +1,82 @@
+# Dcode frontend: static bundle + /api proxy.
+#
+# A template, not a finished config. The nginx image runs envsubst over
+# /etc/nginx/templates/*.template at boot, restricted by NGINX_ENVSUBST_FILTER
+# to the three names below — without that filter it would also eat nginx's own
+# $host, $remote_addr and $request_uri.
+#
+# The defaults in the Dockerfile reproduce the previous behaviour exactly
+# (listen 80, proxy to api:8000, Docker's embedded resolver), so the developer
+# stack is unchanged. Railway overrides them.
+
+server {
+ listen ${PORT};
+ listen [::]:${PORT};
+ server_name _;
+
+ root /usr/share/nginx/html;
+ index index.html;
+
+ # Compression was off: the base image ships `#gzip on;` commented out and
+ # this file never enabled it, so the bundle went out uncompressed. The main
+ # chunk is ~750 kB raw against ~225 kB gzipped.
+ gzip on;
+ gzip_vary on;
+ gzip_min_length 1024;
+ gzip_proxied any;
+ gzip_types
+ text/plain text/css text/javascript
+ application/javascript application/json application/xml
+ image/svg+xml font/woff font/woff2;
+
+ location = /healthz {
+ add_header Content-Type text/plain;
+ return 200 'ok';
+ }
+
+ location /api/ {
+ # Resolved per request, not once at startup. Railway's private DNS
+ # hands out a new address on every redeploy, and nginx caches a literal
+ # proxy_pass target for the life of the process — the API would keep
+ # working until the first redeploy of it and then fail with no change
+ # on this side. A variable target forces re-resolution.
+ resolver ${DNS_RESOLVER} valid=10s ipv6=on;
+ set $api_upstream ${API_UPSTREAM};
+ proxy_pass $api_upstream$request_uri;
+
+ proxy_http_version 1.1;
+ proxy_set_header Host $host;
+ proxy_set_header X-Real-IP $remote_addr;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
+
+ # SSE. The gateway already sends X-Accel-Buffering: no, which stops
+ # nginx buffering the body, but that says nothing about how long nginx
+ # will wait between chunks — the default is 60s, and a slow tool or
+ # synthesis step can exceed it. The agent also emits heartbeat comment
+ # frames; this is the other half of keeping a long answer alive.
+ proxy_buffering off;
+ proxy_cache off;
+ proxy_read_timeout 600s;
+ proxy_send_timeout 600s;
+ }
+
+ # Vite emits content-hashed filenames, so these are safe to keep for a
+ # year: a changed file is a changed URL.
+ location /assets/ {
+ # One header, not two. `expires 1y` emits its own Cache-Control, so
+ # pairing it with add_header sent the response out with two of them.
+ add_header Cache-Control "public, max-age=31536000, immutable" always;
+ try_files $uri =404;
+ }
+
+ # index.html must never be cached, or a browser keeps loading an old
+ # document that points at asset hashes the deploy no longer serves.
+ location = /index.html {
+ add_header Cache-Control "no-store, must-revalidate";
+ }
+
+ location / {
+ try_files $uri $uri/ /index.html;
+ }
+}
diff --git a/apps/frontend/src/App.tsx b/apps/frontend/src/App.tsx
index dfa177b..200356e 100644
--- a/apps/frontend/src/App.tsx
+++ b/apps/frontend/src/App.tsx
@@ -1,6 +1,8 @@
import { Route, Routes } from 'react-router-dom';
+import { RequireSession } from '@/components/RequireSession';
import LandingPage from '@/pages/LandingPage';
+import LoginPage from '@/pages/LoginPage';
import MethodologyPage from '@/pages/MethodologyPage';
import PrimitivesGallery from '@/pages/PrimitivesGallery';
import WorkbenchPage from '@/pages/WorkbenchPage';
@@ -10,8 +12,20 @@ export default function App() {
{/* Marketing landing (Phase 3). CTAs route into the workbench. */}
} />
- {/* The product (Phase 2). */}
- } />
+ {/* The gate between the landing page and the product (Deploy.md D-2).
+ Public by necessity, and a no-op wherever the gateway reports
+ `auth_required: false`. */}
+ } />
+ {/* The product (Phase 2). Guarded in the UI for the redirect only — the
+ gateway is what actually refuses, on every protected route. */}
+
+
+
+ }
+ />
{/* Evaluation / H1 story, moved out of the product (Phase 3 slice 3b). */}
} />
{/* Design-system gallery (Phase 1). */}
diff --git a/apps/frontend/src/api/client.ts b/apps/frontend/src/api/client.ts
index 9c06f2f..4068827 100644
--- a/apps/frontend/src/api/client.ts
+++ b/apps/frontend/src/api/client.ts
@@ -7,12 +7,15 @@
import type {
ErrorPayload,
FinalAnswerPayload,
+ LoginRequest,
PartialAnswerPayload,
QueryRequest,
QueryStreamEvent,
RepoCreateRequest,
RepoCreateResponse,
+ RepoListResponse,
RepoStatusResponse,
+ SessionState,
SourceResponse,
SymbolNeighbors,
SSEEventName,
@@ -25,20 +28,93 @@ import type {
const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? '';
+/**
+ * Thrown when the gateway refuses for want of a session. Callers distinguish
+ * it from a transport failure so an expired cookie sends you to the login page
+ * rather than rendering as "the backend is down".
+ */
+export class UnauthenticatedError extends Error {
+ constructor(message = 'not authenticated') {
+ super(message);
+ this.name = 'UnauthenticatedError';
+ }
+}
+
+/**
+ * A gated deployment answers 401 once the session cookie expires. Every call
+ * below routes through this so an expiry surfaces as "sign in again" instead
+ * of a generic failure string in the middle of the workbench.
+ */
+function assertAuthenticated(response: Response, path: string): void {
+ if (response.status === 401) {
+ throw new UnauthenticatedError(`${path} requires a session`);
+ }
+}
+
+/** Read session state. Always 200 — the caller decides whether to gate. */
+export async function getSession(): Promise {
+ const response = await fetch(`${BASE_URL}/api/v1/auth/me`);
+ if (!response.ok) {
+ throw new Error(`GET /api/v1/auth/me failed: ${response.status}`);
+ }
+ return (await response.json()) as SessionState;
+}
+
+export async function login(body: LoginRequest): Promise {
+ const response = await fetch(`${BASE_URL}/api/v1/auth/login`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+ if (response.status === 401) {
+ throw new UnauthenticatedError('Incorrect username or password.');
+ }
+ if (!response.ok) {
+ throw new Error(`POST /api/v1/auth/login failed: ${response.status}`);
+ }
+ return (await response.json()) as SessionState;
+}
+
+export async function logout(): Promise {
+ const response = await fetch(`${BASE_URL}/api/v1/auth/logout`, { method: 'POST' });
+ if (!response.ok) {
+ throw new Error(`POST /api/v1/auth/logout failed: ${response.status}`);
+ }
+ return (await response.json()) as SessionState;
+}
+
export async function submitRepo(body: RepoCreateRequest): Promise {
const response = await fetch(`${BASE_URL}/api/v1/repos`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
+ assertAuthenticated(response, 'POST /api/v1/repos');
if (!response.ok) {
throw new Error(`POST /api/v1/repos failed: ${response.status}`);
}
return (await response.json()) as RepoCreateResponse;
}
+/**
+ * Everything indexed on the server, newest first.
+ *
+ * The switcher's localStorage recents only know what this browser did, so a
+ * reader on a new device used to open an empty workbench and have to index a
+ * repository before they could ask anything.
+ */
+export async function listRepos(): Promise {
+ const response = await fetch(`${BASE_URL}/api/v1/repos`);
+ assertAuthenticated(response, 'GET /api/v1/repos');
+ if (!response.ok) {
+ throw new Error(`GET /api/v1/repos failed: ${response.status}`);
+ }
+ return (await response.json()) as RepoListResponse;
+}
+
export async function getRepoStatus(repoId: UUID): Promise {
const response = await fetch(`${BASE_URL}/api/v1/repos/${repoId}/status`);
+ assertAuthenticated(response, 'GET /api/v1/repos/:id/status');
if (!response.ok) {
throw new Error(`GET /api/v1/repos/${repoId}/status failed: ${response.status}`);
}
@@ -55,6 +131,7 @@ export async function getSource(
if (params.line != null) qs.set('line', String(params.line));
if (params.symbol) qs.set('symbol', params.symbol);
const response = await fetch(`${BASE_URL}/api/v1/repos/${repoId}/source?${qs.toString()}`);
+ assertAuthenticated(response, 'GET /api/v1/repos/:id/source');
if (!response.ok) {
throw new Error(`GET /api/v1/repos/${repoId}/source failed: ${response.status}`);
}
@@ -65,6 +142,7 @@ export async function getSource(
export async function getNeighbors(repoId: UUID, symbol: string): Promise {
const qs = new URLSearchParams({ symbol });
const response = await fetch(`${BASE_URL}/api/v1/repos/${repoId}/neighbors?${qs.toString()}`);
+ assertAuthenticated(response, 'GET /api/v1/repos/:id/neighbors');
if (!response.ok) {
throw new Error(`GET /api/v1/repos/${repoId}/neighbors failed: ${response.status}`);
}
@@ -88,6 +166,7 @@ export async function streamQuery(
signal,
});
+ assertAuthenticated(response, 'POST /api/v1/query');
if (!response.ok) {
throw new Error(
`POST /api/v1/query failed: ${response.status}${await response.text().then((text) => (text ? ` ${text}` : ''))}`
diff --git a/apps/frontend/src/api/types.ts b/apps/frontend/src/api/types.ts
index 25af0d9..f2da0e9 100644
--- a/apps/frontend/src/api/types.ts
+++ b/apps/frontend/src/api/types.ts
@@ -150,3 +150,36 @@ export interface SymbolNeighbors {
calls: Location[];
references: Location[];
}
+
+export interface RepoSummary {
+ repo_id: UUID;
+ url: string;
+ status: RepoStatus;
+}
+
+/**
+ * `truncated` is explicit rather than inferred from a full page. Silently
+ * showing a subset of what exists is the sort of quiet claim this UI avoids.
+ */
+export interface RepoListResponse {
+ repos: RepoSummary[];
+ truncated: boolean;
+}
+
+// --- Session (single shared account; see Deploy.md D-6) -------------------
+
+export interface LoginRequest {
+ username: string;
+ password: string;
+}
+
+/**
+ * `auth_required` is separate from `authenticated` so the SPA behaves in both
+ * deployments. With the gate off the API reports `auth_required: false`, and
+ * the workbench must not redirect to a login page that would accept anything.
+ */
+export interface SessionState {
+ auth_required: boolean;
+ authenticated: boolean;
+ username: string | null;
+}
diff --git a/apps/frontend/src/components/RequireSession.tsx b/apps/frontend/src/components/RequireSession.tsx
new file mode 100644
index 0000000..e7ffceb
--- /dev/null
+++ b/apps/frontend/src/components/RequireSession.tsx
@@ -0,0 +1,58 @@
+import { useEffect, useState } from 'react';
+import { Navigate } from 'react-router-dom';
+
+import { getSession } from '@/api/client';
+
+type Gate = 'checking' | 'allowed' | 'denied';
+
+/**
+ * Route guard for the workbench.
+ *
+ * Three states, not two. While the session check is in flight the answer is
+ * genuinely unknown, and rendering either the workbench or a redirect would be
+ * asserting something not yet known — the same reasoning as
+ * Honesty_Constraints §1, where a turn's state is derived from what has
+ * arrived rather than from a guess.
+ *
+ * It fails **open** on a network error, which is deliberate and worth being
+ * explicit about: this is a convenience redirect, not the security boundary.
+ * The gateway refuses every protected route with 401 regardless of what the
+ * SPA renders, so a guard that locked the UI out whenever `/auth/me` blipped
+ * would only break the product without protecting anything.
+ */
+export function RequireSession({ children }: { children: React.ReactNode }) {
+ const [gate, setGate] = useState('checking');
+
+ useEffect(() => {
+ let active = true;
+ getSession()
+ .then((session) => {
+ if (!active) return;
+ setGate(session.auth_required && !session.authenticated ? 'denied' : 'allowed');
+ })
+ .catch(() => {
+ if (active) setGate('allowed');
+ });
+ return () => {
+ active = false;
+ };
+ }, []);
+
+ if (gate === 'checking') {
+ return (
+
+ checking session…
+
+ );
+ }
+
+ if (gate === 'denied') {
+ return ;
+ }
+
+ return <>{children}>;
+}
diff --git a/apps/frontend/src/components/workbench/RepoSwitcher.tsx b/apps/frontend/src/components/workbench/RepoSwitcher.tsx
index 9df8f7e..b7cdcd9 100644
--- a/apps/frontend/src/components/workbench/RepoSwitcher.tsx
+++ b/apps/frontend/src/components/workbench/RepoSwitcher.tsx
@@ -1,7 +1,7 @@
import { useMutation, useQuery } from '@tanstack/react-query';
import { useEffect, useMemo, useRef, useState } from 'react';
-import { getRepoStatus, submitRepo } from '@/api/client';
+import { getRepoStatus, listRepos, submitRepo } from '@/api/client';
import type { RepoStatusResponse } from '@/api/types';
import type { PillStatus } from '@/components/ui';
import { cx } from '@/lib/cx';
@@ -58,10 +58,16 @@ export interface RepoSwitcherProps {
}
/**
- * Topbar repo switcher (replaces the Index page). Lists the localStorage
- * recents, polls the active repo's live status (GET /repos/{id}/status) so
- * `indexing…` progress shows in place, and indexes a new repo (POST /repos)
- * from the dropdown. Selecting a repo scopes the whole workbench to it.
+ * Topbar repo switcher (replaces the Index page). Lists what is indexed,
+ * polls the active repo's live status (GET /repos/{id}/status) so `indexing…`
+ * progress shows in place, and indexes a new repo (POST /repos) from the
+ * dropdown. Selecting a repo scopes the whole workbench to it.
+ *
+ * The list is localStorage recents *plus* whatever the server reports. Neither
+ * alone is right: recents are per-browser, so a reader on a new device saw an
+ * empty product; the server list has no idea which repository this person was
+ * last working in, and does not know the URL as they typed it. Recents lead,
+ * server rows fill in behind them.
*/
export function RepoSwitcher({ activeRepoId, onSelect }: RepoSwitcherProps) {
const [open, setOpen] = useState(false);
@@ -139,9 +145,33 @@ export function RepoSwitcher({ activeRepoId, onSelect }: RepoSwitcherProps) {
);
}, [liveRepoId, liveRepoStatus, liveRepoUrl]);
+ // Server-side inventory. Cheap, and it does not poll: repositories appear
+ // when someone indexes one, which is a page-scale event, not a per-second
+ // one. The active repo's *status* is polled separately below.
+ const repoListQuery = useQuery({
+ queryKey: ['repo-list'],
+ queryFn: listRepos,
+ staleTime: 30_000,
+ });
+
+ // Recents first — they carry the URL as typed and the order this reader
+ // last worked in. Server rows are appended, deduped by id.
+ const knownRepos = useMemo(() => {
+ const seen = new Set(recents.map((item) => item.repoId));
+ const fromServer = (repoListQuery.data?.repos ?? [])
+ .filter((repo) => !seen.has(repo.repo_id))
+ .map((repo) => ({
+ repoId: repo.repo_id,
+ url: repo.url,
+ status: repo.status,
+ savedAt: '',
+ }));
+ return [...recents, ...fromServer];
+ }, [recents, repoListQuery.data]);
+
const activeRepo = useMemo(
- () => recents.find((item) => item.repoId === activeRepoId) ?? null,
- [recents, activeRepoId]
+ () => knownRepos.find((item) => item.repoId === activeRepoId) ?? null,
+ [knownRepos, activeRepoId]
);
// We couldn't reach the gateway, so we don't know this repo's state. The
@@ -210,10 +240,12 @@ export function RepoSwitcher({ activeRepoId, onSelect }: RepoSwitcherProps) {
Indexed repositories
- {recents.length === 0 ? (
-
None yet — index one below.
+ {knownRepos.length === 0 ? (
+
+ {repoListQuery.isPending ? 'Loading…' : 'None yet — index one below.'}
+
) : (
- recents.map((repo) => {
+ knownRepos.map((repo) => {
const isActive = repo.repoId === activeRepoId;
const live = isActive ? liveStatus : undefined;
const unknown = isActive && unreachable;
diff --git a/apps/frontend/src/pages/LoginPage.tsx b/apps/frontend/src/pages/LoginPage.tsx
new file mode 100644
index 0000000..ab6fbaa
--- /dev/null
+++ b/apps/frontend/src/pages/LoginPage.tsx
@@ -0,0 +1,101 @@
+import { useState } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+
+import { UnauthenticatedError, login } from '@/api/client';
+import { Button } from '@/components/ui';
+
+/**
+ * The gate between the landing page and the workbench (Deploy.md D-2).
+ *
+ * One shared account, so there is no "sign up", no "forgot password" and no
+ * account menu — offering any of them would imply an identity system that does
+ * not exist (D-6).
+ */
+export default function LoginPage() {
+ const navigate = useNavigate();
+ const [username, setUsername] = useState('');
+ const [password, setPassword] = useState('');
+ const [error, setError] = useState(null);
+ const [submitting, setSubmitting] = useState(false);
+
+ async function onSubmit(event: React.FormEvent) {
+ event.preventDefault();
+ setSubmitting(true);
+ setError(null);
+ try {
+ await login({ username, password });
+ navigate('/workbench', { replace: true });
+ } catch (caught) {
+ // A wrong password and an unreachable gateway are different problems and
+ // are worth different sentences: one is the reader's to fix.
+ setError(
+ caught instanceof UnauthenticatedError
+ ? 'Incorrect username or password.'
+ : 'Could not reach the server. Check that the backend is running.'
+ );
+ } finally {
+ setSubmitting(false);
+ }
+ }
+
+ return (
+
+
+
+ ← Dcode
+
+
+
+ Sign in to the workbench
+
+
+ The evaluation write-up is{' '}
+
+ open to everyone
+
+ . The workbench indexes repositories and calls metered models, so it is not.
+
+
+
+
+
+ );
+}
diff --git a/apps/frontend/tests/App.test.tsx b/apps/frontend/tests/App.test.tsx
index 11d1af7..8a0e20b 100644
--- a/apps/frontend/tests/App.test.tsx
+++ b/apps/frontend/tests/App.test.tsx
@@ -1,9 +1,20 @@
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { render, screen } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
import App from '@/App';
+import { getSession } from '@/api/client';
+
+// The workbench sits behind a session check, so every render of it now waits
+// on one request. Stubbed to the ungated answer — the gate's own behaviour is
+// covered in RequireSession.test.tsx rather than incidentally here.
+vi.mock('@/api/client', async (importOriginal) => ({
+ ...(await importOriginal()),
+ getSession: vi.fn(),
+}));
+
+const mockedGetSession = vi.mocked(getSession);
function renderAppAt(path: string) {
const queryClient = new QueryClient();
@@ -17,14 +28,27 @@ function renderAppAt(path: string) {
}
describe('App IA', () => {
+ beforeEach(() => {
+ mockedGetSession.mockResolvedValue({
+ auth_required: false,
+ authenticated: true,
+ username: null,
+ });
+ });
+
it('renders the marketing landing at /', () => {
renderAppAt('/');
expect(screen.getByText(/Understand any codebase/i)).toBeInTheDocument();
});
- it('renders the workbench at /workbench', () => {
+ it('renders the workbench at /workbench', async () => {
renderAppAt('/workbench');
- expect(screen.getByText(/ask this codebase anything/i)).toBeInTheDocument();
+ expect(await screen.findByText(/ask this codebase anything/i)).toBeInTheDocument();
+ });
+
+ it('renders the login page at /login', () => {
+ renderAppAt('/login');
+ expect(screen.getByRole('heading', { name: /sign in to the workbench/i })).toBeInTheDocument();
});
it('renders the methodology page at /methodology', () => {
diff --git a/apps/frontend/tests/LoginPage.test.tsx b/apps/frontend/tests/LoginPage.test.tsx
new file mode 100644
index 0000000..f38a0ba
--- /dev/null
+++ b/apps/frontend/tests/LoginPage.test.tsx
@@ -0,0 +1,78 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { UnauthenticatedError, login } from '@/api/client';
+import LoginPage from '@/pages/LoginPage';
+
+vi.mock('@/api/client', async (importOriginal) => ({
+ ...(await importOriginal()),
+ login: vi.fn(),
+}));
+
+const mockedLogin = vi.mocked(login);
+
+function renderLogin() {
+ return render(
+
+
+ } />
+ workbench body
} />
+
+
+ );
+}
+
+// fireEvent rather than user-event: the latter is not a dependency of this
+// workspace, and adding one for a single file is the larger change.
+function submit(username = 'reviewer', password = 'pw') {
+ fireEvent.change(screen.getByLabelText(/username/i), { target: { value: username } });
+ fireEvent.change(screen.getByLabelText(/password/i), { target: { value: password } });
+ fireEvent.click(screen.getByRole('button', { name: /sign in/i }));
+}
+
+describe('LoginPage', () => {
+ beforeEach(() => {
+ mockedLogin.mockReset();
+ });
+
+ it('sends the reader to the workbench on success', async () => {
+ mockedLogin.mockResolvedValue({
+ auth_required: true,
+ authenticated: true,
+ username: 'reviewer',
+ });
+ renderLogin();
+ submit();
+
+ expect(await screen.findByText('workbench body')).toBeInTheDocument();
+ });
+
+ it('says the credentials are wrong when they are', async () => {
+ mockedLogin.mockRejectedValue(new UnauthenticatedError());
+ renderLogin();
+ submit();
+
+ expect(await screen.findByRole('alert')).toHaveTextContent(/incorrect username or password/i);
+ expect(screen.queryByText('workbench body')).not.toBeInTheDocument();
+ });
+
+ it('distinguishes an unreachable server from a wrong password', async () => {
+ // These are different problems and only one of them is the reader's to
+ // fix. Collapsing them into "sign-in failed" sends someone hunting for a
+ // typo while the backend is down.
+ mockedLogin.mockRejectedValue(new Error('Failed to fetch'));
+ renderLogin();
+ submit();
+
+ expect(await screen.findByRole('alert')).toHaveTextContent(/could not reach the server/i);
+ });
+
+ it('keeps the public evaluation write-up linked from the gate', () => {
+ renderLogin();
+ expect(screen.getByRole('link', { name: /open to everyone/i })).toHaveAttribute(
+ 'href',
+ '/methodology'
+ );
+ });
+});
diff --git a/apps/frontend/tests/RepoSwitcher.test.tsx b/apps/frontend/tests/RepoSwitcher.test.tsx
index 643c1e7..53178fe 100644
--- a/apps/frontend/tests/RepoSwitcher.test.tsx
+++ b/apps/frontend/tests/RepoSwitcher.test.tsx
@@ -7,7 +7,11 @@ import type { RepoStatusResponse } from '@/api/types';
import { RepoSwitcher, repoStatusLabel } from '@/components/workbench/RepoSwitcher';
import { saveRecentRepo } from '@/lib/recentRepos';
-vi.mock('@/api/client', () => ({ getRepoStatus: vi.fn(), submitRepo: vi.fn() }));
+vi.mock('@/api/client', () => ({
+ getRepoStatus: vi.fn(),
+ submitRepo: vi.fn(),
+ listRepos: vi.fn(),
+}));
function renderSwitcher(activeRepoId: string | null = null, onSelect: (id: string) => void = () => {}) {
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
@@ -22,15 +26,21 @@ describe('RepoSwitcher', () => {
beforeEach(() => {
window.localStorage.clear();
vi.clearAllMocks();
+ // Default to "the server knows of nothing", so each test states the
+ // inventory it means to exercise rather than inheriting one.
+ vi.mocked(client.listRepos).mockResolvedValue({ repos: [], truncated: false });
});
- it('shows the empty active state and reveals the index-new-repo form', () => {
+ it('shows the empty active state and reveals the index-new-repo form', async () => {
renderSwitcher();
expect(screen.getByText('select a repo')).toBeInTheDocument();
fireEvent.click(screen.getByText('select a repo'));
expect(screen.getByText('Indexed repositories')).toBeInTheDocument();
- expect(screen.getByText(/None yet/i)).toBeInTheDocument();
+ // "None yet" is a claim about the server, so it waits for the server to
+ // answer. Asserting it before the list request settles would be asserting
+ // something not yet known.
+ expect(await screen.findByText(/None yet/i)).toBeInTheDocument();
fireEvent.click(screen.getByText('+ Index a new repository'));
expect(screen.getByPlaceholderText(/github\.com/i)).toBeInTheDocument();
@@ -229,3 +239,75 @@ describe('repoStatusLabel', () => {
expect(repoStatusLabel('failed')).toBe('failed');
});
});
+
+describe('RepoSwitcher lists what the server knows', () => {
+ beforeEach(() => {
+ window.localStorage.clear();
+ vi.clearAllMocks();
+ vi.mocked(client.getRepoStatus).mockResolvedValue({
+ repo_id: 'srv-1',
+ url: 'https://github.com/psf/requests.git',
+ status: 'ready',
+ progress: 100,
+ stages: { cloning: 'done', parsing: 'done', embedding: 'done', graphing: 'done' },
+ error: null,
+ warnings: [],
+ } as RepoStatusResponse);
+ vi.mocked(client.listRepos).mockResolvedValue({ repos: [], truncated: false });
+ });
+
+ it('offers repositories the server knows about but this browser does not', async () => {
+ // The whole point of the list endpoint: localStorage is per-browser, so a
+ // reader on a new device used to open an empty product and have to index
+ // something before they could ask anything.
+ vi.mocked(client.listRepos).mockResolvedValue({
+ repos: [
+ { repo_id: 'srv-1', url: 'https://github.com/psf/requests.git', status: 'ready' },
+ ],
+ truncated: false,
+ });
+
+ renderSwitcher();
+ fireEvent.click(screen.getByText('select a repo'));
+
+ expect(await screen.findByText('psf/requests')).toBeInTheDocument();
+ expect(screen.queryByText(/None yet/i)).not.toBeInTheDocument();
+ });
+
+ it('does not list the same repository twice when it is also a local recent', async () => {
+ saveRecentRepo({
+ repoId: 'shared-id',
+ url: 'https://github.com/psf/requests.git',
+ status: 'ready',
+ savedAt: new Date().toISOString(),
+ });
+ vi.mocked(client.listRepos).mockResolvedValue({
+ repos: [
+ { repo_id: 'shared-id', url: 'https://github.com/psf/requests.git', status: 'ready' },
+ ],
+ truncated: false,
+ });
+
+ renderSwitcher();
+ fireEvent.click(screen.getByText('select a repo'));
+
+ await waitFor(() => expect(screen.getAllByText('psf/requests')).toHaveLength(1));
+ });
+
+ it('still lists local recents when the server list cannot be read', async () => {
+ // Recents are the reader's own history. Losing them because an extra
+ // request failed would be a regression caused by an enhancement.
+ saveRecentRepo({
+ repoId: 'local-1',
+ url: 'https://github.com/encode/httpx.git',
+ status: 'ready',
+ savedAt: new Date().toISOString(),
+ });
+ vi.mocked(client.listRepos).mockRejectedValue(new Error('gateway down'));
+
+ renderSwitcher();
+ fireEvent.click(screen.getByText('select a repo'));
+
+ expect(await screen.findByText('encode/httpx')).toBeInTheDocument();
+ });
+});
diff --git a/apps/frontend/tests/RequireSession.test.tsx b/apps/frontend/tests/RequireSession.test.tsx
new file mode 100644
index 0000000..58b2552
--- /dev/null
+++ b/apps/frontend/tests/RequireSession.test.tsx
@@ -0,0 +1,96 @@
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { getSession } from '@/api/client';
+import { RequireSession } from '@/components/RequireSession';
+
+vi.mock('@/api/client', async (importOriginal) => ({
+ ...(await importOriginal()),
+ getSession: vi.fn(),
+}));
+
+const mockedGetSession = vi.mocked(getSession);
+
+function renderGuard() {
+ return render(
+
+
+
+
workbench body
+
+ }
+ />
+ login page} />
+
+
+ );
+}
+
+describe('RequireSession', () => {
+ beforeEach(() => {
+ mockedGetSession.mockReset();
+ });
+
+ it('shows neither the workbench nor a redirect while the answer is unknown', () => {
+ // Three states, not two. Rendering either outcome during the check would
+ // assert something that has not arrived yet — the same rule the thread
+ // follows for turn state (Honesty_Constraints §1).
+ mockedGetSession.mockReturnValue(new Promise(() => {}));
+ renderGuard();
+
+ expect(screen.getByRole('status')).toHaveTextContent(/checking session/i);
+ expect(screen.queryByText('workbench body')).not.toBeInTheDocument();
+ expect(screen.queryByText('login page')).not.toBeInTheDocument();
+ });
+
+ it('redirects to the login page when a gate exists and there is no session', async () => {
+ mockedGetSession.mockResolvedValue({
+ auth_required: true,
+ authenticated: false,
+ username: null,
+ });
+ renderGuard();
+
+ expect(await screen.findByText('login page')).toBeInTheDocument();
+ expect(screen.queryByText('workbench body')).not.toBeInTheDocument();
+ });
+
+ it('renders the workbench once a session is present', async () => {
+ mockedGetSession.mockResolvedValue({
+ auth_required: true,
+ authenticated: true,
+ username: 'reviewer',
+ });
+ renderGuard();
+
+ expect(await screen.findByText('workbench body')).toBeInTheDocument();
+ });
+
+ it('does not gate a deployment that has no gate', async () => {
+ // With AUTH_ENABLED off the API reports auth_required: false. Redirecting
+ // to a login page that would accept anything is worse than not gating.
+ mockedGetSession.mockResolvedValue({
+ auth_required: false,
+ authenticated: true,
+ username: null,
+ });
+ renderGuard();
+
+ expect(await screen.findByText('workbench body')).toBeInTheDocument();
+ });
+
+ it('fails open when the session check itself fails', async () => {
+ // Deliberate: this guard is a redirect, not the security boundary. The
+ // gateway answers 401 on every protected route no matter what the SPA
+ // renders, so locking the UI out on a blip would break the product
+ // without protecting anything.
+ mockedGetSession.mockRejectedValue(new Error('network down'));
+ renderGuard();
+
+ expect(await screen.findByText('workbench body')).toBeInTheDocument();
+ });
+});
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 0000000..26eb1f5
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1,28 @@
+"""Keep the test suite out of the developer's `.env`.
+
+`SharedSettings` reads `.env` from the working directory, so every settings
+singleton is built from whatever the developer happens to have configured. That
+is right for running the services and wrong for running the tests: `make check`
+should produce the same answer on every machine.
+
+It is not hypothetical. Switching the auth gate on locally to test it made four
+unrelated tests fail, because the suite picked up `AUTH_ENABLED=true` from the
+file and the assertions were written against the default. The failures pointed
+nowhere near the cause.
+
+Environment variables take precedence over the `.env` file in pydantic-settings,
+and pytest imports this module before any test module, so pinning them here wins
+over the file. Only the settings whose defaults tests actually assert are pinned
+— this is a targeted fix, not an attempt to sandbox the whole environment.
+"""
+
+import os
+
+# Auth defaults off; tests that want the gate turn it on by patching the
+# settings object directly, which is explicit and machine-independent.
+os.environ.setdefault("_DCODE_TEST_ENV_PINNED", "1")
+for name, value in (
+ ("AUTH_ENABLED", "false"),
+ ("DOCS_ENABLED", "true"),
+):
+ os.environ[name] = value
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
index 2ea70dc..9f319cf 100644
--- a/docker-compose.prod.yml
+++ b/docker-compose.prod.yml
@@ -71,6 +71,19 @@ services:
RERANKER_MAX_RETRIES: ${RERANKER_MAX_RETRIES:-3}
RERANKER_PROVIDER: ${RERANKER_PROVIDER:-sidecar}
RERANKER_API_KEY: ${RERANKER_API_KEY:-}
+ # The gate is HARDCODED on, not defaulted. A production deployment that
+ # can be talked out of authenticating by omitting a variable is not a
+ # gate. The API refuses to start if the credential or secret is missing,
+ # so this fails loudly rather than serving the workbench openly.
+ AUTH_ENABLED: "true"
+ AUTH_USERNAME: ${AUTH_USERNAME:?set AUTH_USERNAME in .env.production}
+ AUTH_PASSWORD_HASH: ${AUTH_PASSWORD_HASH:?set AUTH_PASSWORD_HASH in .env.production — generate with `python -m dcode_api.hash_password`}
+ AUTH_SESSION_SECRET: ${AUTH_SESSION_SECRET:?set AUTH_SESSION_SECRET in .env.production — at least 32 characters}
+ AUTH_SESSION_TTL_SECONDS: ${AUTH_SESSION_TTL_SECONDS:-43200}
+ AUTH_COOKIE_SECURE: ${AUTH_COOKIE_SECURE:-true}
+ AUTH_DAILY_QUERY_LIMIT: ${AUTH_DAILY_QUERY_LIMIT:-200}
+ # /docs, /redoc and /openapi.json enumerate the /internal/* surface.
+ DOCS_ENABLED: "false"
LOG_LEVEL: ${LOG_LEVEL:-info}
depends_on:
postgres:
@@ -146,6 +159,11 @@ services:
# Not read directly by the agent, but dcode_shared.db.models binds the
# chunks.embedding column type to it at import time.
EMBEDDING_DIM: ${EMBEDDING_DIM:?set EMBEDDING_DIM in .env.production — it must equal the dimension the volume was migrated at}
+ # Deploy.md R-2. A budget that expires inside the platform's request
+ # limit, and comment frames so a slow answer is not read as an idle
+ # connection.
+ AGENT_REQUEST_BUDGET_SECONDS: ${AGENT_REQUEST_BUDGET_SECONDS:-240}
+ SSE_HEARTBEAT_SECONDS: ${SSE_HEARTBEAT_SECONDS:-20}
RETRIEVAL_BASE_URL: http://api:8000
WORKDIR_BASE: /tmp/dcode-workdirs
INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env.production}
diff --git a/docker-compose.yml b/docker-compose.yml
index 1dc422b..98ca61f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -75,6 +75,17 @@ services:
# 'sidecar' (default) or 'siliconflow' — both serve bge-reranker-v2-m3.
RERANKER_PROVIDER: ${RERANKER_PROVIDER:-sidecar}
RERANKER_API_KEY: ${RERANKER_API_KEY:-}
+ # The shared-account gate, off by default so the developer stack is
+ # unchanged. Present here so it can be switched on locally to test it —
+ # docker-compose.prod.yml hardcodes it on instead of defaulting it.
+ AUTH_ENABLED: ${AUTH_ENABLED:-false}
+ AUTH_USERNAME: ${AUTH_USERNAME:-dcode}
+ AUTH_PASSWORD_HASH: ${AUTH_PASSWORD_HASH:-}
+ AUTH_SESSION_SECRET: ${AUTH_SESSION_SECRET:-}
+ AUTH_SESSION_TTL_SECONDS: ${AUTH_SESSION_TTL_SECONDS:-43200}
+ AUTH_COOKIE_SECURE: ${AUTH_COOKIE_SECURE:-true}
+ AUTH_DAILY_QUERY_LIMIT: ${AUTH_DAILY_QUERY_LIMIT:-200}
+ DOCS_ENABLED: ${DOCS_ENABLED:-true}
LOG_LEVEL: ${LOG_LEVEL:-info}
ports:
- "8000:8000"
@@ -192,6 +203,11 @@ services:
RERANKER_MAX_RETRIES: ${RERANKER_MAX_RETRIES:-3}
RERANKER_PROVIDER: ${RERANKER_PROVIDER:-sidecar}
RERANKER_API_KEY: ${RERANKER_API_KEY:-}
+ # Deploy.md R-2. A budget that expires inside the platform's request
+ # limit, and comment frames so a slow answer is not read as an idle
+ # connection.
+ AGENT_REQUEST_BUDGET_SECONDS: ${AGENT_REQUEST_BUDGET_SECONDS:-240}
+ SSE_HEARTBEAT_SECONDS: ${SSE_HEARTBEAT_SECONDS:-20}
RETRIEVAL_BASE_URL: http://api:8000
WORKDIR_BASE: /tmp/dcode-workdirs
INTERNAL_API_KEY: ${INTERNAL_API_KEY:?set INTERNAL_API_KEY in .env}
diff --git a/infra/docker/api.Dockerfile b/infra/docker/api.Dockerfile
index bcf73a8..4688875 100644
--- a/infra/docker/api.Dockerfile
+++ b/infra/docker/api.Dockerfile
@@ -23,6 +23,10 @@ RUN uv sync --no-dev
EXPOSE 8000
-CMD ["uv", "run", "--package", "dcode-api", \
- "uvicorn", "dcode_api.main:app", \
- "--host", "0.0.0.0", "--port", "8000"]
+# HOST and PORT are read at start, not baked. Railway injects PORT and its
+# private network is IPv6, so a service that binds 0.0.0.0 there is reachable
+# by nothing. The defaults are the previous literals, so compose is unchanged
+# — `sh -c exec` keeps uvicorn as the container's main process rather than
+# leaving a shell in front of it to swallow signals.
+CMD ["sh", "-c", "exec uv run --package dcode-api uvicorn dcode_api.main:app \
+ --host ${HOST:-0.0.0.0} --port ${PORT:-8000}"]
diff --git a/infra/docker/frontend.Dockerfile b/infra/docker/frontend.Dockerfile
index 942d2fc..f20892a 100644
--- a/infra/docker/frontend.Dockerfile
+++ b/infra/docker/frontend.Dockerfile
@@ -15,7 +15,24 @@ RUN npm run build
FROM nginx:1.27-alpine
-COPY nginx.conf /etc/nginx/conf.d/default.conf
+# The site config is a template. The nginx image's entrypoint runs envsubst
+# over /etc/nginx/templates/*.template into /etc/nginx/conf.d/ at boot.
+#
+# NGINX_ENVSUBST_FILTER is not optional: without it envsubst would also
+# substitute nginx's own $host, $remote_addr, $request_uri and $uri, producing
+# a config that is valid, empty in the places that matter, and broken in a way
+# that reads like a proxy bug.
+COPY nginx.conf.template /etc/nginx/templates/default.conf.template
+ENV NGINX_ENVSUBST_FILTER="^(PORT|API_UPSTREAM|DNS_RESOLVER)$"
+
+# Defaults reproduce the previous behaviour exactly, so the developer stack and
+# docker-compose.prod.yml need no change. Railway overrides PORT (it injects
+# one), API_UPSTREAM (http://.railway.internal:8000) and DNS_RESOLVER
+# (its internal resolver) — see Deploy.md R-4.
+ENV PORT=80
+ENV API_UPSTREAM=http://api:8000
+ENV DNS_RESOLVER=127.0.0.11
+
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
diff --git a/infra/docker/railway-agent-worker-entrypoint.sh b/infra/docker/railway-agent-worker-entrypoint.sh
new file mode 100755
index 0000000..d9c0f6b
--- /dev/null
+++ b/infra/docker/railway-agent-worker-entrypoint.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Run the agent and the index worker in one container.
+#
+# THIS IS A RAILWAY WORKAROUND, NOT AN ARCHITECTURE CHANGE. Deploy.md R-1: a
+# Railway volume attaches to exactly one service, and the worker writes the
+# cloned repository tree that the agent's read_file / grep / list_directory
+# tools read back at query time. Two services cannot share it, so the two
+# processes that share the volume share a container.
+#
+# Locally, Docker shares volumes fine and `docker-compose.yml` keeps them
+# separate. Nothing here is used by the developer stack (Deploy.md §5.1).
+#
+# The durable fix is to stop reading repository source from a filesystem at
+# all — Deploy.md §11 item 2 — and it is deliberately not attempted here.
+set -euo pipefail
+
+term() {
+ # Forward the platform's shutdown to both children rather than letting them
+ # be killed individually, so neither is torn down mid-write.
+ trap - TERM INT
+ kill -TERM "${agent_pid:-}" "${worker_pid:-}" 2>/dev/null || true
+ wait
+}
+trap term TERM INT
+
+echo "[entrypoint] starting agent on :${PORT:-8001}"
+uv run --package dcode-agent uvicorn dcode_agent.main:app \
+ --host "${HOST:-::}" --port "${PORT:-8001}" &
+agent_pid=$!
+
+echo "[entrypoint] starting index worker"
+uv run --package dcode-worker python -m dcode_worker.main &
+worker_pid=$!
+
+# `wait -n` returns as soon as EITHER child exits. Waiting on both in sequence
+# would leave a container that looks healthy while indexing is silently dead:
+# the agent would keep answering, and every submitted repository would sit in
+# `queued` forever with nothing to explain it. Exiting takes the platform's
+# restart with it, which is the visible failure.
+set +e
+wait -n
+exit_code=$?
+set -e
+
+echo "[entrypoint] a child exited with ${exit_code}; stopping the other" >&2
+kill -TERM "$agent_pid" "$worker_pid" 2>/dev/null || true
+wait 2>/dev/null || true
+exit "${exit_code}"
diff --git a/infra/docker/railway-agent-worker.Dockerfile b/infra/docker/railway-agent-worker.Dockerfile
new file mode 100644
index 0000000..1a3b695
--- /dev/null
+++ b/infra/docker/railway-agent-worker.Dockerfile
@@ -0,0 +1,41 @@
+# Dcode agent + index worker in one image — Railway only.
+#
+# Deploy.md R-1: a Railway volume attaches to exactly one service, and the
+# worker writes the repository tree the agent's file tools read. The two
+# processes that share that volume therefore share a container.
+#
+# `docker-compose.yml` still runs them as two services against a shared Docker
+# volume, and this file is not referenced there. The local path is not degraded
+# to match the constrained one (Deploy.md §5.1).
+#
+# Build context: repo root.
+FROM python:3.11-slim
+
+# ripgrep for the agent's grep tool; git for the worker's clone stage. Two
+# images' worth of dependencies, because this is two services.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ripgrep git curl \
+ && rm -rf /var/lib/apt/lists/* \
+ && pip install --no-cache-dir uv
+
+WORKDIR /app
+
+COPY pyproject.toml ./
+COPY packages ./packages
+COPY apps/api ./apps/api
+COPY apps/worker ./apps/worker
+COPY apps/agent ./apps/agent
+COPY apps/eval ./apps/eval
+COPY apps/embedding ./apps/embedding
+COPY apps/reranker ./apps/reranker
+
+RUN uv sync --no-dev
+
+COPY infra/docker/railway-agent-worker-entrypoint.sh /usr/local/bin/dcode-entrypoint
+RUN chmod +x /usr/local/bin/dcode-entrypoint
+
+# Railway injects PORT. 8001 keeps the local default meaningful.
+ENV PORT=8001
+EXPOSE 8001
+
+CMD ["/usr/local/bin/dcode-entrypoint"]
diff --git a/packages/shared/src/dcode_shared/schemas.py b/packages/shared/src/dcode_shared/schemas.py
index 0e5a837..1cee05a 100644
--- a/packages/shared/src/dcode_shared/schemas.py
+++ b/packages/shared/src/dcode_shared/schemas.py
@@ -109,6 +109,29 @@ class RepoStatusResponse(BaseModel):
warnings: list[str] = Field(default_factory=list)
+class RepoSummary(BaseModel):
+ """One row of GET /api/v1/repos."""
+
+ repo_id: UUID
+ url: str
+ status: RepoStatus
+
+
+class RepoListResponse(BaseModel):
+ """GET /api/v1/repos response body.
+
+ Exists because the workbench had no way to discover what is indexed: the
+ switcher read `localStorage` only, so a reader on a new device saw an empty
+ product and had to index a repository themselves before they could ask
+ anything. `truncated` is explicit rather than implied by a full page —
+ silently showing a subset of what exists is the kind of quiet claim this
+ project avoids elsewhere.
+ """
+
+ repos: list[RepoSummary] = Field(default_factory=list)
+ truncated: bool = False
+
+
# ===========================================================================
# Public query API (request body; SSE events live in events.py)
# ===========================================================================
diff --git a/packages/shared/tests/test_config_hardening.py b/packages/shared/tests/test_config_hardening.py
index c4949bc..5b0500c 100644
--- a/packages/shared/tests/test_config_hardening.py
+++ b/packages/shared/tests/test_config_hardening.py
@@ -131,6 +131,51 @@ def test_prod_services_receive_the_retrieval_settings_they_read() -> None:
assert not missing, f"{service} is missing {missing} in docker-compose.prod.yml"
+def test_prod_compose_cannot_be_deployed_without_the_auth_gate() -> None:
+ """AUTH_ENABLED is hardcoded on, not defaulted, and the rest is required.
+
+ `${AUTH_ENABLED:-true}` would let a deployment turn the gate off by setting
+ one variable, which is not a gate. The credential and the signing secret
+ use `:?` so a missing one stops the stack instead of producing an API that
+ is open because it could not authenticate.
+
+ The API also refuses to start in that state (`auth_configuration_error`),
+ so this is the outer of two layers rather than the only one.
+ """
+ compose = (_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8")
+ api = _service_block(compose, "api")
+
+ assert '\n AUTH_ENABLED: "true"' in api
+ assert "${AUTH_ENABLED" not in compose, "the gate must not be overridable from the env file"
+ assert "${AUTH_PASSWORD_HASH:?" in api
+ assert "${AUTH_SESSION_SECRET:?" in api
+ assert "${AUTH_PASSWORD_HASH:-" not in compose
+ assert "${AUTH_SESSION_SECRET:-" not in compose
+
+
+def test_prod_compose_closes_the_openapi_surface() -> None:
+ """F-05: /docs, /redoc and /openapi.json enumerate the /internal/* routes."""
+ api = _service_block((_ROOT / "docker-compose.prod.yml").read_text(encoding="utf-8"), "api")
+ assert '\n DOCS_ENABLED: "false"' in api
+
+
+def test_env_examples_never_ship_a_real_looking_credential() -> None:
+ """A password hash or session secret in a committed file is a shipped credential.
+
+ The examples carry placeholders; `python -m dcode_api.hash_password` writes
+ the real values into `.env.production`, which is gitignored.
+ """
+ for name in (".env.example", ".env.production.example"):
+ content = (_ROOT / name).read_text(encoding="utf-8")
+ for line in content.splitlines():
+ stripped = line.strip()
+ if stripped.startswith("AUTH_PASSWORD_HASH="):
+ value = stripped.split("=", 1)[1]
+ assert not value.startswith("pbkdf2_sha256$"), f"{name} ships a real hash"
+ if stripped.startswith("AUTH_SESSION_SECRET="):
+ assert not stripped.split("=", 1)[1].strip(), f"{name} ships a session secret"
+
+
def test_no_dead_loopback_endpoints_in_production_config() -> None:
"""A reranker endpoint pointing at localhost:9999 inside a container.