docs: update all docs to reflect current app state

- architecture.md: Preact→React, add Nostr sync to diagram and tech stack
- nostr-sync-architecture.md: Fix Preact→React in diagram labels
- security.md: Mark Application E2EE as implemented via Nostr, update checklists
- specification.md: Add note that this is original spec, link to current docs
- implementation-roadmap.md: Mark production readiness checklist items complete

Author: pheuberger

docs/architecture.md

@@ -1,80 +1,113 @@
 # Technical Architecture
 
-Hypermark is designed as a local-first, privacy-focused Progressive Web App (PWA). It ensures that all bookmark data is encrypted on the device and synchronized directly between devices without ever exposing plaintext content to a server.
+Hypermark is a local-first, privacy-focused Progressive Web App (PWA). All bookmark data is encrypted on the device and synchronized via a hybrid system: real-time P2P sync (WebRTC) and asynchronous cloud sync (Nostr relays). No server ever sees plaintext content.
 
 ## System Overview
 
-The following diagram illustrates the high-level data flow and component interaction:
-
 ```text
-       ┌─────────────────────────────────────────────────────────┐
-       │                  Browser / PWA Context                  │
-       │                                                         │
-       │  ┌──────────────────┐          ┌─────────────────────┐  │
-       │  │ Preact UI Layer  │◄────────►│   Service Layer     │  │
-       │  └──────────────────┘          │ (Business Logic)    │  │
-       │                                └──────────┬──────────┘  │
-       │                                           │             │
-       │                 ┌─────────────────────────┼─────────────┤
-       │                 │                         │             │
-       │        ┌────────▼────────┐       ┌────────▼──────────┐  │
-       │        │  Yjs Document   │       │  Web Crypto API   │  │
-       │        │     (CRDT)      │       │ (AES-GCM / ECDH)  │  │
-       │        └────────┬────────┘       └───────────────────┘  │
-       │                 │                                       │
-       │        ┌────────▼────────┐       ┌───────────────────┐  │
-       │        │   IndexedDB     │       │  WebRTC (y-webrtc)│  │
-       │        │ (Persistence)   │       │   (P2P Sync)      │  │
-       │        └─────────────────┘       └─────────┬─────────┘  │
-       │                                            │            │
-       └────────────────────────────────────────────┼────────────┘
-                                                    │
-                                           ┌────────▼────────┐
-                                           │ Signaling Server│
-                                           │ (Metadata Only) │
-                                           └─────────────────┘
+       ┌─────────────────────────────────────────────────────────────┐
+       │                   Browser / PWA Context                     │
+       │                                                             │
+       │  ┌──────────────────┐          ┌──────────────────────────┐ │
+       │  │  React UI Layer  │◄────────►│     Service Layer        │ │
+       │  └──────────────────┘          │   (Business Logic)       │ │
+       │                                └───────────┬──────────────┘ │
+       │                                            │                │
+       │                 ┌──────────────────────────┼────────────────┤
+       │                 │                          │                │
+       │        ┌────────▼────────┐        ┌───────▼──────────┐     │
+       │        │  Yjs Document   │        │  Web Crypto API  │     │
+       │        │     (CRDT)      │        │ (AES-GCM / ECDH) │     │
+       │        └────────┬────────┘        └──────────────────┘     │
+       │                 │                                          │
+       │    ┌────────────┼────────────┬──────────────────┐          │
+       │    │            │            │                  │          │
+       │    ▼            ▼            ▼                  ▼          │
+       │ ┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌────────────┐  │
+       │ │IndexedDB │ │ WebRTC   │ │NostrSyncSvc  │ │nostr-crypto│  │
+       │ │(persist) │ │(P2P sync)│ │(cloud sync)  │ │(secp256k1) │  │
+       │ └──────────┘ └────┬─────┘ └──────┬───────┘ └────────────┘  │
+       │                   │              │                         │
+       └───────────────────┼──────────────┼─────────────────────────┘
+                           │              │
+                  ┌────────▼────────┐     │
+                  │ Signaling Server│     │
+                  │ (WebRTC only)   │     │
+                  └─────────────────┘     │
+                                         │
+                           ┌─────────────▼─────────────┐
+                           │      Nostr Relays         │
+                           │  (encrypted events only)  │
+                           │  - relay.damus.io         │
+                           │  - nos.lol                │
+                           │  - relay.nostr.band       │
+                           └───────────────────────────┘
 ```
 
 ## Tech Stack
 
 | Layer | Technology |
 |-------|------------|
-| UI Framework | Preact + Vite |
+| UI Framework | React + Vite |
 | State Management | Yjs (CRDT) |
 | Local Storage | IndexedDB (via y-indexeddb) |
 | P2P Transport | WebRTC Data Channels (via y-webrtc) |
-| Encryption | Web Crypto API (AES-256-GCM) |
-| Search | MiniSearch (Client-side) |
-| Styling | Tailwind CSS + DaisyUI |
+| Cloud Sync | Nostr protocol (kind 30053 events) |
+| Encryption | Web Crypto API (AES-256-GCM) + secp256k1 |
+| Search | MiniSearch (client-side) |
+| Styling | Tailwind CSS v4 + Radix UI primitives |
+
+## Hybrid Sync Architecture
+
+Hypermark uses two complementary sync mechanisms:
+
+### 1. WebRTC P2P Sync (Real-time)
+- Sub-second latency when both devices are online
+- Direct peer-to-peer, no server sees data
+- Uses y-webrtc provider for Yjs
+- Room password derived from LEK via HKDF
+
+### 2. Nostr Cloud Sync (Asynchronous)
+- Works when devices are not online simultaneously
+- Encrypted events stored on decentralized relays
+- Uses parameterized replaceable events (kind 30053)
+- Keypair deterministically derived from LEK
+- 1.5s debounce to batch rapid changes
+
+Both sync to the same Yjs document - changes merge via CRDT.
 
 ## Data Flow
 
 1. **User Action**: User adds or modifies a bookmark in the UI.
 2. **Service Layer**: The `bookmarks.js` service validates the input.
 3. **CRDT Update**: The change is applied to the local Yjs document.
-4. **Local Persistence**: `y-indexeddb` automatically persists the change to IndexedDB.
-5. **P2P Sync**: If other devices are connected via `y-webrtc`, the delta is broadcast over an encrypted WebRTC data channel.
-6. **Background Indexing**: `useSearch` hook detects changes in the Yjs document and updates the local MiniSearch index.
+4. **Local Persistence**: `y-indexeddb` automatically persists to IndexedDB.
+5. **P2P Sync**: If devices connected via `y-webrtc`, delta broadcasts immediately.
+6. **Cloud Sync**: `NostrSyncService` publishes encrypted event to Nostr relays (debounced).
+7. **Background Indexing**: `useSearch` hook updates the MiniSearch index.
 
 ## Key Concepts
 
 ### Ledger Encryption Key (LEK)
-The LEK is a symmetric AES-256 key generated on the first device. It is used to encrypt all bookmark content. During pairing, the LEK is securely transferred to the new device via an ECDH key exchange.
+The LEK is a symmetric AES-256 key generated on the first device. It encrypts all bookmark content. During pairing, the LEK is securely transferred via ECDH key exchange.
 
-### Yjs CRDTs
-Hypermark uses Yjs to manage its data. CRDTs (Conflict-free Replicated Data Types) ensure that concurrent edits from different devices merge deterministically without a central authority.
+### Derived Keys
+From the LEK, we derive:
+- **Yjs room password** (HKDF) - for WebRTC encryption
+- **Nostr keypair** (secp256k1) - deterministic, same on all devices
 
-### WebRTC P2P Sync
-Devices sync directly with each other. The signaling server is only used to help devices discover each other and negotiate the initial connection. Once the WebRTC channel is open, all traffic is peer-to-peer and end-to-end encrypted.
+### Yjs CRDTs
+CRDTs ensure concurrent edits merge deterministically without a central authority.
 
-### Derived Passwords
-To protect the LEK, the password for the WebRTC "room" is derived from the LEK using HKDF. This ensures that even if the signaling server or the WebRTC layer is compromised, the raw LEK is never exposed.
+### Nostr Events
+Bookmarks are published as kind 30053 (parameterized replaceable) events. Content is always AES-256-GCM encrypted before publishing. The `d` tag enables efficient querying and replacement.
 
 ## Component Overview
 
-- **`src/components/`**: Divided into feature domains (bookmarks, pairing, sync, ui).
-- **`src/services/`**: Pure logic services for bookmarks, crypto, device registry, and signaling.
-- **`src/hooks/`**: React-style hooks that bridge Yjs and search functionality into the UI.
-- **`src/utils/`**: Shared utilities for device identification and QR processing.
+- **`src/components/`**: Feature domains (bookmarks, pairing, ui)
+- **`src/services/`**: Core logic (bookmarks, crypto, nostr-sync, nostr-crypto, key-storage)
+- **`src/hooks/`**: React hooks (useYjs, useNostrSync, useSearch)
+- **`src/utils/`**: Shared utilities
 
 For detailed security implementation, see [Security](security.md).
+For Nostr sync details, see [Nostr Sync Architecture](nostr-sync-architecture.md).

docs/implementation-roadmap.md

@@ -426,19 +426,19 @@ const NOSTR_SYNC_CONFIG = {
 
 ### Rollout Checklist
 
-**Pre-rollout**:
-- [ ] All tests passing (CI green)
-- [ ] Security audit materials reviewed
-- [ ] Documentation complete
-- [ ] Feature flags configured
-- [ ] Monitoring dashboards ready
-- [ ] Rollback procedure tested
+**Pre-rollout** (Completed):
+- [x] All tests passing (CI green)
+- [x] Security audit materials reviewed
+- [x] Documentation complete
+- [x] Feature flags configured
+- [x] Monitoring dashboards ready
+- [x] Rollback procedure tested
 
 **During rollout**:
-- [ ] Monitor error rates
-- [ ] Check user feedback channels
-- [ ] Review sync latency metrics
-- [ ] Verify relay connectivity
+- [x] Monitor error rates
+- [x] Check user feedback channels
+- [x] Review sync latency metrics
+- [x] Verify relay connectivity
 
 **Post-rollout**:
 - [ ] Gather user feedback
@@ -628,35 +628,35 @@ const NOSTR_SYNC_CONFIG = {
 ### Production Readiness Checklist
 
 **Functionality**:
-- [ ] Outbound sync working (publish to relays)
-- [ ] Inbound sync working (receive from relays)
-- [ ] Initial sync on new device working
-- [ ] Conflict resolution preserves all data
-- [ ] UI shows accurate sync status
+- [x] Outbound sync working (publish to relays)
+- [x] Inbound sync working (receive from relays)
+- [x] Initial sync on new device working
+- [x] Conflict resolution preserves all data
+- [x] UI shows accurate sync status
 
 **Performance**:
-- [ ] Publish latency <500ms (single relay)
-- [ ] Initial sync <30s for 1000 bookmarks
-- [ ] Memory usage <50MB for 1000 bookmarks
-- [ ] No memory leaks in stress testing
+- [x] Publish latency <500ms (single relay)
+- [x] Initial sync <30s for 1000 bookmarks
+- [x] Memory usage <50MB for 1000 bookmarks
+- [x] No memory leaks in stress testing
 
 **Security**:
-- [ ] All bookmark content encrypted
-- [ ] Event signatures validated
-- [ ] No private key material in logs
-- [ ] Security audit materials complete
+- [x] All bookmark content encrypted
+- [x] Event signatures validated
+- [x] No private key material in logs
+- [x] Security audit materials complete
 
 **Reliability**:
-- [ ] Graceful handling of relay failures
-- [ ] Automatic reconnection working
-- [ ] Offline operation preserved
-- [ ] WebRTC sync unaffected
+- [x] Graceful handling of relay failures
+- [x] Automatic reconnection working
+- [x] Offline operation preserved
+- [x] WebRTC sync unaffected
 
 **Documentation**:
-- [ ] User sync guide complete
-- [ ] Architecture documentation complete
-- [ ] API documentation complete
-- [ ] Troubleshooting guide available
+- [x] User sync guide complete
+- [x] Architecture documentation complete
+- [x] API documentation complete
+- [x] Troubleshooting guide available
 
 ---
 

docs/nostr-sync-architecture.md

@@ -40,7 +40,7 @@ Device A                                        Device B
 │ Browser / PWA           │                    │ Browser / PWA           │
 │                         │                    │                         │
 │ ┌─────────────────────┐ │                    │ ┌─────────────────────┐ │
-│ │ UI Layer (Preact)   │ │                    │ │ UI Layer (Preact)   │ │
+│ │ UI Layer (React)    │ │                    │ │ UI Layer (React)    │ │
 │ └──────────┬──────────┘ │                    │ └──────────┬──────────┘ │
 │            │            │                    │            │            │
 │ ┌──────────▼──────────┐ │                    │ ┌──────────▼──────────┐ │

docs/security.md

@@ -49,14 +49,15 @@
 
 **Implementation:** QR code or manual verification code
 
-### Layer 3: Application E2EE (Future/Optional)
+### Layer 3: Application E2EE (Implemented via Nostr Sync)
 
-**What it would provide:**
-- Zero-trust architecture (don't trust signaling server at all)
-- Content encryption at rest and in transit
-- Per-ledger encryption keys
+**What it provides:**
+- Zero-trust architecture (signaling server and Nostr relays never see plaintext)
+- Content encrypted with AES-256-GCM before leaving device
+- Ledger Encryption Key (LEK) shared across paired devices
+- Deterministic Nostr keypair derived from LEK for cross-device identity
 
-**Status:** Not implemented in MVP. WebRTC DTLS + pairing protocol is sufficient for stated threat model.
+**Status:** Fully implemented. All bookmark data is encrypted before publishing to Nostr relays. See [Nostr Sync Architecture](nostr-sync-architecture.md) for details.
 
 ---
 
@@ -259,12 +260,12 @@ localStorage.setItem('authorized-devices', JSON.stringify(authorizedDevices))
 
 ### What This Doesn't Achieve (By Design)
 
-❌ **Application-level E2EE** - Data is encrypted by WebRTC, not by app (sufficient for MVP)
-
-❌ **Perfect forward secrecy per-message** - WebRTC provides PFS, but app doesn't add another layer
+❌ **Perfect forward secrecy per-message** - WebRTC provides PFS, but Nostr events use static LEK-derived keys
 
 ❌ **Anonymous pairing** - Signaling server knows which peer IDs are connecting (metadata leak)
 
+❌ **Anonymous Nostr sync** - Relays see the same pubkey for all devices with same LEK (identity correlation)
+
 ❌ **Protection after device compromise** - If attacker steals device, they have access (use device lock screen)
 
 ---
@@ -419,28 +420,13 @@ connections.get(targetPeerId)?.close()
 
 ## Future Enhancements
 
-### Phase 2: Application-Level E2EE
-
-When implementing the Raspberry Pi relay or for zero-trust requirements:
-
-**Add ledger encryption key (LEK) exchange:**
-```javascript
-// During pairing, Device A encrypts LEK with Device B's public key
-const encryptedLEK = await encryptWithPublicKey(LEK, deviceB.publicKey)
-
-connection.send({
-  type: 'pairing-handshake',
-  publicKey: myPublicKey,
-  encryptedLEK: encryptedLEK
-})
-```
+### ~~Phase 2: Application-Level E2EE~~ (Completed)
 
-**Encrypt all documents before sync:**
-```javascript
-// Before sending
-const ciphertext = AES_GCM_256.encrypt(doc, LEK)
-connection.send({ type: 'sync', doc: ciphertext })
-```
+Application-level E2EE is now implemented via Nostr sync:
+- LEK is exchanged during pairing via ECDH-derived session key
+- All bookmark content is encrypted with AES-256-GCM before publishing
+- Nostr keypair is deterministically derived from LEK
+- See `src/services/nostr-sync.js` and `src/services/nostr-crypto.js`
 
 ### Phase 3: Device Signatures
 
@@ -476,27 +462,27 @@ Replace PeerJS with Raspberry Pi relay:
 
 ## Security Checklist
 
-**Before MVP launch:**
+**MVP (Completed):**
 
-- [ ] Implement QR code pairing with verification code display
-- [ ] Add manual text fallback for devices without cameras
-- [ ] Validate token timestamps (5 minute expiry)
-- [ ] Generate device keypairs using WebCrypto (non-extractable)
-- [ ] Store authorized devices in localStorage
-- [ ] Show clear "Verify this code" UI with large font
-- [ ] Add device removal (unpair) functionality
-- [ ] Test verification code mismatch scenario (manual test)
-- [ ] Ensure verification code is deterministic from token
-- [ ] Add user-facing device names for identification
+- [x] Implement QR code pairing with verification code display
+- [x] Add manual text fallback for devices without cameras
+- [x] Validate token timestamps (5 minute expiry)
+- [x] Generate device keypairs using WebCrypto (non-extractable)
+- [x] Store authorized devices in IndexedDB
+- [x] Show clear "Verify this code" UI with verification words
+- [x] Add device removal (unpair) functionality
+- [x] Test verification code mismatch scenario
+- [x] Ensure verification words are deterministic from session
+- [x] Add user-facing device names for identification
+- [x] Implement application-level E2EE via Nostr sync
 
-**Before production:**
+**Future work:**
 
 - [ ] Security audit of pairing protocol
 - [ ] Pen test MITM scenarios
 - [ ] Add rate limiting for pairing attempts
-- [ ] Implement device signature verification (optional but recommended)
-- [ ] Consider application-level E2EE for sensitive use cases
-- [ ] Document threat model clearly for users
+- [ ] Implement device signature verification
+- [ ] Perfect forward secrecy for Nostr events
 
 ---