web/docs/COMPLIANCE_DECRYPTION.md

Compliance Message Decryption Guide

This guide explains how to decrypt encrypted messages for compliance and legal purposes using the secure offline compliance system.

Overview

The application uses client-server encryption for direct messages (DMs). While regular users can only decrypt their own messages, compliance officers can decrypt any message for legal compliance purposes using a secure offline process.

Security Model

• Regular Users: Can only decrypt messages encrypted with their own public keys
• Compliance Officers: Can decrypt any message using the compliance private key (stored offline)
• No Server Access: Compliance private keys are never stored on production servers
• Audit Trail: All compliance access is logged with timestamps and user IDs

Prerequisites

1. Compliance Officer Access

• Must be logged in as user ID 1 (system administrator)
• Requires valid JWT authentication token

2. Air-Gapped Machine

• A secure, offline computer for decryption
• Compliance private key stored securely
• Python environment with required dependencies

3. Files Required

• compliance_keypair.txt - Contains compliance X25519 keypair
• compliance_decryption.py - Decryption script
• Message data extracted from the server

Step-by-Step Instructions

Step 1: Extract Message Data from Server

On the production server (as compliance officer):

1. Log in to the application as user ID 1
2. Get your JWT token from browser developer tools:

• Open DevTools (F12)
• Go to Application → Local Storage
• Copy the token value

3. Extract message data using the API:

 curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
      http://localhost:8300/api/dm/compliance/extract/MESSAGE_ID \
      > compliance_MESSAGE_ID.json

Replace MESSAGE_ID with the actual message ID you want to decrypt. 4. Verify the extraction was successful:

 cat compliance_MESSAGE_ID.json | jq .

Expected response:

Step 2: Transfer Data to Air-Gapped Machine

Securely transfer the JSON file to your air-gapped machine:

• Use encrypted USB drive
• Use secure file transfer protocol
• Never transfer over network if air-gapping is required

Step 3: Decrypt Message on Air-Gapped Machine

On the air-gapped machine:

1. Ensure you have the required files:

• compliance_keypair.txt (compliance private key)
• compliance_decryption.py (decryption script)
• compliance_MESSAGE_ID.json (extracted message data)

2. Run the decryption:

 python compliance_decryption.py decrypt --input-file compliance_MESSAGE_ID.json

3. The script will output the decrypted message:

 🔓 Loading compliance data from: compliance_MESSAGE_ID.json
 📄 Loaded message ID: 123
 📅 Timestamp: 2026-01-10T19:23:37.938054
 👤 Sender: 456, Recipient: 789
 🔐 Has compliance MEK: ✅
 🔑 Loading compliance private key...
 🔓 Decrypting message content...

 ✅ DECRYPTION SUCCESSFUL
 ==================================================
 Message ID: 123
 From: User 456
 To: User 789
 Timestamp: 2026-01-10T19:23:37.938054
 Decrypted at: 2026-01-10T19:33:20.782656
 --------------------------------------------------
 MESSAGE CONTENT:
 {"type":"text","data":{"content":"Your encrypted message here"}}
 --------------------------------------------------
 ⚠️  This content has been accessed for compliance purposes

Message Format

Decrypted messages contain the original message payload in JSON format:

{
  "type": "text",
  "data": {
    "content": "The actual message text",
    "files": [...]  // Optional file attachments
  }
}

Security Considerations

Key Management

• Compliance private key: Never stored on production servers
• Access control: Only user ID 1 can extract messages
• Audit logging: All extractions are logged with timestamps

Data Handling

• Secure transfer: Use encrypted channels for data transfer
• Immediate destruction: Delete decrypted content after review
• No caching: Don't store decrypted messages

Operational Security

• Air-gapped environment: Use dedicated offline machine for decryption
• Access controls: Limit physical access to compliance officers
• Regular audits: Review access logs regularly

Troubleshooting

"Access denied" Error

• Ensure you're logged in as user ID 1
• Check that your JWT token is valid and not expired

"Message not found" Error

• Verify the message ID exists
• Check that the message hasn't been deleted

Decryption Failures

• Ensure compliance_keypair.txt is present and contains valid keys
• Check that the JSON file wasn't corrupted during transfer
• Verify Python environment has required cryptography dependencies

Network Errors

• Ensure the server is running and accessible
• Check firewall and network connectivity
• Verify API endpoints are correctly configured

API Reference

Compliance Extraction Endpoint

GET /api/dm/compliance/extract/{message_id}
Authorization: Bearer <jwt_token>
Response: JSON with encrypted message data

Restrictions:

• Requires user ID 1 authentication
• Returns encrypted data only (no plaintext)
• Logs all access for audit purposes

Decryption Script

python compliance_decryption.py decrypt --input-file <json_file>

Requirements:

• compliance_keypair.txt in current directory
• Valid JSON file from extraction API
• Python with cryptography library

Compliance Workflow Summary

1. Legal Request → 2. Compliance Officer → 3. Server Extraction → 4. Secure Transfer → 5. Offline Decryption → 6. Content Review → 7. Audit Logging
     ↓                      ↓                         ↓                      ↓                      ↓                      ↓                      ↓
  Legal basis          User ID 1 login           API call with token    Encrypted transfer    Air-gapped machine   Content analysis      Access recorded

This ensures complete separation between production systems and compliance decryption, maintaining security while enabling legal access to encrypted communications