d3ro-voice/docs/map/07-api-server.md

106 lines
7 KiB
Markdown

# 07 — API Server (.NET) Map
> Surface: `apps/api-server` (`D3ROVoice.Api`), tests in `apps/api-server.Tests`
> Stack: ASP.NET Core 10 + EF Core + SQLite
> Role: AI proxy (LLM/STT) + admin back-office backend for the .NET identity side
---
## 1. Composition root (`Program.cs`)
- **DI:** `AddControllers`, `AddHttpClient` (proxies), Swagger (`v1`), rate limiter policy `auth` (fixed window 10/min per IP, 429), `AddDbContext<AppDbContext>` (SQLite; `DATA_DIR`/`DB_PATH`), scoped `IAuthService`, `ILlmProxyService`, `ISttProxyService`, `IAdminOperationService`.
- **Auth:** JWT Bearer HS256; startup hard-fails unless `JWT_SECRET` (≥32 bytes), `JWT_ISSUER`, `JWT_AUDIENCE` are set. Zero clock skew.
- **Policies:** `ManagerOrAbove` (manager/admin/superadmin), `AdminOrAbove` (admin/superadmin), `SuperAdminOnly` (superadmin). Role normalization strips `_`/`-`, lowercases.
- **CORS/Hosts:** strict origin validation (`CORS_ALLOWED_ORIGINS`), `ALLOWED_HOSTS` required outside Development.
- **Startup DB init:** `EnsureCreated()`, raw `CREATE TABLE IF NOT EXISTS` for admin operation/audit tables, legacy SHA-256 password lockdown (`IsActive=false`, `Role="LegacyDisabled"`), idempotent env admin provisioning (`ADMIN_EMAIL`/`ADMIN_PASSWORD`, only when no active user), default LLM/STT endpoints seeded.
- **Middleware order:** Swagger (dev) → CORS → rate limiter → authentication → authorization. The API no longer serves static files: `wwwroot` (stale site build, download/invite pages, `.well-known` copy, legacy embedded admin SPA, 1.0.0 binaries) was deleted 2026-09-26 (Wave 3, cd9d199), and `UseStaticFiles`/the mobile-asset-block fallbacks were removed from `Program.cs` along with it. The Next.js admin (`apps/admin`) is the only admin UI.
- **Health:** `GET /health`, `GET /api/health` → `{status, service, version, uptimeSeconds, database, timestamp}`.
---
## 2. Controllers & routes
### `AuthController` (`/api/auth`)
| Route | Auth | Behavior |
|---|---|---|
| `POST /register` | anonymous + `X-D3RO-Bootstrap-Token` | Rate-limited, ≤16KB; requires `ADMIN_BOOTSTRAP_TOKEN`; fixed-time compare; `409` if registered |
| `POST /login` | anonymous | Rate-limited; returns JWT; `401` invalid |
| `GET /me` | `[Authorize]` | `UserInfoDto` or `404` |
### `LlmController` (`/api/llm`, class `[Authorize]`)
| Route | Behavior |
|---|---|
| `POST /generate` | Requires prompt; `GenerateAsync` |
| `POST /chat` | `ChatAsync` (last message = prompt) |
### `SttController` (`/api/stt`, class `[Authorize]`)
| Route | Auth | Behavior |
|---|---|---|
| `POST /transcribe` | any auth | **Always `410 Gone` `stt_edge_gateway_required`** — user transcription is Edge-only |
| `POST /internal/transcribe` | anonymous + `X-D3RO-STT-Gateway-Token` | multipart, ≤26MB; requires `D3RO_API_TOKEN`; fixed-time compare; provider orchestration; error map `503/400/502` |
*(Legacy duplicate routes `GET /api/stt/providers` and `POST /api/stt/test` were removed on 2026-11-13; back-office STT endpoint CRUD and testing live exclusively under `AdminController` `/api/admin/stt-endpoints`.)*
### `AdminController` (`/api/admin`, class `ManagerOrAbove`)
All mutations flow through `ExecuteAdminMutationAsync` (idempotent + audited).
| Route | Effective policy |
|---|---|
| `GET /stats` | Manager+ |
| `GET /users` | Manager+ |
| `GET/POST/PUT/DELETE /endpoints[/{id}]` | Manager+ read; Admin+ write |
| `GET /stt-endpoints`, `/stt-endpoints/{id}` | Manager+ |
| `POST/PUT/DELETE /stt-endpoints[/{id}]`, `POST .../set-default` | Admin+ |
| `POST /stt-endpoints/{id}/test` | Manager+ |
| `POST /stt-endpoints/test-direct` | Admin+ |
| `GET /stt-usage`, `GET /usage` | Manager+ |
| `POST /license-audit` | **SuperAdminOnly** |
---
## 3. Services
| Service | Purpose |
|---|---|
| `AuthService` | Register (one-time SuperAdmin bootstrap only, `PasswordHasher<User>`, serialized), login (timing-safe dummy verify, inactive rejection, rehash), JWT gen (8h, claims id/email/role) |
| `LlmProxyService` | Resolve endpoint by model → fallback → Mock echo; OpenAI-style POST; parse content+usage; token cost → `ApiUsageLog`; errors → `ServerErrorLog` + fallback text |
| `SttProxyService` (~1182 lines) | Provider adapters (groq/openai/custom, deepgram, google, assemblyai, azure, local-sidecar), candidate resolution + fallback, content-type/duration detection, `SttUsageLog` cost, synthetic-tone endpoint test, CRUD with exclusive default, usage report |
| `AdminOperationService` | Validates actor/idempotency key/memo, SHA-256 request hash, `Serializable` transaction, idempotent replay, before/after audit entry |
---
## 4. Data (`Data/AppDbContext.cs`)
| DbSet / table | Key fields |
|---|---|
| `Users` | Id, unique Email, PasswordHash, Role (default "User"), IsActive, CreatedAt, LastLoginAt |
| `ModelEndpoints` | Id, unique ModelId, ModelName, Provider, EndpointUrl, ApiKey, per-1k costs, IsActive |
| `UsageLogs` | UserId/Email, model, tokens, cost, duration, status |
| `ErrorLogs` | ErrorType, Message, StackTrace, Endpoint |
| `SttProviderEndpoints` | Name, ProviderType, URL, ApiKey, ModelId, Method, Language, Prompt, Temperature, per-minute/second cost, IsDefault, FallbackPriority, ExtraHeadersJson |
| `SttUsageLogs` | User, endpoint, provider, duration, cost, latency, status, transcript preview |
| `AdminOperationRequests` | ActorEmail + IdempotencyKey (unique), Operation, RequestHash, ResponseJson |
| `AdminAuditEntries` | ActorEmail, Action, TargetType/Id, BeforeJson, AfterJson, Memo, IdempotencyKey |
DTOs (`Dtos/Dtos.cs`): auth, license audit, LLM, admin/model endpoints, STT (transcribe, endpoints, test, usage reports).
---
## 5. Tests (`apps/api-server.Tests/`, xUnit)
`AdminAuthorizationE2ETests`, `AdminOperationServiceTests`, `AuthBootstrapControllerTests`, `AuthSecurityTests`, `SttControllerSecurityTests`, `SttFailClosedTests`, `SttGatewayAuthorizationE2ETests` (**32/32 PASS** after Wave 6 2026-11-14: enforced `MaxAudioBytes = 26 * 1024 * 1024` / `MaxBase64Length` cap in `SttProxyService.DecodeAudioBase64` before `Convert.FromBase64String`, and propagated `HttpContext.RequestAborted` `CancellationToken` across `SttController`/`LlmController`/`AdminController` → `SttProxyService`/`LlmProxyService` → EF/HTTP/AssemblyAI polling to abort paid failover immediately on client disconnect).
---
## 6. API server status summary
- Auth, login, JWT, role policies, rate limiting, CORS, host restrictions: **implemented**.
- LLM proxy: **implemented** (with local Mock echo fallback for standalone testing).
- STT proxy: **implemented** for internal gateway; public `/transcribe` intentionally `410` (Edge-only by design).
- Admin API: users, endpoints (LLM + STT), usage, license audit: **implemented** with idempotency + audit.
- Known intentional states (not bugs):
- Legacy SHA-256 users force-disabled.
- No hardcoded/seeded admin credentials.
- No static file serving — `wwwroot` and its mobile/legacy release asset block were deleted 2026-09-26 (Wave 3, cd9d199); downloads/releases are served only from `site/`.
- `LlmProxyService` Mock fallback.
- This backend holds a **separate identity** from Supabase; see `11-gap-backlog.md` `ID-01`.