Merge branch 'feat/passwordless-support-ca' of github.com:auth0/auth0-server-python into feat/passwordless-support-ca

# Conflicts:
#	src/auth0_server_python/error/__init__.py

Author: rmad17

examples/Passwordless.md

@@ -3,7 +3,7 @@
 Passwordless lets users sign in with a one-time code sent by email or SMS, or with a magic link sent by email. This guide covers the **embedded login** flow on `ServerClient.passwordless` and how each path establishes a server-side session.
 
 > [!NOTE]
-> Passwordless API flows use Auth0 Legacy Passwordless connections (`email` and `sms`). Enable the **Passwordless OTP** grant for your application. See the [Auth0 Passwordless API documentation](https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints).
+> Passwordless API flows use Auth0 Passwordless connections (`email` and `sms`). Enable the **Passwordless OTP** grant for your application. See the [Auth0 Passwordless API documentation](https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints).
 
 > [!IMPORTANT]
 > These flows are for confidential server-side applications. Tokens stay on the server. The browser should only receive your application's session cookie or opaque session reference.
@@ -35,36 +35,20 @@ OTP start does **not** create a session. The session exists only after `verify()
 ## Prerequisites
 
 These flows require a **Regular Web Application**. Passwordless token exchange
-needs a client secret, which a public/SPA client cannot hold safely.
+needs a client secret, which a public client cannot hold safely.
 
-Two tenant-level settings are also required and are easy to miss because
-neither failure mode looks like a configuration problem:
+Two tenant-level settings are also required:
 
 1. **Authentication Profile must be "Identifier First."** The default
    "Universal Login" profile blocks the direct `/oauth/token` call this SDK
    uses for OTP verification. Without it, OTP `verify()` fails with
    `unauthorized_client`. Set it under your tenant's Authentication Profile
    settings. (Skip this if you only use passwordless via Universal Login
    redirects rather than this SDK's embedded flow.)
-2. **Enable the Passwordless OTP grant type** on your application
-   (**Applications -> Your App -> Advanced Settings -> Grant Types**). Without
+2. **Enable the Passwordless OTP grant type** on your application. Without
    it, OTP verification also fails with `unauthorized_client`.
 3. **Magic link only.** Set the tenant flag
-   `universal_login.passwordless.allow_magiclink_verify_without_session` to
-   `true` via the Management API:
-
-   ```
-   PATCH /api/v2/tenants/settings
-   { "universal_login": { "passwordless": { "allow_magiclink_verify_without_session": true } } }
-   ```
-
-   This is required for **any** server-side SDK completing magic link (this
-   one, Express, Next.js, etc.). The browser that opens the emailed link is
-   not guaranteed to be the same browser/session that started the flow.
-   Without it, the user sees: *"The link must be opened on the same device
-   and browser from which you submitted your email address."* This flag is
-   not documented in the public Auth0 API reference, so if you don't set it
-   here you will not discover it from a 400 error message.
+   `universal_login.passwordless.allow_magiclink_verify_without_session` to `true`.
 
 ```python
 from auth0_server_python.auth_server.server_client import ServerClient
@@ -96,7 +80,6 @@ start_result = await server_client.passwordless.start(
     store_options={"request": request, "response": response},
 )
 
-# start_result.id is Auth0's request identifier when returned by the API.
 ```
 
 ### Step 2 - Verify the code and establish the session
@@ -297,7 +280,7 @@ except MfaRequiredError as e:
 ```
 
 > [!NOTE]
-> Passwordless OTP MFA is like passkey-first MFA: there is no existing application session until MFA verification succeeds. `persist=True` creates the initial SDK session when the MFA response includes an ID token.
+> For Passwordless OTP MFA there is no existing application session until MFA verification succeeds. `persist=True` creates the initial SDK session when the MFA response includes an ID token.
 
 ## Error Handling
 

references/docs-update.md

@@ -63,3 +63,4 @@ it from `README.md`'s section for the feature. Name the file after the flow, mat
 | CIBA | `examples/ClientInitiatedBackChannelLogin.md` |
 | MCD domain resolver | `examples/MultipleCustomDomains.md` |
 | Account linking / unlinking | `examples/UserLinking.md` |
+| Passwordless email/SMS OTP + magic link | `examples/Passwordless.md` |

src/auth0_server_python/auth_server/passwordless_client.py

@@ -1,17 +1,15 @@
 """
 Passwordless Client for auth0-server-python SDK.
 
-Implements embedded passwordless login (Legacy Passwordless connections) for a
-confidential (Regular Web App) client:
+Implements embedded passwordless login for a client:
 
 * Email OTP / SMS OTP - ``start()`` sends a code, ``verify()`` exchanges it for
   tokens via the passwordless-OTP grant and establishes a server-side session.
 * Magic link - ``start(send="link")`` emails a one-click link. Completion is
   handled by the standard callback (``ServerClient.complete_interactive_login``),
   not by ``verify()``.
 
-Tokens never leave the server. The browser holds only the opaque session
-reference (RWA / BFF posture).
+Tokens never leave the server. The browser holds only the opaque session.
 """
 
 from typing import TYPE_CHECKING, Any, Optional
@@ -45,10 +43,7 @@
 PASSWORDLESS_OTP_GRANT_TYPE = "http://auth0.com/oauth/grant-type/passwordless/otp"
 DEFAULT_PASSWORDLESS_EMAIL_SCOPE = "openid profile email"
 DEFAULT_PASSWORDLESS_SMS_SCOPE = "openid profile"
-# Header Auth0 reads for the real end-user IP (confidential clients with
-# "Trust Token Endpoint IP Header" enabled).
 FORWARDED_FOR_HEADER = "auth0-forwarded-for"
-# Cap on a non-JSON error body retained as an exception cause.
 _RAW_ERROR_BODY_LIMIT = 2048
 
 
@@ -57,8 +52,7 @@ class PasswordlessClient:
     Client for Auth0 embedded passwordless operations.
 
     Composes the parent :class:`ServerClient` to reuse domain resolution, OIDC
-    discovery, JWKS/ID-token verification, and session persistence rather than
-    duplicating that security-critical logic.
+    discovery, JWKS/ID-token verification, and session persistence.
     """
 
     def __init__(self, server_client: "ServerClient"):
@@ -333,22 +327,11 @@ def _prepare_magic_link_start(
         if store_options is None:
             raise MissingRequiredArgumentError("store_options")
 
-        # Auth0 echoes `state` back unvalidated on this flow. It does not
-        # compare it server-side, and the clicked link's query string can
-        # overwrite whatever was originally stored. This SDK's single-use,
-        # state-keyed transaction plus the exact-match, SDK-owned
-        # `redirect_uri` is therefore the only CSRF and authorization-code-
-        # interception control on magic link. The server provides none.
-        # Never make `state`/`redirect_uri` caller-overridable.
         state = PKCE.generate_random_string(32)
         auth_params["redirect_uri"] = redirect_uri
         auth_params["response_type"] = "code"
         auth_params["state"] = state
         auth_params.setdefault("scope", DEFAULT_PASSWORDLESS_EMAIL_SCOPE)
-        # A caller-supplied scope replaces the default wholesale, so `openid`
-        # is re-injected rather than trusted: without it Auth0 returns no ID
-        # token and the callback never demands one, leaving a session with no
-        # signature-verified claims.
         auth_params["scope"] = self._ensure_openid_scope(auth_params["scope"])
 
         transaction_data = TransactionData(
@@ -481,7 +464,7 @@ def _raw_text(response) -> Optional[str]:
         error body.
 
         Capped because the body may be an HTML error page, WAF block page, or
-        proxy dump: it is attached as the exception ``cause`` and reaches any
+        proxy dump: it is attached as the exception `cause` and reaches any
         logger that serializes it, and httpx applies no response-size limit.
         """
         try:

src/auth0_server_python/auth_server/server_client.py

@@ -872,7 +872,6 @@ async def complete_interactive_login(
         if transaction_data.app_state:
             result["app_state"] = transaction_data.app_state
 
-        # For RAR
         authorization_details = token_response.get("authorization_details")
         if authorization_details:
             result["authorization_details"] = authorization_details

src/auth0_server_python/auth_types/__init__.py

@@ -917,14 +917,8 @@ class _StartPasswordlessBase(BaseModel):
     # BCP 47 tag (e.g. "fr", "en-US"). Forwarded as x-request-language to
     # localise the email/SMS template.
     language: Optional[str] = None
-    # Extra params forwarded to /passwordless/start. SDK-owned keys
-    # (PASSWORDLESS_RESERVED_AUTH_PARAMS) are stripped in the client.
     auth_params: Optional[dict[str, Any]] = None
-    # Attempted solution to a captcha challenge, when the tenant requires one.
     captcha: Optional[str] = None
-    # End-user client IP, relayed to Auth0 as `auth0-forwarded-for` so brute-force
-    # and suspicious-IP protection key on the real user, not the app server. Only
-    # honored for confidential clients with "Trust Token Endpoint IP Header" on.
     client_ip: Optional[str] = None
 
     @field_validator("language")
@@ -975,16 +969,11 @@ class VerifyPasswordlessOtpOptions(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     connection: PasswordlessConnection
-    # Sent to Auth0 as the `otp` form parameter.
     verification_code: str
     email: Optional[str] = None
     phone_number: Optional[str] = None
     scope: Optional[str] = None
     audience: Optional[str] = None
-    # End-user client IP, relayed to Auth0 as `auth0-forwarded-for` on the OTP
-    # token exchange so brute-force protection keys on the real user, not the
-    # app server. Honored only for confidential clients with "Trust Token
-    # Endpoint IP Header" enabled.
     client_ip: Optional[str] = None
 
     @field_validator("phone_number")
@@ -1019,7 +1008,6 @@ def username(self) -> str:
 class PasswordlessStartResult(BaseModel):
     """Success payload from POST /passwordless/start."""
 
-    # Auth0 returns the request id as `_id`. Aliased so `.id` is populated.
     id: Optional[str] = Field(default=None, alias="_id")
 
     class Config:

src/auth0_server_python/error/__init__.py

@@ -1,5 +1,5 @@
 """
-Error classes for the auth0-server-python SDK.
+Error classes for the SDK.
 These exceptions provide specific error types for different failure scenarios.
 """