Metadata-Version: 2.4
Name: authsmith
Version: 0.0.1
Summary: Authentication artifact generator library for Python
Author-email: Cristian Cezar Botez <cx2b+dev@disroot.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://pypi.org/project/authsmith
Project-URL: Source, https://codeberg.org/cx2b/authsmith
Project-URL: Issues, https://codeberg.org/cx2b/authsmith/issues
Project-URL: Repository, https://codeberg.org/cx2b/authsmith.git
Project-URL: Changelog, https://codeberg.org/cx2b/authsmith/CHANGELOG.md
Keywords: authentication,security,secret,password,pin,passphrase,username,hexadecimal,uuid,recovery codes,entropy,generator,library
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: numpy
Dynamic: license-file

# Abstract

[_authsmith_](https://codeberg.org/cx2b/authsmith "Authentication artifact generator library for Python") is a unified interface for generating cryptographically strong passwords, passphrases, PINs, recovery codes, usernames and similar user-facing authentication artifacts suitable for managing data such as account authentication, security tokens (GPG keys, disk-encryption) and related secrets.

A short, funny and easy way to understand passphrases can be found at [_xkcd: Password Strength_](https://xkcd.com/936/ "A webcomic of romance, sarcasm, math and language.").

<br>


# Features

Due to its simplicity, _authsmith_ offers from the start the opportunity to build upon and adapt it to a variety of use cases.

Its flexible architecture ensures support for [future development](#next "Future development"). It has been designed to be adaptable to new requirements while minimizing complete system remake.

_authsmith_ is open source and committed to respect your freedoms, including your freedom to share and change the software (see [LICENSE](#license "GNU General Public License version 3 or any later version")).

<br>


# Technical Notes

- programming language: [Python](https://www.python.org/ "Python, the programming language") 3.13.5
- version control system: [git](https://git-scm.com/ "Distributed version control system")
- dependencies: [NumPy](https://pypi.org/project/numpy/ "Fundamental package for array computing in Python")
- testing: [pytest](https://pypi.org/project/pytest/ "Framework to write small, readable tests")
- building and distributing: [setuptools](https://pypi.org/project/setuptools/ "Build and distribute packages")
- documentation: [Sphinx](https://pypi.org/project/Sphinx/ "Documentation generator")
- audience: software developers

Notable changes in [CHANGELOG](CHANGELOG.md "History and notable changes").

<br>


# Installation

You can get started with _authsmith_ by installing it from [PyPI](https://pypi.org/project/authsmith "Authentication artifact generator library for Python") (recommended). As always, it is best practice to use a virtual environment while you evaluate its features.

**Note**: How you create and activate a virtual environment is not covered here.

```
pip install authsmith
```

Then open a Python session and enter the following commands. A successful installation returns the version number.

``` python
import authsmith

print(authsmith.__version__)
```

<br>


# Development

Clone the repository to get a local copy of the _authsmith_ source code.

```
git clone https://codeberg.org/cx2b/authsmith.git
```

Activate the virtual environment (recommended) and install the package in editable mode.

```
pip install -e .
```

<br>


# Examples

Some introductory examples below (more in the `examples` directory).

## Generate password

``` python
from authsmith.models.context import (
    Context
)

from authsmith.services.artifacts import (
    Artifacts
)

context = Context()

context.size = 18

artifacts = Artifacts(context)

random = artifacts.password(lowercase=6, uppercase=6, digits=2, punctuation=-1, ignore="Ol")

result = "".join(random)

print("password:", result)
```


## Calculate entropy

``` python
from authsmith.services.artifacts import (
    Entropy
)


def explain_strength(value: int) -> str:
    if value < 28:
        message = "very weak; trivial to crack"
    elif value < 35:
        message = "weak; seconds to minutes to crack"
    elif value < 59:
        message = "moderate; hours to days to crack"
    elif value < 79:
        message = "strong; weeks to months to crack"
    elif value < 127:
        message = "very strong; centuries to crack"
    else:
        message = "excellent cryptographic strength"

    return message


password = "3aSBtW4JrJJEL0qt2p"

randomness = Entropy.shannon_entropy(list(password))
strength = Entropy.combinatorial_entropy(list(password))

print(f"password: {password}")
print(f"randomness: {randomness:.2f}")
print(f"strength: {explain_strength(strength)}")
```

<br>


# Next

In no particular order:

- ~~generate unique random characters~~
- ~~generate unique passwords~~
- ~~generate PIN codes~~
- ~~generate user name as combination of letters and digits~~
- ~~generate random hexadecimal codes~~
- ~~generate random cryptographically-secure UUID identifiers~~
- generate recovery codes
- generate API keys
- generate code matrices
- generate Apple-style, easier to remember passwords
- generate unique customizable passphrases
- generate passphrases using the dice method
- add total length (in characters) as requirement for passphrase generation
- option to remove words that are considered offensive
- limits to how long words can be in a passphrase
- option to mix digits and special characters in passphrases
- option to mix uppercase and lowercase letters in passphrases
- ~~calculate entropy (randomness)~~
- ~~calculate entropy (strength)~~
- generate passwords and passphrases in bulk
- add Sphinx configuration files

<br>

# Contributing

Currently, contributing to this project is limited to reporting [issues](issues "Issues on Codeberg") and participating in discussions about feature requests and improvements.

Your feedback is always welcome.

<br>

# License

_authsmith_ is free software and released under the _GNU General Public License version 3 or any later version_. Refer to [LICENSE](COPYING "GNU General Public License version 3 or any later version") for further information about licensing. If not received, see [Licenses - GNU Project - Free Software Foundation](https://www.gnu.org/licenses/ "Licenses, evaluating licenses, other resources").

<br>

----------------------------------------------------------------------

This file is part of _authsmith_ and under the _GNU All-Permissive License_.

Copyright (C) 2026 Cristian Cezar Botez

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.
