End-to-End Encryption (E2E)
Relevant source files
The following files were used as context for generating this wiki page:
The End-to-End Encryption (E2E) system in the Happy ecosystem ensures that all user data, including sessions, messages, and artifacts, is encrypted on the client side before transmission. The architecture follows a "zero-knowledge" principle where the server acts merely as an encrypted relay and cannot decrypt the content of user data.
This system facilitates secure remote control and session sharing between different clients (CLI, Mobile, Web, and macOS) while maintaining privacy against server-side compromises. Authentication is decoupled from standard passwords, instead relying on Ed25519 cryptographic signatures and public key challenges.
Sources: apps/server/workers/README.md:143-147, apps/cli/CLAUDE.md:158-161
Cryptographic Architecture
The project employs multiple cryptographic primitives to handle different security requirements, ranging from session encryption to authentication.
Core Primitives
The system primarily utilizes two encryption standards depending on the specific component and platform:
- AES-256-GCM: The primary algorithm for client-side E2E encryption. It is used in the CLI, Mobile apps (Android/iOS), and macOS clients due to its hardware acceleration (AES-NI) and built-in authentication (AEAD).
- TweetNaCl (XSalsa20-Poly1305): Used primarily for server-side encryption of vendor tokens (like AI API keys) at rest and as a legacy format for early client versions.
Sources: apps/cli/CLAUDE.md:280-295, apps/mobile/android/CLAUDE.md:164-171, apps/server/workers/README.md:139-140
Key Management and Derivation
Keys are managed through platform-specific secure storage, such as the Android Keystore, iOS/macOS Keychain, or the ~/.happy/ directory on the CLI.
For session establishment, the system uses X25519 ECDH (Elliptic Curve Diffie-Hellman) to derive shared secrets. This process is often paired with HKDF-SHA256 (HMAC-based Extract-and-Expand Key Derivation Function) using the info string "happy-encryption".
Sources: apps/mobile/android/CLAUDE.md:167-171, apps/macos/CLAUDE.md:113-116, apps/cli/CLAUDE.md:265-270
Data Flow and Relay
The encryption flow ensures that data remains opaque to the server at all times.
This diagram illustrates the zero-knowledge relay architecture where the server only sees encrypted blobs.
Sources: apps/server/workers/README.md:120-134, apps/cli/CLAUDE.md:163-172
Bundle Formats
Encrypted data is packaged into specific "bundle" formats to allow for versioning and key rotation.
| Version | Format | Description |
|---|---|---|
| 0x00 | [version:1][nonce:12][ciphertext:N][authTag:16] | Initial E2E format. |
| 0x01 | [version:1][keyVersion:2][nonce:12][ciphertext:N][authTag:16] | Format supporting key versioning and rotation. |
| Legacy | [nonce:24][ciphertext:N] | TweetNaCl secretbox (no version byte). |
Sources: apps/cli/CLAUDE.md:300-305, apps/mobile/android/CLAUDE.md:167-170
Nonce Generation
To prevent nonce collision—a critical vulnerability in GCM—the system uses a hybrid approach:
- 4 random bytes concatenated with an 8-byte monotonic counter.
- This ensures uniqueness even across rapid thread-safe operations.
Sources: apps/mobile/android/CLAUDE.md:167-171
Authentication Flow
Authentication is based on public-key cryptography (Ed25519) rather than passwords.
This flow demonstrates the Ed25519-based challenge-response authentication.
Sources: apps/server/workers/README.md:68-75, apps/cli/CLAUDE.md:154-157
Implementation Details
Artifact Encryption
Artifacts (files, code snippets) follow a segmented encryption strategy where the header and body are encrypted separately using AES-256-GCM. This allows for listing artifact metadata (titles, paths) while keeping the actual content secure.
Sources: apps/web/vue/src/services/encryption/artifactEncryption.test.ts:13-16
Support for Diverse Clients
The E2E implementation is standardized across the following languages and frameworks:
- TypeScript/JavaScript:
tweetnaclfor legacy/server and Web Crypto API for GCM. - Swift:
CryptoKitfor AES-GCM and Curve25519 on iOS/macOS. - Kotlin:
Google Tinkor Java Cryptography Architecture (JCA) for Android.
Sources: apps/macos/CLAUDE.md:109-112, apps/mobile/android/CLAUDE.md:157-160, apps/web/vue/src/services/encryption.test.ts:15-20
Conclusion
The Happy E2E encryption system provides a robust security layer that protects user data across various platforms. By combining AES-256-GCM for efficiency, X25519 for key exchange, and Ed25519 for authentication, the project achieves a zero-knowledge architecture where the server acts only as a trustless relay. This ensures that even in the event of a server breach, user content remains inaccessible.