# Kecalek iOS — Architecture & Features

**Version:** 0.8.5
**Platform:** iOS 26+ / Swift 6
**Files:** 57 Swift source files

---

## Project Structure

```
Kecalek/
├── KecalekApp.swift          # App entry point, tab navigation
├── AppState.swift             # Login state, connection monitoring, reconnection
├── Core/
│   ├── ChatClient.swift       # Main actor — all server communication & crypto (3400+ lines)
│   ├── KeyStorage.swift       # Persistent key storage (RSA, Ed25519, sessions, TOFU)
│   ├── KeychainService.swift  # Secure credential storage (biometric auth)
│   └── MessageCache.swift     # Encrypted message cache (per-conversation)
├── Crypto/
│   ├── CryptoUtils.swift      # AES-256-GCM, HKDF, chain KDF, local encryption
│   ├── DoubleRatchet.swift    # Signal Double Ratchet (DM encryption)
│   ├── X3DH.swift             # Extended Triple Diffie-Hellman (session init)
│   ├── SenderKeyState.swift   # Sender Key chains (group encryption)
│   ├── Ed25519Crypto.swift    # Identity key generation & signing
│   ├── X25519Crypto.swift     # DH key agreement & Ed25519↔X25519 conversion
│   ├── RSACrypto.swift        # RSA-2048 key generation, PKCS#1/PKCS#8
│   ├── KeyEncryption.swift    # ECP1 format: PBKDF2 600K + AES-GCM key encryption
│   ├── FieldArithmetic.swift  # GF(2^255-19) for Ed25519→X25519 conversion
│   ├── MessagePadding.swift   # Bucket-based padding (64B–64KB) for metadata privacy
│   ├── ContactVerification.swift # Fingerprints, safety numbers, QR codes
│   └── CryptoErrors.swift     # Error types
├── Network/
│   ├── ConnectionManager.swift # TCP/TLS via Network.framework (actor)
│   └── ProtocolHandler.swift   # Newline-delimited JSON encoding/decoding
├── Models/
│   ├── Message.swift          # Message, reactions, replies, pins, files, images
│   ├── Conversation.swift     # Conversation, members, group detection
│   ├── User.swift             # User, UserProfile
│   ├── DeviceBundle.swift     # X3DH key bundle per device
│   └── Invitation.swift       # Group invitation
├── ViewModels/
│   ├── AuthViewModel.swift    # Login, register, pairing, biometrics
│   ├── ChatViewModel.swift    # Messages, sending, search, reactions, pins
│   ├── ConversationListVM.swift # Conversations, online users, favorites, avatars
│   ├── ProfileViewModel.swift # Profile editing, avatar upload
│   └── VerificationVM.swift   # Safety numbers, QR verification
├── Views/
│   ├── Auth/                  # LoginView, RegisterView, PairingView, AuthorizeDeviceView
│   ├── Chat/                  # ChatView, MessageBubbleView, MessageInputView, etc.
│   ├── Components/            # CircularAvatarView, ConnectionIndicator, OnlineDotOverlay
│   ├── Conversations/         # ConversationListView, ConversationRowView, NewConversationSheet
│   ├── Groups/                # GroupInfoView, InvitationBanner, CreateGroupSheet
│   ├── Profile/               # ProfileView, EditProfileView
│   └── Verification/          # SafetyNumberView, QRCodeScannerView, VerificationStatusView
└── Utilities/
    ├── Constants.swift        # Version, limits, timeouts, server defaults, crypto params
    └── Extensions.swift       # Data hex/base64, DateParsing, Dictionary helpers
```

---

## Architecture

### Pattern: MVVM + Actor Isolation

- **Views** — SwiftUI, declarative UI, bind to `@Observable` ViewModels
- **ViewModels** — `@Observable final class`, business logic, async operations
- **ChatClient** — `actor`, single source of truth for all crypto & network ops
- **Models** — plain `struct`s with `Identifiable`, `Codable`

### Concurrency Model

- `ChatClient` is an **actor** — all crypto state (keys, sessions, ratchets) is thread-safe
- All network calls use `async/await`
- Real-time notifications via `AsyncStream<ChatNotification>` (multiple subscribers)
- Background tasks: avatar loading, reconnection, notification listening

### Connection Lifecycle

```
App Launch → Login (RSA challenge-response) → TCP/TLS connected
         → Background listener loop reads messages continuously
         → Notifications broadcast via AsyncStream to all subscribers
         → On disconnect: exponential backoff reconnect (1s → 30s, 5 attempts)
         → On auth failure: immediate logout (keys rotated)
         → On foreground: check connection health, reconnect if stale (>30s)
```

---

## Encryption (Signal Protocol)

### Key Types

| Key | Algorithm | Size | Purpose |
|-----|-----------|------|---------|
| RSA | RSA-2048 | 256B | Login authentication (challenge-response) |
| Identity Key (IK) | Ed25519 | 32B | Long-term identity, signs SPK |
| Signed Pre-Key (SPK) | X25519 | 32B | Medium-term, rotated every 7 days |
| One-Time Pre-Keys (OPKs) | X25519 | 32B each | Single-use, batch of 50, replenish at 20 |
| Ratchet Keys | X25519 | 32B | Ephemeral per DH ratchet step |
| Sender Keys | Random | 32B | Per-group, per-sender chain key |

### DM Encryption (X3DH + Double Ratchet)

1. **Session Init (X3DH):**
   - Alice computes: DH(IK_A, SPK_B) || DH(EK_A, IK_B) || DH(EK_A, SPK_B) || DH(EK_A, OPK_B)
   - HKDF-SHA256 derives 32-byte shared secret
   - Double Ratchet initialized

2. **Message Encryption (Double Ratchet):**
   - Root key → chain key → message key (HKDF chain)
   - DH ratchet step on each direction change
   - AES-256-GCM with derived message key
   - AAD: ratchet header (dh_pub, n, pn)
   - Max skip: 256 messages

3. **Message Format:**
   ```
   plaintext → MessagePadding.pad() → AES-256-GCM encrypt → base64 → JSON
   ```

### Group Encryption (Sender Keys)

1. Each member maintains own sender key chain
2. Sender key distributed to all members via pairwise Double Ratchet DMs
3. Messages encrypted with AES-256-GCM using derived chain key
4. Chain ID = SHA-256(sender_key) for verification
5. Max skip: 256 messages per chain

### Message Padding

Bucket sizes: `64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536` bytes

```
Format: 0x01 | plaintext | random_padding | pad_length (4B big-endian)
```

All messages padded to nearest bucket size — prevents metadata analysis of message lengths.

### Self-Encryption

- Derived from identity private key via HKDF
- Encrypts own message copies for multi-device access
- Static key — same across all user's devices

### Contact Verification (TOFU)

- **Fingerprint:** Iterated SHA-512 (5200 rounds) over identity key
- **Safety Number:** 60 digits (12 groups of 5), deterministic ordering by userId
- **QR Code:** Binary `version(1B) + uid_len(1B) + uid + identity_key(32B)`
- **TOFU Registry:** Track first-seen identity keys, alert on change
- **Verification Status:** unverified → trusted (TOFU) → verified (manual/QR)

---

## Features

### Authentication & Accounts

- [x] **Registration** — email + password + verification code
- [x] **Login** — RSA challenge-response authentication
- [x] **Biometric Login** — Face ID / Touch ID via Keychain
- [x] **PoW Challenge** — SHA-256 proof-of-work during registration surge
- [x] **Brute-Force Lockout** — exponential backoff (2^n seconds, max 300s)
- [x] **Change Username** — update display name
- [x] **Change Password** — re-encrypt RSA + Ed25519 keys with new PBKDF2 password
- [x] **Key Rotation** — regenerate all keys with grace period for in-flight sessions
- [x] **Logout** — clean disconnect, clear session

### Multi-Device

- [x] **Device Pairing** — authorize new device via pairing flow
- [x] **Device List** — view all authorized devices
- [x] **Device Removal** — revoke device authorization
- [x] **Self-Encryption** — own messages readable on all devices

### Messaging

- [x] **Text Messages** — encrypted DM and group messages
- [x] **Message Replies** — reply-to with visual indicator
- [x] **Reactions** — 6 emoji reactions (👍❤️😂😮😢👎) with toggle
- [x] **Message Pinning** — pin/unpin with pinned messages sheet
- [x] **Message Deletion** — soft delete with "Message deleted" indicator
- [x] **Message Forwarding** — forward to any conversation with source attribution
- [x] **Message Search** — full-text search with result navigation (prev/next)
- [x] **Read Receipts** — track who read each message
- [x] **Delivery Receipts** — sent → delivered → read indicators (checkmarks)
- [x] **Incremental Sync** — fetch only new messages via `after_ts`
- [x] **Deleted Sync** — `get_deleted_since` for incremental deletion sync
- [x] **Message Padding** — metadata privacy via bucket-based padding

### Media & Files

- [x] **Image Upload** — encrypt + chunked upload (24KB chunks)
- [x] **Image Thumbnails** — base64 JPEG preview inline
- [x] **Image Viewer** — full-screen with pinch zoom
- [x] **File Upload** — any file type with mime detection
- [x] **File Download** — decrypt + share via system share sheet
- [x] **File Icons** — type-based system icons (PDF, DOC, ZIP, etc.)

### Conversations

- [x] **Direct Messages** — 1-on-1 encrypted chat
- [x] **Group Conversations** — multi-member with Sender Keys
- [x] **Create Conversation** — new DM or group
- [x] **Rename Conversation** — group rename (creator only)
- [x] **Delete Conversation** — remove DM or delete group
- [x] **Favorites** — pin conversations to top with star icon
- [x] **Unread Counts** — per-conversation badge
- [x] **Online Status** — real-time presence (green dot)

### Group Management

- [x] **Add Member** — by email
- [x] **Remove Member** — creator only
- [x] **Leave Group** — with confirmation
- [x] **Group Avatar** — upload/change group photo
- [x] **Group Rename** — change group name
- [x] **Group Invitations** — accept/decline with banner UI

### Profile

- [x] **User Profile** — username, email, phone, location
- [x] **Avatar** — upload/change profile photo
- [x] **Field Visibility** — toggle phone/location visibility
- [x] **View Other Profiles** — see other users' info (respects visibility)

### Contact Verification

- [x] **Safety Numbers** — 60-digit verification code per contact pair
- [x] **Fingerprints** — identity key fingerprints
- [x] **QR Code Generation** — generate scannable verification QR
- [x] **QR Code Scanning** — camera-based QR scan for verification
- [x] **Verification Status** — verified (green) / trusted (blue) / unverified (gray)
- [x] **TOFU Registry** — track identity key first-seen, detect changes
- [x] **Shield Icon** — verification badge in chat toolbar

### Connection & Reliability

- [x] **TCP/TLS** — Network.framework with optional TLS
- [x] **Configurable Server** — host, port, TLS toggle in login screen
- [x] **Connection Indicator** — visual status (disconnected/connecting/connected)
- [x] **Auto-Reconnect** — exponential backoff (1s → 30s, 5 attempts)
- [x] **Background/Foreground Handling** — reconnect when returning from background
- [x] **Auth Failure Detection** — immediate logout on key rotation

### Caching & Storage

- [x] **Message Cache** — encrypted per-conversation cache on disk
- [x] **Avatar Cache** — disk + in-memory cache
- [x] **Conversation Cache** — cached list for instant UI
- [x] **Session Persistence** — Double Ratchet states saved encrypted
- [x] **Sender Key Persistence** — group key chains saved encrypted
- [x] **Device Bundle Cache** — 5-minute TTL in-memory
- [x] **Keychain Storage** — biometric-protected credentials

---

## Network Protocol

### Transport

```
TCP → optional TLS → Newline-delimited JSON (\n terminated)
```

### Message Format

```json
{"type": "send_message", "request_id": "uuid", "conversation_id": "...", "ciphertext": "base64..."}
```

### API Methods (36 endpoints)

**Auth:** `register`, `register_confirm`, `login_start`, `login_finish`, `change_username`, `change_password`

**Keys:** `get_key_bundle`, `ensure_prekeys`, `get_prekey_count`, `rotate_keys`, `reset_session`

**Messaging:** `send_message`, `get_messages`, `delete_message`, `mark_read`, `mark_conversation_read`, `react_message`, `pin_message`, `get_pinned_messages`, `get_deleted_since`, `forward_message`, `confirm_delivery`, `search_messages`

**Conversations:** `list_conversations`, `create_conversation`, `find_conversation`, `delete_conversation`, `rename_conversation`, `add_member`, `remove_member`, `leave_group`, `accept_invitation`, `decline_invitation`, `list_invitations`

**Profiles:** `get_profile`, `update_profile`, `update_avatar`, `get_avatar`, `update_group_avatar`, `get_group_avatar`

**Files:** `upload_file`, `download_file`

**Devices:** `list_devices`, `remove_device`, `pairing_start`, `pairing_wait`, `authorize_device`

### Notification Types (17 real-time events)

```
new_message, messages_read, message_deleted, message_reacted,
message_pinned, message_unpinned, message_delivered,
conversation_created, conversation_renamed, conversation_deleted,
member_added, member_removed, group_invitation,
user_online, user_offline, online_users,
session_reset, keys_updated
```

---

## Storage Layout

```
~/Library/Application Support/EncryptedChat/{email}/
├── private.pem                    # RSA private key (password-protected)
├── public.pem                     # RSA public key
├── identity_private.bin           # Ed25519 private (ECP1: PBKDF2 + AES-GCM)
├── identity_public.bin            # Ed25519 public
├── spk_private.bin                # Current signed pre-key (X25519)
├── spk_id.txt                     # SPK ID
├── prevspk_private.bin            # Previous SPK (grace period)
├── prevspk_id.txt
├── opk_{id}.bin                   # One-time pre-keys
├── sessions/
│   └── {userId}_{deviceId}.bin    # Double Ratchet state (encrypted)
├── sender_keys/
│   └── {convId}_{senderId}_{deviceId}.bin  # Sender Key chain (encrypted)
├── message_cache/
│   └── {convId}.json              # Message cache (encrypted)
├── conversations_cache.json       # Conversation list cache (encrypted)
├── avatars/
│   └── {convId}.bin               # Avatar image data (encrypted)
├── known_identity_keys.bin        # TOFU registry (encrypted)
├── verified_contacts.bin          # Verified contacts (encrypted)
└── favorites.bin                  # Favorite conversation IDs (encrypted)
```

---

## Build

```bash
# Xcode build
open /Users/filip/Desktop/kecalek_ios/Kecalek/Kecalek.xcodeproj

# Command-line build
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
xcodebuild -scheme Kecalek \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  build
```

**Result:** 57 files, 0 errors, 0 warnings.