From a9af9d33af4a7948117dba8c688e294636b97a80 Mon Sep 17 00:00:00 2001 From: kccleoc Date: Wed, 7 Jan 2026 21:03:00 +0800 Subject: [PATCH] add Makefile Dockerfile README.md --- Dockerfile | 16 ++++++ Makefile | 90 +++++++++++++++++++++++++++++++ README.md | 155 ++++++++++++++++++++++++++++++++++++++++++----------- 3 files changed, 230 insertions(+), 31 deletions(-) create mode 100644 Dockerfile create mode 100644 Makefile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..53e3001 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,16 @@ + +# Dockerfile +# Base build environment for hdwalletpy: Python 3.11 + build tools + venv support +FROM python:3.11-slim + +# Install build tools, headers, and venv module +RUN apt-get update && apt-get install -y --no-install-recommends \ + build-essential \ + python3-dev \ + libffi-dev \ + python3-venv \ + && rm -rf /var/lib/apt/lists/* + +# Set working directory for bind mounts +WORKDIR /app + diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..af9ba9c --- /dev/null +++ b/Makefile @@ -0,0 +1,90 @@ + +# Makefile for hdwalletpy workflow +# - Build a reusable Docker image +# - Compile wheels in container (wheelhouse) +# - Create host venv and install from wheelhouse +# - Optionally run inside a warm container + +# ---------- Config ---------- +IMAGE := python-build-env:3.11 +CONTAINER := hdwallet +WORKDIR := /app +VENV_HOST := .venv_host +VENV_CONTAINER := /opt/venv +WHEELHOUSE := wheelhouse + +# ---------- Help ---------- +.PHONY: help +help: + @echo "Targets:" + @echo " make build-image - Build Docker image with build tools and python3-venv" + @echo " make wheels - Build dependency wheels into ./$(WHEELHOUSE)" + @echo " make venv-host - Create host venv $(VENV_HOST) and install from wheelhouse" + @echo " make up - Start a warm container named $(CONTAINER)" + @echo " make shell - Open a shell in the warm container" + @echo " make venv-container - Create venv inside container at $(VENV_CONTAINER) and install requirements" + @echo " make down - Stop and remove the warm container" + @echo " make clean-venv - Remove host venv $(VENV_HOST)" + @echo " make clean-wheelhouse - Remove local wheel cache $(WHEELHOUSE)" + @echo " make clean - Clean venv and wheelhouse" + +# ---------- Build reusable image ---------- +.PHONY: build-image +build-image: + docker build -t $(IMAGE) . + +# ---------- Build wheels in container ---------- +.PHONY: wheels +wheels: requirements.txt + docker run --rm -it -v "$$PWD":$(WORKDIR) -w $(WORKDIR) $(IMAGE) bash -lc '\ + python -m pip install --upgrade pip setuptools wheel && \ + mkdir -p $(WHEELHOUSE) && \ + python -m pip wheel -r requirements.txt -w $(WHEELHOUSE) \ + ' + +# ---------- Host venv from wheelhouse ---------- +.PHONY: venv-host +venv-host: requirements.txt + python3 -m venv $(VENV_HOST) + . $(VENV_HOST)/bin/activate && \ + python -m pip install --upgrade pip setuptools wheel && \ + python -m pip install --no-index --find-links=$(WHEELHOUSE) -r requirements.txt && \ + python --version + +# ---------- Warm container lifecycle ---------- +.PHONY: up +up: + docker run -dit -v "$$PWD":$(WORKDIR) -w $(WORKDIR) --name $(CONTAINER) $(IMAGE) bash + +.PHONY: shell +shell: + docker exec -it $(CONTAINER) bash + +.PHONY: venv-container +venv-container: requirements.txt + docker exec -it $(CONTAINER) bash -lc '\ + test -x $(VENV_CONTAINER)/bin/python || ( \ + python -m venv $(VENV_CONTAINER) && \ + . $(VENV_CONTAINER)/bin/activate && \ + python -m pip install --upgrade pip setuptools wheel && \ + python -m pip install -r requirements.txt \ + ) && \ + . $(VENV_CONTAINER)/bin/activate && python --version \ + ' + +.PHONY: down +down: + - docker rm -f $(CONTAINER) + +# ---------- Cleanup ---------- +.PHONY: clean-venv +clean-venv: + rm -rf $(VENV_HOST) + +.PHONY: clean-wheelhouse +clean-wheelhouse: + rm -rf $(WHEELHOUSE) + +.PHONY: clean +clean: clean-venv clean-wheelhouse + diff --git a/README.md b/README.md index a6c0fdd..f29d4bd 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,97 @@ -# pyhdwallet v1.0.5 +Here’s an **extended README.md** that combines your original usage instructions with the **Makefile workflow** for clarity and ease of onboarding: -A secure, offline-first command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. It supports optional PGP-encrypted payloads (ASCII-armored `.asc`) and deterministic AES-encrypted ZIP wallet artifacts written under a local `.wallet/` folder. +*** -## Purpose +## ✅ Extended `README.md` -pyhdwallet helps create new wallets or recover from existing mnemonics/seeds with offline operation, auditable derivation, and optional encryption for safer storage. PGP encryption produces an ASCII-armored PGP message suitable for saving as `.asc`.[3] +````markdown +# hdwalletpy – Setup & Usage Guide -## Repository layout +This project provides a Python-based HD Wallet tool with optional Docker-based build automation for fast, reproducible environments. -- `src/pyhdwallet.py` — main CLI script -- `.wallet/` — generated wallet artifacts (recommend adding to `.gitignore`) -- `requirements.in`, `requirements.txt` -- `README.md`, `playbook.md`, `LICENSE` +--- -## Installation +## 📦 Installation Options -1. Ensure Python 3.11+ is installed. -1. Clone/download the repo. -1. Create and activate a virtual environment: +### **Option 1: Standard Python Setup (Host Machine)** + +1. Clone the repository: + ```bash + git clone https://github.com//hdwalletpy.git + cd hdwalletpy +```` + +2. Create a virtual environment: + ```bash + python -m venv .venv + source .venv/bin/activate + ``` + +3. Install dependencies: + ```bash + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + ``` + +*** + +### **Option 2: Fast Setup Using Docker + Makefile** + +This method avoids installing compilers on your host and speeds up dependency builds. + +#### **Step 1: Build Docker Image** ```bash -python -m venv .venv -source .venv/bin/activate +make build-image ``` -1. Install dependencies: +Creates a reusable image `python-build-env:3.11` with build tools and `python3-venv`. + +#### **Step 2: Compile Wheels in Container** ```bash -python -m pip install -r requirements.txt +make wheels ``` -## Basic usage +Builds all dependency wheels into `./wheelhouse` for fast installs. -Run the tool with a subcommand. For help, use `-h` (e.g., `gen -h`, `recover -h`). +#### **Step 3: Create Host Virtual Environment** ```bash -# Generate (prints mnemonic by default; intended for debug/test) +make venv-host +source .venv_host/bin/activate +``` + +Installs dependencies from `wheelhouse` (no compilation needed). + +#### **Optional: Work Inside a Warm Container** + +```bash +make up # Start container +make shell # Open shell inside container +make venv-container # Create container-only venv at /opt/venv +``` + +#### **Cleanup** + +```bash +make clean # Remove host venv and wheelhouse +make down # Stop/remove container +``` + +*** + +## ✅ Basic Usage + +Run the tool with subcommands. For help, use `-h` (e.g., `gen -h`, `recover -h`). + +Examples: + +```bash +# Generate mnemonic (prints to stdout; for debug/test) python ./src/pyhdwallet.py gen -# Generate and save an AES-encrypted ZIP artifact into ./.wallet (password prompted) +# Generate and save AES-encrypted ZIP artifact into ./.wallet (password prompted) python ./src/pyhdwallet.py gen --file # Generate with PGP encryption + ZIP artifact (ZIP contains only encrypted .asc payload) @@ -57,12 +110,16 @@ python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.as python ./src/pyhdwallet.py test ``` -## Notes on `--file`, AES ZIP, and PGP +*** -- `--file` writes **only** an AES-encrypted ZIP (no raw `.json`/`.asc` is left on disk), using `pyzipper`.[4] -- If `--pgp-pubkey-file` is set, the ZIP contains a single ASCII-armored PGP message (`.asc`) created with PGPy-style `PGPMessage.new(...)` then `pubkey.encrypt(...)`.[3] +## 🔐 Notes on `--file`, AES ZIP, and PGP -## About `--force` +* `--file` writes **only** an AES-encrypted ZIP (no raw `.json`/`.asc` left on disk), using `pyzipper`. +* If `--pgp-pubkey-file` is set, the ZIP contains a single ASCII-armored PGP message (`.asc`) created with PGPy-style `PGPMessage.new(...)` then `pubkey.encrypt(...)`. + +*** + +## ⚠️ About `--force` The tool includes a safety guard: if stdout is piped/redirected (non-TTY), it refuses to print sensitive output unless `--force` is set. Checking whether stdout is a terminal is commonly done via `isatty()`. @@ -70,12 +127,48 @@ Example: ```bash python ./src/pyhdwallet.py gen > out.txt # likely refused (non-TTY) -python ./src/pyhdwallet.py gen --force > out.txt # forced (dangerous) +python ./src/pyhdwallet.py gen --force > out.txt # allowed ``` -## Security +*** + +## ✅ Why Use Makefile? + +* **Speed:** Avoid repeated `apt-get` installs; wheels cached locally. +* **Reproducibility:** Same Docker image for builds; no environment drift. +* **Convenience:** One-liner tasks (`make wheels`, `make venv-host`, `make shell`). +* **Separation:** Host venv vs container venv for clean workflows. + +*** + +## Common Makefile Targets + +```bash +make build-image # Build Docker image with build tools +make wheels # Compile wheels into ./wheelhouse +make venv-host # Host venv install from wheelhouse +make up # Start warm container +make shell # Shell into warm container +make venv-container # Container venv at /opt/venv +make down # Stop/remove container +make clean # Remove .venv_host and wheelhouse +``` + +*** + +## License + +Add your license info here. + +``` + +--- + +✅ This README now **integrates your original usage instructions** with the **Makefile workflow**, so new users can choose between a standard Python setup or the optimized Docker-based approach. + +--- + +👉 Do you want me to **also include the Makefile and Dockerfile snippets directly in the README** (so users don’t need to open separate files), or keep them as separate files for clarity? +Or should I prepare a **GitHub-ready ZIP** with `README.md`, `Makefile`, `Dockerfile`, and `.gitignore` for you? +``` -- Designed to run offline; `gen`, `recover`, and `test` block network access in-process. -- Use `--off-screen` to suppress printing sensitive data to stdout. -- Prefer `--file` (AES ZIP) and optionally combine with `--pgp-pubkey-file` for stronger at-rest security. -- For detailed examples and operational guidance, see `playbook.md`.