fastapi-auth-manager-dep 0.1.0__tar.gz

fastapi_auth_manager_dep-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2026 Edmundo Andrade
+
+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.

fastapi_auth_manager_dep-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+exclude src/fastapi_auth/example_app.py
+recursive-exclude src/fastapi_auth/tests *
+recursive-exclude src/fastapi_auth/__pycache__ *

fastapi_auth_manager_dep-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: fastapi-auth-manager-dep
+Version: 0.1.0
+Summary: Reusable authentication dependency for FastAPI with **API Key** and **JWT Bearer** support.
+Author-email: Edmundo Andrade <edmon.af@gmail.com>
+Project-URL: Homepage, https://github.com/edmon1024/fastapi-auth-manager-dep
+Project-URL: Documentation, https://github.com/edmon1024/fastapi-auth-manager-dep
+Project-URL: Repository, https://github.com/edmon1024/fastapi-auth-manager-dep
+Project-URL: Issues, https://github.com/edmon1024/fastapi-auth-manager-dep/issues
+Project-URL: Changelog, https://github.com/edmon1024/fastapi-auth-manager-dep/CHANGELOG.md
+Keywords: fastapi,fastapi-auth-middleware,fastapi-jwt-auth,fastapi-jwt
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pyjwt>=2.4.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: httpx>=0.24.0; extra == "test"
+Dynamic: license-file
+
+# fastapi-auth-manager-dep
+
+Reusable authentication dependency for FastAPI with **API Key** and **JWT Bearer** support.
+
+- One mandatory ADMIN key via envvar (super-key, always valid)
+- Additional api-keys with labels/roles via JSON envvar
+- Fine-grained per-endpoint control: which roles each endpoint accepts
+- HMAC JWT with configurable algorithms
+- Public endpoints via explicit opt-out
+
+---
+
+## Install
+
+```bash
+pip install fastapi-auth-manager-dep
+```
+
+---
+
+## Environment variables
+
+| Variable          | Required | Description                                                                   |
+|-------------------|----------|-------------------------------------------------------------------------------|
+| `AUTH_ADMIN_API_KEY`         | Yes      | Administrator api-key. Super-key: valid on every endpoint.                    |
+| `AUTH_API_KEYS`        | No       | JSON object mapping api-keys to their labels. See format below.               |
+| `AUTH_JWT_SECRET_KEY`| No*      | HMAC secret key for verifying user JWTs. Required when using `"jwt"`. |
+| `AUTH_JWT_ALGORITHMS`  | No       | List of allowed algorithms (default: `["HS256", "HS384", "HS512"]`).          |
+
+### `AUTH_API_KEYS` format
+
+A JSON object where each key is the raw api-key value and the value is its label/role:
+
+```bash
+AUTH_API_KEYS='{"key-abc123": "reports", "key-xyz789": "billing", "key-qrs456": "billing"}'
+```
+
+- Multiple keys can share the same label (same role).
+- Empty string (`AUTH_API_KEYS=""`) is equivalent to having no additional keys.
+
+### `.env` example
+
+```dotenv
+AUTH_ADMIN_API_KEY=super-secret-admin-key
+AUTH_API_KEYS={"key-reports-1": "reports", "key-billing-1": "billing", "key-billing-2": "billing"}
+AUTH_JWT_SECRET_KEY=my-jwt-secret-key
+```
+
+---
+
+## Usage
+
+### 1. Global authentication (entire app)
+
+All endpoints are protected with the ADMIN key by default:
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_auth import AuthDependency
+
+app = FastAPI(dependencies=[Depends(AuthDependency())])
+```
+
+### 2. Restrict by api-key label
+
+Only the ADMIN key and keys labelled `"reports"` can access:
+
+```python
+from fastapi_auth import AuthDependency
+
+@app.get(
+    "/reports",
+    dependencies=[Depends(AuthDependency(valid_token_types={"reports"}))]
+)
+async def get_reports():
+    ...
+```
+
+### 3. Combine api-key and JWT on the same endpoint
+
+```python
+from fastapi_auth import AuthDependency
+
+@app.get(
+    "/billing",
+    dependencies=[Depends(AuthDependency(valid_token_types={"billing", "jwt"}))]
+)
+async def get_billing():
+    ...
+```
+
+### 4. Allow all additional api-keys
+
+```python
+from fastapi_auth import AuthDependency
+
+# Using the AuthDependency.ALL sentinel
+@app.get(
+    "/any",
+    dependencies=[Depends(AuthDependency(valid_token_types=AuthDependency.ALL))]
+)
+async def any_key_endpoint():
+    ...
+
+# Equivalent using a string
+AuthDependency(valid_token_types="*")
+```
+
+### 5. Access the authenticated principal inside a handler
+
+`AuthDependency` returns an `AuthPrincipal` with the method used, role, and JWT payload:
+
+```python
+from fastapi_auth import AuthDependency, AuthPrincipal
+
+@app.get("/me")
+async def me(
+    principal: AuthPrincipal = Depends(
+        AuthDependency(valid_token_types={"jwt", "billing"})
+    )
+):
+    return {
+        "method":  principal.method,   # "jwt" | "api_key"
+        "sub":     principal.sub,       # user_id (JWT) or raw key value (api-key)
+        "role":    principal.role,      # "admin" | "reports" | "billing" | None (JWT)
+        "payload": principal.payload,   # full JWT dict | None
+    }
+```
+
+### 6. Public endpoint (opt-out of global auth)
+
+When auth is configured globally, use `PublicRoute` to exclude specific endpoints:
+
+```python
+from fastapi_auth import PublicRoute
+
+@app.get("/health", dependencies=[Depends(PublicRoute())])
+async def health():
+    return {"status": "ok"}
+```
+
+---
+
+## `valid_token_types` behaviour reference
+
+| `valid_token_types`          | ADMIN key | Additional keys         | User JWT |
+|------------------------------|-----------|-------------------------|----------|
+| `None` (default)             | Yes       | No                      | No       |
+| `{"reports"}`                | Yes       | `reports` label only    | No       |
+| `{"billing", "jwt"}`         | Yes       | `billing` label only    | Yes      |
+| `AuthDependency.ALL` / `"*"` | Yes       | All                     | No       |
+| `{"jwt"}`                    | Yes       | No                      | Yes      |
+
+> The ADMIN key is always valid regardless of the endpoint configuration.
+
+---
+
+## `AuthPrincipal` — return object
+
+```python
+class AuthPrincipal(BaseModel):
+    method:  AuthMethod           # AuthMethod.JWT | AuthMethod.AUTH_ADMIN_API_KEY
+    sub:     str                  # user_id (JWT) or raw api-key value
+    role:    str | None = None    # key role/label; None for JWT
+    payload: dict | None = None   # full JWT payload; None for api-key
+```
+
+---
+
+## Error responses
+
+All authentication errors return HTTP `401 Unauthorized` with a `detail` field:
+
+| Situation                            | `detail`                                  |
+|--------------------------------------|-------------------------------------------|
+| No credentials provided              | `"Authentication credentials are required"` |
+| Api-key not found or not allowed     | `"Invalid authentication credentials"`   |
+| Expired JWT                          | `"JWT token has expired"`                 |
+| Invalid JWT signature                | `"Invalid JWT token: ..."`               |
+| Disallowed JWT algorithm             | `"JWT algorithm not allowed: RS256"`      |
+
+---
+
+## Tests
+
+```bash
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+Test coverage includes:
+
+- ADMIN key as super-key across endpoints with different restrictions
+- Label-based restriction: accepts the correct label, rejects others
+- Multiple keys sharing the same label
+- `ALL` sentinel and its `"*"` string equivalent
+- Valid JWT, expired JWT, JWT ignored when `"jwt"` is not enabled
+- No credentials
+- `AUTH_API_KEYS` validation in settings (JSON string, dict, invalid JSON)
+
+---
+
+## Full example
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_auth import AuthDependency, AuthPrincipal, PublicRoute
+
+app = FastAPI(dependencies=[Depends(AuthDependency())])  # global: ADMIN key only
+
+@app.get("/health", dependencies=[Depends(PublicRoute())])
+async def health():
+    return {"status": "ok"}
+
+@app.get("/reports", dependencies=[Depends(AuthDependency(valid_token_types={"reports"}))])
+async def reports():
+    return {"data": "..."}
+
+@app.get("/me")
+async def me(
+    principal: AuthPrincipal = Depends(AuthDependency(valid_token_types={"jwt"}))
+):
+    return {"sub": principal.sub, "payload": principal.payload}
+
+@app.get("/internal", dependencies=[Depends(AuthDependency(valid_token_types=AuthDependency.ALL))])
+async def internal():
+    return {"message": "any valid api-key accepted"}
+```

fastapi_auth_manager_dep-0.1.0/README.md

@@ -0,0 +1,228 @@
+# fastapi-auth-manager-dep
+
+Reusable authentication dependency for FastAPI with **API Key** and **JWT Bearer** support.
+
+- One mandatory ADMIN key via envvar (super-key, always valid)
+- Additional api-keys with labels/roles via JSON envvar
+- Fine-grained per-endpoint control: which roles each endpoint accepts
+- HMAC JWT with configurable algorithms
+- Public endpoints via explicit opt-out
+
+---
+
+## Install
+
+```bash
+pip install fastapi-auth-manager-dep
+```
+
+---
+
+## Environment variables
+
+| Variable          | Required | Description                                                                   |
+|-------------------|----------|-------------------------------------------------------------------------------|
+| `AUTH_ADMIN_API_KEY`         | Yes      | Administrator api-key. Super-key: valid on every endpoint.                    |
+| `AUTH_API_KEYS`        | No       | JSON object mapping api-keys to their labels. See format below.               |
+| `AUTH_JWT_SECRET_KEY`| No*      | HMAC secret key for verifying user JWTs. Required when using `"jwt"`. |
+| `AUTH_JWT_ALGORITHMS`  | No       | List of allowed algorithms (default: `["HS256", "HS384", "HS512"]`).          |
+
+### `AUTH_API_KEYS` format
+
+A JSON object where each key is the raw api-key value and the value is its label/role:
+
+```bash
+AUTH_API_KEYS='{"key-abc123": "reports", "key-xyz789": "billing", "key-qrs456": "billing"}'
+```
+
+- Multiple keys can share the same label (same role).
+- Empty string (`AUTH_API_KEYS=""`) is equivalent to having no additional keys.
+
+### `.env` example
+
+```dotenv
+AUTH_ADMIN_API_KEY=super-secret-admin-key
+AUTH_API_KEYS={"key-reports-1": "reports", "key-billing-1": "billing", "key-billing-2": "billing"}
+AUTH_JWT_SECRET_KEY=my-jwt-secret-key
+```
+
+---
+
+## Usage
+
+### 1. Global authentication (entire app)
+
+All endpoints are protected with the ADMIN key by default:
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_auth import AuthDependency
+
+app = FastAPI(dependencies=[Depends(AuthDependency())])
+```
+
+### 2. Restrict by api-key label
+
+Only the ADMIN key and keys labelled `"reports"` can access:
+
+```python
+from fastapi_auth import AuthDependency
+
+@app.get(
+    "/reports",
+    dependencies=[Depends(AuthDependency(valid_token_types={"reports"}))]
+)
+async def get_reports():
+    ...
+```
+
+### 3. Combine api-key and JWT on the same endpoint
+
+```python
+from fastapi_auth import AuthDependency
+
+@app.get(
+    "/billing",
+    dependencies=[Depends(AuthDependency(valid_token_types={"billing", "jwt"}))]
+)
+async def get_billing():
+    ...
+```
+
+### 4. Allow all additional api-keys
+
+```python
+from fastapi_auth import AuthDependency
+
+# Using the AuthDependency.ALL sentinel
+@app.get(
+    "/any",
+    dependencies=[Depends(AuthDependency(valid_token_types=AuthDependency.ALL))]
+)
+async def any_key_endpoint():
+    ...
+
+# Equivalent using a string
+AuthDependency(valid_token_types="*")
+```
+
+### 5. Access the authenticated principal inside a handler
+
+`AuthDependency` returns an `AuthPrincipal` with the method used, role, and JWT payload:
+
+```python
+from fastapi_auth import AuthDependency, AuthPrincipal
+
+@app.get("/me")
+async def me(
+    principal: AuthPrincipal = Depends(
+        AuthDependency(valid_token_types={"jwt", "billing"})
+    )
+):
+    return {
+        "method":  principal.method,   # "jwt" | "api_key"
+        "sub":     principal.sub,       # user_id (JWT) or raw key value (api-key)
+        "role":    principal.role,      # "admin" | "reports" | "billing" | None (JWT)
+        "payload": principal.payload,   # full JWT dict | None
+    }
+```
+
+### 6. Public endpoint (opt-out of global auth)
+
+When auth is configured globally, use `PublicRoute` to exclude specific endpoints:
+
+```python
+from fastapi_auth import PublicRoute
+
+@app.get("/health", dependencies=[Depends(PublicRoute())])
+async def health():
+    return {"status": "ok"}
+```
+
+---
+
+## `valid_token_types` behaviour reference
+
+| `valid_token_types`          | ADMIN key | Additional keys         | User JWT |
+|------------------------------|-----------|-------------------------|----------|
+| `None` (default)             | Yes       | No                      | No       |
+| `{"reports"}`                | Yes       | `reports` label only    | No       |
+| `{"billing", "jwt"}`         | Yes       | `billing` label only    | Yes      |
+| `AuthDependency.ALL` / `"*"` | Yes       | All                     | No       |
+| `{"jwt"}`                    | Yes       | No                      | Yes      |
+
+> The ADMIN key is always valid regardless of the endpoint configuration.
+
+---
+
+## `AuthPrincipal` — return object
+
+```python
+class AuthPrincipal(BaseModel):
+    method:  AuthMethod           # AuthMethod.JWT | AuthMethod.AUTH_ADMIN_API_KEY
+    sub:     str                  # user_id (JWT) or raw api-key value
+    role:    str | None = None    # key role/label; None for JWT
+    payload: dict | None = None   # full JWT payload; None for api-key
+```
+
+---
+
+## Error responses
+
+All authentication errors return HTTP `401 Unauthorized` with a `detail` field:
+
+| Situation                            | `detail`                                  |
+|--------------------------------------|-------------------------------------------|
+| No credentials provided              | `"Authentication credentials are required"` |
+| Api-key not found or not allowed     | `"Invalid authentication credentials"`   |
+| Expired JWT                          | `"JWT token has expired"`                 |
+| Invalid JWT signature                | `"Invalid JWT token: ..."`               |
+| Disallowed JWT algorithm             | `"JWT algorithm not allowed: RS256"`      |
+
+---
+
+## Tests
+
+```bash
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+Test coverage includes:
+
+- ADMIN key as super-key across endpoints with different restrictions
+- Label-based restriction: accepts the correct label, rejects others
+- Multiple keys sharing the same label
+- `ALL` sentinel and its `"*"` string equivalent
+- Valid JWT, expired JWT, JWT ignored when `"jwt"` is not enabled
+- No credentials
+- `AUTH_API_KEYS` validation in settings (JSON string, dict, invalid JSON)
+
+---
+
+## Full example
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_auth import AuthDependency, AuthPrincipal, PublicRoute
+
+app = FastAPI(dependencies=[Depends(AuthDependency())])  # global: ADMIN key only
+
+@app.get("/health", dependencies=[Depends(PublicRoute())])
+async def health():
+    return {"status": "ok"}
+
+@app.get("/reports", dependencies=[Depends(AuthDependency(valid_token_types={"reports"}))])
+async def reports():
+    return {"data": "..."}
+
+@app.get("/me")
+async def me(
+    principal: AuthPrincipal = Depends(AuthDependency(valid_token_types={"jwt"}))
+):
+    return {"sub": principal.sub, "payload": principal.payload}
+
+@app.get("/internal", dependencies=[Depends(AuthDependency(valid_token_types=AuthDependency.ALL))])
+async def internal():
+    return {"message": "any valid api-key accepted"}
+```

fastapi_auth_manager_dep-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["setuptools>=82.0.1", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastapi-auth-manager-dep"
+version = "0.1.0"
+authors = [
+  { name="Edmundo Andrade", email="edmon.af@gmail.com" },
+]
+description = "Reusable authentication dependency for FastAPI with **API Key** and **JWT Bearer** support."
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = [
+    "fastapi",
+    "fastapi-auth-middleware",
+    "fastapi-jwt-auth",
+    "fastapi-jwt",
+]
+classifiers = [
+    "Framework :: FastAPI",
+    "Operating System :: OS Independent",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "fastapi>=0.100.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "pyjwt>=2.4.0",
+]
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "httpx>=0.24.0",
+]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+exclude-package-data = {"fastapi_auth" = ["tests*", "example_app.py"]}
+
+[project.urls]
+Homepage = "https://github.com/edmon1024/fastapi-auth-manager-dep"
+Documentation = "https://github.com/edmon1024/fastapi-auth-manager-dep"
+Repository = "https://github.com/edmon1024/fastapi-auth-manager-dep"
+Issues = "https://github.com/edmon1024/fastapi-auth-manager-dep/issues"
+Changelog = "https://github.com/edmon1024/fastapi-auth-manager-dep/CHANGELOG.md"
+
+

fastapi_auth_manager_dep-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth/__init__.py

@@ -0,0 +1,11 @@
+from .dependency import AuthDependency
+from .enums import AuthMethod
+from .public import PublicRoute
+from .schemas import AuthPrincipal
+
+__all__ = [
+    "AuthDependency",
+    "AuthMethod",
+    "PublicRoute",
+    "AuthPrincipal",
+]

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth/dependency.py

@@ -0,0 +1,253 @@
+import logging
+from enum import Enum
+from typing import Optional
+
+import jwt as pyjwt
+from fastapi import HTTPException, Security, status
+from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer
+
+from .enums import AuthMethod
+from .schemas import AuthPrincipal
+from .settings import AuthSettings, get_auth_settings
+
+logger = logging.getLogger(__name__)
+
+# Security schemes shared across all instances (module-level singletons)
+_bearer_scheme = HTTPBearer(auto_error=False)
+_api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+# Sentinel value for "allow all additional api-keys"
+_ALL = object()
+
+
+class AuthDependency:
+    """
+    Authentication dependency for FastAPI.
+
+    Supported mechanisms
+    --------------------
+    - **API Key** via ``X-API-Key`` header
+    - **JWT Bearer** via ``Authorization: Bearer <token>`` header
+      (only when ``"jwt"`` is included in ``valid_token_types``)
+
+    Api-key logic
+    -------------
+    The ADMIN key (``AUTH_ADMIN_API_KEY`` envvar) is a **super-key**: always valid on any
+    endpoint, regardless of ``valid_token_types``.
+
+    Additional keys are defined in the ``AUTH_API_KEYS`` envvar as JSON::
+
+        AUTH_API_KEYS='{"key-abc": "reports", "key-xyz": "billing"}'
+
+    Each key's label must be used for per-endpoint restrictions via ``valid_token_types``.
+
+    Controlling which keys a given instance accepts
+    -----------------------------------------------
+    ``valid_token_types=None``
+        ADMIN key only (default behaviour).
+
+    ``valid_token_types={"reports"}``
+        ADMIN key + all keys labelled ``"reports"``.
+
+    ``valid_token_types="*"`` or ``valid_token_types=AuthDependency.ALL``
+        ADMIN key + **all** additional keys with no label filter.
+
+    Quick reference
+    ---------------
+    ::
+
+        # Global: ADMIN key only
+        app = FastAPI(dependencies=[Depends(AuthDependency())])
+
+        # Endpoint: accept "reports" keys and user JWTs
+        @router.get("/report", dependencies=[Depends(
+            AuthDependency(valid_token_types={"reports", "jwt"})
+        )])
+
+        # Endpoint: accept all additional keys
+        @router.get("/open", dependencies=[Depends(
+            AuthDependency(valid_token_types=AuthDependency.ALL)
+        )])
+
+        # Access the authenticated principal inside the handler
+        @router.get("/me")
+        async def me(principal: AuthPrincipal = Depends(AuthDependency(...))):
+            return principal
+    """
+
+    #: Sentinel to allow all additional api-keys without label filtering.
+    ALL = _ALL
+
+    def __init__(
+        self,
+        valid_token_types: "set[str | Enum] | object | None" = None,
+        settings: AuthSettings | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        valid_token_types:
+            - ``None``                       → ADMIN key only.
+            - ``{"role-a"}``                 → ADMIN key + keys labelled ``"role-a"``.
+            - ``AuthDependency.ALL`` / ``"*"`` → ADMIN key + all additional keys.
+            - Include ``"jwt"`` to enable user JWT authentication.
+        settings:
+            Configuration injection. Defaults to ``get_auth_settings()``.
+        """
+        self._settings = settings or get_auth_settings()
+        self._allow_all_keys: bool = valid_token_types is _ALL or valid_token_types == "*"
+
+        if self._allow_all_keys:
+            self._valid_token_types: set[str] = set()
+        else:
+            self._valid_token_types = self._normalize(valid_token_types)
+
+    # ------------------------------------------------------------------
+    # Static helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _normalize(raw: "set[str | Enum] | None") -> set[str]:
+        """Converts a mixed Enum/str set to a plain set of strings."""
+        if not raw:
+            return set()
+        result: set[str] = set()
+        for item in raw:
+            result.add(item.value if isinstance(item, Enum) else str(item))
+        return result
+
+    # ------------------------------------------------------------------
+    # Allowed api-key set construction
+    # ------------------------------------------------------------------
+
+    def _allowed_api_keys(self) -> set[str]:
+        """
+        Returns the set of valid api-keys for this instance.
+
+        Rules:
+        1. ADMIN key is always included (super-key).
+        2. If ``_allow_all_keys`` → every key from ``AUTH_API_KEYS``.
+        3. Otherwise → only keys whose label is in ``_valid_token_types``.
+        """
+        allowed: set[str] = set()
+
+        # 1. ADMIN super-key (always)
+        if self._settings.AUTH_ADMIN_API_KEY:
+            allowed.add(self._settings.AUTH_ADMIN_API_KEY)
+
+        # 2. Additional keys according to policy
+        if self._allow_all_keys:
+            allowed.update(k for k in self._settings.AUTH_API_KEYS if k)
+        else:
+            for label in self._valid_token_types:
+                if label == "jwt":
+                    continue  # label is "jwt", which indicates JWT auth, not an api-key
+                allowed.update(self._settings.keys_for_label(label))
+
+        return allowed
+
+    # ------------------------------------------------------------------
+    # JWT verification
+    # ------------------------------------------------------------------
+
+    def _verify_jwt(self, token: str) -> dict:
+        """
+        Decodes and validates an HMAC JWT.
+
+        Raises
+        ------
+        HTTPException 401 for invalid, expired, or disallowed-algorithm tokens.
+        """
+        try:
+            header = pyjwt.get_unverified_header(token)
+            alg = header.get("alg")
+            if alg not in self._settings.AUTH_JWT_ALGORITHMS:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail=f"JWT algorithm not allowed: {alg}",
+                )
+            payload = pyjwt.decode(
+                token,
+                self._settings.AUTH_JWT_SECRET_KEY,
+                algorithms=self._settings.AUTH_JWT_ALGORITHMS,
+            )
+            return payload
+        except HTTPException:
+            raise
+        except pyjwt.ExpiredSignatureError:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="JWT token has expired",
+            )
+        except pyjwt.InvalidTokenError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=f"Invalid JWT token: {exc}",
+            )
+
+    # ------------------------------------------------------------------
+    # Api-key verification
+    # ------------------------------------------------------------------
+
+    def _verify_api_key(self, api_key: str) -> str:
+        """
+        Validates the api-key against the allowed set.
+
+        Returns
+        -------
+        The label/role associated with the key (``"admin"`` for the ADMIN key).
+
+        Raises
+        ------
+        HTTPException 401 if the key is not in the allowed set.
+        """
+        if api_key not in self._allowed_api_keys():
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid authentication credentials",
+            )
+        return self._settings.label_for_key(api_key) or "unknown"
+
+    # ------------------------------------------------------------------
+    # Main callable
+    # ------------------------------------------------------------------
+
+    async def __call__(
+        self,
+        credentials: Optional[HTTPAuthorizationCredentials] = Security(_bearer_scheme),
+        api_key: Optional[str] = Security(_api_key_header),
+    ) -> AuthPrincipal:
+        """
+        Evaluation order:
+        1. JWT Bearer  → if ``"jwt"`` is enabled and a Bearer token is present.
+        2. API Key     → if the ``X-API-Key`` header is present.
+        3. 401         → no valid mechanism found.
+
+        Returns
+        -------
+        :class:`AuthPrincipal` with method, sub, role, and optional payload.
+        """
+        # 1. JWT
+        jwt_enabled = "jwt" in self._valid_token_types
+        if jwt_enabled and credentials and credentials.scheme.lower() == "bearer":
+            payload = self._verify_jwt(credentials.credentials)
+            return AuthPrincipal(
+                method=AuthMethod.JWT,
+                sub=payload.get("sub", ""),
+                payload=payload,
+            )
+
+        # 2. API Key
+        if api_key:
+            label = self._verify_api_key(api_key)
+            return AuthPrincipal(
+                method=AuthMethod.AUTH_ADMIN_API_KEY,
+                sub=api_key,
+                role=label,
+            )
+
+        # 3. No credentials → 401
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication credentials are required",
+        )

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth/enums.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class AuthMethod(str, Enum):
+    JWT = "jwt"
+    AUTH_ADMIN_API_KEY = "api_key"

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth/public.py

@@ -0,0 +1,36 @@
+from typing import Optional
+
+from fastapi import Security
+from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer
+
+from .schemas import AuthPrincipal
+
+_bearer_scheme = HTTPBearer(auto_error=False)
+_api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+class PublicRoute:
+    """
+    No-auth dependency for public endpoints.
+
+    When authentication is configured globally on the app
+    (via ``app = FastAPI(dependencies=[Depends(AuthDependency())])``),
+    use this dependency to opt specific endpoints out of authentication.
+    It accepts any request without validation.
+
+    Usage
+    -----
+    ```python
+    @router.get("/health", dependencies=[Depends(PublicRoute())])
+    async def health():
+        return {"status": "ok"}
+    ```
+    """
+
+    async def __call__(
+        self,
+        credentials: Optional[HTTPAuthorizationCredentials] = Security(_bearer_scheme),
+        api_key: Optional[str] = Security(_api_key_header),
+    ) -> None:
+        """Always returns None without validating anything."""
+        return None

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth/schemas.py

@@ -0,0 +1,23 @@
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+from .enums import AuthMethod
+
+
+class AuthPrincipal(BaseModel):
+    """
+    Authentication result returned by AuthDependency.
+
+    Attributes
+    ----------
+    method  : Mechanism used (``"jwt"`` or ``"api_key"``).
+    sub     : Subject identifier (``user_id`` for JWT, raw key value for api-key).
+    role    : Api-key label/role (``"admin"``, ``"reports"``…). None for JWT.
+    payload : Full JWT payload. None for api-key.
+    """
+
+    method: AuthMethod
+    sub: str
+    role: Optional[str] = None
+    payload: Optional[dict[str, Any]] = None

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth/settings.py

@@ -0,0 +1,113 @@
+import json
+import logging
+from functools import lru_cache
+
+from pydantic import field_validator, model_validator
+from pydantic_settings import BaseSettings
+
+logger = logging.getLogger(__name__)
+
+
+class AuthSettings(BaseSettings):
+    """
+    Environment variables for the authentication module.
+
+    Required
+    --------
+    AUTH_ADMIN_API_KEY           Admin api-key (super-key, always required).
+
+    Optional
+    --------
+    AUTH_API_KEYS          JSON object mapping raw api-keys to their labels/roles.
+                      Format: '{"key-abc": "reports", "key-xyz": "billing"}'
+                      Labels are used with valid_token_types in AuthDependency.
+
+    AUTH_JWT_SECRET_KEY  HMAC secret key for verifying user JWTs.
+                      Required only when using "jwt" in valid_token_types.
+
+    AUTH_JWT_ALGORITHMS    List of allowed HMAC algorithms (default: HS256/384/512).
+    """
+
+    # --- Admin api-key (required) ---
+    AUTH_ADMIN_API_KEY: str
+
+    # --- Additional api-keys: {"<raw-key>": "<label>", ...} ---
+    AUTH_API_KEYS: dict[str, str] = {}
+
+    # --- JWT ---
+    AUTH_JWT_SECRET_KEY: str = ""
+    AUTH_JWT_ALGORITHMS: list[str] = ["HS256", "HS384", "HS512"]
+
+    @field_validator("AUTH_API_KEYS", mode="before")
+    @classmethod
+    def _parse_api_keys(cls, v: object) -> dict[str, str]:
+        """Accepts the envvar as a JSON string or as a dict (useful for test injection)."""
+        if isinstance(v, str):
+            v = v.strip()
+            if not v:
+                return {}
+            try:
+                parsed = json.loads(v)
+            except json.JSONDecodeError as exc:
+                raise ValueError(
+                    f"AUTH_API_KEYS must be a valid JSON string: {exc}. "
+                    'Example: \'{"key-abc": "reports", "key-xyz": "billing"}\''
+                ) from exc
+            if not isinstance(parsed, dict):
+                raise ValueError("AUTH_API_KEYS must be a JSON object (dict).")
+            return parsed
+        if isinstance(v, dict):
+            return v
+        raise ValueError(f"Unexpected type for AUTH_API_KEYS: {type(v)}")
+
+    @field_validator("AUTH_API_KEYS")
+    @classmethod
+    def _validate_api_keys_structure(cls, v: dict[str, str]) -> dict[str, str]:
+        """Ensures all keys and labels are non-empty strings."""
+        for key, label in v.items():
+            if not isinstance(key, str) or not key.strip():
+                raise ValueError(f"Api-key '{key}' cannot be an empty string.")
+            if not isinstance(label, str) or not label.strip():
+                raise ValueError(
+                    f"Label for api-key '{key}' cannot be an empty string."
+                )
+        return v
+
+    @model_validator(mode="after")
+    def _warn_duplicate_keys(self) -> "AuthSettings":
+        """Warns if any additional key shares the same value as the ADMIN key."""
+        duplicates = [k for k in self.AUTH_API_KEYS if k == self.AUTH_ADMIN_API_KEY]
+        if duplicates:
+            logger.warning(
+                "AUTH: One of the AUTH_API_KEYS has the same value as AUTH_ADMIN_API_KEY (admin). "
+                "Consider using unique keys per role."
+            )
+        return self
+
+    # ------------------------------------------------------------------
+    # Query helpers (used by AuthDependency)
+    # ------------------------------------------------------------------
+
+    def label_for_key(self, api_key: str) -> str | None:
+        """
+        Returns the label/role associated with an api-key.
+        The ADMIN key always returns "admin".
+        """
+        if api_key == self.AUTH_ADMIN_API_KEY:
+            return "admin"
+        return self.AUTH_API_KEYS.get(api_key)
+
+    def keys_for_label(self, label: str) -> set[str]:
+        """Returns all api-keys that share a given label."""
+        return {k for k, lbl in self.AUTH_API_KEYS.items() if lbl == label}
+
+    def all_extra_labels(self) -> set[str]:
+        """Returns the set of unique labels defined in AUTH_API_KEYS."""
+        return set(self.AUTH_API_KEYS.values())
+
+    model_config = {"env_file": ".env", "extra": "ignore"}
+
+
+@lru_cache
+def get_auth_settings() -> AuthSettings:
+    return AuthSettings()

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth_manager_dep.egg-info/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: fastapi-auth-manager-dep
+Version: 0.1.0
+Summary: Reusable authentication dependency for FastAPI with **API Key** and **JWT Bearer** support.
+Author-email: Edmundo Andrade <edmon.af@gmail.com>
+Project-URL: Homepage, https://github.com/edmon1024/fastapi-auth-manager-dep
+Project-URL: Documentation, https://github.com/edmon1024/fastapi-auth-manager-dep
+Project-URL: Repository, https://github.com/edmon1024/fastapi-auth-manager-dep
+Project-URL: Issues, https://github.com/edmon1024/fastapi-auth-manager-dep/issues
+Project-URL: Changelog, https://github.com/edmon1024/fastapi-auth-manager-dep/CHANGELOG.md
+Keywords: fastapi,fastapi-auth-middleware,fastapi-jwt-auth,fastapi-jwt
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pyjwt>=2.4.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: httpx>=0.24.0; extra == "test"
+Dynamic: license-file
+
+# fastapi-auth-manager-dep
+
+Reusable authentication dependency for FastAPI with **API Key** and **JWT Bearer** support.
+
+- One mandatory ADMIN key via envvar (super-key, always valid)
+- Additional api-keys with labels/roles via JSON envvar
+- Fine-grained per-endpoint control: which roles each endpoint accepts
+- HMAC JWT with configurable algorithms
+- Public endpoints via explicit opt-out
+
+---
+
+## Install
+
+```bash
+pip install fastapi-auth-manager-dep
+```
+
+---
+
+## Environment variables
+
+| Variable          | Required | Description                                                                   |
+|-------------------|----------|-------------------------------------------------------------------------------|
+| `AUTH_ADMIN_API_KEY`         | Yes      | Administrator api-key. Super-key: valid on every endpoint.                    |
+| `AUTH_API_KEYS`        | No       | JSON object mapping api-keys to their labels. See format below.               |
+| `AUTH_JWT_SECRET_KEY`| No*      | HMAC secret key for verifying user JWTs. Required when using `"jwt"`. |
+| `AUTH_JWT_ALGORITHMS`  | No       | List of allowed algorithms (default: `["HS256", "HS384", "HS512"]`).          |
+
+### `AUTH_API_KEYS` format
+
+A JSON object where each key is the raw api-key value and the value is its label/role:
+
+```bash
+AUTH_API_KEYS='{"key-abc123": "reports", "key-xyz789": "billing", "key-qrs456": "billing"}'
+```
+
+- Multiple keys can share the same label (same role).
+- Empty string (`AUTH_API_KEYS=""`) is equivalent to having no additional keys.
+
+### `.env` example
+
+```dotenv
+AUTH_ADMIN_API_KEY=super-secret-admin-key
+AUTH_API_KEYS={"key-reports-1": "reports", "key-billing-1": "billing", "key-billing-2": "billing"}
+AUTH_JWT_SECRET_KEY=my-jwt-secret-key
+```
+
+---
+
+## Usage
+
+### 1. Global authentication (entire app)
+
+All endpoints are protected with the ADMIN key by default:
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_auth import AuthDependency
+
+app = FastAPI(dependencies=[Depends(AuthDependency())])
+```
+
+### 2. Restrict by api-key label
+
+Only the ADMIN key and keys labelled `"reports"` can access:
+
+```python
+from fastapi_auth import AuthDependency
+
+@app.get(
+    "/reports",
+    dependencies=[Depends(AuthDependency(valid_token_types={"reports"}))]
+)
+async def get_reports():
+    ...
+```
+
+### 3. Combine api-key and JWT on the same endpoint
+
+```python
+from fastapi_auth import AuthDependency
+
+@app.get(
+    "/billing",
+    dependencies=[Depends(AuthDependency(valid_token_types={"billing", "jwt"}))]
+)
+async def get_billing():
+    ...
+```
+
+### 4. Allow all additional api-keys
+
+```python
+from fastapi_auth import AuthDependency
+
+# Using the AuthDependency.ALL sentinel
+@app.get(
+    "/any",
+    dependencies=[Depends(AuthDependency(valid_token_types=AuthDependency.ALL))]
+)
+async def any_key_endpoint():
+    ...
+
+# Equivalent using a string
+AuthDependency(valid_token_types="*")
+```
+
+### 5. Access the authenticated principal inside a handler
+
+`AuthDependency` returns an `AuthPrincipal` with the method used, role, and JWT payload:
+
+```python
+from fastapi_auth import AuthDependency, AuthPrincipal
+
+@app.get("/me")
+async def me(
+    principal: AuthPrincipal = Depends(
+        AuthDependency(valid_token_types={"jwt", "billing"})
+    )
+):
+    return {
+        "method":  principal.method,   # "jwt" | "api_key"
+        "sub":     principal.sub,       # user_id (JWT) or raw key value (api-key)
+        "role":    principal.role,      # "admin" | "reports" | "billing" | None (JWT)
+        "payload": principal.payload,   # full JWT dict | None
+    }
+```
+
+### 6. Public endpoint (opt-out of global auth)
+
+When auth is configured globally, use `PublicRoute` to exclude specific endpoints:
+
+```python
+from fastapi_auth import PublicRoute
+
+@app.get("/health", dependencies=[Depends(PublicRoute())])
+async def health():
+    return {"status": "ok"}
+```
+
+---
+
+## `valid_token_types` behaviour reference
+
+| `valid_token_types`          | ADMIN key | Additional keys         | User JWT |
+|------------------------------|-----------|-------------------------|----------|
+| `None` (default)             | Yes       | No                      | No       |
+| `{"reports"}`                | Yes       | `reports` label only    | No       |
+| `{"billing", "jwt"}`         | Yes       | `billing` label only    | Yes      |
+| `AuthDependency.ALL` / `"*"` | Yes       | All                     | No       |
+| `{"jwt"}`                    | Yes       | No                      | Yes      |
+
+> The ADMIN key is always valid regardless of the endpoint configuration.
+
+---
+
+## `AuthPrincipal` — return object
+
+```python
+class AuthPrincipal(BaseModel):
+    method:  AuthMethod           # AuthMethod.JWT | AuthMethod.AUTH_ADMIN_API_KEY
+    sub:     str                  # user_id (JWT) or raw api-key value
+    role:    str | None = None    # key role/label; None for JWT
+    payload: dict | None = None   # full JWT payload; None for api-key
+```
+
+---
+
+## Error responses
+
+All authentication errors return HTTP `401 Unauthorized` with a `detail` field:
+
+| Situation                            | `detail`                                  |
+|--------------------------------------|-------------------------------------------|
+| No credentials provided              | `"Authentication credentials are required"` |
+| Api-key not found or not allowed     | `"Invalid authentication credentials"`   |
+| Expired JWT                          | `"JWT token has expired"`                 |
+| Invalid JWT signature                | `"Invalid JWT token: ..."`               |
+| Disallowed JWT algorithm             | `"JWT algorithm not allowed: RS256"`      |
+
+---
+
+## Tests
+
+```bash
+pip install pytest pytest-asyncio
+pytest tests/ -v
+```
+
+Test coverage includes:
+
+- ADMIN key as super-key across endpoints with different restrictions
+- Label-based restriction: accepts the correct label, rejects others
+- Multiple keys sharing the same label
+- `ALL` sentinel and its `"*"` string equivalent
+- Valid JWT, expired JWT, JWT ignored when `"jwt"` is not enabled
+- No credentials
+- `AUTH_API_KEYS` validation in settings (JSON string, dict, invalid JSON)
+
+---
+
+## Full example
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_auth import AuthDependency, AuthPrincipal, PublicRoute
+
+app = FastAPI(dependencies=[Depends(AuthDependency())])  # global: ADMIN key only
+
+@app.get("/health", dependencies=[Depends(PublicRoute())])
+async def health():
+    return {"status": "ok"}
+
+@app.get("/reports", dependencies=[Depends(AuthDependency(valid_token_types={"reports"}))])
+async def reports():
+    return {"data": "..."}
+
+@app.get("/me")
+async def me(
+    principal: AuthPrincipal = Depends(AuthDependency(valid_token_types={"jwt"}))
+):
+    return {"sub": principal.sub, "payload": principal.payload}
+
+@app.get("/internal", dependencies=[Depends(AuthDependency(valid_token_types=AuthDependency.ALL))])
+async def internal():
+    return {"message": "any valid api-key accepted"}
+```

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth_manager_dep.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/fastapi_auth/__init__.py
+src/fastapi_auth/dependency.py
+src/fastapi_auth/enums.py
+src/fastapi_auth/public.py
+src/fastapi_auth/schemas.py
+src/fastapi_auth/settings.py
+src/fastapi_auth_manager_dep.egg-info/PKG-INFO
+src/fastapi_auth_manager_dep.egg-info/SOURCES.txt
+src/fastapi_auth_manager_dep.egg-info/dependency_links.txt
+src/fastapi_auth_manager_dep.egg-info/requires.txt
+src/fastapi_auth_manager_dep.egg-info/top_level.txt

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth_manager_dep.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth_manager_dep.egg-info/requires.txt

@@ -0,0 +1,9 @@
+fastapi>=0.100.0
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+pyjwt>=2.4.0
+
+[test]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+httpx>=0.24.0

fastapi_auth_manager_dep-0.1.0/src/fastapi_auth_manager_dep.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastapi_auth