zclaw_openfang/docs/changelogs/2026-03-21-phase1-security.md

Phase 1: Security + Testing

Date: 2026-03-21 Status: Complete

Overview

This phase establishes the security foundation and testing framework for the ZCLAW architecture optimization project. It implements encrypted credential storage and enforces secure WebSocket connections.

Changes

Security Enhancements

1. Encrypted localStorage Fallback (secure-storage.ts)

• Issue: Credentials were stored in plaintext in localStorage when OS keyring was unavailable
• Solution: Implemented AES-GCM encryption for localStorage fallback
• Details:
  • Added crypto-utils.ts with encryption/decryption functions
  • Uses PBKDF2 (100,000 iterations) for key derivation
  • Uses AES-GCM (256-bit) for encryption
  • Unique IV per encryption operation
  • Backward compatible with existing unencrypted data

2. WSS Enforcement (gateway-client.ts)

• Issue: Non-localhost connections could use insecure ws:// protocol
• Solution: Block non-localhost connections that don't use WSS
• Details:
  • Added SecurityError class for clear error handling
  • Added validateWebSocketSecurity() function
  • Throws error for ws:// connections to non-localhost hosts
  • Allows ws:// for localhost (development convenience)
  • Allows wss:// for any host

Testing Infrastructure

1. Vitest Framework Setup

• Installed Vitest 2.1.8 with jsdom environment
• Added @testing-library/react for component testing
• Added @testing-library/jest-dom for DOM matchers
• Configured coverage thresholds (60% initial target)

2. Test Files Created

File	Tests	Coverage
crypto-utils.test.ts	10	arrayToBase64, base64ToArray, encrypt, decrypt, deriveKey, generateMasterKey
secure-storage.test.ts	11	Encryption fallback, backward compatibility, special characters
gateway-security.test.ts	13	isLocalhost, WSS enforcement, SecurityError
chatStore.test.ts	39	Messages, conversations, agents, streaming

Files Changed

New Files

desktop/
├── src/lib/crypto-utils.ts          # AES-GCM encryption utilities
├── tests/lib/crypto-utils.test.ts   # Encryption tests
├── tests/lib/secure-storage.test.ts # Secure storage tests
├── tests/lib/gateway-security.test.ts # WSS security tests
├── tests/setup.ts                   # Vitest setup with mocks
└── vitest.config.ts                 # Vitest configuration

Modified Files

desktop/
├── src/lib/secure-storage.ts        # Added encryption fallback
├── src/lib/gateway-client.ts        # Added WSS enforcement
└── package.json                     # Added test dependencies

Migration Notes

• Automatic Migration: Existing unencrypted localStorage data will be automatically migrated on first read
• No Manual Intervention: The encryption/decryption is transparent to users
• Key Generation: A master key is automatically generated and stored in localStorage

Breaking Changes

WSS Required for Remote Connections

• ws:// protocol is no longer allowed for non-localhost connections
• Impact: Users connecting to remote servers must use wss://
• Migration: Update gateway URLs to use wss:// protocol

// Before (now throws SecurityError)
const client = new GatewayClient('ws://example.com:4200/ws');

// After (required)
const client = new GatewayClient('wss://example.com:4200/ws');

// Localhost still works with ws://
const client = new GatewayClient('ws://localhost:4200/ws'); // OK

Test Results

Test Files  4 passed (4)
Tests       73 passed (73)

New modules coverage:
- crypto-utils.ts:     100%
- secure-storage.ts:   95%+
- gateway-security:    100%
- chatStore.ts:        80%+

Security Verification

• localStorage credentials encrypted (AES-GCM)
• Non-localhost connections require WSS
• Encryption keys not exposed in logs
• Backward compatible with unencrypted data
• Unique IV per encryption operation

Next Steps (Phase 2)

• Domain reorganization
• Migrate Chat Store to Valtio
• Migrate Hands Store + XState
• Enhance Intelligence caching
• Extract shared modules

---

Generated by Claude Code - Phase 1 Implementation