re-teamspeak/docs/SRS.md

# Software Requirements Specification (SRS)
# ReTeamSpeak - Cross-Platform TeamSpeak Client

**Version**: 1.0.0  
**Date**: 2026-05-12  
**Status**: Based on actual implementation  

---

## 1. Introduction

### 1.1 Purpose
ReTeamSpeak is a cross-platform TeamSpeak 3 voice communication client supporting Windows, macOS, Linux, iOS, and Android. This document specifies the software requirements based on the implemented system.

### 1.2 Scope
The system implements:
- TeamSpeak 3 protocol (UDP-based, encrypted voice/text communication)
- Cross-platform UI via Tauri v2 + React
- Audio engine with Opus codec
- Local data storage (SQLite)
- Identity and bookmark management

### 1.3 Definitions
| Term | Definition |
|------|-----------|
| TS3 | TeamSpeak 3 protocol |
| EAX | AES-128-CTR with OMAC encryption mode |
| ECDH | Elliptic Curve Diffie-Hellman key exchange |
| Opus | Audio codec used for voice transmission |
| VAD | Voice Activity Detection |
| PTT | Push-To-Talk |

---

## 2. System Requirements

### 2.1 Functional Requirements

#### FR-01: Connection Management
- **FR-01.1**: Connect to TS3 servers via UDP
- **FR-01.2**: Support RSA puzzle handshake (DoS protection)
- **FR-01.3**: Support ECDH key exchange (P-256 and Curve25519)
- **FR-01.4**: Support AES-128-EAX encrypted communication
- **FR-01.5**: Support QuickLZ packet compression
- **FR-01.6**: Support packet fragmentation (max 500 bytes)
- **FR-01.7**: Support selective repeat reliable delivery
- **FR-01.8**: Support connection state machine (Disconnected → Connecting → Connected → ChannelListFinished)

#### FR-02: Authentication
- **FR-02.1**: ECC P-256 identity key generation
- **FR-02.2**: Hash Cash level computation (anti-spam)
- **FR-02.3**: Server password authentication (base64(sha1(password)))
- **FR-02.4**: Channel password authentication
- **FR-02.5**: Permission token support
- **FR-02.6**: UID computation (base64(sha1(publicKey)))

#### FR-03: Voice Communication
- **FR-03.1**: Opus codec encoding/decoding (48kHz)
- **FR-03.2**: Voice Activity Detection (VAD)
- **FR-03.3**: Push-To-Talk (PTT) mode
- **FR-03.4**: Per-client volume control
- **FR-03.5**: Whisper support (direct and group)
- **FR-03.6**: Codec types: Speex NB/WB/UWB, CELT, Opus Voice/Music

#### FR-04: Text Messaging
- **FR-04.1**: Server messages
- **FR-04.2**: Channel messages
- **FR-04.3**: Private messages
- **FR-04.4**: BBCode formatting support
- **FR-04.5**: Message history (SQLite storage)

#### FR-05: Channel Management
- **FR-05.1**: Channel tree display
- **FR-05.2**: Channel join/leave
- **FR-05.3**: Channel creation/editing (with permissions)
- **FR-05.4**: Channel subscription

#### FR-06: Client Management
- **FR-06.1**: Online client list
- **FR-06.2**: Client info display
- **FR-06.3**: Server group management
- **FR-06.4**: Channel group management
- **FR-06.5**: Client kick/ban (with permissions)

#### FR-07: Data Storage
- **FR-07.1**: Identity storage (encrypted private keys)
- **FR-07.2**: Server bookmarks
- **FR-07.3**: Chat message history
- **FR-07.4**: Application settings

#### FR-08: File Transfer
- **FR-08.1**: File upload to channels
- **FR-08.2**: File download from channels
- **FR-08.3**: File browsing
- **FR-08.4**: Transfer progress tracking

### 2.2 Non-Functional Requirements

#### NFR-01: Performance
- **NFR-01.1**: Connection establishment < 3 seconds
- **NFR-01.2**: Voice latency < 200ms
- **NFR-01.3**: Message delivery < 100ms
- **NFR-01.4**: Support 1000+ client servers

#### NFR-02: Security
- **NFR-02.1**: AES-128-EAX encryption for all commands
- **NFR-02.2**: ECDH key exchange (forward secrecy)
- **NFR-02.3**: RSA puzzle DoS protection
- **NFR-02.4**: ChaCha20-Poly1305 identity storage encryption

#### NFR-03: Compatibility
- **NFR-03.1**: Windows 10/11
- **NFR-03.2**: macOS 11+
- **NFR-03.3**: Linux (Ubuntu 20.04+, Debian 11+)
- **NFR-03.4**: iOS 15+
- **NFR-03.5**: Android 10+
- **NFR-03.6**: TS3 server versions 3.0.x and 3.1.x

#### NFR-04: Reliability
- **NFR-04.1**: Automatic reconnection on temporary disconnect
- **NFR-04.2**: Packet retransmission with exponential backoff
- **NFR-04.3**: Connection timeout detection (30 seconds)
- **NFR-04.4**: Graceful degradation on packet loss

---

## 3. System Architecture

### 3.1 Module Structure
```
src/
├── shared/          # Shared types (Client, Channel, Server, Events)
├── tscore/          # Protocol core (packets, crypto, connection)
├── tsaudio/         # Audio engine (capture, playback, codec)
├── tsdb/            # Database (SQLite via rusqlite)
└── tauri-app/       # Application shell
    ├── src-tauri/   # Rust backend (Tauri commands)
    └── frontend/    # React frontend (TypeScript)
```

### 3.2 Technology Stack
| Layer | Technology |
|-------|-----------|
| Language | Rust 1.70+, TypeScript 5.x |
| Desktop Framework | Tauri v2 |
| Frontend | React 18, Vite 5 |
| Async Runtime | Tokio |
| Actor Framework | Actix |
| Database | SQLite (rusqlite) |
| Audio | Opus, cpal |
| Crypto | AES-EAX, P-256, Curve25519, SHA-256/512 |

---

## 4. Protocol Specification

### 4.1 Packet Format
```
C2S: [MAC:8][PId:2][CId:2][PT:1][Data:≤487]
S2C: [MAC:8][PId:2][PT:1][Data:≤489]
```

### 4.2 Packet Types
| Type | Value | Encrypted | Reliable | Fragmentable |
|------|-------|-----------|----------|--------------|
| Voice | 0x00 | Optional | No | No |
| VoiceWhisper | 0x01 | Optional | No | No |
| Command | 0x02 | Yes | Yes | Yes |
| CommandLow | 0x03 | Yes | Yes | Yes |
| Ping | 0x04 | No | No | No |
| Pong | 0x05 | No | No | No |
| Ack | 0x06 | Yes | Yes | No |
| AckLow | 0x07 | Yes | Yes | No |
| Init | 0x08 | No | Yes | No |

### 4.3 Handshake Sequence
```
Client → Server: Init0 (version, timestamp, random0)
Server → Client: Init1 (random1, random0_r)
Client → Server: Init2 (version, random1, random0_r)
Server → Client: Init3 (x, n, level, random2)  [RSA puzzle]
Client → Server: Init4 (x, n, level, random2, y, clientinitiv)
Server → Client: initivexpand2 (beta, omega, proof, license)
Client → Server: clientek (ek, proof)
Server → Client: initserver
Server → Client: channellist...channellistfinished
Server → Client: notifycliententerview...
```

### 4.4 Encryption
- **Algorithm**: AES-128-EAX (AES-128-CTR + OMAC)
- **Key derivation**: SHA-256(direction | type | generation_id | shared_iv)
- **Shared IV**: SHA-512(ECDH shared secret) XOR alpha/beta
- **MAC**: 8 bytes (EAX tag)

---

## 5. Data Structures

### 5.1 Core Types (from shared/src/types.rs)
```rust
ClientId(u16)        // Client identifier
ChannelId(u64)       // Channel identifier  
ServerGroupId(u64)   // Server group identifier
ClientDbId(u64)      // Client database identifier
Uid(String)          // Unique identifier (base64)
PermissionId(u32)    // Permission identifier
```

### 5.2 Database Schema (from tsdb/src/lib.rs)
```sql
CREATE TABLE identities (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    private_key TEXT NOT NULL,
    counter INTEGER DEFAULT 0,
    max_counter INTEGER DEFAULT 0,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

CREATE TABLE bookmarks (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    address TEXT NOT NULL,
    port INTEGER DEFAULT 9987,
    nickname TEXT,
    server_password TEXT,
    channel TEXT,
    channel_password TEXT,
    auto_connect INTEGER DEFAULT 0,
    last_connected TEXT,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    server_address TEXT NOT NULL,
    invoker_id INTEGER NOT NULL,
    invoker_name TEXT NOT NULL,
    invoker_uid TEXT NOT NULL,
    target_type TEXT NOT NULL,
    target_id INTEGER,
    message TEXT NOT NULL,
    is_read INTEGER DEFAULT 0,
    timestamp TEXT NOT NULL
);

CREATE TABLE settings (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    updated_at TEXT NOT NULL
);
```

---

## 6. Test Results

### 6.1 Unit Tests (32 tests passing)
```
tscore::protocol::tests - 14 tests
  ✓ test_packet_type_conversion
  ✓ test_flags
  ✓ test_header_c2s
  ✓ test_header_s2c
  ✓ test_in_packet_parse
  ✓ test_out_packet
  ✓ test_command_parse
  ✓ test_command_serialize
  ✓ test_command_builder
  ✓ test_escape_sequences
  ✓ test_init_packet_parse
  ✓ test_init_packet_serialize
  ✓ test_ack_packet
  ✓ test_packet_type_properties

tscore::crypto::tests - 12 tests
  ✓ test_sha1, test_sha256, test_sha512
  ✓ test_hash_password
  ✓ test_create_key_nonce
  ✓ test_create_encryption_key
  ✓ test_shared_secret_old, test_shared_secret_new
  ✓ test_key_cache
  ✓ test_eax_encrypt_decrypt
  ✓ test_fake_encrypt_decrypt
  ✓ test_hash_cash_level
  ✓ test_compute_uid

tscore::connection::tests - 6 tests
  ✓ test_encode_version
  ✓ test_rsa_puzzle
  ✓ test_resend_manager
  ✓ test_rtt_estimator
  ✓ test_sent_packet_retry
```

---

## 7. Constraints

### 7.1 Technical Constraints
- Rust edition 2021
- Tauri v2 for desktop/mobile
- Must maintain TS3 protocol compatibility
- UDP transport only (no TCP fallback)

### 7.2 Legal Constraints
- TeamSpeak is a trademark of TeamSpeak Systems GmbH
- Implementation is for educational/research purposes
- No server-side code (client-only)

---

## 8. References

1. TS3 Protocol Paper (`refercence/tsdeclarations/ts3protocol.md`)
2. Packet Definitions (`refercence/tsdeclarations/Packets.txt`)
3. Message Definitions (`refercence/tsdeclarations/Messages.toml`)
4. tsclientlib implementation (`refercence/tsclientlib/`)
5. Qint implementation (`refercence/Qint/`)