quart-security 1.0.0__tar.gz

quart_security-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest -q

quart_security-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    if: github.repository == 'level09/quart-security'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/quart-security
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quart_security-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.uv-cache/
+.venv/

quart_security-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 quart-security maintainers
+
+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.

quart_security-1.0.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.1
+Name: quart-security
+Version: 1.0.0
+Summary: Native async auth for Quart
+Author: quart-security maintainers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: quart>=0.20.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: libpass>=1.9
+Requires-Dist: pyotp>=2.9
+Requires-Dist: qrcode>=8.0
+Requires-Dist: webauthn>=2.0
+Requires-Dist: wtforms>=3.1
+Requires-Dist: aiosmtplib>=3.0
+Requires-Dist: blinker>=1.7
+Requires-Dist: itsdangerous>=2.1
+Requires-Dist: email-validator>=2.0
+Requires-Dist: pytest>=8.0 ; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23 ; extra == "dev"
+Requires-Dist: ruff>=0.6 ; extra == "dev"
+Project-URL: Homepage, https://github.com/level09/quart-security
+Project-URL: Issues, https://github.com/level09/quart-security/issues
+Project-URL: Repository, https://github.com/level09/quart-security
+Provides-Extra: dev
+
+# quart-security
+
+`quart-security` is a native async authentication extension for Quart.
+
+It is designed as a practical replacement path for Flask-Security style session auth in Quart applications, without Flask shims and without Flask-Login.
+
+## What You Get
+
+### Core auth
+- Session-based login and logout
+- Email/password registration
+- Password change flow (including OAuth-style users that don’t know an initial random password)
+- `current_user` proxy
+- `@auth_required("session")` and `@roles_required(...)`
+
+### MFA
+- TOTP setup and verification
+- Recovery code generation and one-time consumption
+
+### WebAuthn (passkeys / security keys)
+- Credential registration
+- Passwordless sign-in (first factor)
+- Authenticated verification flow (step-up / second factor)
+- Credential deletion
+
+### Extension and compatibility surface
+- Quart extension pattern (`Security(app, datastore)`)
+- Flask-Security-style endpoint naming through `url_for_security()`
+- Signals for auth lifecycle events
+- Overridable templates under `templates/security/`
+
+## Non-Goals (Current Scope)
+
+This project intentionally focuses on session auth and MFA currently in active use:
+- No token-based API auth
+- No SMS/email OTP
+- No account locking workflow
+- No remember-me token system
+
+## Installation
+
+### Install from repository
+
+```bash
+uv add git+https://github.com/level09/quart-security.git
+```
+
+### Local development
+
+```bash
+uv sync --group dev
+uv run pytest -q
+```
+
+Package build backend: `flit`.
+
+## Quick Integration
+
+```python
+from quart import Quart
+from quart_security import Security, SQLAlchemyUserDatastore
+
+# your models should include fields used by auth, roles, and MFA/WebAuthn
+from myapp.models import db, User, Role, WebAuthnCredential
+
+
+def create_app():
+    app = Quart(__name__)
+
+    app.config.update(
+        SECRET_KEY="change-me",
+        SECURITY_PASSWORD_SALT="change-me-too",
+        SECURITY_POST_LOGIN_VIEW="/dashboard",
+        SECURITY_POST_REGISTER_VIEW="/login",
+    )
+
+    db.init_app(app)
+    datastore = SQLAlchemyUserDatastore(
+        db,
+        User,
+        Role,
+        webauthn_model=WebAuthnCredential,
+    )
+
+    Security(app, datastore)
+    return app
+```
+
+## Required Model Surface
+
+Your user/role models are expected to provide the fields used by active features.
+
+Minimum practical user fields:
+- `fs_uniquifier`
+- `email`
+- `password`
+- `active`
+- `roles`
+
+For tracking / MFA / WebAuthn features:
+- `last_login_at`, `current_login_at`, `last_login_ip`, `current_login_ip`, `login_count`
+- `tf_primary_method`, `tf_totp_secret`, `mf_recovery_codes`
+- `fs_webauthn_user_handle`
+- relationship/association for stored WebAuthn credentials
+
+## Key Configuration
+
+The extension uses `SECURITY_*` keys for migration-friendly configuration.
+
+Core:
+- `SECURITY_PASSWORD_HASH` (default: `pbkdf2_sha512`)
+- `SECURITY_PASSWORD_SALT` (recommended)
+- `SECURITY_PASSWORD_LENGTH_MIN` (default: `12`)
+- `SECURITY_REGISTERABLE`
+- `SECURITY_CHANGEABLE`
+- `SECURITY_TRACKABLE`
+- `SECURITY_CSRF_PROTECT` (default: `True`)
+
+2FA:
+- `SECURITY_TWO_FACTOR`
+- `SECURITY_TOTP_ISSUER`
+- `SECURITY_MULTI_FACTOR_RECOVERY_CODES`
+- `SECURITY_MULTI_FACTOR_RECOVERY_CODES_N`
+
+WebAuthn:
+- `SECURITY_WEBAUTHN`
+- `SECURITY_WAN_ALLOW_AS_FIRST_FACTOR`
+- `SECURITY_WAN_ALLOW_AS_MULTI_FACTOR`
+- `SECURITY_WAN_RP_ID` (optional override)
+- `SECURITY_WAN_RP_NAME` (optional override)
+- `SECURITY_WAN_EXPECTED_ORIGIN` (optional override)
+- `SECURITY_WAN_REQUIRE_USER_VERIFICATION` (default: `True`)
+
+Routing:
+- `SECURITY_POST_LOGIN_VIEW`
+- `SECURITY_POST_REGISTER_VIEW`
+
+## Route Map
+
+Core:
+- `/login`
+- `/register`
+- `/logout`
+- `/change`
+
+2FA:
+- `/tf-setup`
+- `/tf-validate`
+- `/tf-select`
+- `/mf-recovery-codes`
+- `/mf-recovery`
+
+WebAuthn:
+- `/wan-register`
+- `/wan-register-response`
+- `/wan-signin`
+- `/wan-signin-response`
+- `/wan-verify`
+- `/wan-verify-response`
+- `/wan-delete`
+
+## Template Overrides
+
+Default templates are intentionally simple and framework-neutral.
+
+Override by placing templates with the same names under your app’s
+`templates/security/` directory.
+
+## Public API
+
+```python
+from quart_security import (
+    Security,
+    SQLAlchemyUserDatastore,
+    current_user,
+    auth_required,
+    roles_required,
+    UserMixin,
+    RoleMixin,
+    hash_password,
+    verify_password,
+    user_authenticated,
+    user_logged_out,
+    password_changed,
+    tf_profile_changed,
+    user_registered,
+    url_for_security,
+)
+```
+
+## Testing
+
+Project tests cover:
+- password hashing/validation
+- auth and role decorators
+- register/login/logout/change-password
+- TOTP and recovery code flows
+- WebAuthn register/sign-in/verify/delete route behavior
+
+Run:
+
+```bash
+uv run pytest -q
+```
+
+### WebAuthn staging validation (recommended before release tags)
+
+Run this in a HTTPS staging environment with production-like hostnames and real browser prompts:
+
+1. Register a passkey from `/wan-register` and verify it is persisted with expected `name`, `usage`, and `sign_count`.
+2. Complete passwordless sign-in from `/wan-signin` with the same credential.
+3. Complete authenticated verify flow from `/wan-verify` while already signed in.
+4. Delete credential from `/wan-delete` and confirm subsequent passkey auth fails for that credential.
+5. Repeat step 1 and step 2 with a second authenticator type (for example platform passkey + hardware key) to validate device portability assumptions.
+
+## Notes for Production
+
+- Run behind HTTPS for WebAuthn in non-local environments.
+- Set explicit WebAuthn RP values (`SECURITY_WAN_RP_ID`, `SECURITY_WAN_EXPECTED_ORIGIN`) when behind proxies or multiple domains.
+- Keep CSRF protection enabled unless you have a deliberate replacement.
+

quart_security-1.0.0/README.md

@@ -0,0 +1,220 @@
+# quart-security
+
+`quart-security` is a native async authentication extension for Quart.
+
+It is designed as a practical replacement path for Flask-Security style session auth in Quart applications, without Flask shims and without Flask-Login.
+
+## What You Get
+
+### Core auth
+- Session-based login and logout
+- Email/password registration
+- Password change flow (including OAuth-style users that don’t know an initial random password)
+- `current_user` proxy
+- `@auth_required("session")` and `@roles_required(...)`
+
+### MFA
+- TOTP setup and verification
+- Recovery code generation and one-time consumption
+
+### WebAuthn (passkeys / security keys)
+- Credential registration
+- Passwordless sign-in (first factor)
+- Authenticated verification flow (step-up / second factor)
+- Credential deletion
+
+### Extension and compatibility surface
+- Quart extension pattern (`Security(app, datastore)`)
+- Flask-Security-style endpoint naming through `url_for_security()`
+- Signals for auth lifecycle events
+- Overridable templates under `templates/security/`
+
+## Non-Goals (Current Scope)
+
+This project intentionally focuses on session auth and MFA currently in active use:
+- No token-based API auth
+- No SMS/email OTP
+- No account locking workflow
+- No remember-me token system
+
+## Installation
+
+### Install from repository
+
+```bash
+uv add git+https://github.com/level09/quart-security.git
+```
+
+### Local development
+
+```bash
+uv sync --group dev
+uv run pytest -q
+```
+
+Package build backend: `flit`.
+
+## Quick Integration
+
+```python
+from quart import Quart
+from quart_security import Security, SQLAlchemyUserDatastore
+
+# your models should include fields used by auth, roles, and MFA/WebAuthn
+from myapp.models import db, User, Role, WebAuthnCredential
+
+
+def create_app():
+    app = Quart(__name__)
+
+    app.config.update(
+        SECRET_KEY="change-me",
+        SECURITY_PASSWORD_SALT="change-me-too",
+        SECURITY_POST_LOGIN_VIEW="/dashboard",
+        SECURITY_POST_REGISTER_VIEW="/login",
+    )
+
+    db.init_app(app)
+    datastore = SQLAlchemyUserDatastore(
+        db,
+        User,
+        Role,
+        webauthn_model=WebAuthnCredential,
+    )
+
+    Security(app, datastore)
+    return app
+```
+
+## Required Model Surface
+
+Your user/role models are expected to provide the fields used by active features.
+
+Minimum practical user fields:
+- `fs_uniquifier`
+- `email`
+- `password`
+- `active`
+- `roles`
+
+For tracking / MFA / WebAuthn features:
+- `last_login_at`, `current_login_at`, `last_login_ip`, `current_login_ip`, `login_count`
+- `tf_primary_method`, `tf_totp_secret`, `mf_recovery_codes`
+- `fs_webauthn_user_handle`
+- relationship/association for stored WebAuthn credentials
+
+## Key Configuration
+
+The extension uses `SECURITY_*` keys for migration-friendly configuration.
+
+Core:
+- `SECURITY_PASSWORD_HASH` (default: `pbkdf2_sha512`)
+- `SECURITY_PASSWORD_SALT` (recommended)
+- `SECURITY_PASSWORD_LENGTH_MIN` (default: `12`)
+- `SECURITY_REGISTERABLE`
+- `SECURITY_CHANGEABLE`
+- `SECURITY_TRACKABLE`
+- `SECURITY_CSRF_PROTECT` (default: `True`)
+
+2FA:
+- `SECURITY_TWO_FACTOR`
+- `SECURITY_TOTP_ISSUER`
+- `SECURITY_MULTI_FACTOR_RECOVERY_CODES`
+- `SECURITY_MULTI_FACTOR_RECOVERY_CODES_N`
+
+WebAuthn:
+- `SECURITY_WEBAUTHN`
+- `SECURITY_WAN_ALLOW_AS_FIRST_FACTOR`
+- `SECURITY_WAN_ALLOW_AS_MULTI_FACTOR`
+- `SECURITY_WAN_RP_ID` (optional override)
+- `SECURITY_WAN_RP_NAME` (optional override)
+- `SECURITY_WAN_EXPECTED_ORIGIN` (optional override)
+- `SECURITY_WAN_REQUIRE_USER_VERIFICATION` (default: `True`)
+
+Routing:
+- `SECURITY_POST_LOGIN_VIEW`
+- `SECURITY_POST_REGISTER_VIEW`
+
+## Route Map
+
+Core:
+- `/login`
+- `/register`
+- `/logout`
+- `/change`
+
+2FA:
+- `/tf-setup`
+- `/tf-validate`
+- `/tf-select`
+- `/mf-recovery-codes`
+- `/mf-recovery`
+
+WebAuthn:
+- `/wan-register`
+- `/wan-register-response`
+- `/wan-signin`
+- `/wan-signin-response`
+- `/wan-verify`
+- `/wan-verify-response`
+- `/wan-delete`
+
+## Template Overrides
+
+Default templates are intentionally simple and framework-neutral.
+
+Override by placing templates with the same names under your app’s
+`templates/security/` directory.
+
+## Public API
+
+```python
+from quart_security import (
+    Security,
+    SQLAlchemyUserDatastore,
+    current_user,
+    auth_required,
+    roles_required,
+    UserMixin,
+    RoleMixin,
+    hash_password,
+    verify_password,
+    user_authenticated,
+    user_logged_out,
+    password_changed,
+    tf_profile_changed,
+    user_registered,
+    url_for_security,
+)
+```
+
+## Testing
+
+Project tests cover:
+- password hashing/validation
+- auth and role decorators
+- register/login/logout/change-password
+- TOTP and recovery code flows
+- WebAuthn register/sign-in/verify/delete route behavior
+
+Run:
+
+```bash
+uv run pytest -q
+```
+
+### WebAuthn staging validation (recommended before release tags)
+
+Run this in a HTTPS staging environment with production-like hostnames and real browser prompts:
+
+1. Register a passkey from `/wan-register` and verify it is persisted with expected `name`, `usage`, and `sign_count`.
+2. Complete passwordless sign-in from `/wan-signin` with the same credential.
+3. Complete authenticated verify flow from `/wan-verify` while already signed in.
+4. Delete credential from `/wan-delete` and confirm subsequent passkey auth fails for that credential.
+5. Repeat step 1 and step 2 with a second authenticator type (for example platform passkey + hardware key) to validate device portability assumptions.
+
+## Notes for Production
+
+- Run behind HTTPS for WebAuthn in non-local environments.
+- Set explicit WebAuthn RP values (`SECURITY_WAN_RP_ID`, `SECURITY_WAN_EXPECTED_ORIGIN`) when behind proxies or multiple domains.
+- Keep CSRF protection enabled unless you have a deliberate replacement.

quart_security-1.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["flit_core>=3.9,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "quart-security"
+version = "1.0.0"
+description = "Native async auth for Quart"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "quart-security maintainers" },
+]
+dependencies = [
+  "quart>=0.20.0",
+  "sqlalchemy>=2.0",
+  "libpass>=1.9",
+  "pyotp>=2.9",
+  "qrcode>=8.0",
+  "webauthn>=2.0",
+  "wtforms>=3.1",
+  "aiosmtplib>=3.0",
+  "blinker>=1.7",
+  "itsdangerous>=2.1",
+  "email-validator>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/level09/quart-security"
+Repository = "https://github.com/level09/quart-security"
+Issues = "https://github.com/level09/quart-security/issues"
+
+[tool.flit.module]
+name = "quart_security"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.uv]
+default-groups = ["dev"]

quart_security-1.0.0/quart_security/__init__.py

@@ -0,0 +1,34 @@
+"""Public API for quart-security."""
+
+from .core import Security
+from .datastore import SQLAlchemyUserDatastore
+from .decorators import auth_required, roles_required
+from .models import RoleMixin, UserMixin
+from .password import hash_password, verify_password
+from .proxies import current_user
+from .signals import (
+    password_changed,
+    tf_profile_changed,
+    user_authenticated,
+    user_logged_out,
+    user_registered,
+)
+from .utils import url_for_security
+
+__all__ = [
+    "Security",
+    "SQLAlchemyUserDatastore",
+    "auth_required",
+    "roles_required",
+    "UserMixin",
+    "RoleMixin",
+    "hash_password",
+    "verify_password",
+    "current_user",
+    "user_authenticated",
+    "user_logged_out",
+    "password_changed",
+    "tf_profile_changed",
+    "user_registered",
+    "url_for_security",
+]