spotifywebapiPython 1.0.72__py3-none-any.whl → 1.0.74__py3-none-any.whl

spotifywebapipython/zeroconfapi/cryptodiffiehellman.py

@@ -1,11 +1,17 @@
 import secrets
 
-from .helpers import byte_list_to_int
+from .helpers import byte_list_to_int, int_to_bytes, b64_to_int, int_to_b64str
 
 class CryptoDiffieHellman:
+    """
+    Diffie Hellman cryptography helper class.
+    
+    The following link does a pretty good job of explaining this process:
+    https://www.comparitech.com/blog/information-security/diffie-hellman-key-exchange/
+    """
     
     DH_GENERATOR = 2
-    DH_PRIME = byte_list_to_int([
+    DH_PRIME_MODULUS = byte_list_to_int([
         0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xc9, 0x0f, 0xda, 0xa2, 0x21, 0x68, 0xc2,
         0x34, 0xc4, 0xc6, 0x62, 0x8b, 0x80, 0xdc, 0x1c, 0xd1, 0x29, 0x02, 0x4e, 0x08, 0x8a, 0x67,
         0xcc, 0x74, 0x02, 0x0b, 0xbe, 0xa6, 0x3b, 0x13, 0x9b, 0x22, 0x51, 0x4a, 0x08, 0x79, 0x8e,
@@ -16,9 +22,68 @@ class CryptoDiffieHellman:
     
 
     def __init__(self):
-        self._private_key = secrets.randbits(95 * 8)
-        self.public_key = pow(CryptoDiffieHellman.DH_GENERATOR, self._private_key, CryptoDiffieHellman.DH_PRIME)
+        """
+        Initializes a new instance of the class.
+        """
+        # generate our private key value.
+        self._PrivateKey = secrets.randbits(95 * 8)
+        
+        # generate a public key that we can share with a partner.
+        self._PublicKey:int = pow(CryptoDiffieHellman.DH_GENERATOR, self._PrivateKey, CryptoDiffieHellman.DH_PRIME_MODULUS)
+
+
+    @property
+    def PublicKey(self) -> int:
+        """ 
+        Returns our public key in an integer format.
+        """
+        return self._PublicKey
+    
+    @PublicKey.setter
+    def PublicKey(self, value:int):
+        """ 
+        Sets the PublicKey property value.
+        """
+        if isinstance(value, int):
+            self._PublicKey = value
+
 
+    @property
+    def PublicKeyBase64String(self) -> str:
+        """ 
+        Returns our public key in a base64 encoded string format.
+        """
+        return int_to_b64str(self._PublicKey)
+    
 
-    def shared_secret(self, remote_key):
-        return pow(remote_key, self._private_key, CryptoDiffieHellman.DH_PRIME)
+    def SharedSecret(self, remotePublicKey:int):
+        """
+        Returns a shared secret value that is calculated based upon the specified `remotePublicKey`
+        value, our private key value, and a shared Modulus value.
+        
+        Args:
+            remotePublicKey (int):
+                The Remote clients PublicKey value.
+        
+        The shared secret value can be calculated as:
+        SharedSecret = remotePublicKey(base,g) ** PrivateKey(secret,a) % DH_PRIME(modulus,p)
+        SharedSecret = g**a mod p
+        SharedSecret = base ** secret % modulus
+        
+        - base = remotePublicKey
+        - secret = PrivateKey
+        - modulus = DH_PRIME
+        """
+        # calculate the shared secret value based upon the remote's PublicKey, our PrivateKey, and the shared Modulus.
+        
+        # another way to express this formula is:
+        # SharedSecret = g**a mod p
+        
+        # another way to express this formula is:
+        # SharedSecret = base ** secret % modulus
+        
+        # - base or `g`     = remotePublicKey
+        # - secret or `a`   = PrivateKey
+        # - modulus or `p`  = DH_PRIME
+        return pow(remotePublicKey, self._PrivateKey, CryptoDiffieHellman.DH_PRIME_MODULUS)
+    

spotifywebapipython/zeroconfapi/helpers.py

@@ -1,4 +1,5 @@
 from base64 import b64decode, b64encode
+import binascii
 
 
 def write_int(i: int, out: bytearray):
@@ -14,17 +15,43 @@ def write_bytes(b: bytes, out: bytearray):
     out.extend(b)
 
 
-def byte_list_to_int(byte_list):
+def byte_list_to_int(byte_list) -> int:
+    """
+    Converts a list of bytes to a big integer.
+    """
     return int.from_bytes(bytes(byte_list), 'big')
 
 
-def int_to_bytes(i: int):
-    return i.to_bytes((i.bit_length() + 7) // 8, byteorder='big')
+def int_to_bytes(value: int) -> bytes:
+    """
+    Converts a big integer to bytes.
+    """
+    return value.to_bytes((value.bit_length() + 7) // 8, byteorder='big') or b'\0'
 
 
-def int_to_b64str(i: int):
-    return b64encode(int_to_bytes(i)).decode('ascii')
+def int_to_b64str(value: int) -> str:
+    """
+    Converts a big integer to a base64-encoded string value.
+    """
+    return b64encode(int_to_bytes(value)).decode('ascii')
 
 
-def b64_to_int(b64: str):
-    return int.from_bytes(b64decode(b64), 'big')
+def b64_to_int(value: str):
+    """
+    Converts a base64-encoded string or byte array to a big integer.
+    """
+    return int.from_bytes(b64decode(value), 'big')
+
+
+def string_to_int(value):
+    """
+    Converts a string to a big integer.
+    """
+    return int(binascii.hexlify(value), 16)
+
+
+def int_of_string(value):
+    """
+    Converts a string to a big integer.
+    """
+    return int(binascii.hexlify(value), 16)

spotifywebapipython/zeroconfapi/zeroconfconnect.py

@@ -6,7 +6,7 @@ import time
 
 # our package imports.
 from .blobbuilder import BlobBuilder
-from .credentials import Credentials
+from .credentials import Credentials, AuthenticationTypes
 from .helpers import int_to_b64str
 from .spotifyzeroconfapierror import SpotifyZeroconfApiError
 from .zeroconfresponse import ZeroconfResponse
@@ -42,6 +42,12 @@ class ZeroconfConnect:
     GitHub repository.
     """
     
+    SPOTIFY_CONNECT_CLIENT_VERSION_DEFAULT:str = '2.7.1'
+    """
+    Spotify Connect default version string ('2.7.1').
+    """
+    
+
     def __init__(self, 
                  hostIpAddress:str,
                  hostIpPort:int,
@@ -72,6 +78,8 @@ class ZeroconfConnect:
         # validations.
         if (useSSL is None) or (not isinstance(useSSL,bool)):
             useSSL = False
+        if (version is None) or (not isinstance(version,str)):
+            version = ZeroconfConnect.SPOTIFY_CONNECT_CLIENT_VERSION_DEFAULT
             
         # initialize storage.
         self._CPath:str = cpath
@@ -208,10 +216,15 @@ class ZeroconfConnect:
                 responseUTF8 = response.content.decode('utf-8')
                 _logsi.LogText(SILevel.Error, "ZeroconfConnect http response [%s-%s]: '%s' (utf-8)" % (response.status_code, response.reason, endpoint), responseUTF8)
             
-            # at this point we don't know what Spotify Web Api returned, so let's 
-            # just raise a new exception with the non-JSON response data.
-            raise SpotifyZeroconfApiError(response.status_code, responseUTF8, methodName, response.reason, _logsi)
-            
+            # at this point we don't know what Spotify Web Api returned!
+            # it's been found that some devices (Sonos, etc) do not return a proper JSON response.
+            # raise a new exception with the non-JSON response data if the http status is not 200 (OK).
+            if (response.status_code != 200):
+                raise SpotifyZeroconfApiError(response.status_code, responseUTF8, methodName, response.reason, _logsi)
+
+            # trace.
+            _logsi.LogVerbose("Spotify Connect Device (ip=%s) returned an invalid JSON response, but the http status code was 200 so we will ignore it" % (self._HostIpAddress))
+
         # at this point we know that the response contains JSON data, as
         # we would have raised an exception before this if we could not
         # convert the response to JSON!
@@ -335,14 +348,6 @@ class ZeroconfConnect:
             # get the current device id from the device via Spotify ZeroConf API `getInfo` endpoint.
             info:ZeroconfGetInfo = self.GetInformation()
 
-            # are we including origin device information (e.g. deviceName, deviceId)?
-            # TODO - maybe tailor this to info.BrandDisplayName and info.ModelDisplayName instead?
-            includeOriginDeviceInfo:bool = False
-            if (info.PublicKey == 'SU5WQUxJRA==') and (info.Availability == 'NOT-LOADED'):
-                includeOriginDeviceInfo = True
-            elif info.TokenType == 'authorization_code':                
-                includeOriginDeviceInfo = True
-
             # execute the Spotify Zeroconf API addUser request.
             responseData:dict = self._ConnectAddUser(
                 info,
@@ -350,7 +355,6 @@ class ZeroconfConnect:
                 password,
                 loginId,
                 apiMethodName,
-                includeOriginDeviceInfo=includeOriginDeviceInfo
                 )
 
             # process results.
@@ -402,7 +406,6 @@ class ZeroconfConnect:
                     password,
                     loginId,
                     apiMethodName,
-                    includeOriginDeviceInfo=includeOriginDeviceInfo
                     )
 
                 # process results.
@@ -447,7 +450,6 @@ class ZeroconfConnect:
             password:str,
             loginId:str,
             apiMethodName:str,
-            includeOriginDeviceInfo:bool=False,
             ) -> dict:
         """
         Execute the `addUser` request.
@@ -459,17 +461,14 @@ class ZeroconfConnect:
             
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
-            apiMethodParms.AppendKeyValue("includeOriginDeviceInfo", includeOriginDeviceInfo)
             apiMethodParms.AppendKeyValue("info.Availability", info.Availability)
             apiMethodParms.AppendKeyValue("info.PublicKey", info.PublicKey)
+            apiMethodParms.AppendKeyValue("info.DeviceId", info.DeviceId)
+            apiMethodParms.AppendKeyValue("info.RemoteName", info.RemoteName)
             _logsi.LogMethodParmList(SILevel.Verbose, "Issuing Spotify Connect Zeroconf addUser request (ip=%s)" % self._HostIpAddress, apiMethodParms)
         
-            # validations.
-            if (includeOriginDeviceInfo is None):
-                includeOriginDeviceInfo = False
-            
             # formulate the blob.
-            credentials:Credentials = Credentials(username, password)
+            credentials:Credentials = Credentials(username, password, AuthenticationTypes.USER_PASS)
             builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
             blob = builder.build()
         
@@ -482,29 +481,41 @@ class ZeroconfConnect:
                 'Connection': 'close'
             }
             _logsi.LogDictionary(SILevel.Debug, "ZeroconfConnect http request: '%s' (headers)" % (endpoint), reqHeaders)
-            
-            # set tokenType based on getInfo token type.
-            # if TokenType is 'athorization_code', then use it as-is;
-            # otherwise, use 'default'.
+
+            # set defaults used by most manufacturers - we will tailor these in the
+            # logic below for specific manufacturers / devices as required:
+            # - clientKey should be the getInfo response PublicKey (base64 encoded).
+            # - exclude origin device information from the addUser request.
+            # - tokenType should be set to 'default'.
+            clientKey:str = builder.dh_keys.PublicKeyBase64String
+            includeOriginDeviceInfo:bool = False
             tokenType:str = 'default'
-            if info.TokenType == 'authorization_code':
-                tokenType = info.TokenType
             
-            # set clientKey based on getInfo token type.
-            # if TokenType is 'athorization_code', then clientKey should be null.
-            # otherwise, clientKey should be the PublicKey (base64 encoded).
-            clientKey:str = int_to_b64str(builder.dh_keys.public_key)
-            if info.TokenType == 'authorization_code':
+            # include the origin device information if PublicKey="INVALID" (base64 encoded) and availability="NOT-LOADED".
+            if (info.PublicKey == 'SU5WQUxJRA==') and (info.Availability == 'NOT-LOADED'):
+                includeOriginDeviceInfo = True
+
+            # special processing for tokenType "authorization_code":
+            # - include origin device information in the addUser request.
+            # - set the tokenType to 'authorization_code'.
+            # - set the clientKey value to null, as it is contained in the token.
+            if info.TokenType == 'authorization_code':                
                 clientKey = ''
-            
+                includeOriginDeviceInfo = True
+                tokenType = info.TokenType
+                
+                # TODO - not sure of the blob credentials layout for AuthenticationTypes.SPOTIFY_TOKEN requests.
+                # get a Spotify WebServices API auth token that the Sonos device can use.
+                #credentials:Credentials = Credentials(username, authToken, AuthenticationTypes.SPOTIFY_TOKEN)  # authToken is the password
+                #credentials:Credentials = Credentials('', authToken, AuthenticationTypes.SPOTIFY_TOKEN)  # authToken is the password
+                #builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
+                #blob = builder.build()
+
             # set request parameters.
             reqData={
                 'action': 'addUser',
                 'version': info.Version,
                 'tokenType': tokenType,
-                #'version': self.Version,
-                #'tokenType': 'default',                                     # NOTE - not the same as info.TokenType!
-                #'clientKey': int_to_b64str(builder.dh_keys.public_key),
                 'clientKey': clientKey,
                 'loginId': loginId or '',                                   # canonical login id (e.g. "31l77fd87g8h9j00k89f07jf87ge")
                 'userName': credentials.username.decode('ascii'),           # user name (e.g. "youremail@mail.com")
@@ -643,9 +654,32 @@ class ZeroconfConnect:
             # trace.
             _logsi.LogObject(SILevel.Verbose, '%s result (%s)' % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
 
-            # if result status is not ok, then raise an exception.
+            # was a status value returned?
+            # it's been found that some devices (Sonos, etc) do not return a proper JSON response.
+            # for these cases, we will rely on the http status code for the response code.
+            if (result.Status is None):
+
+                # was a good http status code returned?
+                if response.status_code == 200:
+                    
+                    # yes - default status results if they are not set.
+                    result.Status = 101
+                    if result.StatusString is None:
+                        result.StatusString = "OK"
+                    if result.SpotifyError is None:
+                        result.SpotifyError = 0
+
+            # are we processing result status?
             if (not ignoreStatusResult):
-                if (result.Status != 101):
+                
+                if (result.Status is None) and (response.status_code != 200):
+                    # if status value was not returned and http status is not 200, then 
+                    # raise an exception with http status details.
+                    raise SpotifyZeroconfApiError(response.status_code, responseData, apiMethodName, response.reason, _logsi)
+                        
+                elif (result.Status != 101):
+                    # if status was returned and it's not ok, then raise an exception
+                    # with JSON response details.
                     raise SpotifyZeroconfApiError(result.Status, result.ToString(), apiMethodName, result.StatusString, _logsi)
 
             # give spotify zeroconf api time to process the change.
@@ -724,6 +758,9 @@ class ZeroconfConnect:
         Raises:
             SpotifyWebApiError: 
                 If the Spotify Zeroconf API request response contains error information.
+                
+        The request will timeout after 5 seconds and an exception raised if the device cannot be reached 
+        or does not respond within that time frame.
 
         <details>
           <summary>Sample Code</summary>
@@ -768,7 +805,7 @@ class ZeroconfConnect:
             # execute spotify zeroconf api request.
             response = requests.get(
                 self._Uri, 
-                timeout=10,
+                timeout=5,
                 headers=reqHeaders,
                 params=reqParams
             )

spotifywebapipython/zeroconfapi/zeroconfgetinfo.py

@@ -133,7 +133,7 @@ class ZeroconfGetInfo(ZeroconfResponse):
 
         Device aliases will show up as separate devices in the Spotify app.  
         
-        Note
+        A maximum of 8 aliases are supported (SP_MAX_DEVICE_ALIASES).
         
         Please refer to the `RemoteName` property for more information.       
         """
@@ -146,9 +146,12 @@ class ZeroconfGetInfo(ZeroconfResponse):
         The SpZeroConfVars availability field returned by SpZeroConfGetVars.  
         
         The following are values that I have encountered thus far:  
-        - "" = Device is available and ready for use.
+        - ""            - Device is available and ready for use.
         - "UNAVAILABLE" - Device is unavailable, and should probably be rebooted.
-        - "NOT-LOADED" - Spotify SDK / API is not loaded.
+        - "NOT-LOADED"  - Spotify SDK / API is not loaded.
+        
+        The maximum length of the availability string (SP_MAX_AVAILABILITY_LENGTH) 
+        is 15 characters (not counting terminating NULL).       
         """
         return self._Availability
 
@@ -157,6 +160,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def BrandDisplayName(self) -> str:
         """ 
         A UTF-8-encoded brand name of the hardware device, for hardware integrations (e.g. "Bose", "Onkyo", etc).
+        
+        The maximum length of the brand display name (SP_MAX_BRAND_NAME_LENGTH) 
+        is 32 characters (not counting terminating NULL).       
         """
         return self._BrandDisplayName
 
@@ -165,6 +171,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def ClientId(self) -> str:
         """ 
         Client id of the application (e.g. "79ebcb219e8e4e123456789000123456").
+        
+        The maximum length of the client ID value (SP_MAX_CLIENT_ID_LENGTH) 
+        is 32 characters (not counting terminating NULL).
         """
         return self._ClientId
 
@@ -173,6 +182,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def DeviceId(self) -> str:
         """ 
         Unique device ID used for ZeroConf logins (e.g. "30fbc80e35598f3c242f2120413c943dfd9715fe").
+
+        The maximum length of the device ID value used for ZeroConf logins (SP_MAX_DEVICE_ID_LENGTH) 
+        is 64 characters (not counting terminating NULL).
         """
         return self._DeviceId
     
@@ -191,20 +203,23 @@ class ZeroconfGetInfo(ZeroconfResponse):
         Type of the device (e.g. "SPEAKER", "AVR", etc).
         
         Can be any of the following `SpDeviceType` devices:
-        - kSpDeviceTypeComputer	    Laptop or desktop computer device.
-        - kSpDeviceTypeTablet	    Tablet PC device.
-        - kSpDeviceTypeSmartphone	Smartphone device.
-        - kSpDeviceTypeSpeaker	    Speaker device.
-        - kSpDeviceTypeTV	        Television device.
-        - kSpDeviceTypeAVR	        Audio/Video receiver device.
-        - kSpDeviceTypeSTB	        Set-Top Box device.
-        - kSpDeviceTypeAudioDongle	Audio dongle device.
-        - kSpDeviceTypeGameConsole	Game console device.
-        - kSpDeviceTypeCastVideo	Chromecast Video.
-        - kSpDeviceTypeCastAudio	Chromecast Audio.
-        - kSpDeviceTypeAutomobile	Automobile.
-        - kSpDeviceTypeSmartwatch	Smartwatch.
-        - kSpDeviceTypeChromebook	Chromebook.        
+        - Computer	    Laptop or desktop computer device.
+        - Tablet	    Tablet PC device.
+        - Smartphone	Smartphone device.
+        - Speaker	    Speaker device.
+        - TV	        Television device.
+        - AVR	        Audio/Video receiver device.
+        - STB	        Set-Top Box device.
+        - AudioDongle	Audio dongle device.
+        - GameConsole	Game console device.
+        - CastVideo	    Chromecast Video.
+        - CastAudio	    Chromecast Audio.
+        - Automobile	Automobile.
+        - Smartwatch	Smartwatch.
+        - Chromebook	Chromebook.        
+        
+        The maximum length of the device type string (SP_MAX_DEVICE_TYPE_LENGTH) 
+        is 15 characters (not counting terminating NULL).
         """
         return self._DeviceType
     
@@ -221,6 +236,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def GroupStatus(self) -> str:
         """ 
         The SpZeroConfVars group_status field returned by SpZeroConfGetVars (e.g. "NONE").
+
+        The maximum length of the group status string (SP_MAX_GROUP_STATUS_LENGTH) 
+        is 15 characters (not counting terminating NULL).
         """
         return self._GroupStatus
 
@@ -255,6 +273,19 @@ class ZeroconfGetInfo(ZeroconfResponse):
         return False
     
 
+    @property
+    def IsBrandSonos(self) -> bool:
+        """ 
+        Returns True if the device is a 'Sonos' branded device; otherwise, False.
+        
+        Determination is made based upon the `BrandDisplayName` property value.
+        """
+        result:bool = False
+        if (isinstance(self._BrandDisplayName, str)) and (self._BrandDisplayName.lower().strip() == 'sonos'):
+            result = True
+        return result
+    
+
     @property
     def LibraryVersion(self) -> str:
         """ 
@@ -267,6 +298,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def ModelDisplayName(self) -> str:
         """ 
         A UTF-8-encoded model name of the hardware device, for hardware integrations (e.g. "Soundtouch").
+        
+        The maximum length of the model display name (SP_MAX_MODEL_NAME_LENGTH) 
+        is 30 characters (not counting terminating NULL).
         """
         return self._ModelDisplayName
 
@@ -283,6 +317,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def PublicKey(self) -> str:
         """ 
         Public key used in ZeroConf logins (e.g. "G+ZM4irhc...").
+        
+        The maximum length of the public key used in ZeroConf logins (SP_MAX_PUBLIC_KEY_LENGTH) 
+        is 149 characters (not counting terminating NULL).
         """
         return self._PublicKey
 
@@ -328,6 +365,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def Scope(self) -> str:
         """ 
         OAuth scope requested when authenticating with the Spotify backend (e.g. "streaming").
+        
+        The maximum length of the token type string (SP_MAX_SCOPE_LENGTH) 
+        is 64 characters (not counting terminating NULL).
         """
         return self._Scope
 
@@ -344,6 +384,8 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def SupportedDrmMediaFormats(self) -> list:
         """ 
         The SpZeroConfVars supported_drm_media_formats field returned by SpZeroConfGetVars (e.g. []).
+        
+        A maximum of 8 formats are supported (SP_MAX_SUPPORTED_FORMATS).
         """
         return self._SupportedDrmMediaFormats
 
@@ -351,7 +393,13 @@ class ZeroconfGetInfo(ZeroconfResponse):
     @property
     def TokenType(self) -> str:
         """ 
-        Token type provided by the client (e.g. "accesstoken", "authorization_code", etc).
+        Token type provided by the client:
+        - "accesstoken"         Access token.
+        - "authorization_code"  OAuth Authorization Code token.
+        - "default"             Default access token.
+        
+        The maximum length of the token type string (SP_MAX_TOKEN_TYPE_LENGTH) 
+        is 30 characters (not counting terminating NULL).
         """
         return self._TokenType
 
@@ -360,6 +408,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def Version(self) -> str:
         """ 
         ZeroConf API version number (e.g. "2.10.0").
+        
+        The maximum length of the library version string (SP_MAX_VERSION_LENGTH) 
+        is 30 characters (not counting terminating NULL).
         """
         return self._Version