flask-advanced-auth 0.1.0__tar.gz

flask_advanced_auth-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# SQLite databases (demo/dev)
+instance/
+*.db
+
+# Env files with secrets
+backend/.env
+
+# Distribution
+dist/

flask_advanced_auth-0.1.0/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Multi-rule JWT configuration via `JWT_AUTHENTICATION_RULES` dict
+- Singleton `JWTAuthenticationRules` for centralized rule management
+- `TokenFactory` for generating and validating access and refresh tokens
+- `@authenticate` decorator for protecting Flask routes
+- `BlackListed` class for token revocation
+- `Database` singleton for bridging Flask-SQLAlchemy
+- `import_handler` utility for dynamic dotted-path imports
+- `PyJWT` proxy wrapper for encode/decode operations
+- Pydantic-backed `JWTRuleDetails` validator for rule configuration
+- `initialize_jwt_authentication()` bootstrap entry point
+- MIT License
+
+### Fixed
+- `parse_token()` was a stub — now correctly extracts token from `Authorization` header
+- `get_rule(None)` was returning the rule name string instead of the rule dict
+- `@authenticate` decorator had misplaced `return wrapper` causing it to never execute the view
+- `table` / `table_path` field aliases were misspelled as `"tabel"` / `"tabel_path"` in the Pydantic validator
+- `is_blacklisted()` was ignoring `rule_name`, always reading the default rule's blacklist setting
+- Added `_reset()` class methods to `Database` and `JWTAuthenticationRules` singletons for test isolation
+
+## [0.1.0] - TBD
+
+_Initial public release._

flask_advanced_auth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Waheed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flask_advanced_auth-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: flask-advanced-auth
+Version: 0.1.0
+Summary: Advanced JWT authentication for Flask with multi-rule support, token tracking, and blacklisting.
+Project-URL: Homepage, https://github.com/Wehda23/Flask-Advanced-Authentication
+Project-URL: Repository, https://github.com/Wehda23/Flask-Advanced-Authentication
+Project-URL: Bug Tracker, https://github.com/Wehda23/Flask-Advanced-Authentication/issues
+Author: Waheed
+License: MIT
+License-File: LICENSE
+Keywords: auth,authentication,blacklist,flask,flask-sqlalchemy,jwt,token
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: flask-sqlalchemy>=3.0.0
+Requires-Dist: flask>=2.3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-flask>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flask-advanced-auth
+
+[![PyPI version](https://img.shields.io/pypi/v/flask-advanced-auth.svg)](https://pypi.org/project/flask-advanced-auth/)
+[![Python versions](https://img.shields.io/pypi/pyversions/flask-advanced-auth.svg)](https://pypi.org/project/flask-advanced-auth/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/Wehda23/Flask-Advanced-Authentication/actions/workflows/ci.yml/badge.svg)](https://github.com/Wehda23/Flask-Advanced-Authentication/actions)
+[![Coverage](https://img.shields.io/badge/coverage-88%25-brightgreen.svg)](https://github.com/Wehda23/Flask-Advanced-Authentication)
+
+**flask-advanced-auth** is a production-grade, highly configurable JWT authentication extension for Flask and Flask-SQLAlchemy. It provides multi-rule support (different token lifetimes, secrets, and models for users vs. admins), built-in database token tracking, automatic token revocation (blacklisting), and clean route decorators.
+
+---
+
+## ✨ Features
+
+- 🔑 **Multi-Rule Authentication**: Define distinct rules for different user tiers (e.g. `users`, `managers`, `api_clients`) with independent secrets, algorithms, and lifetimes.
+- 🛡️ **Easy Route Protection**: Clean `@authenticate(auth_classes=[AuthenticateJWT])` decorator with customizable 401 response and model injection into `request.instance`.
+- 🔄 **Access & Refresh Tokens**: Native support for short-lived access tokens and long-lived refresh tokens with convenient `refresh_access_token()` helper.
+- 🚫 **Token Revocation (Blacklisting)**: Built-in revocation mechanism with database persistence and `logout()` helper.
+- 📊 **Token Tracking**: Track issued tokens in the database to detect anomalies, enforce single-session limits, or audit activity.
+- 🔌 **Multiple Extraction Strategies**: Extract tokens from `Authorization: Bearer <token>` headers, HTTP cookies, or URL query parameters.
+- ⚡ **Pydantic Validation**: Strict configuration schema validation powered by Pydantic V2 with flexible aliases.
+- 🧪 **Thoroughly Tested**: 100% test pass rate with ≥ 88% test coverage.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install flask-advanced-auth
+```
+
+Or install with development dependencies:
+
+```bash
+pip install flask-advanced-auth[dev]
+```
+
+---
+
+## 🚀 Quick Start (5 Minutes)
+
+### 1. Configure Rules & Bootstrap
+
+```python
+from datetime import timedelta
+from flask import Flask, jsonify, request
+from flask_sqlalchemy import SQLAlchemy
+from flask_advanced_auth import (
+    initialize_jwt_authentication,
+    authenticate,
+    AuthenticateJWT,
+    TokenFactory,
+    refresh_access_token,
+    logout,
+)
+
+app = Flask(__name__)
+app.config["SECRET_KEY"] = "your-app-secret"
+app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
+db = SQLAlchemy(app)
+
+# Define your JWT rules
+JWT_RULES = {
+    "default": {
+        "description": "Standard user access token",
+        "secret_key": "your-jwt-secret-key",
+        "algorithm": "HS256",
+        "access_token_lifetime": timedelta(minutes=15),
+        "refresh_token_lifetime": timedelta(days=7),
+        "token_header": "Bearer ",
+    }
+}
+
+# Initialize flask-advanced-auth
+initialize_jwt_authentication(
+    database_path="app.db",
+    rules=JWT_RULES,
+)
+```
+
+### 2. Issue Tokens on Login
+
+```python
+@app.route("/api/login", methods=["POST"])
+def login():
+    username = request.json.get("username")
+    
+    factory = TokenFactory()
+    access_token = factory.generate_token(
+        rule_name="default",
+        extra_payload={"sub": username},
+    )
+    refresh_token = factory.generate_refresh_token(
+        rule_name="default",
+        extra_payload={"sub": username},
+    )
+    
+    return jsonify({
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+    })
+```
+
+### 3. Protect Routes
+
+```python
+@app.route("/api/dashboard")
+@authenticate(auth_classes=[AuthenticateJWT], rule_name="default")
+def dashboard():
+    return jsonify({"message": "Welcome to your protected dashboard!"})
+```
+
+### 4. Refresh Tokens & Logout
+
+```python
+@app.route("/api/refresh", methods=["POST"])
+def refresh():
+    token = request.json.get("refresh_token")
+    new_access_token = refresh_access_token(token, rule_name="default")
+    return jsonify({"access_token": new_access_token})
+
+@app.route("/api/logout", methods=["POST"])
+def user_logout():
+    token = request.headers.get("Authorization", "").replace("Bearer ", "")
+    logout(token, rule_name="default")
+    return jsonify({"message": "Token revoked successfully."})
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+Rules are passed as a dictionary where each key represents a rule name (e.g. `"default"`, `"admin"`):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `description` | `str` | *Required* | Description of what this token rule is used for. |
+| `secret_key` | `str` | *Required* | Secret signing key for encoding and decoding tokens. |
+| `algorithm` | `str` | *Required* | JWT signing algorithm (e.g. `'HS256'`, `'RS256'`). |
+| `access_token_lifetime` | `timedelta` | *Required* | Expiry duration for access tokens. |
+| `refresh_token_lifetime` | `timedelta` | `None` | Expiry duration for refresh tokens. |
+| `token_header` | `str` | `'Bearer '` | Expected header prefix in `Authorization` header. |
+| `table` | `bool` | `False` | Whether to link tokens to a database entity. |
+| `table_path` | `str` | `None` | Dotted import path to model class (e.g. `'myapp.models.User'`). |
+| `track_created` | `bool` | `False` | Persist issued tokens to the database. |
+| `track_created_table_path` | `str` | `None` | Dotted import path to TrackModel class. |
+| `track_created_allow_duplicates` | `bool` | `True` | Allow multiple active tokens for the same user. |
+| `blacklisted` | `bool` | `False` | Enable token blacklist checks on verification. |
+| `blacklisted_table_path` | `str` | `None` | Dotted import path to BlackListModel class. |
+
+---
+
+## 🧩 Authentication Strategies
+
+You can choose how tokens are extracted by passing different authentication classes to `@authenticate`:
+
+```python
+from flask_advanced_auth import (
+    authenticate,
+    HeaderAuthentication,   # Reads Authorization: Bearer <token>
+    CookieAuthentication,   # Reads token from HTTP cookies
+    QueryParamAuthentication, # Reads ?token=<token>
+)
+
+# 1. From Authorization header
+@app.route("/api/v1/data")
+@authenticate(auth_classes=[HeaderAuthentication])
+def api_data():
+    return {"status": "ok"}
+
+# 2. From Cookie
+@app.route("/web/profile")
+@authenticate(auth_classes=[CookieAuthentication])
+def web_profile():
+    return {"status": "ok"}
+
+# 3. From URL parameter (e.g., SSE or WebSocket connection handshake)
+@app.route("/stream")
+@authenticate(auth_classes=[QueryParamAuthentication])
+def stream():
+    return {"status": "connected"}
+```
+
+---
+
+## 🗄️ Database Model Mixins
+
+When enabling `track_created` or `blacklisted`, use our ready-to-use SQLAlchemy model mixins:
+
+```python
+from flask_advanced_auth.models import AbstractTrackModelMixin, AbstractBlackListModelMixin
+from myapp.database import db
+
+class TrackedToken(db.Model, AbstractTrackModelMixin):
+    __tablename__ = "tracked_tokens"
+
+class BlacklistedToken(db.Model, AbstractBlackListModelMixin):
+    __tablename__ = "blacklisted_tokens"
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+# Run tests with coverage
+pytest -v
+
+# Run single test module
+pytest tests/test_decorators.py -v
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

flask_advanced_auth-0.1.0/README.md

@@ -0,0 +1,223 @@
+# flask-advanced-auth
+
+[![PyPI version](https://img.shields.io/pypi/v/flask-advanced-auth.svg)](https://pypi.org/project/flask-advanced-auth/)
+[![Python versions](https://img.shields.io/pypi/pyversions/flask-advanced-auth.svg)](https://pypi.org/project/flask-advanced-auth/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://github.com/Wehda23/Flask-Advanced-Authentication/actions/workflows/ci.yml/badge.svg)](https://github.com/Wehda23/Flask-Advanced-Authentication/actions)
+[![Coverage](https://img.shields.io/badge/coverage-88%25-brightgreen.svg)](https://github.com/Wehda23/Flask-Advanced-Authentication)
+
+**flask-advanced-auth** is a production-grade, highly configurable JWT authentication extension for Flask and Flask-SQLAlchemy. It provides multi-rule support (different token lifetimes, secrets, and models for users vs. admins), built-in database token tracking, automatic token revocation (blacklisting), and clean route decorators.
+
+---
+
+## ✨ Features
+
+- 🔑 **Multi-Rule Authentication**: Define distinct rules for different user tiers (e.g. `users`, `managers`, `api_clients`) with independent secrets, algorithms, and lifetimes.
+- 🛡️ **Easy Route Protection**: Clean `@authenticate(auth_classes=[AuthenticateJWT])` decorator with customizable 401 response and model injection into `request.instance`.
+- 🔄 **Access & Refresh Tokens**: Native support for short-lived access tokens and long-lived refresh tokens with convenient `refresh_access_token()` helper.
+- 🚫 **Token Revocation (Blacklisting)**: Built-in revocation mechanism with database persistence and `logout()` helper.
+- 📊 **Token Tracking**: Track issued tokens in the database to detect anomalies, enforce single-session limits, or audit activity.
+- 🔌 **Multiple Extraction Strategies**: Extract tokens from `Authorization: Bearer <token>` headers, HTTP cookies, or URL query parameters.
+- ⚡ **Pydantic Validation**: Strict configuration schema validation powered by Pydantic V2 with flexible aliases.
+- 🧪 **Thoroughly Tested**: 100% test pass rate with ≥ 88% test coverage.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install flask-advanced-auth
+```
+
+Or install with development dependencies:
+
+```bash
+pip install flask-advanced-auth[dev]
+```
+
+---
+
+## 🚀 Quick Start (5 Minutes)
+
+### 1. Configure Rules & Bootstrap
+
+```python
+from datetime import timedelta
+from flask import Flask, jsonify, request
+from flask_sqlalchemy import SQLAlchemy
+from flask_advanced_auth import (
+    initialize_jwt_authentication,
+    authenticate,
+    AuthenticateJWT,
+    TokenFactory,
+    refresh_access_token,
+    logout,
+)
+
+app = Flask(__name__)
+app.config["SECRET_KEY"] = "your-app-secret"
+app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
+db = SQLAlchemy(app)
+
+# Define your JWT rules
+JWT_RULES = {
+    "default": {
+        "description": "Standard user access token",
+        "secret_key": "your-jwt-secret-key",
+        "algorithm": "HS256",
+        "access_token_lifetime": timedelta(minutes=15),
+        "refresh_token_lifetime": timedelta(days=7),
+        "token_header": "Bearer ",
+    }
+}
+
+# Initialize flask-advanced-auth
+initialize_jwt_authentication(
+    database_path="app.db",
+    rules=JWT_RULES,
+)
+```
+
+### 2. Issue Tokens on Login
+
+```python
+@app.route("/api/login", methods=["POST"])
+def login():
+    username = request.json.get("username")
+    
+    factory = TokenFactory()
+    access_token = factory.generate_token(
+        rule_name="default",
+        extra_payload={"sub": username},
+    )
+    refresh_token = factory.generate_refresh_token(
+        rule_name="default",
+        extra_payload={"sub": username},
+    )
+    
+    return jsonify({
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+    })
+```
+
+### 3. Protect Routes
+
+```python
+@app.route("/api/dashboard")
+@authenticate(auth_classes=[AuthenticateJWT], rule_name="default")
+def dashboard():
+    return jsonify({"message": "Welcome to your protected dashboard!"})
+```
+
+### 4. Refresh Tokens & Logout
+
+```python
+@app.route("/api/refresh", methods=["POST"])
+def refresh():
+    token = request.json.get("refresh_token")
+    new_access_token = refresh_access_token(token, rule_name="default")
+    return jsonify({"access_token": new_access_token})
+
+@app.route("/api/logout", methods=["POST"])
+def user_logout():
+    token = request.headers.get("Authorization", "").replace("Bearer ", "")
+    logout(token, rule_name="default")
+    return jsonify({"message": "Token revoked successfully."})
+```
+
+---
+
+## ⚙️ Configuration Reference
+
+Rules are passed as a dictionary where each key represents a rule name (e.g. `"default"`, `"admin"`):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `description` | `str` | *Required* | Description of what this token rule is used for. |
+| `secret_key` | `str` | *Required* | Secret signing key for encoding and decoding tokens. |
+| `algorithm` | `str` | *Required* | JWT signing algorithm (e.g. `'HS256'`, `'RS256'`). |
+| `access_token_lifetime` | `timedelta` | *Required* | Expiry duration for access tokens. |
+| `refresh_token_lifetime` | `timedelta` | `None` | Expiry duration for refresh tokens. |
+| `token_header` | `str` | `'Bearer '` | Expected header prefix in `Authorization` header. |
+| `table` | `bool` | `False` | Whether to link tokens to a database entity. |
+| `table_path` | `str` | `None` | Dotted import path to model class (e.g. `'myapp.models.User'`). |
+| `track_created` | `bool` | `False` | Persist issued tokens to the database. |
+| `track_created_table_path` | `str` | `None` | Dotted import path to TrackModel class. |
+| `track_created_allow_duplicates` | `bool` | `True` | Allow multiple active tokens for the same user. |
+| `blacklisted` | `bool` | `False` | Enable token blacklist checks on verification. |
+| `blacklisted_table_path` | `str` | `None` | Dotted import path to BlackListModel class. |
+
+---
+
+## 🧩 Authentication Strategies
+
+You can choose how tokens are extracted by passing different authentication classes to `@authenticate`:
+
+```python
+from flask_advanced_auth import (
+    authenticate,
+    HeaderAuthentication,   # Reads Authorization: Bearer <token>
+    CookieAuthentication,   # Reads token from HTTP cookies
+    QueryParamAuthentication, # Reads ?token=<token>
+)
+
+# 1. From Authorization header
+@app.route("/api/v1/data")
+@authenticate(auth_classes=[HeaderAuthentication])
+def api_data():
+    return {"status": "ok"}
+
+# 2. From Cookie
+@app.route("/web/profile")
+@authenticate(auth_classes=[CookieAuthentication])
+def web_profile():
+    return {"status": "ok"}
+
+# 3. From URL parameter (e.g., SSE or WebSocket connection handshake)
+@app.route("/stream")
+@authenticate(auth_classes=[QueryParamAuthentication])
+def stream():
+    return {"status": "connected"}
+```
+
+---
+
+## 🗄️ Database Model Mixins
+
+When enabling `track_created` or `blacklisted`, use our ready-to-use SQLAlchemy model mixins:
+
+```python
+from flask_advanced_auth.models import AbstractTrackModelMixin, AbstractBlackListModelMixin
+from myapp.database import db
+
+class TrackedToken(db.Model, AbstractTrackModelMixin):
+    __tablename__ = "tracked_tokens"
+
+class BlacklistedToken(db.Model, AbstractBlackListModelMixin):
+    __tablename__ = "blacklisted_tokens"
+```
+
+---
+
+## 🧪 Running Tests
+
+```bash
+# Run tests with coverage
+pytest -v
+
+# Run single test module
+pytest tests/test_decorators.py -v
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

flask_advanced_auth-0.1.0/flask_advanced_auth/TokenProxy.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+"""
+Module contains proxy class for JWT token encoding and decoding.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+import jwt
+from .jwt_rules import JWTAuthenticationRules
+from datetime import datetime, timezone, timedelta
+
+
+class JsonWebToken(ABC):
+    """Abstract base class for JWT encode/decode operations (Proxy pattern)."""
+
+    @abstractmethod
+    def encode_token(self, payload: dict, secret_key: str, algorithm: str) -> str:
+        """Encode a payload into a JWT token string."""
+        pass
+
+    @abstractmethod
+    def decode_token(self, token: str, secret_key: str, algorithm: str) -> Optional[dict]:
+        """Decode a JWT token string into a payload dict."""
+        pass
+
+
+class PyJWT(JsonWebToken):
+    """Concrete JWT proxy using the PyJWT library."""
+
+    @property
+    def rule_handler(self) -> JWTAuthenticationRules:
+        return JWTAuthenticationRules()
+
+    def required_payload(self, rule_name: str, token_type: str) -> dict[str, Any]:
+        """Build the standard required payload fields (type + expiry)."""
+        token_lifetime: timedelta = self.rule_handler.get_token_lifetime(
+            rule_name, token_type
+        )
+        return {
+            "type": token_type,
+            "exp": datetime.now(timezone.utc) + token_lifetime,
+        }
+
+    def encode_token(
+        self,
+        payload: dict,
+        secret_key: str,
+        algorithm: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> str:
+        """Encode a payload dict into a signed JWT string."""
+        return jwt.encode(payload, key=secret_key, algorithm=algorithm, *args, **kwargs)
+
+    def decode_token(
+        self,
+        token: str,
+        secret_key: str,
+        algorithm: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Optional[dict]:
+        """Decode and verify a JWT token."""
+        try:
+            return jwt.decode(
+                token, key=secret_key, algorithms=[algorithm], *args, **kwargs
+            )
+        except (jwt.ExpiredSignatureError, jwt.InvalidTokenError):
+            return None