OL-Auth (v1.0.0)
OL-Auth is a lightweight, zero-configuration authentication engine for Python web applications. With a single line of code, it provisions your user & session tables, handles password hashing and persistent cookie sessions, protects routes, and serves responsive light/dark Sign up and Log in pages.
✨ Features
- Zero-config local dev, easy cloud scaling: Defaults to SQLite (WAL mode), and switches to PostgreSQL or MySQL via a standard connection string (
db=orOLAUTH_DATABASE_URL). - Flask & FastAPI out of the box: Auto-detects the framework and mounts
/signup,/login, and/logout. - One-line route protection: Use
@olauth.login_requiredin Flask orDepends(olauth.login_required)in FastAPI, and readolauth.current_user()anywhere. - Production-minded security defaults:
bcryptpassword hashing (12 rounds, safe handling for >72-byte passwords) and constant-time login checks.- Persistent opaque session tokens stored as SHA-256 digests in
olauth_sessions. HttpOnly,SameSite=Laxcookies (with automaticSecureflag over HTTPS).- CSRF same-origin
POSTchecks (Origin/Sec-Fetch-Site), open-redirect validation on?next=, XSS-escaped templates, and per-IP sliding-window rate limiting.
📦 Installation
Install directly from PyPI:
# Core package
pip install olauth
# With web framework extras
pip install "olauth[flask]"
pip install "olauth[fastapi]"
# Optional database drivers for cloud hosting
pip install "olauth[postgres]"
pip install "olauth[mysql]"
# Combine extras as needed (e.g. FastAPI + PostgreSQL)
pip install "olauth[fastapi,postgres]"
💻 Quickstart
Flask
from flask import Flask
import olauth
app = Flask(__name__)
olauth.init(app) # Creates olauth.db and mounts /signup, /login, /logout
@app.route("/")
def home():
user = olauth.current_user()
if user:
return f"Welcome back, {user['email']}! <a href='/logout'>Log out</a>"
return "Hello guest! <a href='/login'>Log in</a>"
@app.route("/dashboard")
@olauth.login_required
def dashboard():
user = olauth.current_user()
return f"Protected dashboard for user #{user['id']} ({user['email']})"
if __name__ == "__main__":
app.run(debug=True)
In Flask Jinja templates, current_user is also automatically injected into the template context.
FastAPI
from fastapi import Depends, FastAPI
import olauth
app = FastAPI()
olauth.init(app)
@app.get("/")
def home(user: dict | None = Depends(olauth.current_user)):
return {"user": user}
@app.get("/dashboard")
def dashboard(user: dict = Depends(olauth.login_required)):
return {"message": f"Hello {user['email']}", "user_id": user["id"]}
- Browser requests (
Accept: text/html) to protected FastAPI routes redirect (303) to/login?next=.... - API/JSON clients receive
401 Unauthorized.
🗄️ Databases (SQLite, PostgreSQL, MySQL)
Pass a connection URL to olauth.init(app, db=...) or set the OLAUTH_DATABASE_URL environment variable:
import os
import olauth
# 1. Zero-config SQLite (default: olauth.db)
olauth.init(app)
# 2. Custom SQLite path
olauth.init(app, db="sqlite:///data/app.db")
# 3. PostgreSQL (requires `pip install "olauth[postgres]"`)
olauth.init(app, db=os.getenv("DATABASE_URL")) # e.g. postgresql://user:pass@host:5432/db
# 4. MySQL (requires `pip install "olauth[mysql]"`)
olauth.init(app, db="mysql://user:pass@host:3306/db")
✉️ Email Verification (Opt-In 6-Digit Code)
Email verification is off by default so hackathons and prototypes stay instant. When you want to verify emails, use the built-in zero-dependency SMTP sender, console mode, or a custom callback:
# 1. Built-in SMTP sender (defaults to Gmail SSL on port 465; or set OLAUTH_SMTP_USER / OLAUTH_SMTP_PASSWORD)
olauth.init(
app,
smtp_user="myapp@gmail.com",
smtp_password="xxxx-xxxx-xxxx-xxxx", # App Password
)
# 2. Local dev mode: prints the 6-digit code in your terminal with zero credentials
olauth.init(app, verify_email="console")
# 3. Custom sender (Resend, SendGrid, Postmark, etc.)
olauth.init(
app,
send_verification_code=lambda email, code: send_my_email(
to=email,
subject="Your verification code",
text=f"Your verification code is: {code}",
),
)
When enabled:
/signupcreates the account unverified, hashes and stores a single-use 6-digit code, sends it, and redirects to/verify.- Unverified users trying to
/loginare sent a fresh code and redirected to/verify(403for JSON requests). - Submitting the code on
/verifyactivates the account and logs the user in.
⚙️ Configuration Options
All options have safe defaults and can be customized in olauth.init(...):
| Parameter | Default | Description |
|---|---|---|
db |
None (olauth.db) |
SQLite path/URI, postgresql://..., or mysql://... (falls back to OLAUTH_DATABASE_URL). |
redirect_to |
"/" |
Default destination after successful login/signup when ?next= is absent. |
login_url |
"/login" |
Route for login and destination when unauthenticated browser requests are redirected. |
verify_url |
"/verify" |
Route for entering the 6-digit email verification code. |
cookie_name |
"olauth_session" |
Name of the HttpOnly session cookie. |
session_ttl |
604800 (7 days) |
Session lifetime in seconds. |
verification_ttl |
900 (15 min) |
Email verification code lifetime in seconds. |
cookie_secure |
None (auto) |
Force Secure cookie flag (True/False), or auto-detect from HTTPS / X-Forwarded-Proto. |
auto_login_on_signup |
True |
Immediately issue a session cookie upon account creation (or verification). |
min_password_length |
8 |
Minimum password length enforced on /signup. |
rate_limit |
15 |
Failed auth attempts per client IP allowed per 60-second sliding window (0 disables). |
verify_email |
False |
Set to "console" for terminal verification codes during local dev. |
smtp_user |
None |
SMTP username/sender address (falls back to OLAUTH_SMTP_USER). |
smtp_password |
None |
SMTP password/app password (falls back to OLAUTH_SMTP_PASSWORD). |
smtp_host |
"smtp.gmail.com" |
SMTP server hostname for built-in email delivery. |
smtp_port |
465 |
SMTP port (465 uses SSL; other ports use STARTTLS). |
send_verification_code |
None |
Optional custom callback (email, code) -> None overriding the built-in sender. |
🧪 Running Tests
pip install -e ".[dev]"
pytest
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for olauth 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| olauth-1.0.0.tar.gz | 27.8 kB | With provenance | Details for olauth-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| olauth-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for olauth-1.0.0-py3-none-any.whl |
Total release size: 51.2 kB
Release files / olauth-1.0.0.tar.gz
| Download URL | olauth-1.0.0.tar.gz |
|---|---|
| Size | 27.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f07a4db0adfae43657fdf5c135f80cdf0529801702c95bebddd8e6b6ca9650f4
|
|
BLAKE2b-256 checksum How to use checksums |
a5ac91a8cc33b47ca1eac02533e33a217b8e5127d803f64c83ce3b28f1e2282f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / olauth-1.0.0-py3-none-any.whl
| Download URL | olauth-1.0.0-py3-none-any.whl |
|---|---|
| Size | 23.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e3a4a31a1a2b1846a322c767e6018b1332acbbed1b0c232a3104fe862ed5c3c6
|
|
BLAKE2b-256 checksum How to use checksums |
4fe75f79a98e34d4847709913947867e5ba56476783f8a061eaba19173dac034
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for olauth 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for olauth-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.