docs(security): document triple-layer encryption architecture

This commit provides a comprehensive explanation of the system's
triple-layer encryption model across documentation and UI.

Changes include:
- Detailed breakdown of client-side (AES-GCM-256), server-side key,
  and database encryption layers in README, security page,
  and dedicated documentation files.
- Clarification of security properties and attacker capabilities.
- Addition of 'Encryption & Security' section in ARCHITECTURE.md.
- Creation of a new dedicated ENCRYPTION.md document.

Author: teycir

README.md

@@ -35,9 +35,33 @@
   <h3>Zero-Trust • Edge-Native • Unbreakable</h3>
 </div>
 
-### 🔒 Layer 1: The Vault (D1 Database Storage)
-> **Encrypted Storage**
-Files are stored encrypted in Cloudflare D1 database. The encrypted blobs are stored alongside metadata, with cryptographic enforcement preventing early access.
+### 🔒 Layer 1: The Vault (Encrypted D1 Database Storage)
+> **Triple-Layer Encryption**
+
+**All seals are encrypted in the database with multiple security layers:**
+
+1. **Client-Side Encryption (AES-GCM-256)**
+   - Your content is encrypted in your browser BEFORE sending to server
+   - Uses split-key architecture: Key A (client) + Key B (server)
+   - Encrypted blob stored as base64 in D1 database
+
+2. **Server-Side Key Encryption**
+   - Key B is encrypted with `MASTER_ENCRYPTION_KEY` before database storage
+   - Master key stored as environment secret (never in database)
+   - Uses HKDF key derivation for additional security
+
+3. **Database Contents (All Encrypted)**
+   - ✅ Encrypted blob (AES-GCM-256 ciphertext)
+   - ✅ Encrypted Key B (AES-GCM-256 with master key)
+   - ✅ IV (public, needed for decryption)
+   - ✅ Metadata (unlock time, timestamps)
+   - ❌ NO plaintext content ever stored
+
+**What an attacker with database access CANNOT do:**
+- Decrypt without Key A (in URL hash, never sent to server)
+- Decrypt without master encryption key (environment secret)
+- Modify unlock time (cryptographically signed)
+- Access content before unlock time (server enforces time-lock)
 
 ### 🤝 Layer 2: The Handshake (Split-Key Crypto)
 > **Trust-Minimized**
@@ -162,10 +186,12 @@ sequenceDiagram
 **❌ NO.** The unlock time is stored in the database when you create the seal. API requests can't modify it.
 
 ### "What if I steal Key B from the database?"
-**⚠️ PARTIAL.** Key B is encrypted with a master key. Even if you steal it, you still need:
-1. The master encryption key (environment secret)
+**❌ NO.** Key B is encrypted with a master key before storage. Even if you steal the encrypted Key B from the database, you still need:
+1. The master encryption key (environment secret, not in database)
 2. Key A (stored in the URL hash, never sent to server)
-3. Both keys to decrypt
+3. Both decrypted keys to decrypt the content
+
+**Database breach impact:** Attacker gets encrypted blobs and encrypted keys, but cannot decrypt without master key and Key A.
 
 ### "Can I brute-force the encryption?"
 **❌ NO.** AES-GCM-256 with cryptographically random keys. Would take billions of years with current technology.

app/security/page.tsx

@@ -24,20 +24,47 @@ export default function SecurityPage() {
 
         <Card className="p-4 sm:p-6 md:p-8 space-y-6">
           <h2 className="text-xl sm:text-2xl font-bold text-neon-green mb-4 flex items-center gap-2">
-            <Lock className="w-6 h-6" /> Encryption Implementation
+            <Lock className="w-6 h-6" /> Triple-Layer Encryption
           </h2>
           <div className="space-y-4 text-neon-green/60 text-sm">
-            <div>
-              <p className="text-neon-green font-bold mb-2">AES-GCM 256-bit Encryption</p>
-              <p>All content is encrypted using AES-GCM with 256-bit keys, providing authenticated encryption with associated data (AEAD).</p>
+            <div className="border-l-2 border-neon-green/30 pl-4">
+              <p className="text-neon-green font-bold mb-2">Layer 1: Client-Side Encryption (AES-GCM-256)</p>
+              <p className="mb-2">Your content is encrypted in your browser BEFORE sending to the server using split-key architecture.</p>
+              <ul className="list-disc list-inside ml-4 space-y-1 text-xs">
+                <li>Key A: Stored in URL hash (never sent to server)</li>
+                <li>Key B: Sent to server (encrypted before storage)</li>
+                <li>Master Key: Derived from Key A + Key B using HKDF</li>
+                <li>Result: AES-GCM-256 encrypted ciphertext</li>
+              </ul>
             </div>
-            <div>
-              <p className="text-neon-green font-bold mb-2">Split-Key Architecture</p>
-              <p>Encryption uses two keys: Key A (client-side, in URL hash) and Key B (server-side, time-locked). Both are required for decryption.</p>
+            <div className="border-l-2 border-neon-green/30 pl-4">
+              <p className="text-neon-green font-bold mb-2">Layer 2: Server-Side Key Encryption</p>
+              <p className="mb-2">Key B is encrypted with MASTER_ENCRYPTION_KEY before database storage.</p>
+              <ul className="list-disc list-inside ml-4 space-y-1 text-xs">
+                <li>Master key stored as environment secret (not in database)</li>
+                <li>Uses HKDF key derivation with seal ID as salt</li>
+                <li>Even database breach cannot decrypt Key B</li>
+              </ul>
             </div>
-            <div>
-              <p className="text-neon-green font-bold mb-2">Cryptographically Secure Random Number Generation</p>
-              <p>All keys and IVs are generated using the Web Crypto API&apos;s CSPRNG, ensuring unpredictability.</p>
+            <div className="border-l-2 border-neon-green/30 pl-4">
+              <p className="text-neon-green font-bold mb-2">Layer 3: Encrypted Database Storage</p>
+              <p className="mb-2">All seals stored encrypted in Cloudflare D1 database:</p>
+              <ul className="list-disc list-inside ml-4 space-y-1 text-xs">
+                <li>✅ Encrypted blob (AES-GCM-256 ciphertext as base64)</li>
+                <li>✅ Encrypted Key B (AES-GCM-256 with master key)</li>
+                <li>✅ IV (public, needed for decryption)</li>
+                <li>✅ Metadata (unlock time, timestamps)</li>
+                <li>❌ NO plaintext content EVER stored</li>
+              </ul>
+            </div>
+            <div className="bg-neon-green/5 p-4 rounded border border-neon-green/20">
+              <p className="text-neon-green font-bold mb-2">🛡️ What an Attacker with Database Access CANNOT Do:</p>
+              <ul className="list-disc list-inside ml-4 space-y-1 text-xs">
+                <li>Decrypt content (needs Key A from URL hash)</li>
+                <li>Decrypt Key B (needs master encryption key)</li>
+                <li>Modify unlock time (cryptographically signed)</li>
+                <li>Access content early (server enforces time-lock)</li>
+              </ul>
             </div>
           </div>
         </Card>
@@ -48,8 +75,8 @@ export default function SecurityPage() {
           </h2>
           <div className="space-y-4 text-neon-green/60 text-sm">
             <div>
-              <p className="text-neon-green font-bold mb-2">Cloudflare D1 Database Storage</p>
-              <p>Encrypted blobs and metadata are stored in Cloudflare&apos;s edge database with automatic replication and encryption at rest.</p>
+              <p className="text-neon-green font-bold mb-2">Cloudflare D1 Encrypted Database Storage</p>
+              <p>All seals are stored encrypted in Cloudflare&apos;s edge database with triple-layer encryption: client-side AES-GCM-256, server-side key encryption, and database encryption at rest. NO plaintext content is ever stored.</p>
             </div>
             <div>
               <p className="text-neon-green font-bold mb-2">Edge Runtime</p>
@@ -84,8 +111,8 @@ export default function SecurityPage() {
               <p>Split-key architecture means neither the server alone nor the client alone can decrypt content.</p>
             </div>
             <div>
-              <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> Encrypted Storage</p>
-              <p>All data stored in D1 database with encryption at rest and cryptographic access controls.</p>
+              <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> Triple-Layer Encrypted Storage</p>
+              <p>All seals encrypted with AES-GCM-256 client-side, Key B encrypted with master key server-side, and database encryption at rest. Zero plaintext storage.</p>
             </div>
             <div>
               <p className="text-neon-green font-bold mb-2 flex items-center gap-2"><CheckCircle2 className="w-4 h-4" /> Client-Side Decryption</p>

docs/ARCHITECTURE.md

@@ -30,6 +30,38 @@ Time-Seal follows a layered architecture with clear separation of concerns and d
 
 ## Core Abstractions
 
+### 0. Encryption & Security (`lib/crypto.ts`, `lib/keyEncryption.ts`)
+**Purpose**: Triple-layer encryption for all seals
+
+**Architecture**:
+```typescript
+// Layer 1: Client-side split-key encryption
+const { keyA, keyB } = await generateKeys();
+const masterKey = await deriveMasterKey(keyA, keyB);
+const encrypted = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, masterKey, data);
+
+// Layer 2: Server-side key encryption
+const encryptedKeyB = await encryptKeyB(keyB, MASTER_KEY, sealId);
+
+// Layer 3: Database storage (all encrypted)
+// - encrypted_blob: AES-GCM-256 ciphertext
+// - key_b: Encrypted with master key
+// - iv: Public (needed for decryption)
+```
+
+**Security Properties**:
+- ✅ Zero plaintext in database
+- ✅ Split-key architecture (Key A never sent to server)
+- ✅ Master key encryption for Key B
+- ✅ HKDF key derivation with deterministic salt
+- ✅ AES-GCM-256 authenticated encryption
+
+**Benefits**:
+- Database breach cannot decrypt content
+- Server compromise cannot decrypt without Key A
+- URL interception cannot decrypt without Key B
+- Defense-in-depth security model
+
 ### 1. Service Layer (`lib/sealService.ts`)
 **Purpose**: Encapsulates all business logic for seal operations