livrare lot 2

2026-07-10 03:39:53 -07:00 · 2026-07-10 03:39:53 -07:00 · 8ecc78e729
commit 8ecc78e729
763 changed files with 164593 additions and 0 deletions
--- a/backend/services/gateway-auth-layer/didiKong/INDEX.md
+++ b/backend/services/gateway-auth-layer/didiKong/INDEX.md
@ -0,0 +1,208 @@
+# didiKong - Index
+
+API Gateway pentru platforma DIDI. Toate requesturile externe trec prin Kong inainte sa ajunga la serviciile backend. Gestioneaza rutare, rate limiting, CORS, SSL si headere.
+
+**Imagine**: didi-kong:latest (Kong 3.9.1)
+**Container**: didi-kong (activ, pe masina de deployment)
+
+**Mod**: DB-less declarativ (`KONG_DATABASE=off`)
+**Porturi** (doar loopback `127.0.0.1`): 18000 (proxy HTTP -> container 8000), 18001 (admin API -> 8001), 18443 (proxy TLS -> 8443 ssl)
+
+---
+
+## Deployment: container local DB-less (activ)
+
+Kong ruleaza ca un singur container `didi-kong` pe masina de deployment, in mod **DB-less** (`KONG_DATABASE=off`). Nu exista Kong Cluster, Control Plane, Data Planes sau HAProxy, si nu exista PostgreSQL pentru Kong.
+
+- Config declarativa din `declarative/kong.yml.didi11-local`, montata in container la `/kong/declarative/kong.yml`.
+- Porturile sunt legate exclusiv pe loopback (`127.0.0.1`): proxy `18000`, admin API `18001`, proxy TLS `18443`. Kong nu e expus public direct; traficul extern intra prin edge/tunel catre proxy-ul local.
+- Single source of truth = fisierul declarativ `kong.yml.didi11-local`. Orice modificare de rute/plugin-uri se face in acest fisier + reload.
+
+---
+
+## Mod de operare: DB-less (declarativ)
+
+Configuratia vine integral din fisierul `declarative/kong.yml.didi11-local`. Kong nu are baza de date proprie.
+```
+KONG_DATABASE=off
+KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml
+```
+
+Nu exista mod PostgreSQL / productie separata pentru Kong: acelasi fisier declarativ este sursa unica de adevar.
+
+---
+
+## Servicii inregistrate
+
+Kong ruteaza catre 2 servicii backend (conform `kong.yml.didi11-local`):
+
+| Serviciu | Target | Status |
+|----------|--------|--------|
+| didi-agent-v3 | http://didi-agent-v3:24803 | activ |
+| didi-framework | http://didi-framework:3005 | activ |
+
+Nota: rutele agent-v3 au timeout mare (660s = 11 min) pentru procesarea video.
+
+---
+
+## Rute definite
+
+### Agent service (activ)
+
+| Path | Metode | Destinatie |
+|------|--------|------------|
+| /agent/health | GET | agent-api |
+| /agent/status | GET | agent-api |
+| /api/pipelines | GET | agent-api |
+| /api/analyze | POST | agent-api |
+| /api/sessions | GET | agent-api |
+| /api/upload | POST | agent-api |
+| /api/abort | POST | agent-api |
+| /api/v3/* | toate | agent-api (acopera si /api/v3/moderation/*) |
+
+### didiFramework (config + HIL moderation)
+
+| Path | Metode | Destinatie |
+|------|--------|------------|
+| /api/* | toate | didiFramework (acopera /api/moderation-config, /api/sensitive-topics, /api/moderation-roles) |
+
+Nota: rutele de moderatie (HIL) calatoresc pe regulile generale `/api/v3/*` (agent-v3) si `/api/*` (didiFramework) — nu sunt necesare reguli Kong dedicate.
+
+> Notă: serviciile Python legacy `orchestrator-api` și `analysis-api` (rute `/api/v1/catalog|pipelines|runs/*`,
+> `/analysis/*`) NU mai există în config-ul local — au fost eliminate odată cu migrarea pe agent-v3. Config-ul
+> `kong.yml.didi11-local` rutează exclusiv către `didi-agent-v3` și `didi-framework`.
+
+### Admin dashboard
+
+| Path | Metode | Destinatie |
+|------|--------|------------|
+| /admin | toate | admin-dashboard |
+| /admin/api | toate | admin-dashboard |
+
+---
+
+## Plugin-uri globale
+
+5 plugin-uri active pe toate rutele:
+
+### 1. CORS
+- Origins: localhost:3000, localhost:3001, localhost:8100, * (wildcard)
+- Metode: GET, POST, PUT, DELETE, OPTIONS, PATCH
+- Headere: Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, Authorization, X-Request-ID
+- Exposed headers: X-Auth-Token, X-Request-ID
+- Credentials: activat
+- Max age: 3600s
+- Preflight continue: nu
+
+### 2. Rate Limiting
+- 100 requests/minut per consumer
+- 2000 requests/ora per consumer
+- 10000 requests/zi per consumer
+- Politica: local (fara state distribuit)
+- Fault tolerant: da
+
+### 3. Correlation ID (Request ID Tracking)
+- Header: X-Request-ID
+- Generator: UUID
+- Echo downstream: da (returnat in raspuns)
+
+### 4. Request Size Limiting
+- Max payload: 100MB (pentru upload media)
+- Require content-length: nu
+
+### 5. Response Transformer
+- Adauga: X-Gateway: DIDI-Kong, X-API-Version: 2.0
+- Sterge: Server, Via (ascunde detalii interne)
+
+---
+
+## Upstreams (load balancing)
+
+Config-ul local (`kong.yml.didi11-local`) NU definește upstream-uri — rutarea se face
+direct către serviciile `didi-agent-v3:24803` și `didi-framework:3005`. Scalarea orizontală
+a workerilor se face la nivel de agent-v3 (`scale-workers.sh`), nu prin upstream-uri Kong.
+
+---
+
+## SSL/TLS
+
+- Certificat self-signed pentru <host-local>
+- Locatie: certs/server.crt, certs/server.key
+- Valabil: feb 2026 - feb 2027
+- Emitent: DIDI, Bucharest, RO
+- Servit pe proxy-ul TLS local `127.0.0.1:18443`
+
+---
+
+## Integrare Keycloak (LOCAL) + enforcement JWT (Modul 4 Gateway)
+
+Kong valideaza token-urile emise de instanta Keycloak **locala** (`didi-keycloak`, port `28080`, servita sub `/auth`). Realm-urile locale sunt `didi-clients` (useri finali) si `didi-admins` (operatori). Issuer-ele locale au forma `http://localhost:28080/auth/realms/didi-clients` si `.../didi-admins`.
+
+Enforcement-ul se face prin pluginul Kong `jwt` (nu OIDC/introspection): validare de semnatura **RS256** cu chei publice statice, `key_claim_name: iss` (Kong potriveste tokenul dupa claim-ul `iss` cu un `jwt_secret` inregistrat pe consumer).
+
+Consumer: **`didi-keycloak-users`** — detine `jwt_secrets` (RS256, `rsa_public_key`) pentru toate issuer-ele acceptate, cheia fiind chiar valoarea `iss`:
+- local: `http://localhost:28080/realms/didi-clients`, `http://localhost:28080/realms/didi-admins`
+- plus issuer-ele externe/edge folosite in fata proxy-ului: `https://didi365.eu/auth/realms/{didi-clients,didi-admins}`, `https://<sso-extern>/realms/...`, `https://<sso-extern>/realms/...`, `https://<host-local>/auth/realms/...`, `https://10.11.10.11:{3001,8443}/auth/realms/...`
+
+Pluginul `jwt` este activ pe **16 rute protejate** de pe cele doua servicii (`didi-agent-v3` si `didi-framework`), incluzand ruta **`/framework`** (route `didi-framework-direct`, jwt adaugat 2026-07-08). Rutele publice raman fara jwt (health/status, media public, verify-email, waitlist), iar rutele de extensie folosesc autentificare separata prin `X-API-Key` + rate-limiting.
+
+JWT validation flow:
+1. Clientul (SPA/extensie) obtine token JWT de la Keycloak local (`/auth/realms/didi-clients` sau `/auth/realms/didi-admins`).
+2. Trimite request cu `Authorization: Bearer {token}`.
+3. Kong potriveste `iss` cu `jwt_secret`-ul consumer-ului `didi-keycloak-users` si valideaza semnatura RS256; token invalid/lipsa -> `401`.
+4. Daca valid, ruteaza requestul catre serviciul backend local (`didi-agent-v3:24803` / `didi-framework`).
+5. Serviciul backend decodeaza tokenul pentru `user_id`/`email`/`realm_access.roles` (fara re-validare — Kong a validat deja).
+
+---
+
+## Configurare performanta
+
+```
+KONG_NGINX_WORKER_PROCESSES=auto
+KONG_MEM_CACHE_SIZE=256m
+KONG_NGINX_PROXY_PROXY_BUFFER_SIZE=128k
+KONG_NGINX_PROXY_PROXY_BUFFERS=4 256k
+KONG_NGINX_PROXY_PROXY_BUSY_BUFFERS_SIZE=256k
+KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS=4 64k
+```
+
+Buffer-urile mari sunt necesare pentru headerele JWT de la Keycloak (token-urile pot fi foarte mari).
+
+---
+
+## Fisiere
+
+```
+Dockerfile                       -- Imagine didi-kong (Kong 3.9), instaleaza curl, entrypoint
+entrypoint.sh                    -- Pornire Kong DB-less + wait for ready + log servicii
+declarative/
+  kong.yml.didi11-local          -- Configurare declarativa activa (single source of truth, montata la /kong/declarative/kong.yml)
+certs/
+  server.crt                     -- Certificat SSL self-signed
+  server.key                     -- Cheie privata SSL
+```
+
+Zero cod custom. Zero plugin-uri Lua custom. Doar configurare declarativa si certificat SSL.
+
+---
+
+## Health check
+
+```
+kong health (interval 30s, timeout 10s, retries 3, start period 60s)
+```
+
+---
+
+## Consumers
+
+Configuratia declarativa defineste un singur consumer Kong: **`didi-keycloak-users`** (username + custom_id `didi-keycloak-users`), care detine `jwt_secrets`-urile RS256 pentru toate issuer-ele Keycloak locale/edge acceptate (vezi sectiunea Integrare Keycloak). Acest consumer este cel pe care pluginul `jwt` il rezolva la validarea tokenului.
+
+Limitele per-tier (free/paid/enterprise) provin din atributele de grup Keycloak (realm-urile locale `didi-clients` / `didi-admins`) si sunt disponibile in claim-urile JWT pentru rate limiting; rutele de extensie au propriul rate-limiting per `X-API-Key` (30/min).
+
+## Recent Changes
+
+- **2026-07-08 — jwt pe `/framework`**: pluginul `jwt` (RS256, `key_claim_name: iss`) adaugat pe ruta `didi-framework-direct` (path `/framework`). Enforcement JWT acum activ pe 16 rute protejate pe `didi-agent-v3` + `didi-framework`.
+- **jwt_secrets pentru issuer-ele locale** pe consumer `didi-keycloak-users`: `http://localhost:28080/realms/didi-clients` + `.../didi-admins`, alaturi de issuer-ele edge (`didi365.eu/auth`, `<sso-extern>`, `<sso-extern>`, `<host-local>/auth`, `10.11.10.11:{3001,8443}/auth`) pentru realm-urile `didi-clients` si `didi-admins`.
+- **Rute de extensie** (`didi-agent-extension-analyze`, `-async`, `-status`, `-upload`): autentificare `X-API-Key` + `rate-limiting` 30/min + `request-transformer`; CORS extins cu origins `chrome-extension://[a-z]+`, `moz-extension://[a-z0-9-]+` + header `X-API-Key`.
+- **Single source of truth** = `declarative/kong.yml.didi11-local` (DB-less). Fara cluster, fara decK sync.