Metadata-Version: 2.4
Name: fastapi-openbi
Version: 1.0.0
Summary: Embeddable, Secure, Self-Contained BI Dashboard Engine for FastAPI
Author: OpenBI Team
Project-URL: Homepage, https://github.com/open-bi/fastapi-openbi
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: FastAPI
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.95.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: uvicorn>=0.20.0

# fastapi-openbi

> 🚀 **Self-Contained, Enterprise-Grade, Zero-Leakage BI Dashboard Engine for FastAPI.**

`fastapi-openbi` is a lightweight, drop-in Python library for FastAPI that lets you build, manage, and embed interactive analytical dashboards (Charts, KPI Cards, Drill-Downs, Multi-Tab pages) with **zero database credentials or raw SQL exposed to clients**.

---

## 🔒 Core Security Highlights

1. **Zero DB Credential Leakage**: Database URLs are stored exclusively on the server and encrypted with **AES-256-GCM**.
2. **Zero SQL Exposed**: Client browsers and frontend routes only receive and send opaque `queryId` identifiers.
3. **Anti-IDOR Protection**: Requests are cryptographically authorized via **Scoped Dashboard Access Tokens** stored in the database.
4. **1-Click Kill Switch**: Admins can revoke or regenerate client access tokens in real-time.
5. **Swagger / OpenAPI Encapsulation**: All internal OpenBI routes are hidden from `/docs` and `/redoc` (`include_in_schema=False`).
6. **DoS & Pool Protection**: Includes an in-memory **LRU Query Result Cache** (0.1ms responses), dedicated sub-pool, and a hard 3-second `statement_timeout`.

---

## 📦 Installation

```bash
pip install ./packages/python-sdk
# Or install dependencies:
pip install fastapi psycopg2-binary cryptography uvicorn
```

---

## ⚡ 1-Minute Quick Start (FastAPI)

```python
import os
from fastapi import FastAPI
from open_bi import create_bi_router, BIEngineConfig

app = FastAPI(title="My Enterprise SaaS Application")

# 1. Configure the OpenBI Engine
bi_config = BIEngineConfig(
    primary_db_url=os.getenv("DATABASE_URL", "postgresql://postgres:pass@localhost:5432/my_db"),
    admin_password=os.getenv("BI_ADMIN_PASSWORD", "super_secret_admin_key"),
    encryption_key=os.getenv("BI_ENCRYPTION_KEY", "vault_secret_32_bytes_long!"),
    include_in_schema=False,  # Hides all BI routes from public /docs
    query_timeout_ms=3000,    # Kills any query taking > 3 seconds
    cache_ttl_seconds=30      # In-memory query result cache
)

# 2. Mount the OpenBI Router (1 line of code)
app.include_router(create_bi_router(bi_config), prefix="/api/bi")

# Your normal application routes:
@app.get("/")
def index():
    return {"status": "running"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

---

## 🛠️ How It Works (Two-State Architecture)

### 1. Admin Studio Workflow (Creator Mode)
- Admin logs in with `BI_ADMIN_PASSWORD` (sent via `X-BI-Admin-Key` header).
- Admin can connect to databases, inspect schemas, write SQL queries, and configure charts.
- The engine auto-generates a unique `access_token` (e.g. `emb_live_8f9a2b7c4d1e...`) for the dashboard and saves the configuration in the primary database.

### 2. Client Viewer Workflow (End-User Mode)
- The client frontend route calls:
  `GET /api/bi/public/dashboards/{dashboard_id}` (Header: `X-Dashboard-Token: emb_live_...`)
  `POST /api/bi/public/query/execute` (Header: `X-Dashboard-Token: emb_live_...`, Body: `{ "queryId": "q_123" }`)
- **What happens on the server**:
  1. Verifies the token against the database record.
  2. Verifies `q_123` belongs to this dashboard (Anti-IDOR).
  3. Checks the in-memory LRU cache.
  4. Runs the SQL query on the backend and returns **pure JSON data rows** to the browser.
- **Client DevTools Inspector**: Sees **zero DB strings, zero passwords, and zero SQL queries**.

---

## 🧪 Testing

Run the automated security test suite:
```bash
python packages/python-sdk/tests/test_openbi.py
```
*(All 9 security and functional tests verify AES-256 encryption, Anti-IDOR enforcement, SQL Guard, Token verification, and payload sanitization).*
