fix: stop leaking secrets through logs and session storage

.gitignore

@@ -76,4 +76,14 @@ docs/_build/
 .env
 .env.*
 !.env.example
-!.env.sample
+!.env.sample
+*.env
+
+# macOS
+.DS_Store
+
+# Cloudflare Wrangler local state
+.wrangler/
+
+# Personal editor workspaces
+*.code-workspace

CHANGELOG.md

@@ -7,7 +7,76 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Security
+- **Secrets in session storage**: `client_secret` is no longer written to session storage
+  (which may be a browser cookie); it is kept in process memory. Legacy sessions that still
+  contain it are cleaned on load and save.
+- **Secrets in logs**: the SDK no longer logs the token-exchange payload or response, the OAuth
+  `state`, session contents, user details or storage values, and no longer raises its own
+  loggers to INFO.
+- **Token endpoint errors**: a failed code exchange now reports only the HTTP status and the
+  standard OAuth `error` code. The response body is no longer included in exceptions, logs, or
+  the Flask / FastAPI callback responses, which now return a generic HTTP 400.
+- **OAuth callback validation**: `state` is always required and must match the login started
+  in the same session; the ID token `nonce` is verified. Both are single-use. The ID token's
+  issuer must match the configured Kinde host, its audience must include the client ID, and it
+  must not be expired.
+- **FastAPI**: the callback no longer forwards the consumed `state` to the post-login URL, and
+  logout now clears the user's server-side tokens (previously only the session cookie was
+  cleared).
+- **Flask**: the session is bound to a user only after a successful callback.
+- **Logout after a restart or on another worker**: the Flask and FastAPI `/logout` routes cleared
+  the session before logging out, so the SDK couldn't find the user's tokens there: the access
+  token wasn't revoked and the logout URL had no `id_token_hint`. They now log out first.
+- **Legacy Account API helpers**: the helper functions in `kinde_sdk.core.helpers` now log only
+  the HTTP status and the standard OAuth `error` code when a request fails, not the response's
+  `error_description`.
+- **Account API errors**: the permissions, roles and feature flag helpers log only the
+  exception type and HTTP status when an Account API call fails, not the response body.
+
+### Changed
+- Callbacks without a `state` parameter, and token responses without an ID token (e.g. custom
+  scopes that omit `openid`), are now rejected.
+
 ### Fixed
+- **Token refresh deadlock**: `TokenManager.get_access_token()` hung forever when the access
+  token had expired and a refresh token was available (non-reentrant lock re-acquired in
+  `set_tokens`).
+- **Account API host**: permission, role and feature flag lookups with `force_api=True` were sent
+  to the generated client's placeholder host (`your_kinde_subdomain.kinde.com`) and silently
+  returned empty results. They now use the configured Kinde host (`OAuth(host=...)` or
+  `KINDE_HOST`). The access token's `iss` is used only when it exactly matches a configured
+  host; otherwise the configured host is used and a warning is logged.
+- **Account API permissions**: with `force_api=True`, `get_permission()` never granted anything
+  because the API's `{id, name, key}` objects were compared with the key string;
+  `get_permissions()` now returns keys, as in token mode.
+- **Account API feature flags**: with `force_api=True`, flags were read from a non-existent
+  `data.flags` attribute and always came back empty; the `data.feature_flags` list is now parsed.
+- **Management API feature flags**: `environments_api.get_environement_feature_flags()` and
+  `organizations_api.get_organization_feature_flags()` raised a `ValidationError` for any
+  boolean or integer flag, because the published spec declares every flag value as a string.
+  Values are now `bool`, `int` or `str`, and the generator re-applies the correction
+  (`SPEC_ERRATA` in `generate_management_sdk.py`) until the spec is fixed upstream.
+- **Signed out after a restart or on another worker**: session data is keyed by a device ID that
+  was generated per process and never saved (there is no request at startup), so after a restart,
+  or with several workers (e.g. `gunicorn -w 4`), the tokens in a user's session couldn't be found.
+  The device ID is now stored in the user's session and read from there. Sessions created
+  before this fix will need to sign in once more.
+- **Refreshed tokens persisted**: tokens from a refresh were only kept in process memory, so with
+  server-side or cookie sessions, a restart or another worker kept using (and refreshing with) the
+  old ones. `UserSession` now writes them back to session storage after every refresh.
+- **StorageManager.reset() deadlock**: `reset()` held the class lock while calling `initialize()`,
+  which takes the same non-reentrant lock; the lock is now reentrant.
+- **KindeSessionManagement**: the standalone-only guard never fired, because constructing the
+  `NullFramework` singleton always marks it initialized; it now raises inside Flask / FastAPI
+  apps as documented, and requires a standalone `OAuth` client to exist.
+- **Feature flag codes**: `get_all_flags()` in token mode returned flags with an empty `code`.
+- **Logout redirect**: the logout URL now includes the `redirect` parameter that Kinde's
+  `/logout` endpoint reads (`redirect_uri` is still sent). The target is
+  `post_logout_redirect_uri`, then the new `KINDE_POST_LOGOUT_REDIRECT_URI` environment
+  variable, then `KINDE_REDIRECT_URI` as before, so the built-in `/logout` routes can return
+  users to your home page instead of the callback.
+- Previously unbounded `requests` calls now use a 30 second timeout.
 - **CI**: Hardened `renovate.json` so Renovate can no longer re-propose bumping the Python
   `<3.12` `django` pin in `requirements.txt` to Django 6.x (Django 6.0+ requires Python
   3.12+). Django is a test-only dependency for this SDK (no runtime usage), and the

README.md

@@ -69,7 +69,8 @@ Create a `.env` file with your Kinde credentials:
 KINDE_CLIENT_ID=your_client_id
 KINDE_CLIENT_SECRET=your_client_secret
 KINDE_REDIRECT_URI=http://localhost:8000/callback
-KINDE_DOMAIN=your_kinde_domain
+KINDE_POST_LOGOUT_REDIRECT_URI=http://localhost:8000
+KINDE_HOST=https://your_kinde_domain.kinde.com
 ```
 
 #### Available Routes
@@ -141,7 +142,8 @@ Create a `.env` file with your Kinde credentials:
 KINDE_CLIENT_ID=your_client_id
 KINDE_CLIENT_SECRET=your_client_secret
 KINDE_REDIRECT_URI=http://localhost:5000/callback
-KINDE_DOMAIN=your_kinde_domain
+KINDE_POST_LOGOUT_REDIRECT_URI=http://localhost:5000
+KINDE_HOST=https://your_kinde_domain.kinde.com
 ```
 
 #### Available Routes
@@ -179,11 +181,41 @@ def protected_route():
 For both FastAPI and Flask integrations:
 
 1. Always use HTTPS in production
-2. Use a secure session secret key
-3. Implement proper state parameter validation
+2. Use a secure session secret key (`SECRET_KEY` for Flask, the session middleware key for FastAPI)
+3. Use **server-side sessions** (see below)
 4. Handle OAuth errors appropriately
-5. Implement proper session management
-6. Consider implementing CSRF protection
+5. Consider implementing CSRF protection for your own state-changing routes
+
+**What the SDK keeps in the session.** After login the session holds the user's access token,
+refresh token and ID token (plus their decoded claims) so the user stays signed in across
+requests. During a login it also holds the OAuth `state`, the `nonce` and the PKCE
+`code_verifier` until the callback consumes them. The `client_secret` is never written to the
+session: it is held in process memory only.
+
+Because those values are bearer credentials, keep the session data on the server:
+
+- **Flask**: the integration configures Flask-Session with `SESSION_TYPE=filesystem` by default.
+  Set `SESSION_FILE_DIR` to a private directory, or use `redis` in multi-instance deployments.
+- **FastAPI**: Starlette's `SessionMiddleware` stores the whole session in a signed (not
+  encrypted) cookie, so the tokens would travel in the cookie. Prefer a server-side session
+  middleware that keeps only a session ID in the cookie.
+
+**Logout.** The logout URL carries the ID token as the standard OIDC `id_token_hint` query
+parameter, so it can appear in browser history and in the access logs of the identity
+provider. Access and refresh tokens are never put in URLs.
+
+**Callback validation.** The `/callback` route only accepts a callback for a login started by
+this SDK in the same session: the `state` parameter is required and must match, and the ID
+token's `nonce` must match the one sent with the authorization request. Both are single-use.
+As a consequence:
+
+- callbacks without a `state` parameter are rejected with HTTP 400;
+- logins must request the `openid` scope (the SDK default) so that an ID token is returned.
+
+**Errors and logs.** Callback failures return a generic HTTP 400 message; details such as the
+token endpoint's response body are never echoed to the browser or written to the logs. The SDK
+does not log secrets, authorization codes or tokens at any log level, and it does not change
+the level of your loggers.
 
 # Kinde Management API Module
 

generate_management_sdk.py

@@ -645,6 +645,59 @@ def add_custom_imports(config: Dict[str, Any]):
     print("✓ Added custom imports to __init__.py")
 
 
+# =============================================================================
+# SPEC ERRATA
+# =============================================================================
+
+# Places where the published spec disagrees with what the API returns.
+# Each entry: (model file, text the generator emits, corrected text).
+SPEC_ERRATA = [
+    # Flag values are typed by "type" (str, int or bool), but the spec declares them as strings,
+    # so boolean and integer flags failed validation.
+    (
+        "models/get_organization_feature_flags_response_feature_flags_value.py",
+        "    value: Optional[StrictStr] = None",
+        "    value: Optional[Union[StrictBool, StrictInt, StrictStr]] = None",
+    ),
+    (
+        "models/get_organization_feature_flags_response_feature_flags_value.py",
+        "from pydantic import BaseModel, ConfigDict, StrictStr, field_validator\n"
+        "from typing import Any, ClassVar, Dict, List, Optional\n",
+        "from pydantic import BaseModel, ConfigDict, StrictBool, StrictInt, StrictStr, field_validator\n"
+        "from typing import Any, ClassVar, Dict, List, Optional, Union\n",
+    ),
+]
+
+
+def apply_spec_errata(config: Dict[str, Any]) -> bool:
+    """Correct generated models where the spec doesn't match the API.
+
+    Returns False if a correction can't be applied, so generation fails instead of
+    shipping the bug the correction fixes.
+    """
+    print_section("Applying Spec Errata")
+
+    output_dir = Path(config["output_dir"])
+    ok = True
+    for relative_path, generated, corrected in SPEC_ERRATA:
+        path = output_dir / relative_path
+        if not path.exists():
+            print(f"❌ {relative_path} not found; update SPEC_ERRATA")
+            ok = False
+            continue
+        content = path.read_text(encoding="utf-8")
+        if corrected in content:
+            continue
+        if generated not in content:
+            print(f"❌ {relative_path} changed upstream; update the entry in SPEC_ERRATA, "
+                  "or remove it if the spec is now correct")
+            ok = False
+            continue
+        path.write_text(content.replace(generated, corrected), encoding="utf-8")
+        print(f"✓ Patched {relative_path}")
+    return ok
+
+
 # =============================================================================
 # VALIDATION
 # =============================================================================
@@ -799,6 +852,10 @@ def generate_single_sdk(skip_tests: bool, no_diff: bool) -> bool:
 
     # Step 3: Add custom imports
     add_custom_imports(config)
+
+    # Step 3b: Correct models where the published spec is wrong
+    if not apply_spec_errata(config):
+        return False
 
     # Step 4: Validate
     if not validate_generation(config):

kinde_fastapi/examples/management_token_example.py

@@ -26,8 +26,8 @@
 # Extract, introspect, and validate management token from header
 def get_management_token(credentials: HTTPAuthorizationCredentials = Depends(security)) -> ManagementTokenManager:
     logger.debug("Starting token validation")
+    # Never log the bearer token, not even a prefix
     bearer_token = credentials.credentials
-    logger.debug(f"Received bearer token (first 20 chars): {bearer_token[:20]}...")
 
     # SDK config from env
     domain = os.getenv("KINDE_HOST", "https://app.kinde.com")
@@ -53,10 +53,10 @@ def get_management_token(credentials: HTTPAuthorizationCredentials = Depends(sec
             client_id=client_id,
             client_secret=client_secret
         )
-        logger.debug(f"ManagementTokenManager instantiated {bearer_token}")
+        logger.debug("ManagementTokenManager instantiated")
 
         introspection_result = token_manager.validate_and_set_via_introspection(bearer_token)
-        logger.debug(f"Introspection result: {introspection_result}")
+        logger.debug(f"Introspection active: {bool(introspection_result.get('active'))}")
 
         access_token = token_manager.get_access_token()
         if not access_token:
@@ -74,10 +74,10 @@ def get_management_token(credentials: HTTPAuthorizationCredentials = Depends(sec
             headers={"WWW-Authenticate": "Bearer"}
         )
     except Exception as e:
-        logger.error(f"Exception in token validation: {str(e)}", exc_info=True)
+        logger.error(f"Exception in token validation: {type(e).__name__}")
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
-            detail=f"Token introspection failed: {str(e)}",
+            detail="Token introspection failed",
             headers={"WWW-Authenticate": "Bearer"}
         )
 
@@ -107,10 +107,10 @@ async def get_users(token_manager: ManagementTokenManager = Depends(get_manageme
             "users": users_response.users if users_response.users else []  # In production, filter sensitive data
         }
     except Exception as e:
-        logger.error(f"Error in get_users: {str(e)}", exc_info=True)
+        logger.error(f"Error in get_users: {type(e).__name__}")
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to fetch users: {str(e)}"
+            detail="Failed to fetch users"
         ) from e
 
 # Run the app

kinde_fastapi/framework/fastapi_framework.py

@@ -3,6 +3,7 @@
 from fastapi.responses import RedirectResponse, HTMLResponse
 from kinde_sdk.core.framework.framework_interface import FrameworkInterface
 from kinde_sdk.auth.oauth import OAuth
+from kinde_sdk.core.exceptions import KindeLoginException, KindeTokenException
 from ..middleware.framework_middleware import FrameworkMiddleware
 import os
 import uuid
@@ -139,7 +140,6 @@ async def login(request: Request):
                 login_options['invitation_code'] = invitation_code
 
             url = await self._oauth.login(login_options)
-            self._logger.warning(f"[Login] Session is: {request.session}")
             return RedirectResponse(url=url)
 
         # Callback route
@@ -182,17 +182,32 @@ async def callback(request: Request, code: Optional[str] = None, state: Optional
 
                         return RedirectResponse(login_url)
                     except Exception as ex:
-                        return HTMLResponse(f"Error parsing reauth state: {str(ex)}", status_code=400)
+                        self._logger.warning("Invalid reauth state: %s", type(ex).__name__)
+                        return HTMLResponse("Error parsing reauth state", status_code=400)
+
+            # Reject before handle_redirect, which would consume the pending state
+            if not code:
+                return HTMLResponse("Authentication failed: Missing authorization code", status_code=400)
 
             user_id = request.session.get('user_id') or str(uuid.uuid4())
 
+            # Exception messages can carry token-endpoint details, so they are
+            # logged by type only and never returned to the browser
             try:
                 assert self._oauth is not None
                 await self._oauth.handle_redirect(code, user_id, state)
+            except KindeLoginException:
+                # Missing, forged or stale callbacks are client errors, as in the Flask route
+                self._logger.warning("OAuth callback rejected")
+                return HTMLResponse("Authentication failed: invalid or expired login request", status_code=400)
+            except KindeTokenException:
+                # Kinde rejected the authorization code; the message is already logged by type and status
+                self._logger.warning("OAuth callback token exchange failed")
+                return HTMLResponse("Authentication failed", status_code=400)
             except Exception as e:
-                if "State not found" in str(e):
-                    return HTMLResponse("Error: State not found. Please check Kinde Python SDK documentation.\n" + str(e), status_code=500)
-                raise e
+                # Anything else is a server-side fault, not a bad request
+                self._logger.error("OAuth callback failed: %s", type(e).__name__)
+                return HTMLResponse("Authentication failed", status_code=500)
 
             request.session['user_id'] = user_id
 
@@ -206,23 +221,28 @@ async def callback(request: Request, code: Optional[str] = None, state: Optional
             if not post_login_redirect.startswith('http'):
                 post_login_redirect = str(request.base_url).rstrip('/') + post_login_redirect
 
-            parsed = urlparse(post_login_redirect)
-            if state:
-                query_dict = parse_qs(parsed.query)
-                query_dict['state'] = [state]
-                new_query = urlencode(query_dict, doseq=True)
-                redirect_url = urlunparse((parsed.scheme, parsed.netloc, parsed.path, parsed.params, new_query, parsed.fragment))
-            else:
-                redirect_url = post_login_redirect
-
-            return RedirectResponse(redirect_url)
+            # The consumed OAuth state is not forwarded: it would only end up in
+            # browser history, Referer headers and access logs
+            return RedirectResponse(post_login_redirect)
 
         # Logout route
         @self.app.get("/logout")
         async def logout(request: Request):
             """Logout the user and redirect to Kinde logout page."""
+            # Pass the user_id so the SDK also drops the server-side tokens
+            user_id = request.session.get('user_id')
+            # Log out before clearing the session: after a restart, or on another worker,
+            # the SDK reads the user's tokens from the session to revoke them and to build
+            # the logout URL
+            try:
+                logout_url = await self._oauth.logout(user_id)
+            except Exception as e:
+                # Still sign the user out here and at Kinde. Returning a response (not
+                # raising) is what saves the cleared session to the cookie
+                self._logger.error("Logout failed: %s", type(e).__name__)
+                logout_url = await self._oauth.logout()
             request.session.clear()
-            return RedirectResponse(url=await self._oauth.logout())
+            return RedirectResponse(url=logout_url)
 
         # Register route
         @self.app.get("/register")