refactor: migrate from api-key auth to jwt

Author: martvaha

README.md

@@ -32,22 +32,34 @@ By default the project will create two directories in the root directory: `./con
 
 ### Authentication
 
-By default the API is unauthenticated. To require an API key, set `API_KEY` in the service environment (or `.env`):
+The API authenticates requests with short-lived JWTs minted by LibreChat (`Authorization: Bearer <token>`, EdDSA/Ed25519 by default, RS256 also supported). LibreChat signs tokens with a private key; this service verifies them with the matching public key.
+
+By default the API is unauthenticated — when no public key is configured, all requests are accepted (dev mode only; a warning is logged at startup). To enable auth:
+
+1. Generate a keypair:
+
+```bash
+openssl genpkey -algorithm ed25519 -out codeapi-private.pem
+openssl pkey -in codeapi-private.pem -pubout -out codeapi-public.pem
+awk 'NF {printf "%s\\n", $0}' codeapi-public.pem   # \n-escape a PEM for a one-line env value
+```
+
+2. Set the public key in the service environment (or `.env`):
 
 ```ini
-API_KEY=<your-secret-key>
+CODEAPI_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n"
+# or alternatively: CODEAPI_JWT_PUBLIC_KEY_BASE64=<base64-encoded PEM>
 ```
 
-When set, all `/v1` endpoints require a matching `x-api-key` header and return `401` otherwise (`/health` stays open). LibreChat sends this header automatically using its `LIBRECHAT_CODE_API_KEY` value, so the two must match.
+When set, all `/v1` endpoints require a valid Bearer token and return `401` otherwise (`/health` stays open). Optional overrides (defaults match LibreChat): `CODEAPI_JWT_ISSUER=librechat`, `CODEAPI_JWT_AUDIENCE=codeapi`, `CODEAPI_JWT_ALGORITHMS=["EdDSA","RS256"]`, `CODEAPI_JWT_LEEWAY=30`.
 
 ### Configuring LibreChat
 
-LibreChat is configured to use the code interpreter API by default.
-
 To configure LibreChat to use the local code interpreter, set the following environment variables in LibreChat:
 
 ```ini
-LIBRECHAT_CODE_API_KEY=<any-value-here> # must match the service's API_KEY if one is configured
+CODEAPI_JWT_ENABLED=true # or CODEAPI_AUTH_PROVIDER=librechat-jwt
+CODEAPI_JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" # \n-escaped private PEM; _BASE64 and _JWK_JSON variants also exist
 LIBRECHAT_CODE_BASEURL=http(s)://host:port/v1/librechat # for local testing use to point to host IP http://host.docker.internal:8000/v1/librechat
 ```
 

app/api/auth.py

@@ -1,19 +1,91 @@
-import secrets
-from typing import Optional
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any, Dict, Optional
 
-from fastapi import Header, HTTPException
+import jwt
+from cryptography.hazmat.primitives import serialization
+from fastapi import Header, HTTPException, Request
+from loguru import logger
 
 from app.shared.config import get_settings
 
 
-async def verify_api_key(x_api_key: Optional[str] = Header(None)) -> None:
-    """Require a matching x-api-key header when an API key is configured.
+@dataclass(frozen=True)
+class AuthContext:
+    """Verified identity from a LibreChat code-API JWT."""
 
-    Auth is disabled when ``API_KEY`` is unset. Settings are read at request
-    time so the key can be toggled in tests.
+    enabled: bool  # False when auth is unconfigured (open mode)
+    sub: Optional[str] = None  # LibreChat user id (trustworthy identity)
+    tenant_id: Optional[str] = None
+    role: Optional[str] = None
+    claims: Dict[str, Any] = field(default_factory=dict)
+
+
+@lru_cache(maxsize=4)
+def _load_public_key(pem: str):
+    """Parse a PEM public key; cached on the PEM string so settings swaps in tests just work."""
+    return serialization.load_pem_public_key(pem.encode("utf-8"))
+
+
+def _unauthorized() -> HTTPException:
+    return HTTPException(status_code=401, detail="Unauthorized", headers={"WWW-Authenticate": "Bearer"})
+
+
+async def verify_jwt(request: Request, authorization: Optional[str] = Header(None)) -> AuthContext:
+    """Verify the LibreChat-minted Bearer JWT on the request.
+
+    Auth is disabled when no public key is configured. Settings are read at
+    request time so the key can be toggled in tests. The verified claims are
+    attached to ``request.state.auth`` for route handlers.
     """
     settings = get_settings()
-    if settings.API_KEY is None:
-        return
-    if x_api_key is None or not secrets.compare_digest(x_api_key, settings.API_KEY):
-        raise HTTPException(status_code=401, detail="Unauthorized")
+    pem = settings.JWT_PUBLIC_KEY_PEM
+    if pem is None:
+        context = AuthContext(enabled=False)
+        request.state.auth = context
+        return context
+
+    if authorization is None:
+        raise _unauthorized()
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not token.strip():
+        raise _unauthorized()
+    token = token.strip()
+
+    try:
+        key = _load_public_key(pem)
+    except ValueError:
+        logger.error("CODEAPI_JWT_PUBLIC_KEY is not a valid PEM public key")
+        raise HTTPException(status_code=500, detail="Server authentication misconfigured")
+
+    try:
+        kid = jwt.get_unverified_header(token).get("kid")
+        logger.debug(f"Verifying code-API token with kid={kid}")
+    except jwt.InvalidTokenError:
+        raise _unauthorized()
+
+    try:
+        payload = jwt.decode(
+            token,
+            key,
+            algorithms=settings.CODEAPI_JWT_ALGORITHMS,
+            audience=settings.CODEAPI_JWT_AUDIENCE,
+            issuer=settings.CODEAPI_JWT_ISSUER,
+            leeway=settings.CODEAPI_JWT_LEEWAY,
+            options={"require": ["exp", "iat", "sub"]},
+        )
+    except (jwt.InvalidTokenError, TypeError, ValueError) as exc:
+        # PyJWT raises TypeError/ValueError (not InvalidTokenError) when the
+        # token's alg does not match the configured key type
+        logger.warning(f"Rejected code-API token: {exc}")
+        raise _unauthorized()
+
+    context = AuthContext(
+        enabled=True,
+        sub=payload["sub"],
+        tenant_id=payload.get("tenant_id"),
+        role=payload.get("role"),
+        claims=payload,
+    )
+    request.state.auth = context
+    return context

app/main.py

@@ -6,7 +6,7 @@
 from fastapi.responses import JSONResponse
 from loguru import logger
 
-from .api.auth import verify_api_key
+from .api.auth import verify_jwt
 from .api.base import router as base_router
 from .api.librechat import router as librechat_router
 from .api.container import router as docker_router
@@ -24,6 +24,9 @@ async def lifespan(app: FastAPI):
     setup_logging()
     logger.info("Starting application")
 
+    if get_settings().JWT_PUBLIC_KEY_PEM is None:
+        logger.warning("CODEAPI_JWT_PUBLIC_KEY not set — API is UNAUTHENTICATED (dev mode only)")
+
     # Initialize database
     await db_manager.initialize()
 
@@ -65,10 +68,10 @@ async def lifespan(app: FastAPI):
 # Add logging middleware
 app.add_middleware(RequestLoggingMiddleware)
 
-# Include routers (all /v1 routes require x-api-key when API_KEY is configured)
-app.include_router(base_router, dependencies=[Depends(verify_api_key)])
-app.include_router(librechat_router, dependencies=[Depends(verify_api_key)])
-app.include_router(docker_router, dependencies=[Depends(verify_api_key)])
+# Include routers (all /v1 routes require a LibreChat JWT when a public key is configured)
+app.include_router(base_router, dependencies=[Depends(verify_jwt)])
+app.include_router(librechat_router, dependencies=[Depends(verify_jwt)])
+app.include_router(docker_router, dependencies=[Depends(verify_jwt)])
 
 
 @app.exception_handler(HTTPException)

app/shared/config.py

@@ -1,8 +1,10 @@
+import base64
+
 from loguru import logger
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from functools import lru_cache
 from pathlib import Path
-from typing import Dict, Optional, Set
+from typing import Dict, List, Optional, Set
 
 
 class Settings(BaseSettings):
@@ -26,7 +28,23 @@ def CONFIG_PATH_ABS(self) -> Path:
     # API settings
     PORT: int = 8000  # Port exposed from the container
     API_PREFIX: str = "/v1"  # API prefix
-    API_KEY: Optional[str] = None  # When set, requests must send a matching x-api-key header
+
+    # JWT auth (LibreChat code-API tokens); auth is disabled when no public key is set
+    CODEAPI_JWT_PUBLIC_KEY: Optional[str] = None  # PEM, "\n"-escaped newlines allowed
+    CODEAPI_JWT_PUBLIC_KEY_BASE64: Optional[str] = None  # base64-encoded PEM alternative
+    CODEAPI_JWT_ISSUER: str = "librechat"
+    CODEAPI_JWT_AUDIENCE: str = "codeapi"
+    CODEAPI_JWT_ALGORITHMS: List[str] = ["EdDSA", "RS256"]
+    CODEAPI_JWT_LEEWAY: int = 30  # seconds of clock-skew tolerance
+
+    @property
+    def JWT_PUBLIC_KEY_PEM(self) -> Optional[str]:
+        """Resolved public key PEM, or None when JWT auth is unconfigured."""
+        if self.CODEAPI_JWT_PUBLIC_KEY:
+            return self.CODEAPI_JWT_PUBLIC_KEY.replace("\\n", "\n").strip()
+        if self.CODEAPI_JWT_PUBLIC_KEY_BASE64:
+            return base64.b64decode(self.CODEAPI_JWT_PUBLIC_KEY_BASE64).decode("utf-8").strip()
+        return None
 
     # Code execution sandbox settings
     SANDBOX_MAX_EXECUTION_TIME: int = 300  # Docker container execution time limit in seconds

pyproject.toml

@@ -17,6 +17,7 @@ dependencies = [
     "python-magic>=0.4.27",
     "loguru>=0.7.3",
     "nanoid>=2.0.0",
+    "pyjwt[crypto]>=2.10.1",
 ]
 
 [project.optional-dependencies]