workos 1.5.1__py3-none-any.whl → 5.38.0__py3-none-any.whl

workos/pipes.py

@@ -0,0 +1,93 @@
+from typing import Dict, Optional, Protocol
+
+from workos.types.pipes import (
+    GetAccessTokenFailureResponse,
+    GetAccessTokenResponse,
+    GetAccessTokenSuccessResponse,
+)
+from workos.typing.sync_or_async import SyncOrAsync
+from workos.utils.http_client import AsyncHTTPClient, SyncHTTPClient
+from workos.utils.request_helper import REQUEST_METHOD_POST
+
+
+class PipesModule(Protocol):
+    """Protocol defining the Pipes module interface."""
+
+    def get_access_token(
+        self,
+        *,
+        provider: str,
+        user_id: str,
+        organization_id: Optional[str] = None,
+    ) -> SyncOrAsync[GetAccessTokenResponse]:
+        """Retrieve an access token for a third-party provider.
+
+        Kwargs:
+            provider (str): The third-party provider identifier
+            user_id (str): The WorkOS user ID
+            organization_id (str, optional): The WorkOS organization ID
+
+        Returns:
+            GetAccessTokenResponse: Success response with token or failure response with error
+        """
+        ...
+
+
+class Pipes(PipesModule):
+    """Sync implementation of the Pipes module."""
+
+    _http_client: SyncHTTPClient
+
+    def __init__(self, http_client: SyncHTTPClient):
+        self._http_client = http_client
+
+    def get_access_token(
+        self,
+        *,
+        provider: str,
+        user_id: str,
+        organization_id: Optional[str] = None,
+    ) -> GetAccessTokenResponse:
+        json_data: Dict[str, str] = {"user_id": user_id}
+        if organization_id is not None:
+            json_data["organization_id"] = organization_id
+
+        response = self._http_client.request(
+            f"data-integrations/{provider}/token",
+            method=REQUEST_METHOD_POST,
+            json=json_data,
+        )
+
+        if response.get("active") is True:
+            return GetAccessTokenSuccessResponse.model_validate(response)
+        return GetAccessTokenFailureResponse.model_validate(response)
+
+
+class AsyncPipes(PipesModule):
+    """Async implementation of the Pipes module."""
+
+    _http_client: AsyncHTTPClient
+
+    def __init__(self, http_client: AsyncHTTPClient):
+        self._http_client = http_client
+
+    async def get_access_token(
+        self,
+        *,
+        provider: str,
+        user_id: str,
+        organization_id: Optional[str] = None,
+    ) -> GetAccessTokenResponse:
+        json_data: Dict[str, str] = {"user_id": user_id}
+        if organization_id is not None:
+            json_data["organization_id"] = organization_id
+
+        response = await self._http_client.request(
+            f"data-integrations/{provider}/token",
+            method=REQUEST_METHOD_POST,
+            json=json_data,
+        )
+
+        if response.get("active") is True:
+            return GetAccessTokenSuccessResponse.model_validate(response)
+        return GetAccessTokenFailureResponse.model_validate(response)

workos/portal.py

@@ -1,43 +1,66 @@
-import workos
-from workos.utils.request import RequestHelper, REQUEST_METHOD_POST
-from workos.utils.validation import PORTAL_MODULE, validate_settings
+from typing import Optional, Protocol, Dict, Literal, Union
+from workos.types.portal.portal_link import PortalLink
+from workos.types.portal.portal_link_intent import PortalLinkIntent
+from workos.types.portal.portal_link_intent_options import IntentOptions
+from workos.utils.http_client import SyncHTTPClient
+from workos.utils.request_helper import REQUEST_METHOD_POST
 
 
 PORTAL_GENERATE_PATH = "portal/generate_link"
 
 
-class Portal(object):
-    @validate_settings(PORTAL_MODULE)
-    def __init__(self):
-        pass
-
-    @property
-    def request_helper(self):
-        if not getattr(self, "_request_helper", None):
-            self._request_helper = RequestHelper()
-        return self._request_helper
-
-    def generate_link(self, intent, organization, return_url=None):
+class PortalModule(Protocol):
+    def generate_link(
+        self,
+        *,
+        intent: PortalLinkIntent,
+        organization_id: str,
+        return_url: Optional[str] = None,
+        success_url: Optional[str] = None,
+        intent_options: Optional[IntentOptions] = None,
+    ) -> PortalLink:
         """Generate a link to grant access to an organization's Admin Portal
 
-        Args:
-            intent (str): The access scope for the generated Admin Portal link. Valid values are: ["sso", "dsync"]
-            organization (string): The ID of the organization the Admin Portal link will be generated for
-
         Kwargs:
-            return_url (str): The URL that the end user will be redirected to upon exiting the generated Admin Portal. If none is provided, the default redirect link set in your WorkOS Dashboard will be used. (Optional)
+            intent (PortalLinkIntent): The access scope for the generated Admin Portal link.
+            organization_id (str): The ID of the organization the Admin Portal link will be generated for.
+            return_url (str): The URL that the end user will be redirected to upon exiting the generated Admin Portal.
+                If none is provided, the default redirect link set in your WorkOS Dashboard will be used. (Optional)
+            success_url (str): The URL to which WorkOS will redirect users to upon successfully viewing Audit Logs,
+                setting up Log Streams, Single Sign On or Directory Sync. (Optional)
 
         Returns:
-            str:  URL to redirect a User to to access an Admin Portal session
+            PortalLink: PortalLink object with URL to redirect a User to to access an Admin Portal session.
         """
-        params = {
+        ...
+
+
+class Portal(PortalModule):
+
+    _http_client: SyncHTTPClient
+
+    def __init__(self, http_client: SyncHTTPClient):
+        self._http_client = http_client
+
+    def generate_link(
+        self,
+        *,
+        intent: PortalLinkIntent,
+        organization_id: str,
+        return_url: Optional[str] = None,
+        success_url: Optional[str] = None,
+        intent_options: Optional[IntentOptions] = None,
+    ) -> PortalLink:
+        json = {
             "intent": intent,
-            "organization": organization,
+            "organization": organization_id,
             "return_url": return_url,
+            "success_url": success_url,
+            "intent_options": intent_options,
         }
-        return self.request_helper.request(
-            PORTAL_GENERATE_PATH,
-            method=REQUEST_METHOD_POST,
-            params=params,
-            token=workos.api_key,
+
+        response = self._http_client.request(
+            PORTAL_GENERATE_PATH, method=REQUEST_METHOD_POST, json=json
         )
+
+        return PortalLink.model_validate(response)

workos/session.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, List, Protocol
+
+from functools import lru_cache
+import json
+from typing import Any, Dict, Optional, Union, cast
+
+import jwt
+from jwt import PyJWKClient
+from cryptography.fernet import Fernet
+
+from workos.types.user_management.session import (
+    AuthenticateWithSessionCookieFailureReason,
+    AuthenticateWithSessionCookieSuccessResponse,
+    AuthenticateWithSessionCookieErrorResponse,
+    RefreshWithSessionCookieErrorResponse,
+    RefreshWithSessionCookieSuccessResponse,
+)
+from workos.typing.sync_or_async import SyncOrAsync
+
+if TYPE_CHECKING:
+    from workos.user_management import UserManagementModule
+    from workos.user_management import AsyncUserManagement, UserManagement
+
+
+@lru_cache(maxsize=None)
+def _get_jwks_client(jwks_url: str) -> PyJWKClient:
+    return PyJWKClient(jwks_url)
+
+
+class SessionModule(Protocol):
+    user_management: "UserManagementModule"
+    client_id: str
+    session_data: str
+    cookie_password: str
+    jwks: PyJWKClient
+    jwk_algorithms: List[str]
+
+    def __init__(
+        self,
+        *,
+        user_management: "UserManagementModule",
+        client_id: str,
+        session_data: str,
+        cookie_password: str,
+    ) -> None:
+        # If the cookie password is not provided, throw an error
+        if cookie_password is None or cookie_password == "":
+            raise ValueError("cookie_password is required")
+
+        self.user_management = user_management
+        self.client_id = client_id
+        self.session_data = session_data
+        self.cookie_password = cookie_password
+
+        self.jwks = _get_jwks_client(self.user_management.get_jwks_url())
+
+        # Algorithms are hardcoded for security reasons. See https://pyjwt.readthedocs.io/en/stable/algorithms.html#specifying-an-algorithm
+        self.jwk_algorithms = ["RS256"]
+
+    def authenticate(
+        self,
+    ) -> Union[
+        AuthenticateWithSessionCookieSuccessResponse,
+        AuthenticateWithSessionCookieErrorResponse,
+    ]:
+        if self.session_data is None or self.session_data == "":
+            return AuthenticateWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.NO_SESSION_COOKIE_PROVIDED,
+            )
+
+        try:
+            session = self.unseal_data(self.session_data, self.cookie_password)
+        except Exception:
+            return AuthenticateWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_SESSION_COOKIE,
+            )
+
+        if not session.get("access_token", None):
+            return AuthenticateWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_SESSION_COOKIE,
+            )
+
+        try:
+            signing_key = self.jwks.get_signing_key_from_jwt(session["access_token"])
+            decoded = jwt.decode(
+                session["access_token"],
+                signing_key.key,
+                algorithms=self.jwk_algorithms,
+                options={"verify_aud": False},
+            )
+        except jwt.exceptions.InvalidTokenError:
+            return AuthenticateWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_JWT,
+            )
+
+        return AuthenticateWithSessionCookieSuccessResponse(
+            authenticated=True,
+            session_id=decoded["sid"],
+            organization_id=decoded.get("org_id", None),
+            role=decoded.get("role", None),
+            roles=decoded.get("roles", None),
+            permissions=decoded.get("permissions", None),
+            entitlements=decoded.get("entitlements", None),
+            user=session["user"],
+            impersonator=session.get("impersonator", None),
+            feature_flags=decoded.get("feature_flags", None),
+        )
+
+    def refresh(
+        self,
+        *,
+        organization_id: Optional[str] = None,
+        cookie_password: Optional[str] = None,
+    ) -> SyncOrAsync[
+        Union[
+            RefreshWithSessionCookieSuccessResponse,
+            RefreshWithSessionCookieErrorResponse,
+        ]
+    ]: ...
+
+    def get_logout_url(self, return_to: Optional[str] = None) -> str:
+        auth_response = self.authenticate()
+
+        if isinstance(auth_response, AuthenticateWithSessionCookieErrorResponse):
+            raise ValueError(
+                f"Failed to extract session ID for logout URL: {auth_response.reason}"
+            )
+
+        result = self.user_management.get_logout_url(
+            session_id=auth_response.session_id,
+            return_to=return_to,
+        )
+        return str(result)
+
+    @staticmethod
+    def seal_data(data: Dict[str, Any], key: str) -> str:
+        fernet = Fernet(key)
+        # Encrypt and convert bytes to string
+        encrypted_bytes = fernet.encrypt(json.dumps(data).encode())
+        return encrypted_bytes.decode("utf-8")
+
+    @staticmethod
+    def unseal_data(sealed_data: str, key: str) -> Dict[str, Any]:
+        fernet = Fernet(key)
+        # Convert string back to bytes before decryption
+        encrypted_bytes = sealed_data.encode("utf-8")
+        decrypted_str = fernet.decrypt(encrypted_bytes).decode()
+        return cast(Dict[str, Any], json.loads(decrypted_str))
+
+
+class Session(SessionModule):
+    user_management: "UserManagement"
+
+    def __init__(
+        self,
+        *,
+        user_management: "UserManagement",
+        client_id: str,
+        session_data: str,
+        cookie_password: str,
+    ) -> None:
+        # If the cookie password is not provided, throw an error
+        if cookie_password is None or cookie_password == "":
+            raise ValueError("cookie_password is required")
+
+        self.user_management = user_management
+        self.client_id = client_id
+        self.session_data = session_data
+        self.cookie_password = cookie_password
+
+        self.jwks = _get_jwks_client(self.user_management.get_jwks_url())
+
+        # Algorithms are hardcoded for security reasons. See https://pyjwt.readthedocs.io/en/stable/algorithms.html#specifying-an-algorithm
+        self.jwk_algorithms = ["RS256"]
+
+    def refresh(
+        self,
+        *,
+        organization_id: Optional[str] = None,
+        cookie_password: Optional[str] = None,
+    ) -> Union[
+        RefreshWithSessionCookieSuccessResponse,
+        RefreshWithSessionCookieErrorResponse,
+    ]:
+        cookie_password = (
+            self.cookie_password if cookie_password is None else cookie_password
+        )
+
+        try:
+            session = self.unseal_data(self.session_data, cookie_password)
+        except Exception:
+            return RefreshWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_SESSION_COOKIE,
+            )
+
+        if not session.get("refresh_token", None) or not session.get("user", None):
+            return RefreshWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_SESSION_COOKIE,
+            )
+
+        try:
+            auth_response = self.user_management.authenticate_with_refresh_token(
+                refresh_token=session["refresh_token"],
+                organization_id=organization_id,
+                session={"seal_session": True, "cookie_password": cookie_password},
+            )
+
+            self.session_data = str(auth_response.sealed_session)
+            self.cookie_password = (
+                cookie_password if cookie_password is not None else self.cookie_password
+            )
+
+            signing_key = self.jwks.get_signing_key_from_jwt(auth_response.access_token)
+
+            decoded = jwt.decode(
+                auth_response.access_token,
+                signing_key.key,
+                algorithms=self.jwk_algorithms,
+                options={"verify_aud": False},
+            )
+
+            return RefreshWithSessionCookieSuccessResponse(
+                authenticated=True,
+                sealed_session=str(auth_response.sealed_session),
+                session_id=decoded["sid"],
+                organization_id=decoded.get("org_id", None),
+                role=decoded.get("role", None),
+                roles=decoded.get("roles", None),
+                permissions=decoded.get("permissions", None),
+                entitlements=decoded.get("entitlements", None),
+                user=auth_response.user,
+                impersonator=auth_response.impersonator,
+                feature_flags=decoded.get("feature_flags", None),
+            )
+        except Exception as e:
+            return RefreshWithSessionCookieErrorResponse(
+                authenticated=False, reason=str(e)
+            )
+
+
+class AsyncSession(SessionModule):
+    user_management: "AsyncUserManagement"
+
+    def __init__(
+        self,
+        *,
+        user_management: "AsyncUserManagement",
+        client_id: str,
+        session_data: str,
+        cookie_password: str,
+    ) -> None:
+        # If the cookie password is not provided, throw an error
+        if cookie_password is None or cookie_password == "":
+            raise ValueError("cookie_password is required")
+
+        self.user_management = user_management
+        self.client_id = client_id
+        self.session_data = session_data
+        self.cookie_password = cookie_password
+
+        self.jwks = _get_jwks_client(self.user_management.get_jwks_url())
+
+        # Algorithms are hardcoded for security reasons. See https://pyjwt.readthedocs.io/en/stable/algorithms.html#specifying-an-algorithm
+        self.jwk_algorithms = ["RS256"]
+
+    async def refresh(
+        self,
+        *,
+        organization_id: Optional[str] = None,
+        cookie_password: Optional[str] = None,
+    ) -> Union[
+        RefreshWithSessionCookieSuccessResponse,
+        RefreshWithSessionCookieErrorResponse,
+    ]:
+        cookie_password = (
+            self.cookie_password if cookie_password is None else cookie_password
+        )
+
+        try:
+            session = self.unseal_data(self.session_data, cookie_password)
+        except Exception:
+            return RefreshWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_SESSION_COOKIE,
+            )
+
+        if not session.get("refresh_token", None) or not session.get("user", None):
+            return RefreshWithSessionCookieErrorResponse(
+                authenticated=False,
+                reason=AuthenticateWithSessionCookieFailureReason.INVALID_SESSION_COOKIE,
+            )
+
+        try:
+            auth_response = await self.user_management.authenticate_with_refresh_token(
+                refresh_token=session["refresh_token"],
+                organization_id=organization_id,
+                session={"seal_session": True, "cookie_password": cookie_password},
+            )
+
+            self.session_data = str(auth_response.sealed_session)
+            self.cookie_password = (
+                cookie_password if cookie_password is not None else self.cookie_password
+            )
+
+            signing_key = self.jwks.get_signing_key_from_jwt(auth_response.access_token)
+
+            decoded = jwt.decode(
+                auth_response.access_token,
+                signing_key.key,
+                algorithms=self.jwk_algorithms,
+                options={"verify_aud": False},
+            )
+
+            return RefreshWithSessionCookieSuccessResponse(
+                authenticated=True,
+                sealed_session=str(auth_response.sealed_session),
+                session_id=decoded["sid"],
+                organization_id=decoded.get("org_id", None),
+                role=decoded.get("role", None),
+                roles=decoded.get("roles", None),
+                permissions=decoded.get("permissions", None),
+                entitlements=decoded.get("entitlements", None),
+                user=auth_response.user,
+                impersonator=auth_response.impersonator,
+                feature_flags=decoded.get("feature_flags", None),
+            )
+        except Exception as e:
+            return RefreshWithSessionCookieErrorResponse(
+                authenticated=False, reason=str(e)
+            )