Smart Passwords Library: Cryptographic password generation and management without storage. Generate passwords from secrets, verify knowledge without exposure, manage metadata securely.
By using this software, you agree to the full disclaimer terms.
Summary: Software provided "AS IS" without warranty. You assume all risks.
Full legal disclaimer: See DISCLAIMER.md
- 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:
- Smart Passwords: Generate deterministic passwords from secret phrases
- Strong Random Passwords: Cryptographically secure passwords with character diversity
- Authentication Codes: Generate secure 2FA/MFA codes with guaranteed character sets
- Base Passwords: Simple random passwords for general use
- Key Generation: Create public/private verification keys from secrets
- Secret Verification: Prove knowledge of secrets without revealing them (public key verification)
- Metadata Management: Store and update password metadata (descriptions, lengths) without storing passwords
- 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)
- Pointer-Based Security Paradigm - Architectural Shift from Data Protection to Data Non-Existence
- Local Data Regeneration Paradigm - Ontological Shift from Data Transmission to Synchronous State Discovery
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.
- New config location:
~/.config/smart_password_manager/passwords.json - Automatic migration: Legacy
~/.cases.jsonfiles are auto-migrated on first use - Cross-platform paths: Uses
Path.home()for all OS support - Safe backup: Original file preserved as
.cases.json.bak - Backward compatibility: Old files are automatically migrated, not deleted
- None! Full backward compatibility maintained
pip install smartpasslibStarting from v2.2.2, configuration files are stored in:
| Platform | Configuration Path |
|---|---|
| Linux | ~/.config/smart_password_manager/passwords.json |
| macOS | ~/.config/smart_password_manager/passwords.json |
| Windows | C:\Users\Username\.config\smart_password_manager\passwords.json |
Legacy Migration:
- Old
~/.cases.jsonfiles are automatically migrated on first use - Original file is backed up as
~/.cases.json.bak - Migration is one-time and non-destructive
Custom Path:
# Use default platform-specific path
manager = SmartPasswordManager()
# Or specify custom path
manager = SmartPasswordManager('/path/to/my/config.json')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#pGFvhHfrom 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) # Truefrom 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*DFyM4from smartpasslib import SmartPasswordManager, SmartPassword, SmartPasswordMaster
manager = SmartPasswordManager() # Automatically uses ~/.config/smart_password_manager/passwords.json
# 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#uhqVDx3GqqQzELOHBase Generator - Simple random passwords:
from smartpasslib.generators.base import BasePasswordGenerator
password = BasePasswordGenerator.generate(12)
# Output: oGHZRCv6zaZFStrong Generator - Cryptographically secure with character diversity:
from smartpasslib.generators.strong import StrongPasswordGenerator
password = StrongPasswordGenerator.generate(14) # Guarantees one of each character type
# Output: 3g4nU_4k6!c%rsCode Generator - Secure codes for authentication:
from smartpasslib.generators.code import CodeGenerator
code = CodeGenerator.generate(6) # Minimum 4 characters
# Output: Q%5ff*Smart Generator - Deterministic passwords from seeds:
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%!6Ifrom 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%'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"- CLI Smart Password Generator - Generate passwords from terminal
- CLI Smart Password Manager - Manage password metadata
- Web Smart Password Manager - Browser-based interface
- Desktop Smart Password Manager - Cross-platform desktop app
# 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 build100% test coverage - All components thoroughly tested:
- Password generators with edge cases
- Cryptographic key operations
- Metadata serialization/deserialization
- Error handling and validation
- File persistence operations
Public API (stable):
SmartPasswordMaster- Main interface classSmartPasswordManager- Metadata managementSmartPassword- Password metadata containerSmartPasswordFactory- Factory for creating metadata
Internal API (subject to change):
- All modules in
smartpasslib.generators.* smartpasslib.factories.*smartpasslib.utils.*
Copyright (©) 2026, Alexander Suvorov
- Issues: GitHub 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.
Your secret phrase is the cryptographic master key
- Permanent data loss: Lost secret phrase = irreversible loss of all derived passwords
- No recovery mechanisms: No password recovery, no secret reset, no administrative override
- Deterministic generation: Identical input (secret + parameters) = identical output (password)
- Single point of failure: Secret phrase is the sole authentication factor for all passwords
- Secure storage required: Digital storage of secret phrases is prohibited
Critical: Test password regeneration with non-essential accounts before production use
Version: 2.2.2 | Author: Alexander Suvorov