remem-auth 0.1.0__tar.gz

remem_auth-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.worktrees/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.venv/

remem_auth-0.1.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: remem-auth
+Version: 0.1.0
+Summary: Shared authentication library for remem Python services
+Requires-Python: <3.15,>=3.11
+Requires-Dist: pydantic-settings<3,>=2
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyjwt[crypto]<3,>=2.8
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: fastmcp>=2.14.0; extra == 'all'
+Requires-Dist: starlette>=0.27; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: cryptography==46.0.5; extra == 'dev'
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: fastmcp>=2.14.0; extra == 'dev'
+Requires-Dist: httpx==0.28.1; extra == 'dev'
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.2; extra == 'dev'
+Requires-Dist: ruff==0.15.4; extra == 'dev'
+Requires-Dist: starlette>=0.27; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: starlette>=0.27; extra == 'fastapi'
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=2.14.0; extra == 'fastmcp'

remem_auth-0.1.0/README.md

@@ -0,0 +1,197 @@
+# remem-auth
+
+Shared authentication library for remem Python services. Supports JWT verification (Azure Entra ID / Google) and static bearer tokens, with out-of-the-box integrations for FastAPI and FastMCP.
+
+## Installation
+
+```bash
+# Core library (JWT verification + static tokens)
+pip install remem-auth
+
+# With FastAPI integration
+pip install remem-auth[fastapi]
+
+# With FastMCP integration
+pip install remem-auth[fastmcp]
+
+# All optional dependencies
+pip install remem-auth[all]
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+### 1. Configure Environment Variables
+
+All settings are read from environment variables with the `REMEM_AUTH_` prefix:
+
+| Variable | Description | Default |
+|---|---|---|
+| `REMEM_AUTH_AZURE_TENANT_ID` | Azure Entra ID tenant ID | `""` |
+| `REMEM_AUTH_AZURE_CLIENT_ID` | Azure app registration client ID | `""` |
+| `REMEM_AUTH_GOOGLE_CLIENT_ID` | Google OAuth client ID | `""` |
+| `REMEM_AUTH_STATIC_TOKENS` | Comma-separated static bearer tokens | `""` |
+| `REMEM_AUTH_IDPS_JSON` | Advanced: full JSON array of IdP configs | `""` |
+| `REMEM_AUTH_VERIFY_EXP` | Whether to verify token expiration | `True` |
+| `REMEM_AUTH_VERIFY_AUD` | Whether to verify audience | `True` |
+
+**Example — Azure Entra ID:**
+
+```bash
+export REMEM_AUTH_AZURE_TENANT_ID="your-tenant-id"
+export REMEM_AUTH_AZURE_CLIENT_ID="your-client-id"
+```
+
+**Example — Static tokens (useful for dev/test):**
+
+```bash
+export REMEM_AUTH_STATIC_TOKENS="dev-token-1,dev-token-2"
+```
+
+**Example — Custom IdP via JSON:**
+
+```bash
+export REMEM_AUTH_IDPS_JSON='[{"name":"my-idp","issuer":"https://idp.example.com","jwks_uri":"https://idp.example.com/.well-known/jwks.json","audience":"my-app"}]'
+```
+
+### 2. FastAPI Integration
+
+```python
+from fastapi import Depends, FastAPI
+from remem.auth import AuthConfig, AuthenticatedUser, FastAPIAuth
+
+config = AuthConfig()  # reads from environment variables
+auth = FastAPIAuth(config)
+app = FastAPI()
+
+@app.get("/protected")
+def protected(user: AuthenticatedUser = Depends(auth)):
+    return {"subject": user.subject, "email": user.email}
+```
+
+Unauthenticated requests receive a `401 Unauthorized` response with a `WWW-Authenticate: Bearer` header.
+
+### 3. FastMCP Integration
+
+```python
+from fastmcp import FastMCP
+from remem.auth import AuthConfig, FastMCPAuthProvider
+
+config = AuthConfig()
+mcp = FastMCP("my-server", auth=FastMCPAuthProvider(config))
+
+@mcp.tool()
+def hello() -> str:
+    return "world"
+```
+
+FastMCPAuthProvider implements FastMCP's `TokenVerifier` interface and uses `asyncio.to_thread()` internally so the synchronous verifier doesn't block the event loop.
+
+### 4. Using the Core API Directly
+
+If you're not using either framework, you can call the verification engine directly:
+
+```python
+from remem.auth import AuthConfig, AuthVerifier, AuthenticationError
+
+config = AuthConfig()
+verifier = AuthVerifier(config)
+
+try:
+    user = verifier.verify_token("eyJhbGciOi...")
+    print(user.subject, user.email, user.auth_method)
+except AuthenticationError as e:
+    print(f"Authentication failed: {e}")
+```
+
+**Extracting tokens from request headers:**
+
+```python
+from remem.auth import extract_token
+
+# Works with any object that has a .headers attribute (Mapping[str, str])
+token = extract_token(request)
+```
+
+`extract_token` checks `Authorization: Bearer <token>` first, then falls back to the `api-key` header.
+
+## Core Concepts
+
+### Verification Flow
+
+`AuthVerifier.verify_token()` processes tokens in this order:
+
+1. **Auth not enabled** — returns an anonymous user (graceful degradation)
+2. **No token** — raises `AuthenticationError`
+3. **Matches a static token** — returns a static-token user (O(1) set lookup)
+4. **JWT** — peeks the issuer from an unverified decode, then routes to the matching IdP verifier
+
+### AuthenticatedUser
+
+The user object returned after successful authentication:
+
+```python
+class AuthenticatedUser(BaseModel):
+    subject: str                     # JWT "sub" claim
+    email: str | None                # extracted from email / preferred_username / upn
+    name: str | None                 # JWT "name" claim
+    auth_method: AuthMethod          # "jwt" | "static" | "none"
+    idp_name: str | None             # IdP name (e.g. "azure", "google")
+    claims: dict[str, Any]           # full JWT payload
+    token: str                       # raw token (excluded from serialization)
+```
+
+The `token` field is marked with `exclude=True` and `repr=False`, so it won't appear in `.model_dump()` output or `print()` — preventing accidental credential leaks.
+
+### Graceful Degradation
+
+When no IdPs or static tokens are configured, `auth_enabled` is `False` and all requests are allowed through with an anonymous user. This lets you omit auth configuration in development environments.
+
+## API Reference
+
+### Module Exports
+
+```python
+from remem.auth import (
+    AuthConfig,                # pydantic-settings configuration
+    AuthVerifier,              # core verification engine
+    AuthenticationError,       # verification failure exception
+    AuthenticatedUser,         # user model
+    AuthMethod,                # authentication method enum
+    IdpConfig,                 # identity provider config model
+    extract_token,             # extract token from request headers
+    create_auth_config_from_env,  # AuthConfig factory function
+    FastAPIAuth,               # FastAPI dependency (lazy import)
+    FastMCPAuthProvider,       # FastMCP auth provider (lazy import)
+)
+```
+
+`FastAPIAuth` and `FastMCPAuthProvider` are lazy-imported via `__getattr__` — their framework dependencies are only loaded when actually accessed.
+
+### IdpConfig Fields
+
+When using `REMEM_AUTH_IDPS_JSON` to define custom IdPs, each entry supports:
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `name` | `str` | Yes | — | IdP identifier |
+| `issuer` | `str` | Yes | — | JWT issuer (used for routing) |
+| `jwks_uri` | `str` | Yes | — | JWKS endpoint URL |
+| `audience` | `str \| None` | No | `None` | Expected audience |
+| `algorithms` | `list[str]` | No | `["RS256"]` | Allowed signing algorithms |
+
+## Development
+
+```bash
+# Create a virtualenv and install dev dependencies
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Lint
+ruff check src/ tests/
+```

remem_auth-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "remem-auth"
+version = "0.1.0"
+description = "Shared authentication library for remem Python services"
+requires-python = ">=3.11,<3.15"
+dependencies = [
+    "PyJWT[crypto]>=2.8,<3",
+    "pydantic>=2,<3",
+    "pydantic-settings>=2,<3",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.100",
+    "starlette>=0.27",
+]
+fastmcp = [
+    "fastmcp>=2.14.0",
+]
+all = [
+    "remem-auth[fastapi,fastmcp]",
+]
+dev = [
+    "remem-auth[all]",
+    "pytest==9.0.2",
+    "pytest-asyncio==1.3.0",
+    "httpx==0.28.1",
+    "cryptography==46.0.5",
+    "ruff==0.15.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/remem"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/remem", "pyproject.toml", "README.md"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

remem_auth-0.1.0/src/remem/auth/__init__.py

@@ -0,0 +1,33 @@
+"""remem-auth — Shared authentication library for remem Python services."""
+
+from ._config import AuthConfig, create_auth_config_from_env
+from ._models import AuthenticatedUser, AuthMethod, IdpConfig
+from ._token_extraction import extract_token
+from ._verifier import AuthenticationError, AuthVerifier
+
+__all__ = [
+    "AuthConfig",
+    "AuthenticatedUser",
+    "AuthenticationError",
+    "AuthMethod",
+    "AuthVerifier",
+    "FastAPIAuth",
+    "FastMCPAuthProvider",
+    "IdpConfig",
+    "create_auth_config_from_env",
+    "extract_token",
+]
+
+
+def __getattr__(name: str):
+    if name == "FastAPIAuth":
+        from ._fastapi import FastAPIAuth
+
+        return FastAPIAuth
+
+    if name == "FastMCPAuthProvider":
+        from ._fastmcp import FastMCPAuthProvider
+
+        return FastMCPAuthProvider
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

remem_auth-0.1.0/src/remem/auth/_config.py

@@ -0,0 +1,86 @@
+"""Configuration for remem-auth via environment variables."""
+
+import json
+
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+
+from ._models import IdpConfig
+
+
+class AuthConfig(BaseSettings):
+    """Auth configuration loaded from environment variables.
+
+    All env vars are prefixed with ``REMEM_AUTH_``.
+    """
+
+    model_config = {"env_prefix": "REMEM_AUTH_"}
+
+    # Azure Entra ID convenience fields
+    azure_tenant_id: str = ""
+    azure_client_id: str = ""
+
+    # Google convenience field
+    google_client_id: str = ""
+
+    # Advanced: full JSON array of IdpConfig dicts
+    idps_json: str = ""
+
+    # Comma-separated static bearer tokens
+    static_tokens: str = ""
+
+    # Verification flags
+    verify_exp: bool = True
+    verify_aud: bool = True
+
+    def get_idp_configs(self) -> list[IdpConfig]:
+        """Build the list of IdP configurations from settings."""
+        if self.idps_json:
+            try:
+                raw = json.loads(self.idps_json)
+                return [IdpConfig(**entry) for entry in raw]
+            except (json.JSONDecodeError, TypeError, ValidationError) as exc:
+                raise ValueError(f"Invalid REMEM_AUTH_IDPS_JSON: {exc}") from exc
+
+        configs: list[IdpConfig] = []
+
+        if self.azure_tenant_id and self.azure_client_id:
+            configs.append(
+                IdpConfig(
+                    name="azure",
+                    issuer=f"https://login.microsoftonline.com/{self.azure_tenant_id}/v2.0",
+                    jwks_uri=(
+                        f"https://login.microsoftonline.com/{self.azure_tenant_id}"
+                        "/discovery/v2.0/keys"
+                    ),
+                    audience=self.azure_client_id,
+                )
+            )
+
+        if self.google_client_id:
+            configs.append(
+                IdpConfig(
+                    name="google",
+                    issuer="https://accounts.google.com",
+                    jwks_uri="https://www.googleapis.com/oauth2/v3/certs",
+                    audience=self.google_client_id,
+                )
+            )
+
+        return configs
+
+    def get_static_token_set(self) -> set[str]:
+        """Parse comma-separated static tokens into a set."""
+        if not self.static_tokens:
+            return set()
+        return {t.strip() for t in self.static_tokens.split(",") if t.strip()}
+
+    @property
+    def auth_enabled(self) -> bool:
+        """True if any IdP or static token is configured."""
+        return bool(self.get_idp_configs() or self.get_static_token_set())
+
+
+def create_auth_config_from_env() -> AuthConfig:
+    """Factory that instantiates AuthConfig from environment variables."""
+    return AuthConfig()

remem_auth-0.1.0/src/remem/auth/_fastapi.py

@@ -0,0 +1,37 @@
+"""FastAPI integration — Depends()-compatible auth callable."""
+
+from fastapi import HTTPException, Request
+from starlette.status import HTTP_401_UNAUTHORIZED
+
+from ._config import AuthConfig
+from ._models import AuthenticatedUser
+from ._token_extraction import extract_token
+from ._verifier import AuthenticationError, AuthVerifier
+
+
+class FastAPIAuth:
+    """Callable dependency for FastAPI that verifies bearer tokens.
+
+    Usage::
+
+        auth = FastAPIAuth(config)
+        app = FastAPI()
+
+        @app.get("/protected")
+        def protected(user: AuthenticatedUser = Depends(auth)):
+            return {"subject": user.subject}
+    """
+
+    def __init__(self, config: AuthConfig):
+        self._verifier = AuthVerifier(config)
+
+    def __call__(self, request: Request) -> AuthenticatedUser:
+        token = extract_token(request)
+        try:
+            return self._verifier.verify_token(token)
+        except AuthenticationError as exc:
+            raise HTTPException(
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail=str(exc),
+                headers={"WWW-Authenticate": "Bearer"},
+            ) from exc

remem_auth-0.1.0/src/remem/auth/_fastmcp.py

@@ -0,0 +1,81 @@
+"""FastMCP integration — TokenVerifier-based auth provider."""
+
+import asyncio
+
+from ._config import AuthConfig
+from ._verifier import AuthenticationError, AuthVerifier
+
+try:
+    from fastmcp.server.auth import AccessToken, TokenVerifier
+
+    _HAS_FASTMCP = True
+except ImportError:  # pragma: no cover
+    _HAS_FASTMCP = False
+
+    class TokenVerifier:  # type: ignore[no-redef]
+        """Stub so the module is importable without fastmcp."""
+
+        def __init__(self, *args, **kwargs): ...
+
+    class AccessToken:  # type: ignore[no-redef]
+        pass
+
+
+class FastMCPAuthProvider(TokenVerifier):
+    """Auth provider for FastMCP servers.
+
+    Usage::
+
+        from remem.auth import AuthConfig, FastMCPAuthProvider
+
+        config = AuthConfig()
+        mcp = FastMCP("my-server", auth=FastMCPAuthProvider(config))
+    """
+
+    def __init__(self, config: AuthConfig):
+        super().__init__()
+        self._verifier = AuthVerifier(config)
+
+    async def verify_token(self, token: str) -> AccessToken | None:  # type: ignore[override]
+        if not self._verifier.auth_enabled:
+            return AccessToken(
+                token="",
+                client_id="anonymous",
+                scopes=[],
+                claims={},
+            )
+
+        if not token:
+            return None
+
+        try:
+            user = await asyncio.to_thread(self._verifier.verify_token, token)
+        except AuthenticationError:
+            return None
+
+        scopes = _extract_scopes(user.claims)
+        expires_at = user.claims.get("exp")
+
+        return AccessToken(
+            token=token,
+            client_id=user.subject,
+            scopes=scopes,
+            expires_at=int(expires_at) if expires_at is not None else None,
+            claims=user.claims,
+        )
+
+
+def _extract_scopes(claims: dict) -> list[str]:
+    """Extract scopes from JWT claims.
+
+    Supports ``scope`` (space-separated string) and ``scp`` (list).
+    """
+    scope = claims.get("scope")
+    if isinstance(scope, str):
+        return scope.split()
+
+    scp = claims.get("scp")
+    if isinstance(scp, list):
+        return [str(s) for s in scp]
+
+    return []

remem_auth-0.1.0/src/remem/auth/_models.py

@@ -0,0 +1,36 @@
+"""Data models for remem-auth."""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AuthMethod(str, Enum):
+    """How a user was authenticated."""
+
+    JWT = "jwt"
+    STATIC = "static"
+    NONE = "none"
+
+
+class IdpConfig(BaseModel):
+    """Configuration for a single identity provider."""
+
+    name: str
+    issuer: str
+    jwks_uri: str
+    audience: str | None = None
+    algorithms: list[str] = Field(default_factory=lambda: ["RS256"])
+
+
+class AuthenticatedUser(BaseModel):
+    """Represents a successfully authenticated user."""
+
+    subject: str
+    email: str | None = None
+    name: str | None = None
+    auth_method: AuthMethod
+    idp_name: str | None = None
+    claims: dict[str, Any] = Field(default_factory=dict)
+    token: str = Field(default="", exclude=True, repr=False)

remem_auth-0.1.0/src/remem/auth/_token_extraction.py

@@ -0,0 +1,43 @@
+"""Token extraction from HTTP request headers."""
+
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HasHeaders(Protocol):
+    """Any object that exposes a ``headers`` mapping (e.g. Starlette Request)."""
+
+    @property
+    def headers(self) -> Mapping[str, str]: ...
+
+
+def _get_header(headers: Mapping[str, str], *names: str) -> str:
+    """Return the first truthy header value found, or empty string."""
+    for name in names:
+        value = headers.get(name)
+        if value:
+            return value
+    return ""
+
+
+def extract_token(request: HasHeaders) -> str | None:
+    """Extract a bearer token from request headers.
+
+    Checks ``Authorization: Bearer <token>`` first, then falls back to
+    the ``api-key`` header.  Returns *None* if neither is present.
+
+    Both lower-case and title-case header names are tried so that plain
+    ``dict`` callers (outside Starlette's case-insensitive Headers) work.
+    """
+    headers = request.headers
+
+    auth_header = _get_header(headers, "authorization", "Authorization")
+    if auth_header.lower().startswith("bearer "):
+        return auth_header[7:].strip()
+
+    api_key = _get_header(headers, "api-key", "Api-Key")
+    if api_key:
+        return api_key.strip()
+
+    return None

remem_auth-0.1.0/src/remem/auth/_verifier.py

@@ -0,0 +1,131 @@
+"""Core token verification engine."""
+
+import jwt
+from jwt import PyJWKClient
+
+from ._config import AuthConfig
+from ._models import AuthMethod, AuthenticatedUser, IdpConfig
+
+
+class AuthenticationError(Exception):
+    """Raised when token verification fails."""
+
+
+class _IdpVerifier:
+    """Verifies JWTs for a single identity provider."""
+
+    def __init__(self, idp: IdpConfig, *, verify_exp: bool = True, verify_aud: bool = True):
+        self._idp = idp
+        self._jwks_client = PyJWKClient(idp.jwks_uri)
+        self._verify_exp = verify_exp
+        self._verify_aud = verify_aud
+
+    def verify(self, token: str) -> AuthenticatedUser:
+        signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+
+        has_audience = self._verify_aud and self._idp.audience
+        options: dict = {
+            "verify_exp": self._verify_exp,
+            "verify_aud": has_audience,
+        }
+
+        decode_kwargs: dict = {
+            "algorithms": self._idp.algorithms,
+            "issuer": self._idp.issuer,
+            "options": options,
+        }
+        if has_audience:
+            decode_kwargs["audience"] = self._idp.audience
+
+        payload = jwt.decode(token, signing_key.key, **decode_kwargs)
+        return _payload_to_user(payload, token=token, idp_name=self._idp.name)
+
+
+def _payload_to_user(
+    payload: dict, *, token: str, idp_name: str | None = None
+) -> AuthenticatedUser:
+    """Convert a JWT payload dict into an AuthenticatedUser."""
+    subject = payload.get("sub", "")
+    email = payload.get("email") or payload.get("preferred_username") or payload.get("upn")
+    name = payload.get("name")
+
+    return AuthenticatedUser(
+        subject=subject,
+        email=email,
+        name=name,
+        auth_method=AuthMethod.JWT,
+        idp_name=idp_name,
+        claims=payload,
+        token=token,
+    )
+
+
+class AuthVerifier:
+    """Main verification engine supporting multiple IdPs and static tokens."""
+
+    def __init__(self, config: AuthConfig):
+        self._config = config
+        self._static_tokens: set[str] = config.get_static_token_set()
+        self._issuer_to_verifier: dict[str, _IdpVerifier] = {}
+
+        for idp in config.get_idp_configs():
+            verifier = _IdpVerifier(
+                idp,
+                verify_exp=config.verify_exp,
+                verify_aud=config.verify_aud,
+            )
+            self._issuer_to_verifier[idp.issuer] = verifier
+
+    @property
+    def auth_enabled(self) -> bool:
+        return self._config.auth_enabled
+
+    def verify_token(self, token: str | None) -> AuthenticatedUser:
+        """Verify a token and return the authenticated user.
+
+        Flow:
+        1. If auth not enabled → anonymous user (graceful degradation)
+        2. If no token → raise AuthenticationError
+        3. If token matches a static token → static AuthenticatedUser
+        4. Peek issuer from unverified decode → route to IdP verifier
+        """
+        if not self.auth_enabled:
+            return AuthenticatedUser(
+                subject="anonymous",
+                auth_method=AuthMethod.NONE,
+                claims={},
+            )
+
+        if not token:
+            raise AuthenticationError("No token provided")
+
+        # Static token check — O(1) set lookup, cheapest path
+        if token in self._static_tokens:
+            return AuthenticatedUser(
+                subject="static-token-user",
+                auth_method=AuthMethod.STATIC,
+                claims={},
+                token=token,
+            )
+
+        # JWT verification — peek issuer then route
+        try:
+            unverified = jwt.decode(token, options={"verify_signature": False})
+        except jwt.DecodeError as exc:
+            raise AuthenticationError(f"Malformed token: {exc}") from exc
+
+        issuer = unverified.get("iss", "")
+        verifier = self._issuer_to_verifier.get(issuer)
+        if verifier is None:
+            raise AuthenticationError(f"Unknown issuer: {issuer!r}")
+
+        try:
+            return verifier.verify(token)
+        except jwt.ExpiredSignatureError as exc:
+            raise AuthenticationError(f"Token expired: {exc}") from exc
+        except jwt.InvalidAudienceError as exc:
+            raise AuthenticationError(f"Invalid audience: {exc}") from exc
+        except jwt.InvalidIssuerError as exc:
+            raise AuthenticationError(f"Invalid issuer: {exc}") from exc
+        except Exception as exc:
+            raise AuthenticationError(f"Token verification failed: {exc}") from exc