refactor(library): rename library fastapi-api-key to keyshield

Author: Athroniaeth

AGENTS.md

@@ -6,7 +6,7 @@ Follow existing patterns and run the same tooling as humans.
 ## Project overview
 
 - Language: Python 3.9+
-- Package: `fastapi_api_key` (src layout)
+- Package: `keyshield` (src layout)
 - Async-first services and repositories
 - Optional extras for FastAPI, SQLAlchemy, Argon2, bcrypt, aiocache
 
@@ -90,7 +90,7 @@ Artifacts: `coverage.xml`, `htmlcov/`, `junit.xml`.
 
 ### Error handling
 
-- Domain exceptions live in `fastapi_api_key.domain.errors`.
+- Domain exceptions live in `keyshield.domain.errors`.
 - Raise domain errors in services and repositories, translate to HTTP exceptions in API layer.
 - Preserve original errors with `raise ... from exc`.
 - Use specific exceptions (`KeyNotFound`, `InvalidKey`, `ConfigurationError`) rather than `ValueError` unless appropriate.
@@ -123,7 +123,7 @@ Artifacts: `coverage.xml`, `htmlcov/`, `junit.xml`.
 
 ## Repository layout
 
-- `src/fastapi_api_key/` core library
+- `src/keyshield/` core library
 - `tests/` unit/integration tests
 - `examples/` example applications (used in docs)
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thanks for helping improve `fastapi-api-key`! This guide walks you through the toolchain, branching model, and tooling conventions we follow.
+Thanks for helping improve `keyshield`! This guide walks you through the toolchain, branching model, and tooling conventions we follow.
 
 ## Prerequisites
 
@@ -13,12 +13,12 @@ Thanks for helping improve `fastapi-api-key`! This guide walks you through the t
 1. **Fork** the repository to your own GitHub account.
 2. **Clone** your fork locally:
    ```bash
-   git clone https://github.com/<you>/fastapi-api-key.git
-   cd fastapi-api-key
+   git clone https://github.com/<you>/keyshield.git
+   cd keyshield
    ```
 3. **Add the upstream remote** so you can sync later:
    ```bash
-   git remote add upstream https://github.com/Athroniaeth/fastapi-api-key.git
+   git remote add upstream https://github.com/Athroniaeth/keyshield.git
    ```
 4. **Create a feature branch** from the active integration branch (default: `development`):
    ```bash
@@ -71,7 +71,7 @@ source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows
    git push origin feat/<short-topic>
    ```
 
-6. **Open a pull request** targeting `Athroniaeth/fastapi-api-key:development`. Summarise the change, mention tests/docs runs, and link related issues if applicable.
+6. **Open a pull request** targeting `Athroniaeth/keyshield:development`. Summarise the change, mention tests/docs runs, and link related issues if applicable.
 
 ## Pull request checklist
 

README.md

@@ -1,20 +1,20 @@
 # 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)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FAthroniaeth%2Fkeyshield%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)
+[![PyPI version](https://img.shields.io/pypi/v/keyshield.svg)](https://pypi.org/project/keyshield/)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://athroniaeth.github.io/keyshield/)
+[![codecov](https://codecov.io/gh/Athroniaeth/keyshield/graph/badge.svg)](https://codecov.io/gh/Athroniaeth/keyshield)
 [![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 a backend-agnostic library that provides a production-ready, secure API key system, with optional FastAPI and Typer connectors.
+`keyshield` provides a backend-agnostic library that provides a production-ready, secure API key system, with optional FastAPI and Typer connectors.
 
 ## 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/)
+- **Documentation:** [https://athroniaeth.github.io/keyshield/](https://athroniaeth.github.io/keyshield/)
+- **PyPI package:** [https://pypi.org/project/keyshield/](https://pypi.org/project/keyshield/)
 
 ## Features
 
@@ -41,8 +41,8 @@ This library try to follow best practices and relevant RFCs for API key manageme
 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
+uv add keyshield
+uv pip install keyshield
 ```
 
 ### Development installation
@@ -60,18 +60,18 @@ 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**                                      |
+| **Base installation**          | `keyshield`             | Installs the core package without any optional dependencies.                |
+| **With Bcrypt support**        | `keyshield[bcrypt]`     | Adds support for password hashing using **bcrypt**                          |
+| **With Argon2 support**        | `keyshield[argon2]`     | Adds support for password hashing using **Argon2**                          |
+| **With SQLAlchemy support**    | `keyshield[sqlalchemy]` | Adds database integration via **SQLAlchemy**                                |
+| **With Cache Service support** | `keyshield[aiocache]`   | Adds database integration via **Aiocache**                                  |
+| **Core setup**                 | `keyshield[core]`       | Installs the **core dependencies** (SQLAlchemy + Argon2 + bcrypt + aiocache |
+| **FastAPI only**               | `keyshield[fastapi]`    | Installs **FastAPI** as an optional dependency                              |
+| **Full installation**          | `keyshield[all]`        | Installs **all optional dependencies**                                      |
 
 ```bash
-uv add fastapi-api-key[sqlalchemy]
-uv pip install fastapi-api-key[sqlalchemy]
+uv add keyshield[sqlalchemy]
+uv pip install keyshield[sqlalchemy]
 uv sync --extra sqlalchemy
 uv pip install -e ".[sqlalchemy]"
 ```
@@ -100,8 +100,8 @@ Install `make` via `sudo apt install make` on Debian/Ubuntu or `choco install ma
 ```python
 import asyncio
 
-from fastapi_api_key import ApiKeyService
-from fastapi_api_key.repositories.in_memory import InMemoryApiKeyRepository
+from keyshield import ApiKeyService
+from keyshield.repositories.in_memory import InMemoryApiKeyRepository
 
 
 async def main():
@@ -122,9 +122,9 @@ Override the default pepper in production:
 
 ```python
 import os
-from fastapi_api_key import ApiKeyService
-from fastapi_api_key.hasher.argon2 import Argon2ApiKeyHasher
-from fastapi_api_key.repositories.in_memory import InMemoryApiKeyRepository
+from keyshield import ApiKeyService
+from keyshield.hasher.argon2 import Argon2ApiKeyHasher
+from keyshield.repositories.in_memory import InMemoryApiKeyRepository
 
 pepper = os.environ["SECRET_PEPPER"]
 hasher = Argon2ApiKeyHasher(pepper=pepper)
@@ -178,10 +178,10 @@ 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
+from keyshield import ApiKey, ApiKeyService
+from keyshield.hasher.argon2 import Argon2ApiKeyHasher
+from keyshield.repositories.sql import SqlAlchemyApiKeyRepository
+from keyshield.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

docs/index.md

@@ -1,20 +1,20 @@
 # 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)
+![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FAthroniaeth%2Fkeyshield%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)
+[![PyPI version](https://img.shields.io/pypi/v/keyshield.svg)](https://pypi.org/project/keyshield/)
+[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://athroniaeth.github.io/keyshield/)
+[![codecov](https://codecov.io/gh/Athroniaeth/keyshield/graph/badge.svg)](https://codecov.io/gh/Athroniaeth/keyshield)
 [![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 a backend-agnostic library that provides a production-ready, secure API key system, with optional FastAPI and Typer connectors.
+`keyshield` provides a backend-agnostic library that provides a production-ready, secure API key system, with optional FastAPI and Typer connectors.
 
 ## 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/)
+- **Documentation:** [https://athroniaeth.github.io/keyshield/](https://athroniaeth.github.io/keyshield/)
+- **PyPI package:** [https://pypi.org/project/keyshield/](https://pypi.org/project/keyshield/)
 
 ## Features
 

docs/quickstart.md

@@ -8,12 +8,12 @@ This quickstart guide helps you set up the package and create your first API key
 This project is published on PyPI. Use a tool like [uv](https://docs.astral.sh/uv/) to manage dependencies.
 
 ```bash
-uv add fastapi-api-key
+uv add keyshield
 ```
 
 or using pip:
 ```bash
-pip install fastapi-api-key
+pip install keyshield
 ```
 
 ## 2. Create api key

docs/usage/database.md

@@ -7,7 +7,7 @@ This guide covers SQLAlchemy setup with aiosqlite for persistent API key storage
 Install the SQLAlchemy extra:
 
 ```bash
-pip install fastapi-api-key[sqlalchemy]
+pip install keyshield[sqlalchemy]
 ```
 
 ## Example

docs/usage/django.md

@@ -1,7 +1,7 @@
 # Django Integration
 
-`fastapi-api-key` supports [Django](https://www.djangoproject.com/) 4.1+ via the
-`fastapi_api_key.django` package.
+`keyshield` supports [Django](https://www.djangoproject.com/) 4.1+ via the
+`keyshield.django` package.
 
 The integration provides:
 
@@ -15,7 +15,7 @@ The integration provides:
 ## Installation
 
 ```bash
-uv add fastapi_api_key[django]
+uv add keyshield[django]
 ```
 
 ## Setup
@@ -26,24 +26,24 @@ Add the app to `INSTALLED_APPS` in your Django settings:
 # settings.py
 INSTALLED_APPS = [
     ...
-    "fastapi_api_key.django",
+    "keyshield.django",
 ]
 ```
 
 Then run migrations to create the `api_keys` table:
 
 ```bash
-python manage.py makemigrations fastapi_api_key_django
+python manage.py makemigrations keyshield_django
 python manage.py migrate
 ```
 
 ## Quick start
 
 ```python
 # myapp/api_keys.py
-from fastapi_api_key.django import DjangoApiKeyRepository
-from fastapi_api_key.services.base import ApiKeyService
-from fastapi_api_key.hasher.argon2 import Argon2ApiKeyHasher
+from keyshield.django import DjangoApiKeyRepository
+from keyshield.services.base import ApiKeyService
+from keyshield.hasher.argon2 import Argon2ApiKeyHasher
 
 async def get_service() -> ApiKeyService:
     return ApiKeyService(
@@ -57,7 +57,7 @@ Register the management endpoints in your URL configuration:
 ```python
 # myapp/urls.py
 from django.urls import path, include
-from fastapi_api_key.django.urls import create_api_keys_urlpatterns
+from keyshield.django.urls import create_api_keys_urlpatterns
 from myapp.api_keys import get_service
 
 urlpatterns = [
@@ -71,7 +71,7 @@ Use the `require_api_key` decorator on any async view:
 
 ```python
 from django.http import JsonResponse
-from fastapi_api_key.django.decorators import require_api_key
+from keyshield.django.decorators import require_api_key
 from myapp.api_keys import get_service
 
 @require_api_key(svc_factory=get_service)
@@ -111,7 +111,7 @@ Django's `as_view(svc_factory=...)` pattern is used for dependency injection.
 You can wire up any service factory, including one backed by caching:
 
 ```python
-from fastapi_api_key.services.cached import CachedApiKeyService
+from keyshield.services.cached import CachedApiKeyService
 
 async def get_service() -> CachedApiKeyService:
     return CachedApiKeyService(

docs/usage/litestar.md

@@ -1,7 +1,7 @@
 # Litestar Integration
 
-`fastapi-api-key` provides first-class support for [Litestar](https://litestar.dev/) via
-`fastapi_api_key.litestar_api`.  The integration exposes two helpers:
+`keyshield` provides first-class support for [Litestar](https://litestar.dev/) via
+`keyshield.litestar_api`.  The integration exposes two helpers:
 
 | Helper | Purpose |
 |---|---|
@@ -11,17 +11,17 @@
 ## Installation
 
 ```bash
-uv add fastapi_api_key[litestar]
+uv add keyshield[litestar]
 ```
 
 ## Quick start
 
 ```python
 from litestar import Litestar
-from fastapi_api_key.litestar_api import create_api_keys_router, create_api_key_guard
-from fastapi_api_key.services.base import ApiKeyService
-from fastapi_api_key.repositories.in_memory import InMemoryApiKeyRepository
-from fastapi_api_key.hasher.argon2 import Argon2ApiKeyHasher
+from keyshield.litestar_api import create_api_keys_router, create_api_key_guard
+from keyshield.services.base import ApiKeyService
+from keyshield.repositories.in_memory import InMemoryApiKeyRepository
+from keyshield.hasher.argon2 import Argon2ApiKeyHasher
 
 # Shared service provider (called once per request by Litestar DI)
 async def provide_svc() -> ApiKeyService:
@@ -41,7 +41,7 @@ app = Litestar(route_handlers=[mgmt_router])
 ```python
 from litestar import Litestar, get
 from litestar.connection import Request
-from fastapi_api_key.litestar_api import create_api_key_guard
+from keyshield.litestar_api import create_api_key_guard
 
 guard = create_api_key_guard(provide_svc=provide_svc)
 
@@ -93,7 +93,7 @@ lifecycle handles session management transparently:
 
 ```python
 from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
-from fastapi_api_key.repositories.sql import SqlAlchemyApiKeyRepository, Base
+from keyshield.repositories.sql import SqlAlchemyApiKeyRepository, Base
 
 engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
 SessionLocal = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
@@ -107,11 +107,11 @@ async def provide_svc() -> ApiKeyService:
 
 ## Caching
 
-The `CachedApiKeyService` from `fastapi_api_key.services.cached` works
+The `CachedApiKeyService` from `keyshield.services.cached` works
 identically in Litestar:
 
 ```python
-from fastapi_api_key.services.cached import CachedApiKeyService
+from keyshield.services.cached import CachedApiKeyService
 
 async def provide_svc() -> CachedApiKeyService:
     return CachedApiKeyService(