nostr-keygen

A tiny command‑line utility written in Python that generates an Nostr npub (public key) and nsec (private key) pair from a single file that you drop into the terminal.

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

Entropy – The contents of the file you provide are read in binary mode.
Hash – The data is hashed with SHA‑256 to produce a 32‑byte seed.
Key generation – The seed is fed to the secp256k1 curve to create an ECDSA private key.
Bech32 encoding – The private key is encoded as nsec; the compressed public key is encoded as npub.

The utility is intentionally lightweight; it has no external configuration and works on any platform with Python 3.8+.

🛠️ Installation

1️⃣ Install Python

macOS: Use Homebrew
```
brew install python@3.12
```
(If you already have Python, skip this step.)
Linux (Ubuntu / Debian‑based):
```
sudo apt-get update
sudo apt-get install python3 python3-venv
```
(Other distros may use yum, dnf, or your package manager of choice.)
Linux (Arch):
```
sudo pacman -S python
```

Tip

– On macOS the python3 binary is typically symlinked to python, but on many Linux systems you’ll need python3 explicitly.

2️⃣ Clone the repo

git clone https://github.com/your‑github‑handle/nostr-keygen.git
cd nostr-keygen

3️⃣ Create a virtual‑environment (recommended)

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.

4️⃣ Install the tool in editable mode (development) or normally

Editable (work on the code as you edit it)
```
pip install -e .
```
Normal installation
```
pip install .
```

Both forms install the console‑script nostr‑keygen into ./venv/bin.

🚀 Run

# Drop any file onto the terminal prompt!
# macOS (most terminals) and many Linux terminals allow drag‑and‑drop.

nostr-keygen <filepath>

Example: nostr-keygen /tmp/randomfile.pdf

📄 Quick test

# 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)

# main.py
import argparse, hashlib
from ecdsa import SigningKey, SECP256k1
from bech32 import bech32_encode, convertbits

NSEC_PREFIX, NPUB_PREFIX = "nsec", "npub"

def _to_bech32(data: bytes, hrp: str) -> str:
    five_bits = convertbits(list(data), 8, 5, True)
    return bech32_encode(hrp, five_bits)

# …  (rest unchanged) …

📄 License

MIT.

3.2 KiB Raw Blame History Unescape Escape