rythazhur/mizan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs carry the shape of the system, not its status

Browse Source 
MIZAN.md's phase-numbered implementation order, PRODUCT_ARCHITECTURE's
"Deferred until Render revenue funds it" and "Shipped in", PSR_VS_EDGE's
current-state section, and the READMEs' passing-test counts were all reporting
where the work stood rather than what the system is. OWED_SURFACE keeps its
subject — surface that is specified but unbuilt — stated as the shape each unit
owes.

The channel sections follow the renamed slots: Params / ClientMessage /
ServerMessage, and Channel as the base class on both backends.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ryth Azhur
2026-07-27 14:03:29 -04:00
parent 3aafec6dd4
commit e00b3a177e
10 changed files with 243 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/CACHE_KEYING.md
View File

@@ -1,19 +1,18 @@
# Cache Keying
*Discovered 2026-04-06.*
## What cache keying is for
## The gap
Mizan's invalidation surface names *which* entries die. Cache keying
names *which entry is which*. A key that does not separate User A's
content from User B's turns Edge caching into a
**security vulnerability** — it serves one user's content to another.
Mizan specified invalidation but never specified cache keying.
Without correct cache keying, Edge caching is a **security
vulnerability** — it serves User A's content to User B.
## Why `Vary` is not the mechanism
## Why Vary doesn't work
All major CDNs ignore `Vary` for personalized content, and no
standardized replacement exists. The key itself carries identity.
All major CDNs ignore `Vary` for personalized content. No
standardized replacement exists.
## Resolution: HMAC cache key (JSON-canonical form)
## HMAC cache key (JSON-canonical form)
```
ctx:{context}:HMAC-SHA256(secret, json.dumps({
@@ -28,9 +27,10 @@ ctx:{context}:HMAC-SHA256(secret, json.dumps({
`"ctx:{context}:{hmac_hex}"`. The `ctx:{context}:` prefix lets broad
purge SCAN by prefix. Param values are normalized for cross-language
consistency (`True`→`"true"`, `None`→`"null"`) before stringification.
Implemented in `cores/mizan-python/src/mizan_core/cache/keys.py` and
`backends/mizan-ts/src/cache/keys.ts` (`deriveCacheKey`); pin tests
verify identical output.
The derivation lives in
`cores/mizan-python/src/mizan_core/cache/keys.py` and
`backends/mizan-ts/src/cache/keys.ts` (`deriveCacheKey`); pinned
vectors hold the two outputs byte-identical.
### Key derivation rules
@@ -43,18 +43,16 @@ verify identical output.
## Identity layer
MWT (Mizan Web Token) — see [MWT_SPEC.md](MWT_SPEC.md). JWT with
Mizan claims on `X-Mizan-Token` header. Replaces the old
`JWTUser` + permission key metadata approach.
Mizan claims on `X-Mizan-Token` header.
## Cache architecture
*Decided 2026-04-06.*
**Not a compiled binary ABI. Not a pluggable Python protocol.**
Each backend adapter (Python, TypeScript, future PHP/C#/Go)
implements the cache protocol in its own language.
**Conformance verified by a shared test suite.**
Each backend adapter (Python, TypeScript, PHP, C#, Go) implements the
cache protocol in its own language. **Conformance is verified by a
shared test suite**, so the implementations cannot drift apart
silently.
### Required operations
@@ -80,6 +78,6 @@ become **unreachable orphans**. No purge needed; no thundering herd.
## Invariant
All cache-related code must implement *identical* HMAC key
derivation. Cross-language conformance tests enforce this. Any
divergence is a security vulnerability.
All cache-related code implements *identical* HMAC key derivation.
Cross-language conformance tests enforce this. Any divergence is a
security vulnerability.