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 |
EndpointUrlPolicy |
Upstream LLM/STT endpoint SSRF validation (Services/EndpointUrlPolicy.cs) paired with named "UpstreamNoRedirect" HttpClient (AllowAutoRedirect = false) (Wave 7) |
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, EndpointSecurityAndSttProxyTests, SttControllerSecurityTests, SttFailClosedTests, SttGatewayAuthorizationE2ETests (55 passed, 0 failed after Wave 7 c68e81e 2026-11-14, post-v1.17.1; Wave 6 enforced MaxAudioBytes = 26 * 1024 * 1024 / MaxBase64Length cap in SttProxyService.DecodeAudioBase64 before Convert.FromBase64String and propagated HttpContext.RequestAborted CancellationToken, and Wave 7 added Services/EndpointUrlPolicy.cs SSRF validation, named "UpstreamNoRedirect" HttpClient with AllowAutoRedirect = false, and query parameter URL encoding across AdminController, SttController, LlmProxyService, and SttProxyService).
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.