Cleaned dead code and updated documents

docs/MWT_SPEC.md

@@ -15,8 +15,10 @@ detection.
 | `pkey` | Deterministic hash of user's permission state at issuance |
 | `exp` | Configurable short TTL — controls permission staleness window (Django setting) |
 | `iat` | Issued at |
-| `kid` | Key ID — for secret rotation |
+| `kid` | Key ID — for secret rotation. Carried in the JOSE header (RFC 7515), not the payload |
 | `aud` | Audience binding — prevents cross-tenant replay |
+| `nbf` | Not-before — tolerates clock skew |
+| `staff` / `super` | `is_staff` / `is_superuser`, used to build `MWTUser` without a DB query |
 
 ## Key decisions
 
@@ -25,10 +27,14 @@ detection.
 - **`X-Mizan-Token` header, not `Authorization: Bearer`.** Avoids
   collision with DRF, allauth, and existing JWT systems. Cloudflare
   WAF/Access do not inspect custom headers.
-- **Replaces `JWTUser` + `_try_jwt_auth` entirely.** Old approach is
-  deleted.
+- **`MWTUser`** is a minimal, DB-free request user built from the
+  token claims (`cores/mizan-python/src/mizan_core/mwt.py`).
+  > A separate JWT module (`mizan/jwt/`) still exists for standard
+  > user-auth access/refresh tokens; MWT is the cache-keying identity
+  > layer, not a replacement for that module.
 - **App handles authentication** (session, social, etc.). Mizan
-  issues MWT *from* the authenticated identity.
+  issues MWT *from* the authenticated identity
+  (`create_mwt(user, secret, ttl, audience, kid)`).
 - **Edge Worker** validates MWT, extracts `sub` for HMAC cache key,
   checks `exp`.
 - **`pkey` computation must be deterministic:**
@@ -43,9 +49,11 @@ detection.
 JSON with sorted keys:
 
 ```
-HMAC(secret, JSON.stringify({"c": context, "p": sorted_params, "u": user_id}))
+ctx:{context}:HMAC(secret, JSON.stringify({"c": context, "p": sorted_params, "r": rev, "u": user_id}))
 ```
 
+See [CACHE_KEYING.md](CACHE_KEYING.md) for the full derivation.
+
 ## What this solves
 
 - DRF token collision
@@ -55,5 +63,8 @@ HMAC(secret, JSON.stringify({"c": context, "p": sorted_params, "u": user_id}))
 
 ## Usage rule
 
-All cache-layer auth code uses MWT, not Django session or raw JWT.
-The `@client(auth=...)` parameter gates on MWT validity.
+MWT is the identity Edge/cache layers key on. The `@client(auth=...)`
+parameter is enforced server-side in `mizan/client/executor.py`
+(`_check_auth_requirement`), which checks `request.user` against the
+auth requirement (`required` / `staff` / `superuser` / callable);
+`request.user` may be an `MWTUser` (stateless) or a session user.