How ajay-1011-git/kaaval works
KAAVAL protects browser sessions against stolen-cookie replay with per-request PulseLock proofs, and also provides deterministic security assessment and policy services plus an incident dashboard. The principal workflow is passkey login and session-key binding, followed by nonce-backed signing and gateway verification; resulting security events feed the live dashboard and Chronicle. The graph includes README-documented Radar, Guardian, and attacker demonstrations. Some subsystem wiring is represented only where explicit in the README or sampled routes; unsampled implementation details are omitted.
Main entry points: main.py Gateway app · db.py SQLite state · page.tsx Dashboard · client.ts Signed fetch
Components 25
PulseLock SDK
- Session keys
sdk/src/keys.ts - Passkey ceremonies
sdk/src/webauthn.ts - Signed fetch
sdk/src/client.ts - Request canonicalization
sdk/src/canonical.ts
Gateway security
- Gateway app
backend/main.py - WebAuthn routes
backend/gateway/webauthn_routes.py - Nonce issuance
backend/gateway/nonce.py - Protected demo app
backend/gateway/demo_app_routes.py - Proof verification
backend/gateway/verify.py - Event writing
backend/events.py - SQLite state
backend/db.py - SSE stream
backend/gateway/events_stream.py
Security services
- Radar reports
backend/radar/routes.py - Exposure scoring
backend/radar/scoring.py - Guardian evaluation
backend/guardian/routes.py - OAuth policy
backend/guardian/oauth_policy.py - Device-code policy
backend/guardian/device_code_policy.py - Incident narration
backend/chronicle/routes.py - Deterministic fallback
backend/chronicle/fallback.py
Dashboard and narration
- Dashboard
frontend/app/page.tsx - Live event client
frontend/lib/eventsClient.ts - Chronicle client
frontend/lib/chronicleClient.ts
Attack demonstration
- Attacker consoles
demo-tools/attacker
Other components
- Browser user
- Groq API
Connections 36
- Browser user → Passkey ceremonies: starts passkey login
- Passkey ceremonies → Session keys: binds session key
- Passkey ceremonies → WebAuthn routes: registers or logs in
- WebAuthn routes → SQLite state: stores credentials and sessions
- Signed fetch → Passkey ceremonies: gets active session
- Signed fetch → Nonce issuance: requests nonce
- Signed fetch → Request canonicalization: builds signed envelope
- Signed fetch → Protected demo app: sends proof-bearing request
- Browser user → Signed fetch: makes protected request
- Gateway app → WebAuthn routes: mounts routes
- Gateway app → Nonce issuance: mounts routes
- Gateway app → Protected demo app: mounts routes
- Gateway app → Radar reports: mounts routes
- Gateway app → Guardian evaluation: mounts routes
- Gateway app → Incident narration: mounts routes
- Protected demo app → Proof verification: verifies protected request
- Proof verification → Event writing: writes decision event
- Protected demo app → SQLite state: records transfer
- Event writing → SQLite state: persists events
- Nonce issuance → SQLite state: stores nonce state
- Radar reports → Exposure scoring: generates report
- Guardian evaluation → OAuth policy: evaluates consent
- Guardian evaluation → Device-code policy: evaluates device code
- Guardian evaluation → Event writing: records decisions
- Incident narration → SQLite state: loads selected events
- Incident narration → Deterministic fallback: uses on failure or fallback mode
- Incident narration → Groq API: requests live narrative
- Browser user → Dashboard: views security status
- Dashboard → Radar reports: requests report
- Dashboard → Guardian evaluation: submits policy checks
- Dashboard → Live event client: subscribes to events
- Live event client → SSE stream: opens SSE connection
- SSE stream → SQLite state: polls event history
- Dashboard → Chronicle client: requests explanation
- Chronicle client → Incident narration: posts event IDs
- Attacker consoles → Protected demo app: replays attack requests