tradesenseAi / docs /audit /api_inventory.md
Niranjan-Murugarasu024
feat: TradeSense AI Chairman Edition production release ready for Hugging Face Spaces
0125724
|
Raw History Blame Contribute Delete
7.38 kB
# TradeSense AI — API Endpoint Inventory & Contract Audit
**Module 00: Production Forensic Audit**
**Audit Timestamp:** 2026-10-05T12:20:00+05:30
**Status:** COMPLETE & VERIFIED
---
## 1. Executive Summary
The active FastAPI backend exposes **36 endpoints** across 9 functional routers.
- **Authenticated Endpoints**: 15 endpoints enforce JWT Bearer Token validation via `Security(get_current_user)` and RBAC checks (`require_role(...)`).
- **Public / Unauthenticated Endpoints**: 21 endpoints are accessible without credentials.
- **Contract Integrity**: Pydantic v2 schemas govern all request payloads and response models, enforcing strict data typing and validation errors (`422 Unprocessable Entity`).
---
## 2. Complete API Endpoint Inventory
| Method | Endpoint | Auth | RBAC Role | Request Schema | Response Schema | DB / Ext API | Caching / Rate Limit | Status |
|---|---|---|---|---|---|---|---|---|
| `GET` | `/` | None | Public | None | HTML | None / Local Disk | Static / None | **VERIFIED** |
| `GET` | `/health` | None | Public | None | `HealthStatusResponse` | SQLite / None | None | **VERIFIED** |
| `GET` | `/ready` | None | Public | None | `ReadinessResponse` | SQLite, Cache / None | None | **VERIFIED** |
| `GET` | `/startup` | None | Public | None | `StartupResponse` | Schema Check / None | None | **VERIFIED** |
| `GET` | `/metrics` | None | Public | None | Prometheus Text | In-Memory Counters | Real-time | **VERIFIED** |
| `POST` | `/api/v1/auth/login` | None | Public | Query: `username`, `password` | `TokenResponse` | Users Table / None | 5 failed lockout | **VERIFIED** |
| `POST` | `/api/v1/auth/logout` | JWT | Authenticated | None | `MessageResponse` | Revocation List | Token Blacklist | **VERIFIED** |
| `POST` | `/api/v1/auth/token` | JWT | Authenticated | None | `TokenResponse` | Users Table | None | **VERIFIED** |
| `GET` | `/api/v1/market/quote/{symbol}` | None | Public | Path: `symbol`, Query: `exchange` | `QuoteResponse` | Cache → yfinance | 5s In-Memory Cache | **VERIFIED** |
| `GET` | `/api/v1/market/chart/{symbol}` | None | Public | Path: `symbol`, Query: `timeframe` | `ChartResponse` (OHLCV) | Cache → yfinance | 60s Cache | **VERIFIED** |
| `GET` | `/api/v1/market/search` | None | Public | Query: `q` (min 1 char) | `List[SearchResult]` | In-memory Indian catalog | None / In-memory | **VERIFIED** |
| `GET` | `/api/v1/market/company_overview` | None | Public | None | `CompanyOverviewResponse` | Cache → Quotes | 30s Cache | **VERIFIED** |
| `GET` | `/api/v1/market/live_ticker` | None | Public | None | `LiveTickerResponse` | Cache → Quotes | 10s Cache | **VERIFIED** |
| `GET` | `/api/v1/market/context` | None | Public | None | `MarketContextResponse` | Macro indicators | 60s Cache | **VERIFIED** |
| `GET` | `/api/v1/market/options/{symbol}` | None | Public | Path: `symbol` | `OptionsSummaryResponse` | yfinance options chain | 30s Cache | **VERIFIED** |
| `GET` | `/api/v1/calendar/sessions` | None | Public | None | `SessionResponse` | NSE / BSE trading calendar | Static / None | **VERIFIED** |
| `GET` | `/api/v1/research/{ticker}` | None | Public | Path: `ticker` | `ResearchAnalysisResponse` | Master Quant Engine | Compute heavy / None | **RISK (P0)** |
| `POST` | `/api/v1/research/runs` | JWT | `RESEARCHER` | `ResearchRunSubmissionRequest` | `ResearchRunAccepted` | SQLite + Worker Queue | Rate Limited | **VERIFIED** |
| `GET` | `/api/v1/research/runs` | JWT | `VIEWER` | Query: `limit`, `offset` | `List[ResearchRunSummary]` | SQLite Runs Table | None | **VERIFIED** |
| `GET` | `/api/v1/research/runs/{run_id}` | JWT | `VIEWER` | Path: `run_id` | `ResearchRunDetail` | SQLite Runs Table | None | **VERIFIED** |
| `GET` | `/api/v1/research/runs/{run_id}/evidence_package` | JWT | `VIEWER` | Path: `run_id` | `EvidencePackageResponse` | Runs + Audit Table | None | **VERIFIED** |
| `POST` | `/api/v1/research/runs/{run_id}/reproduce` | JWT | `SENIOR_RESEARCHER` | Path: `run_id` | `ReproductionResult` | Runs + Quant Engine | None | **VERIFIED** |
| `GET` | `/api/v1/governance/decisions` | JWT | `VIEWER` | Query: `status` | `List[GovernanceDecision]` | Governance Table | None | **VERIFIED** |
| `POST` | `/api/v1/governance/decisions/{id}/reviews` | JWT | `SENIOR_RESEARCHER` | Query: `verdict`, `comments` | `ReviewResponse` | Governance Table | None | **VERIFIED** |
| `GET` | `/api/v1/governance/family_1_archive` | JWT | `AUDITOR` | None | `ArchiveResponse` | Archive Records | None | **VERIFIED** |
| `GET` | `/api/v1/audit/events` | JWT | `AUDITOR` | Query: `limit`, `offset` | `List[AuditEvent]` | Audit Ledger Table | None | **VERIFIED** |
| `GET` | `/api/v1/audit/verify` | JWT | `ADMIN` | None | `LedgerVerificationResult` | Audit Ledger Table | Computes SHA-256 chain | **VERIFIED** |
| `POST` | `/api/v1/organizations` | JWT | `ADMIN` | Query: `name` | `OrgResponse` | Organizations Table | None | **VERIFIED** |
| `GET` | `/api/v1/organizations` | JWT | `ADMIN` | None | `List[OrgResponse]` | Organizations Table | None | **VERIFIED** |
| `GET` | `/api/v1/tenants/usage` | JWT | `OPERATOR` | None | `TenantUsageResponse` | Tenant Quotas Table | None | **VERIFIED** |
| `GET` | `/api/v1/observability/metrics` | JWT | `OPERATOR` | None | `ObservabilitySnapshot` | Metrics Aggregator | Real-time | **VERIFIED** |
| `GET` | `/api/v1/screener` | None | Public | None | `ScreenerResponse` | Multi-stock stats | 60s Cache | **VERIFIED** |
| `GET` | `/api/v1/journal` | None | Public | None | `JournalResponse` | Prediction Journal | None | **VERIFIED** |
| `GET` | `/api/v1/statutory/costs` | None | Public | Query: `price`, `qty`, `turnover` | `StatutoryCostBreakdown` | Local Indian Tax Rules | Pure compute | **VERIFIED** |
| `GET` | `/api/v1/data/health` | None | Public | None | `DataHealthResponse` | Provider health pings | 15s Cache | **VERIFIED** |
| `GET` | `/api/v1/data/diagnostics` | None | Public | None | `DataDiagnosticsResponse` | Provider telemetry | None | **VERIFIED** |
---
## 3. Contract Discrepancies & API Hazards
### 3.1 Field Naming & Serialization Mismatches
1. **`last_price` Nullability in Search Results**:
- Schema: `/api/v1/market/search` returns `last_price: Optional[float] = None`.
- Frontend: `app.js` line 2395 expects a float or assigns `0`. Injects `₹0.00` into the Company Overview table for any searched stock that hasn't had an explicit `/quote` fetched yet.
2. **`change_pct` vs `change_percent`**:
- Backend `QuoteResponse` outputs `change_pct: float`.
- Legacy frontend snippets refer to `quote.change_percent`, causing undefined badges in un-updated UI cards.
### 3.2 Unauthenticated Denial of Service (DoS) Risk on `/api/v1/research/{ticker}`
- **Symptom**: `GET /api/v1/research/{ticker}` executes a full walk-forward backtest, conformal prediction interval generation, and risk falsification pipeline synchronously in the ASGI thread pool.
- **Root Cause**: The endpoint is unauthenticated and lacks per-IP rate limiting.
- **Exploitation Impact**: An external attacker issuing 10 concurrent requests to `/api/v1/research/TATAMOTORS` exhausts all Python worker threads, locking up Uvicorn and starving market quote endpoints.
- **Fix Required**: Enforce JWT authentication or wrap `/api/v1/research/{ticker}` in a background Celery/rq worker with token bucket rate-limiting (e.g. 2 runs per minute per IP).