| name | crypto |
| description | Client-side cryptography with libsodium. Use when working on files in src/lib/crypto/. |
Crypto Guidelines
All crypto happens client-side. Server NEVER sees plaintext.
Architecture
- Seed phrase (128-bit) → Ed25519 keypair (signing) → X25519 keypair (encryption)
- Vault key (random 256-bit) wrapped with user's X25519 public key
- Data encrypted with XChaCha20-Poly1305
Critical Rules
- Never log keys or sensitive data - not even in development
- Use libsodium - don't implement crypto primitives
- Async everywhere - all functions async (libsodium-wrappers)
- Constant-time comparisons -
sodium.comparefor secrets - Zeroize secrets -
sodium.memzerowhen done - Type-safe keys - use branded types (VaultKey, SigningKey)
Common Pitfalls
- Don't use
crypto.randomBytes→ usesodium.randombytes_buf - Don't concatenate key material → use proper KDFs
- Don't store keys in localStorage without encryption
- Don't forget
await sodium.readybefore operations
Testing
Use property-based tests for roundtrip verification with fast-check.