shellui-django 0.3.0__tar.gz → 0.5.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 (42) hide show
  1. shellui_django-0.5.0/CHANGELOG.md +89 -0
  2. {shellui_django-0.3.0 → shellui_django-0.5.0}/PKG-INFO +1 -1
  3. {shellui_django-0.3.0 → shellui_django-0.5.0}/pyproject.toml +1 -1
  4. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/__init__.py +1 -1
  5. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/__init__.py +6 -0
  6. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/delegation.py +12 -15
  7. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/identity_jwks.py +53 -2
  8. shellui_django-0.5.0/src/shellui_django/mcp/internal.py +673 -0
  9. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/rs256_helpers.py +12 -0
  10. shellui_django-0.5.0/src/shellui_django/mcp/tests/test_approval_authority.py +261 -0
  11. shellui_django-0.5.0/src/shellui_django/mcp/tests/test_identity_jwks_decode.py +104 -0
  12. shellui_django-0.5.0/src/shellui_django/mcp/tests/test_internal_assertions.py +246 -0
  13. shellui_django-0.5.0/src/shellui_django/mcp/tests/test_internal_revocation.py +517 -0
  14. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_package.py +7 -0
  15. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/write_gate.py +3 -1
  16. shellui_django-0.3.0/CHANGELOG.md +0 -64
  17. shellui_django-0.3.0/src/shellui_django/mcp/internal.py +0 -264
  18. shellui_django-0.3.0/src/shellui_django/mcp/tests/test_internal_revocation.py +0 -109
  19. {shellui_django-0.3.0 → shellui_django-0.5.0}/.gitignore +0 -0
  20. {shellui_django-0.3.0 → shellui_django-0.5.0}/LICENSE +0 -0
  21. {shellui_django-0.3.0 → shellui_django-0.5.0}/README.md +0 -0
  22. {shellui_django-0.3.0 → shellui_django-0.5.0}/SECURITY.md +0 -0
  23. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/decorators.py +0 -0
  24. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/gateway.py +0 -0
  25. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/masking.py +0 -0
  26. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/openapi_mcp.py +0 -0
  27. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/openapi_tools.py +0 -0
  28. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/rate_limit.py +0 -0
  29. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/resources.py +0 -0
  30. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/routing.py +0 -0
  31. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/server.py +0 -0
  32. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/__init__.py +0 -0
  33. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/mcp_routing_urlconf.py +0 -0
  34. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_delegation.py +0 -0
  35. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_gateway.py +0 -0
  36. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_masking.py +0 -0
  37. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_openapi_tools.py +0 -0
  38. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_resources.py +0 -0
  39. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_routing.py +0 -0
  40. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_server_routing.py +0 -0
  41. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/mcp/tests/test_write_gate_mcp.py +0 -0
  42. {shellui_django-0.3.0 → shellui_django-0.5.0}/src/shellui_django/testing/__init__.py +0 -0
@@ -0,0 +1,89 @@
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.5.0] - 2026-11-06
27
+
28
+ ### 🛠 Improvements
29
+
30
+ - MCP internal assertions: optional regional authority fields on `build_mcp_approval_assertion` (`grant_version`, `global_company_id`, `company_binding_version`) and optional revocation policy metadata on `build_mcp_revocation_list_response_assertion` (`revocation_policy_version`, `max_active_grant_version`); strict non-negative integers, delegated global pair rules (`is not None` only), body and JWT parity for top-level policy fields (legacy digit strings on the HTTP envelope), per-agent binding validation with `mcp_authority_snapshot_fingerprint` and `mcp_authority_snapshot_rejected` on trusted rows, delegated grant cap checks against signed `max_active_grant_version` without blocking personal rows, `jti` and lifetime invariants (`exp` after `iat`, 600 s cap) on Identity-signed revocation lists, and positive `cache_seconds` bounded by the same cap.
31
+ - Revocation list verification: strict `iat` / `exp` types after decode (reject bool and float; digit strings coerced), clock window aligned with `IDENTITY_RS256_LEEWAY_SECONDS` (5 s) on `decode_identity_rs256_jwt`.
32
+ - `decode_identity_rs256_jwt` always requires `exp`, `iat`, `sub`, `scope`, and `jti`; `require_claims` adds further required names (union). Timestamps are normalized to integers after verify.
33
+ - `verify_rs256_mcp_assertion` lifetime checks use the same strict timestamp parsing as revocation (no `int()` on raw claims).
34
+ - Destructive MCP tools always require approval in `full` mode; `mcp_destructive` does not skip the gate.
35
+
36
+ ### 📚 Documentation
37
+
38
+ - `docs/mcp.md`: regional authority, revocation policy proof, per-agent binding snapshots, numeric `0` vs omitted or `None`, `decode_identity_rs256_jwt` requirements, and destructive approval rules.
39
+
40
+ ## [0.4.0] - 2026-11-04
41
+
42
+ ### 🔒 Security
43
+
44
+ - Service-to-identity MCP internal assertions (`build_mcp_approval_assertion`, `build_mcp_call_log_assertion`, `build_mcp_revocation_assertion`) are signed RS256 with the caller `JWT_SIGNING_KEY` and caller issuer (`JWT_ISSUER` or SimpleJWT `ISSUER`), not SimpleJWT HMAC keys.
45
+ - `verify_mcp_internal_assertion` / `verify_rs256_mcp_assertion` verify RS256 against caller JWKS or PEM (`expected_issuer`, audience, scope, target, lifetime, optional `register_jti`). HS256 and `alg: none` are rejected; verification never uses a private key.
46
+
47
+ ### 🚨 Changed
48
+
49
+ - `verify_mcp_internal_assertion` now requires `public_jwks_or_pem` and `expected_issuer` (breaking for Identity and other verifiers).
50
+
51
+ ## [0.3.0] - 2026-11-02
52
+
53
+ ### ✨ Feature
54
+
55
+ - 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.
56
+
57
+ ### 📚 Documentation
58
+
59
+ - Document downstream token delegation in `docs/mcp.md`.
60
+
61
+ ## [0.2.1] - 2026-11-02
62
+
63
+ ### 📚 Documentation
64
+
65
+ - Add CI, PyPI, Python and license badges to the README.
66
+
67
+ ## [0.2.0] - 2026-11-02
68
+
69
+ ### ✨ Feature
70
+
71
+ - 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.
72
+
73
+ ### 📚 Documentation
74
+
75
+ - Document the MCP aggregating gateway in `docs/mcp.md`.
76
+
77
+ ### 🏗 Chore
78
+
79
+ - PyPI metadata: license file, classifiers, keywords and project links.
80
+
81
+ ## [0.1.0] - 2026-11-02
82
+
83
+ ### ✨ Feature
84
+
85
+ - First release of `shellui-django` with the shared MCP module (OpenAPI tools, write gate, revocation helpers, streamable HTTP server).
86
+
87
+ ### 📚 Documentation
88
+
89
+ - Add package README and `docs/` guides for the MCP and testing modules.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: shellui-django
3
- Version: 0.3.0
3
+ Version: 0.5.0
4
4
  Summary: Shared Django libraries for Shellui services
5
5
  Project-URL: Homepage, https://shellui.com
6
6
  Project-URL: Source, https://github.com/shellui/django-commons
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "shellui-django"
3
- version = "0.3.0"
3
+ version = "0.5.0"
4
4
  description = "Shared Django libraries for Shellui services"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -1,3 +1,3 @@
1
1
  """Shared Django libraries for Shellui services."""
2
2
 
3
- __version__ = '0.3.0'
3
+ __version__ = '0.5.0'
@@ -12,13 +12,16 @@ from shellui_django.mcp.delegation import (
12
12
  from shellui_django.mcp.internal import (
13
13
  APPROVAL_AUDIENCE,
14
14
  APPROVAL_SCOPE,
15
+ INTERNAL_ASSERTION_MAX_LIFETIME_SECONDS,
15
16
  REVOCATION_CACHE_SECONDS,
17
+ REVOCATION_LIST_MAX_ASSERTION_LIFETIME_SECONDS,
16
18
  REVOCATION_LIST_SCOPE,
17
19
  build_mcp_approval_assertion,
18
20
  build_mcp_revocation_list_response_assertion,
19
21
  parse_trusted_revocation_poll_response,
20
22
  verify_mcp_internal_assertion,
21
23
  verify_mcp_revocation_list_response,
24
+ verify_rs256_mcp_assertion,
22
25
  )
23
26
 
24
27
  __all__ = [
@@ -31,11 +34,14 @@ __all__ = [
31
34
  'verify_downstream_token_request',
32
35
  'APPROVAL_AUDIENCE',
33
36
  'APPROVAL_SCOPE',
37
+ 'INTERNAL_ASSERTION_MAX_LIFETIME_SECONDS',
34
38
  'REVOCATION_CACHE_SECONDS',
39
+ 'REVOCATION_LIST_MAX_ASSERTION_LIFETIME_SECONDS',
35
40
  'REVOCATION_LIST_SCOPE',
36
41
  'build_mcp_approval_assertion',
37
42
  'build_mcp_revocation_list_response_assertion',
38
43
  'parse_trusted_revocation_poll_response',
39
44
  'verify_mcp_internal_assertion',
40
45
  'verify_mcp_revocation_list_response',
46
+ 'verify_rs256_mcp_assertion',
41
47
  ]
@@ -8,6 +8,8 @@ from typing import Any
8
8
 
9
9
  import jwt
10
10
 
11
+ from shellui_django.mcp.identity_jwks import IdentityJwksError, jwt_unix_timestamp_claim_strict
12
+
11
13
  DOWNSTREAM_TOKEN_AUDIENCE = 'shellui-mcp-downstream-token'
12
14
  DOWNSTREAM_TOKEN_SCOPE = 'mcp.downstream_token.mint'
13
15
  DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS = 60
@@ -91,27 +93,22 @@ def _normalize_bearer_token(raw_token: str) -> str:
91
93
 
92
94
 
93
95
  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
96
+ from shellui_django.mcp.identity_jwks import IdentityJwksError, resolve_public_verification_key
101
97
 
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.')
98
+ try:
99
+ return resolve_public_verification_key(token, public_jwks_or_pem)
100
+ except IdentityJwksError as exc:
101
+ raise DownstreamTokenRequestError(str(exc)) from exc
107
102
 
108
103
 
109
104
  def _assert_lifetime_within_limit(claims: dict[str, Any]) -> None:
110
105
  try:
111
- iat = int(claims['iat'])
112
- exp = int(claims['exp'])
113
- except (KeyError, TypeError, ValueError) as exc:
106
+ iat = jwt_unix_timestamp_claim_strict(claims['iat'], field='iat')
107
+ exp = jwt_unix_timestamp_claim_strict(claims['exp'], field='exp')
108
+ except KeyError as exc:
114
109
  raise DownstreamTokenRequestError('Invalid iat or exp.') from exc
110
+ except IdentityJwksError as exc:
111
+ raise DownstreamTokenRequestError(str(exc)) from exc
115
112
  if exp <= iat:
116
113
  raise DownstreamTokenRequestError('Token lifetime is invalid.')
117
114
  if exp - iat > DOWNSTREAM_TOKEN_REQUEST_MAX_LIFETIME_SECONDS:
@@ -13,6 +13,8 @@ import jwt
13
13
  from jwt.algorithms import RSAAlgorithm
14
14
 
15
15
  _CACHE_TTL_SECONDS = 300
16
+ # Match ``INTERNAL_ASSERTION_LEEWAY_SECONDS`` in ``internal`` for Identity JWT verification.
17
+ IDENTITY_RS256_LEEWAY_SECONDS = 5
16
18
  _cache_lock = threading.Lock()
17
19
  _jwks_cache: dict[str, tuple[float, dict[str, Any]]] = {}
18
20
 
@@ -21,6 +23,27 @@ class IdentityJwksError(Exception):
21
23
  pass
22
24
 
23
25
 
26
+ def jwt_unix_timestamp_claim_strict(value: Any, *, field: str) -> int:
27
+ """``iat`` / ``exp`` after JWT decode: non-negative int, or digit-only string (PyJWT quirk).
28
+
29
+ Rejects bool, float, and non-digit strings so values are not confused via ``int()`` coercion.
30
+ """
31
+ if isinstance(value, bool):
32
+ raise IdentityJwksError(f'{field} must be a Unix timestamp.')
33
+ if isinstance(value, float):
34
+ raise IdentityJwksError(f'{field} must be a Unix timestamp.')
35
+ if isinstance(value, int):
36
+ if value < 0:
37
+ raise IdentityJwksError(f'{field} must be non-negative.')
38
+ return value
39
+ if isinstance(value, str):
40
+ s = value.strip()
41
+ if not s or not s.isdigit():
42
+ raise IdentityJwksError(f'{field} must be a Unix timestamp.')
43
+ return int(s)
44
+ raise IdentityJwksError(f'{field} must be a Unix timestamp.')
45
+
46
+
24
47
  def identity_jwks_url_for_issuer(issuer: str) -> str:
25
48
  base = (issuer or '').strip().rstrip('/')
26
49
  if not base:
@@ -68,6 +91,18 @@ def _public_key_from_jwk(jwk: dict[str, Any]):
68
91
  return RSAAlgorithm.from_jwk(json.dumps(jwk))
69
92
 
70
93
 
94
+ def resolve_public_verification_key(token: str, public_jwks_or_pem: dict[str, Any] | str):
95
+ """Return a verification key from inline JWKS, a fetched document, or a PEM string."""
96
+ if isinstance(public_jwks_or_pem, str):
97
+ pem = public_jwks_or_pem.strip()
98
+ if not pem:
99
+ raise IdentityJwksError('Verification key is required.')
100
+ return pem
101
+ if isinstance(public_jwks_or_pem, dict):
102
+ return resolve_verification_key(token, public_jwks_or_pem)
103
+ raise IdentityJwksError('public_jwks_or_pem must be a PEM string or JWKS document.')
104
+
105
+
71
106
  def resolve_verification_key(token: str, jwks_document: dict[str, Any]):
72
107
  header = jwt.get_unverified_header(token)
73
108
  kid = header.get('kid')
@@ -90,20 +125,36 @@ def decode_identity_rs256_jwt(
90
125
  jwks_url: str | None = None,
91
126
  jwks: dict[str, Any] | None = None,
92
127
  timeout: float = 10.0,
128
+ require_claims: tuple[str, ...] = (),
93
129
  ) -> dict[str, Any]:
130
+ """Verify an Identity-issued RS256 JWT against JWKS.
131
+
132
+ Always requires ``exp``, ``iat``, ``sub``, ``scope``, and ``jti``. Names in
133
+ ``require_claims`` add further required claims (union, never a substitute).
134
+ Timestamp claims are normalized to strict non-negative integers after decode.
135
+ """
94
136
  header = jwt.get_unverified_header(token)
95
137
  if header.get('alg') != 'RS256':
96
138
  raise IdentityJwksError('Identity JWT must use RS256.')
97
139
  document = get_jwks_document(jwks_url=jwks_url, jwks=jwks, timeout=timeout)
98
140
  key = resolve_verification_key(token, document)
141
+ mandatory = {'exp', 'iat', 'sub', 'scope', 'jti'}
142
+ merged = sorted(mandatory.union(require_claims))
99
143
  try:
100
- return jwt.decode(
144
+ claims = jwt.decode(
101
145
  token,
102
146
  key=key,
103
147
  algorithms=['RS256'],
104
148
  audience=audience,
105
149
  issuer=issuer,
106
- options={'require': ['exp', 'iat', 'sub', 'scope']},
150
+ leeway=IDENTITY_RS256_LEEWAY_SECONDS,
151
+ options={'require': merged},
107
152
  )
108
153
  except jwt.PyJWTError as exc:
109
154
  raise IdentityJwksError('Invalid Identity JWT.') from exc
155
+ try:
156
+ claims['iat'] = jwt_unix_timestamp_claim_strict(claims['iat'], field='iat')
157
+ claims['exp'] = jwt_unix_timestamp_claim_strict(claims['exp'], field='exp')
158
+ except KeyError as exc:
159
+ raise IdentityJwksError('Invalid Identity JWT.') from exc
160
+ return claims