Reference
Security model
A cache that reuses LLM answers is a trust system. This page describes what is enforced, where, and what you should know before exposing anything.
Auth, per surface#
| Surface | Gate |
|---|---|
| RESP3 (Redis protocol) | CROWKIS_AUTH_TOKEN bearer auth, constant-time comparison. |
| gRPC | Same token gate as RESP. |
| Management REST | CROWKIS_ADMIN_KEY, RBAC API keys, or session auth. Reader endpoints need reader auth; mutating endpoints need stronger roles. |
| Dashboard metrics & live feed | Require the admin key or a management API key whenever auth is enabled. |
Tenant isolation#
Every semantic entry is namespaced by tenant. Lookups never cross the boundary — a paraphrase match in tenant A cannot serve an answer cached by tenant B. Isolation is also one of the five anti-poisoning stages, so cross-tenant anomalies score against a write being trusted at all.
The anti-poisoning pipeline#
Cache poisoning is the defining risk of semantic caching: one malicious or hallucinated write, served to every nearby query. Crowkis scores every write through five weighted stages before it is trusted:
| Stage | Signal | Weight |
|---|---|---|
| 1 — Coherence | Does the answer semantically cohere with the question? | 0.30 |
| 2 — Content | Content-level heuristics on the answer itself. | 0.10 |
| 3 — Source trust | Track record of the writing source, from an append-only ledger. | 0.30 |
| 4 — Isolation | Tenant-boundary and namespace consistency. | 0.15 |
| 5 — Neighbourhood | Does it agree with its semantic neighbours? | 0.15 |
The composite must clear 0.75 or the write is refused. Every decision is recorded in the trust ledger, so "why was this blocked?" always has an answer.
PII and compliance#
A PII index supports scrubbing and erasure workflows over cached entries, with erasure reports exposed through the management API. Prompt previews are excluded from logs by default (CROWKIS_LOG_QUERY_PREVIEWS=0), and compliance report exports are built into the control plane.
Deployment guidance#
Three decisions every deployment should make consciously:
| Area | Recommendation |
|---|---|
| TLS | Terminate at your proxy or service mesh, like most data-plane infrastructure — keep Crowkis ports off the public internet. |
| Network placement | Run on a trusted segment; bind beyond loopback only with CROWKIS_AUTH_TOKEN and CROWKIS_ADMIN_KEY set. |
| License enforcement | Tier gating is honor-system (the CockroachDB / Sentry model), not DRM — verification is offline, nothing phones home. |