gitignore

nostr_keygen.egg-info/PKG-INFO

@@ -14,14 +14,32 @@ A tiny command‑line utility written in Python that generates an Nostr **npub**
 
 > **NOTE:** The instructions below work on **macOS** and **Linux**. If you’re on Windows you’ll need a compatible terminal (e.g. WSL, Git‑Bash, or PowerShell with Python).
 
-## How it works
+---
 
-1. **Entropy** – The contents of the file you provide are read in binary mode.
-2. **Hash** – The data is hashed with SHA‑256 to produce a 32‑byte seed.
-3. **Key generation** – The seed is fed to the secp256k1 curve to create an ECDSA private key.
-4. **Bech32 encoding** – The private key is encoded as `nsec`; the compressed public key is encoded as `npub`.
+## 🚀 Run
 
-The utility is intentionally lightweight; it has no external configuration and works on any platform with Python 3.8+.
+```bash
+# Drop any file into the terminal prompt!
+# macOS (most terminals) and many Linux terminals allow drag‑and‑drop.
+
+nostr-keygen <filepath>
+```
+
+> The terminal prompt you see (``$`` on macOS, ``username@host:~$`` on Linux) accepts drag‑and‑drop of any file. The script will read that file path and produce key strings.
+
+---
+
+### 📄 Quick test
+
+```bash
+# Create a tiny dummy file
+printf "random entropy" > /tmp/dummy.bin
+
+# Run the program
+nostr-keygen /tmp/dummy.bin
+```
+
+You should see two lines outputted: an `nsec` string and an `npub` string.
 
 ## 🛠️ Installation
 
@@ -61,7 +79,7 @@ python3 -m venv .venv          # create a venv in the repo directory
 source .venv/bin/activate      # activate it (both on macOS and Linux)
 ```
 
-> The virtual‑environment isolates the dependencies (`ecdsa`, `bech32`‑et c.) from the rest of your system.
+> The virtual‑environment isolates third‑party libraries (`ecdsa`, `bech32`, etc.) from the system‑wide Python installation, ensuring that installing or updating them won’t accidentally break other projects. It also guarantees that anyone who checks out the repo can recreate the exact same runtime environment.
 
 ### 4️⃣ Install the tool in editable mode (development) or normally
 
@@ -75,36 +93,12 @@ source .venv/bin/activate      # activate it (both on macOS and Linux)
   pip install .
   ```
 
-Both forms install the console‑script `nostr‑keygen` into `./venv/bin`.
+Both forms install the console‑script `nostr‑keygen` into `./.venv/bin`.
 
-## 🚀 Run
+## 🚫 Key‑string safety
 
-```bash
-# Drop any file onto the terminal prompt!
-# macOS (most terminals) and many Linux terminals allow drag‑and‑drop.
+> Keep your `nsec` secret in a secure, offline location. Anyone with that string can sign Nostr events or spend Nostr‑based funds.
 
-nostr-keygen <filepath>
-```
-
-> Example: `nostr-keygen /tmp/randomfile.pdf`
-
----
-
-### 📄 Quick test
-
-```bash
-# Create a tiny dummy file
-printf "random entropy" > /tmp/dummy.bin
-
-# Run the program
-nostr-keygen /tmp/dummy.bin
-```
-
-You should see two lines outputted: an `nsec` string and an `npub` string.
-
-## 📦 Packaging details
-
-The project uses a `pyproject.toml` and the `[project.scripts]` entry to expose the `nostr-keygen` command. No additional packaging steps are needed for local use.
 
 ## 🔧 How the code works (quick dive)
 
@@ -120,9 +114,12 @@ def _to_bech32(data: bytes, hrp: str) -> str:
     five_bits = convertbits(list(data), 8, 5, True)
     return bech32_encode(hrp, five_bits)
 
-# …  (rest unchanged) …
+# … (rest unchanged) …
 ```
 
-## 📄 License
+### Why the key‑gen algorithm matters
 
-MIT.
+1. **Read file in binary** – We need raw entropy; reading as text would truncate or encode the file in an unexpected way. Binary mode is the most faithful representation of the file’s content.
+2. **SHA‑256 hash** – Provides a *deterministic* 32‑byte seed from any file. Different inputs yield different seeds, and the same input always yields the same seed.
+3. **Create a secp256k1 signing key** – The curve used by Nostr (and Bitcoin) for ECDSA. The secret key is derived directly from the seed bytes.
+4. **Bech32 encoding** – Nostr keys are human‑readable Bech32 strings prefixed with `nsec` or `npub`. `_to_bech32` converts 8‑bit byte streams to 5‑bit groups and encodes them.