Skip to content

Commit ad35531

Browse files
JuliaEdomclaude
andcommitted
fix(api): rate-limit anonymous callers, redact 500s, expose truncated, constant-time key
Closes the gap between what the README promises and what the public API did: - Rate limit is now unconditional. require_api_key returned "anonymous" BEFORE the limiter ran, so a keyless deploy (the default) had no 60/min limit at all. Anonymous callers are now bucketed by client IP. - The API key is read from Settings (validation_alias NL_SQL_API_KEY), so a value in .env is honoured — matching the module docstring, which was previously false (key was read straight from os.environ). - Key comparison uses secrets.compare_digest (constant-time), not `!=`. - 500s no longer leak exception text (paths, driver internals, provider payloads): the client gets a generic message + trace_id; the detail is logged server-side. - AskResponse now carries `truncated` so a client can tell a full result from a row-capped one (the flag existed on QueryResult but was dropped at the boundary). Regression tests: 61st anonymous request → 429, wrong key → 401, truncated flag surfaced, 500 body carries no secret text. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 91b69b8 commit ad35531

3 files changed

Lines changed: 101 additions & 13 deletions

File tree

‎src/nl_sql/api/main.py‎

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@
1919

2020
from __future__ import annotations
2121

22+
import logging
23+
import secrets
2224
import time
2325
import uuid
2426
from collections import defaultdict, deque
@@ -44,6 +46,8 @@
4446
from nl_sql.llm.providers.mistral import MistralProvider
4547
from nl_sql.schema_index.indexer import SchemaIndex
4648

49+
logger = logging.getLogger("nl_sql.api")
50+
4751
# ---------------------------------------------------------- response models
4852

4953

@@ -95,6 +99,7 @@ class AskResponse(BaseModel):
9599
rows: list[list[Any]] | None
96100
columns: list[str] | None
97101
row_count: int
102+
truncated: bool
98103
caption: str
99104
output_format: str | None
100105
error_kind: str | None
@@ -129,10 +134,12 @@ def _result_to_response(result: PipelineRunResult, *, latency_ms: float) -> AskR
129134
rows: list[list[Any]] | None = None
130135
columns: list[str] | None = None
131136
row_count = 0
137+
truncated = False
132138
if result.outcome is not None and result.outcome.result is not None:
133139
rows = [list(r) for r in result.outcome.result.rows]
134140
columns = list(result.outcome.result.columns)
135141
row_count = result.outcome.result.row_count
142+
truncated = result.outcome.result.truncated
136143

137144
trace_steps: list[TraceStep] = []
138145
for step in result.trace:
@@ -158,6 +165,7 @@ def _result_to_response(result: PipelineRunResult, *, latency_ms: float) -> AskR
158165
rows=rows,
159166
columns=columns,
160167
row_count=row_count,
168+
truncated=truncated,
161169
caption=result.caption,
162170
output_format=fmt_name,
163171
error_kind=result.error_kind.value if result.error_kind else None,
@@ -277,32 +285,37 @@ def create_app() -> FastAPI:
277285
settings = get_settings()
278286
rate_limiter = _TokenBucket(max_req=60, window_s=60)
279287

280-
api_key_env = "" # `NL_SQL_API_KEY` via env, optional
281-
import os
282-
283-
api_key_env = os.environ.get("NL_SQL_API_KEY", "")
288+
# Read from Settings (honours .env), not os.environ directly.
289+
api_key_env = settings.api_key
284290

285291
async def require_api_key(
286292
request: Request,
287293
x_api_key: str | None = Header(default=None, alias="X-API-Key"),
288294
) -> str:
289-
if not api_key_env:
290-
# Auth off entirely when no key is configured — useful for local
291-
# eval drivers and the Streamlit UI bootstrapping side-by-side.
292-
return "anonymous"
293-
if x_api_key != api_key_env:
295+
# 1. Auth — only enforced when a key is configured. Constant-time compare
296+
# so a timing side-channel can't leak the key byte by byte (the
297+
# `and` short-circuits, so compare_digest only runs when a key is set).
298+
if api_key_env and (
299+
x_api_key is None or not secrets.compare_digest(x_api_key, api_key_env)
300+
):
294301
raise HTTPException(
295302
status_code=status.HTTP_401_UNAUTHORIZED,
296303
detail="missing or invalid X-API-Key header",
297304
)
298-
ok, retry_after = rate_limiter.check(x_api_key)
305+
306+
# 2. Rate limit — ALWAYS on, even with no key. A keyless public deploy is
307+
# otherwise unthrottled (the README promises 60 req/min). Bucket by key
308+
# when present, else by client IP.
309+
client_host = request.client.host if request.client else "unknown"
310+
bucket_key = x_api_key or client_host
311+
ok, retry_after = rate_limiter.check(bucket_key)
299312
if not ok:
300313
raise HTTPException(
301314
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
302315
detail=f"rate limit exceeded; retry in {retry_after}s",
303316
headers={"Retry-After": str(retry_after)},
304317
)
305-
return x_api_key
318+
return x_api_key or "anonymous"
306319

307320
# --------------------------------------------------------- health / ready
308321

@@ -394,10 +407,15 @@ def ask(
394407
dialect=spec.dialect,
395408
verify_retry_on_empty=True,
396409
)
397-
except Exception as exc: # pragma: no cover — defensive
410+
except Exception as exc:
411+
# Never leak exception text (paths, driver internals, provider
412+
# payloads) to the client. Log the detail server-side under a
413+
# trace_id the caller can quote in a bug report.
414+
trace_id = str(uuid.uuid4())
415+
logger.exception("pipeline crashed [trace_id=%s]", trace_id)
398416
raise HTTPException(
399417
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
400-
detail=f"pipeline crashed: {type(exc).__name__}: {exc}",
418+
detail=f"internal pipeline error (trace_id={trace_id})",
401419
) from exc
402420
latency_ms = (time.perf_counter() - t0) * 1000.0
403421
return _result_to_response(result, latency_ms=latency_ms)

‎src/nl_sql/config/settings.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,12 @@ class Settings(BaseSettings):
7373
groq_api_key: str = Field(default="", validation_alias="GROQ_API_KEY")
7474
openrouter_api_key: str = Field(default="", validation_alias="OPENROUTER_API_KEY")
7575

76+
# Optional API auth for the FastAPI surface. When empty, /ask and /databases
77+
# are open — but the rate limiter still applies (keyed by client IP), so a
78+
# keyless public deploy is not unthrottled. Read here (not os.environ) so a
79+
# value in .env is honoured, per the api/main module docstring.
80+
api_key: str = Field(default="", validation_alias="NL_SQL_API_KEY")
81+
7682
# diskcache for LLM generate/embed responses (per docs/02_architecture_v2.md §6.5).
7783
# Two subdirs ("gen", "embed") are created under this root by `nl_sql.llm.cache`.
7884
llm_cache_dir: str = ".cache/llm"

‎tests/api/test_api_routes_mocked.py‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -318,3 +318,67 @@ def test_rate_limit_kicks_in_after_max_req(monkeypatch: pytest.MonkeyPatch) -> N
318318
assert r.status_code == 429
319319
assert "rate limit" in r.json()["detail"]
320320
assert r.headers.get("Retry-After") is not None
321+
322+
323+
def test_rate_limit_applies_to_anonymous_requests(monkeypatch: pytest.MonkeyPatch) -> None:
324+
"""No API key configured → auth is off, but the limiter still throttles by IP.
325+
326+
This is the B1 regression: previously require_api_key returned "anonymous"
327+
before ever calling the limiter, so a keyless public deploy had no limit.
328+
"""
329+
monkeypatch.delenv("NL_SQL_API_KEY", raising=False)
330+
app = create_app()
331+
app.dependency_overrides[get_singletons] = lambda: _make_fake_singletons()
332+
client = TestClient(app)
333+
334+
for _ in range(60):
335+
r = client.get("/databases")
336+
assert r.status_code == 200, r.json()
337+
338+
r = client.get("/databases")
339+
assert r.status_code == 429
340+
assert r.headers.get("Retry-After") is not None
341+
342+
343+
def test_wrong_api_key_is_rejected(monkeypatch: pytest.MonkeyPatch) -> None:
344+
"""A present-but-wrong key → 401 (exercises the constant-time compare path)."""
345+
monkeypatch.setenv("NL_SQL_API_KEY", "correct-secret")
346+
app = create_app()
347+
app.dependency_overrides[get_singletons] = lambda: _make_fake_singletons()
348+
r = TestClient(app).get("/databases", headers={"X-API-Key": "wrong-secret"})
349+
assert r.status_code == 401
350+
351+
352+
def test_ask_response_exposes_truncated_flag(client_with_fakes: TestClient) -> None:
353+
"""B3: the client can tell a full result from a row-capped one."""
354+
result = _make_pipeline_result()
355+
assert result.outcome is not None
356+
assert result.outcome.result is not None
357+
truncated_result = QueryResult(
358+
rows=result.outcome.result.rows,
359+
columns=result.outcome.result.columns,
360+
row_count=result.outcome.result.row_count,
361+
truncated=True,
362+
elapsed_ms=1.0,
363+
)
364+
result.outcome = ExecutionOutcome(
365+
sql=result.outcome.sql,
366+
validation=result.outcome.validation,
367+
result=truncated_result,
368+
)
369+
with patch("nl_sql.api.main.run_pipeline", return_value=result):
370+
r = client_with_fakes.post("/ask", json={"question": "q", "db_id": "chinook"})
371+
assert r.status_code == 200
372+
assert r.json()["truncated"] is True
373+
374+
375+
def test_ask_500_is_redacted_with_trace_id(client_with_fakes: TestClient) -> None:
376+
"""B2: a pipeline crash returns a generic message + trace_id, not the exc text."""
377+
secret_detail = "psycopg.OperationalError: password=hunter2 at /srv/secret/path"
378+
with patch("nl_sql.api.main.run_pipeline", side_effect=RuntimeError(secret_detail)):
379+
r = client_with_fakes.post("/ask", json={"question": "q", "db_id": "chinook"})
380+
assert r.status_code == 500
381+
detail = r.json()["detail"]
382+
assert "hunter2" not in detail
383+
assert "/srv/secret/path" not in detail
384+
assert "trace_id=" in detail

0 commit comments

Comments
 (0)