python-xbox 0.1.0__py3-none-any.whl

pythonxbox/authentication/models.py

@@ -0,0 +1,162 @@
+"""Authentication Models."""
+
+from datetime import datetime, timedelta, UTC
+
+from pydantic import BaseModel, Field
+from pydantic.dataclasses import dataclass
+
+from pythonxbox.common.models import PascalCaseModel
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+class XTokenResponse(PascalCaseModel):
+    issue_instant: datetime
+    not_after: datetime
+    token: str
+
+    def is_valid(self) -> bool:
+        return self.not_after > utc_now()
+
+
+class XADDisplayClaims(BaseModel):
+    # {"xdi": {"did": "F.....", "dcs": "0"}}
+    xdi: dict[str, str]
+
+
+class XADResponse(XTokenResponse):
+    display_claims: XADDisplayClaims
+
+
+class XATDisplayClaims(BaseModel):
+    xti: dict[str, str]
+
+
+class XATResponse(XTokenResponse):
+    display_claims: XATDisplayClaims
+
+
+class XAUDisplayClaims(BaseModel):
+    xui: list[dict[str, str]]
+
+
+class XAUResponse(XTokenResponse):
+    display_claims: XAUDisplayClaims
+
+
+class XSTSDisplayClaims(BaseModel):
+    xui: list[dict[str, str]]
+
+
+class XSTSResponse(XTokenResponse):
+    display_claims: XSTSDisplayClaims
+
+    @property
+    def xuid(self) -> str:
+        return self.display_claims.xui[0]["xid"]
+
+    @property
+    def userhash(self) -> str:
+        return self.display_claims.xui[0]["uhs"]
+
+    @property
+    def gamertag(self) -> str:
+        return self.display_claims.xui[0]["gtg"]
+
+    @property
+    def age_group(self) -> str:
+        return self.display_claims.xui[0]["agg"]
+
+    @property
+    def privileges(self) -> str:
+        return self.display_claims.xui[0]["prv"]
+
+    @property
+    def user_privileges(self) -> str:
+        return self.display_claims.xui[0]["usr"]
+
+    @property
+    def authorization_header_value(self) -> str:
+        return f"XBL3.0 x={self.userhash};{self.token}"
+
+
+class OAuth2TokenResponse(BaseModel):
+    token_type: str
+    expires_in: int
+    scope: str
+    access_token: str
+    refresh_token: str | None = None
+    user_id: str
+    issued: datetime = Field(default_factory=utc_now)
+
+    def is_valid(self) -> bool:
+        return (self.issued + timedelta(seconds=self.expires_in)) > utc_now()
+
+
+"""XAL related models"""
+
+
+@dataclass
+class XalAppParameters:
+    app_id: str
+    title_id: str
+    redirect_uri: str
+
+
+@dataclass
+class XalClientParameters:
+    user_agent: str
+    device_type: str
+    client_version: str
+    query_display: str
+
+
+class SisuAuthenticationResponse(PascalCaseModel):
+    msa_oauth_redirect: str
+    msa_request_parameters: dict[str, str]
+
+
+class SisuAuthorizationResponse(PascalCaseModel):
+    device_token: str
+    title_token: XATResponse
+    user_token: XAUResponse
+    authorization_token: XSTSResponse
+    web_page: str
+    sandbox: str
+    use_modern_gamertag: bool | None = None
+
+
+"""Signature related models"""
+
+
+class TitleEndpoint(PascalCaseModel):
+    protocol: str
+    host: str
+    host_type: str
+    path: str | None = None
+    relying_party: str | None = None
+    sub_relying_party: str | None = None
+    token_type: str | None = None
+    signature_policy_index: int | None = None
+    server_cert_index: list[int] | None = None
+
+
+class SignaturePolicy(PascalCaseModel):
+    version: int
+    supported_algorithms: list[str]
+    max_body_bytes: int
+
+
+class TitleEndpointCertificate(PascalCaseModel):
+    thumbprint: str
+    is_issuer: bool | None = None
+    root_cert_index: int
+
+
+class TitleEndpointsResponse(PascalCaseModel):
+    end_points: list[TitleEndpoint]
+    signature_policies: list[SignaturePolicy]
+    certs: list[TitleEndpointCertificate]
+    root_certs: list[str]

pythonxbox/authentication/xal.py

@@ -0,0 +1,348 @@
+"""
+Xbox Authentication Library
+
+Authenticate with Windows Live Server and Xbox Live (used by mobile Xbox Apps)
+"""
+
+import base64
+import hashlib
+import logging
+import os
+from collections.abc import Callable
+from urllib import parse
+import uuid
+
+import httpx
+from ms_cv import CorrelationVector
+
+from pythonxbox.authentication.models import (
+    OAuth2TokenResponse,
+    SisuAuthenticationResponse,
+    SisuAuthorizationResponse,
+    TitleEndpointsResponse,
+    XADResponse,
+    XalAppParameters,
+    XalClientParameters,
+    XSTSResponse,
+)
+from pythonxbox.common.signed_session import SignedSession
+
+log = logging.getLogger("xal.authentication")
+
+APP_PARAMS_XBOX_BETA_APP = XalAppParameters(
+    app_id="000000004415494b",
+    title_id="177887386",
+    redirect_uri="ms-xal-000000004415494b://auth",
+)
+
+APP_PARAMS_XBOX_APP = XalAppParameters(
+    app_id="000000004c12ae6f",
+    title_id="328178078",
+    redirect_uri="ms-xal-000000004c12ae6f://auth",
+)
+
+APP_PARAMS_GAMEPASS = XalAppParameters(
+    app_id="000000004c20a908",
+    title_id="1016898439",
+    redirect_uri="ms-xal-000000004c20a908://auth",
+)
+
+APP_PARAMS_GAMEPASS_BETA = XalAppParameters(
+    app_id="000000004c20a908",
+    title_id="1016898439",
+    redirect_uri="ms-xal-public-beta-000000004c20a908://auth",
+)
+
+APP_PARAMS_FAMILY_SETTINGS = XalAppParameters(
+    app_id="00000000482C8F49",
+    title_id="1618633878",
+    redirect_uri="https://login.live.com/oauth20_desktop.srf",
+)
+
+CLIENT_PARAMS_IOS = XalClientParameters(
+    user_agent="XAL iOS 2021.11.20211021.000",
+    device_type="iOS",
+    client_version="15.6.1",
+    query_display="ios_phone",
+)
+
+CLIENT_PARAMS_ANDROID = XalClientParameters(
+    user_agent="XAL Android 2020.07.20200714.000",
+    device_type="Android",
+    client_version="8.0.0",
+    query_display="android_phone",
+)
+
+
+class XALManager:
+    def __init__(
+        self,
+        session: SignedSession,
+        device_id: uuid.UUID,
+        app_params: XalAppParameters,
+        client_params: XalClientParameters,
+    ) -> None:
+        self.session = session
+        self.device_id = device_id
+        self.app_params = app_params
+        self.client_params = client_params
+        self.cv = CorrelationVector()
+
+    @staticmethod
+    def _get_random_bytes(length: int) -> bytes:
+        return os.urandom(length)
+
+    @staticmethod
+    def _generate_code_verifier() -> str:
+        # https://tools.ietf.org/html/rfc7636
+        code_verifier = (
+            base64.urlsafe_b64encode(XALManager._get_random_bytes(32))
+            .decode()
+            .rstrip("=")
+        )
+        assert len(code_verifier) >= 43 and len(code_verifier) <= 128
+
+        return code_verifier
+
+    @staticmethod
+    def _get_code_challenge_from_code_verifier(code_verifier: str) -> str:
+        code_challenge = hashlib.sha256(code_verifier.encode()).digest()
+        # Base64 urlsafe encoding WITH stripping trailing '='
+        code_challenge = base64.urlsafe_b64encode(code_challenge).decode().rstrip("=")
+
+        return code_challenge
+
+    @staticmethod
+    def _generate_random_state() -> str:
+        state = str(uuid.uuid4()).encode()
+        # Base64 urlsafe encoding WITHOUT stripping trailing '='
+        return base64.b64encode(state).decode()
+
+    @staticmethod
+    async def get_title_endpoints(session: httpx.AsyncClient) -> TitleEndpointsResponse:
+        url = "https://title.mgt.xboxlive.com/titles/default/endpoints"
+        headers = {"x-xbl-contract-version": "1"}
+        params = {"type": 1}
+        resp = await session.get(url, headers=headers, params=params)
+        resp.raise_for_status()
+        return TitleEndpointsResponse(**resp.json())
+
+    async def request_device_token(self) -> XADResponse:
+        # Proof of possession: https://tools.ietf.org/html/rfc7800
+
+        device_id = str(self.device_id)
+
+        if self.client_params.device_type.lower() == "android":
+            # {decf45e4-945d-4379-b708-d4ee92c12d99}
+            device_id = f"{{{device_id}}}"
+        else:
+            # iOSs
+            # DECF45E4-945D-4379-B708-D4EE92C12D99
+            device_id = device_id.upper()
+
+        url = "https://device.auth.xboxlive.com/device/authenticate"
+        headers = {"x-xbl-contract-version": "1", "MS-CV": self.cv.get_value()}
+        data = {
+            "RelyingParty": "http://auth.xboxlive.com",
+            "TokenType": "JWT",
+            "Properties": {
+                "AuthMethod": "ProofOfPossession",
+                "Id": device_id,
+                "DeviceType": self.client_params.device_type,
+                "Version": self.client_params.client_version,
+                "ProofKey": self.session.request_signer.proof_field,
+            },
+        }
+
+        resp = await self.session.send_signed("POST", url, headers=headers, json=data)
+        resp.raise_for_status()
+        return XADResponse(**resp.json())
+
+    async def __oauth20_token_endpoint(self, json_body: dict) -> httpx.Response:
+        url = "https://login.live.com/oauth20_token.srf"
+        headers = {"MS-CV": self.cv.increment()}
+
+        # NOTE: No signature necessary
+        return await self.session.post(url, headers=headers, data=json_body)
+
+    async def exchange_code_for_token(
+        self, authorization_code: str, code_verifier: str
+    ) -> OAuth2TokenResponse:
+        post_body = {
+            "client_id": self.app_params.app_id,
+            "code": authorization_code,
+            "code_verifier": code_verifier,
+            "grant_type": "authorization_code",
+            "redirect_uri": self.app_params.redirect_uri,
+            "scope": "service::user.auth.xboxlive.com::MBI_SSL",
+        }
+        resp = await self.__oauth20_token_endpoint(post_body)
+        resp.raise_for_status()
+        return OAuth2TokenResponse(**resp.json())
+
+    async def refresh_token(self, refresh_token_jwt: str) -> httpx.Response:
+        post_body = {
+            "client_id": self.app_params.app_id,
+            "refresh_token": refresh_token_jwt,
+            "grant_type": "refresh_token",
+            "redirect_uri": self.app_params.redirect_uri,
+            "scope": "service::user.auth.xboxlive.com::MBI_SSL",
+        }
+
+        resp = await self.__oauth20_token_endpoint(post_body)
+        resp.raise_for_status()
+        return resp
+
+    async def request_sisu_authentication(
+        self, device_token_jwt: str, code_challenge: str, state: str
+    ) -> tuple[SisuAuthenticationResponse, str]:
+        """
+        Request Sisu authentication URL
+
+        Response holds authentication URL that needs to be called by the user
+        in webbrowser
+
+        Returns:
+            Tuple of (authentication response, sisu session id)
+        """
+        url = "https://sisu.xboxlive.com/authenticate"
+        headers = {"x-xbl-contract-version": "1", "MS-CV": self.cv.increment()}
+        post_body = {
+            "AppId": self.app_params.app_id,
+            "TitleId": self.app_params.title_id,
+            "RedirectUri": self.app_params.redirect_uri,
+            "DeviceToken": device_token_jwt,
+            "Sandbox": "RETAIL",
+            "TokenType": "code",
+            "Offers": ["service::user.auth.xboxlive.com::MBI_SSL"],
+            "Query": {
+                "display": self.client_params.query_display,
+                "code_challenge": code_challenge,
+                "code_challenge_method": "S256",
+                "state": state,
+            },
+        }
+
+        resp = await self.session.send_signed(
+            "POST", url, headers=headers, json=post_body
+        )
+        resp.raise_for_status()
+        return (
+            SisuAuthenticationResponse.model_validate_json(resp.content),
+            resp.headers["X-SessionId"],
+        )
+
+    async def do_sisu_authorization(
+        self, sisu_session_id: str, access_token_jwt: str, device_token_jwt: str
+    ) -> SisuAuthorizationResponse:
+        """
+        Sisu authorization
+
+        Returns:
+            Response with device-/title-/user-tokens
+        """
+        url = "https://sisu.xboxlive.com/authorize"
+        headers = {"MS-CV": self.cv.increment()}
+        post_body = {
+            "AccessToken": f"t={access_token_jwt}",
+            "AppId": self.app_params.app_id,
+            "DeviceToken": device_token_jwt,
+            "Sandbox": "RETAIL",
+            "SiteName": "user.auth.xboxlive.com",
+            "SessionId": sisu_session_id,
+            "ProofKey": self.session.request_signer.proof_field,
+        }
+
+        resp = await self.session.send_signed(
+            "POST", url, headers=headers, json=post_body
+        )
+        resp.raise_for_status()
+        return SisuAuthorizationResponse(**resp.json())
+
+    async def xsts_authorization(
+        self,
+        device_token_jwt: str,
+        title_token_jwt: str,
+        user_token_jwt: str,
+        relying_party: str,
+    ) -> XSTSResponse:
+        """
+        Request additional XSTS tokens for specific relying parties
+        """
+        url = "https://xsts.auth.xboxlive.com/xsts/authorize"
+        headers = {"x-xbl-contract-version": "1", "MS-CV": self.cv.increment()}
+        post_body = {
+            "RelyingParty": relying_party,
+            "TokenType": "JWT",
+            "Properties": {
+                "SandboxId": "RETAIL",
+                "DeviceToken": device_token_jwt,
+                "TitleToken": title_token_jwt,
+                "UserTokens": [user_token_jwt],
+            },
+        }
+
+        resp = await self.session.send_signed(
+            "POST", url, headers=headers, json=post_body
+        )
+        resp.raise_for_status()
+        return XSTSResponse(**resp.json())
+
+    async def auth_flow(
+        self, user_input_cb: Callable[[str], str]
+    ) -> SisuAuthorizationResponse:
+        """
+        Does the whole XAL/Sisu authentication flow
+
+        Args:
+            user_input_cb: User callback which takes args: (auth_url: str) and
+                returns the redirect URL (str)
+
+        Returns:
+            Sisu authorization response with all tokens
+        """
+
+        # Fetch device token
+        device_token_resp = await self.request_device_token()
+
+        # Generate states for OAUTH
+        code_verifier = self._generate_code_verifier()
+        code_challenge = self._get_code_challenge_from_code_verifier(code_verifier)
+        state = self._generate_random_state()
+
+        # Request Sisu authentication URL
+        (
+            sisu_authenticate_resp,
+            sisu_session_id,
+        ) = await self.request_sisu_authentication(
+            device_token_resp.token, code_challenge, state
+        )
+
+        # Prompt user for redirect URI after auth
+        redirect_uri = user_input_cb(sisu_authenticate_resp.msa_oauth_redirect)
+
+        # Ensure redirect URI looks like expected
+        if not redirect_uri.startswith(self.app_params.redirect_uri):
+            raise Exception("Wrong data passed as redirect URI")
+
+        # Parse URL query
+        query_params = dict(parse.parse_qsl(parse.urlsplit(redirect_uri).query))
+
+        # Extract code and state
+        resp_authorization_code = query_params["code"]
+        resp_state = query_params["state"]
+
+        if resp_state != state:
+            raise Exception("Response with non-matching state received")
+
+        # Exchange authentication code for tokens
+        tokens = await self.exchange_code_for_token(
+            resp_authorization_code, code_verifier
+        )
+
+        # Do Sisu authorization
+        sisu_authorization = await self.do_sisu_authorization(
+            sisu_session_id, tokens.access_token, device_token_resp.token
+        )
+
+        return sisu_authorization

pythonxbox/common/exceptions.py

@@ -0,0 +1,59 @@
+"""
+Special Exception subclasses
+"""
+
+from typing import Any
+from pythonxbox.common.ratelimits import RateLimit
+from httpx import Response
+
+
+class XboxException(Exception):
+    """Base exception for all Xbox exceptions to subclass"""
+
+    pass
+
+
+class AuthenticationException(XboxException):
+    """Raised when logging in fails, likely due to incorrect auth credentials"""
+
+    pass
+
+
+class TwoFactorAuthRequired(XboxException):
+    def __init__(self, message: str, server_data: dict[str, Any]) -> None:
+        """
+        Raised when 2FA is required
+
+        Args:
+            message (str): Exception message
+            server_data (dict): Server data dict, extracted js object from windows live auth request
+        """
+        super().__init__(message)
+        self.server_data = server_data
+
+
+class InvalidRequest(XboxException):
+    def __init__(self, message: str, response: Response) -> None:
+        """
+        Raised when something is wrong with the request
+
+        Args:
+            message (str): error message returned by the server
+            response (requests.Response): Instance of :class:`requests.Response`
+
+        """
+        self.message = message
+        self.response = response
+
+
+class NotFoundException(XboxException):
+    """Any exception raised due to a resource being missing will subclass this"""
+
+    pass
+
+
+class RateLimitExceededException(XboxException):
+    def __init__(self, message: str, rate_limit: RateLimit) -> None:
+        self.message = message
+        self.rate_limit = rate_limit
+        self.try_again_in = rate_limit.get_reset_after()

pythonxbox/common/filetimes.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2009, David Buxton <david@gasmark6.com>
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+# TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""Tools to convert between Python datetime instances and Microsoft times."""
+
+from calendar import timegm
+from datetime import datetime, timedelta, UTC
+
+# http://support.microsoft.com/kb/167296
+# How To Convert a UNIX time_t to a Win32 FILETIME or SYSTEMTIME
+EPOCH_AS_FILETIME = 116444736000000000  # January 1, 1970 as MS file time
+HUNDREDS_OF_NANOSECONDS = 10000000
+
+
+ZERO = timedelta(0)
+HOUR = timedelta(hours=1)
+
+
+def dt_to_filetime(dt: datetime) -> int:
+    """Converts a datetime to Microsoft filetime format. If the object is
+    time zone-naive, it is forced to UTC before conversion.
+
+    >>> "%.0f" % dt_to_filetime(datetime(2009, 7, 25, 23, 0))
+    '128930364000000000'
+
+    >>> "%.0f" % dt_to_filetime(datetime(1970, 1, 1, 0, 0, tzinfo=UTC))
+    '116444736000000000'
+
+    >>> "%.0f" % dt_to_filetime(datetime(1970, 1, 1, 0, 0))
+    '116444736000000000'
+
+    >>> dt_to_filetime(datetime(2009, 7, 25, 23, 0, 0, 100))
+    128930364000001000
+    """
+    if (dt.tzinfo is None) or (dt.tzinfo.utcoffset(dt) is None):
+        dt = dt.replace(tzinfo=UTC)
+    ft = EPOCH_AS_FILETIME + (timegm(dt.timetuple()) * HUNDREDS_OF_NANOSECONDS)
+    return ft + (dt.microsecond * 10)
+
+
+def filetime_to_dt(ft: int) -> datetime:
+    """Converts a Microsoft filetime number to a Python datetime. The new
+    datetime object is time zone-naive but is equivalent to tzinfo=utc.
+
+    >>> filetime_to_dt(116444736000000000)
+    datetime.datetime(1970, 1, 1, 0, 0)
+
+    >>> filetime_to_dt(128930364000000000)
+    datetime.datetime(2009, 7, 25, 23, 0)
+
+    >>> filetime_to_dt(128930364000001000)
+    datetime.datetime(2009, 7, 25, 23, 0, 0, 100)
+    """
+    # Get seconds and remainder in terms of Unix epoch
+    (s, ns100) = divmod(ft - EPOCH_AS_FILETIME, HUNDREDS_OF_NANOSECONDS)
+    # Convert to datetime object
+    dt = datetime.fromtimestamp(s, UTC)
+    # Add remainder in as microseconds. Python 3.2 requires an integer
+    dt = dt.replace(microsecond=(ns100 // 10))
+    return dt

pythonxbox/common/models.py

@@ -0,0 +1,34 @@
+"""Base Models."""
+
+from pydantic import ConfigDict, BaseModel
+
+
+def to_pascal(string: str) -> str:
+    return "".join(word.capitalize() for word in string.split("_"))
+
+
+def to_camel(string: str) -> str:
+    words = string.split("_")
+    return words[0] + "".join(word.capitalize() for word in words[1:])
+
+
+def to_lower(string: str) -> str:
+    return string.replace("_", "")
+
+
+class PascalCaseModel(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True, populate_by_name=True, alias_generator=to_pascal
+    )
+
+
+class CamelCaseModel(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True, populate_by_name=True, alias_generator=to_camel
+    )
+
+
+class LowerCaseModel(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True, populate_by_name=True, alias_generator=to_lower
+    )