shellui-django 0.1.0__tar.gz → 0.3.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 (36) hide show
  1. {shellui_django-0.1.0 → shellui_django-0.3.0}/CHANGELOG.md +30 -0
  2. {shellui_django-0.1.0 → shellui_django-0.3.0}/PKG-INFO +23 -2
  3. {shellui_django-0.1.0 → shellui_django-0.3.0}/README.md +6 -1
  4. {shellui_django-0.1.0 → shellui_django-0.3.0}/pyproject.toml +22 -1
  5. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/__init__.py +1 -1
  6. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/__init__.py +14 -0
  7. shellui_django-0.3.0/src/shellui_django/mcp/delegation.py +165 -0
  8. shellui_django-0.3.0/src/shellui_django/mcp/gateway.py +358 -0
  9. shellui_django-0.3.0/src/shellui_django/mcp/tests/test_delegation.py +227 -0
  10. shellui_django-0.3.0/src/shellui_django/mcp/tests/test_gateway.py +303 -0
  11. {shellui_django-0.1.0 → shellui_django-0.3.0}/.gitignore +0 -0
  12. {shellui_django-0.1.0 → shellui_django-0.3.0}/LICENSE +0 -0
  13. {shellui_django-0.1.0 → shellui_django-0.3.0}/SECURITY.md +0 -0
  14. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/decorators.py +0 -0
  15. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/identity_jwks.py +0 -0
  16. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/internal.py +0 -0
  17. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/masking.py +0 -0
  18. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/openapi_mcp.py +0 -0
  19. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/openapi_tools.py +0 -0
  20. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/rate_limit.py +0 -0
  21. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/resources.py +0 -0
  22. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/routing.py +0 -0
  23. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/server.py +0 -0
  24. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/__init__.py +0 -0
  25. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/mcp_routing_urlconf.py +0 -0
  26. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/rs256_helpers.py +0 -0
  27. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_internal_revocation.py +0 -0
  28. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_masking.py +0 -0
  29. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_openapi_tools.py +0 -0
  30. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_package.py +0 -0
  31. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_resources.py +0 -0
  32. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_routing.py +0 -0
  33. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_server_routing.py +0 -0
  34. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/tests/test_write_gate_mcp.py +0 -0
  35. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/mcp/write_gate.py +0 -0
  36. {shellui_django-0.1.0 → shellui_django-0.3.0}/src/shellui_django/testing/__init__.py +0 -0
@@ -23,6 +23,36 @@ Breaking changes bump the major version (minor while below 1.0.0), so services c
23
23
  See for sample https://raw.githubusercontent.com/favoloso/conventional-changelog-emoji/master/CHANGELOG.md
24
24
  -->
25
25
 
26
+ ## [0.3.0] - 2026-11-02
27
+
28
+ ### ✨ Feature
29
+
30
+ - Add `shellui_django.mcp.delegation`: RS256 helpers for gateway-to-Identity downstream MCP token mint requests (`sign_downstream_token_request`, `verify_downstream_token_request`) with shared audience and scope constants.
31
+
32
+ ### 📚 Documentation
33
+
34
+ - Document downstream token delegation in `docs/mcp.md`.
35
+
36
+ ## [0.2.1] - 2026-11-02
37
+
38
+ ### 📚 Documentation
39
+
40
+ - Add CI, PyPI, Python and license badges to the README.
41
+
42
+ ## [0.2.0] - 2026-11-02
43
+
44
+ ### ✨ Feature
45
+
46
+ - Add `shellui_django.mcp.gateway`: `AggregatingMcpServer` merges downstream `tools/list` and forwards `tools/call` with service-scoped RS256 tokens (`aud` = `{service}/mcp`). Host apps inject the service URL map, agent lookup, and token minting.
47
+
48
+ ### 📚 Documentation
49
+
50
+ - Document the MCP aggregating gateway in `docs/mcp.md`.
51
+
52
+ ### 🏗 Chore
53
+
54
+ - PyPI metadata: license file, classifiers, keywords and project links.
55
+
26
56
  ## [0.1.0] - 2026-11-02
27
57
 
28
58
  ### ✨ Feature
@@ -1,10 +1,25 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: shellui-django
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Shared Django libraries for Shellui services
5
+ Project-URL: Homepage, https://shellui.com
6
+ Project-URL: Source, https://github.com/shellui/django-commons
7
+ Project-URL: Documentation, https://github.com/shellui/django-commons/tree/main/docs
8
+ Project-URL: Changelog, https://github.com/shellui/django-commons/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/shellui/django-commons/issues
5
10
  Author: Sébastien Barbier
6
11
  License-Expression: MIT
7
12
  License-File: LICENSE
13
+ Keywords: django,djangorestframework,mcp,shellui
14
+ Classifier: Development Status :: 3 - Alpha
15
+ Classifier: Framework :: Django
16
+ Classifier: Framework :: Django :: 6.0
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Internet :: WWW/HTTP
22
+ Classifier: Topic :: Security
8
23
  Requires-Python: >=3.14
9
24
  Requires-Dist: django==6.0.8
10
25
  Requires-Dist: djangorestframework==3.18.2
@@ -12,10 +27,16 @@ Provides-Extra: mcp
12
27
  Requires-Dist: cryptography>=50.0.0; extra == 'mcp'
13
28
  Requires-Dist: djangorestframework-simplejwt==5.5.1; extra == 'mcp'
14
29
  Requires-Dist: pyjwt>=2.14.0; extra == 'mcp'
30
+ Requires-Dist: requests>=2.32.0; extra == 'mcp'
15
31
  Description-Content-Type: text/markdown
16
32
 
17
33
  # shellui-django
18
34
 
35
+ [![CI](https://github.com/shellui/django-commons/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/shellui/django-commons/actions/workflows/ci.yml)
36
+ [![PyPI](https://img.shields.io/pypi/v/shellui-django)](https://pypi.org/project/shellui-django/)
37
+ [![Python](https://img.shields.io/pypi/pyversions/shellui-django)](https://pypi.org/project/shellui-django/)
38
+ [![License: MIT](https://img.shields.io/github/license/shellui/django-commons)](LICENSE)
39
+
19
40
  Shared Django libraries for [Shellui](https://shellui.com) backend services: identity, storage, hosting, email, and saas.
20
41
 
21
42
  ## Principles
@@ -32,7 +53,7 @@ pip install shellui-django
32
53
  pip install shellui-django[mcp] # MCP server helpers
33
54
  ```
34
55
 
35
- Requires Python 3.14+, Django, and DRF. The `[mcp]` extra adds PyJWT, cryptography, and SimpleJWT for MCP auth and signed internal calls.
56
+ Requires Python 3.14+, Django, and DRF. The `[mcp]` extra adds PyJWT, cryptography, SimpleJWT, and requests for MCP auth, signed internal calls, and the aggregating gateway.
36
57
 
37
58
  ## Modules
38
59
 
@@ -1,5 +1,10 @@
1
1
  # shellui-django
2
2
 
3
+ [![CI](https://github.com/shellui/django-commons/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/shellui/django-commons/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/shellui-django)](https://pypi.org/project/shellui-django/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/shellui-django)](https://pypi.org/project/shellui-django/)
6
+ [![License: MIT](https://img.shields.io/github/license/shellui/django-commons)](LICENSE)
7
+
3
8
  Shared Django libraries for [Shellui](https://shellui.com) backend services: identity, storage, hosting, email, and saas.
4
9
 
5
10
  ## Principles
@@ -16,7 +21,7 @@ pip install shellui-django
16
21
  pip install shellui-django[mcp] # MCP server helpers
17
22
  ```
18
23
 
19
- Requires Python 3.14+, Django, and DRF. The `[mcp]` extra adds PyJWT, cryptography, and SimpleJWT for MCP auth and signed internal calls.
24
+ Requires Python 3.14+, Django, and DRF. The `[mcp]` extra adds PyJWT, cryptography, SimpleJWT, and requests for MCP auth, signed internal calls, and the aggregating gateway.
20
25
 
21
26
  ## Modules
22
27
 
@@ -1,9 +1,22 @@
1
1
  [project]
2
2
  name = "shellui-django"
3
- version = "0.1.0"
3
+ version = "0.3.0"
4
4
  description = "Shared Django libraries for Shellui services"
5
5
  readme = "README.md"
6
6
  license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ keywords = ["django", "djangorestframework", "mcp", "shellui"]
9
+ classifiers = [
10
+ "Development Status :: 3 - Alpha",
11
+ "Framework :: Django",
12
+ "Framework :: Django :: 6.0",
13
+ "Intended Audience :: Developers",
14
+ "Operating System :: OS Independent",
15
+ "Programming Language :: Python :: 3",
16
+ "Programming Language :: Python :: 3.14",
17
+ "Topic :: Security",
18
+ "Topic :: Internet :: WWW/HTTP",
19
+ ]
7
20
  requires-python = ">=3.14"
8
21
  authors = [{ name = "Sébastien Barbier" }]
9
22
  dependencies = [
@@ -11,11 +24,19 @@ dependencies = [
11
24
  "djangorestframework==3.18.2",
12
25
  ]
13
26
 
27
+ [project.urls]
28
+ Homepage = "https://shellui.com"
29
+ Source = "https://github.com/shellui/django-commons"
30
+ Documentation = "https://github.com/shellui/django-commons/tree/main/docs"
31
+ Changelog = "https://github.com/shellui/django-commons/blob/main/CHANGELOG.md"
32
+ Issues = "https://github.com/shellui/django-commons/issues"
33
+
14
34
  [project.optional-dependencies]
15
35
  mcp = [
16
36
  "cryptography>=50.0.0",
17
37
  "djangorestframework-simplejwt==5.5.1",
18
38
  "pyjwt>=2.14.0",
39
+ "requests>=2.32.0",
19
40
  ]
20
41
 
21
42
  [dependency-groups]
@@ -1,3 +1,3 @@
1
1
  """Shared Django libraries for Shellui services."""
2
2
 
3
- __version__ = '0.1.0'
3
+ __version__ = '0.3.0'
@@ -1,6 +1,14 @@
1
1
  """MCP server layer for Shellui Django services."""
2
2
 
3
3
  from shellui_django.mcp.decorators import mcp_expose_tool
4
+ from shellui_django.mcp.delegation import (
5
+ DOWNSTREAM_TOKEN_AUDIENCE,
6
+ DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS,
7
+ DOWNSTREAM_TOKEN_SCOPE,
8
+ DownstreamTokenRequestError,
9
+ sign_downstream_token_request,
10
+ verify_downstream_token_request,
11
+ )
4
12
  from shellui_django.mcp.internal import (
5
13
  APPROVAL_AUDIENCE,
6
14
  APPROVAL_SCOPE,
@@ -15,6 +23,12 @@ from shellui_django.mcp.internal import (
15
23
 
16
24
  __all__ = [
17
25
  'mcp_expose_tool',
26
+ 'DOWNSTREAM_TOKEN_AUDIENCE',
27
+ 'DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS',
28
+ 'DOWNSTREAM_TOKEN_SCOPE',
29
+ 'DownstreamTokenRequestError',
30
+ 'sign_downstream_token_request',
31
+ 'verify_downstream_token_request',
18
32
  'APPROVAL_AUDIENCE',
19
33
  'APPROVAL_SCOPE',
20
34
  'REVOCATION_CACHE_SECONDS',
@@ -0,0 +1,165 @@
1
+ """RS256 JWT delegation: gateway requests Identity to mint downstream MCP access tokens."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ import uuid
7
+ from typing import Any
8
+
9
+ import jwt
10
+
11
+ DOWNSTREAM_TOKEN_AUDIENCE = 'shellui-mcp-downstream-token'
12
+ DOWNSTREAM_TOKEN_SCOPE = 'mcp.downstream_token.mint'
13
+ DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS = 60
14
+ DOWNSTREAM_TOKEN_REQUEST_LEEWAY_SECONDS = 5
15
+
16
+ _REQUIRED_CLAIMS = (
17
+ 'iss',
18
+ 'aud',
19
+ 'scope',
20
+ 'agent_id',
21
+ 'company_id',
22
+ 'resource',
23
+ 'jti',
24
+ 'iat',
25
+ 'exp',
26
+ )
27
+
28
+
29
+ class DownstreamTokenRequestError(Exception):
30
+ def __init__(self, message: str, *, status: int = 401):
31
+ super().__init__(message)
32
+ self.message = message
33
+ self.status = status
34
+
35
+
36
+ def sign_downstream_token_request(
37
+ private_key_pem: str,
38
+ kid: str,
39
+ issuer: str,
40
+ agent_id: str,
41
+ company_id: int,
42
+ resource: str,
43
+ ttl: int,
44
+ ) -> str:
45
+ """Sign a short-lived RS256 request JWT for Identity's downstream token mint endpoint."""
46
+ if ttl <= 0 or ttl > DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS:
47
+ raise DownstreamTokenRequestError(
48
+ f'ttl must be between 1 and {DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS} seconds.'
49
+ )
50
+ pem = (private_key_pem or '').strip()
51
+ if not pem:
52
+ raise DownstreamTokenRequestError('private_key_pem is required.')
53
+ iss = (issuer or '').strip()
54
+ if not iss:
55
+ raise DownstreamTokenRequestError('issuer is required.')
56
+ agent = (agent_id or '').strip()
57
+ if not agent:
58
+ raise DownstreamTokenRequestError('agent_id is required.')
59
+ res = (resource or '').strip()
60
+ if not res:
61
+ raise DownstreamTokenRequestError('resource is required.')
62
+ now = int(time.time())
63
+ claims = {
64
+ 'iss': iss,
65
+ 'aud': DOWNSTREAM_TOKEN_AUDIENCE,
66
+ 'scope': DOWNSTREAM_TOKEN_SCOPE,
67
+ 'agent_id': agent,
68
+ 'company_id': int(company_id),
69
+ 'resource': res,
70
+ 'jti': uuid.uuid4().hex,
71
+ 'iat': now,
72
+ 'exp': now + int(ttl),
73
+ }
74
+ headers: dict[str, str] | None = None
75
+ key_id = (kid or '').strip()
76
+ if key_id:
77
+ headers = {'kid': key_id}
78
+ token = jwt.encode(claims, pem, algorithm='RS256', headers=headers)
79
+ return token.decode('utf-8') if isinstance(token, bytes) else token
80
+
81
+
82
+ def _normalize_bearer_token(raw_token: str) -> str:
83
+ if not raw_token or not raw_token.strip():
84
+ raise DownstreamTokenRequestError('Missing downstream token request JWT.')
85
+ token = raw_token.strip()
86
+ if token.lower().startswith('bearer '):
87
+ token = token[7:].strip()
88
+ if not token:
89
+ raise DownstreamTokenRequestError('Missing downstream token request JWT.')
90
+ return token
91
+
92
+
93
+ def _resolve_verification_key(token: str, public_jwks_or_pem: dict[str, Any] | str) -> Any:
94
+ if isinstance(public_jwks_or_pem, str):
95
+ pem = public_jwks_or_pem.strip()
96
+ if not pem:
97
+ raise DownstreamTokenRequestError('Verification key is required.')
98
+ return pem
99
+ if isinstance(public_jwks_or_pem, dict):
100
+ from shellui_django.mcp.identity_jwks import IdentityJwksError, resolve_verification_key
101
+
102
+ try:
103
+ return resolve_verification_key(token, public_jwks_or_pem)
104
+ except IdentityJwksError as exc:
105
+ raise DownstreamTokenRequestError(str(exc)) from exc
106
+ raise DownstreamTokenRequestError('public_jwks_or_pem must be a PEM string or JWKS document.')
107
+
108
+
109
+ def _assert_lifetime_within_limit(claims: dict[str, Any]) -> None:
110
+ try:
111
+ iat = int(claims['iat'])
112
+ exp = int(claims['exp'])
113
+ except (KeyError, TypeError, ValueError) as exc:
114
+ raise DownstreamTokenRequestError('Invalid iat or exp.') from exc
115
+ if exp <= iat:
116
+ raise DownstreamTokenRequestError('Token lifetime is invalid.')
117
+ if exp - iat > DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS:
118
+ raise DownstreamTokenRequestError('Token lifetime exceeds the maximum allowed.')
119
+
120
+
121
+ def verify_downstream_token_request(
122
+ token: str,
123
+ public_jwks_or_pem: dict[str, Any] | str,
124
+ expected_issuer: str,
125
+ ) -> dict[str, Any]:
126
+ """Verify a gateway-signed downstream token request; returns claims (including ``jti`` for one-time use)."""
127
+ normalized = _normalize_bearer_token(token)
128
+ issuer = (expected_issuer or '').strip().rstrip('/')
129
+ if not issuer:
130
+ raise DownstreamTokenRequestError('expected_issuer is required.')
131
+ try:
132
+ header = jwt.get_unverified_header(normalized)
133
+ except jwt.PyJWTError as exc:
134
+ raise DownstreamTokenRequestError('Invalid downstream token request JWT.') from exc
135
+ alg = str(header.get('alg') or '')
136
+ if alg != 'RS256':
137
+ raise DownstreamTokenRequestError('Downstream token request JWT must use RS256.')
138
+ key = _resolve_verification_key(normalized, public_jwks_or_pem)
139
+ try:
140
+ claims = jwt.decode(
141
+ normalized,
142
+ key=key,
143
+ algorithms=['RS256'],
144
+ audience=DOWNSTREAM_TOKEN_AUDIENCE,
145
+ issuer=issuer,
146
+ leeway=DOWNSTREAM_TOKEN_REQUEST_LEEWAY_SECONDS,
147
+ options={'require': list(_REQUIRED_CLAIMS)},
148
+ )
149
+ except jwt.PyJWTError as exc:
150
+ raise DownstreamTokenRequestError('Invalid downstream token request JWT.') from exc
151
+ scope = str(claims.get('scope') or '')
152
+ if scope != DOWNSTREAM_TOKEN_SCOPE:
153
+ raise DownstreamTokenRequestError('Downstream token request scope mismatch.')
154
+ aud = claims.get('aud')
155
+ if isinstance(aud, list):
156
+ if DOWNSTREAM_TOKEN_AUDIENCE not in aud:
157
+ raise DownstreamTokenRequestError('Downstream token request audience mismatch.')
158
+ elif str(aud or '') != DOWNSTREAM_TOKEN_AUDIENCE:
159
+ raise DownstreamTokenRequestError('Downstream token request audience mismatch.')
160
+ _assert_lifetime_within_limit(claims)
161
+ for name in _REQUIRED_CLAIMS:
162
+ value = claims.get(name)
163
+ if value is None or (isinstance(value, str) and not value.strip()):
164
+ raise DownstreamTokenRequestError(f'Missing required claim: {name}.')
165
+ return dict(claims)