Optional session file encryption

[nikblanchet]

Summary

Session files may contain sensitive information (file paths, API config, audit ratings). Add optional AES-256 encryption with user-provided key to protect data at rest.

Sensitive Data in Session Files

• File paths (may reveal project structure)
• API configuration (timeouts, retry settings)
• Audit ratings (user assessments)
• User preferences (style guides, tone)

Proposed Enhancement

Add optional encryption with AES-256.

Usage

# Set encryption key (environment variable)
export DOCIMP_SESSION_KEY=$(openssl rand -base64 32)

# Sessions automatically encrypted when key is set
docimp audit ./src
# → Session saved encrypted to .docimp/session-reports/audit-session-{uuid}.json

# Resume works transparently (decrypts on load)
docimp audit ./src --resume

Implementation

Files:

• cli/src/utils/session-state-manager.ts
• analyzer/src/utils/session_state_manager.py

Encryption:

• Algorithm: AES-256-GCM (authenticated encryption)
• Key derivation: PBKDF2 (from user key)
• IV: Random per file (stored in encrypted file header)

TypeScript:

import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';

// Encrypt before saving
const key = deriveKey(process.env.DOCIMP_SESSION_KEY);
const iv = randomBytes(16);
const cipher = createCipheriv('aes-256-gcm', key, iv);
const encrypted = Buffer.concat([cipher.update(jsonContent), cipher.final()]);
const authTag = cipher.getAuthTag();

// Write: { iv, authTag, encrypted }

Trade-offs

• Adds complexity
• User must manage encryption keys
• Loss of key = loss of all encrypted sessions
• Benefits: Protects sensitive data at rest

Effort

~6 hours

Related

• Code review PR Session 2: Audit State Schema & Persistence (Issue #216) #365