fauth 0.2.1__tar.gz → 0.2.2__tar.gz

fauth-0.2.2/.github/actions/setup-python-env/action.yml

@@ -0,0 +1,34 @@
+name: 'Setup Python Environment'
+description: 'Install Python, uv, and project dependencies'
+
+inputs:
+  python-version:
+    description: 'Python version to set up'
+    required: true
+  uv-version:
+    description: 'uv version to install'
+    required: false
+    default: '0.9.11'
+  install-dependencies:
+    description: 'Whether to run uv sync after setup'
+    required: false
+    default: 'true'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Python ${{ inputs.python-version }}
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        version: ${{ inputs.uv-version }}
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install dependencies
+      if: inputs.install-dependencies == 'true'
+      shell: bash
+      run: uv sync --all-groups --frozen

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

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: write
+  actions: write
+
+jobs:
+  lint:
+    name: Lint (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run lint and format checks
+        run: uv run poe format
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run unit tests
+        env:
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+        run: uv run poe test
+
+  update-hooks:
+    name: Update pre-commit hooks
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: "3.13"
+
+      - name: Autoupdate pre-commit hooks
+        run: uv run pre-commit autoupdate
+
+      - name: Commit updated hooks
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add .pre-commit-config.yaml
+          git diff --staged --quiet || git commit -m "chore(config): update pre-commit hooks"
+          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
+        with:
+          token: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: "3.13"
+
+      - name: Bump version and update changelog
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.21.1
+        with:
+          github_token: ${{ secrets.GH_TOKEN || secrets.GITHUB_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 || secrets.GITHUB_TOKEN }}
+          ref: main
+          fetch-depth: 0
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
+        with:
+          python-version: "3.13"
+          install-dependencies: "false"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{fauth-0.2.1 → fauth-0.2.2}/.github/workflows/pre-commit-autoupdate.yml

@@ -5,8 +5,8 @@ name: Pre-commit Update
 
 on:
   schedule:
-    - cron: '0 2 * * *'
-  workflow_dispatch: # Allows manual triggering of the workflow
+    - cron: '0 2 * * 1' # Mondays at 2 AM UTC
+  workflow_dispatch:
 
 permissions:
   contents: read
@@ -20,34 +20,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          token: ${{ secrets.GH_TOKEN }}
+          fetch-depth: 0
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v7
+      - name: Setup environment
+        uses: ./.github/actions/setup-python-env
         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 }}
+          token: ${{ secrets.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
+          labels: update-hooks

{fauth-0.2.1 → fauth-0.2.2}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: gitleaks
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.15.8'
+    rev: 'v0.15.9'
     hooks:
       - id: ruff-check
         name: ruff

{fauth-0.2.1 → fauth-0.2.2}/CHANGELOG.md

@@ -1,6 +1,56 @@
 # CHANGELOG
 
 
+## v0.2.2 (2026-04-04)
+
+### Bug Fixes
+
+- Add badge for dependabot
+  ([`22f4719`](https://github.com/justmatias/fauth/commit/22f47195a489fbd9a63f5772c1081b887a2b0ea1))
+
+### Chores
+
+- Add python version matrix to CI/CD workflow
+  ([`9576512`](https://github.com/justmatias/fauth/commit/9576512733ed709c9bce62a97101d397a010ace8))
+
+- Fix cicd for dependabot prs
+  ([`befb729`](https://github.com/justmatias/fauth/commit/befb729fca3e37ba23c5158b29659f712455f6ac))
+
+- Implement setup env action and remove legacy requirements.txt
+  ([`781a552`](https://github.com/justmatias/fauth/commit/781a552e29c3d658247762c5cf13bb66042976fb))
+
+- Remove extract curly brace
+  ([`2661dd3`](https://github.com/justmatias/fauth/commit/2661dd3f94da79909fa900d6d6dc341e199f5bb4))
+
+- Restore checkout step in jobs
+  ([`ad4e33d`](https://github.com/justmatias/fauth/commit/ad4e33d1b2575f368b7cb256c1bf9d34b52855dd))
+
+- Set python version to min supported
+  ([`8c981a4`](https://github.com/justmatias/fauth/commit/8c981a40939df8230ba1f776cf1dc6f57090ebad))
+
+- **config**: Update pre-commit hooks
+  ([`ab09f61`](https://github.com/justmatias/fauth/commit/ab09f6185058cece84ddf5ef371b268b7fb75429))
+
+- **config**: Update pre-commit hooks
+  ([`6ec7a6d`](https://github.com/justmatias/fauth/commit/6ec7a6de9c618d1d5bf8b0f157d52888346f49a1))
+
+- **config**: Update requirements.txt
+  ([`862978f`](https://github.com/justmatias/fauth/commit/862978f8073c065086b3080dafc45e3b604b98ce))
+
+- **deps**: Bump cryptography from 46.0.5 to 46.0.6
+  ([`a61129d`](https://github.com/justmatias/fauth/commit/a61129df6777736ecff5df4c1a878a70b378025d))
+
+Bumps [cryptography](https://github.com/pyca/cryptography) from 46.0.5 to 46.0.6. -
+  [Changelog](https://github.com/pyca/cryptography/blob/main/CHANGELOG.rst) -
+  [Commits](https://github.com/pyca/cryptography/compare/46.0.5...46.0.6)
+
+--- updated-dependencies: - dependency-name: cryptography dependency-version: 46.0.6
+
+dependency-type: indirect ...
+
+Signed-off-by: dependabot[bot] <support@github.com>
+
+
 ## v0.2.1 (2026-04-03)
 
 ### Bug Fixes

{fauth-0.2.1 → fauth-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fauth
-Version: 0.2.1
+Version: 0.2.2
 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
@@ -37,6 +37,7 @@ 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.
 
+[![Dependabot Updates](https://github.com/justmatias/fauth/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/justmatias/fauth/actions/workflows/dependabot/dependabot-updates)
 [![PyPI version](https://img.shields.io/pypi/v/fauth)](https://pypi.org/project/fauth/)
 [![Python versions](https://img.shields.io/pypi/pyversions/fauth)](https://pypi.org/project/fauth/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -78,26 +79,37 @@ from pydantic import BaseModel
 class User(BaseModel):
     id: str
     username: str
+    hashed_password: str
     is_active: bool = True
     roles: list[str] = []
     permissions: list[str] = []
 ```
 
-### 2. Implement the `UserLoader` protocol
+### 2. Implement the `UserLoader` and `IdentityLoader` protocols
 
-FAuth uses a callback-based approach to load users. You provide a function that receives a decoded JWT payload and returns your user object:
+FAuth uses a callback-based approach. You provide functions that retrieve users from your data source:
 
 ```python
-from fauth import TokenPayload
+from fauth import TokenPayload, hash_password
 
 # Your database, ORM, or any data source
 DB: dict[str, User] = {
-    "user-123": User(id="user-123", username="alice", roles=["admin"], permissions=["read", "write"]),
+    "user-123": User(
+        id="user-123",
+        username="alice",
+        hashed_password=hash_password("s3cret"),
+        roles=["admin"],
+        permissions=["read", "write"],
+    ),
 }
 
+# UserLoader — resolves a user from a decoded JWT
 async def load_user(payload: TokenPayload) -> User | None:
-    """Look up a user by the `sub` claim from the JWT."""
     return DB.get(payload.sub)
+
+# IdentityLoader — resolves a user by identifier (for password authentication)
+async def load_identity(identifier: str) -> User | None:
+    return next((u for u in DB.values() if u.username == identifier), None)
 ```
 
 ### 3. Create the AuthProvider
@@ -106,7 +118,11 @@ async def load_user(payload: TokenPayload) -> User | None:
 from fauth import AuthConfig, AuthProvider
 
 config = AuthConfig(secret_key="my-super-secret-key")
-auth: AuthProvider[User] = AuthProvider(config=config, user_loader=load_user)
+auth: AuthProvider[User] = AuthProvider(
+    config=config,
+    user_loader=load_user,
+    identity_loader=load_identity,
+)
 ```
 
 ### 4. Wire it into FastAPI
@@ -117,15 +133,16 @@ from fastapi import FastAPI, Depends
 app = FastAPI()
 
 @app.post("/login")
-async def login():
-    return await auth.login(sub="user-123")
+async def login(username: str, password: str):
+    user = await auth.authenticate(username, password)
+    return await auth.login(sub=user.id)
 
 @app.get("/me")
 async def get_me(user: User = Depends(auth.require_user)):
     return {"message": f"Hello {user.username}"}
 ```
 
-That's it. The `/me` endpoint is now protected. Requests without a valid `Bearer` token will receive a `401 Unauthorized` response.
+That's it. The `/login` endpoint verifies credentials via `authenticate()`, then issues tokens via `login()`. The `/me` endpoint is protected — requests without a valid `Bearer` token will receive a `401 Unauthorized` response.
 
 ---
 
@@ -135,7 +152,7 @@ That's it. The `/me` endpoint is now protected. Requests without a valid `Bearer
 from fastapi import FastAPI, Depends, HTTPException
 from fastapi.security import OAuth2PasswordRequestForm
 from pydantic import BaseModel
-from fauth import AuthConfig, AuthProvider, TokenPayload, SecureAPIRouter
+from fauth import AuthConfig, AuthProvider, TokenPayload, SecureAPIRouter, hash_password
 
 app = FastAPI()
 
@@ -143,41 +160,50 @@ app = FastAPI()
 class User(BaseModel):
     id: str
     username: str
+    hashed_password: str
     is_active: bool = True
     roles: list[str] = []
     permissions: list[str] = []
 
-# Mock database
+# Mock databases
 DB: dict[str, User] = {
-    "user-123": User(id="user-123", username="alice", roles=["admin"], permissions=["read", "write"])
+    "user-123": User(
+        id="user-123",
+        username="alice",
+        hashed_password=hash_password("s3cret"),
+        roles=["admin"],
+        permissions=["read", "write"],
+    )
+}
+
+# Identity lookup by username (used by authenticate)
+IDENTITY_DB: dict[str, User] = {
+    "alice": DB["user-123"],
 }
 
 # 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. Define how to fetch a user by username/email for login
-async def load_user_by_identity(identifier: str) -> User | None:
-    # In a real app, this would query your database
-    for user in DB.values():
-        if user.username == identifier:
-            return user
-    return None
+# 3. Define the callback that retrieves a user by identifier (for password auth)
+async def load_identity(identifier: str) -> User | None:
+    return IDENTITY_DB.get(identifier)
 
 # 4. Instantiate the auth component
 config = AuthConfig(secret_key="my-super-secret-key", algorithm="HS256")
 auth: AuthProvider[User] = AuthProvider(
     config=config,
     user_loader=load_user,
-    identity_loader=load_user_by_identity
+    identity_loader=load_identity,
 )
 
 # --- Routes ---
 
 @app.post("/login")
-async def login():
-    # 4. Use `auth.login` to issue tokens (password verification omitted for now)
-    return await auth.login(sub="user-123")
+async def login(username: str, password: str):
+    # 5. Verify credentials, then issue tokens
+    user = await auth.authenticate(username, password)
+    return await auth.login(sub=user.id)
 
 @app.get("/me")
 async def get_me(user: User = Depends(auth.require_user)):
@@ -256,21 +282,24 @@ The main orchestrator. Provides FastAPI dependencies for authentication and auth
 AuthProvider(
     config: AuthConfig,
     user_loader: UserLoader[T],
-    transport: Transport | None = None,              # Defaults to BearerTransport()
+    identity_loader: IdentityLoader[T] | None = None, # Required for authenticate()
+    transport: Transport | None = None,               # Defaults to BearerTransport()
     token_payload_schema: type[TokenPayload] = TokenPayload,
+    password_field_name: str = "hashed_password",      # Attribute on user model holding the hash
 )
 ```
 
 #### Methods
 
-| Method                        | Returns         | Description                                                              |
-| ----------------------------- | --------------- | ------------------------------------------------------------------------ |
-| `require_user`                | `T`             | FastAPI dependency — extracts and validates the token, loads the user    |
-| `require_active_user`         | `T`             | Like `require_user`, but also checks `user.is_active`                    |
-| `require_roles(roles)`        | `Callable`      | Returns a dependency that demands the user has all specified roles       |
-| `require_permissions(perms)`  | `Callable`      | Returns a dependency that demands the user has all specified permissions |
-| `login(sub, scopes?, extra?)` | `TokenResponse` | Issues access + refresh tokens for a given subject                       |
-| `get_security_scheme()`       | `SecurityBase`  | Returns the OpenAPI security scheme for docs                             |
+| Method                              | Returns         | Description                                                              |
+| ----------------------------------- | --------------- | ------------------------------------------------------------------------ |
+| `require_user`                      | `T`             | FastAPI dependency — extracts and validates the token, loads the user    |
+| `require_active_user`               | `T`             | Like `require_user`, but also checks `user.is_active`                    |
+| `require_roles(roles)`              | `Callable`      | Returns a dependency that demands the user has all specified roles       |
+| `require_permissions(perms)`        | `Callable`      | Returns a dependency that demands the user has all specified permissions |
+| `authenticate(identifier, password)`| `T`             | Verifies credentials via `IdentityLoader` + password check              |
+| `login(sub, scopes?, extra?)`       | `TokenResponse` | Issues access + refresh tokens for a given subject                       |
+| `get_security_scheme()`             | `SecurityBase`  | Returns the OpenAPI security scheme for docs                             |
 
 ### `UserLoader` Protocol
 
@@ -292,6 +321,24 @@ class MyUserLoader:
         return await self.db.get_user(token_payload.sub)
 ```
 
+### `IdentityLoader` Protocol
+
+Used by `authenticate()` to look up a user by an identifier (username, email, etc.):
+
+```python
+# As a plain function
+async def load_identity(identifier: str) -> User | None:
+    return await db.get_user_by_username(identifier)
+
+# Or as a callable class
+class MyIdentityLoader:
+    def __init__(self, db: Database):
+        self.db = db
+
+    async def __call__(self, identifier: str) -> User | None:
+        return await self.db.get_user_by_username(identifier)
+```
+
 ### `TokenPayload`
 
 The decoded JWT structure. Accepts extra claims via `model_config = ConfigDict(extra="allow")`.
@@ -362,6 +409,78 @@ is_valid = verify_password("my-password", hashed)  # True
 
 ---
 
+## Authentication with Password Verification
+
+FAuth provides a built-in `authenticate()` method on `AuthProvider` that handles credential verification using the `IdentityLoader` protocol and Argon2 password hashing.
+
+### Basic setup
+
+```python
+from pydantic import BaseModel
+from fauth import AuthConfig, AuthProvider, hash_password
+
+class User(BaseModel):
+    id: str
+    username: str
+    hashed_password: str
+    is_active: bool = True
+
+# Identity loader retrieves user by username/email/etc.
+async def load_identity(identifier: str) -> User | None:
+    return await db.get_user_by_username(identifier)
+
+# Token-based user loader (used by require_user)
+async def load_user(payload) -> User | None:
+    return await db.get_user_by_id(payload.sub)
+
+auth = AuthProvider(
+    config=AuthConfig(secret_key="my-secret"),
+    user_loader=load_user,
+    identity_loader=load_identity,
+)
+```
+
+### Using `authenticate()` in a login endpoint
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.post("/login")
+async def login(username: str, password: str):
+    # Verifies password and checks is_active
+    user = await auth.authenticate(username, password)
+    # Issue tokens
+    return await auth.login(sub=user.id)
+```
+
+`authenticate()` performs three checks in order:
+1. **User exists** — looks up the user via `IdentityLoader`. Raises `401` if not found.
+2. **Password is valid** — verifies the plain password against the hashed password stored on the user. Raises `401` if invalid.
+3. **User is active** — checks `user.is_active` (if the attribute exists). Raises `401` if inactive.
+
+### Custom password field
+
+By default, `authenticate()` reads the hash from `user.hashed_password`. If your model stores it under a different attribute name, pass `password_field_name`:
+
+```python
+class User(BaseModel):
+    id: str
+    pw_hash: str  # non-standard field name
+
+auth = AuthProvider(
+    config=config,
+    user_loader=load_user,
+    identity_loader=load_identity,
+    password_field_name="pw_hash",
+)
+```
+
+> **Note:** If `AuthProvider` is created without an `identity_loader`, calling `authenticate()` will raise a `RuntimeError`.
+
+---
+
 ## Custom Token Payload
 
 If you need custom claims in your tokens (e.g., `tenant_id`, `organization_id`), subclass `TokenPayload` and pass it to `AuthProvider`:
@@ -548,11 +667,12 @@ async def test_secure_me_endpoint():
 
 ### Testing utilities reference
 
-| Import                                                | Description                                                  |
-| ----------------------------------------------------- | ------------------------------------------------------------ |
-| `build_fake_auth_provider(users?, config_overrides?)` | Creates an `AuthProvider` backed by in-memory fakes          |
-| `fake_auth_config(**overrides)`                       | Returns an `AuthConfig` with safe test defaults              |
-| `FakeUserLoader[T]`                                   | In-memory `UserLoader` — populate with `.add_user(id, user)` |
+| Import                                                | Description                                                           |
+| ----------------------------------------------------- | --------------------------------------------------------------------- |
+| `build_fake_auth_provider(users?, config_overrides?)` | Creates an `AuthProvider` backed by in-memory fakes                   |
+| `fake_auth_config(**overrides)`                       | Returns an `AuthConfig` with safe test defaults                       |
+| `FakeUserLoader[T]`                                   | In-memory `UserLoader` — populate with `.add_user(id, user)`          |
+| `FakeIdentityLoader[T]`                               | In-memory `IdentityLoader` — populate with `.add_user(id, user)`      |
 
 ---
 
@@ -625,7 +745,9 @@ FAuth raises `HTTPException` with standard HTTP status codes:
 | Expired token           | `401`       | `"Token expired"`                                              |
 | Invalid/malformed token | `401`       | `"Invalid token"`                                              |
 | User not found          | `401`       | `"User does not exist"`                                        |
-| Inactive user           | `400`       | `"Inactive user"`                                              |
+| Invalid credentials     | `401`       | `"Invalid credentials"` (from `authenticate()`)               |
+| Inactive user (token)   | `400`       | `"Inactive user"` (from `require_active_user`)                |
+| Inactive user (login)   | `401`       | `"Inactive user"` (from `authenticate()`)                     |
 | Missing role            | `403`       | `"Missing role: {role}"`                                       |
 | Missing permission      | `403`       | `"Insufficient permissions: requires {permission} permission"` |