Security
There are two trust zones. People and AI clients authenticate to the Taxonomy API with a JWT. GRE services trust only each other, through a shared service key. The Taxonomy API is the only bridge: its /gre/... gateway checks the user's role, then forwards the call with the service key that the browser never sees.
People: JWT
| Aspect | Implementation |
|---|---|
| Login | POST /auth/login checks the password hash (Passwords.Hash / Verify) and returns a JWT valid for 8 hours (TokenService.Lifetime). |
| Signing | HMAC-SHA256 with Auth:JwtKey (32+ characters, required at start-up). Issuer kaleido-taxonomy-api. |
| Claims | sub (user id), name, role. |
| Default rule | A fallback policy requires an authenticated user on every endpoint. /health and /auth/login opt out with AllowAnonymous. |
| Policies | editor accepts editor or admin; admin accepts admin only. |
| Guessing | LoginThrottle: 5 failures for one username and IP lock that pair for 1 minute. Password verification also runs for unknown users, so timing does not reveal valid usernames. |
| WebSockets | The SignalR hub at /hubs/pipeline reads the token from the access_token query string, because browsers cannot set headers on a WebSocket. |
| First admin | Created at start-up from Auth:AdminPassword if no user exists; if that is unset a random password is generated and logged once. |
Services: shared key
src/Kaleido.Gre.Hosting/ServiceKey.cs adds a middleware to every GRE service:
- Every request except
/healthmust carryX-Api-Keyequal toService:ApiKey. - The comparison uses
CryptographicOperations.FixedTimeEquals, so the response time does not leak the key. - A missing or shorter-than-16-character key stops the service at start-up.
Each client can use a different key per target (Activity:ApiKey, Profile:ApiKey and so on); by default they all use the service's own key.
The gateway's role rules
src/Kaleido.Taxonomy.Api/Endpoints/GreEndpoints.cs forwards GET, POST, PUT and DELETE on /gre/{service}/{**path}.
| Request | Who may make it |
|---|---|
Any GET | Any signed-in user |
POST /gre/recommender/recommend, POST /gre/profile/affinities/compute | Any signed-in user (read-only computations) |
| Any other write | editor or admin |
Writes to ingest (Kafka connections hold credentials) | admin only, except DELETE /gre/ingest/data which editors may call to reset the simulation |
Any path starting with internal | Nobody: answered with 404 |
The gateway strips host, authorization, content-length, transfer-encoding, connection and any incoming x-api-key header before adding its own key, so a user cannot smuggle a service key or forward their JWT to an internal service.
Secrets at rest
| Secret | Where it is stored | Protection |
|---|---|---|
| User passwords | app_user.PasswordHash | PBKDF2-SHA256, 210,000 iterations, 16-byte random salt (Infrastructure/Passwords.cs) |
| AI provider API keys | ai_provider.ApiKeyEnc | AES-256-GCM with a key derived from Auth:JwtKey (SecretBox). Never returned by the API; only a hint of the last four characters. |
| Kafka SASL and Schema Registry passwords | Redis cfg:ingest:sources | AES-GCM with a key derived from SERVICE_API_KEY (SourceStore). Never sent to the browser; the view only says whether one is set. |
Changing Auth:JwtKey or SERVICE_API_KEY makes the matching stored secrets unreadable; they must be entered again. The code treats a failed decryption as "no password set" rather than crashing.
Other protections
- Outbound requests to admin-supplied addresses go through
SafeHttp, which blocks loopback, private and link-local targets at connect time. That covers redirects and DNS rebinding. - Stored HTML is served back as
text/plainwithX-Content-Type-Options: nosniff, so captured pages never render in the app's origin. - Page fetching honours
robots.txt, identifies itself honestly and fails withBlockedExceptionon a bot challenge instead of imitating a browser. - Telemetry names HTTP spans by route template, so customer ids in URLs never reach traces.
- Simulation writes to a Kafka ingestion only when an admin switched on Allow the Simulation to write test messages here for it. The
/internal/sources/{id}/connectionroute that hands the simulator the credentials returns 403 otherwise, and the gateway never forwards it.