lime-mcp-server-sdk 0.2.0__py3-none-any.whl

lime_mcp_server/__init__.py

@@ -0,0 +1,28 @@
+"""LIME MCP resource server SDK — JWT verification via Core JWKS."""
+
+from __future__ import annotations
+
+from lime_mcp_server._cache import JwksCache
+from lime_mcp_server._config import LimeConfig
+from lime_mcp_server._envelope import FORBIDDEN_MCP_CLAIMS, unwrap_lime_data
+from lime_mcp_server._jwt import verify_mcp_access_token
+from lime_mcp_server._types import TokenValidationResult
+from lime_mcp_server._verifier import TokenVerifier
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "FORBIDDEN_MCP_CLAIMS",
+    "JwksCache",
+    "LimeConfig",
+    "TokenValidationResult",
+    "TokenVerifier",
+    "jwks_cache_ttl_seconds",
+    "unwrap_lime_data",
+    "verify_mcp_access_token",
+]
+
+
+def jwks_cache_ttl_seconds() -> int:
+    """Default JWKS cache TTL from environment (compatibility helper)."""
+    return LimeConfig().cache_ttl

lime_mcp_server/_cache.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from lime_mcp_server._config import LimeConfig
+from lime_mcp_server._envelope import JWKS_PATH, METADATA_PATH, unwrap_lime_data
+
+logger = logging.getLogger("lime.mcp_server")
+
+
+@dataclass(frozen=True, slots=True)
+class JwksSnapshot:
+    keys: list[dict[str, Any]]
+    issuer: str
+    fetched_at: float
+
+
+class JwksCache:
+    """Thread-safe JWKS + OAuth metadata cache with stale fallback."""
+
+    def __init__(
+        self,
+        config: LimeConfig,
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._snapshot: JwksSnapshot | None = None
+        self._last_forced_refresh_at: float = 0.0
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(
+            timeout=config.http_timeout,
+            trust_env=False,
+            headers={
+                "Accept": "application/json",
+                "User-Agent": config.user_agent,
+            },
+        )
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def warm(self) -> None:
+        """Prefetch metadata and JWKS (non-fatal on failure)."""
+        try:
+            self.refresh(force=True)
+        except Exception:
+            logger.warning("JWKS cache warmup failed", exc_info=True)
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._snapshot = None
+
+    def refresh(self, *, force: bool = False) -> None:
+        """Refresh metadata + JWKS from LIME."""
+        now = time.monotonic()
+        with self._lock:
+            if force:
+                elapsed = now - self._last_forced_refresh_at
+                if elapsed < self._config.min_refresh_seconds:
+                    if self._snapshot is not None:
+                        return
+                self._last_forced_refresh_at = now
+            self._snapshot = self._fetch_snapshot()
+
+    def get_jwks(self, kid: str | None) -> tuple[list[dict[str, Any]], str]:
+        """Return JWKS keys and issuer; refresh on TTL expiry or kid mismatch."""
+        snapshot = self._current_snapshot()
+        if snapshot is None or self._is_expired(snapshot):
+            try:
+                self.refresh(force=False)
+            except Exception as exc:
+                if snapshot is not None:
+                    logger.warning("JWKS refresh failed, using stale cache: %s", exc)
+                    return snapshot.keys, snapshot.issuer
+                raise
+            snapshot = self._current_snapshot()
+            if snapshot is None:
+                raise RuntimeError("JWKS cache unavailable after refresh")
+
+        if kid is not None and not any(key.get("kid") == kid for key in snapshot.keys):
+            try:
+                self.refresh(force=True)
+            except Exception as exc:
+                logger.warning("JWKS kid-mismatch refresh failed: %s", exc)
+                if not any(key.get("kid") == kid for key in snapshot.keys):
+                    raise
+            snapshot = self._current_snapshot()
+            if snapshot is None:
+                raise RuntimeError("JWKS cache unavailable after kid refresh")
+
+        return snapshot.keys, snapshot.issuer
+
+    def _current_snapshot(self) -> JwksSnapshot | None:
+        with self._lock:
+            return self._snapshot
+
+    def _is_expired(self, snapshot: JwksSnapshot) -> bool:
+        return (time.monotonic() - snapshot.fetched_at) >= self._config.cache_ttl
+
+    def _fetch_snapshot(self) -> JwksSnapshot:
+        metadata = self._fetch_metadata()
+        issuer = str(metadata.get("issuer", "")).strip()
+        if not issuer:
+            raise ValueError("metadata missing issuer")
+        jwks_uri = str(metadata.get("jwks_uri", ""))
+        keys = self._fetch_jwks(jwks_uri)
+        return JwksSnapshot(keys=keys, issuer=issuer, fetched_at=time.monotonic())
+
+    def _fetch_metadata(self) -> dict[str, Any]:
+        response = self._client.get(f"{self._config.base_url}{METADATA_PATH}")
+        if response.status_code != 200:
+            raise RuntimeError(f"oauth metadata HTTP {response.status_code}")
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise ValueError("metadata response must be JSON object") from exc
+        if not isinstance(body, dict):
+            raise ValueError("metadata response must be JSON object")
+        return unwrap_lime_data(body)
+
+    def _fetch_jwks(self, jwks_uri: str) -> list[dict[str, Any]]:
+        base = self._config.base_url
+        if jwks_uri.startswith(base):
+            path = jwks_uri[len(base) :]
+        elif jwks_uri.startswith("http"):
+            raise ValueError("cross-origin jwks_uri fetch not supported")
+        elif jwks_uri:
+            path = jwks_uri
+        else:
+            path = JWKS_PATH
+
+        response = self._client.get(f"{base}{path}")
+        if response.status_code != 200:
+            raise RuntimeError(f"jwks HTTP {response.status_code}")
+        try:
+            body = response.json()
+        except ValueError as exc:
+            raise ValueError("jwks response must be JSON object") from exc
+        if not isinstance(body, dict):
+            raise ValueError("jwks response must be JSON object")
+        data = unwrap_lime_data(body)
+        keys = data.get("keys")
+        if not isinstance(keys, list) or not keys:
+            raise ValueError("jwks missing keys")
+        return keys

lime_mcp_server/_config.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _env_int(name: str, default: str) -> int:
+    return int(os.environ.get(name, default))
+
+
+@dataclass(frozen=True, slots=True)
+class LimeConfig:
+    """Configuration for MCP JWT verification against LIME Core JWKS."""
+
+    base_url: str = field(
+        default_factory=lambda: os.environ.get("LIME_BASE_URL", "https://lime.pics").rstrip("/"),
+    )
+    audience: str = field(
+        default_factory=lambda: os.environ.get("LIME_OAUTH_AUDIENCE", "mcp"),
+    )
+    cache_ttl: int = field(
+        default_factory=lambda: _env_int("LIME_JWKS_CACHE_TTL_SECONDS", "3600"),
+    )
+    leeway_seconds: int = field(
+        default_factory=lambda: _env_int("LIME_JWT_VERIFY_LEEWAY_SECONDS", "120"),
+    )
+    min_refresh_seconds: int = field(
+        default_factory=lambda: _env_int("LIME_JWKS_MIN_REFRESH_SECONDS", "60"),
+    )
+    allowed_algorithms: tuple[str, ...] = ("RS256",)
+    user_agent: str = field(
+        default_factory=lambda: os.environ.get("LIME_VERIFY_USER_AGENT", "curl/8.5.0"),
+    )
+    http_timeout: float = 30.0

lime_mcp_server/_envelope.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+METADATA_PATH = "/api/v1/modules/oauth/.well-known/oauth-authorization-server"
+JWKS_PATH = "/api/v1/core/.well-known/jwks.json"
+
+FORBIDDEN_MCP_CLAIMS = frozenset({"user_id", "passport_version", "request_id"})
+
+
+def unwrap_lime_data(body: dict[str, Any]) -> dict[str, Any]:
+    """Unwrap LIME API envelope ``{ ok, data }``."""
+    if not body.get("ok"):
+        raise ValueError("LIME envelope not ok")
+    data = body.get("data")
+    if not isinstance(data, dict):
+        raise ValueError("LIME envelope missing data object")
+    return data

lime_mcp_server/_jwt.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+import jwt
+from jwt.algorithms import RSAAlgorithm
+
+from lime_mcp_server._envelope import FORBIDDEN_MCP_CLAIMS
+
+
+def verify_mcp_access_token(
+    token: str,
+    *,
+    issuer: str,
+    audience: str,
+    jwks_keys: list[dict[str, Any]],
+    leeway_seconds: int = 120,
+    allowed_algorithms: tuple[str, ...] = ("RS256",),
+) -> dict[str, Any]:
+    """Verify RS256 MCP access token against pre-fetched JWKS keys."""
+    header = jwt.get_unverified_header(token)
+    kid = header.get("kid")
+    matching = [key for key in jwks_keys if key.get("kid") == kid]
+    if not matching:
+        raise jwt.InvalidTokenError(f"no jwks key for kid={kid!r}")
+    public_key = cast(Any, RSAAlgorithm.from_jwk(matching[0]))
+    claims = jwt.decode(
+        token,
+        public_key,
+        algorithms=list(allowed_algorithms),
+        issuer=issuer,
+        audience=audience,
+        leeway=leeway_seconds,
+    )
+    for forbidden in FORBIDDEN_MCP_CLAIMS:
+        if forbidden in claims:
+            raise jwt.InvalidTokenError(f"forbidden claim: {forbidden}")
+    sub = claims.get("sub")
+    if not isinstance(sub, str) or not sub.strip():
+        raise jwt.InvalidTokenError("missing sub claim")
+    return claims

lime_mcp_server/_types.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class TokenValidationResult:
+    """Structured outcome of MCP JWT verification."""
+
+    is_valid: bool
+    claims: dict[str, Any] | None = None
+    error: str | None = None
+
+    @property
+    def agent_id(self) -> str | None:
+        """Agent UUID from ``sub`` claim (MCP OAuth has no separate ``agent_id`` claim)."""
+        if self.is_valid and self.claims:
+            sub = self.claims.get("sub")
+            if isinstance(sub, str) and sub.strip():
+                return sub
+        return None

lime_mcp_server/_verifier.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Any
+
+import jwt
+
+from lime_mcp_server._cache import JwksCache
+from lime_mcp_server._config import LimeConfig
+from lime_mcp_server._jwt import verify_mcp_access_token
+from lime_mcp_server._types import TokenValidationResult
+
+
+class TokenVerifier:
+    """Verify LIME-issued MCP JWTs for external resource servers."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        audience: str | None = None,
+        cache_ttl: int | None = None,
+        leeway_seconds: int | None = None,
+        min_refresh_seconds: int | None = None,
+        allowed_algorithms: tuple[str, ...] | None = None,
+        config: LimeConfig | None = None,
+        cache: JwksCache | None = None,
+    ) -> None:
+        defaults = config or LimeConfig()
+        self._config = LimeConfig(
+            base_url=(base_url or defaults.base_url).rstrip("/"),
+            audience=audience or defaults.audience,
+            cache_ttl=cache_ttl if cache_ttl is not None else defaults.cache_ttl,
+            leeway_seconds=(
+                leeway_seconds if leeway_seconds is not None else defaults.leeway_seconds
+            ),
+            min_refresh_seconds=(
+                min_refresh_seconds
+                if min_refresh_seconds is not None
+                else defaults.min_refresh_seconds
+            ),
+            allowed_algorithms=allowed_algorithms or defaults.allowed_algorithms,
+            user_agent=defaults.user_agent,
+            http_timeout=defaults.http_timeout,
+        )
+        self._cache = cache or JwksCache(self._config)
+        self._cache.warm()
+
+    @property
+    def config(self) -> LimeConfig:
+        return self._config
+
+    def verify(self, token: str) -> TokenValidationResult:
+        """Verify a Bearer MCP JWT and return a structured result."""
+        try:
+            kid = self._get_kid(token)
+            jwks_keys, issuer = self._cache.get_jwks(kid)
+            claims = verify_mcp_access_token(
+                token,
+                issuer=issuer,
+                audience=self._config.audience,
+                jwks_keys=jwks_keys,
+                leeway_seconds=self._config.leeway_seconds,
+                allowed_algorithms=self._config.allowed_algorithms,
+            )
+            return TokenValidationResult(is_valid=True, claims=claims, error=None)
+        except jwt.ExpiredSignatureError:
+            return TokenValidationResult(is_valid=False, error="Token expired")
+        except jwt.InvalidIssuerError:
+            return TokenValidationResult(is_valid=False, error="Invalid issuer")
+        except jwt.InvalidAudienceError:
+            return TokenValidationResult(is_valid=False, error="Invalid audience")
+        except jwt.InvalidTokenError as exc:
+            return TokenValidationResult(is_valid=False, error=f"Invalid token: {exc}")
+        except Exception as exc:
+            return TokenValidationResult(is_valid=False, error=f"Verification error: {exc}")
+
+    def refresh_cache(self) -> None:
+        self._cache.refresh(force=True)
+
+    def invalidate_cache(self) -> None:
+        self._cache.invalidate()
+
+    @staticmethod
+    def _get_kid(token: str) -> str | None:
+        try:
+            header = jwt.get_unverified_header(token)
+            kid = header.get("kid")
+            return str(kid) if kid is not None else None
+        except Exception:
+            return None
+
+    def close(self) -> None:
+        self._cache.close()
+
+    def __enter__(self) -> TokenVerifier:
+        return self
+
+    def __exit__(self, *_args: Any) -> None:
+        self.close()

lime_mcp_server_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: lime-mcp-server-sdk
+Version: 0.2.0
+Summary: JWT verification for LIME MCP resource servers
+Project-URL: Homepage, https://github.com/Mawyxx/lime-mcp-server-sdk
+Project-URL: Repository, https://github.com/Mawyxx/lime-mcp-server-sdk
+Author: Mawyxx
+License-Expression: MIT
+License-File: LICENSE
+Keywords: jwt,lime,mcp,oauth,resource-server
+Classifier: Development Status :: 4 - Beta
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography<45,>=42.0
+Requires-Dist: httpx<0.28,>=0.27
+Requires-Dist: pyjwt<3,>=2.8
+Provides-Extra: dev
+Requires-Dist: mypy<2.0,>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: respx<0.22,>=0.21; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lime-mcp-server-sdk
+
+JWT verification for **LIME MCP resource servers** ([ADR 0081](https://github.com/Mawyxx/LIME)).
+
+Install:
+
+```bash
+pip install lime-mcp-server-sdk
+```
+
+## Quick start
+
+```python
+from lime_mcp_server import TokenVerifier
+
+verifier = TokenVerifier()  # defaults: https://lime.pics, aud=mcp
+result = verifier.verify(bearer_token)
+if result.is_valid:
+    agent_uuid = result.agent_id  # alias for claims["sub"]
+```
+
+MCP OAuth JWT identity is claim **`sub`** (UUID). There is no separate `agent_id` claim.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LIME_BASE_URL` | `https://lime.pics` | LIME origin for OAuth metadata + JWKS |
+| `LIME_OAUTH_AUDIENCE` | `mcp` | Expected JWT `aud` |
+| `LIME_JWKS_CACHE_TTL_SECONDS` | `3600` | Metadata + JWKS cache TTL |
+| `LIME_JWT_VERIFY_LEEWAY_SECONDS` | `120` | Clock skew leeway |
+| `LIME_JWKS_MIN_REFRESH_SECONDS` | `60` | Min interval between forced JWKS refresh |
+
+## Development
+
+Monorepo workspace: `sdk/lime-mcp-server-sdk/` (gitignored). Standalone repo: [github.com/Mawyxx/lime-mcp-server-sdk](https://github.com/Mawyxx/lime-mcp-server-sdk).
+
+```bash
+cd sdk/lime-mcp-server-sdk
+pip install -e ".[dev]"
+ruff check src tests
+mypy src/lime_mcp_server
+pytest --cov=lime_mcp_server --cov-fail-under=100
+```
+
+Live integration (optional):
+
+```bash
+LIME_MCP_SERVER_INTEGRATION=1 LIME_AGENT_TOKEN=at_... pytest tests/integration/ -v
+```
+
+## Publish (standalone repo)
+
+From monorepo workspace (after local QA):
+
+```bash
+cd sdk/lime-mcp-server-sdk
+git push -u origin main
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+GitHub Actions on tag `v*` publishes to PyPI. One-time setup:
+
+1. Create project `lime-mcp-server-sdk` on [pypi.org](https://pypi.org/manage/projects/)
+2. PyPI → **Publishing** → **Add a new pending publisher**:
+   - Owner: `Mawyxx`, repo: `lime-mcp-server-sdk`, workflow: `publish.yml`, environment: `pypi`
+3. GitHub repo → **Settings → Environments** → create **`pypi`**
+4. Push tag: `git push origin v0.2.0` (or re-tag and force-push)
+
+Until PyPI is live, install from GitHub:
+
+```bash
+pip install "lime-mcp-server-sdk @ git+https://github.com/Mawyxx/lime-mcp-server-sdk.git@v0.2.0"
+```
+
+## Changelog
+
+### 0.2.0
+
+- Remove framework adapters (`LimeMcpTokenVerifier`, `[mcp]` extra). Core-only wheel.
+
+### 0.1.0
+
+- Initial release: `TokenVerifier`, `TokenValidationResult`, JWKS cache.

lime_mcp_server_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lime_mcp_server/__init__.py,sha256=heAu1DPT4eTWFHvHVhrpSVibre-WPHi-ArLDCrB5F2k,826
+lime_mcp_server/_cache.py,sha256=gWusqHrEldB99DctfzuKJQ17I9gfQA9JSXqihLO-HxE,5596
+lime_mcp_server/_config.py,sha256=SfLSQXuWn3Eg1E73ySk9_IhA_6i6hIijykQg--tmlnc,1122
+lime_mcp_server/_envelope.py,sha256=ahXMnqZbkiSWU-XELFQ7XrN-ylBH63wWN9SRxTR4XbY,603
+lime_mcp_server/_jwt.py,sha256=_VR0DP-YEDBMi0qdRjlTEVOffF7XA9-9VTjk3yh6zZ8,1269
+lime_mcp_server/_types.py,sha256=XLgvwtTvBe4DUOBkIZM3YLe1B8yiTxqoqAES-IpSa1c,632
+lime_mcp_server/_verifier.py,sha256=tuhzKl3KncSbGsPVHbOu8VtydwKD-RzyVbNhmcyGS2k,3603
+lime_mcp_server/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lime_mcp_server_sdk-0.2.0.dist-info/METADATA,sha256=bFb7Fa2LzZ0kc4gsvLp6ooVfn9TzOqDYnSrPKB3etpc,3637
+lime_mcp_server_sdk-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+lime_mcp_server_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=c4XnKeH8FnU_zj8Hk7EZn-q2TVtygTdCBwF8im5NIhc,1063
+lime_mcp_server_sdk-0.2.0.dist-info/RECORD,,

lime_mcp_server_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

lime_mcp_server_sdk-0.2.0.dist-info/licenses/LICENSE

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