Files
CyberRanger/identity/claude/classified/RANGERBLOCK_SECURITY_INTEGRATION_PLAN.md
T
ranger c789f2c68d Add complete CyberRanger research archive — 200 files
- 86 modelfiles: Full system prompt evolution V1-V42.6 (54 extracted from Ollama backup + 32 original Modelfiles)
- 30 training datasets: V6-V22 training JSONs + caring awareness data
- 10 Colab notebooks: Training + merge scripts
- 19 evaluation files: Drift results, ASR charts, verification
- 5 test suites: Injection tests, regression tests
- 4 observations: V24-V33 testing results + visual summaries
- 38 identity files: Claude/Gemini/Ollama identity architecture
- 7 security files: Injection research, manipulation analysis
- 3 psychology files: Psychology Layer, Milgram chapter, David's thoughts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-20 22:36:02 +01:00

657 lines
23 KiB
Markdown

# 🛡️ RANGERBLOCK SECURITY INTEGRATION PLAN
## Project Codename: "SHEPHERD PROTOCOL"
### Unified Identity & Registration System
---
## 1. EXECUTIVE SUMMARY
Implement a unified security and registration system across ALL RangerBlock components:
| Component | Current State | Target State |
|-----------|---------------|--------------|
| **ranger-chat-lite** | Hardware fingerprint + RSA keys (unused) | Full encryption + Commander verification |
| **blockchain-chat.cjs** | Simple nickname only | Hardware ID + persistent identity |
| **voice-chat.cjs** | Simple nickname only | Hardware ID + encrypted voice |
| **server-only** | Does not exist | Centralized auth hub with kill switch |
---
## 2. CURRENT STATE ANALYSIS
### A. ranger-chat-lite (Electron App) ✅ BEST
**Location**: `/Users/ranger/rangerplex-ai/apps/ranger-chat-lite/`
**What It Has**:
```
✅ Hardware fingerprinting (SHA-256 of Hardware UUID + hostname + username)
✅ Persistent identity (user_identity.json)
✅ RSA-2048 keypair generation
✅ Cross-platform support (macOS/Windows/Linux)
✅ IPC API for identity operations
✅ Message statistics tracking
✅ User moderation note (admins can track real identity)
```
**Key Files**:
- `electron/identityService.ts` - Core identity logic (379 lines)
- `electron/main.ts` - IPC handlers
- `electron/preload.ts` - API bridge
**Hardware Fingerprint Code** (identityService.ts:109-173):
```typescript
// macOS: system_profiler SPHardwareDataType → Hardware UUID
// Windows: wmic csproduct get uuid
// Linux: /etc/machine-id
const fingerprint = crypto
.createHash('sha256')
.update(hardwareId + os.hostname() + os.userInfo().username)
.digest('hex')
.substring(0, 32)
```
**What It's Missing**:
```
❌ Password/PIN protection
❌ Message encryption (plain text over ws://)
❌ TLS/WSS (unencrypted WebSocket)
❌ Token-based auth (no JWT/session tokens)
❌ Server-side identity verification
❌ Kill switch integration
```
---
### B. blockchain-chat.cjs (Terminal Chat) ⚠️ BASIC
**Location**: `/Users/ranger/rangerplex-ai/rangerblock/just-chat/blockchain-chat.cjs`
**What It Has**:
```
✅ Basic nickname registration
✅ Machine name detection (getMachineName())
✅ Local IP detection
✅ Channel-based chat (#rangers)
```
**Current Registration** (line 204-216):
```javascript
// Very simple - just sends nickname to server
ws.send(JSON.stringify({
type: 'register',
address: `${nickname}-${Date.now()}`,
nickname: nickname,
channel: DEFAULT_CHANNEL,
ip: getLocalIP(),
port: 0
}));
```
**What It's Missing**:
```
❌ Hardware fingerprinting
❌ Persistent identity file
❌ RSA keypairs
❌ Any form of authentication
❌ TODO at line 412: "Implement challenge-response authentication"
```
---
### C. voice-chat.cjs (Terminal Voice) ⚠️ BASIC
**Location**: `/Users/ranger/rangerplex-ai/rangerblock/just-chat/voice-chat.cjs`
**What It Has**:
```
✅ Same basic registration as blockchain-chat
✅ Voice call states (IDLE, CALLING, RINGING, IN_CALL, IN_GROUP)
✅ Audio compression with zlib
✅ Private calls + group voice
```
**What It's Missing**:
```
❌ Hardware fingerprinting
❌ Persistent identity
❌ Voice encryption (just zlib compression, not crypto)
❌ Call authentication (anyone can call anyone)
```
---
### D. server-only (Planned) 🆕 NOT BUILT
**Location**: `/Users/ranger/rangerplex-ai/rangerblock/server-only/` (to be created)
**Purpose**: Centralized authentication hub + kill switch controller
---
## 3. TARGET ARCHITECTURE
```
┌─────────────────────────────────────────────────────────────────────┐
│ RANGERBLOCK SECURITY LAYER │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ranger-chat- │ │ blockchain- │ │ voice-chat │ │
│ │ lite │ │ chat.cjs │ │ .cjs │ │
│ │ (Electron) │ │ (Terminal) │ │ (Terminal) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ SHARED IDENTITY SERVICE │ │
│ │ ~/.rangerblock/identity/ │ │
│ │ - hardware_fingerprint.json │ │
│ │ - user_identity.json │ │
│ │ - keys/ (RSA-2048) │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ RANGERBLOCK AUTH SERVER │ │
│ │ (server-only/auth-server.cjs) │ │
│ │ - Challenge-response auth │ │
│ │ - Hardware ID verification │ │
│ │ - Session token issuance │ │
│ │ - Ban list management │ │
│ │ - KILL SWITCH LISTENER │ │
│ └──────────────────────────┬──────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ COMMANDER CONTROL PANEL │ │
│ │ (~/.claude/ranger/classified/rain/) │ │
│ │ - Rain Protocol triggers │ │
│ │ - User management │ │
│ │ - Network monitoring │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 4. SHARED IDENTITY SERVICE
### A. Common Identity Module
**New File**: `/Users/ranger/rangerplex-ai/rangerblock/lib/identity-service.cjs`
**Purpose**: Shared code for ALL RangerBlock apps (Electron + Node.js terminal)
**Features**:
```javascript
class RangerBlockIdentity {
// Core identity
getOrCreateIdentity(username) // Returns persistent identity
getHardwareFingerprint() // Cross-platform hardware ID
// Cryptography
generateKeyPair() // RSA-2048 keys
signMessage(message) // Sign with private key
verifySignature(message, sig, pubKey) // Verify with public key
// Storage
saveIdentity() // Persist to ~/.rangerblock/
loadIdentity() // Load from disk
exportIdentity() // Backup identity
// Auth helpers
generateChallenge() // Create auth challenge
respondToChallenge(challenge) // Sign challenge
// Commander integration
checkKillSwitch() // Check if network is live
validateCommanderMessage(msg) // Verify Commander signature
}
```
### B. Storage Structure
**Location**: `~/.rangerblock/` (shared across all apps)
```
~/.rangerblock/
├── identity/
│ ├── hardware_fingerprint.json # Device-specific ID
│ ├── user_identity.json # User profile + stats
│ └── registration_token.json # Server-issued auth token
├── keys/
│ ├── private_key.pem # RSA-2048 private (NEVER share)
│ └── public_key.pem # RSA-2048 public (sent to server)
├── sessions/
│ └── current_session.json # Active session token
└── config/
└── preferences.json # User preferences
```
---
## 5. AUTHENTICATION FLOW
### Phase 1: First-Time Registration
```
┌─────────┐ ┌─────────┐ ┌─────────┐
│ CLIENT │ │ SERVER │ │COMMANDER│
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
│ 1. Generate hardware ID │ │
│ Generate RSA keypair │ │
│ │ │
│ 2. Connect to server │ │
├─────────────────────────────>│ │
│ │ │
│ 3. Server sends challenge │ │
│<─────────────────────────────┤ │
│ (random nonce) │ │
│ │ │
│ 4. Client signs challenge │ │
│ with private key │ │
│ │ │
│ 5. Send registration: │ │
│ - hardware_id │ │
│ - public_key │ │
│ - signed_challenge │ │
│ - nickname │ │
├─────────────────────────────>│ │
│ │ │
│ │ 6. Verify signature │
│ │ Store hardware_id + │
│ │ public_key mapping │
│ │ │
│ 7. Registration approved │ │
│ (session token issued) │ │
│<─────────────────────────────┤ │
│ │ │
│ │ 8. Log new registration │
│ ├─────────────────────────────>│
│ │ (for Commander review) │
│ │ │
```
### Phase 2: Returning User
```
┌─────────┐ ┌─────────┐
│ CLIENT │ │ SERVER │
└────┬────┘ └────┬────┘
│ │
│ 1. Load existing identity │
│ (hardware_id + keys) │
│ │
│ 2. Connect + send auth │
│ - hardware_id │
│ - session_token (if have) │
├─────────────────────────────>│
│ │
│ 3. Server sends challenge │
│<─────────────────────────────┤
│ │
│ 4. Sign challenge │
├─────────────────────────────>│
│ │
│ 5. Server verifies against │
│ stored public key │
│ │
│ 6. Session restored │
│<─────────────────────────────┤
```
---
## 6. IMPLEMENTATION PLAN
### Phase 1: Shared Identity Library (Week 1)
**Priority**: HIGH
**Tasks**:
- [ ] Create `/rangerblock/lib/identity-service.cjs`
- [ ] Port hardware fingerprinting from identityService.ts to Node.js
- [ ] Implement RSA-2048 key generation
- [ ] Implement signature creation/verification
- [ ] Create `~/.rangerblock/` storage structure
- [ ] Write unit tests
**Files to Create**:
```
/rangerblock/lib/
├── identity-service.cjs # Core identity logic
├── crypto-utils.cjs # RSA/signing helpers
├── storage-utils.cjs # File system operations
└── identity-service.test.js # Tests
```
---
### Phase 2: Auth Server (Week 2)
**Priority**: HIGH
**Tasks**:
- [ ] Create `/rangerblock/server-only/auth-server.cjs`
- [ ] Implement challenge-response protocol
- [ ] Store hardware_id → public_key mappings
- [ ] Implement session token generation (JWT-like)
- [ ] Add ban list functionality
- [ ] Integrate kill switch listener
- [ ] Add Commander notification endpoint
**Files to Create**:
```
/rangerblock/server-only/
├── auth-server.cjs # Main auth server
├── user-database.cjs # User storage (SQLite)
├── session-manager.cjs # Token management
├── ban-list.cjs # Banned users/hardware IDs
└── kill-switch-listener.cjs # Rain Protocol integration
```
**Database Schema**:
```sql
CREATE TABLE users (
id INTEGER PRIMARY KEY,
hardware_id TEXT UNIQUE NOT NULL,
public_key TEXT NOT NULL,
nickname TEXT,
created_at DATETIME,
last_seen DATETIME,
is_banned BOOLEAN DEFAULT 0,
ban_reason TEXT,
message_count INTEGER DEFAULT 0,
trust_score INTEGER DEFAULT 50
);
CREATE TABLE sessions (
id INTEGER PRIMARY KEY,
user_id INTEGER,
token TEXT UNIQUE,
created_at DATETIME,
expires_at DATETIME,
ip_address TEXT,
FOREIGN KEY (user_id) REFERENCES users(id)
);
CREATE TABLE audit_log (
id INTEGER PRIMARY KEY,
user_id INTEGER,
action TEXT,
details TEXT,
timestamp DATETIME,
FOREIGN KEY (user_id) REFERENCES users(id)
);
```
---
### Phase 3: Update blockchain-chat.cjs (Week 3)
**Priority**: MEDIUM
**Tasks**:
- [ ] Import shared identity service
- [ ] Replace simple registration with challenge-response
- [ ] Add persistent identity support
- [ ] Add session token handling
- [ ] Display identity status in UI
- [ ] Handle kill switch signals
**Code Changes**:
```javascript
// OLD (current)
ws.send(JSON.stringify({
type: 'register',
nickname: nickname
}));
// NEW (with security)
const identity = new RangerBlockIdentity();
const myIdentity = await identity.getOrCreateIdentity(nickname);
// Wait for challenge from server
ws.on('message', (data) => {
const msg = JSON.parse(data);
if (msg.type === 'challenge') {
const signature = identity.signMessage(msg.nonce);
ws.send(JSON.stringify({
type: 'register',
hardware_id: myIdentity.hardwareId,
public_key: myIdentity.publicKey,
signature: signature,
nickname: nickname
}));
}
});
```
---
### Phase 4: Update voice-chat.cjs (Week 4)
**Priority**: MEDIUM
**Tasks**:
- [ ] Import shared identity service
- [ ] Add challenge-response auth
- [ ] Add voice stream encryption (AES-256-GCM)
- [ ] Add call authentication (verify caller identity)
- [ ] Handle kill switch signals
**Voice Encryption**:
```javascript
// Generate per-call session key
const sessionKey = crypto.randomBytes(32);
// Encrypt voice data before sending
function encryptVoice(audioBuffer) {
const iv = crypto.randomBytes(12);
const cipher = crypto.createCipheriv('aes-256-gcm', sessionKey, iv);
const encrypted = Buffer.concat([cipher.update(audioBuffer), cipher.final()]);
const authTag = cipher.getAuthTag();
return Buffer.concat([iv, authTag, encrypted]);
}
// Key exchange: Encrypt session key with recipient's public key
const encryptedKey = crypto.publicEncrypt(recipientPublicKey, sessionKey);
```
---
### Phase 5: Update ranger-chat-lite (Week 5)
**Priority**: MEDIUM
**Tasks**:
- [ ] Move identity storage to shared `~/.rangerblock/`
- [ ] Enable RSA signing for all messages
- [ ] Add TLS/WSS support
- [ ] Integrate with auth server
- [ ] Add kill switch handling in Electron
---
### Phase 6: Commander Integration (Week 6)
**Priority**: HIGH
**Tasks**:
- [ ] Create user management API
- [ ] Build network dashboard
- [ ] Integrate Rain Protocol triggers
- [ ] Add real-time alerts for suspicious activity
- [ ] Implement trust score system
---
## 7. KILL SWITCH INTEGRATION
### Server-Side Kill Switch Listener
**File**: `/rangerblock/server-only/kill-switch-listener.cjs`
```javascript
const KILL_COMMANDS = {
'gentle-rain': softKill, // Graceful shutdown
'thunderstorm': hardKill, // Immediate termination
'flood': nuclearKill // Complete purge
};
function startKillSwitchListener(commanderPublicKey) {
// Listen on secret port for Commander signals
const ws = new WebSocket('ws://localhost:XXXX/commander');
ws.on('message', (data) => {
const msg = JSON.parse(data);
// Verify Commander signature
if (!verifyCommanderSignature(msg, commanderPublicKey)) {
console.log('⚠️ Invalid kill switch attempt!');
return;
}
// Execute kill command
if (KILL_COMMANDS[msg.command]) {
KILL_COMMANDS[msg.command](msg.params);
}
});
}
```
### Client-Side Kill Switch Handling
```javascript
// All clients check for kill switch on connect
ws.on('message', (data) => {
const msg = JSON.parse(data);
if (msg.type === 'kill-switch') {
console.log('⚠️ Network shutdown initiated');
switch (msg.level) {
case 'soft':
// Save state, graceful exit
saveState();
process.exit(0);
break;
case 'hard':
// Immediate exit
process.exit(1);
break;
case 'nuclear':
// Wipe local data
wipeLocalData();
process.exit(1);
break;
}
}
});
```
---
## 8. TRUST SCORE SYSTEM
### How It Works
Each user starts with trust score **50** (neutral).
**Score Increases**:
- +1 per day active (max +7/week)
- +5 for verified Commander interaction
- +10 for reporting valid abuse
**Score Decreases**:
- -5 for spam detection
- -10 for suspicious patterns
- -20 for attempted impersonation
- -50 for confirmed abuse (triggers review)
**Trust Levels**:
```
0-19: BANNED (cannot connect)
20-39: RESTRICTED (rate limited, monitored)
40-59: NORMAL (standard access)
60-79: TRUSTED (higher limits)
80-100: VERIFIED (full access, can report)
```
---
## 9. FILE LOCATIONS SUMMARY
### Classified (Commander Only)
```
~/.claude/ranger/classified/
├── RANGERBLOCK_KILL_SWITCH_PLAN.md # Rain Protocol
├── RANGERBLOCK_SECURITY_INTEGRATION_PLAN.md # This document
└── rain/ # Kill switch code (future)
├── commander-keys/
└── rain-protocol.cjs
```
### Shared Identity (All Apps)
```
~/.rangerblock/
├── identity/
├── keys/
├── sessions/
└── config/
```
### Source Code
```
/Users/ranger/rangerplex-ai/rangerblock/
├── lib/
│ ├── identity-service.cjs # NEW
│ ├── crypto-utils.cjs # NEW
│ └── storage-utils.cjs # NEW
├── server-only/ # NEW
│ ├── auth-server.cjs
│ ├── user-database.cjs
│ └── kill-switch-listener.cjs
└── just-chat/
├── blockchain-chat.cjs # UPDATE
└── voice-chat.cjs # UPDATE
```
---
## 10. SECURITY CHECKLIST
### Before Going Live:
- [ ] All communications over WSS (TLS)
- [ ] Private keys never leave device
- [ ] Hardware IDs salted with secret
- [ ] Session tokens expire after 24 hours
- [ ] Rate limiting on all endpoints
- [ ] Audit logging enabled
- [ ] Kill switch tested on test network
- [ ] Commander keys generated offline
- [ ] Backup keys in secure location
- [ ] Ban list functionality tested
---
## 11. NEXT STEPS
**Immediate** (awaiting green light):
1. Create `/rangerblock/lib/identity-service.cjs`
2. Port hardware fingerprinting from TypeScript
3. Test on all platforms
**Short-term**:
4. Build auth server
5. Update blockchain-chat.cjs
6. Update voice-chat.cjs
**Medium-term**:
7. Update ranger-chat-lite
8. Build Commander dashboard
9. Full integration testing
---
**Document Classification**: COMMANDER EYES ONLY
**Created**: December 3, 2024
**Author**: Ranger (AIR9cd99c4515aeb3f6)
**For**: David Keane (IR240474)
**Related**: RANGERBLOCK_KILL_SWITCH_PLAN.md
🎖️ Rangers lead the way!
---
## AWAITING GREEN LIGHT FOR IMPLEMENTATION