fauth 0.1.0__tar.gz

fauth-0.1.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

fauth-0.1.0/.github/workflows/cicd.yml

@@ -0,0 +1,181 @@
+name: CI
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+
+permissions:
+  id-token: write
+  contents: write
+  actions: write
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        with:
+          token: ${{ env.GH_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.11'
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-groups --frozen
+
+      - name: Run lint and format checks
+        id: format
+        run: |
+          uv run poe format
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.11'
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-groups --frozen
+
+      - name: Run unit tests
+        env:
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: |
+          uv run poe test
+
+  requirements:
+    name: Requirements
+    if: github.ref != 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          fetch-depth: 0
+          ref: ${{ github.head_ref }}
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.11'
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-groups --frozen
+
+      - name: Generate requirements.txt
+        run: |
+          uv pip compile pyproject.toml -o requirements.txt
+
+      - name: Commit and push requirements.txt
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add requirements.txt
+          git diff --staged --quiet || git commit -m "chore(config): update requirements.txt"
+          git push origin HEAD:${{ github.head_ref }}
+
+  versioning:
+    name: Versioning
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v6
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        with:
+          token: ${{ env.GH_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.11'
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-groups --frozen
+
+      - name: Bump version and update changelog
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.21.1
+        with:
+          github_token: ${{ secrets.GH_TOKEN }}
+
+    outputs:
+      released: ${{ steps.release.outputs.released }}
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    if: needs.versioning.outputs.released == 'true'
+    needs: [versioning]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fauth
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.11'
+          python-version: '3.13'
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fauth-0.1.0/.github/workflows/pre-commit-autoupdate.yml

@@ -0,0 +1,53 @@
+# The workflow checks out the repository, installs pre-commit, and runs the autoupdate command.
+# If there are any updates, it creates a pull request with the changes.
+
+name: Pre-commit Update
+
+on:
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch: # Allows manual triggering of the workflow
+
+permissions:
+  contents: read
+
+jobs:
+  auto-update:
+    permissions:
+      contents: write
+      pull-requests: write
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: '0.9.11'
+          python-version: '3.13'
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-groups --frozen
+
+      - name: Autoupdate pre-commit hooks
+        working-directory: '.'
+        run: uv run pre-commit autoupdate
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v8
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        with:
+          token: ${{ env.GH_TOKEN }}
+          branch: chore/pre-commit-autoupdate
+          title: Update pre-commit hooks
+          commit-message: 'chore(config): update pre-commit hooks'
+          body: |
+            This PR was created automatically by the pre-commit autoupdate workflow.
+            It updates the pre-commit hooks to their latest versions.
+          labels: update

fauth-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+*.so
+
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+MANIFEST
+
+.venv/
+venv/
+ENV/
+env/
+
+pip-log.txt
+pip-delete-this-directory.txt
+
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+.mypy_cache/
+dmypy.json
+dmypy.txt
+.ruff_cache/
+
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+.DS_Store
+Thumbs.db
+
+.env
+.env.*

fauth-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,58 @@
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.25
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: detect-private-key
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.15.6'
+    hooks:
+      - id: ruff-check
+        name: ruff
+        args: ['--fix']
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.9.4
+    hooks:
+      - id: bandit
+        args: ['-r', '-lll']
+
+  - repo: https://github.com/pylint-dev/pylint
+    rev: v4.0.5
+    hooks:
+      - id: pylint
+        types: [python]
+        additional_dependencies:
+          - loguru==0.7.3
+          - pydantic==2.12.4
+          - pydantic-settings==2.12
+          - uvicorn==0.38.0
+          - pytest==9.0.2
+          - polyfactory==3.2.0
+          - fastapi==0.135.1
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - loguru==0.7.3
+          - pydantic==2.12.4
+          - pydantic-settings==2.12
+          - pytest==9.0.2
+          - polyfactory==3.2.0
+          - fastapi==0.135.1
+          - pyjwt==2.11.0
+          - pwdlib==0.3.0

fauth-0.1.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# CHANGELOG
+
+
+## v0.1.0 (2026-03-29)
+
+### Bug Fixes
+
+- Add tests for core and api modules
+  ([`cb6ed8a`](https://github.com/justmatias/fauth/commit/cb6ed8aabca0e4de41054cfd1857e1f41973d55c))
+
+- Add tests for create_access_token
+  ([`eae2201`](https://github.com/justmatias/fauth/commit/eae22013a94a56e931fbd2ba21f1800b90a4fd29))
+
+- Add tests for jwt utilities and password utilities.
+  ([`23f6345`](https://github.com/justmatias/fauth/commit/23f6345412be42eb6377f3bd008e4c0700b29ccb))
+
+- Add unit tests and fixtures for the authentication provider.
+  ([`e81e447`](https://github.com/justmatias/fauth/commit/e81e447391307df431a419439b30c46ab6f3f0cd))
+
+### Chores
+
+- Add polyfactory as new development dependencies.
+  ([`e36e895`](https://github.com/justmatias/fauth/commit/e36e895fff0843218efcf425c75bb6ed66e29ad6))
+
+- Add pypi publishing job
+  ([`e8f5ba0`](https://github.com/justmatias/fauth/commit/e8f5ba07326dd058ed7df1f3881a7831ba563392))
+
+- Fix lint issues
+  ([`8e18b2f`](https://github.com/justmatias/fauth/commit/8e18b2f4d093a05f897033c97241158dab727100))
+
+- Improve type hints, update dependencies, and apply minor stylistic adjustments across several
+  modules
+  ([`1d55d31`](https://github.com/justmatias/fauth/commit/1d55d31cb7bd143dc353a44628c6f3575e571420))
+
+- Restructure main package
+  ([`f0d7236`](https://github.com/justmatias/fauth/commit/f0d723698da27d74cb7db9c7ca3a0ef2b1e129a2))
+
+- **config**: Merge with main
+  ([`c66d1eb`](https://github.com/justmatias/fauth/commit/c66d1eb612a2caebe790d20ce4a7f162ee49b6a4))
+
+- **config**: Update pre-commit hooks
+  ([`77a8f95`](https://github.com/justmatias/fauth/commit/77a8f95d330ea0570a04ca8bd5bbccc72554e5e4))
+
+- **config**: Update requirements.txt
+  ([`13b718a`](https://github.com/justmatias/fauth/commit/13b718aae048d817191fe26a96b6fd964f59e82a))
+
+- **config**: Update requirements.txt
+  ([`ec11b90`](https://github.com/justmatias/fauth/commit/ec11b90eb30ab24a5b384c5b9662077fea46d903))
+
+- **config**: Update requirements.txt
+  ([`08fed86`](https://github.com/justmatias/fauth/commit/08fed86e03f8bd6e3ec902dfc1d13225406be4a6))
+
+### Features
+
+- Implement core authentication logic, transports, and testing utilities
+  ([`7abbd34`](https://github.com/justmatias/fauth/commit/7abbd343405c93fc86de1c454b51c94a25b04774))
+
+
+## v0.0.0 (2026-03-10)
+
+### Chores
+
+- Add initial project readme and detailed design plan
+  ([`161b2e0`](https://github.com/justmatias/fauth/commit/161b2e0fa87b5b1d04d83496e50076362e9874f6))
+
+- Introduce package and document new testing utilities including fakes and factories.
+  ([`52f3299`](https://github.com/justmatias/fauth/commit/52f32998d9095d825d7a1059be535dd7121814e6))
+
+- Update readme
+  ([`1e50ee3`](https://github.com/justmatias/fauth/commit/1e50ee3d59747f19d9c54a85858c786d4a95cfbe))
+
+- **config**: Initialize new fauth project with core structure, dependency management, CI/CD, and
+  code quality tooling
+  ([`0fe70cf`](https://github.com/justmatias/fauth/commit/0fe70cf7e453e404db44b64828ce5dc5bc440f73))

fauth-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matías Giménez
+
+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.

fauth-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: fauth
+Version: 0.1.0
+Summary: Ergonomic, lightweight JWT authentication for FastAPI. Secure your routes instantly with plug-and-play dependency injection
+Project-URL: Homepage, https://github.com/justmatias/fauth
+Project-URL: Repository, https://github.com/justmatias/fauth
+Project-URL: Issues, https://github.com/justmatias/fauth/issues
+Author-email: Matias Gimenez <matiasgimenez.dev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,fastapi,jwt,rbac,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.100
+Requires-Dist: pwdlib[argon2]>=0.2
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyjwt[crypto]>=2.8
+Description-Content-Type: text/markdown
+
+# FAuth
+
+An ergonomic, plug-and-play authentication library for FastAPI.
+
+`fauth` eliminates boilerplate around JWT, password hashing, user fetching, and Role-Based Access Control (RBAC) by leveraging FastAPI's Dependency Injection (`Depends`), Pydantic models, and Python Protocols.
+
+## Features
+
+- **Protocol-Based User Fetching**: Complete inversion of control. You implement a simple `UserLoader` protocol to define how to fetch a user from a token payload.
+- **Plug-and-Play Configuration**: Centralized settings via Pydantic (`AuthConfig`). Configure once, inject everywhere.
+- **Pluggable Transports**: Extensible `Transport` protocol with a built-in `BearerTransport` for Authorization header tokens.
+- **Built-in Password Hashing**: Uses modern Argon2 via `pwdlib`.
+- **RBAC**: Flexible `require_roles` and `require_permissions` dependencies for endpoint authorization.
+- **Secure Router**: `SecureAPIRouter` applies authentication as a router-level dependency, securing all its routes automatically.
+- **Testing Utilities**: Ships fake implementations (`FakeUserLoader`) and a `build_fake_auth_provider()` factory so consumers can write unit tests with zero boilerplate.
+- **Type Safety**: Fully annotated for MyPy and IDE integration.
+
+## Quick Start
+
+```bash
+pip install fauth
+```
+
+```bash
+uv add fauth
+```
+
+## How to use FAuth
+
+To adopt FAuth, define an async user lookup function (implementing the `UserLoader` protocol), supply an `AuthConfig`, and instantiate the `AuthProvider`. You can then inject the provider directly into FastAPI endpoints.
+
+```python
+from fastapi import FastAPI, Depends
+from pydantic import BaseModel
+from fauth import AuthConfig, AuthProvider, TokenPayload, SecureAPIRouter
+
+app = FastAPI()
+
+# 1. Define your internal user model
+class User(BaseModel):
+    id: str
+    username: str
+    is_active: bool = True
+    roles: list[str] = []
+
+# Mock database
+DB: dict[str, User] = {
+    "user-123": User(id="user-123", username="alice", roles=["admin"])
+}
+
+# 2. Define the callback that retrieves a user from the decoded JWT
+async def load_user(payload: TokenPayload) -> User | None:
+    return DB.get(payload.sub)
+
+# 3. Instantiate the auth component (ideally wired in DI or at module-level)
+config = AuthConfig(secret_key="my-super-secret-key", algorithm="HS256")
+auth: AuthProvider[User] = AuthProvider(config=config, user_loader=load_user)
+
+# --- Routes ---
+
+@app.post("/login")
+async def login():
+    # Example logic: password hashing checks omitted for brevity
+    # 4. Use `auth.login` to issue tokens
+    return await auth.login(sub="user-123")
+
+@app.get("/me")
+async def get_me(user: User = Depends(auth.require_user())):
+    # 5. `auth.require_user()` secures the endpoint automatically
+    return {"message": f"Hello {user.username}"}
+
+@app.get("/admin")
+async def get_admin_data(user: User = Depends(auth.require_roles("admin"))):
+    # 6. `auth.require_roles()` enforces RBAC implicitly
+    return {"secret_data": "Top secret admin info"}
+
+# --- Securing Multiple Routes ---
+
+# 7. Use `SecureAPIRouter` to protect an entire group of routes.
+# Any route added to this router will require an active user automatically.
+secure_router = SecureAPIRouter(auth_provider=auth, prefix="/internal", tags=["Protected"])
+
+@secure_router.get("/dashboard")
+async def get_dashboard():
+    # This endpoint is secured by FAuth without needing Depends in the signature!
+    return {"data": "Secure dashboard"}
+
+app.include_router(secure_router)
+```
+
+## Custom Token Payload
+
+By default, FAuth decodes JWTs into its built-in `TokenPayload` schema. If you need custom claims in your tokens (e.g., `tenant_id`, `organization_id`), subclass `TokenPayload` and pass it to `AuthProvider`:
+
+```python
+from fauth import AuthConfig, AuthProvider, TokenPayload
+
+class MyTokenPayload(TokenPayload):
+    tenant_id: str
+    plan: str = "free"
+
+auth = AuthProvider(
+    config=AuthConfig(secret_key="my-secret"),
+    user_loader=load_user,
+    token_payload_schema=MyTokenPayload,  # JWTs will be decoded into MyTokenPayload
+)
+```
+
+When issuing tokens, use the `extra` parameter to encode the custom claims into the JWT:
+
+```python
+await auth.login(sub="user-123", extra={"tenant_id": "acme", "plan": "pro"})
+```
+
+On the decoding side, your `user_loader` will receive a `MyTokenPayload` instance with fully typed access to `payload.tenant_id` and `payload.plan`.
+
+## Testing your endpoints with FAuth Fakes
+
+FAuth ships with a `fauth.testing` module specifically to simplify testing. No complex JWT mocks or real database dependencies needed — just use `build_fake_auth_provider` to wire up an in-memory auth provider.
+
+```python
+import asyncio
+import pytest
+from fastapi.testclient import TestClient
+from pydantic import BaseModel
+
+from myapp.main import app, auth  # Import your FastAPI app and FAuth instance
+from fauth.testing import build_fake_auth_provider
+
+class User(BaseModel):
+    id: str
+    username: str
+    is_active: bool = True
+    roles: list[str] = []
+
+@pytest.fixture
+def test_client() -> TestClient:
+    # 1. Provide a mock test user
+    mock_user = User(id="user-123", username="test_user", roles=["admin"])
+
+    # 2. Wire the fake provider with an in-memory user store
+    fake = build_fake_auth_provider(users={"user-123": mock_user})
+
+    # 3. Override the internal cached dependency functions.
+    # These are the actual callables that FastAPI resolves inside Depends().
+    app.dependency_overrides[auth._require_user] = fake._require_user
+    app.dependency_overrides[auth._require_active_user] = fake._require_active_user
+
+    yield TestClient(app)
+
+    # Clean up overrides
+    app.dependency_overrides.clear()
+
+def test_secure_route(test_client):
+    response = test_client.get("/me")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello test_user"}
+```
+
+### Alternative: End-to-end testing with real JWT tokens
+
+If you prefer issuing real tokens in tests, `build_fake_auth_provider` uses safe test defaults (a fixed secret key, short expiry) so you can generate tokens without any extra setup.
+
+```python
+def test_secure_me_endpoint():
+    user = User(id="user-999", username="fake_alice", roles=[])
+
+    # FAuth supplies a pre-made test provider with safe defaults
+    test_auth = build_fake_auth_provider(users={"user-999": user})
+
+    # Generate a real JWT token via the test provider
+    token_response = asyncio.run(test_auth.login(sub="user-999"))
+
+    # Override the dependency so the app uses the test user store
+    app.dependency_overrides[auth._require_user] = test_auth._require_user
+
+    # Apply Bearer token
+    client = TestClient(app)
+    response = client.get(
+        "/me",
+        headers={"Authorization": f"Bearer {token_response.access_token}"}
+    )
+
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello fake_alice"}
+
+    app.dependency_overrides.clear()
+```