WhatsApp AI Recall - Security Documentation

Overview

WhatsApp AI Recall (WAIR) is designed with a privacy-first, local-first architecture. All data processing happens locally on your machine - no data is sent to cloud services (except for WhatsApp connectivity).

Security Features

1. Database Encryption

SQLCipher (AES-256-CBC)

Entire SQLite database is encrypted
Encryption key derived from user password using scrypt
Key is never persisted - derived at runtime only
Backup files are automatically encrypted

Key Derivation:

scrypt(password, salt, N=16384, r=8, p=1, keyLength=32)

2. Media File Encryption

AES-256-GCM

Each media file encrypted individually
Unique salt and IV per file
Authentication tag for integrity verification
Encrypted file format: [salt][iv][authTag][ciphertext]

3. Session Encryption

WhatsApp Session:

Session credentials encrypted with user password
Stored encrypted in ./data/sessions/
Auto-reconnect uses encrypted session

4. Key Management

Password-Based Key Derivation:

Master key derived from user password
Same password always derives same key (deterministic)
Keys wiped from memory after use
No keys stored on disk

Key Hierarchy:

User Password
    │
    └── scrypt() ──► Database Key
    │
    └── scrypt(salt) ──► Media Key (per file)

Security Best Practices

Password Requirements

Minimum requirements enforced:

At least 8 characters
At least one uppercase letter
At least one lowercase letter
At least one number
At least one special character

Recommendations:

Use a password manager
Minimum 12 characters recommended
Don't reuse passwords from other services

Secure Configuration

Environment Variables:

# NEVER commit .env to version control
DATABASE_PASSWORD=<strong-unique-password>
DASHBOARD_ADMIN_PASSWORD=<strong-unique-password>
DASHBOARD_SESSION_SECRET=<random-64-char-string>

File Permissions:

# Linux/macOS
chmod 600 .env
chmod 700 data/
chmod 700 data/sessions/

Network Security

Default Configuration:

Dashboard binds to localhost only (127.0.0.1)
Port 3000 (configurable via PORT env var)
Ollama on port 11434 (localhost only)

Firewall Rules:

# Allow only necessary ports
ufw allow 3000/tcp  # Dashboard (if remote access needed)
ufw deny 11434/tcp  # Ollama (localhost only)

HTTPS (Production): For remote access, use a reverse proxy:

server {
    listen 443 ssl;
    server_name wair.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Session Security

Dashboard Sessions:

Encrypted session cookies (libsodium)
30-minute timeout (configurable)
HTTP-only cookies (no JavaScript access)
Secure flag in production (HTTPS only)

WhatsApp Sessions:

Encrypted session storage
Auto-reconnect with encrypted credentials
Session cleared on logout

Data Protection

Data at Rest

All data encrypted:

Database: SQLCipher AES-256
Media files: AES-256-GCM
Sessions: AES-256-GCM

Data in Transit

WhatsApp: End-to-end encrypted (WhatsApp protocol)
Dashboard: Session-based with encrypted cookies
API: Rate-limited with authentication

Data Deletion

Secure Deletion:

Keys wiped from memory (multiple passes)
Database records deleted (SQLite DELETE)
Media files deleted (OS-level delete)

Factory Reset:

# Delete all data
rm -rf ./data/
# Re-run setup
npm run setup

Access Control

Authentication

Dashboard:

Single admin user
Password-based authentication
Session-based access control

API:

Optional API key authentication
Rate limiting (100 requests/minute default)
Request logging

Authorization

Default Roles:

Admin: Full access to all features
User: Query access only (future feature)

API Permissions:

Endpoint	Permission
GET /api/v1/health	Public
POST /api/v1/query	Authenticated
GET /api/v1/settings	Admin
POST /api/v1/settings	Admin
POST /api/v1/backup/create	Admin

Threat Model

Protected Against

✅ Eavesdropping: All data encrypted at rest ✅ Session Hijacking: Encrypted sessions with timeout ✅ Brute Force: Rate limiting, strong password requirements ✅ Data Theft: Full database encryption ✅ Memory Attacks: Keys wiped after use

Not Protected Against

❌ Physical Access: Someone with physical access can potentially extract data ❌ Memory Dump: Cold boot attacks could potentially extract keys ❌ Malware: Local malware could capture keystrokes or screen ❌ Password Loss: Forgotten password = lost data (by design)

Mitigations

Physical Access:

Use full disk encryption (BitLocker, FileVault, LUKS)
Lock screen when away from computer

Memory Attacks:

Restart computer regularly
Use hardware with memory encryption

Malware:

Keep system updated
Use antivirus software
Don't run untrusted software

Password Loss:

Use password manager
Create secure backup of password
Export data before password changes

Security Checklist

Initial Setup

Set strong database password (12+ chars)
Set strong admin password (12+ chars)
Generate random session secret
Secure .env file (chmod 600)
Enable firewall

Ongoing Security

Production Deployment

Incident Response

Suspected Compromise

Stop the application:
```
npm stop  # or Ctrl+C
```
Change passwords:
- Database password (requires re-encryption)
- Admin password
- Any exposed credentials
Review logs:
```
tail -n 1000 ./data/logs/app.log
```
Create forensic backup:
```
npm run backup
```
Assess damage:
- Check access logs
- Review query history
- Check for unauthorized changes

Password Recovery

If you forget your password:

Data cannot be recovered (by design)
Options:
1. Remember password (check password manager)
2. Restore from backup (if password known)
3. Factory reset (data loss)