Skip to main content

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​

AspectImplementation
LoginPOST /auth/login checks the password hash (Passwords.Hash / Verify) and returns a JWT valid for 8 hours (TokenService.Lifetime).
SigningHMAC-SHA256 with Auth:JwtKey (32+ characters, required at start-up). Issuer kaleido-taxonomy-api.
Claimssub (user id), name, role.
Default ruleA fallback policy requires an authenticated user on every endpoint. /health and /auth/login opt out with AllowAnonymous.
Policieseditor accepts editor or admin; admin accepts admin only.
GuessingLoginThrottle: 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.
WebSocketsThe SignalR hub at /hubs/pipeline reads the token from the access_token query string, because browsers cannot set headers on a WebSocket.
First adminCreated 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 /health must carry X-Api-Key equal to Service: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}.

RequestWho may make it
Any GETAny signed-in user
POST /gre/recommender/recommend, POST /gre/profile/affinities/computeAny signed-in user (read-only computations)
Any other writeeditor 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 internalNobody: 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​

SecretWhere it is storedProtection
User passwordsapp_user.PasswordHashPBKDF2-SHA256, 210,000 iterations, 16-byte random salt (Infrastructure/Passwords.cs)
AI provider API keysai_provider.ApiKeyEncAES-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 passwordsRedis cfg:ingest:sourcesAES-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/plain with X-Content-Type-Options: nosniff, so captured pages never render in the app's origin.
  • Page fetching honours robots.txt, identifies itself honestly and fails with BlockedException on 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}/connection route that hands the simulator the credentials returns 403 otherwise, and the gateway never forwards it.