Error Handling & Recovery

┌─────────────────────────────────────────────────────────────┐
│ ZentalkError (base)                                          │
├─────────────────────────────────────────────────────────────┤
│  ├── NetworkError                                            │
│  │    ├── TimeoutError                                       │
│  │    ├── ConnectionError                                    │
│  │    ├── DNSError                                           │
│  │    └── TLSError                                           │
│  │                                                           │
│  ├── CryptoError                                             │
│  │    ├── DecryptionError                                    │
│  │    ├── SignatureError                                     │
│  │    ├── MACError                                           │
│  │    └── KeyError                                           │
│  │                                                           │
│  ├── ProtocolError                                           │
│  │    ├── StateError                                         │
│  │    ├── VersionError                                       │
│  │    ├── SequenceError                                      │
│  │    └── HandshakeError                                     │
│  │                                                           │
│  └── StorageError                                            │
│       ├── QuotaError                                         │
│       ├── CorruptionError                                    │
│       ├── AccessError                                        │
│       └── TransactionError                                   │
└─────────────────────────────────────────────────────────────┘

Retry Algorithm:

1. Initialize:
   base_delay = 1 second
   max_delay = 30 seconds
   max_attempts = 10
   attempt = 0

2. On failure:
   if attempt >= max_attempts:
       return PERMANENT_FAILURE

   delay = min(base_delay * (2 ^ attempt), max_delay)
   jitter = random(0, delay * 0.1)
   actual_delay = delay + jitter

   wait(actual_delay)
   attempt = attempt + 1
   retry_operation()

3. On success:
   reset attempt counter
   resume normal operation

Offline Queue Structure:

┌─────────────────────────────────────────────────────────────┐
│ Queue Entry                                                  │
├─────────────────────────────────────────────────────────────┤
│ message_id      │ UUID                                       │
│ recipient       │ Wallet address                             │
│ encrypted_data  │ Pre-encrypted message blob                 │
│ created_at      │ Unix timestamp (ms)                        │
│ attempts        │ Retry count                                │
│ last_attempt    │ Last retry timestamp                       │
│ priority        │ HIGH / NORMAL / LOW                        │
│ expires_at      │ TTL expiration timestamp                   │
└─────────────────────────────────────────────────────────────┘

Reconnection State Machine:

┌───────────┐     network lost     ┌──────────────┐
│ CONNECTED │─────────────────────→│ DISCONNECTED │
└───────────┘                      └──────────────┘
      ↑                                   │
      │                                   │ start backoff
      │                                   ↓
      │ success                    ┌──────────────┐
      └────────────────────────────│ RECONNECTING │←─┐
                                   └──────────────┘  │
                                          │          │
                                          │ failure  │
                                          └──────────┘

Decryption Failure Decision Tree:

1. Decryption fails with current receiving chain key
   │
   ├─→ Check skipped message keys
   │   │
   │   ├─→ Found: Decrypt with skipped key, delete key
   │   │
   │   └─→ Not found: Continue to step 2
   │
2. Check if message contains new DH ratchet key
   │
   ├─→ Yes: Attempt DH ratchet step
   │   │
   │   ├─→ Success: Decrypt with new chain
   │   │
   │   └─→ Failure: Continue to step 3
   │
   └─→ No: Continue to step 3
   │
3. Increment failure counter for this session
   │
   ├─→ Counter < 3: Request message resend
   │
   ├─→ Counter >= 3: Trigger session reset
   │
   └─→ Counter >= 5: Flag as potential attack

MAC Failure Response:

1. IMMEDIATELY discard message
2. Do NOT attempt alternative decryption
3. Do NOT advance ratchet state
4. Log security event:
   {
     type: "MAC_FAILURE",
     peer: <address>,
     timestamp: <now>,
     message_header: <non-sensitive portion>
   }
5. Increment MAC failure counter
6. If counter >= 2 in 1 hour:
   - Flag session as potentially compromised
   - Notify user with security warning
   - Recommend session reset

State Recovery Matrix:

Current          Expected         Recovery Action
─────────────────────────────────────────────────
NO_SESSION       ESTABLISHED      Initiate X3DH
PENDING          ESTABLISHED      Wait or retry X3DH
ESTABLISHED      NO_SESSION       Accept (peer reset)
CLOSED           Any active       Create new session
Invalid/Corrupt  Any              Force reset

Version Negotiation:

1. Client sends supported_versions: [1.0, 1.1, 2.0]
2. Server selects highest common version
3. If no common version:
   Server responds:
   {
     error: "VERSION_MISMATCH",
     server_versions: [3.0, 3.1],
     client_versions: [1.0, 1.1, 2.0],
     upgrade_url: "https://zentalk.io/download"
   }
4. Client notifies user: "Update required"

Scenario 1: Lost Message

Alice                               Bob
──────                              ───
Sends M1 (N=0) ─────────────────→  Receives M1
Sends M2 (N=1) ────────X           (lost in network)
Sends M3 (N=2) ─────────────────→  Receives M3

Bob expects N=1, receives N=2
Detection: Message number gap
Recovery: Bob stores skipped key for N=1

Scenario 2: Lost DH Ratchet

Alice                               Bob
──────                              ───
DH ratchet, sends M1 ──────X        (lost)
Sends M2 ─────────────────────────→ Receives M2

Bob has old DHr, cannot derive correct chain
Detection: Decryption fails with current state
Recovery: Attempt ratchet with received DH key

Scenario 3: State Corruption

Alice                               Bob
──────                              ───
Stores state to disk                Receives message
App crashes before flush            Decrypts successfully
App restarts with old state         Advances ratchet

Alice's state is behind Bob's state
Detection: Multiple decryption failures
Recovery: Session reset required

On message receipt:

1. Extract header: DH_pub, msg_num, prev_chain_len

2. Check for message number gap:
   if msg_num > Nr:
       gap_size = msg_num - Nr
       if gap_size > MAX_SKIP:
           return REJECT_POSSIBLE_DOS
       store_skipped_keys(Nr, msg_num - 1)

3. Check DH key:
   if DH_pub != current_DHr:
       if DH_pub in recent_DH_keys:
           // Out of order from previous chain
           use_previous_chain()
       else:
           // New DH ratchet
           perform_dh_ratchet(DH_pub)

4. Attempt decryption:
   if success:
       clear_failure_counter()
   else:
       increment_failure_counter()
       if failures >= DESYNC_THRESHOLD:
           initiate_recovery()

Desync Recovery Flow:

┌─────────────────┐
│ Desync Detected │
└────────┬────────┘
         │
         ▼
┌─────────────────────────┐
│ failures < 3?           │───Yes───→ Request resend
└───────────┬─────────────┘
            │ No
            ▼
┌─────────────────────────┐
│ Try alternative chains  │
│ (skipped keys, prev DH) │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Alternative succeeded?  │───Yes───→ Resume normal
└───────────┬─────────────┘
            │ No
            ▼
┌─────────────────────────┐
│ Send RESET_REQUEST      │
│ to peer                 │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Await RESET_ACK         │
│ (timeout: 30 seconds)   │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Re-establish session    │
│ via X3DH                │
└─────────────────────────┘

Recovery Message Handling:

1. Before reset:
   - Flush all pending decrypted messages to storage
   - Mark queued outgoing messages as NEEDS_REENCRYPT
   - Record message IDs of failed decryptions

2. After new session established:
   - Re-encrypt and resend queued messages
   - Request resend of failed incoming messages:
     {
       type: "RESEND_REQUEST",
       message_ids: [<list of lost message IDs>],
       reason: "session_reset"
     }

3. Peer responds:
   - Re-encrypts requested messages with new session
   - Marks messages as RESENT to prevent duplicates

Message Delivery State Machine:

┌──────────┐   encrypt    ┌─────────┐   send    ┌────────┐
│ CREATING │─────────────→│ PENDING │──────────→│  SENT  │
└──────────┘              └─────────┘           └────────┘
                               │                    │
                          timeout/error         delivered
                               │                    │
                               ▼                    ▼
                          ┌─────────┐         ┌───────────┐
                          │ FAILED  │         │ DELIVERED │
                          └─────────┘         └───────────┘
                               │                    │
                          retry succeeds        read
                               │                    │
                               ▼                    ▼
                          ┌────────┐           ┌────────┐
                          │  SENT  │           │  READ  │
                          └────────┘           └────────┘

Notification Decision:

1. Message enters FAILED state
2. Determine failure type:
   - Transient (network): "Message will retry when online"
   - Permanent (blocked): "Message could not be delivered"
   - Recoverable (key change): "Recipient's keys changed. Verify and resend?"

3. Display appropriate UI:
   - Transient: Yellow warning icon on message
   - Permanent: Red error icon, tap for details
   - Recoverable: Action prompt with verify option

Quota Exceeded Response:

1. Identify storage consumers:
   - Message history: typically largest
   - Media cache: can be cleared
   - Session state: critical, cannot reduce
   - Logs: can be truncated

2. Execute cleanup strategy:
   Priority 1: Clear media cache
   Priority 2: Compress old messages
   Priority 3: Archive old conversations
   Priority 4: Prompt user for action

3. Cleanup thresholds:
   - At 80% quota: Clear media cache
   - At 90% quota: Archive conversations > 6 months
   - At 95% quota: Notify user, suggest export
   - At 100%: Emergency mode, queue to memory only

Corruption Detection Algorithm:

1. On database open:
   - Verify schema version matches expected
   - Check critical tables exist
   - Validate index structures

2. On read operation:
   if stored_checksum != computed_checksum:
       mark_record_corrupted(record_id)
       attempt_recovery(record_id)

3. Periodic integrity check (weekly):
   for each table:
       for each record:
           validate_structure(record)
           validate_references(record)
           validate_checksum(record)
       report_corruption_rate()

Repair Decision Tree:

┌─────────────────────────┐
│ Corruption Detected     │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Scope Assessment        │
│ (single record/table/DB)│
└───────────┬─────────────┘
            │
   ┌────────┼────────┐
   │        │        │
   ▼        ▼        ▼
┌──────┐ ┌──────┐ ┌──────┐
│Record│ │Table │ │ Full │
└──┬───┘ └──┬───┘ └──┬───┘
   │        │        │
   ▼        ▼        ▼
Restore  Rebuild   Restore
from     from      from
cache    indices   backup

Manual Recovery UI Flow:

1. User accesses Settings → Data Recovery

2. Options presented:
   ┌─────────────────────────────────────────┐
   │ Recovery Options                         │
   ├─────────────────────────────────────────┤
   │ [Attempt Auto-Repair]                    │
   │   Try to fix corruption automatically    │
   │                                          │
   │ [Restore from Backup]                    │
   │   Last backup: 2 hours ago               │
   │                                          │
   │ [Export Available Data]                  │
   │   Save what can be recovered             │
   │                                          │
   │ [Clear All Data]                         │
   │   Start fresh (contacts re-sync)         │
   └─────────────────────────────────────────┘

3. After selection:
   - Confirm destructive actions
   - Show progress indicator
   - Report success/failure
   - Guide next steps

Log Entry Structure:

{
  timestamp: "2024-01-15T10:30:00.000Z",
  level: "ERROR",
  code: "CRYPTO_001",
  message: "Decryption failed",
  context: {
    session_id: "abc123",
    peer: "0x1234...5678",
    message_num: 42,
    attempt: 2
  },
  stack: "<stack trace for DEBUG only>"
}

Circuit Breaker Logic:

state = CLOSED
failure_count = 0
last_failure_time = null

on_operation():
    if state == OPEN:
        if now() - last_failure_time > 60 seconds:
            state = HALF_OPEN
        else:
            return FAIL_FAST

    result = attempt_operation()

    if result == SUCCESS:
        state = CLOSED
        failure_count = 0
    else:
        failure_count += 1
        last_failure_time = now()
        if failure_count >= 5:
            state = OPEN