Protocol Specification

1. On app launch:
   spk_age = current_time - spk_creation_timestamp

   if spk_age >= 7 days:
       trigger_spk_rotation()
   else:
       schedule_timer(7 days - spk_age)

2. Timer fires:
   generate_new_spk()
   sign_spk()
   upload_to_server()
   schedule_next_rotation(7 days)

┌─────────────────────────────────────────────────────────────┐
│ Signed Data Structure                                        │
├─────────────────────────────────────────────────────────────┤
│ Protocol version (1 byte)           │ 0x01                  │
│ SPK public key (32 bytes)           │ X25519 public key     │
│ Timestamp (8 bytes)                 │ Unix epoch (seconds)  │
│ SPK ID (4 bytes)                    │ Unique identifier     │
└─────────────────────────────────────────────────────────────┘

Signature = Ed25519_Sign(IK_private, protocol_version || spk_public || timestamp || spk_id)
Signature length: 64 bytes

SPK storage structure:
{
  current_spk: { private, public, signature, created_at, id },
  previous_spk: { private, public, signature, created_at, id, retained_until }
}

OPK generation:
for i in 0..100:
    keypair = X25519_keygen()
    opk_id = secure_random_u32()
    store_locally(opk_id, keypair.private)
    upload_queue.add(opk_id, keypair.public)

Server-side count tracking:
{
  user_address: "0x...",
  opk_count: 47,
  last_replenishment: 1704067200,
  low_threshold_notified: false
}

Replenishment flow:
1. Server detects opk_count < 20
2. Server sets pending_notification = true
3. On next client connection:
   server sends: { type: "opk_low", current_count: 17 }
4. Client generates: 100 - current_count = 83 new OPKs
5. Client uploads new OPKs
6. Server updates count, clears notification flag

WebSocket notification:
{
  "type": "key_status",
  "opk_count": 17,
  "opk_threshold": 20,
  "action_required": "replenish_opks",
  "timestamp": 1704067200
}

Push notification (if WebSocket unavailable):
{
  "priority": "high",
  "data": {
    "type": "key_maintenance",
    "action": "opk_replenish"
  }
}

Standard X3DH (with OPK):
SK = HKDF(DH1 || DH2 || DH3 || DH4, "ZentalkX3DH")

Fallback X3DH (without OPK):
SK = HKDF(DH1 || DH2 || DH3, "ZentalkX3DHNoOPK")

Key Bundle Structure:
┌─────────────────────────────────────────────────────────────┐
│ Header                                                       │
├─────────────────────────────────────────────────────────────┤
│ Protocol version (1 byte)           │ 0x01                  │
│ Bundle type (1 byte)                │ 0x01 = full           │
│                                     │ 0x02 = OPK only       │
│                                     │ 0x03 = SPK rotation   │
│ Timestamp (8 bytes)                 │ Unix epoch (seconds)  │
├─────────────────────────────────────────────────────────────┤
│ Identity Key Section                                         │
├─────────────────────────────────────────────────────────────┤
│ IK public (32 bytes)                │ Ed25519 public key    │
├─────────────────────────────────────────────────────────────┤
│ Signed Pre-Key Section                                       │
├─────────────────────────────────────────────────────────────┤
│ SPK ID (4 bytes)                    │ Unique identifier     │
│ SPK public (32 bytes)               │ X25519 public key     │
│ SPK signature (64 bytes)            │ Ed25519 signature     │
├─────────────────────────────────────────────────────────────┤
│ One-Time Pre-Keys Section                                    │
├─────────────────────────────────────────────────────────────┤
│ OPK count (2 bytes)                 │ Number of OPKs        │
│ For each OPK:                                                │
│   OPK ID (4 bytes)                  │ Unique identifier     │
│   OPK public (32 bytes)             │ X25519 public key     │
├─────────────────────────────────────────────────────────────┤
│ Kyber Section (if PQC enabled)                               │
├─────────────────────────────────────────────────────────────┤
│ Kyber public key (1,184 bytes)      │ ML-KEM-768            │
└─────────────────────────────────────────────────────────────┘

Upload request:
POST /v1/keys/bundle
Authorization: Bearer <JWT>
Content-Type: application/octet-stream

JWT claims:
{
  "sub": "0x1234...abcd",           // User wallet address
  "iat": 1704067200,                // Issued at
  "exp": 1704067500,                // Expires (5 min)
  "action": "key_upload",
  "bundle_hash": "sha256:abc123..." // Hash of bundle for integrity
}

Signature: Ed25519_Sign(IK_private, JWT_header || JWT_claims)

Server-side transaction:
BEGIN TRANSACTION;
  -- Validate entire bundle first
  VALIDATE bundle_signature;
  VALIDATE spk_signature;
  VALIDATE all opk_ids unique;

  -- Apply updates atomically
  UPDATE identity_keys SET ...;
  UPDATE signed_prekeys SET ...;
  INSERT INTO one_time_prekeys ...;

  -- Only commit if all validations pass
COMMIT;

Version negotiation:
1. Client sends bundle with version = 0x02
2. Server checks supported_versions
3. If server supports 0x02: accept
4. If server only supports 0x01: reject with error
   {
     "error": "unsupported_version",
     "supported": [0x01],
     "requested": 0x02
   }

Validation order (fail-fast):
1. Parse bundle structure
2. Verify protocol version supported
3. Validate timestamp freshness
4. Verify IK matches registered identity
5. Verify SPK signature
6. Check SPK ID uniqueness
7. Check all OPK IDs unique
8. Verify no duplicate OPKs in request
9. Rate limit check
10. Commit to database

Verification steps:
1. Extract signed_data = version || spk_public || timestamp || spk_id
2. Extract signature from bundle
3. Fetch IK_public from user record
4. result = Ed25519_Verify(IK_public, signed_data, signature)
5. If !result: reject("invalid_spk_signature")

Timestamp validation:
current = server_time()
bundle_time = bundle.timestamp

if bundle_time < current - 86400:    // 24 hours
    reject("timestamp_expired")

if bundle_time > current + 300:      // 5 minutes
    reject("timestamp_future")

Rate limit response:
HTTP 429 Too Many Requests
{
  "error": "rate_limited",
  "operation": "spk_rotation",
  "retry_after": 21600,
  "limit": 2,
  "window": 86400
}

Duplicate detection query:
SELECT COUNT(*) FROM one_time_prekeys
WHERE opk_id IN (incoming_ids)
AND user_id != current_user_id;

if count > 0:
    reject("opk_id_collision")
    log_security_event("cross_user_opk_collision", details)

Client-side clock validation:
1. Before upload, fetch server time:
   GET /v1/time -> { "server_time": 1704067200 }

2. Calculate drift:
   drift = abs(local_time - server_time)

3. If drift > 300 seconds:
   warn_user("Clock sync required")
   offer_ntp_sync()

4. Adjust timestamps:
   adjusted_timestamp = local_time - drift

Optimistic locking:
1. Client fetches current bundle_version: 42
2. Client prepares update with expected_version: 42
3. Server checks:
   if current_version != expected_version:
       reject("version_conflict", current_version)
4. Client retries:
   - Fetch latest bundle
   - Merge changes
   - Retry upload with new version

Recovery flow:
1. On app resume after offline:
   offline_duration = current_time - last_active_time

2. If offline_duration > 7 days:
   spk_must_rotate = true

3. If offline_duration > 30 days:
   warn_user("Extended offline period detected")
   recommend_full_key_rotation()

4. Check server for OPK count:
   GET /v1/keys/status
   -> { "opk_count": 3, "spk_valid": false }

5. Execute required maintenance:
   if !spk_valid: rotate_spk()
   if opk_count < 20: replenish_opks(100 - opk_count)

Integrity verification:
1. Local bundle checksum:
   stored_hash = storage.get("bundle_checksum")
   current_hash = SHA-256(serialize(bundle))

   if stored_hash != current_hash:
       corruption_detected = true

2. Key pair validation:
   test_message = random_bytes(32)
   signature = Ed25519_Sign(ik_private, test_message)

   if !Ed25519_Verify(ik_public, test_message, signature):
       key_mismatch = true

3. Recovery procedure:
   if corruption_detected || key_mismatch:
       if backup_available:
           restore_from_encrypted_backup()
       else:
           initiate_full_key_regeneration()
           notify_contacts_of_key_change()

1. Alice fetches Bob's key bundle: IK_B, SPK_B, OPK_B

2. Alice generates ephemeral key pair: EK_A

3. Alice computes DH outputs:
   DH1 = X25519(IK_A, SPK_B)
   DH2 = X25519(EK_A, IK_B)
   DH3 = X25519(EK_A, SPK_B)
   DH4 = X25519(EK_A, OPK_B)    // if OPK available

4. Alice derives shared secret:
   SK = HKDF(DH1 || DH2 || DH3 || DH4, "ZentalkX3DH")

5. Alice sends initial message with:
   - IK_A (her identity key)
   - EK_A (ephemeral public key)
   - OPK_B identifier (which one-time key was used)
   - Encrypted message using SK

Input:  DH outputs (128 bytes)
Salt:   0x00 * 32
Info:   "ZentalkX3DH"
Output: 32 bytes (root key for Double Ratchet)

1. Derive message key:
   MK, CK_new = HKDF(CK, 0x01, "ZentalkChain")

2. Encrypt message:
   ciphertext = AES-256-GCM(MK, nonce, plaintext, AD)

3. Update chain key:
   CK = CK_new

4. Delete message key (forward secrecy)

1. Compute DH output:
   DH_out = X25519(DHs_private, DHr_new)

2. Derive new keys:
   RK_new, CKr_new = HKDF(RK, DH_out, "ZentalkRatchet")

3. Generate new DH keypair:
   DHs_new = X25519_keygen()

4. Compute second DH:
   DH_out2 = X25519(DHs_new_private, DHr_new)

5. Derive sending chain:
   RK_final, CKs_new = HKDF(RK_new, DH_out2, "ZentalkRatchet")

┌────────────┐    initiate()    ┌─────────────┐
│ NO_SESSION │─────────────────→│ INITIATING  │
└────────────┘                  └─────────────┘
      ↑                               │
      │ reset()                       │ X3DH complete
      │                               ↓
┌────────────┐    timeout       ┌─────────────┐
│   CLOSED   │←─────────────────│   PENDING   │
└────────────┘                  └─────────────┘
      ↑                               │
      │ close()                       │ first DR message received
      │                               ↓
┌────────────┐    no activity   ┌─────────────┐
│   STALE    │←─────────────────│ ESTABLISHED │
└────────────┘   (30 days)      └─────────────┘
      │                               ↑
      └───────────────────────────────┘
              any message

Alice (Initiator)                          Bob (Responder)
─────────────────                          ───────────────
1. Generate EK_A
2. Fetch Bob's key bundle
3. Compute SK = X3DH(...)
4. Initialize DR state:
   - RK = SK
   - DHs = EK_A (reused)
   - DHr = SPK_B
   - CKs = HKDF(RK, DH(DHs, DHr))
   - CKr = null (not yet known)
   - Ns = 0, Nr = 0, PN = 0

5. Send first message:
   [IK_A, EK_A, OPK_id, DR_msg_0]
                                           6. Receive message
   ─────── X3DH ENDS HERE ───────          7. Verify IK_A, look up OPK
                                           8. Compute SK = X3DH(...)
                                           9. Initialize DR state:
                                              - RK = SK
                                              - DHs = generate new
                                              - DHr = EK_A
                                              - CKr = HKDF(RK, DH(DHr, DHs))
                                              - CKs = null
                                              - Ns = 0, Nr = 0, PN = 0
                                           10. Decrypt DR_msg_0
                                           11. Delete OPK_B (one-time use)

   ─────── DR BEGINS HERE ───────

                                           12. Send reply with new DHs:
                                               [DR_msg_1]
13. Receive DR_msg_1
14. DH ratchet with Bob's new DHs
15. Both sides now in full DR mode

┌─────────────────────────────────────────────────────┐
│ Skipped Keys Store (max 1000 entries)               │
├─────────────────────────────────────────────────────┤
│ Key: (DH_public, message_number)                    │
│ Value: message_key                                  │
│ TTL: 7 days                                         │
├─────────────────────────────────────────────────────┤
│ Example entries:                                    │
│ (0xab12...cd34, 5) → 0x9f8e...7d6c                 │
│ (0xab12...cd34, 6) → 0x1a2b...3c4d                 │
│ (0xef56...gh78, 0) → 0x5e6f...7g8h                 │
└─────────────────────────────────────────────────────┘

1. If (N - M) > MAX_SKIP (1000):
   → REJECT message (potential DoS attack)
   → Do NOT advance ratchet state

2. If (N - M) <= MAX_SKIP:
   → Derive and store keys for messages M through N-1
   → Each key stored as (current_DHr, index)
   → Process message N normally
   → Nr = N + 1

On message receipt:
1. Extract (DH_pub, msg_num) from header

2. Compute message_id = SHA-256(DH_pub || msg_num || ciphertext)

3. Check replay cache:
   if message_id in seen_messages:
       → REJECT (replay attack)

4. If msg_num < Nr and not in skipped_keys:
   → REJECT (already processed or replay)

5. After successful decryption:
   → Add message_id to seen_messages (TTL: 7 days)
   → If from skipped_keys: DELETE the key

Alice (detecting issue)                    Bob
───────────────────────                    ───
1. Detect session problem
   (3+ decrypt failures)

2. Send RESET_REQUEST:
   {
     type: "RESET_REQUEST",
     reason: "decrypt_failure",
     last_successful_msg: <hash>,
     timestamp: <now>,
     signature: Sign(IK_A, payload)
   }
                                           3. Verify signature
                                           4. Validate reason
                                           5. Clear session state
                                           6. Generate fresh key bundle
                                           7. Send RESET_ACK:
                                              {
                                                type: "RESET_ACK",
                                                new_SPK: <public_key>,
                                                new_OPKs: [<keys>],
                                                signature: Sign(IK_B, payload)
                                              }

8. Verify signature
9. Clear local session state
10. Initiate new X3DH with
    fresh key bundle
                                           11. Respond to X3DH

─── New session ESTABLISHED ───

Pre-Reset:
┌─────────────────────────────────────────────┐
│ Message Store (encrypted at rest)           │
├─────────────────────────────────────────────┤
│ Messages are encrypted with:                │
│ storage_key = HKDF(user_password, salt)     │
│                                             │
│ NOT with session keys!                      │
│                                             │
│ This means:                                 │
│ ✓ Messages survive session reset            │
│ ✓ Messages survive device change            │
│ ✓ Messages require user password to access  │
└─────────────────────────────────────────────┘

Reset Process:
1. Export message history (already encrypted)
2. Delete ratchet state (RK, CKs, CKr, etc.)
3. Delete skipped message keys
4. Clear replay cache
5. Reset to NO_SESSION state
6. Message history remains intact
7. Re-establish session via X3DH

                    ┌─────────────────┐
                    │   Bob's Phone   │
                    │ Session: S_bp   │
                    └────────┬────────┘
                             │
┌─────────────┐              │         ┌─────────────┐
│ Alice Phone │──────────────┼────────→│ Bob Tablet  │
│ Session:    │              │         │ Session: S_bt│
│ S_ap_bp     │              │         └─────────────┘
│ S_ap_bt     │              │
│ S_ap_bd     │              │         ┌─────────────┐
└─────────────┘              └────────→│ Bob Desktop │
                                       │ Session: S_bd│
                                       └─────────────┘

Alice's Phone has 3 separate sessions:
- S_ap_bp: with Bob's Phone
- S_ap_bt: with Bob's Tablet
- S_ap_bd: with Bob's Desktop

1. Alice sends message to Bob
2. Server identifies Bob's devices: [Phone, Tablet, Desktop]
3. For each device:
   - If device has session with Alice:
     → Queue encrypted message
   - If no session exists:
     → Queue X3DH initiation request

4. Device comes online:
   - Fetches queued messages
   - Processes in order (by server timestamp)
   - Handles X3DH initiations first

5. Message queue limits:
   - Max 1000 messages per device
   - Max 30 days retention
   - Oldest messages dropped if limit reached

1. User adds new device (Desktop)

2. Desktop generates:
   - New Identity Key? NO - imported from backup
   - New Signed Pre-Key: YES
   - New One-Time Pre-Keys: YES (100)

3. Desktop publishes key bundle to server

4. Existing sessions: NONE
   - Desktop has no sessions with anyone
   - Must wait for incoming X3DH or initiate new

5. When Alice messages Bob:
   - Server sees Bob has new device
   - Alice's client fetches Desktop's key bundle
   - Alice initiates X3DH with Desktop
   - Desktop now has session with Alice

6. Message history:
   - NOT automatically synced
   - User can export/import encrypted backup
   - Or: request history from another device (E2E encrypted)

1. User marks device as lost/stolen

2. Server:
   - Removes device's key bundle
   - Stops routing messages to device
   - Notifies peers: "device removed"

3. Peers:
   - Delete sessions with revoked device
   - Stop encrypting for that device

4. Revoked device:
   - Cannot receive new messages
   - Cannot establish new sessions
   - Existing session keys eventually expire

AD = version || sender_id || recipient_id || timestamp

nonce = secure_random(12)
ciphertext, tag = AES-GCM-Encrypt(key, nonce, plaintext, AD)
output = nonce || ciphertext || tag

1. Standard X3DH:
   SK_classical = X3DH(IK, SPK, OPK, EK)

2. Kyber encapsulation:
   ciphertext, SK_kyber = Kyber.Encapsulate(recipient_kyber_pk)

3. Combined secret:
   SK_hybrid = HKDF(SK_classical || SK_kyber, "ZentalkHybrid")

┌─────────────────────────────────────────┐
│ Version (1 byte)                        │
├─────────────────────────────────────────┤
│ Sender DH Public Key (32 bytes)         │
├─────────────────────────────────────────┤
│ Message Number (4 bytes)                │
├─────────────────────────────────────────┤
│ Previous Chain Length (4 bytes)         │
├─────────────────────────────────────────┤
│ Nonce (12 bytes)                        │
├─────────────────────────────────────────┤
│ Ciphertext (variable)                   │
├─────────────────────────────────────────┤
│ Authentication Tag (16 bytes)           │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ Version (1 byte) = 0x02                 │
├─────────────────────────────────────────┤
│ Sender DH Public Key (32 bytes)         │
├─────────────────────────────────────────┤
│ Kyber Ciphertext (1,088 bytes)          │
├─────────────────────────────────────────┤
│ Message Number (4 bytes)                │
├─────────────────────────────────────────┤
│ Previous Chain Length (4 bytes)         │
├─────────────────────────────────────────┤
│ Nonce (12 bytes)                        │
├─────────────────────────────────────────┤
│ Ciphertext (variable)                   │
├─────────────────────────────────────────┤
│ Authentication Tag (16 bytes)           │
└─────────────────────────────────────────┘

1. User provides password

2. Derive key:
   salt = secure_random(32)
   key = PBKDF2-SHA256(password, salt, 600000)

3. Encrypt key bundle:
   nonce = secure_random(12)
   backup = AES-256-GCM(key, nonce, key_bundle)

4. Store on mesh:
   mesh.store(address, salt || nonce || backup)

1. Fetch backup from mesh

2. Extract salt, nonce, ciphertext

3. Derive key from password:
   key = PBKDF2-SHA256(password, salt, 600000)

4. Decrypt:
   key_bundle = AES-256-GCM-Decrypt(key, nonce, ciphertext)

fingerprint = SHA-256(identity_public_key)
display = format_as_numeric(fingerprint)

37291 84756 19283 04857
29184 73829 18374 02948