Feature: Implement JWT Token Blacklist for Revocation with Merkle Tree Replication #8

New Issue

MrKalzu · 2025-09-22T17:01:12+03:00

MrKalzu commented

2025-09-22 17:01:12 +03:00

Blacklist Storage:

Key Structure: Use a dedicated prefix like _blacklist:tokens/ followed by the token_hash (SHA3-512 of the JWT).
Value: Simple JSON metadata: {"revoked_at": 1695280000, "reason": "compromised", "user_uuid": "abc123"}.
TTL: Inherit from original token's ExpiresAt (no need to keep forever; expired tokens auto-purge).
Storage Hook: On revocation, add to blacklist via db.Update (atomic with optional tamper log).

Merkle Tree Integration (cluster/merkle.go):

Inclusion: Treat _blacklist:tokens/* as regular keys in getAllKVPairsForMerkleTree()—no special handling needed.
Efficiency: Blacklists are small (few entries), so they add negligible overhead to tree diffs/hashes.
Sync Trigger: On revocation, optionally bump a "blacklist version" key (_meta:blacklist_version) to force quicker Merkle refresh in catch-up sync.
Pruning: During sync, auto-remove expired blacklist entries (e.g., in resolveConflict() if timestamp > revoked_at + TTL).

Example Flow

Client: DELETE /api/tokens/abc123... (with admin JWT).
Handler: Add _blacklist:tokens/abc123... with TTL.
Merkle sync detects change → replicates to peers in next cycle.
Future validations on any node: Fail if in blacklist.

Configuration

Add to types.Config: token_blacklist_enabled: true (default: true when auth_enabled: true).
blacklist_cache_size: 1000 (memory LRU for hot tokens).
Logging: Tamper log action "token_blacklist_add".

Blacklist Storage: Key Structure: Use a dedicated prefix like _blacklist:tokens/ followed by the token_hash (SHA3-512 of the JWT). Value: Simple JSON metadata: {"revoked_at": 1695280000, "reason": "compromised", "user_uuid": "abc123"}. TTL: Inherit from original token's ExpiresAt (no need to keep forever; expired tokens auto-purge). Storage Hook: On revocation, add to blacklist via db.Update (atomic with optional tamper log). Merkle Tree Integration (cluster/merkle.go): Inclusion: Treat _blacklist:tokens/* as regular keys in getAllKVPairsForMerkleTree()—no special handling needed. Efficiency: Blacklists are small (few entries), so they add negligible overhead to tree diffs/hashes. Sync Trigger: On revocation, optionally bump a "blacklist version" key (_meta:blacklist_version) to force quicker Merkle refresh in catch-up sync. Pruning: During sync, auto-remove expired blacklist entries (e.g., in resolveConflict() if timestamp > revoked_at + TTL). Example Flow - Client: DELETE /api/tokens/abc123... (with admin JWT). - Handler: Add _blacklist:tokens/abc123... with TTL. - Merkle sync detects change → replicates to peers in next cycle. - Future validations on any node: Fail if in blacklist. Configuration - Add to types.Config: token_blacklist_enabled: true (default: true when auth_enabled: true). - blacklist_cache_size: 1000 (memory LRU for hot tokens). - Logging: Tamper log action "token_blacklist_add".

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: ryyst/kalzu-value-store#8