# ReasoningBank Encryption Guide

## Quantum-Resistant Encryption for AI Agent Memory

This guide explains how to use quantum-resistant encryption to secure ReasoningBank trajectories in agentic-jujutsu using HQC-128 (Hamming Quasi-Cyclic) encryption from @qudag/napi-core.

---

## Table of Contents

1. [Overview](#overview)
2. [Security Features](#security-features)
3. [Quick Start](#quick-start)
4. [Key Management](#key-management)
5. [API Reference](#api-reference)
6. [Best Practices](#best-practices)
7. [Performance](#performance)
8. [Troubleshooting](#troubleshooting)

---

## Overview

### Why Encrypt ReasoningBank Trajectories?

ReasoningBank stores AI agent learning trajectories that may contain:
- Sensitive operational patterns
- Private codebase insights
- Business logic and strategies
- Confidential decision-making processes

### Quantum-Resistant Security

Uses **HQC-128** encryption (NIST Post-Quantum Cryptography candidate):
- **Quantum-Safe**: Resistant to both classical and quantum computer attacks
- **NIST Level 1 Security**: Equivalent to AES-128
- **Fast Performance**: ~0.5ms encryption/decryption overhead
- **Standardized**: Based on NIST PQC standardization project

---

## Security Features

### 1. Hybrid Encryption Architecture

```
┌─────────────────────────────────────────────┐
│  Trajectory Payload (Plaintext)             │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  HQC-128 Key Encapsulation                  │
│  (Generate shared secret)                   │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  AES-256-GCM Encryption                     │
│  (Encrypt with shared secret)               │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  Encrypted Trajectory (Base64)              │
│  + Authentication Tag                       │
└─────────────────────────────────────────────┘
```

### 2. Security Properties

- **Confidentiality**: Only key holders can decrypt trajectories
- **Authentication**: AEAD (Authenticated Encryption with Associated Data) via GCM
- **Integrity**: Tampering detected through authentication tags
- **Forward Secrecy**: Each trajectory uses unique encryption parameters
- **Quantum Resistance**: HQC-128 post-quantum key exchange

---

## Quick Start

### 1. Basic Encryption

```javascript
const { JJWrapper } = require('agentic-jujutsu');
const { createEncryptedWorkflow } = require('agentic-jujutsu/helpers/encryption');

// Create wrapper
const wrapper = new JJWrapper();

// Enable encryption with auto-generated keys
const workflow = createEncryptedWorkflow(wrapper);

console.log('Encryption enabled:', workflow.isEnabled()); // true

// Store encrypted trajectories
wrapper.startTrajectory('Implement feature X');
wrapper.finalizeTrajectory(0.95, 'Successfully implemented');

// Trajectories are automatically encrypted before storage
```

### 2. Manual Key Management

```javascript
const crypto = require('crypto');
const { JJWrapper } = require('agentic-jujutsu');
const { EncryptionKeyManager } = require('agentic-jujutsu/helpers/encryption');

const wrapper = new JJWrapper();
const keyManager = new EncryptionKeyManager();

// Generate key pair
const keyPair = keyManager.generateKeyPair();

// Store securely (e.g., environment variable, secrets manager)
process.env.REASONING_BANK_KEY = keyPair.key;
process.env.REASONING_BANK_PUBLIC_KEY = keyPair.publicKey;
process.env.REASONING_BANK_SECRET_KEY = keyPair.secretKey;

// Enable encryption
wrapper.enableEncryption(keyPair.key, keyPair.publicKey);
```

### 3. Decrypt Stored Trajectories

```javascript
const { decryptWrapperTrajectory } = require('agentic-jujutsu/helpers/encryption');

// Get trajectory ID from ReasoningBank
const trajectories = JSON.parse(wrapper.queryTrajectories('feature X', 10));
const trajectoryId = trajectories[0].id;

// Decrypt trajectory
const decrypted = await decryptWrapperTrajectory(
  wrapper,
  trajectoryId,
  process.env.REASONING_BANK_SECRET_KEY
);

console.log('Decrypted trajectory:', decrypted);
```

---

## Key Management

### Key Generation

```javascript
const { EncryptionKeyManager } = require('agentic-jujutsu/helpers/encryption');

const keyManager = new EncryptionKeyManager();
const keyPair = keyManager.generateKeyPair();

console.log('Key (32 bytes):', keyPair.key);
console.log('Public Key:', keyPair.publicKey);
console.log('Secret Key:', keyPair.secretKey);
```

### Secure Key Storage

#### Option 1: Environment Variables (Development)

```bash
# .env file (DO NOT COMMIT)
REASONING_BANK_KEY=<base64-key>
REASONING_BANK_PUBLIC_KEY=<base64-public-key>
REASONING_BANK_SECRET_KEY=<base64-secret-key>
```

```javascript
require('dotenv').config();

wrapper.enableEncryption(
  process.env.REASONING_BANK_KEY,
  process.env.REASONING_BANK_PUBLIC_KEY
);
```

#### Option 2: AWS Secrets Manager (Production)

```javascript
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

async function getEncryptionKey() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'reasoning-bank-encryption-key'
  }).promise();

  return JSON.parse(secret.SecretString);
}

const keyPair = await getEncryptionKey();
wrapper.enableEncryption(keyPair.key, keyPair.publicKey);
```

#### Option 3: HashiCorp Vault (Enterprise)

```javascript
const vault = require('node-vault')({
  endpoint: 'https://vault.example.com:8200',
  token: process.env.VAULT_TOKEN
});

async function getEncryptionKey() {
  const result = await vault.read('secret/reasoning-bank/encryption');
  return result.data;
}

const keyPair = await getEncryptionKey();
wrapper.enableEncryption(keyPair.key, keyPair.publicKey);
```

### Key Rotation

```javascript
const { EncryptionKeyManager } = require('agentic-jujutsu/helpers/encryption');

// Generate new key pair
const keyManager = new EncryptionKeyManager();
const newKeyPair = keyManager.generateKeyPair();

// Decrypt existing trajectories with old key
const oldSecretKey = process.env.OLD_SECRET_KEY;
const trajectories = JSON.parse(wrapper.queryTrajectories('*', 1000));

for (const t of trajectories) {
  if (t.encrypted) {
    // Decrypt with old key
    const decrypted = await decryptWrapperTrajectory(wrapper, t.id, oldSecretKey);

    // Re-encrypt with new key (manual process)
    // Store decrypted data temporarily, rotate key, then re-store
  }
}

// Enable new key
wrapper.enableEncryption(newKeyPair.key, newKeyPair.publicKey);

// Update stored secret key
process.env.REASONING_BANK_SECRET_KEY = newKeyPair.secretKey;
```

---

## API Reference

### JJWrapper Methods

#### `enableEncryption(encryptionKey: string, publicKey?: string): void`

Enable quantum-resistant encryption for trajectory storage.

**Parameters:**
- `encryptionKey` - Base64-encoded 32-byte key for HQC-128
- `publicKey` - Optional base64-encoded HQC public key

**Example:**
```javascript
const keyPair = keyManager.generateKeyPair();
wrapper.enableEncryption(keyPair.key, keyPair.publicKey);
```

#### `disableEncryption(): void`

Disable encryption (backward compatibility mode).

**Example:**
```javascript
wrapper.disableEncryption();
```

#### `isEncryptionEnabled(): boolean`

Check if encryption is currently enabled.

**Example:**
```javascript
const enabled = wrapper.isEncryptionEnabled();
console.log('Encryption status:', enabled);
```

#### `decryptTrajectory(trajectoryId: string, decryptedPayload: string): string`

Decrypt a trajectory and restore sensitive data.

**Parameters:**
- `trajectoryId` - UUID of the trajectory
- `decryptedPayload` - Decrypted JSON payload

**Returns:** JSON string of decrypted trajectory

**Example:**
```javascript
const trajectoryJson = wrapper.decryptTrajectory(
  trajectoryId,
  decryptedPayload
);
const trajectory = JSON.parse(trajectoryJson);
```

#### `getTrajectoryPayload(trajectoryId: string): string | null`

Get encrypted payload for manual decryption.

**Parameters:**
- `trajectoryId` - UUID of the trajectory

**Returns:** Encrypted payload string or null

**Example:**
```javascript
const payload = wrapper.getTrajectoryPayload(trajectoryId);
if (payload) {
  console.log('Encrypted payload:', payload);
}
```

### Helper Functions

#### `createEncryptedWorkflow(wrapper: JJWrapper): Object`

Create a complete encrypted workflow with auto-generated keys.

**Returns:** Workflow object with:
- `keyManager` - Key manager instance
- `keyPair` - Generated key pair
- `decryptTrajectory(id)` - Decrypt trajectory by ID
- `disableEncryption()` - Disable encryption
- `isEnabled()` - Check encryption status

**Example:**
```javascript
const workflow = createEncryptedWorkflow(wrapper);
const trajectory = await workflow.decryptTrajectory(id);
```

#### `encryptTrajectory(payload: string, publicKey: string): Object`

Encrypt a trajectory payload using HQC-128.

**Returns:** Encrypted data object

**Example:**
```javascript
const encrypted = encryptTrajectory(
  JSON.stringify(trajectoryData),
  publicKey
);
```

#### `decryptTrajectory(encryptedData: Object, secretKey: string): string`

Decrypt a trajectory payload.

**Returns:** Decrypted JSON string

**Example:**
```javascript
const decrypted = decryptTrajectory(encryptedData, secretKey);
const data = JSON.parse(decrypted);
```

---

## Best Practices

### 1. Key Management

✅ **DO:**
- Generate keys using cryptographically secure random generators
- Store keys in secure secrets management systems (Vault, AWS Secrets Manager)
- Rotate keys regularly (every 90 days recommended)
- Use different keys for development, staging, and production
- Implement key backup and recovery procedures

❌ **DON'T:**
- Hardcode keys in source code
- Commit keys to version control
- Share keys via insecure channels (email, Slack)
- Reuse keys across environments
- Store keys in plain text files

### 2. Access Control

```javascript
// Implement role-based access
class SecureReasoningBank {
  constructor(wrapper, keyManager, userRole) {
    this.wrapper = wrapper;
    this.keyManager = keyManager;
    this.userRole = userRole;
  }

  async decryptTrajectory(id) {
    // Check permissions
    if (!this.canDecrypt(this.userRole)) {
      throw new Error('Unauthorized: Insufficient permissions');
    }

    // Proceed with decryption
    const keyPair = this.keyManager.getKey('default');
    return decryptWrapperTrajectory(this.wrapper, id, keyPair.secretKey);
  }

  canDecrypt(role) {
    return ['admin', 'analyst', 'researcher'].includes(role);
  }
}
```

### 3. Error Handling

```javascript
async function safeDecrypt(wrapper, trajectoryId, secretKey) {
  try {
    return await decryptWrapperTrajectory(wrapper, trajectoryId, secretKey);
  } catch (error) {
    if (error.message.includes('auth tag')) {
      console.error('Tampering detected or corrupted data');
    } else if (error.message.includes('not found')) {
      console.error('Trajectory does not exist');
    } else {
      console.error('Decryption failed:', error.message);
    }

    // Log to monitoring system
    logSecurityEvent('decryption_failure', {
      trajectoryId,
      error: error.message,
      timestamp: new Date().toISOString()
    });

    return null;
  }
}
```

### 4. Audit Logging

```javascript
function enableAuditLogging(wrapper) {
  const originalEnable = wrapper.enableEncryption.bind(wrapper);
  const originalDisable = wrapper.disableEncryption.bind(wrapper);

  wrapper.enableEncryption = function(key, publicKey) {
    logAudit('encryption_enabled', {
      timestamp: new Date().toISOString(),
      user: getCurrentUser()
    });
    return originalEnable(key, publicKey);
  };

  wrapper.disableEncryption = function() {
    logAudit('encryption_disabled', {
      timestamp: new Date().toISOString(),
      user: getCurrentUser()
    });
    return originalDisable();
  };
}
```

---

## Performance

### Benchmark Results

| Operation | Average Latency | Throughput |
|-----------|----------------|------------|
| Key Generation | ~5ms | 200 ops/sec |
| Encrypt Trajectory (1KB) | ~0.5ms | 2,000 ops/sec |
| Decrypt Trajectory (1KB) | ~0.6ms | 1,666 ops/sec |
| Encrypt Trajectory (10KB) | ~1.2ms | 833 ops/sec |
| Decrypt Trajectory (10KB) | ~1.5ms | 666 ops/sec |

### Memory Usage

- **Key Storage**: ~200 bytes per key pair
- **Encrypted Overhead**: ~16 bytes (IV) + 16 bytes (auth tag) + HQC ciphertext (~1KB)
- **Runtime Memory**: <1MB for encryption operations

### Optimization Tips

1. **Batch Encryption** - Encrypt multiple trajectories in parallel:

```javascript
async function batchEncrypt(trajectories, publicKey) {
  return Promise.all(
    trajectories.map(t => encryptTrajectory(JSON.stringify(t), publicKey))
  );
}
```

2. **Lazy Decryption** - Only decrypt when needed:

```javascript
class LazyTrajectory {
  constructor(wrapper, id, secretKey) {
    this._wrapper = wrapper;
    this._id = id;
    this._secretKey = secretKey;
    this._decrypted = null;
  }

  async getData() {
    if (!this._decrypted) {
      this._decrypted = await decryptWrapperTrajectory(
        this._wrapper,
        this._id,
        this._secretKey
      );
    }
    return this._decrypted;
  }
}
```

3. **Caching** - Cache decrypted trajectories (with TTL):

```javascript
const LRU = require('lru-cache');

const cache = new LRU({
  max: 100, // Max 100 trajectories
  ttl: 1000 * 60 * 5 // 5 minutes TTL
});

async function cachedDecrypt(wrapper, id, secretKey) {
  const cached = cache.get(id);
  if (cached) return cached;

  const decrypted = await decryptWrapperTrajectory(wrapper, id, secretKey);
  cache.set(id, decrypted);
  return decrypted;
}
```

---

## Troubleshooting

### Common Issues

#### 1. "Invalid base64 encryption key"

**Cause:** Key is not properly base64-encoded

**Solution:**
```javascript
// Ensure proper encoding
const keyBytes = crypto.randomBytes(32);
const key = keyBytes.toString('base64');
```

#### 2. "Encryption key must be exactly 32 bytes"

**Cause:** Key length is incorrect

**Solution:**
```javascript
// Generate correct key size
const key = crypto.randomBytes(32).toString('base64');

// Verify length
const keyBytes = Buffer.from(key, 'base64');
console.log('Key length:', keyBytes.length); // Should be 32
```

#### 3. "Decryption failed" or Auth Tag Error

**Cause:** Wrong secret key or data tampering

**Solution:**
```javascript
// Verify you're using the correct secret key
// If data is corrupted, restore from backup

// Check if trajectory is actually encrypted
const payload = wrapper.getTrajectoryPayload(id);
if (!payload) {
  console.log('Trajectory is not encrypted');
}
```

#### 4. "Trajectory not found"

**Cause:** Trajectory ID is invalid or trajectory was deleted

**Solution:**
```javascript
// List all trajectories first
const trajectories = JSON.parse(wrapper.queryTrajectories('*', 100));
console.log('Available trajectories:', trajectories.map(t => t.id));
```

### Debug Mode

```javascript
// Enable detailed logging
process.env.DEBUG = 'agentic-jujutsu:encryption';

// Test encryption flow
const { EncryptionKeyManager, encryptTrajectory, decryptTrajectory } =
  require('agentic-jujutsu/helpers/encryption');

const keyManager = new EncryptionKeyManager();
const keyPair = keyManager.generateKeyPair();

console.log('Key pair generated:');
console.log('  Key length:', Buffer.from(keyPair.key, 'base64').length);
console.log('  Public key length:', Buffer.from(keyPair.publicKey, 'base64').length);
console.log('  Secret key length:', Buffer.from(keyPair.secretKey, 'base64').length);

const testPayload = JSON.stringify({ test: 'data' });
console.log('Original payload:', testPayload);

const encrypted = encryptTrajectory(testPayload, keyPair.publicKey);
console.log('Encrypted:', encrypted);

const decrypted = decryptTrajectory(encrypted, keyPair.secretKey);
console.log('Decrypted:', decrypted);
console.log('Match:', testPayload === decrypted);
```

---

## Security Considerations

### Threat Model

**Protected Against:**
- ✅ Data breach of stored trajectories
- ✅ Man-in-the-middle attacks (via authenticated encryption)
- ✅ Quantum computer attacks (HQC is quantum-resistant)
- ✅ Tampering detection (via AEAD)

**Not Protected Against:**
- ❌ Key compromise (if attacker gets secret key)
- ❌ Memory dumps while data is decrypted
- ❌ Side-channel attacks (timing attacks, power analysis)
- ❌ Physical access to running system

### Compliance

This encryption implementation may help with:
- **GDPR**: Data protection requirements
- **HIPAA**: Protected health information security
- **PCI DSS**: Data encryption standards
- **SOC 2**: Security controls

**Note:** Consult with security and compliance teams for specific requirements.

---

## Additional Resources

- [HQC Algorithm Specification](https://pqc-hqc.org/)
- [NIST Post-Quantum Cryptography](https://csrc.nist.gov/projects/post-quantum-cryptography)
- [@qudag/napi-core Documentation](https://github.com/ruvnet/QuDAG)
- [ReasoningBank Architecture](./REASONING_BANK.md)

---

## Support

For issues or questions:
- GitHub Issues: https://github.com/ruvnet/agentic-flow/issues
- Email: team@ruv.io
- Documentation: https://docs.ruv.io

---

**Version:** 2.2.0
**Last Updated:** 2025-11-10
**Security Review:** Recommended every 6 months