smartpasslib (Smart Passwords Library) ^v2.1.0

Smart Passwords Library: Cryptographic password generation and management without storage. Generate passwords from secrets, verify knowledge without exposure, manage metadata securely.

🔐 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:

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)

⚠️ Critical Notice

BEFORE USING THIS SOFTWARE, READ THE COMPLETE LEGAL DISCLAIMER BELOW

View Legal Disclaimer & Liability Waiver

Usage of this software constitutes acceptance of all terms and conditions.

📚 Research Paradigms & Publications

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

🔬 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.0

⚠️ CRITICAL WARNING: Upgrading to v2.1.0 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:

# v1.x → v2.1.0
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:

# v1.x → v2.1.0
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:

# v1.x
password = SmartPasswordMaster.generate_smart_password(
    login="service", 
    secret="mysecret", 
    length=12
)

# v2.1.0
password = SmartPasswordMaster.generate_smart_password(
    secret="mysecret", 
    length=12
)

SmartPassword Creation:

# v1.x
sp = SmartPassword(
    login="GitHub", 
    key=public_key, 
    length=16
)

# v2.1.0
sp = SmartPassword(
    public_key=public_key,
    description="GitHub", 
    length=16
)

Manager Operations:

# v1.x (deprecated methods)
manager.add(password)
manager.get_password("login")

# v2.1.0
manager.add_smart_password(sp)
manager.get_smart_password(public_key)

Metadata Updates (New):

# 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:

Simplified API - Single secret parameter instead of login + secret
Cleaner Code - Removed all deprecated methods and legacy code
Better Security - Streamlined cryptographic operations
Full Test Coverage - 100% test coverage ensures reliability
Clearer Naming - public_key accurately represents verification key
Metadata Updates - New update() methods for description and length

Note: v2.1.0 is not backward compatible with v1.x. Update your code according to the migration guide.

📦 Installation

pip install smartpasslib

🚀 Quick Start

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

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

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

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:

from smartpasslib.generators.base import BasePasswordGenerator
password = BasePasswordGenerator.generate(12)
# Output: oGHZRCv6zaZF

Strong 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%rs

Code 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%!6I

💡 Advanced Usage

Password Management System

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

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 - Generate passwords from terminal
CLI Smart Password Manager - Manage password metadata

Graphical Applications

Web Smart Password Manager - Browser-based interface
Desktop Smart Password Manager - Cross-platform desktop app

👨‍💻 For Developers

Development Setup

# 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

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
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.0 passwords are incompatible with v1.x. Never mix secret phrases across different versions.

Secret Phrase Security

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

📄 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:

ANY AND ALL DATA LOSS: Complete or partial loss of passwords, accounts, credentials, cryptographic keys, or any data whatsoever
ANY AND ALL SECURITY INCIDENTS: Unauthorized access, data breaches, account compromises, theft, or exposure of sensitive information
ANY AND ALL FINANCIAL LOSSES: Direct, indirect, incidental, special, consequential, or punitive damages of any kind
ANY AND ALL OPERATIONAL DISRUPTIONS: Service interruptions, account lockouts, authentication failures, or denial of service
ANY AND ALL IMPLEMENTATION ISSUES: Bugs, errors, vulnerabilities, misconfigurations, or incorrect usage
ANY AND ALL LEGAL OR REGULATORY CONSEQUENCES: Violations of laws, regulations, compliance requirements, or terms of service
ANY AND ALL PERSONAL OR BUSINESS DAMAGES: Reputational harm, business interruption, loss of revenue, or any other damages
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.0 | Author: Alexander Suvorov

Note: This is v2.1.0. If migrating from v1.x, all passwords must be regenerated.

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github/workflows		.github/workflows
data		data
smartpasslib		smartpasslib
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

License

smartlegionlab/smartpasslib

Folders and files

Latest commit

History

Repository files navigation

smartpasslib (Smart Passwords Library) v2.1.0