https://github.com/smartlegionlab/smartpasslib
Cross-platform library for generating smart passwords.
https://github.com/smartlegionlab/smartpasslib
password-generator password-manager pypi pypi-package pypi-packages python python-libraries python-library python3 smart-password smart-password-generator smart-password-lib smart-password-library smart-password-manager smartlegionlab termux
Last synced: about 1 month ago
JSON representation
Cross-platform library for generating smart passwords.
- Host: GitHub
- URL: https://github.com/smartlegionlab/smartpasslib
- Owner: smartlegionlab
- License: bsd-3-clause
- Created: 2021-11-14T00:52:05.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-06-11T03:05:33.000Z (9 months ago)
- Last Synced: 2025-06-11T03:49:25.233Z (9 months ago)
- Topics: password-generator, password-manager, pypi, pypi-package, pypi-packages, python, python-libraries, python-library, python3, smart-password, smart-password-generator, smart-password-lib, smart-password-library, smart-password-manager, smartlegionlab, termux
- Language: Python
- Homepage:
- Size: 22.5 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# smartpasslib (Smart Passwords Library) v2.1.1
---
**Smart Passwords Library: Cryptographic password generation and management without storage. Generate passwords from secrets, verify knowledge without exposure, manage metadata securely.**
---
[](https://pypi.org/project/smartpasslib/)
[](https://github.com/smartlegionlab/smartpasslib/)
[](https://pypi.org/project/smartpasslib)
[](https://github.com/smartlegionlab/smartpasslib/blob/master/LICENSE)
[](https://pypi.org/project/smartpasslib)
[](https://github.com/smartlegionlab/smartpasslib/stargazers)
[](https://github.com/smartlegionlab/smartpasslib/network/members)
[](https://pepy.tech/projects/smartpasslib)
[](https://pepy.tech/projects/smartpasslib)
[](https://pepy.tech/projects/smartpasslib)
---
## **🔐 Core Principles:**
- 🔐 **Zero-Storage Security**: No passwords or secret phrases are ever stored or transmitted
- 🔑 **Deterministic Generation**: Identical secret + parameters = identical password (SHA3-512 based)
- 📝 **Metadata Only**: Store only verification metadata (public keys, descriptions, lengths)
- 🔄 **On-Demand Regeneration**: Passwords are recalculated when needed, never retrieved from storage
**What You Can Do:**
1. **Smart Passwords**: Generate deterministic passwords from secret phrases
2. **Strong Random Passwords**: Cryptographically secure passwords with character diversity
3. **Authentication Codes**: Generate secure 2FA/MFA codes with guaranteed character sets
4. **Base Passwords**: Simple random passwords for general use
5. **Key Generation**: Create public/private verification keys from secrets
6. **Secret Verification**: Prove knowledge of secrets without revealing them (public key verification)
7. **Metadata Management**: Store and update password metadata (descriptions, lengths) without storing passwords
8. **Deterministic & Non-Deterministic**: Both reproducible and random password generation options
**Key Features:**
- ✅ **No Password Database**: Eliminates the need for password storage
- ✅ **No Secret Storage**: Secret phrases never leave your control
- ✅ **Public Key Verification**: Verify secrets without exposing them
- ✅ **Multiple Generator Types**: Smart, strong, base, and code generators
- ✅ **Metadata Updates**: Modify descriptions and lengths without affecting cryptographic integrity
- ✅ **Full Test Coverage**: 100% tested for reliability and security
- ✅ **Cross-Platform**: Works anywhere Python runs
**Security Model:**
- **Proof of Knowledge**: Verify you know a secret without storing or transmitting it
- **Deterministic Security**: Same input = same output, always reproducible
- **Metadata Separation**: Non-sensitive data (descriptions) stored separately from verification data (public keys)
- **No Recovery Backdoors**: Lost secret = permanently lost passwords (by design)
---
## ⚠️ Critical Notice
**BEFORE USING THIS SOFTWARE, READ THE COMPLETE LEGAL DISCLAIMER BELOW**
[View Legal Disclaimer & Liability Waiver](#-legal-disclaimer)
*Usage of this software constitutes acceptance of all terms and conditions.*
---
## 📚 Research Paradigms & Publications
- **[Pointer-Based Security Paradigm](https://doi.org/10.5281/zenodo.17204738)** - Architectural Shift from Data Protection to Data Non-Existence
- **[Local Data Regeneration Paradigm](https://doi.org/10.5281/zenodo.17264327)** - Ontological Shift from Data Transmission to Synchronous State Discovery
---
## 🔬 Technical Foundation
The library implements **deterministic password generation** - passwords are generated reproducibly from secret phrases using cryptographic hash functions.
**Key principle**: Instead of storing passwords, you store verification metadata. The actual password is regenerated on-demand from your secret.
**What's NOT stored**:
- Your secret phrase
- The actual password
- Any reversible password data
**What IS stored** (optional):
- Public verification key (hash of secret)
- Service description
- Password length parameter
**Security model**: Proof of secret knowledge without secret storage.
---
## 🆕 What's New in v2.1.1
⚠️ CRITICAL WARNING: Upgrading to v2.1.1 will break all existing password generation. All passwords generated with v1.x will become invalid, and public keys will no longer verify.
### Major Changes:
**API Simplification:**
- Removed `login` parameter from all methods - now uses only `secret` phrase
- Simplified `SmartKeyGenerator` to work with single `secret` parameter
- Removed `SmartPasswordMaster.generate_default_smart_password()` method
**Data Model Updates:**
- `SmartPassword` class updated: `login` → `description`, `key` → `public_key`
- All deprecated methods removed
- Removed deprecated `file_path` property from `SmartPasswordManager`
**New Features:**
- Added `SmartPassword.update()` method to modify description and length
- Added `SmartPasswordManager.update_smart_password()` method for stored passwords
**Security Improvements:**
- Simplified key derivation algorithm in `SmartKeyGenerator`
- Cleaner seed management in `SmartPasswordGenerator`
- Removed complex hash mixing from v1.x
**Testing & Quality:**
- 100% test coverage achieved
- Comprehensive exception testing added
- Improved test fixtures and data management
### Breaking Changes:
**Method Signature Changes:**
```python
# v1.x → v2.1.1
SmartPasswordMaster.generate_smart_password(login, secret, length)
SmartPasswordMaster.generate_smart_password(secret, length)
SmartPasswordMaster.generate_public_key(login, secret)
SmartPasswordMaster.generate_public_key(secret)
SmartPasswordMaster.check_public_key(login, secret, public_key)
SmartPasswordMaster.check_public_key(secret, public_key)
```
**Class Structure Changes:**
```python
# v1.x → v2.1.1
SmartPassword(login, key, length)
SmartPassword(public_key, description, length)
SmartKeyGenerator._create_key(login, secret, steps)
SmartKeyGenerator._create_key(secret, steps)
```
**Removed Methods:**
- `SmartPasswordManager.add()` → use `add_smart_password()`
- `SmartPasswordManager.get_password()` → use `get_smart_password()`
- `SmartPasswordManager.remove()` → use `delete_smart_password()`
- `SmartPasswordManager.load_file()` → internal `_load_data()`
- `SmartPasswordManager.save_file()` → internal `_write_data()`
- `SmartPasswordManager.file_path` → use `filename`
- `SmartPasswordMaster.generate_default_smart_password()`
### Migration Guide:
**Password Generation:**
```python
# v1.x
password = SmartPasswordMaster.generate_smart_password(
login="service",
secret="mysecret",
length=12
)
# v2.1.1
password = SmartPasswordMaster.generate_smart_password(
secret="mysecret",
length=12
)
```
**SmartPassword Creation:**
```python
# v1.x
sp = SmartPassword(
login="GitHub",
key=public_key,
length=16
)
# v2.1.1
sp = SmartPassword(
public_key=public_key,
description="GitHub",
length=16
)
```
**Manager Operations:**
```python
# v1.x (deprecated methods)
manager.add(password)
manager.get_password("login")
# v2.1.1
manager.add_smart_password(sp)
manager.get_smart_password(public_key)
```
**Metadata Updates (New):**
```python
# Update existing smart password metadata
manager.update_smart_password(
public_key=stored_key,
description="Updated Service Name",
length=20
)
# Or update SmartPassword object directly
password_metadata.update(
description="New Description",
length=24
)
```
### Key Improvements:
1. **Simplified API** - Single `secret` parameter instead of `login` + `secret`
2. **Cleaner Code** - Removed all deprecated methods and legacy code
3. **Better Security** - Streamlined cryptographic operations
4. **Full Test Coverage** - 100% test coverage ensures reliability
5. **Clearer Naming** - `public_key` accurately represents verification key
6. **Metadata Updates** - New `update()` methods for description and length
**Note:** v2.1.1 is not backward compatible with v1.x. Update your code according to the migration guide.
---
## 📦 Installation
```bash
pip install smartpasslib
```
---
## 🚀 Quick Start
```python
from smartpasslib import SmartPasswordMaster
# Your secret phrase is the only key needed
secret = "my secret phrase"
# Discover the password
password = SmartPasswordMaster.generate_smart_password(
secret=secret,
length=16
)
print(f"Your discovered password: {password}")
# Example output: _4qkVFcC3#pGFvhH
```
## 🔑 Verification Without Storage
```python
from smartpasslib import SmartPasswordMaster
# Generate a public verification key (store this, not the password)
public_key = SmartPasswordMaster.generate_public_key(
secret="my secret"
)
# Later, verify you know the secret without revealing it
is_valid = SmartPasswordMaster.check_public_key(
secret="my secret",
public_key=public_key
) # Returns True - proof of secret knowledge
print(is_valid) # True
```
---
## 🏗️ Core Components
### SmartPasswordMaster - Main Interface
```python
from smartpasslib import SmartPasswordMaster
# Generate different types of passwords
base_password = SmartPasswordMaster.generate_base_password(length=12)
# Output: wd@qt99QH84P
strong_password = SmartPasswordMaster.generate_strong_password(length=14)
# Output: _OYZ7h7wBLcg1Y
smart_password = SmartPasswordMaster.generate_smart_password("secret", 16)
# Output: wcJjBKIhsgV%!6Iq
# Generate and verify keys
public_key = SmartPasswordMaster.generate_public_key("secret")
is_valid = SmartPasswordMaster.check_public_key("secret", public_key)
print(f"Verification: {is_valid}") # Verification: True
# Generate secure codes
auth_code = SmartPasswordMaster.generate_code(8)
# Output: r6*DFyM4
```
### SmartPasswordManager - Metadata Storage
```python
from smartpasslib import SmartPasswordManager, SmartPassword, SmartPasswordMaster
manager = SmartPasswordManager()
# Store verification metadata (not the password and not secret phrase!)
public_key = SmartPasswordMaster.generate_public_key("github secret")
smart_pass = SmartPassword(
public_key=public_key,
description="GitHub account",
length=18
)
manager.add_smart_password(smart_pass)
# Update metadata
manager.update_smart_password(
public_key=public_key,
description="GitHub Professional",
length=20
)
# Retrieve and regenerate password when needed
stored_metadata = manager.get_smart_password(public_key)
regenerated_password = SmartPasswordMaster.generate_smart_password(
"github secret",
stored_metadata.length
)
# Output: ntm#uhqVDx3GqqQzELOH
```
### Generators
**Base Generator** - Simple random passwords:
```python
from smartpasslib.generators.base import BasePasswordGenerator
password = BasePasswordGenerator.generate(12)
# Output: oGHZRCv6zaZF
```
**Strong Generator** - Cryptographically secure with character diversity:
```python
from smartpasslib.generators.strong import StrongPasswordGenerator
password = StrongPasswordGenerator.generate(14) # Guarantees one of each character type
# Output: 3g4nU_4k6!c%rs
```
**Code Generator** - Secure codes for authentication:
```python
from smartpasslib.generators.code import CodeGenerator
code = CodeGenerator.generate(6) # Minimum 4 characters
# Output: Q%5ff*
```
**Smart Generator** - Deterministic passwords from seeds:
```python
from smartpasslib.generators.smart import SmartPasswordGenerator
from smartpasslib.generators.key import SmartKeyGenerator
seed = SmartKeyGenerator.generate_private_key("secret")
password = SmartPasswordGenerator.generate(seed, 15)
# Output: wcJjBKIhsgV%!6I
```
---
## 💡 Advanced Usage
### Password Management System
```python
from smartpasslib import SmartPasswordManager, SmartPassword, SmartPasswordMaster
class PasswordVault:
def __init__(self):
self.manager = SmartPasswordManager()
def add_service(self, service_name: str, secret: str, length: int = 16):
"""Register a new service with its secret"""
public_key = SmartPasswordMaster.generate_public_key(secret)
metadata = SmartPassword(
public_key=public_key,
description=service_name,
length=length
)
self.manager.add_smart_password(metadata)
return public_key
def get_password(self, public_key: str, secret: str) -> str:
"""Regenerate password when needed"""
metadata = self.manager.get_smart_password(public_key)
if metadata:
return SmartPasswordMaster.generate_smart_password(
secret,
metadata.length
)
return None
# Usage
vault = PasswordVault()
key = vault.add_service("My Account", "my account secret", 20)
password = vault.get_password(key, "my account secret")
# Output: _!DGHSTiE!DQxLojjlT%'
```
### Two-Factor Authentication Codes
```python
from smartpasslib.generators.code import CodeGenerator
def generate_2fa_code():
"""Generate a secure 2FA code"""
return CodeGenerator.generate(8)
auth_code = generate_2fa_code() # Example: "lA4P&P!k"
```
---
## 🔧 Ecosystem
### Command Line Tools
- **[CLI Smart Password Generator](https://github.com/smartlegionlab/clipassgen/)** - Generate passwords from terminal
- **[CLI Smart Password Manager](https://github.com/smartlegionlab/clipassman/)** - Manage password metadata
### Graphical Applications
- **[Web Smart Password Manager](https://github.com/smartlegionlab/smart-password-manager)** - Browser-based interface
- **[Desktop Smart Password Manager](https://github.com/smartlegionlab/smartpasslib)** - Cross-platform desktop app
---
## 👨💻 For Developers
### Development Setup
```bash
# Install development dependencies
pip install -r data/requirements-dev.txt
# Run tests
pytest -v
# Run tests with coverage
pytest -v --cov=smartpasslib --cov-report=html
# Build package
python -m build
```
### Testing Coverage
**100% test coverage** - All components thoroughly tested:
- Password generators with edge cases
- Cryptographic key operations
- Metadata serialization/deserialization
- Error handling and validation
- File persistence operations
```
Coverage report: 100%
coverage.py v7.12.0
```
### API Stability
**Public API** (stable):
- `SmartPasswordMaster` - Main interface class
- `SmartPasswordManager` - Metadata management
- `SmartPassword` - Password metadata container
- `SmartPasswordFactory` - Factory for creating metadata
**Internal API** (subject to change):
- All modules in `smartpasslib.generators.*`
- `smartpasslib.factories.*`
- `smartpasslib.utils.*`
---
## 📜 License
**[BSD 3-Clause License](LICENSE)**
Copyright (c) 2026, Alexander Suvorov
```
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```
---
## 🆘 Support
- **Issues**: [GitHub Issues](https://github.com/smartlegionlab/smartpasslib/issues)
- **Documentation**: Inline code documentation
- **Tests**: 100% coverage ensures reliability
**Note**: Always test password generation in your specific environment. Implementation security depends on proper usage.
---
## ⚠️ Security Warnings
**Version Incompatibility**: v2.1.1 passwords are incompatible with v1.x.
Never mix secret phrases across different versions.
### Secret Phrase Security
**Your secret phrase is the cryptographic master key**
1. **Permanent data loss**: Lost secret phrase = irreversible loss of all derived passwords
2. **No recovery mechanisms**: No password recovery, no secret reset, no administrative override
3. **Deterministic generation**: Identical input (secret + parameters) = identical output (password)
4. **Single point of failure**: Secret phrase is the sole authentication factor for all passwords
5. **Secure storage required**: Digital storage of secret phrases is prohibited
**Critical**: Test password regeneration with non-essential accounts before production use
---
## 📄 Legal Disclaimer
**COMPLETE AND ABSOLUTE RELEASE FROM ALL LIABILITY**
**SOFTWARE PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.**
The copyright holder, contributors, and any associated parties **EXPLICITLY DISCLAIM AND DENY ALL RESPONSIBILITY AND LIABILITY** for:
1. **ANY AND ALL DATA LOSS**: Complete or partial loss of passwords, accounts, credentials, cryptographic keys, or any data whatsoever
2. **ANY AND ALL SECURITY INCIDENTS**: Unauthorized access, data breaches, account compromises, theft, or exposure of sensitive information
3. **ANY AND ALL FINANCIAL LOSSES**: Direct, indirect, incidental, special, consequential, or punitive damages of any kind
4. **ANY AND ALL OPERATIONAL DISRUPTIONS**: Service interruptions, account lockouts, authentication failures, or denial of service
5. **ANY AND ALL IMPLEMENTATION ISSUES**: Bugs, errors, vulnerabilities, misconfigurations, or incorrect usage
6. **ANY AND ALL LEGAL OR REGULATORY CONSEQUENCES**: Violations of laws, regulations, compliance requirements, or terms of service
7. **ANY AND ALL PERSONAL OR BUSINESS DAMAGES**: Reputational harm, business interruption, loss of revenue, or any other damages
8. **ANY AND ALL THIRD-PARTY CLAIMS**: Claims made by any other parties affected by software usage
**USER ACCEPTS FULL AND UNCONDITIONAL RESPONSIBILITY**
By installing, accessing, or using this software in any manner, you irrevocably agree that:
- You assume **ALL** risks associated with software usage
- You bear **SOLE** responsibility for secret phrase management and security
- You accept **COMPLETE** responsibility for all testing and validation
- You are **EXCLUSIVELY** liable for compliance with all applicable laws
- You accept **TOTAL** responsibility for any and all consequences
- You **PERMANENTLY AND IRREVOCABLY** waive, release, and discharge all claims against the copyright holder, contributors, distributors, and any associated entities
**NO WARRANTY OF ANY KIND**
This software comes with **ABSOLUTELY NO GUARANTEES** regarding:
- Security effectiveness or cryptographic strength
- Reliability or availability
- Fitness for any particular purpose
- Accuracy or correctness
- Freedom from defects or vulnerabilities
**NOT A SECURITY PRODUCT OR SERVICE**
This is experimental software. It is not:
- Security consultation or advice
- A certified cryptographic product
- A guaranteed security solution
- Professional security software
- Endorsed by any security authority
**FINAL AND BINDING AGREEMENT**
Usage of this software constitutes your **FULL AND UNCONDITIONAL ACCEPTANCE** of this disclaimer. If you do not accept **ALL** terms and conditions, **DO NOT USE THE SOFTWARE.**
**BY PROCEEDING, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS DISCLAIMER IN ITS ENTIRETY, UNDERSTAND ITS TERMS COMPLETELY, AND ACCEPT THEM WITHOUT RESERVATION OR EXCEPTION.**
---
**Version**: 2.1.1 | [**Author**](https://smartlegionlab.ru): [Alexander Suvorov](https://alexander-suvorov.ru)
---
**Note**: This is v2.1.1. If migrating from v1.x, all passwords must be regenerated.