scalekit-sdk-python 2.16.0__tar.gz → 2.18.0__tar.gz

{scalekit_sdk_python-2.16.0 → scalekit_sdk_python-2.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scalekit-sdk-python
-Version: 2.16.0
+Version: 2.18.0
 Summary: Scalekit official Python SDK
 Home-page: https://github.com/scalekit-inc/scalekit-sdk-python
 Author: Team Scalekit
@@ -17,7 +17,7 @@ Requires-Dist: google>=3.0
 Requires-Dist: requests>=2.34.0
 Requires-Dist: PyJWT>=2.13.0
 Requires-Dist: cffi>=1.15.1
-Requires-Dist: cryptography<49,>=46.0.6
+Requires-Dist: cryptography>=50.0.0
 Requires-Dist: setuptools<83.0,>=82.0.1
 Requires-Dist: grpcio-status<2.0,>=1.81.0
 Requires-Dist: protoc-gen-openapiv2>=0.0.1
@@ -27,6 +27,12 @@ Requires-Dist: python-dotenv<2.0,>=1.2.2
 Requires-Dist: Faker<41.0,>=33.0.0
 Requires-Dist: pydantic>=2.13.4
 Requires-Dist: mcp>=1.27.2
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -35,6 +41,7 @@ Dynamic: description-content-type
 Dynamic: home-page
 Dynamic: license
 Dynamic: license-file
+Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: summary
 
@@ -178,6 +185,88 @@ Explore fully functional sample applications built with popular Python framework
 |-----------|------------|-------------|
 | **FastAPI** | [scalekit-fastapi-example](https://github.com/scalekit-developers/scalekit-fastapi-example) | Modern async Python API framework |
 
+### Full Stack Auth — encrypted-session middleware for Flask, FastAPI, and Django
+
+The example above is for **Modular SSO**: Scalekit brokers the OAuth exchange with your customer's own IdP via a `connection_id`, and your app owns its own session however it likes.
+
+If instead Scalekit hosts your login UI and you want it to also manage the session lifecycle for you (**Full Stack Auth**), `scalekit-sdk-python` ships optional Flask, FastAPI, and Django extras that handle the encrypted session cookie, transparent token refresh, CSRF-safe login/callback, and full logout for you — no hand-rolled cookies, no manual refresh timing.
+
+Register these under **Dashboard → Authentication → Redirects** before testing:
+- **Redirect URI** — your `redirect_uri` (the `/callback` path). Scalekit rejects the exchange if this doesn't match exactly.
+- **Post Logout Redirect URI** — where users land after full logout. A relative path gets auto-absolutized against the request host, but the resulting absolute URL must still be registered.
+- **Initiate Login URL** — your `/login` path. Scalekit redirects here (not `/callback`) for a bookmarked login page, an IdP portal tile, or an invite/magic link — the login view already handles this correctly, including the `idp_initiated_login` case, with no extra code required.
+
+pip install "scalekit-sdk-python[flask]"  # or "scalekit-sdk-python[fastapi]" or "scalekit-sdk-python[django]"
+
+```python
+# Flask
+import os
+from flask import Flask
+from scalekit.frameworks.flask import ScalekitAuth
+
+app = Flask(__name__)
+auth = ScalekitAuth(
+    app,
+    env_url=os.environ["SCALEKIT_ENV_URL"],
+    client_id=os.environ["SCALEKIT_CLIENT_ID"],
+    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
+    redirect_uri="https://myapp.com/callback",
+    cookie_encryption_secret=os.environ["COOKIE_ENCRYPTION_SECRET"],  # openssl rand -base64 32
+)  # registers /login, /callback, /logout
+
+@app.route("/account")
+@auth.requires_auth
+def account():
+    return {"email": auth.current_user["email"]}
+```
+
+```python
+# FastAPI -- protect routes with Depends(), FastAPI's idiomatic mechanism
+import os
+from fastapi import Depends, FastAPI
+from scalekit.frameworks.fastapi import ScalekitAuth
+
+app = FastAPI()
+auth = ScalekitAuth(
+    env_url=os.environ["SCALEKIT_ENV_URL"],
+    client_id=os.environ["SCALEKIT_CLIENT_ID"],
+    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
+    redirect_uri="https://myapp.com/callback",
+    cookie_encryption_secret=os.environ["COOKIE_ENCRYPTION_SECRET"],
+)
+auth.install(app)  # registers /login, /callback, /logout
+
+@app.get("/account")
+async def account(user: dict = Depends(auth.requires_auth)):
+    return {"email": user["email"]}
+```
+
+```python
+# Django -- settings.py
+import os
+
+MIDDLEWARE = [..., "scalekit.frameworks.django.ScalekitAuthMiddleware"]
+SCALEKIT_ENV_URL = os.environ["SCALEKIT_ENV_URL"]
+SCALEKIT_CLIENT_ID = os.environ["SCALEKIT_CLIENT_ID"]
+SCALEKIT_CLIENT_SECRET = os.environ["SCALEKIT_CLIENT_SECRET"]
+SCALEKIT_REDIRECT_URI = "https://myapp.com/callback"
+SCALEKIT_COOKIE_ENCRYPTION_SECRET = os.environ["COOKIE_ENCRYPTION_SECRET"]
+
+# urls.py
+from django.urls import include, path
+urlpatterns = [path("", include("scalekit.frameworks.django")), ...]  # /login, /callback, /logout
+
+# views.py
+from django.http import JsonResponse
+from scalekit.frameworks.django import login_required
+
+@login_required
+def account(request):
+    return JsonResponse(request.scalekit_user)
+```
+
+See [`examples/flask`](./examples/flask), [`examples/fastapi`](./examples/fastapi), and [`examples/django`](./examples/django) for complete, runnable versions. For a fuller production-oriented sample app, see the framework repos above.
+
 ## 🔗 Helpful Links
 
 ### 📖 Quickstart Guides

{scalekit_sdk_python-2.16.0 → scalekit_sdk_python-2.18.0}/README.md

@@ -138,6 +138,88 @@ Explore fully functional sample applications built with popular Python framework
 |-----------|------------|-------------|
 | **FastAPI** | [scalekit-fastapi-example](https://github.com/scalekit-developers/scalekit-fastapi-example) | Modern async Python API framework |
 
+### Full Stack Auth — encrypted-session middleware for Flask, FastAPI, and Django
+
+The example above is for **Modular SSO**: Scalekit brokers the OAuth exchange with your customer's own IdP via a `connection_id`, and your app owns its own session however it likes.
+
+If instead Scalekit hosts your login UI and you want it to also manage the session lifecycle for you (**Full Stack Auth**), `scalekit-sdk-python` ships optional Flask, FastAPI, and Django extras that handle the encrypted session cookie, transparent token refresh, CSRF-safe login/callback, and full logout for you — no hand-rolled cookies, no manual refresh timing.
+
+Register these under **Dashboard → Authentication → Redirects** before testing:
+- **Redirect URI** — your `redirect_uri` (the `/callback` path). Scalekit rejects the exchange if this doesn't match exactly.
+- **Post Logout Redirect URI** — where users land after full logout. A relative path gets auto-absolutized against the request host, but the resulting absolute URL must still be registered.
+- **Initiate Login URL** — your `/login` path. Scalekit redirects here (not `/callback`) for a bookmarked login page, an IdP portal tile, or an invite/magic link — the login view already handles this correctly, including the `idp_initiated_login` case, with no extra code required.
+
+pip install "scalekit-sdk-python[flask]"  # or "scalekit-sdk-python[fastapi]" or "scalekit-sdk-python[django]"
+
+```python
+# Flask
+import os
+from flask import Flask
+from scalekit.frameworks.flask import ScalekitAuth
+
+app = Flask(__name__)
+auth = ScalekitAuth(
+    app,
+    env_url=os.environ["SCALEKIT_ENV_URL"],
+    client_id=os.environ["SCALEKIT_CLIENT_ID"],
+    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
+    redirect_uri="https://myapp.com/callback",
+    cookie_encryption_secret=os.environ["COOKIE_ENCRYPTION_SECRET"],  # openssl rand -base64 32
+)  # registers /login, /callback, /logout
+
+@app.route("/account")
+@auth.requires_auth
+def account():
+    return {"email": auth.current_user["email"]}
+```
+
+```python
+# FastAPI -- protect routes with Depends(), FastAPI's idiomatic mechanism
+import os
+from fastapi import Depends, FastAPI
+from scalekit.frameworks.fastapi import ScalekitAuth
+
+app = FastAPI()
+auth = ScalekitAuth(
+    env_url=os.environ["SCALEKIT_ENV_URL"],
+    client_id=os.environ["SCALEKIT_CLIENT_ID"],
+    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
+    redirect_uri="https://myapp.com/callback",
+    cookie_encryption_secret=os.environ["COOKIE_ENCRYPTION_SECRET"],
+)
+auth.install(app)  # registers /login, /callback, /logout
+
+@app.get("/account")
+async def account(user: dict = Depends(auth.requires_auth)):
+    return {"email": user["email"]}
+```
+
+```python
+# Django -- settings.py
+import os
+
+MIDDLEWARE = [..., "scalekit.frameworks.django.ScalekitAuthMiddleware"]
+SCALEKIT_ENV_URL = os.environ["SCALEKIT_ENV_URL"]
+SCALEKIT_CLIENT_ID = os.environ["SCALEKIT_CLIENT_ID"]
+SCALEKIT_CLIENT_SECRET = os.environ["SCALEKIT_CLIENT_SECRET"]
+SCALEKIT_REDIRECT_URI = "https://myapp.com/callback"
+SCALEKIT_COOKIE_ENCRYPTION_SECRET = os.environ["COOKIE_ENCRYPTION_SECRET"]
+
+# urls.py
+from django.urls import include, path
+urlpatterns = [path("", include("scalekit.frameworks.django")), ...]  # /login, /callback, /logout
+
+# views.py
+from django.http import JsonResponse
+from scalekit.frameworks.django import login_required
+
+@login_required
+def account(request):
+    return JsonResponse(request.scalekit_user)
+```
+
+See [`examples/flask`](./examples/flask), [`examples/fastapi`](./examples/fastapi), and [`examples/django`](./examples/django) for complete, runnable versions. For a fuller production-oriented sample app, see the framework repos above.
+
 ## 🔗 Helpful Links
 
 ### 📖 Quickstart Guides

{scalekit_sdk_python-2.16.0 → scalekit_sdk_python-2.18.0}/scalekit/_version.py

@@ -1,3 +1,3 @@
 # Single source of truth for the SDK version.
 # Import this in setup.py and scalekit/core.py — never hardcode the version elsewhere.
-__version__ = "2.16.0"
+__version__ = "2.18.0"

{scalekit_sdk_python-2.16.0 → scalekit_sdk_python-2.18.0}/scalekit/client.py

@@ -9,7 +9,7 @@ import hmac
 import hashlib
 import base64
 from datetime import datetime, timedelta, timezone
-from scalekit.core import CoreClient
+from scalekit.core import CoreClient, DEFAULT_KEEPALIVE_TIME_MS, DEFAULT_KEEPALIVE_TIMEOUT_MS
 from scalekit.domain import DomainClient
 from scalekit.connection import ConnectionClient
 from scalekit.m2m_client import M2MClient
@@ -50,23 +50,46 @@ webhook_signature_version = "v1"
 class ScalekitClient:
     """ Class definition for scalekit client """
 
-    def __init__(self, env_url: str, client_id: str, client_secret: str):
+    def __init__(
+        self,
+        env_url: str,
+        client_id: str,
+        client_secret: str,
+        keepalive_time_ms: int = DEFAULT_KEEPALIVE_TIME_MS,
+        keepalive_timeout_ms: int = DEFAULT_KEEPALIVE_TIMEOUT_MS,
+    ):
         """
         Initializer for Scalekit base class
 
-        :param env_url        : Environment URL
-        :type                 : ``` str ```
-        :param client_id      : Client ID
-        :type                 : ``` str ```
-        :param client_secret  : Client Secret
-        :type                 : ``` str ```
+        :param env_url               : Environment URL
+        :type                        : ``` str ```
+        :param client_id             : Client ID
+        :type                        : ``` str ```
+        :param client_secret         : Client Secret
+        :type                        : ``` str ```
+        :param keepalive_time_ms     : How often, in milliseconds, an idle gRPC
+                                        connection is verified before reuse.
+                                        Defaults to 60000; most callers never
+                                        need to set this. Set to 0 to disable
+                                        keepalive entirely.
+        :type                        : ``` int ```
+        :param keepalive_timeout_ms  : How long, in milliseconds, to wait for a
+                                        keepalive response before treating an
+                                        idle connection as dead. Defaults to
+                                        10000.
+        :type                        : ``` int ```
 
         :returns:
             None
         """
         try:
             self.core_client = CoreClient(
-                env_url=env_url, client_id=client_id, client_secret=client_secret)
+                env_url=env_url,
+                client_id=client_id,
+                client_secret=client_secret,
+                keepalive_time_ms=keepalive_time_ms,
+                keepalive_timeout_ms=keepalive_timeout_ms,
+            )
             self.domain = DomainClient(self.core_client)
             self.connection = ConnectionClient(self.core_client)
             self.organization = OrganizationClient(self.core_client)

{scalekit_sdk_python-2.16.0 → scalekit_sdk_python-2.18.0}/scalekit/core.py

@@ -19,6 +19,33 @@ TMetadata = TypeVar("TMetadata")
 TOKEN_ENDPOINT = "/oauth/token"
 JWKS_ENDPOINT = "/keys"
 
+# Must clear the backend's EnforcementPolicy.MinTime (30s, scalekit's
+# cmd/grpc.go) with real margin, not just match it: grpc-core pings on this
+# exact interval for as long as the channel is open (keepalive_permit_without_calls
+# below), so a value equal to MinTime leaves zero room for jitter between the
+# client's timer and the server's strike window — one early ping is a strike,
+# three and the server GOAWAYs the connection, recreating the bug this fixes.
+# 60s matches the Java SDK's default for the same reason.
+DEFAULT_KEEPALIVE_TIME_MS = 60_000
+DEFAULT_KEEPALIVE_TIMEOUT_MS = 10_000
+
+# The floor tracks DEFAULT_KEEPALIVE_TIME_MS for the reason spelled out above:
+# the backend's EnforcementPolicy.MinTime is 30s, and a value at exactly 30s has
+# zero jitter headroom — grpc's ping timer drifts slightly early, so an early
+# ping counts as a strike and enough strikes make the server GOAWAY. 60s gives
+# 2x margin over the 30s MinTime. Since there is no legitimate reason to go below
+# the default, the only sensible choices are 0 (disabled) or >= 60s. (gRPC also
+# silently clamps sub-10s values up to 10s per grpc/proposal A8, so a small value
+# never even reaches the wire as requested.) Reject 1..59999.
+MIN_KEEPALIVE_TIME_MS = 60_000
+
+# requests defaults to no timeout, so a black-holed connection blocks the
+# calling thread until the OS abandons the socket. Bound the connect and read
+# phases separately with a (connect, read) tuple.
+DEFAULT_HTTP_CONNECT_TIMEOUT_S = 10
+DEFAULT_HTTP_READ_TIMEOUT_S = 30
+DEFAULT_HTTP_TIMEOUT = (DEFAULT_HTTP_CONNECT_TIMEOUT_S, DEFAULT_HTTP_READ_TIMEOUT_S)
+
 
 class WithCall(Protocol):
     def __call__(self, request: TRequest, metadata: TMetadata) -> TResponse: ...
@@ -32,16 +59,36 @@ class CoreClient:
     api_version = "20260727"
     user_agent = f"{sdk_version} Python/{platform.python_version()} ({platform.system()}; {platform.architecture()}"
 
-    def __init__(self, env_url, client_id, client_secret):
+    def __init__(
+        self,
+        env_url,
+        client_id,
+        client_secret,
+        keepalive_time_ms: int = DEFAULT_KEEPALIVE_TIME_MS,
+        keepalive_timeout_ms: int = DEFAULT_KEEPALIVE_TIMEOUT_MS,
+    ):
         """
         Initializer for Core client
 
-        :param env_url        : Environment URL
-        :type                 : ``` str ```
-        :param client_id      : Client ID
-        :type                 : ``` str ```
-        :param client_secret  : Client Secret
-        :type                 : ``` str ```
+        :param env_url               : Environment URL
+        :type                        : ``` str ```
+        :param client_id             : Client ID
+        :type                        : ``` str ```
+        :param client_secret         : Client Secret
+        :type                        : ``` str ```
+        :param keepalive_time_ms     : How often, in milliseconds, an idle gRPC
+                                        connection is verified before reuse.
+                                        Must stay above the backend's keepalive
+                                        MinTime (30s) with real margin, or the
+                                        server treats this ping as abuse. Defaults
+                                        to 60000. Set to 0 to disable keepalive
+                                        entirely.
+        :type                        : ``` int ```
+        :param keepalive_timeout_ms  : How long, in milliseconds, to wait for a
+                                        keepalive response before treating an
+                                        idle connection as dead. Defaults to
+                                        10000.
+        :type                        : ``` int ```
         :returns
             None
         """
@@ -50,6 +97,20 @@ class CoreClient:
         self.env_url = env_url
         self.client_id = client_id
         self.client_secret = client_secret
+        # 0 means "disabled" and is allowed through deliberately; only 1..59999
+        # is rejected. A value below the 60s default leaves too little margin
+        # over the Scalekit server's 30s MinTime — an early ping gets struck as
+        # abusive and the server GOAWAYs — and gRPC silently raises sub-10s
+        # values to 10s, so a small value is never what the caller asked for.
+        if keepalive_time_ms and keepalive_time_ms < MIN_KEEPALIVE_TIME_MS:
+            raise ValueError(
+                f"keepalive_time_ms must be 0 (disabled) or >= {MIN_KEEPALIVE_TIME_MS}; "
+                f"got {keepalive_time_ms}. A value below the default leaves too little "
+                "margin over the Scalekit server's 30s MinTime (early pings are struck "
+                "as abusive), and gRPC silently raises sub-10s values to 10s."
+            )
+        self.keepalive_time_ms = keepalive_time_ms
+        self.keepalive_timeout_ms = keepalive_timeout_ms
         self.keys = {}
         self.access_token = None
         self.grpc_secure_channel = None
@@ -70,7 +131,24 @@ class CoreClient:
             channel_credentials,
             call_credentials,
         )
-        self.grpc_secure_channel = grpc.secure_channel(self.host, composite_credentials)
+        # keepalive_time_ms == 0 disables keepalive entirely: no options are
+        # passed, so grpc-core falls back to its own defaults (no idle pings).
+        channel_options = []
+        if self.keepalive_time_ms:
+            # keepalive_permit_without_calls=1 so an idle channel is still
+            # periodically verified: without it, grpc-core only sends HTTP/2
+            # keepalive PINGs while there are active calls, so a connection
+            # silently dropped by a network intermediary while idle isn't
+            # detected until the next real call is written to it.
+            channel_options = [
+                ('grpc.keepalive_time_ms', self.keepalive_time_ms),
+                ('grpc.keepalive_timeout_ms', self.keepalive_timeout_ms),
+                ('grpc.keepalive_permit_without_calls', 1),
+                ('grpc.http2.max_pings_without_data', 0),
+            ]
+        self.grpc_secure_channel = grpc.secure_channel(
+            self.host, composite_credentials, options=channel_options
+        )
 
     def __authenticate_client(self):
         """
@@ -104,6 +182,7 @@ class CoreClient:
             headers=self.get_headers(headers=headers),
             data=data,
             verify=True,
+            timeout=DEFAULT_HTTP_TIMEOUT,
         )
         if response.status_code != 200:
             raise ScalekitServerException.promote(response)
@@ -114,7 +193,9 @@ class CoreClient:
         if self.keys and len(self.keys) > 0:
             return
         response = requests.get(
-            self.env_url + JWKS_ENDPOINT, headers=self.get_headers()
+            self.env_url + JWKS_ENDPOINT,
+            headers=self.get_headers(),
+            timeout=DEFAULT_HTTP_TIMEOUT,
         )
         response = json.loads(response.content)
         keys = response["keys"]