TT-auth-system 1.1.0

An authentication system with one-time login links and templated email sending

OTC Auth System

This 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).
•	DB_HOST: The database server host.
•	DB_PORT: The database server port (commonly 3306 for MySQL).
•	DB_USER: The username for the database.
•	DB_PASSWORD: The password for the database.
•	DB_NAME: The name of the database.
•	DB_TABLE: The name of the table containing user data.
•	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).
•	JSON_FILE_PATH: The path to the JSON file used for storing 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

Optional Reply-To Address

REPLY_TO_ADDR=[e-mail]

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 JSON File for Storing Codes

JSON_FILE_PATH=auth_codes.json

Database Configuration

DB_HOST=db.example.com DB_PORT=3306 DB_USER=db_user DB_PASSWORD=db_password DB_NAME=db_name DB_TABLE=users_table

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:

<title>Login Link</title>

Hello, {{ first_name }},

Click the link below to log in:

{{ login_link }}

This link is valid for one-time use only.

Best regards,
Your App Team

The {{ login_link }} and {{ first_name }} placeholders will be replaced with the actual login link and 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 purging old codes:

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(“[e-mail]”)

Validate a code (returns the associated email if valid, None otherwise)

is_valid = auth_system.validate_code(code)

Purge all valid codes from memory

auth_system.purge_valid_codes()

Dependencies

The package depends on the following Python libraries:

•	python-dotenv: For loading environment variables from a .env file.
•	jinja2: For rendering HTML templates.
•	pymysql: For connecting to a MySQL database.
•	smtplib: Part of Python’s standard library, used for sending emails via SMTP.
•	cryptography: For secure encryption and decryption using Fernet.

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. A sample pytest test file is provided to illustrate how to test the main functionalities of the package.

License

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