Merge pull request #5 from Athroniaeth/development

- docs(scopes): add basic scopes example, fastapi scopes example, rewor… 
- docs(mkdocs): rework all mkdocs pages, remove bad information
- build(deps): update all dependencies and format/lint code
- docs(readme): add pypi and mkdocs url to readme

Author: Athroniaeth

README.md

@@ -1,7 +1,9 @@
-# Fastapi Api Key
+# FastAPI Api Key
 
 ![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FAthroniaeth%2Ffastapi-api-key%2Fmain%2Fpyproject.toml)
 [![Tested with pytest](https://img.shields.io/badge/tests-pytest-informational.svg)](https://pytest.org/)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-api-key.svg)](https://pypi.org/project/fastapi-api-key/)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://athroniaeth.github.io/fastapi-api-key/)
 [![codecov](https://codecov.io/gh/Athroniaeth/fastapi-api-key/graph/badge.svg)](https://codecov.io/gh/Athroniaeth/fastapi-api-key)
 [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://bandit.readthedocs.io/)
 [![Deps: uv](https://img.shields.io/badge/deps-managed%20with%20uv-3E4DD8.svg)](https://docs.astral.sh/uv/)
@@ -11,15 +13,25 @@
 ships with a domain model, hashing helpers, repository contracts, and an optional FastAPI router for CRUD management of
 keys.
 
+## Links
+
+- **Documentation:** [https://athroniaeth.github.io/fastapi-api-key/](https://athroniaeth.github.io/fastapi-api-key/)
+- **PyPI package:** [https://pypi.org/project/fastapi-api-key/](https://pypi.org/project/fastapi-api-key/)
+
 ## Features
 
 - **Security-first**: secrets are hashed with a salt and a pepper, and never logged or returned after creation
-- **Ready-to-use**: just create your repository (storage) and use service
 - **Prod-ready**: services and repositories are async, and battle-tested
 
+
 - **Agnostic hasher**: you can use any async-compatible hashing strategy (default: Argon2)
 - **Agnostic backend**: you can use any async-compatible database (default: SQLAlchemy)
-- **Factory**: create a Typer, FastAPI router wired to api key systems (only SQLAlchemy for now)
+- **Connector**: create a Typer, FastAPI router wired to api key systems
+
+
+- **Envvar support**: easily configure peppers and other secrets via environment variables
+- **Extensible**: customize models, repositories, hashers, and services to fit your needs
+- **Scopes support**: assign scopes to API keys for fine-grained access control
 
 ## Standards compliance
 
@@ -32,14 +44,15 @@ This library try to follow best practices and relevant RFCs for API key manageme
 
 ## Installation
 
+### Basic installation
 This project is not published to PyPI. Use a tool like [uv](https://docs.astral.sh/uv/) to manage dependencies.
 
 ```bash
 uv add fastapi-api-key
 uv pip install fastapi-api-key
 ```
 
-## Development installation
+### Development installation
 
 Clone or fork the repository and install the project with the extras that fit your stack. Examples below use `uv`:
 
@@ -48,6 +61,8 @@ uv sync --extra all  # fastapi + sqlalchemy + argon2 + bcrypt
 uv pip install -e ".[all]"
 ```
 
+### Optional dependencies
+
 For lighter setups you can choose individual extras:
 
 | Installation mode              | Command                       | Description                                                                 |
@@ -125,6 +140,12 @@ service = ApiKeyService(
 
 This is a classic API key if you don't modify the service behavior:
 
+**Structure:**
+
+`{global_prefix}`-`{delimiter}`-`{identifier}`-`{delimiter}`-`{secret}`
+
+**Example:**
+
 `ak-7a74caa323a5410d-mAfP3l6yAxqFz0FV2LOhu2tPCqL66lQnj3Ubd08w9RyE4rV4skUcpiUVIfsKEbzw`
 
 - "-" separators so that systems can easily split

docs/index.md

@@ -1,62 +1,81 @@
-# Fastapi Api Key
+# FastAPI Api Key
+
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FAthroniaeth%2Ffastapi-api-key%2Fmain%2Fpyproject.toml)
+[![Tested with pytest](https://img.shields.io/badge/tests-pytest-informational.svg)](https://pytest.org/)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-api-key.svg)](https://pypi.org/project/fastapi-api-key/)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://athroniaeth.github.io/fastapi-api-key/)
+[![codecov](https://codecov.io/gh/Athroniaeth/fastapi-api-key/graph/badge.svg)](https://codecov.io/gh/Athroniaeth/fastapi-api-key)
+[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://bandit.readthedocs.io/)
+[![Deps: uv](https://img.shields.io/badge/deps-managed%20with%20uv-3E4DD8.svg)](https://docs.astral.sh/uv/)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-4B32C3.svg)](https://docs.astral.sh/ruff/)
 
 `fastapi-api-key` provides reusable building blocks to issue, persist, and verify API keys in FastAPI applications. It
 ships with a domain model, hashing helpers, repository contracts, and an optional FastAPI router for CRUD management of
 keys.
 
+## Links
+
+- **Documentation:** [https://athroniaeth.github.io/fastapi-api-key/](https://athroniaeth.github.io/fastapi-api-key/)
+- **PyPI package:** [https://pypi.org/project/fastapi-api-key/](https://pypi.org/project/fastapi-api-key/)
+
 ## Features
 
 - **Security-first**: secrets are hashed with a salt and a pepper, and never logged or returned after creation
-- **Ready-to-use**: just create your repository (storage) and use service
 - **Prod-ready**: services and repositories are async, and battle-tested
 
 - **Agnostic hasher**: you can use any async-compatible hashing strategy (default: Argon2)
 - **Agnostic backend**: you can use any async-compatible database (default: SQLAlchemy)
-- **Factory**: create a Typer, FastAPI router wired to api key systems (only SQLAlchemy for now)
+- **Connector**: create a Typer, FastAPI router wired to api key systems
+
+
+- **Envvar support**: easily configure peppers and other secrets via environment variables
+- **Extensible**: customize models, repositories, hashers, and services to fit your needs
+- **Scopes support**: assign scopes to API keys for fine-grained access control
+
+## Standards compliance
+
+This library try to follow best practices and relevant RFCs for API key management and authentication:
+
+- **[RFC 9110/7235](https://www.rfc-editor.org/rfc/rfc9110.html)**: Router raise 401 for missing/invalid keys, 403 for
+  valid but inactive/expired keys
+- **[RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)**: Supports `Authorization: Bearer <api_key>` header for
+  key transmission (also supports deprecated `X-API-Key` header and `api_key` query param)
+
+## How API Keys Work
+
+### API Key Format
+
+This is a classic API key if you don't modify the service behavior:
 
-## Installation
+**Structure:**
 
-This projet does not publish to PyPI. Use a tool like [uv](https://docs.astral.sh/uv/) to manage dependencies.
+`{global_prefix}`-`{delimiter}`-`{identifier}`-`{delimiter}`-`{secret}`
 
-```bash
-uv add fastapi-api-key
-uv pip install fastapi-api-key
-```
+**Example:**
 
-## Development installation
+`ak-7a74caa323a5410d-mAfP3l6yAxqFz0FV2LOhu2tPCqL66lQnj3Ubd08w9RyE4rV4skUcpiUVIfsKEbzw`
 
-Clone the repository and install the project with the extras that fit your stack. Examples below use `uv`:
+- "-" separators so that systems can easily split
+- Prefix `ak` (for "Api Key"), to identify the key type (useful to indicate that it is an API key).
+- 16 first characters are the identifier (UUIDv4 without dashes)
+- 48 last characters are the secret (random URL-safe base64 string)
 
-```bash
-uv sync --extra all  # fastapi + sqlalchemy + argon2 + bcrypt
-uv pip install -e ".[all]"
-```
+When verifying an API key, the service extracts the identifier, retrieves the corresponding record from the repository,
+and compares the hashed secret. If found, it hashes the provided secret (with the same salt and pepper) and compares it
+to the stored hash.
+If they match, the key is valid.
 
-For lighter setups you can choose individual extras:
+### Schema validation
 
-| Installation mode           | Command                       | Description                                                                      |
-|-----------------------------|-------------------------------|----------------------------------------------------------------------------------|
-| **Base installation**       | `fastapi-api-key`             | Installs the core package without any optional dependencies.                     |
-| **With bcrypt support**     | `fastapi-api-key[bcrypt]`     | Adds support for password hashing using **bcrypt** (`bcrypt>=5.0.0`).            |
-| **With Argon2 support**     | `fastapi-api-key[argon2]`     | Adds support for password hashing using **Argon2** (`argon2-cffi>=25.1.0`).      |
-| **With SQLAlchemy support** | `fastapi-api-key[sqlalchemy]` | Adds database integration via **SQLAlchemy** (`sqlalchemy>=2.0.43`).             |
-| **Core setup**              | `fastapi-api-key[core]`       | Installs the **core dependencies** (SQLAlchemy + Argon2 + bcrypt).               |
-| **FastAPI only**            | `fastapi-api-key[fastapi]`    | Installs **FastAPI** as an optional dependency (`fastapi>=0.118.0`).             |
-| **Full installation**       | `fastapi-api-key[all]`        | Installs **all optional dependencies**: FastAPI, SQLAlchemy, Argon2, and bcrypt. |
+Here is a diagram showing what happens after you initialize your API key service with a global prefix and delimiter when you provide an API key to the `.verify_key()` method.
 
-```bash
-uv add fastapi-api-key[sqlalchemy]
-uv pip install fastapi-api-key[sqlalchemy]
-uv sync --extra sqlalchemy
-uv pip install -e ".[sqlalchemy]"
-```
+<img src="./schema.svg">
 
-Development dependencies (pytest, ruff, etc.) are available under the `dev` group:
+## Additional notes
 
-```bash
-uv sync --extra dev
-uv pip install -e ".[dev]"
-```
+- Python 3.9+ is required.
+- The library issues warnings if you keep the default pepper; always configure a secret value outside source control.
+- Never log peppers or plaintext API keys, change the pepper of prod will prevent you from reading API keys
 
 ## What to read next
 

docs/quickstart.md

@@ -4,10 +4,50 @@ This quickstart guide helps you set up the package and create your first API key
 
 ## 1. Install dependencies
 
-Install the package with all optional dependencies using your preferred method. Examples below use [uv](https://docs.astral.sh/uv/):
+### Basic installation
+This project is not published to PyPI. Use a tool like [uv](https://docs.astral.sh/uv/) to manage dependencies.
 
 ```bash
-uv sync --extra all 
+uv add fastapi-api-key
+uv pip install fastapi-api-key
+```
+
+### Development installation
+
+Clone or fork the repository and install the project with the extras that fit your stack. Examples below use `uv`:
+
+```bash
+uv sync --extra all  # fastapi + sqlalchemy + argon2 + bcrypt
+uv pip install -e ".[all]"
+```
+
+### Optional dependencies
+
+For lighter setups you can choose individual extras:
+
+| Installation mode              | Command                       | Description                                                                 |
+|--------------------------------|-------------------------------|-----------------------------------------------------------------------------|
+| **Base installation**          | `fastapi-api-key`             | Installs the core package without any optional dependencies.                |
+| **With Bcrypt support**        | `fastapi-api-key[bcrypt]`     | Adds support for password hashing using **bcrypt**                          |
+| **With Argon2 support**        | `fastapi-api-key[argon2]`     | Adds support for password hashing using **Argon2**                          |
+| **With SQLAlchemy support**    | `fastapi-api-key[sqlalchemy]` | Adds database integration via **SQLAlchemy**                                |
+| **With Cache Service support** | `fastapi-api-key[aiocache]`   | Adds database integration via **Aiocache**                                  |
+| **Core setup**                 | `fastapi-api-key[core]`       | Installs the **core dependencies** (SQLAlchemy + Argon2 + bcrypt + aiocache |
+| **FastAPI only**               | `fastapi-api-key[fastapi]`    | Installs **FastAPI** as an optional dependency                              |
+| **Full installation**          | `fastapi-api-key[all]`        | Installs **all optional dependencies**                                      |
+
+```bash
+uv add fastapi-api-key[sqlalchemy]
+uv pip install fastapi-api-key[sqlalchemy]
+uv sync --extra sqlalchemy
+uv pip install -e ".[sqlalchemy]"
+```
+
+Development dependencies (pytest, ruff, etc.) are available under the `dev` group:
+
+```bash
+uv sync --extra dev
+uv pip install -e ".[dev]"
 ```
 
 ## 2. Create api key

docs/usage/scopes.md

@@ -0,0 +1,27 @@
+# Scopes
+
+This libray integrates the concept of scopes to provide fine-grained access control for API keys. Scopes are strings that define the permissions associated with an API key. When creating or updating an API key, you can specify the scopes that the key should have.
+If you define 2 scopes "read" and "write" to an route, an API key must have both scopes to access that route.
+
+## Example
+
+### Simple
+
+This is the canonical example from `examples/example_scopes.py`:
+
+!!! tip "Always set a pepper"
+    The default pepper is a placeholder. Set `API_KEY_PEPPER` (or pass it explicitly to the hashers) in every environment.
+
+```python
+--8<-- "examples/example_scopes.py"
+
+```
+
+### FastAPI
+
+You can create security Depends with required scopes like this:
+
+```python
+--8<-- "examples/example_fastapi_scopes.py"
+
+```

examples/example_fastapi_scopes.py

@@ -0,0 +1,111 @@
+import os
+from pathlib import Path
+from typing import AsyncIterator
+
+from fastapi import FastAPI, Depends, APIRouter
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+
+from fastapi_api_key import ApiKey, ApiKeyService
+from fastapi_api_key.hasher.argon2 import Argon2ApiKeyHasher
+from fastapi_api_key.repositories.sql import SqlAlchemyApiKeyRepository
+from fastapi_api_key.api import create_api_keys_router, create_depends_api_key
+
+# Set env var to override default pepper
+# Using a strong, unique pepper is crucial for security
+# Default pepper is insecure and should not be used in production
+pepper = os.getenv("API_KEY_PEPPER")
+hasher = Argon2ApiKeyHasher(pepper=pepper)
+
+path = Path(__file__).parent / "db.sqlite3"
+database_url = os.environ.get("DATABASE_URL", f"sqlite+aiosqlite:///{path}")
+
+async_engine = create_async_engine(database_url, future=True)
+async_session_maker = async_sessionmaker(
+    async_engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+app = FastAPI(title="API with API Key Management")
+
+
+async def inject_async_session() -> AsyncIterator[AsyncSession]:
+    """Dependency to provide an active SQLAlchemy async session."""
+    async with async_session_maker() as session:
+        async with session.begin():
+            yield session
+
+
+async def inject_svc_api_keys(async_session: AsyncSession = Depends(inject_async_session)) -> ApiKeyService:
+    """Dependency to inject the API key service with an active SQLAlchemy async session."""
+    repo = SqlAlchemyApiKeyRepository(async_session)
+
+    # Necessary if you don't use your own DeclarativeBase
+    await repo.ensure_table()
+
+    return ApiKeyService(repo=repo, hasher=hasher)
+
+
+# Create security dependency that requires "write" scope
+security = create_depends_api_key(inject_svc_api_keys, required_scopes=["write"])
+router_protected = APIRouter(prefix="/protected", tags=["Protected"])
+
+router = APIRouter(prefix="/api-keys", tags=["API Keys"])
+router_api_keys = create_api_keys_router(
+    inject_svc_api_keys,
+    router=router,
+)
+
+
+@router_protected.get("/")
+async def read_protected_data(api_key: ApiKey = Depends(security)):
+    return {
+        "message": "This is protected data",
+        "apiKey": {
+            "id": api_key.id_,
+            "name": api_key.name,
+            "description": api_key.description,
+            "isActive": api_key.is_active,
+            "createdAt": api_key.created_at,
+            "expiresAt": api_key.expires_at,
+            "lastUsedAt": api_key.last_used_at,
+        },
+    }
+
+
+app.include_router(router_api_keys)
+app.include_router(router_protected)
+
+
+async def main():
+    async with async_session_maker() as async_session:
+        repo = SqlAlchemyApiKeyRepository(async_session)
+
+        # Necessary if you don't use your own DeclarativeBase
+        await repo.ensure_table()
+
+        svc = ApiKeyService(repo=repo, hasher=hasher)
+
+        # Create an API key without scopes
+        bad_entity = ApiKey(name="no-scope-key", scopes=["read"])
+        good_entity = ApiKey(name="with-scope-key", scopes=["write"])
+
+        _, bad_api_key = await svc.create(bad_entity)
+        _, good_api_key = await svc.create(good_entity)
+
+        print(f"Bad API Key (no required scopes): '{bad_api_key}'")
+        print(f"Good API Key (with required scopes): '{good_api_key}'")
+
+        await async_session.commit()
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    # Create an invalid and a valid API key for testing
+    asyncio.run(main())
+
+    import uvicorn
+
+    # Run the FastAPI app and test the 2 api keys against the protected endpoint
+    uvicorn.run(app, host="localhost", port=8000)