bearerbridge 0.1.0__tar.gz

bearerbridge-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.env
+.venv/

bearerbridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BearerBridge Contributors
+
+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.

bearerbridge-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include src/bearerbridge py.typed

bearerbridge-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: bearerbridge
+Version: 0.1.0
+Summary: FastAPI helpers for Supabase/JWKS bearer JWT validation and service-to-service auth forwarding.
+Author: BearerBridge Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,bearer,fastapi,jwks,jwt,service-to-service,supabase
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-jose[cryptography]>=3.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# BearerBridge
+
+BearerBridge is a small FastAPI auth helper for teams that pass user bearer tokens across multiple services.
+It validates Supabase/JWKS access tokens at each service boundary and adds a simple internal service key check for service-to-service calls.
+
+```text
+frontend -> core API -> agent API -> MCP API -> core API
+           JWT + internal key all the way across trusted service hops
+```
+
+BearerBridge does not generate users, store secrets, or replace your identity provider. It helps your APIs consistently answer two questions:
+
+```text
+Who is the user?        Authorization: Bearer <user jwt>
+Is this our service?    X-Internal-Service-Key: <shared service secret>
+```
+
+## Features
+
+- Validate bearer JWTs from Supabase or any JWKS-compatible issuer.
+- Verify issuer, audience, expiration, signature, and allowed algorithms.
+- Cache JWKS responses with automatic refresh when a new `kid` appears.
+- FastAPI dependencies for user JWT auth, internal service auth, or both together.
+- Constant-time internal service key comparison using `secrets.compare_digest`.
+- Header forwarding helper for chained service calls.
+- Framework-light core with only `fastapi`, `httpx`, and `python-jose` runtime dependencies.
+- MIT licensed and safe for public reuse; secrets stay in environment variables, not in the package.
+
+## Installation
+
+```bash
+pip install bearerbridge
+```
+
+For local development from this repo:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from typing import Any
+
+from fastapi import Depends, FastAPI, Request
+from bearerbridge import BearerBridge, BridgeSettings
+
+bridge = BearerBridge(
+    BridgeSettings(
+        jwks_url="https://PROJECT_REF.supabase.co/auth/v1/.well-known/jwks.json",
+        issuer="https://PROJECT_REF.supabase.co/auth/v1",
+        audience="authenticated",
+        algorithms=("ES256", "RS256"),
+        internal_service_key="use-a-long-random-secret-from-env",
+    )
+)
+
+app = FastAPI()
+
+@app.get("/me")
+async def me(claims: dict[str, Any] = Depends(bridge.require_user)):
+    return {"sub": claims.get("sub"), "email": claims.get("email")}
+
+@app.post("/internal/run")
+async def run_internal(
+    claims: dict[str, Any] = Depends(bridge.require_user_and_internal_service),
+):
+    return {"ok": True, "user_id": claims.get("sub")}
+```
+
+## Environment Example
+
+BearerBridge intentionally does not read your environment by itself. Your app should load settings however it already does, then pass them into `BridgeSettings`.
+
+```env
+JWKS_URL=https://PROJECT_REF.supabase.co/auth/v1/.well-known/jwks.json
+JWKS_ISS=https://PROJECT_REF.supabase.co/auth/v1
+JWKS_AUD=authenticated
+JWKS_ALG=ES256,RS256
+INTERNAL_SERVICE_KEY=generate-a-long-random-secret
+```
+
+Generate a service key:
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+Use the same `INTERNAL_SERVICE_KEY` in services that are allowed to call each other. Do not expose it to browsers.
+
+## Forwarding Auth Headers
+
+When one service calls the next service, forward the user JWT and add your internal service key:
+
+```python
+import httpx
+from fastapi import Request
+from bearerbridge import BearerBridge, BridgeSettings
+
+bridge = BearerBridge(BridgeSettings(...))
+
+async def call_agent(request: Request, payload: dict):
+    async with httpx.AsyncClient(timeout=20) as client:
+        response = await client.post(
+            "https://agent.example.com/run_tool",
+            json=payload,
+            headers=bridge.forward_headers(request.headers),
+        )
+        response.raise_for_status()
+        return response.json()
+```
+
+`forward_headers` copies the inbound `Authorization` header and adds `X-Internal-Service-Key` when configured.
+
+## Common Service Chain
+
+For a public multi-service chain, validate at every public service boundary:
+
+```text
+React app
+  -> Core API: validates user JWT
+  -> Agent API: validates user JWT + internal service key
+  -> MCP API: validates user JWT + internal service key
+  -> Core API: validates user JWT + internal service key for internal callbacks
+```
+
+Public health endpoints can stay unauthenticated for load balancers. Business endpoints should require at least the user JWT, and service-only endpoints should require both JWT and internal service key.
+
+## API
+
+### `BridgeSettings`
+
+```python
+BridgeSettings(
+    jwks_url: str,
+    issuer: str,
+    audience: str | tuple[str, ...] = "authenticated",
+    algorithms: tuple[str, ...] = ("ES256", "RS256"),
+    jwks_ttl_seconds: int = 36000,
+    internal_service_key: str | None = None,
+    internal_header_name: str = "X-Internal-Service-Key",
+)
+```
+
+### `BearerBridge`
+
+```python
+await bridge.decode_token(token)
+await bridge.require_user(...)
+await bridge.require_internal_service(...)
+await bridge.require_user_and_internal_service(...)
+bridge.forward_headers(inbound_headers)
+```
+
+## Security Notes
+
+- Never put `INTERNAL_SERVICE_KEY` in frontend code.
+- Prefer HTTPS everywhere.
+- Use a long random service key and rotate it when team access changes.
+- Keep JWT validation enabled in each separately reachable service.
+- Do not trust decoded JWT claims unless signature, issuer, audience, algorithm, and expiry were verified.
+- BearerBridge validates authentication; your app still owns authorization decisions such as tenant access, roles, and row-level security.
+
+## Publishing
+
+Build:
+
+```bash
+python -m build
+```
+
+Check:
+
+```bash
+python -m twine check dist/*
+```
+
+Publish to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Publish to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+## License
+
+MIT
+

bearerbridge-0.1.0/README.md

@@ -0,0 +1,194 @@
+# BearerBridge
+
+BearerBridge is a small FastAPI auth helper for teams that pass user bearer tokens across multiple services.
+It validates Supabase/JWKS access tokens at each service boundary and adds a simple internal service key check for service-to-service calls.
+
+```text
+frontend -> core API -> agent API -> MCP API -> core API
+           JWT + internal key all the way across trusted service hops
+```
+
+BearerBridge does not generate users, store secrets, or replace your identity provider. It helps your APIs consistently answer two questions:
+
+```text
+Who is the user?        Authorization: Bearer <user jwt>
+Is this our service?    X-Internal-Service-Key: <shared service secret>
+```
+
+## Features
+
+- Validate bearer JWTs from Supabase or any JWKS-compatible issuer.
+- Verify issuer, audience, expiration, signature, and allowed algorithms.
+- Cache JWKS responses with automatic refresh when a new `kid` appears.
+- FastAPI dependencies for user JWT auth, internal service auth, or both together.
+- Constant-time internal service key comparison using `secrets.compare_digest`.
+- Header forwarding helper for chained service calls.
+- Framework-light core with only `fastapi`, `httpx`, and `python-jose` runtime dependencies.
+- MIT licensed and safe for public reuse; secrets stay in environment variables, not in the package.
+
+## Installation
+
+```bash
+pip install bearerbridge
+```
+
+For local development from this repo:
+
+```bash
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+from typing import Any
+
+from fastapi import Depends, FastAPI, Request
+from bearerbridge import BearerBridge, BridgeSettings
+
+bridge = BearerBridge(
+    BridgeSettings(
+        jwks_url="https://PROJECT_REF.supabase.co/auth/v1/.well-known/jwks.json",
+        issuer="https://PROJECT_REF.supabase.co/auth/v1",
+        audience="authenticated",
+        algorithms=("ES256", "RS256"),
+        internal_service_key="use-a-long-random-secret-from-env",
+    )
+)
+
+app = FastAPI()
+
+@app.get("/me")
+async def me(claims: dict[str, Any] = Depends(bridge.require_user)):
+    return {"sub": claims.get("sub"), "email": claims.get("email")}
+
+@app.post("/internal/run")
+async def run_internal(
+    claims: dict[str, Any] = Depends(bridge.require_user_and_internal_service),
+):
+    return {"ok": True, "user_id": claims.get("sub")}
+```
+
+## Environment Example
+
+BearerBridge intentionally does not read your environment by itself. Your app should load settings however it already does, then pass them into `BridgeSettings`.
+
+```env
+JWKS_URL=https://PROJECT_REF.supabase.co/auth/v1/.well-known/jwks.json
+JWKS_ISS=https://PROJECT_REF.supabase.co/auth/v1
+JWKS_AUD=authenticated
+JWKS_ALG=ES256,RS256
+INTERNAL_SERVICE_KEY=generate-a-long-random-secret
+```
+
+Generate a service key:
+
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(48))"
+```
+
+Use the same `INTERNAL_SERVICE_KEY` in services that are allowed to call each other. Do not expose it to browsers.
+
+## Forwarding Auth Headers
+
+When one service calls the next service, forward the user JWT and add your internal service key:
+
+```python
+import httpx
+from fastapi import Request
+from bearerbridge import BearerBridge, BridgeSettings
+
+bridge = BearerBridge(BridgeSettings(...))
+
+async def call_agent(request: Request, payload: dict):
+    async with httpx.AsyncClient(timeout=20) as client:
+        response = await client.post(
+            "https://agent.example.com/run_tool",
+            json=payload,
+            headers=bridge.forward_headers(request.headers),
+        )
+        response.raise_for_status()
+        return response.json()
+```
+
+`forward_headers` copies the inbound `Authorization` header and adds `X-Internal-Service-Key` when configured.
+
+## Common Service Chain
+
+For a public multi-service chain, validate at every public service boundary:
+
+```text
+React app
+  -> Core API: validates user JWT
+  -> Agent API: validates user JWT + internal service key
+  -> MCP API: validates user JWT + internal service key
+  -> Core API: validates user JWT + internal service key for internal callbacks
+```
+
+Public health endpoints can stay unauthenticated for load balancers. Business endpoints should require at least the user JWT, and service-only endpoints should require both JWT and internal service key.
+
+## API
+
+### `BridgeSettings`
+
+```python
+BridgeSettings(
+    jwks_url: str,
+    issuer: str,
+    audience: str | tuple[str, ...] = "authenticated",
+    algorithms: tuple[str, ...] = ("ES256", "RS256"),
+    jwks_ttl_seconds: int = 36000,
+    internal_service_key: str | None = None,
+    internal_header_name: str = "X-Internal-Service-Key",
+)
+```
+
+### `BearerBridge`
+
+```python
+await bridge.decode_token(token)
+await bridge.require_user(...)
+await bridge.require_internal_service(...)
+await bridge.require_user_and_internal_service(...)
+bridge.forward_headers(inbound_headers)
+```
+
+## Security Notes
+
+- Never put `INTERNAL_SERVICE_KEY` in frontend code.
+- Prefer HTTPS everywhere.
+- Use a long random service key and rotate it when team access changes.
+- Keep JWT validation enabled in each separately reachable service.
+- Do not trust decoded JWT claims unless signature, issuer, audience, algorithm, and expiry were verified.
+- BearerBridge validates authentication; your app still owns authorization decisions such as tenant access, roles, and row-level security.
+
+## Publishing
+
+Build:
+
+```bash
+python -m build
+```
+
+Check:
+
+```bash
+python -m twine check dist/*
+```
+
+Publish to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Publish to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+## License
+
+MIT
+

bearerbridge-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "bearerbridge"
+version = "0.1.0"
+description = "FastAPI helpers for Supabase/JWKS bearer JWT validation and service-to-service auth forwarding."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "BearerBridge Contributors" }
+]
+keywords = ["fastapi", "supabase", "jwt", "jwks", "bearer", "service-to-service", "auth"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = [
+  "fastapi>=0.110",
+  "httpx>=0.27",
+  "python-jose[cryptography]>=3.3",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]
+dev = [
+  "build>=1.2",
+  "twine>=5.0",
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]
+
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/bearerbridge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+

bearerbridge-0.1.0/src/bearerbridge/__init__.py

@@ -0,0 +1,13 @@
+from bearerbridge.config import BridgeSettings
+from bearerbridge.dependencies import BearerBridge
+from bearerbridge.errors import BearerBridgeError, InternalServiceAuthError, TokenValidationError
+
+__all__ = [
+    "BearerBridge",
+    "BearerBridgeError",
+    "BridgeSettings",
+    "InternalServiceAuthError",
+    "TokenValidationError",
+]
+
+__version__ = "0.1.0"

bearerbridge-0.1.0/src/bearerbridge/config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BridgeSettings:
+    jwks_url: str
+    issuer: str
+    audience: str | tuple[str, ...] = "authenticated"
+    algorithms: tuple[str, ...] = ("ES256", "RS256")
+    jwks_ttl_seconds: int = 36000
+    internal_service_key: str | None = None
+    internal_header_name: str = "X-Internal-Service-Key"
+
+    def __post_init__(self) -> None:
+        if not self.jwks_url:
+            raise ValueError("jwks_url is required")
+        if not self.issuer:
+            raise ValueError("issuer is required")
+        if self.jwks_ttl_seconds <= 0:
+            raise ValueError("jwks_ttl_seconds must be positive")
+        if not self.algorithms:
+            raise ValueError("at least one JWT algorithm is required")
+        if not self.internal_header_name:
+            raise ValueError("internal_header_name is required")

bearerbridge-0.1.0/src/bearerbridge/dependencies.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import secrets
+from typing import Any, Mapping
+
+from fastapi import Depends, HTTPException, Request, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from starlette.datastructures import Headers
+
+from bearerbridge.config import BridgeSettings
+from bearerbridge.errors import InternalServiceAuthError, TokenValidationError
+from bearerbridge.jwks import JWKSVerifier
+
+_security = HTTPBearer(auto_error=False)
+
+
+class BearerBridge:
+    def __init__(self, settings: BridgeSettings) -> None:
+        self.settings = settings
+        self._verifier = JWKSVerifier(settings)
+
+    async def decode_token(self, token: str) -> dict[str, Any]:
+        return await self._verifier.decode(token)
+
+    async def require_user(
+        self,
+        credentials: HTTPAuthorizationCredentials | None = Depends(_security),
+    ) -> dict[str, Any]:
+        if credentials is None or credentials.scheme.lower() != "bearer":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Missing bearer token",
+            )
+        try:
+            return await self.decode_token(credentials.credentials)
+        except TokenValidationError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=str(exc),
+            ) from exc
+
+    async def require_internal_service(self, request: Request) -> None:
+        try:
+            self.verify_internal_service(request.headers)
+        except InternalServiceAuthError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=str(exc),
+            ) from exc
+
+    async def require_user_and_internal_service(
+        self,
+        request: Request,
+        credentials: HTTPAuthorizationCredentials | None = Depends(_security),
+    ) -> dict[str, Any]:
+        await self.require_internal_service(request)
+        return await self.require_user(credentials)
+
+    def verify_internal_service(self, headers: Mapping[str, str] | Headers) -> None:
+        expected = self.settings.internal_service_key
+        if not expected:
+            raise InternalServiceAuthError("Internal service key is not configured")
+
+        provided = headers.get(self.settings.internal_header_name)
+        if not provided or not secrets.compare_digest(provided, expected):
+            raise InternalServiceAuthError("Invalid internal service key")
+
+    def forward_headers(self, inbound_headers: Mapping[str, str] | Headers) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        authorization = inbound_headers.get("authorization") or inbound_headers.get("Authorization")
+        if authorization:
+            headers["Authorization"] = authorization
+        if self.settings.internal_service_key:
+            headers[self.settings.internal_header_name] = self.settings.internal_service_key
+        return headers

bearerbridge-0.1.0/src/bearerbridge/errors.py

@@ -0,0 +1,10 @@
+class BearerBridgeError(Exception):
+    """Base package exception."""
+
+
+class TokenValidationError(BearerBridgeError):
+    """Raised when bearer JWT validation fails."""
+
+
+class InternalServiceAuthError(BearerBridgeError):
+    """Raised when internal service authentication fails."""

bearerbridge-0.1.0/src/bearerbridge/jwks.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+from jose import jwk as jose_jwk
+from jose import jwt as jose_jwt
+from jose.exceptions import JWTError
+
+from bearerbridge.config import BridgeSettings
+from bearerbridge.errors import TokenValidationError
+
+
+class JWKSVerifier:
+    def __init__(self, settings: BridgeSettings) -> None:
+        self._settings = settings
+        self._jwks_cache: dict[str, Any] | None = None
+        self._jwks_cache_ts: float | None = None
+
+    async def decode(self, token: str) -> dict[str, Any]:
+        try:
+            header = jose_jwt.get_unverified_header(token)
+        except JWTError as exc:
+            raise TokenValidationError("Invalid token header") from exc
+
+        kid = header.get("kid")
+        jwks = await self._get_jwks_cached()
+        key = self._find_jwk(jwks, kid)
+
+        if key is None and kid:
+            jwks = await self._refresh_jwks()
+            key = self._find_jwk(jwks, kid)
+
+        if key is None:
+            raise TokenValidationError("Signing key not found")
+
+        public_key = jose_jwk.construct(key).to_pem().decode("utf-8")
+        audiences = (
+            self._settings.audience
+            if isinstance(self._settings.audience, tuple)
+            else (self._settings.audience,)
+        )
+        last_error: JWTError | None = None
+        for audience in audiences:
+            try:
+                decoded = jose_jwt.decode(
+                    token,
+                    key=public_key,
+                    algorithms=list(self._settings.algorithms),
+                    audience=audience,
+                    issuer=self._settings.issuer,
+                )
+                if not isinstance(decoded, dict):
+                    raise TokenValidationError("Decoded token payload is not an object")
+                return decoded
+            except JWTError as exc:
+                last_error = exc
+
+        raise TokenValidationError("Token validation failed") from last_error
+
+    async def _fetch_jwks(self) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=10) as client:
+            response = await client.get(self._settings.jwks_url)
+            response.raise_for_status()
+            data = response.json()
+
+        if not isinstance(data, dict) or not isinstance(data.get("keys"), list):
+            raise TokenValidationError("Invalid JWKS response")
+        return data
+
+    async def _get_jwks_cached(self) -> dict[str, Any]:
+        now = time.time()
+        if (
+            self._jwks_cache is not None
+            and self._jwks_cache_ts is not None
+            and now - self._jwks_cache_ts < self._settings.jwks_ttl_seconds
+        ):
+            return self._jwks_cache
+
+        try:
+            return await self._refresh_jwks()
+        except httpx.HTTPError as exc:
+            if self._jwks_cache is not None:
+                return self._jwks_cache
+            raise TokenValidationError("Failed to fetch JWKS") from exc
+
+    async def _refresh_jwks(self) -> dict[str, Any]:
+        data = await self._fetch_jwks()
+        self._jwks_cache = data
+        self._jwks_cache_ts = time.time()
+        return data
+
+    @staticmethod
+    def _find_jwk(jwks: dict[str, Any], kid: str | None) -> dict[str, Any] | None:
+        keys = jwks.get("keys", [])
+        if not isinstance(keys, list):
+            return None
+        if kid:
+            for key in keys:
+                if isinstance(key, dict) and key.get("kid") == kid:
+                    return key
+        if len(keys) == 1 and isinstance(keys[0], dict):
+            return keys[0]
+        return None
+

bearerbridge-0.1.0/tests/test_forwarding.py

@@ -0,0 +1,31 @@
+from bearerbridge.config import BridgeSettings
+from bearerbridge.dependencies import BearerBridge
+
+
+def test_forward_headers_adds_internal_key_and_preserves_authorization() -> None:
+    bridge = BearerBridge(
+        BridgeSettings(
+            jwks_url="https://example.supabase.co/auth/v1/.well-known/jwks.json",
+            issuer="https://example.supabase.co/auth/v1",
+            internal_service_key="secret",
+        )
+    )
+
+    headers = bridge.forward_headers({"authorization": "Bearer abc"})
+
+    assert headers == {
+        "Authorization": "Bearer abc",
+        "X-Internal-Service-Key": "secret",
+    }
+
+
+def test_verify_internal_service_accepts_matching_key() -> None:
+    bridge = BearerBridge(
+        BridgeSettings(
+            jwks_url="https://example.supabase.co/auth/v1/.well-known/jwks.json",
+            issuer="https://example.supabase.co/auth/v1",
+            internal_service_key="secret",
+        )
+    )
+
+    bridge.verify_internal_service({"X-Internal-Service-Key": "secret"})

bearerbridge-0.1.0/tests/test_settings.py

@@ -0,0 +1,10 @@
+from bearerbridge.config import BridgeSettings
+
+
+def test_settings_requires_jwks_url() -> None:
+    try:
+        BridgeSettings(jwks_url="", issuer="issuer")
+    except ValueError as exc:
+        assert "jwks_url" in str(exc)
+    else:
+        raise AssertionError("expected ValueError")