From 9f82db34c418d9afc166e16857adeaa2a82a1fa2 Mon Sep 17 00:00:00 2001
From: Logen <79722764+btcforplebs@users.noreply.github.com>
Date: Sat, 11 Oct 2025 14:59:29 -0400
Subject: [PATCH] Update readme.md

---
 readme.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 1 deletion(-)

diff --git a/readme.md b/readme.md
index 0fab6c6..7cfdcdd 100644
--- a/readme.md
+++ b/readme.md
@@ -1,3 +1,99 @@
+# 🔐 NIP‑49 Key Decrypt Fully Offline Self-Contained HTML
+
+A simple, browser-based tool for decrypting NIP-49 (password-protected) Nostr keys — fully offline.  
+It ensures your private key **never leaves your device** and gives users full transparency into what code is running.
+
+---
+
+## ✅ Overview & Motivation
+
+This tool was built to make **secure, offline decryption** of NIP-49 encrypted Nostr keys easy for anyone — without requiring Node.js, servers, or dependencies.
+
+Most web-based cryptography tools fetch external scripts from CDNs each time they run, which can expose users to privacy or supply-chain risks.  
+The **NIP-49 Offline Decrypt Tool** avoids this by letting users:
+
+1. Fetch the required libraries **once** while online.
+2. Package everything into a **self-contained HTML file**.
+3. Disconnect from the internet and safely decrypt their NIP-49 key offline.
+
+---
+
+## ⚙️ How It Works
+
+The app runs entirely in the browser using JavaScript and modern Web APIs:
+
+1. **Library Fetching (Online)**  
+   The user downloads the required cryptographic libraries:
+   - [`libsodium-wrappers`](https://www.npmjs.com/package/libsodium-wrappers)
+   - [`scrypt-js`](https://www.npmjs.com/package/scrypt-js)
+   - [`bech32`](https://www.npmjs.com/package/bech32)
+
+   These are loaded into memory, never uploaded anywhere, and stored temporarily for packaging.
+
+2. **Self-Contained Export**  
+   The app lets you export a new `nip49-offline.html` file that includes:
+   - The libraries (embedded inline)
+   - The app logic
+   - The interface for decryption
+
+3. **Offline Mode (Decryption)**  
+   Once exported, the tool verifies that you are offline and allows decryption of your NIP-49 key locally.
+
+---
+
+## 🚀 Usage Instructions (Step-by-Step)
+
+1. **Open the Online Tool**  
+   Visit the hosted version or open the HTML file locally with an internet connection.
+
+2. **Step 1: Download Libraries**  
+   - Click **“Download Libraries”**  
+   - The tool will fetch and store the required scripts in memory.  
+   - You’ll see progress indicators for each library.
+
+3. **Step 2: Export Offline HTML**  
+   - Once all libraries are fetched, click **“Export Self-Contained HTML”**.  
+   - This creates a new `nip49-offline.html` file with everything embedded.  
+   - Save the file to your computer.
+
+4. **Step 3: Go Offline**  
+   - Disconnect from the internet.  
+   - Open your saved `nip49-offline.html` file in your browser.
+
+5. **Step 4: Decrypt**  
+   - Paste your NIP-49 encrypted key and password.  
+   - Click “Decrypt.”  
+   - Your private key will be displayed (never transmitted anywhere).
+
+---
+
+## 🔐 Security Notes
+
+- All operations happen **entirely in your browser** — no data leaves your device.  
+- The exported HTML file contains all logic and dependencies inline.  
+- To verify safety, you can inspect the final file contents — everything is human-readable JavaScript and HTML.  
+- Always perform decryption **offline** and **with your network fully disabled** for maximum safety.
+
+---
+
+## 🧠 Technical Details
+
+- **Language:** HTML, JavaScript (no build tools required)  
+- **Libraries Used:**
+  - [`libsodium-wrappers`](https://www.npmjs.com/package/libsodium-wrappers) — cryptographic operations
+  - [`scrypt-js`](https://www.npmjs.com/package/scrypt-js) — password-based key derivation
+  - [`bech32`](https://www.npmjs.com/package/bech32) — encoding/decoding NIP-49 format
+- **Features:**
+  - Detects online/offline state dynamically
+  - In-memory caching of library source code
+  - Self-contained HTML export using `Blob` and `URL.createObjectURL`
+  - Minimal UI for clarity and transparency
+
+---
+
+**Built for Bitcoin & Nostr users who value verifiable, offline-first tools.**
+
+
 # 🔐 NIP‑49 Key Encrypt/Decrypt & Conversion CLI
 
 A tiny, no-fuss command-line tool / self contained HTML to **encrypt**, **decrypt**, and **convert** Nostr keys — safely and offline.
@@ -102,4 +198,4 @@ Yes! You can use tools like pyinstaller to build a standalone binary.
 ### 🤝 Credits
 Built with ❤️ by plebs, for plebs. Inspired by NIP‑49 and the Nostr community.
 ### 🛡️ License
-MIT — Free for all. Fork, contribute, share.
\ No newline at end of file
+MIT — Free for all. Fork, contribute, share.