Merge branch 'main' into feat/passwordless-support

Author: rmad17

README.md

@@ -23,7 +23,7 @@ pip install auth0-server-python
 If you’re using Poetry:
 
 ```shell
-poetry install auth0-server-python
+poetry add auth0-server-python
 ```
 
 ### 2. Create the Auth0 SDK client
@@ -40,7 +40,7 @@ auth0 = ServerClient(
     client_secret='<AUTH0_CLIENT_SECRET>',
     secret='<AUTH0_SECRET>',
     authorization_params= {
-      redirect_uri: '<AUTH0_REDIRECT_URI>',
+      'redirect_uri': '<AUTH0_REDIRECT_URI>',
     }
 )
 ```

examples/ClientInitiatedBackChannelLogin.md

@@ -15,7 +15,7 @@ Before using backchannel authentication:
 ### Initiating Backchannel Authentication
 
 ```python
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 
 # Initialize the Auth0 client
 auth0 = ServerClient(
@@ -101,7 +101,7 @@ Read more above in [Configuring the Store](./ConfigureStore.md).
 
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 
 app = FastAPI()
 

examples/ConfigureStore.md

@@ -37,7 +37,7 @@ If you’re using `auth0-fastapi`, you already have:
 2. **CookieTransactionStore** – stores short-lived transaction data (PKCE code_verifier) in another encrypted cookie.
 
 ```python
-from store.abstract import StateStore, TransactionStore
+from auth0_server_python.store import StateStore, TransactionStore
 
 class StatelessStateStore(StateStore):
     def __init__(self, secret: str, cookie_name: str = "_a0_session"):
@@ -98,9 +98,10 @@ A **stateful** approach stores only a **session ID** in the cookie, while the ac
 ### 3.1. Redis-Based Example
 Let’s walk through a `RedisStateStore` that inherits from `StateStore`:
 ```python
+import json
 import aioredis
 from typing import Any, Dict, Optional
-from store.abstract import StateStore
+from auth0_server_python.store import StateStore
 
 class RedisStateStore(StateStore):
     """
@@ -133,7 +134,6 @@ class RedisStateStore(StateStore):
         #    encrypted_data = self.encrypt(session_id, state)
         #    await self.redis_client.set(session_id, encrypted_data)
         # For demo, let's store it as JSON without encryption:
-        import json
         await self.redis_client.set(session_id, json.dumps(state))
 
         # Now set a cookie in the response with just the session_id
@@ -166,7 +166,6 @@ class RedisStateStore(StateStore):
             return None
 
         # If you used self.encrypt(...) on set, call self.decrypt(...) here.
-        import json
         return json.loads(raw_data)
 
     async def delete(
@@ -206,7 +205,6 @@ class RedisStateStore(StateStore):
         for k in keys:
             raw_data = await self.redis_client.get(k)
             if raw_data:
-                import json
                 session_data = json.loads(raw_data)
                 # If your session_data stores an internal dict with `sid` or `sub`
                 internal = session_data.get("internal", {})
@@ -240,9 +238,10 @@ Now your user’s session data is in **Redis**, and only a minimal session ID is
 If you prefer a **SQL database** for session data, here’s a `PostgresStateStore` example using [asyncpg](https://github.com/MagicStack/asyncpg).
 
 ```python
+import json
 import asyncpg
 from typing import Any, Dict, Optional
-from store.abstract import StateStore
+from auth0_server_python.store import StateStore
 
 class PostgresStateStore(StateStore):
     """
@@ -277,7 +276,6 @@ class PostgresStateStore(StateStore):
             # Optionally encrypt `state`:
             # encrypted_data = self.encrypt(session_id, state)
             # For simplicity, store as JSON
-            import json
             data_json = json.dumps(state)
 
             # Insert or update the session
@@ -322,7 +320,6 @@ class PostgresStateStore(StateStore):
             if not row:
                 return None
             # If you used encryption, do self.decrypt(...)
-            import json
             return json.loads(row["session_data"])
 
     async def delete(

examples/CustomTokenExchange.md

@@ -201,7 +201,7 @@ from auth0_server_python.error import CustomTokenExchangeError
 result = await auth0.request_session_transfer_token(
     subject_token=subject_token,            # your proof of which customer to impersonate
     subject_token_type="urn:acme:customer-subject",
-    organization=None,                      # optional; forwarded to the redirect
+    organization=None,                      # optional, sent on the mint request (separate from the redirect)
     store_options={"request": request, "response": None},
 )
 
@@ -216,7 +216,14 @@ return RedirectResponse(redirect_url)       # your framework performs the redire
 
 > **NOTE**: An actor is mandatory - an STT is only issued when the Action set one. By default the SDK sources the actor from the logged-in agent's session ID token, refreshing it when expired. If the agent is not logged in (no usable session ID token and none can be refreshed), the call fails client-side with `ACTOR_UNAVAILABLE` before any network request.
 
-> **NOTE**: To use your own actor token instead of the session, pass `actor_token` (and optionally `actor_token_type`, which defaults to the ID token URN). An explicit `actor_token` takes precedence and the session is not read at all. It must be an **unexpired, asymmetrically-signed JWT** (RS256 or PS256) - an Auth0 session ID token satisfies this; an HS256 or expired token is rejected by the server.
+> **NOTE**: To use your own actor token instead of the session, pass `actor_token` (and optionally `actor_token_type`, which defaults to the ID token URN). An explicit `actor_token` takes precedence and the session is not read at all. When `actor_token_type` is the ID token URN (the default), Auth0 validates the token, so it must be:
+>
+> - Signed with RS256 or PS256 (HS256 is rejected, it uses a shared secret).
+> - Unexpired, and carrying `sub`, `iss`, `exp`, and `iat`.
+> - Issued to the same client making the exchange (its `aud` must be that client's ID).
+> - Belonging to a user who still exists and is not blocked.
+>
+> An Auth0 ID token from the agent's own session on this client satisfies all of these. A token that fails any of them is rejected by the server.
 >
 > ```python
 > result = await auth0.request_session_transfer_token(
@@ -229,15 +236,15 @@ return RedirectResponse(redirect_url)       # your framework performs the redire
 
 ### Target: forward the STT to `/authorize`
 
-On the target, the STT rides through your normal login. `start_interactive_login` forwards arbitrary authorization parameters to `/authorize`, so your login route just passes `session_transfer_token` (and `organization`, when the STT was issued in an org context) straight through:
+On the target, the STT rides through your normal login. `start_interactive_login` forwards arbitrary authorization parameters to `/authorize`, so your login route just passes `session_transfer_token` (and `organization`, when you want the target login org-scoped) straight through:
 
 ```python
 from auth0_server_python.auth_types import StartInteractiveLoginOptions
 
 url = await auth0.start_interactive_login(
     StartInteractiveLoginOptions(authorization_params={
         "session_transfer_token": request.query_params["session_transfer_token"],
-        # "organization": org,   # when the STT was issued in an org context
+        # "organization": org,   # when you want the target login org-scoped
     }),
     store_options={"request": request, "response": None},
 )

examples/MultipleCustomDomains.md

@@ -19,7 +19,7 @@ See [Security Best Practices](#security-best-practices) for important guidance o
 For applications with a single Auth0 domain:
 
 ```python
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 
 client = ServerClient(
     domain="login.yourapp.com",  # Static string
@@ -34,7 +34,7 @@ client = ServerClient(
 For MCD support, provide a domain resolver function that receives a `DomainResolverContext`:
 
 ```python
-from auth0_server_python import ServerClient
+from auth0_server_python.auth_server import ServerClient
 from auth0_server_python.auth_types import DomainResolverContext
 
 # Map your app hostnames to Auth0 custom domains

examples/RetrievingData.md

@@ -5,12 +5,12 @@
 The SDK's `get_user()` can be used to retrieve the current logged-in user:
 
 ```python
-user = await serverClient.get_user();
+user = await server_client.get_user()
 ```
 
 ### Passing Store Options
 
-Just like most methods, `getUser` accept an argument that is used to pass to the configured Transaction and State Store:
+Just like most methods, `get_user` accept an argument that is used to pass to the configured Transaction and State Store:
 
 ```python
 store_options = {
@@ -27,7 +27,7 @@ Read more above in [Configuring the Store](./ConfigureStore.md).
 The SDK's `get_session()` can be used to retrieve the current session data:
 
 ```python
-session = await serverClient.get_session();
+session = await server_client.get_session()
 ```
 
 ### Passing Store Options
@@ -58,7 +58,7 @@ In order to do this, the SDK needs access to a Refresh Token. By default, the SD
 
 ### Passing Store Options
 
-Just like most methods, `getAccessToken` accept an argument that is used to pass to the configured Transaction and State Store:
+Just like most methods, `get_access_token` accept an argument that is used to pass to the configured Transaction and State Store:
 
 ```python
 store_options = {
@@ -225,7 +225,7 @@ token = await server_client.get_access_token(audience="https://api.example.com")
 
 # Avoid unless necessary: Dynamic scopes increase session size
 token = await server_client.get_access_token(
-    audience="https://api.example.com"
+    audience="https://api.example.com",
     scope="openid profile email read:products write:products admin:all"
 )
 ```
@@ -244,7 +244,7 @@ access_token_for_google = await server_client.get_access_token_for_connection(co
 ```
 
 - `connection`: The connection for which an access token should be retrieved, e.g. `google-oauth2` for Google.
-- `loginHint`: Optional login hint to inform which connection account to use, can be useful when multiple accounts for the connection exist for the same user. 
+- `login_hint`: Optional login hint to inform which connection account to use, can be useful when multiple accounts for the connection exist for the same user. 
 
 The SDK will cache the token internally, and return it from the cache when not expired. When no token is found in the cache, or the token is expired, calling `get_access_token_for_connection()` will call Auth0 to retrieve a new token and update the cache.
 

src/auth0_server_python/auth_server/server_client.py

@@ -2882,6 +2882,7 @@ async def request_session_transfer_token(
 
         Raises:
             CustomTokenExchangeError: If no actor can be resolved or the exchange fails
+            InvalidArgumentError: If organization is provided but blank
         """
         try:
             # Validate the subject up front - before any session read/refresh/network.
@@ -2896,6 +2897,9 @@ async def request_session_transfer_token(
                     "subject_token_type cannot be empty or whitespace-only"
                 )
 
+            if organization is not None and not organization.strip():
+                raise InvalidArgumentError("organization", "organization must not be blank")
+
             actor_token, actor_token_type = await self._resolve_actor_token(
                 actor_token, actor_token_type, store_options)
 
@@ -2924,7 +2928,7 @@ async def request_session_transfer_token(
                 token_type=response.token_type,
                 scope=response.scope,
             )
-        except (CustomTokenExchangeError, ApiError):
+        except (CustomTokenExchangeError, InvalidArgumentError, ApiError):
             raise
         except Exception as e:
             raise CustomTokenExchangeError(

src/auth0_server_python/tests/test_server_client.py

@@ -4227,6 +4227,51 @@ def test_build_session_transfer_redirect_rejects_blank_organization():
             "https://app.example.com/auth/login", _stt_result(), organization="  ")
 
 
+@pytest.mark.asyncio
+async def test_request_session_transfer_token_forwards_organization_on_mint(mocker):
+    """A provided organization is forwarded onto the mint request."""
+    client, post_mock = _stt_client(mocker)
+
+    await client.request_session_transfer_token(
+        subject_token="subj", subject_token_type="urn:acme:sub", actor_token="a",
+        organization="org_abc123",
+    )
+
+    assert post_mock.post.call_args[1]["data"]["organization"] == "org_abc123"
+
+
+@pytest.mark.asyncio
+async def test_request_session_transfer_token_omits_organization_when_absent(mocker):
+    """No organization passed → the parameter is absent from the mint request, not empty."""
+    client, post_mock = _stt_client(mocker)
+
+    await client.request_session_transfer_token(
+        subject_token="subj", subject_token_type="urn:acme:sub", actor_token="a",
+    )
+
+    assert "organization" not in post_mock.post.call_args[1]["data"]
+
+
+@pytest.mark.asyncio
+async def test_request_session_transfer_token_rejects_blank_organization_before_refresh(mocker):
+    """A blank organization is rejected before the expired session is refreshed or persisted."""
+    client, post_mock = _stt_client(mocker)
+    client._state_store.get.return_value = {"id_token": "stale", "refresh_token": "rt"}
+    usable = mocker.patch.object(client, "_is_id_token_usable")
+    refresh = mocker.patch.object(client, "get_token_by_refresh_token")
+
+    with pytest.raises(InvalidArgumentError):
+        await client.request_session_transfer_token(
+            subject_token="subj", subject_token_type="urn:acme:sub",
+            organization="   ",
+        )
+
+    refresh.assert_not_called()
+    usable.assert_not_called()
+    client._state_store.set.assert_not_called()
+    post_mock.post.assert_not_called()
+
+
 @pytest.mark.asyncio
 async def test_request_session_transfer_token_surfaces_server_issued_token_type(mocker):
     """A non-STT issued_token_type is surfaced verbatim, never fabricated as the STT URN."""