TT-auth-system 2.3.12
An authentication system with one-time login links, templated email sending, and SQLite database support
Requires Python: >=3.6

### OTC Auth System

The OTC Auth system is a Python package that provides a simple authentication mechanism using one-time login links. Users receive an email containing a unique login link, generated by the package, which allows them to authenticate without a password. This package is intended to be integrated into larger projects, providing reusable authentication functionality.

# Installation

To install the package, clone the repository or download the source code. Navigate to the root directory of the package and run:

pip3 install TT_auth_system

This command installs the package and its dependencies.

# Setup and Configuration

## Environment Variables

The package relies on several environment variables to configure its behavior, particularly for SMTP settings, database access, encryption, and the base URL of the login link. These should be set in a `.env` file in the root of the main project using the package.

Create a `.env` file with the following variables:

- **SMTP_SERVER**: The address of the SMTP server used to send emails (e.g., smtp.example.com).
- **SMTP_PORT**: The port number for the SMTP server (commonly 587 for TLS or 465 for SSL).
- **SMTP_USERNAME**: The username for SMTP authentication.
- **SMTP_PASSWORD**: The password for SMTP authentication.
- **LOGIN_LINK_BASE_URL**: The base URL for the login link sent to users. This should point to the part of your application that handles login (e.g., https://yourapp.com/login).
- **REPLY_TO_ADDR** (optional): The reply-to email address for the emails sent. If not provided, no reply-to address will be set.
- **FERNET_KEY**: A 32-byte base64-encoded key for Fernet encryption. This key is used to encrypt and decrypt codes.
- **EXPIRATION_TIME**: The time in seconds for which a one-time code remains valid (e.g., 600 seconds for 10 minutes).
- **DB_PATH**: The path to the SQLite database file used to store user data and codes.

## Example `.env` file:

# SMTP Configuration
SMTP_SERVER=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your_smtp_username
SMTP_PASSWORD=your_smtp_password

# Base URL for Login Link
LOGIN_LINK_BASE_URL=https://yourapp.com/login
BASE_URL=http://yourapp.com

# Optional Reply-To Address
REPLY_TO_ADDR=replyto@example.com

# Encryption Key for Fernet (should be 32 bytes in base64)
FERNET_KEY=your_base64_encoded_key

# Expiration Time for Codes (in seconds)
EXPIRATION_TIME=600

# Path to SQLite Database File
DB_PATH=users.db

# Root User to be added if users table is empty
ROOT_USER=example@gmail.com

# Lifespan of the HttpOnly cookie in seconds
COOKIE_LIFE=1800

## HTML Email Template

The package sends an HTML email containing the login link. The HTML template can be passed as a string to the class, or it can be placed in the `templates` directory at the root of the main project. If using a file, it should be named `otc_email.html`.

### Directory Structure:
main_project/
    ├── .env
    ├── templates/
    │   └── otc_email.html
    └── main_script.py

### Example `otc_email.html`:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Login Link</title>
</head>
<body>
    <p>Hello, {{ first_name }},</p>
    <p>Click the link below to log in:</p>
    <p><a href="{{ login_link }}">{{ login_link }}</a></p>
    <p>This link is valid for one-time use only.</p>
    <p>Best regards,<br>Your App Team</p>
</body>
</html>

The `{{ login_link }}` and `{{ first_name }}` placeholders will be replaced with the actual login link and the user’s first name when the email is sent.

# Usage

To use the package in your project, create an instance of the `OTCAuthSystem` class and use its methods for generating and sending emails, validating codes, and managing users:

from TT_auth_system import OTCAuthSystem

# Initialize the auth system
auth_system = OTCAuthSystem()

# Generate a one-time code and send a login email if the email exists in the database
code = auth_system.generate_and_send_email("user@example.com")

# Validate a code (returns the associated email if valid as well as set an HttpOnly Cookie, None otherwise)
is_valid = auth_system.validate_code(code)

# Purge all valid codes from the database
auth_system.purge_valid_codes()

# Get all users from the database
all_users = auth_system.get_all_users()

# Edit a user in the database by user ID
auth_system.edit_user(user_id=1, FirstName="John", LastName="Doe")

# Delete a user from the database by user ID
auth_system.delete_user(user_id=1)

# Get a specific user by email
user = auth_system.get_user_by_email("user@example.com")

# Add a full user
new_user = auth_system.add_user(first_name=first_name, last_name=last_name, email_address=email_address, authorized_flag=authorized_flag, admin_flag=admin_flag)

# Dependencies
The package depends on the following Python libraries:

- **python-dotenv**: For loading environment variables from a `.env` file.
- **jinja2**: For rendering HTML templates.
- **smtplib**: Part of Python’s standard library, used for sending emails via SMTP.
- **cryptography**: For secure encryption and decryption using Fernet.
- **sqlalchemy**: For interacting with the SQLite database.

These dependencies are automatically installed when you install the package using pip.

# Testing

The package includes support for testing with `pytest`. To facilitate testing, dependencies such as database connections and SMTP clients can be injected, allowing for easy mocking.

# License

This project is licensed under the MIT License. See the LICENSE file for details.