filingstudio-proxy 0.2.0__tar.gz

filingstudio_proxy-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+packages/proxy-python/dist/
+*.egg-info/

filingstudio_proxy-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filing Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

filingstudio_proxy-0.2.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: filingstudio-proxy
+Version: 0.2.0
+Summary: Server-side proxy for Filing Studio: hold the API key on your FastAPI server; the browser talks only to your route.
+Project-URL: Homepage, https://filingstudio.com
+Project-URL: Documentation, https://filingstudio.com/docs#sdk
+Author-email: Filing Studio <support@filingstudio.com>
+License: MIT
+License-File: LICENSE
+Keywords: citations,edgar,fastapi,filings,finance,provenance,proxy,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.100
+Requires-Dist: httpx>=0.24
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# filingstudio-proxy
+
+Server-side proxy for [Filing Studio](https://filingstudio.com) on FastAPI.
+Your API key stays on your server; the browser talks only to your route.
+This is the Python twin of `@filingstudio/proxy` (Next.js and Express), with
+the same contract, so `@filingstudio/react` works unchanged in front of it.
+
+```bash
+pip install filingstudio-proxy
+```
+
+```python
+import os
+from fastapi import FastAPI
+from filingstudio_proxy import filing_studio_router
+
+app = FastAPI()
+app.include_router(
+    filing_studio_router(api_key=os.environ["FILING_STUDIO_API_KEY"]),
+    prefix="/api/filings",
+)
+```
+
+Then in the browser: `<ProvenanceProvider proxy="/api/filings">`.
+
+## Public demo? Cap each visitor
+
+```python
+filing_studio_router(api_key=key, budget=40)   # 40 metered requests per visitor per day
+```
+
+Over budget the route answers `429` with an honest note the drawer shows
+("Daily demo limit reached… This says nothing about what the filings
+contain"), never a fake "not found". Coverage checks are never metered, and
+cached answers are served before the meter, so reopening a receipt is free.
+
+Meter on your own login instead of the visitor IP:
+
+```python
+filing_studio_router(
+    api_key=key,
+    budget=100,
+    visitor_key=lambda req: req.state.user_id,
+    limit_for=lambda req: req.state.daily_limit,   # optional per-user quota
+)
+```
+
+## What it guarantees
+
+- Only `GET` and `POST`, only to an allowlist of `/v1` read paths. Dot
+  segments and backslashes are refused before allowlisting.
+- Nothing from the browser request is forwarded except the `/v1` path, its
+  query string, and a POST body (capped at 64 KB).
+- Successful `GET`s are cached in-process (one hour by default) and served
+  before the meter. Errors are never cached.
+- The reply carries `X-FS-Demo-Remaining` when metered; the React SDK's
+  `onLimit` reads it.
+- A missing key answers `503`; an unreachable upstream answers `502`. Neither
+  message can contain the key.
+
+## Options
+
+| option | default | meaning |
+|---|---|---|
+| `api_key` | required | your `fsk_…` key, server-side only |
+| `base_url` | `https://api.filingstudio.com` | upstream base |
+| `allow` | search, trace, traces, verify, coverage, filings, tables | allowed `/v1` prefixes |
+| `cache_ttl_s` | `3600` | GET cache TTL; `0` disables |
+| `budget` | `None` | per-visitor daily cap (int) or a shared `Budget` |
+| `visitor_key` | client IP, cookie fallback | who a request is charged to |
+| `limit_for` | `None` | per-request quota override |
+| `timeout_s` | `30` | upstream timeout |
+| `transport` | `None` | an `httpx` transport, for tests |
+
+## Develop
+
+```bash
+pip install -e .[test]
+pytest
+```
+
+MIT

filingstudio_proxy-0.2.0/README.md

@@ -0,0 +1,82 @@
+# filingstudio-proxy
+
+Server-side proxy for [Filing Studio](https://filingstudio.com) on FastAPI.
+Your API key stays on your server; the browser talks only to your route.
+This is the Python twin of `@filingstudio/proxy` (Next.js and Express), with
+the same contract, so `@filingstudio/react` works unchanged in front of it.
+
+```bash
+pip install filingstudio-proxy
+```
+
+```python
+import os
+from fastapi import FastAPI
+from filingstudio_proxy import filing_studio_router
+
+app = FastAPI()
+app.include_router(
+    filing_studio_router(api_key=os.environ["FILING_STUDIO_API_KEY"]),
+    prefix="/api/filings",
+)
+```
+
+Then in the browser: `<ProvenanceProvider proxy="/api/filings">`.
+
+## Public demo? Cap each visitor
+
+```python
+filing_studio_router(api_key=key, budget=40)   # 40 metered requests per visitor per day
+```
+
+Over budget the route answers `429` with an honest note the drawer shows
+("Daily demo limit reached… This says nothing about what the filings
+contain"), never a fake "not found". Coverage checks are never metered, and
+cached answers are served before the meter, so reopening a receipt is free.
+
+Meter on your own login instead of the visitor IP:
+
+```python
+filing_studio_router(
+    api_key=key,
+    budget=100,
+    visitor_key=lambda req: req.state.user_id,
+    limit_for=lambda req: req.state.daily_limit,   # optional per-user quota
+)
+```
+
+## What it guarantees
+
+- Only `GET` and `POST`, only to an allowlist of `/v1` read paths. Dot
+  segments and backslashes are refused before allowlisting.
+- Nothing from the browser request is forwarded except the `/v1` path, its
+  query string, and a POST body (capped at 64 KB).
+- Successful `GET`s are cached in-process (one hour by default) and served
+  before the meter. Errors are never cached.
+- The reply carries `X-FS-Demo-Remaining` when metered; the React SDK's
+  `onLimit` reads it.
+- A missing key answers `503`; an unreachable upstream answers `502`. Neither
+  message can contain the key.
+
+## Options
+
+| option | default | meaning |
+|---|---|---|
+| `api_key` | required | your `fsk_…` key, server-side only |
+| `base_url` | `https://api.filingstudio.com` | upstream base |
+| `allow` | search, trace, traces, verify, coverage, filings, tables | allowed `/v1` prefixes |
+| `cache_ttl_s` | `3600` | GET cache TTL; `0` disables |
+| `budget` | `None` | per-visitor daily cap (int) or a shared `Budget` |
+| `visitor_key` | client IP, cookie fallback | who a request is charged to |
+| `limit_for` | `None` | per-request quota override |
+| `timeout_s` | `30` | upstream timeout |
+| `transport` | `None` | an `httpx` transport, for tests |
+
+## Develop
+
+```bash
+pip install -e .[test]
+pytest
+```
+
+MIT

filingstudio_proxy-0.2.0/filingstudio_proxy/__init__.py

@@ -0,0 +1,22 @@
+"""Server-side proxy for Filing Studio. Hold the API key on your FastAPI
+server; the browser talks only to your route."""
+
+from .router import (
+    DEFAULT_ALLOW,
+    MAX_BODY_BYTES,
+    REMAINING_HEADER,
+    Budget,
+    filing_studio_router,
+    v1_tail,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "Budget",
+    "DEFAULT_ALLOW",
+    "MAX_BODY_BYTES",
+    "REMAINING_HEADER",
+    "__version__",
+    "filing_studio_router",
+    "v1_tail",
+]

filingstudio_proxy-0.2.0/filingstudio_proxy/router.py

@@ -0,0 +1,313 @@
+"""
+The key-holding proxy for FastAPI, behaviour for behaviour with the
+TypeScript @filingstudio/proxy. Mount it under the prefix your
+<ProvenanceProvider proxy="..."> points at; the browser only ever talks to
+your server, and the API key never leaves it.
+
+    from filingstudio_proxy import filing_studio_router
+    app.include_router(
+        filing_studio_router(api_key=os.environ["FILING_STUDIO_API_KEY"]),
+        prefix="/api/filings",
+    )
+
+Rules, all enforced here:
+  * only GET and POST are forwarded, only to an allowlist of /v1 prefixes;
+    dot segments and backslashes in the path are refused before allowlisting;
+  * nothing from the browser's request reaches upstream except the /v1 path,
+    its query string, and a POST body (capped at 64 KB);
+  * successful GETs are cached in-process and served BEFORE the meter, so
+    reopening a receipt costs no quota and is never refused once quota is
+    spent; errors are never cached;
+  * an optional per-visitor daily budget (client IP first, cookie fallback)
+    answers 429 with an honest indexState note, never a fake "not found";
+    coverage is exempt because it decides whether to offer View-source at all;
+  * a missing key answers 503 and an unreachable upstream answers 502, and
+    neither message can ever contain the key.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+import time
+from datetime import date
+from typing import Callable, Iterable, Optional, Tuple, Union
+from urllib.parse import quote, unquote
+
+import httpx
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse
+
+DEFAULT_BASE = "https://api.filingstudio.com"
+DEFAULT_ALLOW: Tuple[str, ...] = (
+    "v1/search",
+    "v1/trace",
+    "v1/traces",
+    "v1/verify",
+    "v1/coverage",
+    "v1/filings",
+    "v1/tables",
+)
+METER_EXEMPT: Tuple[str, ...] = ("v1/coverage",)
+MAX_BODY_BYTES = 64 * 1024
+MAX_ENTRIES = 5000
+REMAINING_HEADER = "X-FS-Demo-Remaining"
+VISITOR_COOKIE = "fs_visitor"
+LIMIT_NOTE = (
+    "Daily demo limit reached — try again tomorrow. "
+    "This says nothing about what the filings contain."
+)
+
+
+def v1_tail(path: str) -> Optional[str]:
+    """The `v1/…` tail of a request path, decoded, or None when it is not a
+    /v1 path or carries anything that could re-route the upstream request."""
+    at = path.find("/v1/")
+    if at < 0:
+        return None
+    tail = unquote(path[at + 1 :])
+    if "\\" in tail:
+        return None
+    if any(seg in (".", "..") for seg in tail.split("/")):
+        return None
+    return tail
+
+
+def _matches(tail: str, prefixes: Iterable[str]) -> bool:
+    return any(tail == p or tail.startswith(p + "/") for p in prefixes)
+
+
+class Budget:
+    """A per-visitor daily budget. `spend(key, limit)` charges one request and
+    returns (allowed, remaining_today). Bounded: oldest keys are dropped past
+    MAX_ENTRIES."""
+
+    def __init__(self, per_visitor_daily: int) -> None:
+        self.per_visitor_daily = int(per_visitor_daily)
+        self._store: "dict[str, tuple[str, int]]" = {}
+        self._lock = threading.Lock()
+
+    def spend(self, key: str, limit: Optional[int] = None) -> Tuple[bool, int]:
+        lim = self.per_visitor_daily if limit is None else int(limit)
+        today = date.today().isoformat()
+        with self._lock:
+            day, used = self._store.get(key, (today, 0))
+            if day != today:
+                used = 0
+            if used >= lim:
+                self._store[key] = (today, used)
+                return False, 0
+            used += 1
+            self._store[key] = (today, used)
+            while len(self._store) > MAX_ENTRIES:
+                self._store.pop(next(iter(self._store)))
+            return True, lim - used
+
+
+class _Cache:
+    def __init__(self, ttl_s: float) -> None:
+        self.ttl = float(ttl_s)
+        self._store: "dict[str, tuple[float, int, bytes]]" = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[Tuple[int, bytes]]:
+        if self.ttl <= 0:
+            return None
+        with self._lock:
+            hit = self._store.get(key)
+            if not hit:
+                return None
+            at, status, body = hit
+            if time.time() - at > self.ttl:
+                self._store.pop(key, None)
+                return None
+            return status, body
+
+    def put(self, key: str, status: int, body: bytes) -> None:
+        if self.ttl <= 0:
+            return
+        with self._lock:
+            self._store[key] = (time.time(), status, body)
+            while len(self._store) > MAX_ENTRIES:
+                self._store.pop(next(iter(self._store)))
+
+
+def _client_ip(request: Request) -> str:
+    xff = request.headers.get("x-forwarded-for") or ""
+    first = xff.split(",")[0].strip()
+    if first:
+        return first
+    real = (request.headers.get("x-real-ip") or "").strip()
+    if real:
+        return real
+    return (request.client.host if request.client else "") or ""
+
+
+def _default_visitor(request: Request, response: Response) -> str:
+    """The IP is the meter. The cookie only stands in when no IP is known,
+    so a visitor cannot reset their budget by clearing it."""
+    ip = _client_ip(request)
+    if ip:
+        return ip
+    cookie = request.cookies.get(VISITOR_COOKIE)
+    if cookie:
+        return cookie
+    cookie = secrets.token_urlsafe(16)
+    secure = request.url.scheme == "https" or request.headers.get("x-forwarded-proto") == "https"
+    response.set_cookie(
+        VISITOR_COOKIE, cookie, max_age=365 * 24 * 3600,
+        httponly=True, samesite="lax", secure=secure,
+    )
+    return cookie
+
+
+def _json_bytes(obj: dict) -> bytes:
+    return json.dumps(obj).encode()
+
+
+def filing_studio_router(
+    api_key: Optional[str],
+    *,
+    base_url: Optional[str] = None,
+    allow: Iterable[str] = DEFAULT_ALLOW,
+    cache_ttl_s: float = 3600.0,
+    budget: Union[Budget, int, None] = None,
+    visitor_key: Optional[Callable[[Request], str]] = None,
+    limit_for: Optional[Callable[[Request], Optional[int]]] = None,
+    timeout_s: float = 30.0,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+) -> APIRouter:
+    """Build the router.
+
+    api_key      your Filing Studio key (fsk_…). Server-side only.
+    base_url     upstream base; default https://api.filingstudio.com.
+    allow        allowed /v1 prefixes; defaults cover everything the SDK calls.
+    cache_ttl_s  GET cache TTL in seconds; 0 disables.
+    budget       per-visitor daily cap: an int, or a Budget to share one meter.
+    visitor_key  who a request is charged to (default: client IP, cookie
+                 fallback). Return your own login id to meter per user.
+    limit_for    a per-request quota override (e.g. a per-client limit).
+    timeout_s    upstream timeout.
+    transport    an httpx transport, for tests (httpx.MockTransport).
+    """
+    key = (api_key or "").strip()
+    base = (base_url or DEFAULT_BASE).rstrip("/")
+    allowed = tuple(allow)
+    meter = Budget(budget) if isinstance(budget, int) else budget
+    cache = _Cache(cache_ttl_s)
+    router = APIRouter()
+
+    def reply(status: int, obj: dict, headers: Optional[dict] = None) -> JSONResponse:
+        return JSONResponse(obj, status_code=status, headers=headers or {})
+
+    async def handle(request: Request, path: str) -> Response:
+        method = request.method.upper()
+        if method not in ("GET", "POST"):
+            return reply(405, {"error": f"Method not allowed: {method}"}, {"Allow": "GET, POST"})
+        tail = v1_tail("/" + path)
+        if tail is None:
+            return reply(404, {"error": "Not a /v1 path"})
+        if not _matches(tail, allowed):
+            return reply(403, {"error": f"Path not allowed through this proxy: {tail}"})
+        if not key:
+            return reply(
+                503,
+                {
+                    "error": {
+                        "code": "not_configured",
+                        "message": "Filing evidence is not configured on this server.",
+                    },
+                    "indexState": {
+                        "coverage": "unavailable",
+                        "note": "The evidence service is not configured. "
+                                "This says nothing about what the filings contain.",
+                    },
+                },
+            )
+
+        body: Optional[bytes] = None
+        if method == "POST":
+            declared = int(request.headers.get("content-length") or 0)
+            if declared > MAX_BODY_BYTES:
+                return reply(413, {"error": "Request body too large"})
+            body = await request.body()
+            if len(body) > MAX_BODY_BYTES:
+                return reply(413, {"error": "Request body too large"})
+
+        query = request.url.query
+        upstream = f"{base}/{quote(tail, safe='/')}" + (f"?{query}" if query else "")
+        cache_key = upstream if method == "GET" else None
+
+        # A cached answer is free: serve it before the meter runs, so reopening
+        # the same receipt never spends (or is refused for lack of) quota.
+        if cache_key:
+            hit = cache.get(cache_key)
+            if hit:
+                return Response(content=hit[1], status_code=hit[0], media_type="application/json")
+
+        headers: "dict[str, str]" = {}
+        if meter is not None and not _matches(tail, METER_EXEMPT):
+            cookie_carrier = Response()
+            who = visitor_key(request) if visitor_key else _default_visitor(request, cookie_carrier)
+            limit = limit_for(request) if limit_for else None
+            ok, remaining = meter.spend(f"{who}|{date.today().isoformat()}", limit)
+            headers[REMAINING_HEADER] = str(remaining)
+            set_cookie = cookie_carrier.headers.get("set-cookie")
+            if set_cookie:
+                headers["Set-Cookie"] = set_cookie
+            if not ok:
+                return reply(
+                    429,
+                    {
+                        "error": "Daily demo limit reached.",
+                        "indexState": {"coverage": "unavailable", "note": LIMIT_NOTE},
+                    },
+                    headers,
+                )
+
+        up_headers = {"X-API-Key": key}
+        if method == "POST":
+            up_headers["Content-Type"] = "application/json"
+        try:
+            async with httpx.AsyncClient(timeout=timeout_s, transport=transport) as client:
+                res = await client.request(method, upstream, headers=up_headers, content=body)
+        except httpx.HTTPError as exc:
+            # Only the exception's class name: httpx messages can echo the URL.
+            return reply(
+                502,
+                {
+                    "error": {
+                        "code": "upstream_unreachable",
+                        "message": f"Filing Studio could not be reached ({type(exc).__name__}).",
+                    },
+                    "indexState": {
+                        "coverage": "unavailable",
+                        "note": "The evidence service could not be reached. "
+                                "This says nothing about what the filings contain.",
+                    },
+                },
+                headers,
+            )
+
+        content = res.content
+        try:
+            json.loads(content)
+        except ValueError:
+            content = _json_bytes({"error": "Upstream returned a non-JSON response"})
+        if cache_key and res.is_success:
+            cache.put(cache_key, res.status_code, content)
+        return Response(
+            content=content, status_code=res.status_code,
+            media_type="application/json", headers=headers,
+        )
+
+    @router.api_route(
+        "/v1/{path:path}",
+        methods=["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"],
+        include_in_schema=False,
+    )
+    async def v1(path: str, request: Request) -> Response:
+        return await handle(request, "v1/" + path)
+
+    return router

filingstudio_proxy-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "filingstudio-proxy"
+version = "0.2.0"
+description = "Server-side proxy for Filing Studio: hold the API key on your FastAPI server; the browser talks only to your route."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Filing Studio", email = "support@filingstudio.com" }]
+requires-python = ">=3.9"
+dependencies = ["fastapi>=0.100", "httpx>=0.24"]
+keywords = ["sec", "filings", "citations", "provenance", "fastapi", "proxy", "finance", "edgar"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://filingstudio.com"
+Documentation = "https://filingstudio.com/docs#sdk"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["filingstudio_proxy"]
+
+[tool.hatch.build.targets.sdist]
+include = ["filingstudio_proxy", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

filingstudio_proxy-0.2.0/tests/test_router.py

@@ -0,0 +1,180 @@
+import httpx
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from filingstudio_proxy import Budget, filing_studio_router, v1_tail, REMAINING_HEADER
+
+
+def ok(req: httpx.Request) -> httpx.Response:
+    return httpx.Response(200, json={"data": {"ok": True, "path": req.url.path, "q": req.url.query.decode()}})
+
+
+def make(handler=ok, **kw):
+    seen = []
+
+    def h(req: httpx.Request) -> httpx.Response:
+        seen.append(req)
+        return handler(req)
+
+    app = FastAPI()
+    app.include_router(
+        filing_studio_router(transport=httpx.MockTransport(h), **kw),
+        prefix="/api/filings",
+    )
+    return TestClient(app), seen
+
+
+IP = {"x-forwarded-for": "203.0.113.7"}
+
+
+def test_v1_tail_decodes_before_checking_dot_segments():
+    assert v1_tail("/api/filings/v1/trace/abc") == "v1/trace/abc"
+    assert v1_tail("/api/filings/v1/trace/%2e%2e/x") is None
+    assert v1_tail("/api/filings/v1/a\\b") is None
+    assert v1_tail("/api/filings/nope") is None
+
+
+def test_rejects_traversal_and_non_allowlisted_paths_without_calling_upstream():
+    c, seen = make(api_key="k")
+    assert c.get("/api/filings/v1/search/%2e%2e/%2e%2e/admin").status_code == 404
+    assert c.get("/api/filings/v1/admin").status_code == 403
+    assert c.get("/api/filings/v1/searchX").status_code == 403
+    assert seen == []
+
+
+def test_missing_key_answers_503_with_an_honest_index_state():
+    c, seen = make(api_key=None)
+    r = c.get("/api/filings/v1/trace/T")
+    assert r.status_code == 503
+    assert r.json()["indexState"]["coverage"] == "unavailable"
+    assert seen == []
+
+
+def test_forwards_key_and_path_only_never_browser_headers():
+    c, seen = make(api_key="secret")
+    r = c.get(
+        "/api/filings/v1/search?ticker=NVDA&q=revenue",
+        headers={"cookie": "session=abc", "authorization": "Bearer x", **IP},
+    )
+    assert r.status_code == 200
+    up = seen[0]
+    assert up.headers["x-api-key"] == "secret"
+    assert "cookie" not in up.headers
+    assert "authorization" not in up.headers
+    assert str(up.url) == "https://api.filingstudio.com/v1/search?ticker=NVDA&q=revenue"
+
+
+def test_coverage_is_never_metered():
+    c, seen = make(api_key="k", budget=1)
+    assert c.get("/api/filings/v1/trace/T1", headers=IP).status_code == 200
+    for i in range(3):
+        r = c.get(f"/api/filings/v1/coverage?ticker=NVDA&i={i}", headers=IP)
+        assert r.status_code == 200
+        assert REMAINING_HEADER not in r.headers
+    assert len(seen) == 4
+
+
+def test_cache_is_served_before_the_meter_and_never_charged():
+    c, seen = make(api_key="k", budget=1)
+    first = c.get("/api/filings/v1/trace/T1?include=context", headers=IP)
+    assert first.status_code == 200
+    assert first.headers[REMAINING_HEADER] == "0"
+
+    again = c.get("/api/filings/v1/trace/T1?include=context", headers=IP)
+    assert again.status_code == 200
+    assert again.json() == first.json()
+    assert len(seen) == 1
+
+    other = c.get("/api/filings/v1/trace/T2?include=context", headers=IP)
+    assert other.status_code == 429
+    body = other.json()
+    assert body["indexState"]["coverage"] == "unavailable"
+    assert "limit" in body["indexState"]["note"].lower()
+    assert other.headers[REMAINING_HEADER] == "0"
+    assert len(seen) == 1
+
+
+def test_meters_on_ip_so_a_new_cookie_does_not_reset_the_budget():
+    c, _ = make(api_key="k", budget=1)
+    assert c.get("/api/filings/v1/trace/A", headers={**IP, "cookie": "fs_visitor=one"}).status_code == 200
+    assert c.get("/api/filings/v1/trace/B", headers={**IP, "cookie": "fs_visitor=two"}).status_code == 429
+    assert c.get("/api/filings/v1/trace/C", headers={"x-forwarded-for": "198.51.100.9"}).status_code == 200
+
+
+def test_visitor_key_and_limit_for_hooks_meter_on_the_hosts_login():
+    def who(request):
+        return request.headers.get("x-user", "anon")
+
+    def limit(request):
+        return 2 if request.headers.get("x-user") == "pro" else 1
+
+    c, _ = make(api_key="k", budget=Budget(99), visitor_key=who, limit_for=limit)
+    # distinct paths per user: a cached answer is served before the meter
+    assert c.get("/api/filings/v1/trace/F1", headers={"x-user": "free"}).status_code == 200
+    assert c.get("/api/filings/v1/trace/F2", headers={"x-user": "free"}).status_code == 429
+    assert c.get("/api/filings/v1/trace/P1", headers={"x-user": "pro"}).status_code == 200
+    assert c.get("/api/filings/v1/trace/P2", headers={"x-user": "pro"}).status_code == 200
+    assert c.get("/api/filings/v1/trace/P3", headers={"x-user": "pro"}).status_code == 429
+    # and the free user can still reopen what is already cached
+    assert c.get("/api/filings/v1/trace/F1", headers={"x-user": "free"}).status_code == 200
+
+
+def test_post_body_cap_and_method_refusal():
+    c, seen = make(api_key="k")
+    big = "x" * (64 * 1024 + 1)
+    assert c.post("/api/filings/v1/verify", content=big).status_code == 413
+    r = c.put("/api/filings/v1/verify", content="{}")
+    assert r.status_code == 405
+    assert r.headers["allow"] == "GET, POST"
+    assert seen == []
+
+
+def test_post_forwards_json_body_with_content_type():
+    c, seen = make(api_key="k")
+    r = c.post("/api/filings/v1/verify", json={"ticker": "NVDA", "metric": "Revenue", "value": 130497})
+    assert r.status_code == 200
+    assert seen[0].method == "POST"
+    assert seen[0].headers["content-type"] == "application/json"
+    assert b'"ticker": "NVDA"' in seen[0].content or b'"ticker":"NVDA"' in seen[0].content
+
+
+def test_upstream_error_is_502_and_never_leaks_the_key():
+    def boom(req):
+        raise httpx.ConnectError("no route to host")
+
+    c, _ = make(boom, api_key="secret-key-value")
+    r = c.get("/api/filings/v1/trace/T")
+    assert r.status_code == 502
+    assert "secret-key-value" not in r.text
+    assert r.json()["indexState"]["coverage"] == "unavailable"
+
+
+def test_non_json_upstream_becomes_a_json_error():
+    c, _ = make(lambda req: httpx.Response(200, text="<html>nope</html>"), api_key="k")
+    r = c.get("/api/filings/v1/trace/T")
+    assert r.status_code == 200
+    assert r.json()["error"].startswith("Upstream returned a non-JSON")
+
+
+def test_errors_are_never_cached():
+    n = {"i": 0}
+
+    def flaky(req):
+        n["i"] += 1
+        return httpx.Response(500, json={"error": "boom"}) if n["i"] == 1 else ok(req)
+
+    c, _ = make(flaky, api_key="k")
+    assert c.get("/api/filings/v1/trace/T").status_code == 500
+    assert c.get("/api/filings/v1/trace/T").status_code == 200
+    assert n["i"] == 2
+
+
+def test_budget_resets_per_key_and_reports_remaining():
+    b = Budget(3)
+    assert b.spend("a") == (True, 2)
+    assert b.spend("a") == (True, 1)
+    assert b.spend("a") == (True, 0)
+    assert b.spend("a") == (False, 0)
+    assert b.spend("b") == (True, 2)
+    assert b.spend("a", limit=5) == (True, 1)