feat: add voice interaction and harden chat security

[CodewithJha]

Overview

Adds voice interaction to Nawab with STT/TTS support, voice-mode WebSocket integration, frontend voice UX, and security hardening for the affected authentication and WebSocket paths.

This is intentionally a single PR organized into four logical commits so each part can be reviewed independently.

Architecture

Voice input:

VoiceRecorder
→ Frontend BFF
→ /api/v1/voice/transcribe
→ Groq Whisper
→ text
→ WebSocket agent
→ response
→ TTS queue
→ Kokoro
→ audio playback

Voice output uses Kokoro with hm_psi as the default voice and 1.05 speech speed.

Commits / Recommended Review Order

1. Voice foundation

feat: add STT/TTS providers and voice REST API

Adds:

• Groq Whisper STT
• Kokoro TTS
• TTS provider abstraction/factory
• Voice REST endpoints
• Voice configuration
• STT/TTS tests

2. Voice integration + frontend

feat: wire voice mode through streaming and add voice UI

Adds:

• voice_mode WebSocket integration
• Voice-mode prompt/history handling
• Voice recorder
• TTS queue and playback
• Frontend BFF routes
• Voice UI state and interruption handling
• Frontend voice tests

3. Security hardening

security: harden auth, ownership, and WebSocket limits

Hardens:

• WebSocket conversation ownership / IDOR protection
• WebSocket rate and concurrency limits
• Short-lived WebSocket authentication tickets
• Cookie-based session handling
• OTP verification attempt limits
• STT upload limits and MIME validation
• Soft-delete enforcement
• Generic error responses
• JWT configuration validation
• API input limits
• Health metrics access

4. Documentation + configuration

docs: document voice setup and configuration

Adds:

• Voice setup documentation
• Configuration documentation
• Environment examples
• Required test bootstrap configuration
• Relevant gitignore updates

Validation

Backend

• pytest -q
• 144 passed
• 2 deselected
• 2 xfailed

Frontend

• 10 Vitest files
• 28 tests passed
• TypeScript check clean

Live verification

• Backend :9000 verified
• Frontend :3000 verified
• REST authentication verified
• WebSocket ownership and concurrency verified
• STT verified
• TTS verified
• Voice history isolation verified

Security

No real secrets or local environment files are included in the PR.

Notes

Manual Safari subjective audio verification was limited by the available browser automation environment. API, WebSocket, and frontend automated voice paths were verified successfully.

TTS currently uses hm_psi. English-word pronunciation can be improved separately without changing the current voice architecture.

Review Guidance

Please review the four commits in order:

1. Voice foundation
2. Voice integration + frontend
3. Security hardening
4. Documentation + configuration

This order follows the dependency flow and should make the overall change easier to review.

Made with Cursor