From 4eae367cfc504ff0a51c1a624a7e17009a15aab5 Mon Sep 17 00:00:00 2001
From: LC <kccleoc@gmail.com>
Date: Mon, 5 Jan 2026 06:27:21 +0000
Subject: [PATCH] Update documentation for v1.0.2: Add --secure-mode details,
 security improvements, and changelog

---
 playbook.md | 45 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

diff --git a/playbook.md b/playbook.md
index aabda16..4422029 100644
--- a/playbook.md
+++ b/playbook.md
@@ -1,4 +1,4 @@
-# pyhdwallet v1.0.1
+# pyhdwallet v1.0.2
 
 A command-line tool for generating and recovering HD wallets (BIP39) with support for Ethereum, Solana, and Bitcoin. Features offline operation, PGP encryption, and multi-chain address derivation.
 
@@ -27,6 +27,7 @@ A command-line tool for generating and recovering HD wallets (BIP39) with suppor
 - **Private key export**: Export derived private keys in encrypted payloads.
 - **Solana profiles**: Multiple derivation paths for Solana compatibility.
 - **Self-testing**: Built-in tests to verify functionality.
+- **Secure mode**: Optional paranoid mode with memory zeroing, temp files, and no output printing for high-security use.
 
 ## Installation
 
@@ -77,7 +78,13 @@ A command-line tool for generating and recovering HD wallets (BIP39) with suppor
    python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
    ```
 
-4. Run tests:
+4. Use secure mode for high-security operations:
+
+   ```bash
+   python ./src/pyhdwallet.py gen --secure-mode --pgp-pubkey-file key.asc --chains ethereum --addresses 1
+   ```
+
+5. Run tests:
 
    ```bash
    python ./src/pyhdwallet.py test
@@ -100,6 +107,7 @@ python ./src/pyhdwallet.py fetchkey <url> [--out FILE] [--timeout SECONDS]
 - `url`: URL to the ASCII-armored PGP key
 - `--out FILE`: Save the key to a file
 - `--timeout SECONDS`: Request timeout (default: 15)
+- `--secure-mode`: Enable secure mode (temp files, no extra output)
 
 **Example:**
 
@@ -133,6 +141,7 @@ python ./src/pyhdwallet.py gen [options]
 - `--export-private`: Include private keys in encrypted payload
 - `--include-source`: Include mnemonic in encrypted payload
 - `--unsafe-print`: Print mnemonic even when encrypting
+- `--secure-mode`: Enable secure mode (no printing, temp files, memory zeroing)
 
 **Examples:**
 
@@ -140,6 +149,9 @@ python ./src/pyhdwallet.py gen [options]
 # Basic generation
 python ./src/pyhdwallet.py gen
 
+# With secure mode
+python ./src/pyhdwallet.py gen --secure-mode --pgp-pubkey-file key.asc
+
 # With passphrase and encryption
 python ./src/pyhdwallet.py gen --passphrase "mysecret" --pgp-pubkey-file key.asc --export-private
 
@@ -162,6 +174,7 @@ python ./src/pyhdwallet.py recover [options]
 - `--mnemonic MNEMONIC`: BIP39 mnemonic phrase
 - `--seed HEX_SEED`: 128-character hex seed
 - `--interactive`: Prompt for mnemonic/seed interactively
+- `--secure-mode`: Enable secure mode (no printing, temp files, memory zeroing)
 
 **Examples:**
 
@@ -183,9 +196,13 @@ Run minimal self-tests to verify functionality.
 **Usage:**
 
 ```bash
-python ./src/pyhdwallet.py test
+python ./src/pyhdwallet.py test [--secure-mode]
 ```
 
+**Options:**
+
+- `--secure-mode`: Enable secure mode (no extra output)
+
 **Output:** Success/failure messages for derivation tests.
 
 ## Examples
@@ -212,8 +229,24 @@ python ./src/pyhdwallet.py recover --mnemonic "word1 word2 ... word12" --passphr
 # Fetch key
 python ./src/pyhdwallet.py fetchkey "https://example.com/pubkey.asc" --out mykey.asc
 
+# Use in secure mode
+python ./src/pyhdwallet.py fetchkey --secure-mode "https://example.com/pubkey.asc"
+```
+
+### 4. High-Security Operations with Secure Mode
+
+```bash
+# Generate without printing sensitive data
+python ./src/pyhdwallet.py gen --secure-mode --pgp-pubkey-file key.asc --chains ethereum --addresses 1
+
+# Recover in secure mode
+python ./src/pyhdwallet.py recover --secure-mode --interactive --pgp-pubkey-file key.asc --export-private
+```
+
 # Use in recovery
+
 python ./src/pyhdwallet.py recover --interactive --pgp-pubkey-file mykey.asc --export-private
+
 ```
 
 ### 4. Solana-Specific Derivation
@@ -227,10 +260,14 @@ python ./src/pyhdwallet.py gen --chains solana --sol-profile phantom_bip44change
 - **Offline operation**: `gen`, `recover`, and `test` commands block network access.
 - **No plaintext secrets**: Mnemonics and private keys are never printed unless encrypted or `--unsafe-print` is used.
 - **PGP encryption**: Use for secure storage of sensitive data.
+- **Secure mode**: Use `--secure-mode` for paranoid operations—suppresses output, uses temp files with auto-deletion, and zeros memory.
 - **Passphrase handling**: Passphrases are not stored; only hints are included.
 - **Private key export**: Only export what's needed; treat encrypted payloads as sensitive.
+- **File permissions**: Output files are set to owner-only (0o600) for security.
+- **Memory zeroing**: In secure mode, sensitive variables are cleared after use.
 - **Best practices**:
   - Use `--interactive` to avoid command-line history exposure.
+  - Use `--secure-mode` for high-risk operations.
   - Verify PGP fingerprints out-of-band.
   - Run on trusted, offline machines.
 
@@ -240,9 +277,11 @@ python ./src/pyhdwallet.py gen --chains solana --sol-profile phantom_bip44change
 - **Network errors in offline modes**: Ensure no internet access; the tool blocks it.
 - **Invalid mnemonic**: Check word count and spelling.
 - **PGP decryption fails**: Ensure you have the correct private key.
+- **Secure mode issues**: Ensure temp files are deleted; check permissions on output files.
 - **Version check**: Run `python ./src/pyhdwallet.py --version`
 
 ## Changelog
 
+- **v1.0.2**: Security patches - added --secure-mode, memory zeroing, file permission fixes, auto-deletion in secure mode, sanitized errors.
 - **v1.0.1**: Renamed to pyhdwallet, added --version flag, updated documentation, excluded _toDelete in .gitignore.
 - **v1.0.0**: Initial release with gen, recover, fetchkey, and test commands.