olauth 0.1.0a0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,34 @@
1
+ name: Publish to PyPI
2
+
3
+ # Trigger the workflow when a new release is created on GitHub
4
+ on:
5
+ release:
6
+ types: [published]
7
+
8
+ jobs:
9
+ deploy:
10
+ runs-on: ubuntu-latest
11
+ # Required for secure, passwordless authentication with PyPI (OIDC)
12
+ permissions:
13
+ id-token: write
14
+ contents: read
15
+
16
+ steps:
17
+ - name: Checkout code
18
+ uses: actions/checkout@v4
19
+
20
+ - name: Set up Python
21
+ uses: actions/setup-python@v5
22
+ with:
23
+ python-version: '3.x'
24
+
25
+ - name: Install build tools
26
+ run: |
27
+ python -m pip install --upgrade pip
28
+ pip install build
29
+
30
+ - name: Build package
31
+ run: python -m build
32
+
33
+ - name: Publish to PyPI
34
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,22 @@
1
+ # Virtual Environment
2
+ .venv/
3
+ venv/
4
+ ENV/
5
+
6
+ # Python Cache & Build Artifiacts
7
+ __pycache__/
8
+ *.pyc
9
+ *.pyo
10
+ *.pyd
11
+ .pytest_cache/
12
+ build/
13
+ dist/
14
+ *.egg-info/
15
+
16
+ # Local Databases (Crucial for security!)
17
+ *.db
18
+ *.sqlite3
19
+
20
+ # Environment Variables / Private Keys
21
+ .env
22
+ .env.*
olauth-0.1.0a0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jakub Drábik
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,72 @@
1
+ Metadata-Version: 2.4
2
+ Name: olauth
3
+ Version: 0.1.0a0
4
+ Summary: The zero-config, one-liner authentication engine for Python web frameworks.
5
+ Author-email: Your Name <your.email@example.com>
6
+ License-File: LICENSE
7
+ Classifier: License :: OSI Approved :: MIT License
8
+ Classifier: Operating System :: OS Independent
9
+ Classifier: Programming Language :: Python :: 3
10
+ Requires-Python: >=3.8
11
+ Requires-Dist: bcrypt>=4.0.0
12
+ Description-Content-Type: text/markdown
13
+
14
+ # OL-Auth (v0.1.0-alpha)
15
+
16
+ OL-Auth is a lightweight, zero-configuration authentication engine designed to eliminate bootstrap friction in Python web applications. By initializing the library with a single line of code, it provisions a local data store, manages password encryption, and serves responsive, system-adaptive **Log in** and **Sign up** interfaces directly into your application.
17
+
18
+ ---
19
+
20
+ ## 🎯 Ideal for Hackathons & Rapid Prototyping
21
+
22
+ When building prototypes or competing in hackathons, setting up authentication flows (tables, encryption, form handling, and UI styling) repeatedly eats up valuable hours. OL-Auth handles this scaffolding instantly so you can focus entirely on building your core features.
23
+
24
+ ### Current Status: Flask Only
25
+ > ⚠️ **Note:** OL-Auth is currently in an early **Alpha** development phase. It presently **only supports the Flask framework** and utilizes an internal, automated SQLite database.
26
+
27
+ ---
28
+
29
+ ## 📦 Installation (Local Development)
30
+
31
+ Since the package is in alpha and not yet published to PyPI, install it in editable mode within your virtual environment:
32
+
33
+ ```bash
34
+ pip install -e .
35
+ ```
36
+ ## 💻 Usage Example
37
+
38
+ ```python
39
+ from flask import Flask
40
+ import olauth
41
+
42
+ app = Flask(__name__)
43
+
44
+ # Single-line initialization: automatically builds tables and mounts routes
45
+ olauth.init(app)
46
+
47
+ @app.route("/")
48
+ def home():
49
+ return 'Welcome! Visit <a href="/signup">/signup</a> to create an account.'
50
+
51
+ if __name__ == "__main__":
52
+ app.run(debug=True)
53
+ ```
54
+
55
+ Once initialized, the library automatically registers and serves the following endpoints:
56
+ * `/signup` — Renders the registration form and handles user creation.
57
+ * `/login` — Renders the authentication form and verifies credentials.
58
+
59
+ ## 🛠️ Upcoming Roadmap
60
+
61
+ We are actively developing the core foundation to bring this library to a stable Beta release. The immediate roadmap focuses on the following four milestones:
62
+
63
+ 1. **Session Validation & State Handling:** Integrating secure token generation and browser cookie management to keep users authenticated across page requests.
64
+ 2. **FastAPI Engine Support:** Replicating the routing injection logic via `APIRouter` to support FastAPI applications.
65
+ 3. **Targeted Database Connectors:** Expanding the database driver layer to allow seamless scaling by supporting connection strings for:
66
+ * **PostgreSQL** (Enterprise relational storage)
67
+ * **MongoDB** (NoSQL document storage)
68
+ 4. **Performance Optimization:** Tuning connection pooling and cryptographic work-factors to resolve initial execution slowness.
69
+
70
+ ## 📄 License
71
+
72
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,59 @@
1
+ # OL-Auth (v0.1.0-alpha)
2
+
3
+ OL-Auth is a lightweight, zero-configuration authentication engine designed to eliminate bootstrap friction in Python web applications. By initializing the library with a single line of code, it provisions a local data store, manages password encryption, and serves responsive, system-adaptive **Log in** and **Sign up** interfaces directly into your application.
4
+
5
+ ---
6
+
7
+ ## 🎯 Ideal for Hackathons & Rapid Prototyping
8
+
9
+ When building prototypes or competing in hackathons, setting up authentication flows (tables, encryption, form handling, and UI styling) repeatedly eats up valuable hours. OL-Auth handles this scaffolding instantly so you can focus entirely on building your core features.
10
+
11
+ ### Current Status: Flask Only
12
+ > ⚠️ **Note:** OL-Auth is currently in an early **Alpha** development phase. It presently **only supports the Flask framework** and utilizes an internal, automated SQLite database.
13
+
14
+ ---
15
+
16
+ ## 📦 Installation (Local Development)
17
+
18
+ Since the package is in alpha and not yet published to PyPI, install it in editable mode within your virtual environment:
19
+
20
+ ```bash
21
+ pip install -e .
22
+ ```
23
+ ## 💻 Usage Example
24
+
25
+ ```python
26
+ from flask import Flask
27
+ import olauth
28
+
29
+ app = Flask(__name__)
30
+
31
+ # Single-line initialization: automatically builds tables and mounts routes
32
+ olauth.init(app)
33
+
34
+ @app.route("/")
35
+ def home():
36
+ return 'Welcome! Visit <a href="/signup">/signup</a> to create an account.'
37
+
38
+ if __name__ == "__main__":
39
+ app.run(debug=True)
40
+ ```
41
+
42
+ Once initialized, the library automatically registers and serves the following endpoints:
43
+ * `/signup` — Renders the registration form and handles user creation.
44
+ * `/login` — Renders the authentication form and verifies credentials.
45
+
46
+ ## 🛠️ Upcoming Roadmap
47
+
48
+ We are actively developing the core foundation to bring this library to a stable Beta release. The immediate roadmap focuses on the following four milestones:
49
+
50
+ 1. **Session Validation & State Handling:** Integrating secure token generation and browser cookie management to keep users authenticated across page requests.
51
+ 2. **FastAPI Engine Support:** Replicating the routing injection logic via `APIRouter` to support FastAPI applications.
52
+ 3. **Targeted Database Connectors:** Expanding the database driver layer to allow seamless scaling by supporting connection strings for:
53
+ * **PostgreSQL** (Enterprise relational storage)
54
+ * **MongoDB** (NoSQL document storage)
55
+ 4. **Performance Optimization:** Tuning connection pooling and cryptographic work-factors to resolve initial execution slowness.
56
+
57
+ ## 📄 License
58
+
59
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,27 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "olauth"
7
+ version = "0.1.0-alpha"
8
+ description = "The zero-config, one-liner authentication engine for Python web frameworks."
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ authors = [
12
+ { name = "Your Name", email = "your.email@example.com" }
13
+ ]
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "License :: OSI Approved :: MIT License",
17
+ "Operating System :: OS Independent",
18
+ ]
19
+
20
+ # Crucial: These are the external libraries pip will auto-download for your users
21
+ dependencies = [
22
+ "bcrypt>=4.0.0",
23
+ ]
24
+
25
+ # This tells Hatch exactly where your package source files live
26
+ [tool.hatch.build.targets.wheel]
27
+ packages = ["src/olauth"]
@@ -0,0 +1,5 @@
1
+ from .core import olauth
2
+
3
+ init = olauth.init
4
+
5
+ __all__ = ["init", "olauth"]
@@ -0,0 +1,33 @@
1
+ import sys
2
+ from .database import DatabaseManager
3
+
4
+ class OLAuth:
5
+ """Core orchestrator responsible for framework detection and routing injection."""
6
+
7
+ def __init__(self):
8
+ self.db = DatabaseManager()
9
+ self.framework = None
10
+
11
+ def init(self, app, db=None):
12
+ """Discovers the host framework at runtime and mounts the corresponding auth engine."""
13
+ self.db.initialize_db(db)
14
+
15
+ # Stringify the module path to safely identify the framework without hard imports
16
+ app_type = f"{type(app).__module__}.{type(app).__name__}"
17
+
18
+ if "flask" in app_type:
19
+ self.framework = "flask"
20
+ # Lazy-load engine to avoid importing unused framework dependencies
21
+ from .engine_flask import inject_flask
22
+ inject_flask(app, self.db)
23
+
24
+ elif "fastapi" in app_type or "starlette" in app_type:
25
+ self.framework = "fastapi"
26
+ from .engine_fastapi import inject_fastapi
27
+ inject_fastapi(app, self.db)
28
+
29
+ else:
30
+ raise ValueError(f"[OL-Auth] Unsupported framework: {app_type}")
31
+
32
+ # Export a single global instance for the one-liner initialization pattern
33
+ olauth = OLAuth()
@@ -0,0 +1,20 @@
1
+ import bcrypt
2
+
3
+ def hash_password(password: str) -> str:
4
+ """Derives a secure cryptographic hash from a plaintext password using bcrypt."""
5
+ password_bytes = password.encode('utf-8')
6
+
7
+ # Explicitly configure a standard work factor (12 rounds) to balance security and performance
8
+ salt = bcrypt.gensalt(rounds=12)
9
+ hashed_bytes = bcrypt.hashpw(password_bytes, salt)
10
+
11
+ return hashed_bytes.decode('utf-8')
12
+
13
+
14
+ def verify_password(password: str, hashed_password: str) -> bool:
15
+ """Performs a constant-time cryptographic check to prevent timing attacks."""
16
+ password_bytes = password.encode('utf-8')
17
+ hashed_bytes = hashed_password.encode('utf-8')
18
+
19
+ # Safely extract salt properties internally from the stored hash string
20
+ return bcrypt.checkpw(password_bytes, hashed_bytes)
@@ -0,0 +1,74 @@
1
+ import sqlite3
2
+ import os
3
+
4
+ class DatabaseManager:
5
+ """Manages local SQLite connections, schemas, and data persistence layers."""
6
+
7
+ def __init__(self):
8
+ self.connection = None
9
+
10
+ def initialize_db(self, db_path=None):
11
+ """Establishes database connection, configures execution pragmas, and builds schemas."""
12
+ if db_path is None:
13
+ db_path = "olauth.db"
14
+ elif db_path.startswith("sqlite:///"):
15
+ db_path = db_path.replace("sqlite:///", "")
16
+
17
+ # check_same_thread=False allows cross-thread connection sharing required by web servers
18
+ self.connection = sqlite3.connect(db_path, check_same_thread=False)
19
+
20
+ # Enable key-value row factories for clean, dict-like record lookups
21
+ self.connection.row_factory = sqlite3.Row
22
+
23
+ cursor = self.connection.cursor()
24
+
25
+ # Write-Ahead Logging yields high-concurrency performance under concurrent web traffic
26
+ cursor.execute("PRAGMA journal_mode=WAL;")
27
+
28
+ # --- SCHEMA PROVISIONING ---
29
+ cursor.execute("""
30
+ CREATE TABLE IF NOT EXISTS users (
31
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
32
+ email TEXT UNIQUE NOT NULL,
33
+ password_hash TEXT NOT NULL,
34
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
35
+ );
36
+ """)
37
+
38
+ cursor.execute("""
39
+ CREATE TABLE IF NOT EXISTS olauth_sessions (
40
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
41
+ token TEXT UNIQUE NOT NULL,
42
+ user_id INTEGER NOT NULL,
43
+ expires_at TIMESTAMP NOT NULL,
44
+ FOREIGN KEY(user_id) REFERENCES users(id)
45
+ );
46
+ """)
47
+
48
+ self.connection.commit()
49
+ print(f"[OL-Auth] Database initialized and secured at: {db_path}")
50
+
51
+ # --- DATA READ/WRITE OPERATIONS ---
52
+
53
+ def create_user(self, email, hashed_password):
54
+ """Inserts a new secure user record. Returns False on unique constraint conflicts."""
55
+ cursor = self.connection.cursor()
56
+ try:
57
+ cursor.execute(
58
+ "INSERT INTO users (email, password_hash) VALUES (?, ?)",
59
+ (email.lower().strip(), hashed_password)
60
+ )
61
+ self.connection.commit()
62
+ return True
63
+ except sqlite3.IntegrityError:
64
+ # Trap unique email errors smoothly without breaking the application runtime
65
+ return False
66
+
67
+ def get_user_by_email(self, email):
68
+ """Queries the identity table for an exact email match returning a row-mapped instance."""
69
+ cursor = self.connection.cursor()
70
+ cursor.execute(
71
+ "SELECT id, email, password_hash FROM users WHERE email = ?",
72
+ (email.lower().strip(),)
73
+ )
74
+ return cursor.fetchone()
@@ -0,0 +1,7 @@
1
+ def inject_fastapi(app, db):
2
+ """Placeholder initialization for the upcoming FastAPI routing engine.
3
+
4
+ This will be fully implemented in the v0.2.0-alpha milestone.
5
+ """
6
+ # Temporarily pass safely so the application boot sequence doesn't crash
7
+ pass
@@ -0,0 +1,125 @@
1
+ from flask import Blueprint, request, render_template_string, redirect, make_response
2
+ from .crypto import hash_password, verify_password
3
+
4
+ # Monolithic HTML framework view template leveraging native Jinja2 compilation context
5
+ BASE_HTML = """
6
+ <!DOCTYPE html>
7
+ <html lang="en">
8
+ <head>
9
+ <meta charset="UTF-8">
10
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
11
+ <title>{{ title }}</title>
12
+ <style>
13
+ :root {
14
+ --bg: #ffffff; --text: #111111; --border: #e2e8f0; --input-bg: #ffffff;
15
+ --btn-bg: #000000; --btn-text: #ffffff; --btn-hover: #1a1a1a; --focus-ring: #000000;
16
+ }
17
+ @media (prefers-color-scheme: dark) {
18
+ :root {
19
+ --bg: #0b0f19; --text: #f9fafb; --border: #374151; --input-bg: #111827;
20
+ --btn-bg: #ffffff; --btn-text: #000000; --btn-hover: #e5e7eb; --focus-ring: #ffffff;
21
+ }
22
+ }
23
+ body { background-color: var(--bg); color: var(--text); font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; display: flex; min-height: 100vh; align-items: center; justify-content: center; margin: 0; padding: 24px; box-sizing: border-box; }
24
+ .card { width: 100%; max-width: 400px; padding: 40px 32px; border: 1px solid var(--border); border-radius: 12px; box-sizing: border-box; }
25
+ h1 { font-size: 24px; font-weight: 700; margin: 0 0 8px 0; letter-spacing: -0.5px; }
26
+ .error-msg { color: #ef4444; font-size: 14px; margin-bottom: 16px; font-weight: 500; }
27
+ .field { margin-bottom: 20px; }
28
+ label { display: block; font-size: 14px; font-weight: 500; margin-bottom: 6px; opacity: 0.85; }
29
+ input { width: 100%; padding: 12px; font-size: 16px; font-family: inherit; border: 1px solid var(--border); border-radius: 6px; background-color: var(--input-bg); color: var(--text); box-sizing: border-box; }
30
+ input:focus { outline: none; border-color: var(--focus-ring); box-shadow: 0 0 0 2px var(--bg), 0 0 0 4px var(--focus-ring); }
31
+ button { width: 100%; padding: 12px; font-size: 16px; font-weight: 600; font-family: inherit; border-radius: 6px; border: none; background-color: var(--btn-bg); color: var(--btn-text); cursor: pointer; }
32
+ button:hover { background-color: var(--btn-hover); }
33
+ .switch-text { margin-top: 20px; font-size: 14px; text-align: center; opacity: 0.7; }
34
+ .switch-text a { color: var(--text); font-weight: 600; text-decoration: underline; }
35
+ </style>
36
+ </head>
37
+ <body>
38
+ <div class="card">
39
+ <h1>{{ heading }}</h1>
40
+
41
+ {% if error %}
42
+ <div class="error-msg">{{ error }}</div>
43
+ {% endif %}
44
+
45
+ <form method="POST">
46
+ <div class="field">
47
+ <label for="email">Email address</label>
48
+ <input type="email" id="email" name="email" required placeholder="you@example.com">
49
+ </div>
50
+ <div class="field">
51
+ <label for="password">Password</label>
52
+ <input type="password" id="password" name="password" required placeholder="••••••••">
53
+ </div>
54
+ <button type="submit">{{ button_text }}</button>
55
+ <div class="switch-text">
56
+ {{ switch_prompt }} <a href="{{ switch_url }}">{{ switch_action }}</a>
57
+ </div>
58
+ </form>
59
+ </div>
60
+ </body>
61
+ </html>
62
+ """
63
+
64
+ def inject_flask(app, db):
65
+ """Dynamically registers authentication endpoints and view logic onto the host Flask application."""
66
+
67
+ olauth_bp = Blueprint("olauth", __name__)
68
+
69
+ # --- SIGN UP FLOW ---
70
+ @olauth_bp.route("/signup", methods=["GET", "POST"])
71
+ def signup():
72
+ error = ""
73
+ if request.method == "POST":
74
+ email = request.form.get("email")
75
+ password = request.form.get("password")
76
+
77
+ hashed = hash_password(password)
78
+ success = db.create_user(email, hashed)
79
+
80
+ if success:
81
+ return redirect("/login")
82
+ else:
83
+ error = "An account with that email already exists."
84
+
85
+ # Bind template layout to the sign-up context properties
86
+ return render_template_string(
87
+ BASE_HTML,
88
+ title="Sign up",
89
+ heading="Create an account",
90
+ button_text="Sign up",
91
+ error=error,
92
+ switch_prompt="Already have an account?",
93
+ switch_url="/login",
94
+ switch_action="Log in"
95
+ )
96
+
97
+ # --- LOG IN FLOW ---
98
+ @olauth_bp.route("/login", methods=["GET", "POST"])
99
+ def login():
100
+ error = ""
101
+ if request.method == "POST":
102
+ email = request.form.get("email")
103
+ password = request.form.get("password")
104
+
105
+ user = db.get_user_by_email(email)
106
+
107
+ if user and verify_password(password, user["password_hash"]):
108
+ return f"Success! Logged in as: {user['email']}"
109
+ else:
110
+ error = "Invalid email or password."
111
+
112
+ # Bind template layout to the log-in context properties
113
+ return render_template_string(
114
+ BASE_HTML,
115
+ title="Log in",
116
+ heading="Log in to your account",
117
+ button_text="Log in",
118
+ error=error,
119
+ switch_prompt="Don't have an account?",
120
+ switch_url="/signup",
121
+ switch_action="Sign up"
122
+ )
123
+
124
+ # Mount the fully configured authorization routing tier to the core runtime application
125
+ app.register_blueprint(olauth_bp)
@@ -0,0 +1,12 @@
1
+ from flask import Flask
2
+ import olauth
3
+
4
+ app = Flask(__name__)
5
+ olauth.init(app)
6
+
7
+ @app.route("/")
8
+ def home():
9
+ return '<h1>Welcome to the App</h1><p>Go to <a href="/signup">/signup</a> to try OL-Auth!</p>'
10
+
11
+ if __name__ == "__main__":
12
+ app.run(debug=True, port=5000)