Smart Passwords Library: Cryptographic password generation and management without storage. Generate passwords from secrets, verify knowledge without exposure, manage metadata securely.
pip install smartpasslib
Smart Passwords Library: Cryptographic password generation and management without storage.
Generate passwords from secrets, verify knowledge without exposure, manage metadata securely.
Now with Cross-Platform Determinism: Same secret + same parameters = identical password on
C#, Python, Go, Kotlin, JavaScript and any language with SHA-256.
Decentralized by Design: Unlike traditional password managers that store encrypted vaults on central servers,
smartpasslib stores nothing. Your secrets never leave your device. Passwords are regenerated on-demand —
no cloud, no database, no trust required.
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
⚠️ This version is NOT backward compatible with v1.x.x, v2.x.x, or v3.x.x
Passwords generated with older versions cannot be regenerated with v4.0.0.
📖 Full migration instructions → see MIGRATION.md
secrets module and SHA-256What You Can Do:
1. Smart Passwords: Generate deterministic passwords from secret phrases (cross-platform!)
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 cryptographically secure 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
Unlike traditional password managers that store your encrypted vault on central servers, smartpasslib is decentralized by design:
Your passwords exist only when you generate them. Your secrets never leave your device.
Key Features:
- Decentralized & Serverless: No central database, no cloud lock-in, complete user sovereignty
- No Password Database: Eliminates the need for password storage
- No Secret Storage: Secret phrases never leave your control
- Cross-Platform Determinism: Same results on C#, Python, Go, Kotlin, JavaScript
- Public Key Verification: Verify secrets without exposing them
- Multiple Generator Types: Smart, strong, base, and code generators
- Store Only Public Metadata: Descriptions and public keys can be stored; private keys and secrets are NEVER persisted
- Full Test Coverage: 100% tested for reliability and security
The library implements cross-platform deterministic password generation - passwords are generated reproducibly
from secret phrases using SHA-256 cryptographic hash function.
Why SHA-256 instead of SHA3-512:
- Cross-platform standard - Available in every programming language by default
- NIST certified - FIPS 180-4 compliant, used in Bitcoin, TLS, JWT
- 256-bit security - Quantum-resistant (128-bit effective with Grover's algorithm)
- Performance - Faster on 32-bit and 64-bit systems
- Sufficient for passwords - 256 bits of entropy is impossible to brute force
Key principle: Instead of storing passwords, you store verification metadata. The actual password is regenerated on-demand from your secret.
Cross-Platform Guarantee:
- Same secret phrase + same length = identical password on any platform
- Implemented in C#, Python, Go, Kotlin, JavaScript
- Based on SHA-256 (NIST standard) — not language-specific
Decentralized Architecture:
- No central authority required
- Metadata can be synced via any channel (USB, cloud, even paper)
- Your security depends only on your secret phrase, not on any service provider
- Works offline — no internet connection required
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.
pip install smartpasslib
Configuration files are stored in:
| Platform | Configuration Path |
|---|---|
| Linux | ~/.config/smart_password_manager/passwords.json |
| Windows | C:\Users\Username\.config\smart_password_manager\passwords.json |
Legacy Migration:
- Old ~/.cases.json files from v1.x.x/v2.x.x/v3.x.x are NOT compatible with v4.0.0
- Public keys in old files use different derivation (fixed iterations, no salt)
- These files will not be migrated automatically
- If you have existing metadata, you need to recreate entries manually
- Keep old file as backup: ~/.cases.json.v3.bak
- See MIGRATION.md for detailed instructions
from smartpasslib import SmartPasswordMaster
# Your secret phrase is the only key needed (min 12 characters!)
secret = "my_strong_secret_key"
# Generate the password (CROSS-PLATFORM!)
password = SmartPasswordMaster.generate_smart_password(
secret=secret,
length=12
)
print(f"Your generated password: {password}")
from smartpasslib import SmartPasswordMaster
# Generate a public verification key (store this, not the password)
public_key = SmartPasswordMaster.generate_public_key(
secret="my_strong_secret_key"
)
# Later, verify you know the secret without revealing it
is_valid = SmartPasswordMaster.check_public_key(
secret="my_strong_secret_key",
public_key=public_key
)
print(is_valid) # True
from smartpasslib import SmartPasswordMaster
# Generate different types of passwords
base_password = SmartPasswordMaster.generate_base_password(length=12)
# Output example: MG-QwPHu6a*y
strong_password = SmartPasswordMaster.generate_strong_password(length=14)
# Output example: 7u-IOW7$#K*FHd
smart_password = SmartPasswordMaster.generate_smart_password("my_strong_secret_key", 12)
# Output deterministic password (min 12 chars secret required)
# Generate and verify keys
public_key = SmartPasswordMaster.generate_public_key("my_strong_secret_key")
is_valid = SmartPasswordMaster.check_public_key("my_strong_secret_key", public_key)
print(f"Verification: {is_valid}") # Verification: True
# Generate secure codes
auth_code = SmartPasswordMaster.generate_code(8)
# Output example: oLi&D@3s
from smartpasslib import SmartPasswordManager, SmartPassword, SmartPasswordMaster
manager = SmartPasswordManager()
# Store verification metadata (not the password and not secret phrase!)
public_key = SmartPasswordMaster.generate_public_key("MyStrongSecretPhrase2026!")
smart_pass = SmartPassword(
public_key=public_key,
description="GitHub account",
length=18
)
manager.add_smart_password(smart_pass)
# Retrieve and regenerate password when needed
stored_metadata = manager.get_smart_password(public_key)
regenerated_password = SmartPasswordMaster.generate_smart_password(
"MyStrongSecretPhrase2026!",
stored_metadata.length
)
print(regenerated_password)
Base Generator - Cryptographically secure random passwords:
from smartpasslib.generators.base import BasePasswordGenerator
password = BasePasswordGenerator.generate(12)
# Output example: Q#1&tesRzeza
Strong Generator - Cryptographically secure with character diversity:
from smartpasslib.generators.strong import StrongPasswordGenerator
password = StrongPasswordGenerator.generate(14)
# Output example: Ft7n!vJu6&9@V4
Code Generator - Secure codes for authentication:
from smartpasslib.generators.code import CodeGenerator
code = CodeGenerator.generate(6)
# Output example: M$yVc9
Smart Generator - Deterministic passwords from seeds (CROSS-PLATFORM):
from smartpasslib.generators.smart import SmartPasswordGenerator
password = SmartPasswordGenerator.generate("my_strong_secret_key", 12)
# Same secret + length = identical password on Python, Go, Kotlin, JS, C#
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):
if len(secret) < 12:
raise ValueError("Secret must be at least 12 characters")
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:
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_2026!", 20)
password = vault.get_password(key, "my_account_secret_2026!")
There is no "forgot password" button. This is by design:
This is the price of true decentralization — you are completely in control.
✅ "MyCatHippo2026" — mixed case + numbers
✅ "P@ssw0rd!LongSecret" — special chars + numbers + length
✅ "GitHubPersonal2026!" — description + extra chars (but not the description alone)
❌ "short" — too short, raises ValueError
❌ "GitHub Account" — using description as secret (weak!)
❌ "password" — dictionary word, too short
❌ "1234567890" — only digits, too short
Your secret phrase is the cryptographic master key
Critical: Test password regeneration with non-essential accounts before production use
Note: Always test password generation in your specific environment. Implementation security depends on proper usage.
NEVER use your password description as secret phrase
The same deterministic algorithm is available in multiple languages.
smartpasslib Python produces identical passwords to:
| Language | Repository |
|---|---|
| JavaScript | smartpasslib-js |
| Kotlin | smartpasslib-kotlin |
| Go | smartpasslib-go |
| C# | smartpasslib-csharp |
Core Libraries:
- smartpasslib - Python (this)
- smartpasslib-js - JavaScript
- smartpasslib-kotlin - Kotlin
- smartpasslib-go - Go
- smartpasslib-csharp - C#
CLI Applications:
- CLI Smart Password Manager (Python)
- CLI Smart Password Generator (Python)
- CLI Smart Password Manager (C#)
- CLI Smart Password Generator (C#)
Desktop Applications:
- Desktop Smart Password Manager (Python)
- Desktop Smart Password Manager (C#)
Other:
- Smart Password Web Manager
- Smart Password Android Manager
Copyright (©) 2026, Alexander Suvorov
pip install -r data/requirements-dev.txt
pytest -v --cov=smartpasslib --cov-report=html
python -m build
100% test coverage - All components thoroughly tested
Public API (stable):
- SmartPasswordMaster - Main interface class
- SmartPasswordManager - Metadata management
- SmartPassword - Password metadata container
Internal API (subject to change):
- smartpasslib.generators.*
- smartpasslib.utils.*