# RangerBlock Secure Communication Contracts Plan

## CODENAME: SENTINEL COMMS PROTOCOL

**Author**: David Keane (IrishRanger) + Claude Code (Ranger)
**Date**: 2025-12-04
**Status**: PLANNING
**Classification**: PRIVATE

---

## Overview

Smart contracts for secure, identity-verified communication channels. These contracts ensure users are **99.99% certain** they're communicating with the intended person through cryptographic identity verification.

### The Problem

In regular chat apps:
- Anyone can pretend to be someone else
- Man-in-the-middle attacks possible
- No proof of who you're really talking to
- Impersonation is easy

### The Solution

**Blockchain-verified identity handshakes** before sensitive communications:
1. Both parties prove identity via on-chain signatures
2. Challenge-response authentication
3. Session keys derived from verified identities
4. Immutable audit trail of who talked to whom

---

## Three Communication Contracts

### 1. RangerTextChat Contract (WHISPER PROTOCOL)

**Purpose**: Secure text messaging with identity verification

```
Flow:
1. Alice wants to chat with Bob
2. Alice creates ChatSession request on-chain
3. Bob sees request, verifies Alice's on-chain identity
4. Bob accepts with signature proving he's real Bob
5. Both derive shared session key
6. E2E encrypted text chat begins
7. Session recorded on blockchain (not content!)
```

**Features**:
- Identity verification before first message
- E2E encryption with verified keys
- Session expiry (configurable)
- Block/report with on-chain evidence
- Message receipts (delivered/read) optional

**Contract Data**:
```rust
struct TextChatSession {
    session_id: [u8; 32],
    initiator_id_hash: [u8; 32],
    responder_id_hash: [u8; 32],
    initiator_pubkey: [u8; 32],      // For E2E encryption
    responder_pubkey: [u8; 32],
    created_at: i64,
    expires_at: i64,
    status: SessionStatus,           // Pending/Active/Ended/Blocked
    initiator_signature: [u8; 64],
    responder_signature: [u8; 64],
}
```

---

### 2. RangerVoiceChat Contract (ECHO PROTOCOL)

**Purpose**: Secure voice calls with identity verification

```
Flow:
1. Alice initiates voice call to Bob
2. Contract creates VoiceSession with Alice's signature
3. Bob receives call notification
4. Bob verifies Alice's on-chain identity
5. Bob answers with his signature
6. DTLS/SRTP keys exchanged using verified identities
7. Encrypted voice call begins
8. Call metadata recorded (duration, not content)
```

**Features**:
- Pre-call identity verification
- Secure key exchange
- Call duration tracking
- Missed call logging
- Do Not Disturb status checking
- Group call support (future)

**Contract Data**:
```rust
struct VoiceCallSession {
    call_id: [u8; 32],
    caller_id_hash: [u8; 32],
    callee_id_hash: [u8; 32],
    caller_signature: [u8; 64],
    callee_signature: [u8; 64],
    call_started: i64,
    call_ended: i64,
    duration_seconds: u64,
    status: CallStatus,              // Ringing/Active/Ended/Missed/Rejected
    quality_rating: u8,              // Optional 1-5 rating
}
```

---

### 3. RangerVideoChat Contract (VISION PROTOCOL)

**Purpose**: Secure video calls with identity verification

```
Flow:
1. Alice initiates video call to Bob
2. Contract creates VideoSession with Alice's signature
3. Bob receives notification + Alice's verified identity
4. Bob can see Alice's on-chain profile before answering
5. Bob answers with signature proving identity
6. WebRTC connection established with verified DTLS fingerprints
7. Encrypted video call begins
8. Call metadata recorded on-chain
```

**Features**:
- Face-to-verified-identity confirmation
- Bandwidth/quality negotiation
- Screen sharing flag
- Recording consent flag (both must agree)
- Virtual background support flag
- Group video support (future)

**Contract Data**:
```rust
struct VideoCallSession {
    call_id: [u8; 32],
    caller_id_hash: [u8; 32],
    callee_id_hash: [u8; 32],
    caller_signature: [u8; 64],
    callee_signature: [u8; 64],
    call_started: i64,
    call_ended: i64,
    duration_seconds: u64,
    status: CallStatus,
    // Video-specific
    screen_shared: bool,
    recording_consent: bool,         // Both agreed to record
    max_resolution: u16,             // 720, 1080, etc.
}
```

---

## Identity Verification Flow (All Contracts)

```
┌─────────────────────────────────────────────────────────────┐
│                   IDENTITY VERIFICATION                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. CHECK ON-CHAIN REGISTRATION                              │
│     └─> User must have RangerRegistration approved           │
│                                                              │
│  2. CHALLENGE-RESPONSE                                       │
│     └─> Contract generates random nonce                      │
│     └─> User signs nonce with private key                    │
│     └─> Contract verifies signature matches on-chain pubkey  │
│                                                              │
│  3. HARDWARE BINDING (Optional Extra Security)               │
│     └─> Include hardware fingerprint in signature            │
│     └─> Prevents key theft (key only works on original HW)   │
│                                                              │
│  4. SESSION ESTABLISHMENT                                    │
│     └─> Both parties verified                                │
│     └─> Session keys derived                                 │
│     └─> Communication begins                                 │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

---

## Why 99.99% Certainty?

| Security Layer | What It Proves |
|----------------|----------------|
| On-chain registration | User went through registration process |
| Hardware ID binding | Using the same physical device |
| RSA signature | Has the private key (not just username) |
| Challenge-response | Key is available NOW (not stolen earlier) |
| Session signature | Both parties actively participating |

**The 0.01%**:
- Physical device theft + password compromise
- Quantum computer breaking RSA (future concern)
- Zero-day in cryptographic libraries

---

## Implementation Phases

### Phase 1: Text Chat Contract (WHISPER)
- [ ] Create Solana `ranger_text_chat.rs`
- [ ] Create Ethereum `RangerTextChat.sol`
- [ ] Add to RangerChat Lite settings
- [ ] Integrate with existing chat

### Phase 2: Voice Chat Contract (ECHO)
- [ ] Create Solana `ranger_voice_chat.rs`
- [ ] Create Ethereum `RangerVoiceChat.sol`
- [ ] Build voice-chat.cjs integration
- [ ] Add to RangerChat Lite (future)

### Phase 3: Video Chat Contract (VISION)
- [ ] Create Solana `ranger_video_chat.rs`
- [ ] Create Ethereum `RangerVideoChat.sol`
- [ ] Build WebRTC integration
- [ ] Add to RangerChat Lite (future)

### Phase 4: Unified Communications
- [ ] Single "Secure Call" button
- [ ] Auto-negotiate voice/video
- [ ] Group calls support
- [ ] Cross-platform (desktop, mobile, web)

---

## UI/UX in RangerChat Lite

### Before Call/Chat:

```
┌──────────────────────────────────────┐
│  🔐 VERIFYING IDENTITY...            │
│                                      │
│  Checking: IrishRanger               │
│                                      │
│  ✓ On-chain registration verified    │
│  ✓ Hardware ID matches               │
│  ✓ Signature valid                   │
│  ⏳ Waiting for response...          │
│                                      │
│  [Cancel]                            │
└──────────────────────────────────────┘
```

### After Verification:

```
┌──────────────────────────────────────┐
│  ✅ IDENTITY VERIFIED                │
│                                      │
│  You are talking to:                 │
│  IrishRanger (David Keane)           │
│                                      │
│  🔒 This session is secured by:      │
│  • Blockchain verification           │
│  • End-to-end encryption             │
│  • Hardware-bound keys               │
│                                      │
│  Session ID: 0x7f3a...               │
│  Expires: 24 hours                   │
│                                      │
│  [Continue to Chat] [View Details]   │
└──────────────────────────────────────┘
```

---

## Security Benefits

| Feature | Benefit |
|---------|---------|
| No impersonation | Can't fake blockchain signatures |
| Audit trail | Know who talked when (not what) |
| Non-repudiation | Can't deny starting a session |
| Key exchange | Verified keys, no MITM |
| Session expiry | Limits exposure window |
| Revocation | Admin can revoke bad actors |

---

## Integration with Existing Contracts

```
RangerRegistration  ─────┐
                         │
RangerTextChat     ──────┼──── All require valid registration
                         │
RangerVoiceChat    ──────┤
                         │
RangerVideoChat    ──────┘

RangerBridge  ─────> Optional: Pay for premium features with RangerCoin
```

---

## Files to Create (Future)

| File | Location | Purpose |
|------|----------|---------|
| `ranger_text_chat.rs` | `Blockchain/contracts/solana/` | Solana text chat |
| `ranger_voice_chat.rs` | `Blockchain/contracts/solana/` | Solana voice chat |
| `ranger_video_chat.rs` | `Blockchain/contracts/solana/` | Solana video chat |
| `RangerTextChat.sol` | `Blockchain/contracts/` | Ethereum text chat |
| `RangerVoiceChat.sol` | `Blockchain/contracts/` | Ethereum voice chat |
| `RangerVideoChat.sol` | `Blockchain/contracts/` | Ethereum video chat |
| `secure-comm-service.cjs` | `rangerblock/lib/` | JS integration |

---

## Motto

> "Trust, but verify... on the blockchain!"

---

## Authors
- David Keane (IrishRanger) - Supreme Commander
- Claude Code (Ranger) - AI Operations Commander

Rangers lead the way! 🎖️