From ebfb8d02b1877ddf4313c963bb9fde7ff114acbc Mon Sep 17 00:00:00 2001
From: odieyang <520yangziqi@gmail.com>
Date: Sun, 2 Aug 2026 20:30:47 -0700
Subject: [PATCH 1/3] feat(deploy): gate the workbench behind a shared-account
session
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Deploy.md D-2 and D-6: the landing page and the evaluation write-up stay
public, the product does not. One shared account, so no user table and no
migration.
No new dependency. passlib, pyjwt and itsdangerous are all absent from this
workspace and pulling one in to authenticate a single demo account would be
the larger change, so this is stdlib: PBKDF2-HMAC-SHA256 at OWASP's 600k
floor, and an HMAC-signed session cookie that is HttpOnly, Secure and
SameSite=Lax.
The gate is off by default, so local development, every current compose
invocation and the existing tests are unaffected. docker-compose.prod.yml
HARDCODES it on rather than defaulting it — a production gate that can be
switched off by omitting a variable is not a gate — and the API refuses to
start when it is on but unconfigured, because an auth gate that fails open
looks exactly like one that works.
Also closes F-05: /docs, /redoc and /openapi.json enumerate the /internal/*
surface and are now off in production.
A per-session daily query cap sits on /query alone. The login wall removes
anonymous callers; it does nothing about a signed-in one looping a question
through three metered APIs. It is counted before the agent is reached and
it fails open on a Redis error, because a spend guard that takes the
service down when a cache blips has traded a bounded bill for an outage.
Two findings from verifying this, both fixed here and written up in
Deploy.md.
The first is a real trap. Docker Compose interpolates `$VAR` inside
env-file values, so the conventional `pbkdf2_sha256$600000$salt$hash`
reached the container as 22 characters with three of four segments eaten.
Nothing errored: the API booted, the health check passed, and every login
failed forever, indistinguishable from a wrong password. The format now
joins on "." so the character never appears, and the hash is parsed at
startup rather than checked for non-emptiness, so any corruption stops the
boot. This applies to every hand-picked secret containing `$`, not just
this one.
The second is that the test suite reads the developer's .env, so `make
check` is not hermetic. Switching the gate on locally failed four unrelated
tests and the failures pointed nowhere near the cause. A root conftest.py
pins the settings whose defaults tests assert.
Verified live on a gated container: protected routes 401, /healthz and the
session endpoints 200, /openapi.json 404, wrong password 401 with no
cookie, correct password sets the hardened cookie and opens the gate,
switching it back off restores everything. Not verified: the /workbench to
/login redirect in a real browser — it has four unit tests, but headless
screenshots do not work here and that is not a reason to claim otherwise.
Deploy.md says who needs to look at what.
---
.env.production.example | 34 ++
Deploy.md | 71 +++-
apps/api/src/dcode_api/auth.py | 245 +++++++++++
apps/api/src/dcode_api/hash_password.py | 37 ++
apps/api/src/dcode_api/main.py | 77 +++-
apps/api/src/dcode_api/routes/auth.py | 106 +++++
apps/api/src/dcode_api/routes/query.py | 44 +-
apps/api/src/dcode_api/settings.py | 22 +
apps/api/tests/test_auth.py | 382 ++++++++++++++++++
apps/frontend/src/App.tsx | 18 +-
apps/frontend/src/api/client.ts | 62 +++
apps/frontend/src/api/types.ts | 18 +
.../src/components/RequireSession.tsx | 58 +++
apps/frontend/src/pages/LoginPage.tsx | 101 +++++
apps/frontend/tests/App.test.tsx | 30 +-
apps/frontend/tests/LoginPage.test.tsx | 78 ++++
apps/frontend/tests/RequireSession.test.tsx | 96 +++++
conftest.py | 28 ++
docker-compose.prod.yml | 13 +
docker-compose.yml | 11 +
.../shared/tests/test_config_hardening.py | 45 +++
21 files changed, 1538 insertions(+), 38 deletions(-)
create mode 100644 apps/api/src/dcode_api/auth.py
create mode 100644 apps/api/src/dcode_api/hash_password.py
create mode 100644 apps/api/src/dcode_api/routes/auth.py
create mode 100644 apps/api/tests/test_auth.py
create mode 100644 apps/frontend/src/components/RequireSession.tsx
create mode 100644 apps/frontend/src/pages/LoginPage.tsx
create mode 100644 apps/frontend/tests/LoginPage.test.tsx
create mode 100644 apps/frontend/tests/RequireSession.test.tsx
create mode 100644 conftest.py
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..163706e 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, PR 2 and PR 3 landed. PR 4–5 not started.** 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,11 +420,34 @@ 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.**
+
+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`
@@ -476,11 +499,11 @@ 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 |
@@ -493,12 +516,40 @@ as leads to verify when the PR touches them, not as established fact.
| 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-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
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/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/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..e58df74 100644
--- a/apps/frontend/src/api/client.ts
+++ b/apps/frontend/src/api/client.ts
@@ -7,12 +7,14 @@
import type {
ErrorPayload,
FinalAnswerPayload,
+ LoginRequest,
PartialAnswerPayload,
QueryRequest,
QueryStreamEvent,
RepoCreateRequest,
RepoCreateResponse,
RepoStatusResponse,
+ SessionState,
SourceResponse,
SymbolNeighbors,
SSEEventName,
@@ -25,12 +27,68 @@ 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}`);
}
@@ -39,6 +97,7 @@ export async function submitRepo(body: RepoCreateRequest): 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 +114,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 +125,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 +149,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..dd72a92 100644
--- a/apps/frontend/src/api/types.ts
+++ b/apps/frontend/src/api/types.ts
@@ -150,3 +150,21 @@ export interface SymbolNeighbors {
calls: Location[];
references: Location[];
}
+
+// --- 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/pages/LoginPage.tsx b/apps/frontend/src/pages/LoginPage.tsx
new file mode 100644
index 0000000..ab6fbaa
--- /dev/null
+++ b/apps/frontend/src/pages/LoginPage.tsx
@@ -0,0 +1,101 @@
+import { useState } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+
+import { UnauthenticatedError, login } from '@/api/client';
+import { Button } from '@/components/ui';
+
+/**
+ * The gate between the landing page and the workbench (Deploy.md D-2).
+ *
+ * One shared account, so there is no "sign up", no "forgot password" and no
+ * account menu — offering any of them would imply an identity system that does
+ * not exist (D-6).
+ */
+export default function LoginPage() {
+ const navigate = useNavigate();
+ const [username, setUsername] = useState('');
+ const [password, setPassword] = useState('');
+ const [error, setError] = useState(null);
+ const [submitting, setSubmitting] = useState(false);
+
+ async function onSubmit(event: React.FormEvent) {
+ event.preventDefault();
+ setSubmitting(true);
+ setError(null);
+ try {
+ await login({ username, password });
+ navigate('/workbench', { replace: true });
+ } catch (caught) {
+ // A wrong password and an unreachable gateway are different problems and
+ // are worth different sentences: one is the reader's to fix.
+ setError(
+ caught instanceof UnauthenticatedError
+ ? 'Incorrect username or password.'
+ : 'Could not reach the server. Check that the backend is running.'
+ );
+ } finally {
+ setSubmitting(false);
+ }
+ }
+
+ return (
+
+
+
+ ← Dcode
+
+
+
+ Sign in to the workbench
+
+
+ The evaluation write-up is{' '}
+
+ open to everyone
+
+ . The workbench indexes repositories and calls metered models, so it is not.
+
+
+
+
+
+ );
+}
diff --git a/apps/frontend/tests/App.test.tsx b/apps/frontend/tests/App.test.tsx
index 11d1af7..8a0e20b 100644
--- a/apps/frontend/tests/App.test.tsx
+++ b/apps/frontend/tests/App.test.tsx
@@ -1,9 +1,20 @@
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { render, screen } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
import App from '@/App';
+import { getSession } from '@/api/client';
+
+// The workbench sits behind a session check, so every render of it now waits
+// on one request. Stubbed to the ungated answer — the gate's own behaviour is
+// covered in RequireSession.test.tsx rather than incidentally here.
+vi.mock('@/api/client', async (importOriginal) => ({
+ ...(await importOriginal()),
+ getSession: vi.fn(),
+}));
+
+const mockedGetSession = vi.mocked(getSession);
function renderAppAt(path: string) {
const queryClient = new QueryClient();
@@ -17,14 +28,27 @@ function renderAppAt(path: string) {
}
describe('App IA', () => {
+ beforeEach(() => {
+ mockedGetSession.mockResolvedValue({
+ auth_required: false,
+ authenticated: true,
+ username: null,
+ });
+ });
+
it('renders the marketing landing at /', () => {
renderAppAt('/');
expect(screen.getByText(/Understand any codebase/i)).toBeInTheDocument();
});
- it('renders the workbench at /workbench', () => {
+ it('renders the workbench at /workbench', async () => {
renderAppAt('/workbench');
- expect(screen.getByText(/ask this codebase anything/i)).toBeInTheDocument();
+ expect(await screen.findByText(/ask this codebase anything/i)).toBeInTheDocument();
+ });
+
+ it('renders the login page at /login', () => {
+ renderAppAt('/login');
+ expect(screen.getByRole('heading', { name: /sign in to the workbench/i })).toBeInTheDocument();
});
it('renders the methodology page at /methodology', () => {
diff --git a/apps/frontend/tests/LoginPage.test.tsx b/apps/frontend/tests/LoginPage.test.tsx
new file mode 100644
index 0000000..f38a0ba
--- /dev/null
+++ b/apps/frontend/tests/LoginPage.test.tsx
@@ -0,0 +1,78 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { UnauthenticatedError, login } from '@/api/client';
+import LoginPage from '@/pages/LoginPage';
+
+vi.mock('@/api/client', async (importOriginal) => ({
+ ...(await importOriginal()),
+ login: vi.fn(),
+}));
+
+const mockedLogin = vi.mocked(login);
+
+function renderLogin() {
+ return render(
+
+
+ } />
+ workbench body
} />
+
+
+ );
+}
+
+// fireEvent rather than user-event: the latter is not a dependency of this
+// workspace, and adding one for a single file is the larger change.
+function submit(username = 'reviewer', password = 'pw') {
+ fireEvent.change(screen.getByLabelText(/username/i), { target: { value: username } });
+ fireEvent.change(screen.getByLabelText(/password/i), { target: { value: password } });
+ fireEvent.click(screen.getByRole('button', { name: /sign in/i }));
+}
+
+describe('LoginPage', () => {
+ beforeEach(() => {
+ mockedLogin.mockReset();
+ });
+
+ it('sends the reader to the workbench on success', async () => {
+ mockedLogin.mockResolvedValue({
+ auth_required: true,
+ authenticated: true,
+ username: 'reviewer',
+ });
+ renderLogin();
+ submit();
+
+ expect(await screen.findByText('workbench body')).toBeInTheDocument();
+ });
+
+ it('says the credentials are wrong when they are', async () => {
+ mockedLogin.mockRejectedValue(new UnauthenticatedError());
+ renderLogin();
+ submit();
+
+ expect(await screen.findByRole('alert')).toHaveTextContent(/incorrect username or password/i);
+ expect(screen.queryByText('workbench body')).not.toBeInTheDocument();
+ });
+
+ it('distinguishes an unreachable server from a wrong password', async () => {
+ // These are different problems and only one of them is the reader's to
+ // fix. Collapsing them into "sign-in failed" sends someone hunting for a
+ // typo while the backend is down.
+ mockedLogin.mockRejectedValue(new Error('Failed to fetch'));
+ renderLogin();
+ submit();
+
+ expect(await screen.findByRole('alert')).toHaveTextContent(/could not reach the server/i);
+ });
+
+ it('keeps the public evaluation write-up linked from the gate', () => {
+ renderLogin();
+ expect(screen.getByRole('link', { name: /open to everyone/i })).toHaveAttribute(
+ 'href',
+ '/methodology'
+ );
+ });
+});
diff --git a/apps/frontend/tests/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..7ef11d7 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:
diff --git a/docker-compose.yml b/docker-compose.yml
index 1dc422b..d813535 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"
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.
From 94c8b931a5757bf6fe69d2710d2afec3b872052f Mon Sep 17 00:00:00 2001
From: odieyang <520yangziqi@gmail.com>
Date: Sun, 2 Aug 2026 22:08:28 -0700
Subject: [PATCH 2/3] docs(deploy): write down how to see the auth gate locally
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
The two verification items that need a human need the gate switched on
first, and nothing switches it on by default. That walkthrough existed only
in a conversation, which means the next person rediscovers it.
Records the part that actually decides whether the gate can be tested
locally at all: apps/frontend has no .env, so VITE_API_BASE_URL is
undefined and BASE_URL is the empty string, which makes the SPA call
same-origin /api/v1/* on 5173 with vite.config.ts proxying to the gateway.
No cross-origin request, so allow_credentials=False never comes into it.
Pointing VITE_API_BASE_URL at localhost:8000 breaks that, and the failure
would look like a cookie bug rather than a configuration one.
Plus the three things that otherwise cost time: the Secure-cookie fallback
on plain-HTTP localhost, not hand-editing the hash back to $ separators
(§2.3), and that make check is unaffected because conftest.py pins the
setting — which exists because a locally-enabled gate once failed four
unrelated tests with no hint of why.
---
Deploy.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/Deploy.md b/Deploy.md
index 163706e..a81e8ce 100644
--- a/Deploy.md
+++ b/Deploy.md
@@ -640,6 +640,75 @@ 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.
+
+```bash
+# 1. Generate a hash. Interactive and unechoed; it takes no argument, so the
+# password stays out of shell history and the process list.
+uv run --package dcode-api python -m dcode_api.hash_password
+
+# 2. Append to .env (gitignored). Use the hash from step 1.
+# AUTH_ENABLED=true
+# AUTH_USERNAME=reviewer
+# AUTH_PASSWORD_HASH=pbkdf2_sha256.600000..
+# AUTH_SESSION_SECRET=
+
+# 3. Recreate the API. No --build: the image already carries the code, and
+# only the environment changed.
+docker compose up -d api
+```
+
+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.
+
+---
+
## 11. Open Questions
Carried here rather than answered by assumption.
From 043ec9a56e334811cf753371e88749dc5981981a Mon Sep 17 00:00:00 2001
From: odieyang <520yangziqi@gmail.com>
Date: Sun, 2 Aug 2026 22:36:22 -0700
Subject: [PATCH 3/3] feat(deploy): make the stack deployable on Railway
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Four platform constraints, one product gap, and two build fixes.
R-1, the volume. A Railway volume attaches to exactly one service, and the
worker writes the repository tree the agent's read_file / grep /
list_directory tools read back. The two processes that share it now share a
container — via a Railway-only Dockerfile and entrypoint. docker-compose.yml
still runs them separately against a shared Docker volume: local Docker can
share volumes, Railway cannot, and that is a platform difference rather than
a reason to degrade the local path. The entrypoint uses `wait -n` so either
child exiting takes the container down; waiting on both in sequence would
leave one that looks healthy while indexing is silently dead and every
submitted repository sits in `queued` with nothing to explain it.
R-2, the request limits. A query had no overall ceiling at all — only
per-hop timeouts, so fourteen steps plus rerank and synthesis could outlive
the platform's five-minute cut, and an abandoned request kept spending on
three metered APIs. There is now a budget that expires inside that window
and emits a labelled TIMEOUT rather than a connection that simply stops,
and heartbeat comment frames so a slow answer is not mistaken for an idle
one. `:` is a comment in the SSE grammar and the frontend parser already
drops those, so no client contract changed. Nothing half-finished is
emitted on timeout: a partial walk has not been through the groundedness
verifier.
R-4, nginx. The site config becomes a template rendered by the image's
envsubst, with NGINX_ENVSUBST_FILTER restricting it to three names —
without that it would also substitute nginx's own $host and $request_uri
and produce a config that is valid and quietly wrong. The proxy target is
a variable with a resolver because Railway's private DNS changes address on
every redeploy and nginx caches a literal target for the life of the
process; the API would keep working until it was next redeployed and then
fail with no change on this side. Defaults reproduce the previous behaviour
exactly, so compose is unaffected.
F-09, the product gap. GET /api/v1/repos, merged behind the localStorage
recents rather than replacing them: recents carry the URL as typed and this
reader's ordering, the server knows what exists. Without it a reader on a
new device opened an empty workbench and had to index something before they
could ask anything.
Also: gzip was off (the base image ships it commented out and this config
never enabled it), no .dockerignore anywhere, and HOST/PORT were baked into
the API image — Railway injects PORT and its private network is IPv6, so a
service bound to 0.0.0.0 there is reachable by nothing.
Verified by building and running the frontend image: the template renders
correctly under both the default and Railway shapes with nginx's own
variables intact, gzip takes the main chunk from 760,088 to 269,497 bytes,
hashed assets carry one Cache-Control rather than the two the first attempt
emitted, and index.html is no-store. The list endpoint was checked against
the live local database. Heartbeats and the budget have five tests.
Not verified: no Railway deployment exists, and the combined agent-worker
container has never been run. Deploy.md §10.2 is a runbook written from the
code, marked as such.
Deploy.md §10.1 is also rewritten. Its setup block contained placeholders
inside a copy-pasteable heredoc, that got pasted verbatim, and the
placeholder became the credential — the API refused to boot, correctly and
with the right message. The refusal was fine; the instructions were the
defect, so the block now substitutes its own values.
---
.dockerignore | 57 ++++++++
Deploy.md | 131 +++++++++++++++---
apps/agent/src/dcode_agent/main.py | 51 ++++---
apps/agent/src/dcode_agent/settings.py | 15 ++
apps/agent/src/dcode_agent/sse.py | 27 +++-
apps/agent/tests/test_stream_lifetime.py | 120 ++++++++++++++++
apps/api/src/dcode_api/routes/repos.py | 44 ++++++
apps/api/tests/test_repos_route.py | 112 ++++++++++++++-
apps/frontend/.dockerignore | 15 ++
apps/frontend/nginx.conf | 25 ----
apps/frontend/nginx.conf.template | 82 +++++++++++
apps/frontend/src/api/client.ts | 17 +++
apps/frontend/src/api/types.ts | 15 ++
.../src/components/workbench/RepoSwitcher.tsx | 52 +++++--
apps/frontend/tests/RepoSwitcher.test.tsx | 88 +++++++++++-
docker-compose.prod.yml | 5 +
docker-compose.yml | 5 +
infra/docker/api.Dockerfile | 10 +-
infra/docker/frontend.Dockerfile | 19 ++-
.../docker/railway-agent-worker-entrypoint.sh | 48 +++++++
infra/docker/railway-agent-worker.Dockerfile | 41 ++++++
packages/shared/src/dcode_shared/schemas.py | 23 +++
22 files changed, 919 insertions(+), 83 deletions(-)
create mode 100644 .dockerignore
create mode 100644 apps/agent/tests/test_stream_lifetime.py
create mode 100644 apps/frontend/.dockerignore
delete mode 100644 apps/frontend/nginx.conf
create mode 100644 apps/frontend/nginx.conf.template
create mode 100755 infra/docker/railway-agent-worker-entrypoint.sh
create mode 100644 infra/docker/railway-agent-worker.Dockerfile
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/Deploy.md b/Deploy.md
index a81e8ce..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, PR 2 and PR 3 landed. PR 4–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
@@ -449,7 +449,7 @@ 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`
+### PR 4 — `feat/railway-deploy` — **built and locally verified; not deployed**
The only Railway-specific PR. Mostly additive files.
@@ -473,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`
@@ -507,15 +525,16 @@ as leads to verify when the PR touches them, not as established fact.
| 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** |
@@ -651,22 +670,47 @@ 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
-# 1. Generate a hash. Interactive and unechoed; it takes no argument, so the
-# password stays out of shell history and the process list.
-uv run --package dcode-api python -m dcode_api.hash_password
-
-# 2. Append to .env (gitignored). Use the hash from step 1.
-# AUTH_ENABLED=true
-# AUTH_USERNAME=reviewer
-# AUTH_PASSWORD_HASH=pbkdf2_sha256.600000..
-# AUTH_SESSION_SECRET=
-
-# 3. Recreate the API. No --build: the image already carries the code, and
-# only the environment changed.
+# 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.
@@ -709,6 +753,51 @@ 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/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/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/api/client.ts b/apps/frontend/src/api/client.ts
index e58df74..4068827 100644
--- a/apps/frontend/src/api/client.ts
+++ b/apps/frontend/src/api/client.ts
@@ -13,6 +13,7 @@ import type {
QueryStreamEvent,
RepoCreateRequest,
RepoCreateResponse,
+ RepoListResponse,
RepoStatusResponse,
SessionState,
SourceResponse,
@@ -95,6 +96,22 @@ export async function submitRepo(body: RepoCreateRequest): 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');
diff --git a/apps/frontend/src/api/types.ts b/apps/frontend/src/api/types.ts
index dd72a92..f2da0e9 100644
--- a/apps/frontend/src/api/types.ts
+++ b/apps/frontend/src/api/types.ts
@@ -151,6 +151,21 @@ export interface SymbolNeighbors {
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 {
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/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/docker-compose.prod.yml b/docker-compose.prod.yml
index 7ef11d7..9f319cf 100644
--- a/docker-compose.prod.yml
+++ b/docker-compose.prod.yml
@@ -159,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 d813535..98ca61f 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -203,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)
# ===========================================================================