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. +

+ +
+ + + + + {/* Announced, because a failed sign-in with no visible cause is the + point at which a screen-reader user is stuck with no recourse. */} +

+ {error} +

+ + +
+
+
+ ); +} 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.