From 4ac6da1c88366478013c40ed4d5aab0cbc5e366f Mon Sep 17 00:00:00 2001
From: iven <iven_h@qq.com>
Date: Sat, 21 Mar 2026 19:33:44 +0800
Subject: [PATCH] docs: add Phase 1 changelog

- Document security enhancements (encrypted storage, WSS enforcement)
- Document test infrastructure setup
- Document migration notes and breaking changes
- Document test results and coverage

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/changelogs/2026-03-21-phase1-security.md | 133 ++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 docs/changelogs/2026-03-21-phase1-security.md

diff --git a/docs/changelogs/2026-03-21-phase1-security.md b/docs/changelogs/2026-03-21-phase1-security.md
new file mode 100644
index 0000000..c19d51c
--- /dev/null
+++ b/docs/changelogs/2026-03-21-phase1-security.md
@@ -0,0 +1,133 @@
+# 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
+
+```javascript
+// 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
+
+- [x] localStorage credentials encrypted (AES-GCM)
+- [x] Non-localhost connections require WSS
+- [x] Encryption keys not exposed in logs
+- [x] Backward compatible with unencrypted data
+- [x] 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*