Extracts the JWT validation + Heimdall tier resolution + guest session pattern
that was duplicated across kiwi and peregrine into a single reusable module.
CloudSessionFactory is parameterized by product name. Products instantiate it
once at module level and call .dependency() to get a FastAPI-compatible Depends()
function. .require_tier(min_tier) returns a dependency factory for gated routes.
CloudUser carries:
user_id — Directus UUID, "local" (self-hosted), "local-dev" (bypass), "anon-<uuid>"
tier — free | paid | premium | ultra | local
product — which CF product this session is for
has_byok — whether user has a configured LLM backend
meta — dict for product-specific extras (household_id, license_key, etc.)
Products can pass extra_meta= to attach product-specific fields without
subclassing. The module is FastAPI-only (fastapi is a lazy import so local-mode
products that never hit cloud paths don't pay the import cost).
pyr0ball
00737d22cf