From 8dcf377be69c25c979e7af8eb7148048cd1d9051 Mon Sep 17 00:00:00 2001 From: BTCforPlebs Date: Mon, 6 Oct 2025 13:08:35 -0400 Subject: [PATCH] readme --- readme.md | 227 ++++++++++++++++++++++++++---------------------------- 1 file changed, 110 insertions(+), 117 deletions(-) diff --git a/readme.md b/readme.md index 9bc217d..21746d7 100644 --- a/readme.md +++ b/readme.md @@ -1,88 +1,85 @@ # Nostr Chat Widget -A lightweight, privacy-focused chat widget powered by the Nostr protocol. Features end-to-end encryption, decentralized relay connections, and zero server dependencies. +A lightweight, client‑only Nostr chat widget that can be dropped into any website. The widget is built using **nostr-tools** and **Tailwind CSS** for styling. -![License](https://img.shields.io/badge/license-MIT-blue.svg) -![Nostr](https://img.shields.io/badge/protocol-Nostr-purple.svg) - -## ✨ Features - -- 🔐 **End-to-End Encrypted** - Messages encrypted using NIP-04 -- 🌐 **Decentralized** - Connects to multiple Nostr relays -- 🚫 **No Backend Required** - Entirely client-side -- 📱 **Mobile Responsive** - Works seamlessly on all devices -- ⚡ **Lightweight** - Minimal dependencies -- 🔑 **Ephemeral Keys** - Auto-generated session keys (24hr expiry) -- 💾 **Session Persistence** - Messages saved locally per session +--- ## 🚀 Quick Start -### 1. Add Required Files +```bash +# clone and open the demo page +git clone https://github.com/yourusername/nostr-web-chat-plugin.git +cd nostr-web-chat-plugin +open demo/index.html # use your preferred browser +``` -Include the chat widget files in your HTML: +Once the demo page is open you can immediately play with the widget: +1. **Add the public key** – see *Configuring the Public Key* section below. +2. Hit the orange button in the bottom‑right corner and start chatting! + +--- + +## 🔑 Configuring the Public Key (npub) on the Demo Page + +We added an easy‑to‑use input bar at the top‑center of the demo page that lets you quickly test the widget with any Nostr npub. The JS code reads the key from **localStorage** under the key `cs_pubkey`. When you set a new npub it temporarily overwrites the hard‑coded `csPubkey` value in `src/chat.js`. This makes testing live chats a breeze without touching the source. + +### How It Works +1. **Add the input bar** – The demo page already contains a small form (see `demo/index.html`). +2. **Enter an npub** – Click *Set Npub* to store the value in localStorage. +3. **Reload the page** – The widget automatically loads the new key from localStorage and uses it for all DM interactions. +4. **Clear** – Delete `cs_pubkey` from localStorage or set it back to the original value to revert. + +Below is a quick snippet of the relevant part of `demo/index.html` for reference: ```html - - - - - - - - - - -
``` -### 2. Configure Your Public Key +The source file `src/chat.js` then checks localStorage on initialization: -Edit the `CONFIG` object in `chat.js`: - -```javascript -const CONFIG = { - relays: [ - 'wss://relay.damus.io', - 'wss://relay.primal.net', - 'wss://nos.lol' - ], - csPubkey: 'YOUR_PUBLIC_KEY_HERE' // Your team's Nostr public key (hex format) -}; +```js +// At runtime, override the hard‑coded key if present in localStorage +const stored = localStorage.getItem('cs_pubkey'); +if (stored) { + CONFIG.csPubkey = stored; +} ``` -### 3. Done! +You can keep the original placeholder in `src/chat.js` for production releases. For development or demo purposes, this pattern is the recommended way. -The chat widget will appear as a floating button in the bottom-right corner of your page. +--- -## 📋 Configuration Options +## 📖 Getting Your Public Key -| Option | Type | Description | -|--------|------|-------------| -| `relays` | Array | List of Nostr relay URLs to connect to | -| `csPubkey` | String | Your customer support team's public key (hex format) | +1. Create a Nostr identity using any Nostr client. +2. Export your public key in hex format (not npub). +3. Add it to the `csPubkey` field in `src/chat.js`. -### Getting Your Public Key +**Tip:** You can convert npub to hex at [nostr.band/tools](https://nostr.band/tools). -1. Create a Nostr identity using any Nostr client -2. Export your public key in hex format (not npub) -3. Add it to the `csPubkey` field - -**Tip:** You can convert npub to hex at [nostr.band/tools](https://nostr.band/tools) +--- ## 🎨 Customization ### Styling The widget uses Tailwind CSS utility classes. To customize colors, search for these classes in `chat.js`: - - Primary color: `from-[#fdad01] to-[#ff8c00]` (orange gradient) -- Change to your brand colors +- Change it to your brand colors. ### Mobile Behavior @@ -94,76 +91,72 @@ On mobile devices, the chat expands to fullscreen automatically. Customize this } ``` +--- + ## 🔒 How It Works -1. **Session Creation**: When a user opens the chat, an ephemeral keypair is generated and stored locally -2. **Message Encryption**: All messages are encrypted using NIP-04 (end-to-end encryption) -3. **Relay Publishing**: Encrypted messages are published to multiple Nostr relays -4. **Real-time Updates**: The widget subscribes to replies from your team's public key -5. **Local Storage**: Messages persist locally for 24 hours per session +1. **Session Creation**: Generates an in‑memory keypair stored locally for the session. +2. **Message Encryption**: All messages are encrypted using NIP‑04 (end‑to‑end encryption). +3. **Relay Publishing**: Encrypted messages are published to multiple Nostr relays. +4. **Real‑time Updates**: Subscribes to replies from your team's public key. +5. **Local Storage**: Messages persist locally for 24 hours per session. + +--- ## 📦 Dependencies +- **[nostr-tools](https://github.com/nbd-wtf/nostr-tools)** – Nostr protocol implementation +- **[Tailwind CSS](https://tailwindcss.com/)** – Styling framework -- [nostr-tools](https://github.com/nbd-wtf/nostr-tools) - Nostr protocol implementation -- [Tailwind CSS](https://tailwindcss.com/) - Styling framework +--- ## 🛠️ Development ### Local Testing -1. Clone the repository -2. Open `demo/index.html` in a browser -3. Configure your public key in `chat.js` +```bash +# Clone and test the demo +git clone https://github.com/yourusername/nostr-web-chat-plugin.git +cd nostr-web-chat-plugin +open demo/index.html # or serve with a static server +``` -### Browser Compatibility - -- Chrome/Edge: ✅ -- Firefox: ✅ -- Safari: ✅ -- Mobile browsers: ✅ - -**Note:** Requires ES6 module support - -## 📱 Receiving Messages - -To receive and respond to chat messages, you'll need a Nostr client: - -### Recommended Clients - -- **Desktop**: [Nostr.band](https://nostr.band), [Nostrudel](https://nostrudel.ninja) -- **Mobile**: [Damus (iOS)](https://damus.io), [Amethyst (Android)](https://github.com/vitorpamplona/amethyst) -- **Web**: [Snort.social](https://snort.social), [Iris.to](https://iris.to) - -### Setup Instructions - -1. Import your private key into a Nostr client -2. Watch for DM notifications from new chat sessions -3. Reply directly from the client - messages appear instantly in the widget - -## 🔐 Security Considerations - -- **Ephemeral Keys**: Each session generates a new keypair (24hr expiry) -- **No User Data**: No tracking, cookies, or personal data collection -- **E2E Encryption**: All messages encrypted before transmission -- **Relay Privacy**: Messages distributed across multiple relays - -## 📄 License - -MIT License - See LICENSE file for details - -## 🤝 Contributing - -Contributions welcome! Please feel free to submit a Pull Request. - -## 💬 Support - -- **Issues**: [GitHub Issues](https://github.com/yourusername/nostr-chat-widget/issues) -- **Nostr**: Contact via Nostr DM - -## 🙏 Credits - -Built with [Nostr](https://nostr.com) protocol and [nostr-tools](https://github.com/nbd-wtf/nostr-tools) +1. Open `demo/index.html` in a browser. +2. Use the npub input bar to test with any key. --- -**Made with ⚡ by Loge Media** \ No newline at end of file +## 📱 Receiving Messages + +To receive and respond to chat messages, use any Nostr client: +- **Desktop**: [Nostr.band](https://nostr.band), [Snort](https://snort.social) +- **Mobile**: [Damus](https://damus.io), [Amethyst](https://github.com/vitorpamplona/amethyst) + +--- + +## 🔐 Security Considerations + +- **Ephemeral Keys**: New keypair per session (24‑hr expiration). +- **No User Data**: No cookies or tracking. +- **E2E Encryption**: Messages are encrypted before being sent. +- **Relay Privacy**: Distributed across multiple relays. + +--- + +## 📄 License +MIT License – see [LICENSE](LICENSE). + +--- + +## 🤝 Contributing + +Pull requests welcome! Please open an issue first if you plan a large change. + +--- + +## 💬 Support +- **Issues**: [GitHub Issues](https://github.com/yourusername/nostr-web-chat-plugin/issues) +- **Nostr DM**: Use any DM to contact the maintainer. + +--- + +**Made with ⚡ by Loge Media**