shellui-django 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. shellui_django-0.1.0/.gitignore +7 -0
  2. shellui_django-0.1.0/CHANGELOG.md +34 -0
  3. shellui_django-0.1.0/LICENSE +21 -0
  4. shellui_django-0.1.0/PKG-INFO +65 -0
  5. shellui_django-0.1.0/README.md +49 -0
  6. shellui_django-0.1.0/SECURITY.md +19 -0
  7. shellui_django-0.1.0/pyproject.toml +65 -0
  8. shellui_django-0.1.0/src/shellui_django/__init__.py +3 -0
  9. shellui_django-0.1.0/src/shellui_django/mcp/__init__.py +27 -0
  10. shellui_django-0.1.0/src/shellui_django/mcp/decorators.py +35 -0
  11. shellui_django-0.1.0/src/shellui_django/mcp/identity_jwks.py +109 -0
  12. shellui_django-0.1.0/src/shellui_django/mcp/internal.py +264 -0
  13. shellui_django-0.1.0/src/shellui_django/mcp/masking.py +78 -0
  14. shellui_django-0.1.0/src/shellui_django/mcp/openapi_mcp.py +135 -0
  15. shellui_django-0.1.0/src/shellui_django/mcp/openapi_tools.py +120 -0
  16. shellui_django-0.1.0/src/shellui_django/mcp/rate_limit.py +26 -0
  17. shellui_django-0.1.0/src/shellui_django/mcp/resources.py +53 -0
  18. shellui_django-0.1.0/src/shellui_django/mcp/routing.py +90 -0
  19. shellui_django-0.1.0/src/shellui_django/mcp/server.py +280 -0
  20. shellui_django-0.1.0/src/shellui_django/mcp/tests/__init__.py +0 -0
  21. shellui_django-0.1.0/src/shellui_django/mcp/tests/mcp_routing_urlconf.py +33 -0
  22. shellui_django-0.1.0/src/shellui_django/mcp/tests/rs256_helpers.py +74 -0
  23. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_internal_revocation.py +109 -0
  24. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_masking.py +45 -0
  25. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_openapi_tools.py +25 -0
  26. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_package.py +26 -0
  27. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_resources.py +24 -0
  28. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_routing.py +44 -0
  29. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_server_routing.py +157 -0
  30. shellui_django-0.1.0/src/shellui_django/mcp/tests/test_write_gate_mcp.py +62 -0
  31. shellui_django-0.1.0/src/shellui_django/mcp/write_gate.py +53 -0
  32. shellui_django-0.1.0/src/shellui_django/testing/__init__.py +7 -0
@@ -0,0 +1,7 @@
1
+ .venv/
2
+ dist/
3
+ __pycache__/
4
+ *.py[cod]
5
+ *.egg-info/
6
+ .ruff_cache/
7
+ .pytest_cache/
@@ -0,0 +1,34 @@
1
+ # Change Log
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/)
6
+ and this project adheres to [Semantic Versioning](https://semver.org/).
7
+ Releases are tagged `vX.Y.Z` and published to PyPI as `shellui-django`.
8
+ Breaking changes bump the major version (minor while below 1.0.0), so services can pin a compatible range.
9
+
10
+ <!---
11
+ ## [Unreleased] - yyyy-mm-dd
12
+
13
+ ### ✨ Feature – for new features
14
+ ### πŸ›  Improvements – for general improvements
15
+ ### 🚨 Changed – for changes in existing functionality
16
+ ### ⚠️ Deprecated – for soon-to-be removed features
17
+ ### πŸ“š Documentation – for documentation update
18
+ ### πŸ—‘ Removed – for removed features
19
+ ### πŸ› Bug Fixes – for any bug fixes
20
+ ### πŸ”’ Security – in case of vulnerabilities
21
+ ### πŸ— Chore – for tidying code
22
+
23
+ See for sample https://raw.githubusercontent.com/favoloso/conventional-changelog-emoji/master/CHANGELOG.md
24
+ -->
25
+
26
+ ## [0.1.0] - 2026-11-02
27
+
28
+ ### ✨ Feature
29
+
30
+ - First release of `shellui-django` with the shared MCP module (OpenAPI tools, write gate, revocation helpers, streamable HTTP server).
31
+
32
+ ### πŸ“š Documentation
33
+
34
+ - Add package README and `docs/` guides for the MCP and testing modules.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SΓ©bastien Barbier
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,65 @@
1
+ Metadata-Version: 2.5
2
+ Name: shellui-django
3
+ Version: 0.1.0
4
+ Summary: Shared Django libraries for Shellui services
5
+ Author: SΓ©bastien Barbier
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.14
9
+ Requires-Dist: django==6.0.8
10
+ Requires-Dist: djangorestframework==3.18.2
11
+ Provides-Extra: mcp
12
+ Requires-Dist: cryptography>=50.0.0; extra == 'mcp'
13
+ Requires-Dist: djangorestframework-simplejwt==5.5.1; extra == 'mcp'
14
+ Requires-Dist: pyjwt>=2.14.0; extra == 'mcp'
15
+ Description-Content-Type: text/markdown
16
+
17
+ # shellui-django
18
+
19
+ Shared Django libraries for [Shellui](https://shellui.com) backend services: identity, storage, hosting, email, and saas.
20
+
21
+ ## Principles
22
+
23
+ - Only code duplicated in two or more services belongs here.
24
+ - Optional modules. Install what you need via extras (for example `[mcp]`).
25
+ - No shared Django models or migrations for now.
26
+ - [Semantic versioning](https://semver.org/). Services pin a compatible version range.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install shellui-django
32
+ pip install shellui-django[mcp] # MCP server helpers
33
+ ```
34
+
35
+ Requires Python 3.14+, Django, and DRF. The `[mcp]` extra adds PyJWT, cryptography, and SimpleJWT for MCP auth and signed internal calls.
36
+
37
+ ## Modules
38
+
39
+ | Module | Description |
40
+ |--------|-------------|
41
+ | [`shellui_django.mcp`](docs/mcp.md) | Turn a DRF OpenAPI schema into a secure multi-tenant MCP HTTP server. |
42
+ | [`shellui_django.testing`](docs/testing.md) | Shared test helpers (planned). |
43
+
44
+ ## Contributing and releases
45
+
46
+ 1. Open pull requests against `develop`.
47
+ 2. Merge `develop` into `main` when ready to release.
48
+ 3. Tag `vX.Y.Z` on `main`. GitHub Actions publishes `shellui-django` to PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/).
49
+
50
+ Run checks locally:
51
+
52
+ ```bash
53
+ uv sync --all-groups
54
+ DJANGO_SETTINGS_MODULE=tests.django_settings uv run python -m django test shellui_django.mcp.tests --verbosity=1
55
+ uv run ruff check src
56
+ uv build
57
+ ```
58
+
59
+ ## Security
60
+
61
+ Report vulnerabilities as described in [SECURITY.md](SECURITY.md). Do not open public issues for undisclosed security problems.
62
+
63
+ ## License
64
+
65
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,49 @@
1
+ # shellui-django
2
+
3
+ Shared Django libraries for [Shellui](https://shellui.com) backend services: identity, storage, hosting, email, and saas.
4
+
5
+ ## Principles
6
+
7
+ - Only code duplicated in two or more services belongs here.
8
+ - Optional modules. Install what you need via extras (for example `[mcp]`).
9
+ - No shared Django models or migrations for now.
10
+ - [Semantic versioning](https://semver.org/). Services pin a compatible version range.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install shellui-django
16
+ pip install shellui-django[mcp] # MCP server helpers
17
+ ```
18
+
19
+ Requires Python 3.14+, Django, and DRF. The `[mcp]` extra adds PyJWT, cryptography, and SimpleJWT for MCP auth and signed internal calls.
20
+
21
+ ## Modules
22
+
23
+ | Module | Description |
24
+ |--------|-------------|
25
+ | [`shellui_django.mcp`](docs/mcp.md) | Turn a DRF OpenAPI schema into a secure multi-tenant MCP HTTP server. |
26
+ | [`shellui_django.testing`](docs/testing.md) | Shared test helpers (planned). |
27
+
28
+ ## Contributing and releases
29
+
30
+ 1. Open pull requests against `develop`.
31
+ 2. Merge `develop` into `main` when ready to release.
32
+ 3. Tag `vX.Y.Z` on `main`. GitHub Actions publishes `shellui-django` to PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/).
33
+
34
+ Run checks locally:
35
+
36
+ ```bash
37
+ uv sync --all-groups
38
+ DJANGO_SETTINGS_MODULE=tests.django_settings uv run python -m django test shellui_django.mcp.tests --verbosity=1
39
+ uv run ruff check src
40
+ uv build
41
+ ```
42
+
43
+ ## Security
44
+
45
+ Report vulnerabilities as described in [SECURITY.md](SECURITY.md). Do not open public issues for undisclosed security problems.
46
+
47
+ ## License
48
+
49
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,19 @@
1
+ # Security
2
+
3
+ Shellui treats security issues in this library seriously. The MCP module handles multi-tenant agent authentication and must fail closed when tokens or assertions are invalid.
4
+
5
+ ## Reporting a vulnerability
6
+
7
+ Email [security@shellui.com](mailto:security@shellui.com) with:
8
+
9
+ - A description of the issue and affected components
10
+ - Steps to reproduce or a proof of concept
11
+ - Impact assessment if known
12
+
13
+ Please do not open public GitHub issues for undisclosed vulnerabilities.
14
+
15
+ We aim to acknowledge reports within two business days and will coordinate disclosure and credit with you when appropriate.
16
+
17
+ ## Scope
18
+
19
+ This repository contains shared Django code used by Shellui services. Vulnerabilities in how a specific service wires settings or URLs should be reported to that service's maintainers as well.
@@ -0,0 +1,65 @@
1
+ [project]
2
+ name = "shellui-django"
3
+ version = "0.1.0"
4
+ description = "Shared Django libraries for Shellui services"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.14"
8
+ authors = [{ name = "SΓ©bastien Barbier" }]
9
+ dependencies = [
10
+ "django==6.0.8",
11
+ "djangorestframework==3.18.2",
12
+ ]
13
+
14
+ [project.optional-dependencies]
15
+ mcp = [
16
+ "cryptography>=50.0.0",
17
+ "djangorestframework-simplejwt==5.5.1",
18
+ "pyjwt>=2.14.0",
19
+ ]
20
+
21
+ [dependency-groups]
22
+ dev = [
23
+ { include-group = "lint" },
24
+ { include-group = "test" },
25
+ ]
26
+ lint = [
27
+ "ruff>=0.9.0",
28
+ ]
29
+ test = [
30
+ "shellui-django[mcp]",
31
+ ]
32
+
33
+ [build-system]
34
+ requires = ["hatchling"]
35
+ build-backend = "hatchling.build"
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/shellui_django"]
39
+ exclude = [
40
+ "**/tests/**",
41
+ ]
42
+
43
+ [tool.hatch.build.targets.sdist]
44
+ include = [
45
+ "/src",
46
+ "/CHANGELOG.md",
47
+ "/LICENSE",
48
+ "/README.md",
49
+ "/SECURITY.md",
50
+ ]
51
+
52
+ [tool.ruff]
53
+ target-version = "py314"
54
+ line-length = 120
55
+ src = ["src"]
56
+
57
+ [tool.ruff.lint]
58
+ select = ["E", "F", "I", "UP", "B"]
59
+ ignore = ["UP047"]
60
+
61
+ [tool.ruff.lint.per-file-ignores]
62
+ "src/shellui_django/mcp/**" = ["E501"]
63
+
64
+ [tool.ruff.lint.isort]
65
+ known-first-party = ["shellui_django"]
@@ -0,0 +1,3 @@
1
+ """Shared Django libraries for Shellui services."""
2
+
3
+ __version__ = '0.1.0'
@@ -0,0 +1,27 @@
1
+ """MCP server layer for Shellui Django services."""
2
+
3
+ from shellui_django.mcp.decorators import mcp_expose_tool
4
+ from shellui_django.mcp.internal import (
5
+ APPROVAL_AUDIENCE,
6
+ APPROVAL_SCOPE,
7
+ REVOCATION_CACHE_SECONDS,
8
+ REVOCATION_LIST_SCOPE,
9
+ build_mcp_approval_assertion,
10
+ build_mcp_revocation_list_response_assertion,
11
+ parse_trusted_revocation_poll_response,
12
+ verify_mcp_internal_assertion,
13
+ verify_mcp_revocation_list_response,
14
+ )
15
+
16
+ __all__ = [
17
+ 'mcp_expose_tool',
18
+ 'APPROVAL_AUDIENCE',
19
+ 'APPROVAL_SCOPE',
20
+ 'REVOCATION_CACHE_SECONDS',
21
+ 'REVOCATION_LIST_SCOPE',
22
+ 'build_mcp_approval_assertion',
23
+ 'build_mcp_revocation_list_response_assertion',
24
+ 'parse_trusted_revocation_poll_response',
25
+ 'verify_mcp_internal_assertion',
26
+ 'verify_mcp_revocation_list_response',
27
+ ]
@@ -0,0 +1,35 @@
1
+ """Mark DRF views whose OpenAPI operations become MCP tools."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable
6
+ from functools import wraps
7
+ from typing import Any, TypeVar
8
+
9
+ MCP_TOOL_TAG = 'mcp-tools'
10
+
11
+ F = TypeVar('F', bound=Callable[..., Any])
12
+
13
+
14
+ def mcp_expose_tool(_fn: F | None = None, *, name: str | None = None, description: str | None = None) -> F | Callable[[F], F]:
15
+ """Only tagged operations are exported as MCP tools. Never tag internal or staff-only endpoints."""
16
+
17
+ def decorator(fn: F) -> F:
18
+ meta = getattr(fn, '_mcp_tool_meta', None) or {}
19
+ if name:
20
+ meta['name'] = name
21
+ if description:
22
+ meta['description'] = description
23
+ fn._mcp_tool_meta = meta # type: ignore[attr-defined]
24
+
25
+ @wraps(fn)
26
+ def wrapped(*args, **kwargs):
27
+ return fn(*args, **kwargs)
28
+
29
+ wrapped._mcp_tool_meta = meta # type: ignore[attr-defined]
30
+ wrapped._mcp_expose_tool = True # type: ignore[attr-defined]
31
+ return wrapped # type: ignore[return-value]
32
+
33
+ if _fn is not None:
34
+ return decorator(_fn)
35
+ return decorator
@@ -0,0 +1,109 @@
1
+ """Thread-safe Identity JWKS fetch and RS256 JWT verification (no SimpleJWT)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import threading
7
+ import time
8
+ import urllib.error
9
+ import urllib.request
10
+ from typing import Any
11
+
12
+ import jwt
13
+ from jwt.algorithms import RSAAlgorithm
14
+
15
+ _CACHE_TTL_SECONDS = 300
16
+ _cache_lock = threading.Lock()
17
+ _jwks_cache: dict[str, tuple[float, dict[str, Any]]] = {}
18
+
19
+
20
+ class IdentityJwksError(Exception):
21
+ pass
22
+
23
+
24
+ def identity_jwks_url_for_issuer(issuer: str) -> str:
25
+ base = (issuer or '').strip().rstrip('/')
26
+ if not base:
27
+ raise IdentityJwksError('Identity issuer is required.')
28
+ return f'{base}/.well-known/jwks.json'
29
+
30
+
31
+ def _fetch_jwks_document(url: str, *, timeout: float) -> dict[str, Any]:
32
+ request = urllib.request.Request(url, headers={'Accept': 'application/json'})
33
+ try:
34
+ with urllib.request.urlopen(request, timeout=timeout) as response:
35
+ raw = response.read()
36
+ except (urllib.error.URLError, TimeoutError) as exc:
37
+ raise IdentityJwksError('Failed to fetch Identity JWKS.') from exc
38
+ try:
39
+ document = json.loads(raw.decode('utf-8'))
40
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
41
+ raise IdentityJwksError('Identity JWKS response was not JSON.') from exc
42
+ if not isinstance(document, dict) or not isinstance(document.get('keys'), list):
43
+ raise IdentityJwksError('Identity JWKS document is invalid.')
44
+ return document
45
+
46
+
47
+ def get_jwks_document(*, jwks_url: str | None = None, jwks: dict[str, Any] | None = None, timeout: float = 10.0) -> dict[str, Any]:
48
+ if jwks is not None:
49
+ if not isinstance(jwks.get('keys'), list):
50
+ raise IdentityJwksError('Inline JWKS document is invalid.')
51
+ return jwks
52
+ if not jwks_url:
53
+ raise IdentityJwksError('identity_jwks_url or jwks is required.')
54
+ now = time.monotonic()
55
+ with _cache_lock:
56
+ cached = _jwks_cache.get(jwks_url)
57
+ if cached and now - cached[0] < _CACHE_TTL_SECONDS:
58
+ return cached[1]
59
+ document = _fetch_jwks_document(jwks_url, timeout=timeout)
60
+ with _cache_lock:
61
+ _jwks_cache[jwks_url] = (now, document)
62
+ return document
63
+
64
+
65
+ def _public_key_from_jwk(jwk: dict[str, Any]):
66
+ if jwk.get('kty') != 'RSA':
67
+ raise IdentityJwksError('Unsupported JWK type.')
68
+ return RSAAlgorithm.from_jwk(json.dumps(jwk))
69
+
70
+
71
+ def resolve_verification_key(token: str, jwks_document: dict[str, Any]):
72
+ header = jwt.get_unverified_header(token)
73
+ kid = header.get('kid')
74
+ keys = jwks_document.get('keys') or []
75
+ candidates = [item for item in keys if isinstance(item, dict)]
76
+ if kid:
77
+ for jwk in candidates:
78
+ if jwk.get('kid') == kid:
79
+ return _public_key_from_jwk(jwk)
80
+ if len(candidates) == 1:
81
+ return _public_key_from_jwk(candidates[0])
82
+ raise IdentityJwksError('No matching JWKS key for revocation assertion.')
83
+
84
+
85
+ def decode_identity_rs256_jwt(
86
+ token: str,
87
+ *,
88
+ audience: str,
89
+ issuer: str,
90
+ jwks_url: str | None = None,
91
+ jwks: dict[str, Any] | None = None,
92
+ timeout: float = 10.0,
93
+ ) -> dict[str, Any]:
94
+ header = jwt.get_unverified_header(token)
95
+ if header.get('alg') != 'RS256':
96
+ raise IdentityJwksError('Identity JWT must use RS256.')
97
+ document = get_jwks_document(jwks_url=jwks_url, jwks=jwks, timeout=timeout)
98
+ key = resolve_verification_key(token, document)
99
+ try:
100
+ return jwt.decode(
101
+ token,
102
+ key=key,
103
+ algorithms=['RS256'],
104
+ audience=audience,
105
+ issuer=issuer,
106
+ options={'require': ['exp', 'iat', 'sub', 'scope']},
107
+ )
108
+ except jwt.PyJWTError as exc:
109
+ raise IdentityJwksError('Invalid Identity JWT.') from exc