# HumanReadableSeed
HumanReadableSeed is a Python library that converts cryptographic seeds or tokens into human-readable words and vice versa. It was originally developed to work with [edgevpn](https://github.com/mudler/edgevpn/), a minimalist VPN software that cleverly stores its config as a base64 token string, as mentionned in [this issue](https://github.com/mudler/edgevpn/issues/544) which resulted in [this gist](https://gist.github.com/thiswillbeyourgithub/53befc8223f37aa929b35c6ebf8e6365).
## Why
When working with cryptographic seeds or tokens, it's often challenging to share, check or communicate them accurately due to their complex nature. HumanReadableSeed solves this problem by converting these tokens into a sequence of easily readable words. This makes it much easier to share configurations or seeds verbally or in writing, reducing the chance of errors. This is somewhat reminiscent of BIP39 used in cryptocurrencies, but actually BIP39 is not reversible in the same way and no simple to use libraries seemed available for that.
## Features
- Convert cryptographic seeds or tokens into human-readable words
- Convert human-readable words back into the original seed or token
- Customizable wordlist (default uses NLTK words corpus, which after ascii filtering and deduplicationg is about 200 000 words long)
- No dependencies except `fire` to launch the cli and `nltk` for the wordlist if used.
- Automatic or manual chunk size selection for conversion
- Built-in error checking and verbose mode for debugging
## Important Notes
- The input seed must contain only ASCII characters. As spaces are part of ascii, you can sort of *encrypt* a human readable text as a list of words, provided both ends have the same wordlist. Similarly to a one time pad encryption mechanism.
- Any ASCII string of any length can be converted into readable words.
- Not all sequences of words can be converted back into valid seeds. Only words generated by the `seed_to_human` function are guaranteed to be convertible back to seeds.
- The list of words is case insensitive.
## How It Works
HumanReadableSeed uses an encoding scheme to convert between seeds and human-readable words:
1. **Conversion to Binary**: The input seed (ASCII string) is converted to its binary representation.
2. **Chunking**: The binary string is divided into chunks of a specific size (automatically determined based on the wordlist size).
3. **Padding**: If the binary string's length isn't a multiple of the chunk size, padding is added. The amount of padding is encoded in the first word of the output.
4. **Word Mapping**: Each binary chunk is converted to a decimal number, which is then used as an index to select a word from the wordlist.
5. **Output**: The selected words, including the padding word, form the human-readable representation of the seed.
The process is reversible, allowing the original seed to be reconstructed from the words:
1. The first word is used to determine the amount of padding to remove.
2. Each subsequent word is converted back to its index in the wordlist.
3. These indices are converted to binary chunks.
4. The binary chunks are concatenated and converted back to ASCII characters.
This method ensures that any ASCII seed can be converted to words and back again without loss of information.
5. **Verification**: After each conversion (in both directions), a roundtrip check is performed to ensure the accuracy of the conversion. This means that after converting a seed to words, it's immediately converted back to a seed and compared with the original input. Similarly, when converting words to a seed, the result is converted back to words and compared with the original input. This step guarantees the integrity of the conversion process.
## Getting Started
You can install HumanReadableSeed using one of the following methods:
### From PyPI
- As a uv tool:
```
uvx HumanReadableSeed@latest --help
```
- Via uv:
```
uv pip install HumanReadableSeed
```
- Via pip:
```
pip install HumanReadableSeed
```
### From GitHub
1. Clone this repository:
```
git clone https://github.com/yourusername/HumanReadableSeed.git
```
2. Navigate to the cloned directory and install:
```
cd HumanReadableSeed
pip install .
```
## Usage
You can use HumanReadableSeed both as a Python library and as a command-line tool.
### As a Python Library
Here's a basic example of how to use HumanReadableSeed in your Python code:
```python
from HumanReadableSeed import HumanReadableSeed
# Initialize the HumanReadableSeed object
hrs = HumanReadableSeed()
# Convert a seed to human-readable words
seed = "your_token_here"
human_readable = hrs.seed_to_human(seed)
print(f"Human-readable version: {human_readable}")
# Convert back to the original seed
reconstructed_seed = hrs.human_to_seed(human_readable)
print(f"Reconstructed seed: {reconstructed_seed}")
```
### As a Command-Line Tool
You can also use HumanReadableSeed directly from the command line:
1. To convert a seed to human-readable words:
```
python -m HumanReadableSeed toread "your_token_here"
```
Or alternatively:
```
HumanReadableSeed toread "your_token_here"
```
2. To convert human-readable words back to a seed:
```
HumanReadableSeed toseed "word1 word2 word3 ..."
```
3. To enable verbose mode, add the `--verbose` flag:
```
HumanReadableSeed toread "your_token_here" --verbose
```
4. To check the version:
```
HumanReadableSeed --version
```
## Contributing
Contributions to HumanReadableSeed are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the GNU GPL v3 License - see the [LICENSE.md](LICENSE.md) file for details.
## Development
HumanReadableSeed was primarily developed using [aider](https://aider.chat/), an AI-powered coding assistant. This tool significantly contributed to the efficient creation and refinement of the codebase and documentation. My other tool, [BrownieCutter](https://pypi.org/project/BrownieCutter/) was used to quickly create a package.
### Testing
To test the code, you can directly run the `HumanReadableSeed.py` file:
```
python HumanReadableSeed/HumanReadableSeed.py
```
This will execute a series of tests that iterate many times back and forth on random strings of various lengths. It's a great way to verify the robustness of the encoding and decoding processes.
Raw data
{
"_id": null,
"home_page": "https://github.com/thiswillbeyourgithub/HumanReadableSeed",
"name": "HumanReadableSeed",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "seeds, crypto, bitcoin, bip39, readable, seed, wordlist, nltk, onetime, pad, token, mnemonic",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ef/66/eedb7a2ad3ea8ad54744fbf8067c1e7a7dfa6f2f6f8ff7f3c4e213a2c1ea/humanreadableseed-0.0.8.tar.gz",
"platform": null,
"description": "# HumanReadableSeed\n\nHumanReadableSeed is a Python library that converts cryptographic seeds or tokens into human-readable words and vice versa. It was originally developed to work with [edgevpn](https://github.com/mudler/edgevpn/), a minimalist VPN software that cleverly stores its config as a base64 token string, as mentionned in [this issue](https://github.com/mudler/edgevpn/issues/544) which resulted in [this gist](https://gist.github.com/thiswillbeyourgithub/53befc8223f37aa929b35c6ebf8e6365).\n\n## Why\n\nWhen working with cryptographic seeds or tokens, it's often challenging to share, check or communicate them accurately due to their complex nature. HumanReadableSeed solves this problem by converting these tokens into a sequence of easily readable words. This makes it much easier to share configurations or seeds verbally or in writing, reducing the chance of errors. This is somewhat reminiscent of BIP39 used in cryptocurrencies, but actually BIP39 is not reversible in the same way and no simple to use libraries seemed available for that.\n\n## Features\n\n- Convert cryptographic seeds or tokens into human-readable words\n- Convert human-readable words back into the original seed or token\n- Customizable wordlist (default uses NLTK words corpus, which after ascii filtering and deduplicationg is about 200 000 words long)\n- No dependencies except `fire` to launch the cli and `nltk` for the wordlist if used.\n- Automatic or manual chunk size selection for conversion\n- Built-in error checking and verbose mode for debugging\n\n## Important Notes\n\n- The input seed must contain only ASCII characters. As spaces are part of ascii, you can sort of *encrypt* a human readable text as a list of words, provided both ends have the same wordlist. Similarly to a one time pad encryption mechanism.\n- Any ASCII string of any length can be converted into readable words.\n- Not all sequences of words can be converted back into valid seeds. Only words generated by the `seed_to_human` function are guaranteed to be convertible back to seeds.\n- The list of words is case insensitive.\n\n## How It Works\n\nHumanReadableSeed uses an encoding scheme to convert between seeds and human-readable words:\n\n1. **Conversion to Binary**: The input seed (ASCII string) is converted to its binary representation.\n\n2. **Chunking**: The binary string is divided into chunks of a specific size (automatically determined based on the wordlist size).\n\n3. **Padding**: If the binary string's length isn't a multiple of the chunk size, padding is added. The amount of padding is encoded in the first word of the output.\n\n4. **Word Mapping**: Each binary chunk is converted to a decimal number, which is then used as an index to select a word from the wordlist.\n\n5. **Output**: The selected words, including the padding word, form the human-readable representation of the seed.\n\nThe process is reversible, allowing the original seed to be reconstructed from the words:\n\n1. The first word is used to determine the amount of padding to remove.\n2. Each subsequent word is converted back to its index in the wordlist.\n3. These indices are converted to binary chunks.\n4. The binary chunks are concatenated and converted back to ASCII characters.\n\nThis method ensures that any ASCII seed can be converted to words and back again without loss of information.\n\n5. **Verification**: After each conversion (in both directions), a roundtrip check is performed to ensure the accuracy of the conversion. This means that after converting a seed to words, it's immediately converted back to a seed and compared with the original input. Similarly, when converting words to a seed, the result is converted back to words and compared with the original input. This step guarantees the integrity of the conversion process.\n\n## Getting Started\n\nYou can install HumanReadableSeed using one of the following methods:\n\n### From PyPI\n\n- As a uv tool:\n ```\n uvx HumanReadableSeed@latest --help\n ```\n\n- Via uv:\n ```\n uv pip install HumanReadableSeed\n ```\n\n- Via pip:\n ```\n pip install HumanReadableSeed\n ```\n\n### From GitHub\n\n1. Clone this repository:\n ```\n git clone https://github.com/yourusername/HumanReadableSeed.git\n ```\n\n2. Navigate to the cloned directory and install:\n ```\n cd HumanReadableSeed\n pip install .\n ```\n\n## Usage\n\nYou can use HumanReadableSeed both as a Python library and as a command-line tool.\n\n### As a Python Library\n\nHere's a basic example of how to use HumanReadableSeed in your Python code:\n\n```python\nfrom HumanReadableSeed import HumanReadableSeed\n\n# Initialize the HumanReadableSeed object\nhrs = HumanReadableSeed()\n\n# Convert a seed to human-readable words\nseed = \"your_token_here\"\nhuman_readable = hrs.seed_to_human(seed)\nprint(f\"Human-readable version: {human_readable}\")\n\n# Convert back to the original seed\nreconstructed_seed = hrs.human_to_seed(human_readable)\nprint(f\"Reconstructed seed: {reconstructed_seed}\")\n```\n\n### As a Command-Line Tool\n\nYou can also use HumanReadableSeed directly from the command line:\n\n1. To convert a seed to human-readable words:\n ```\n python -m HumanReadableSeed toread \"your_token_here\"\n ```\n Or alternatively:\n ```\n HumanReadableSeed toread \"your_token_here\"\n ```\n\n2. To convert human-readable words back to a seed:\n ```\n HumanReadableSeed toseed \"word1 word2 word3 ...\"\n ```\n\n3. To enable verbose mode, add the `--verbose` flag:\n ```\n HumanReadableSeed toread \"your_token_here\" --verbose\n ```\n\n4. To check the version:\n ```\n HumanReadableSeed --version\n ```\n\n## Contributing\n\nContributions to HumanReadableSeed are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the GNU GPL v3 License - see the [LICENSE.md](LICENSE.md) file for details.\n\n## Development\n\nHumanReadableSeed was primarily developed using [aider](https://aider.chat/), an AI-powered coding assistant. This tool significantly contributed to the efficient creation and refinement of the codebase and documentation. My other tool, [BrownieCutter](https://pypi.org/project/BrownieCutter/) was used to quickly create a package.\n\n### Testing\n\nTo test the code, you can directly run the `HumanReadableSeed.py` file:\n\n```\npython HumanReadableSeed/HumanReadableSeed.py\n```\n\nThis will execute a series of tests that iterate many times back and forth on random strings of various lengths. It's a great way to verify the robustness of the encoding and decoding processes.\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Reversible conversion between seeds and human readable words",
"version": "0.0.8",
"project_urls": {
"Homepage": "https://github.com/thiswillbeyourgithub/HumanReadableSeed"
},
"split_keywords": [
"seeds",
" crypto",
" bitcoin",
" bip39",
" readable",
" seed",
" wordlist",
" nltk",
" onetime",
" pad",
" token",
" mnemonic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "61dfa325a6b7593db747ad2cfdcb710f48d9ee1e653c4dbc37a1ddebeb5e9823",
"md5": "46e6b199de9adfe0eedc544928a3208d",
"sha256": "f1ac0619e360fa7b153c4dee53cff79d425f047529fed98f7c2e12a9b27750cf"
},
"downloads": -1,
"filename": "HumanReadableSeed-0.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46e6b199de9adfe0eedc544928a3208d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 19958,
"upload_time": "2024-10-12T13:04:00",
"upload_time_iso_8601": "2024-10-12T13:04:00.799425Z",
"url": "https://files.pythonhosted.org/packages/61/df/a325a6b7593db747ad2cfdcb710f48d9ee1e653c4dbc37a1ddebeb5e9823/HumanReadableSeed-0.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ef66eedb7a2ad3ea8ad54744fbf8067c1e7a7dfa6f2f6f8ff7f3c4e213a2c1ea",
"md5": "fb7e67e3e5ae6af63a39853f869aae42",
"sha256": "3292e8fe9dfd4cba8c74ce5a0e67b6236f347f908c6bf8b51d5509856a696507"
},
"downloads": -1,
"filename": "humanreadableseed-0.0.8.tar.gz",
"has_sig": false,
"md5_digest": "fb7e67e3e5ae6af63a39853f869aae42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 21949,
"upload_time": "2024-10-12T13:04:03",
"upload_time_iso_8601": "2024-10-12T13:04:03.025652Z",
"url": "https://files.pythonhosted.org/packages/ef/66/eedb7a2ad3ea8ad54744fbf8067c1e7a7dfa6f2f6f8ff7f3c4e213a2c1ea/humanreadableseed-0.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-12 13:04:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thiswillbeyourgithub",
"github_project": "HumanReadableSeed",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "humanreadableseed"
}
JSON
