filingstudio-proxy 0.2.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,6 @@
+filingstudio_proxy/__init__.py,sha256=tZBkz0nFK8HkmWx_4qaOn_pUDtBYoFZY3ARw-R901m4,439
+filingstudio_proxy/router.py,sha256=17nDT1pKIU6gEMmXT9W8fExjzWX_SWXNLPkV5eXdRH8,11949
+filingstudio_proxy-0.2.0.dist-info/METADATA,sha256=M6anuvXpB198ULBkpyI9kmrJnHxAJZsCU3W2qs1OjEA,4019
+filingstudio_proxy-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+filingstudio_proxy-0.2.0.dist-info/licenses/LICENSE,sha256=0N9MXUpOueb0VCrG2YJoMksp8VFEVrsgbeIsEKm00RU,1070
+filingstudio_proxy-0.2.0.dist-info/RECORD,,

filingstudio_proxy-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

filingstudio_proxy-0.2.0.dist-info/licenses/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.