mms-client 1.5.1__tar.gz → 1.7.0__tar.gz

{mms_client-1.5.1 → mms_client-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mms-client
-Version: 1.5.1
+Version: 1.7.0
 Summary: API client for accessing the MMS
 Home-page: https://github.com/ElectroRoute-Japan/mms-client
 Author: Ryan Wood
@@ -22,6 +22,7 @@ Requires-Dist: backoff (>=2.2.1,<3.0.0)
 Requires-Dist: cryptography (>=42.0.5,<43.0.0)
 Requires-Dist: lxml (>=5.1.0,<6.0.0)
 Requires-Dist: pendulum (>=3.0.0,<4.0.0)
+Requires-Dist: pycryptodomex (>=3.20.0,<4.0.0)
 Requires-Dist: pydantic (>=2.6.3,<3.0.0)
 Requires-Dist: pydantic-xml (>=2.9.0,<3.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
@@ -43,6 +44,9 @@ The underlying API sends and receives XML documents. Each of these request or re
 
 After the data has been converted and added to the outer request object, it is sent to the appropriate server endpoint via a Zeep client. The client certificate is also injected into the request using a PCKS12 adaptor.
 
+## Domain
+The domain to use when signing the content ID to MTOM attachments is specified when creating the client. This is not verified by the server, but it is used to generate the content ID for the MTOM attachments. As such, it is important to ensure that the domain is correct.
+
 # Serialization
 This library relies on Pydantic 2 and the pydantic-xml library for serialization/deserialization. As such, any type in this library can be converted to not only XML, but to JSON as well. This is extremely useful if you're trying to build a pass-through API service or something similar.
 
@@ -142,7 +146,7 @@ from mms_client.utils.web import ClientType
 cert = Certificate("/path/to/my/cert.p12", "fake_passphrase")
 
 # Create a new MMS client
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
 
 # Create our request offer
 request_offer = OfferData(
@@ -176,14 +180,14 @@ There's a lot of code here but it's not terribly difficult to understand. All th
 If you want to test your MMS connection, you can try using the test server:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
 ```
 
 ## Connecting as a Market Admin
 If you're connecting as a market operator (MO), you can connect in admin mode:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
 ```
 
 ## Auditing XML Requests & Responses
@@ -202,13 +206,14 @@ class TestAuditPlugin(AuditPlugin):
     def audit_response(self, mms_response: bytes) -> None:
         self.response = mms_response
 
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
 ```
 
 This same input allows for the user to create their own plugins and add them to the Zeep client, allowing for a certain amount of extensibility.
 
 # Completeness
 This client is not complete. Currently, it supports the following endpoints:
+- MarketQuery_ReserveRequirementQuery
 - MarketSubmit_OfferData
 - MarketQuery_OfferQuery
 - MarketCancel_OfferCancel

{mms_client-1.5.1 → mms_client-1.7.0}/README.md

@@ -11,6 +11,9 @@ The underlying API sends and receives XML documents. Each of these request or re
 
 After the data has been converted and added to the outer request object, it is sent to the appropriate server endpoint via a Zeep client. The client certificate is also injected into the request using a PCKS12 adaptor.
 
+## Domain
+The domain to use when signing the content ID to MTOM attachments is specified when creating the client. This is not verified by the server, but it is used to generate the content ID for the MTOM attachments. As such, it is important to ensure that the domain is correct.
+
 # Serialization
 This library relies on Pydantic 2 and the pydantic-xml library for serialization/deserialization. As such, any type in this library can be converted to not only XML, but to JSON as well. This is extremely useful if you're trying to build a pass-through API service or something similar.
 
@@ -110,7 +113,7 @@ from mms_client.utils.web import ClientType
 cert = Certificate("/path/to/my/cert.p12", "fake_passphrase")
 
 # Create a new MMS client
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert)
 
 # Create our request offer
 request_offer = OfferData(
@@ -144,14 +147,14 @@ There's a lot of code here but it's not terribly difficult to understand. All th
 If you want to test your MMS connection, you can try using the test server:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, test=True)
 ```
 
 ## Connecting as a Market Admin
 If you're connecting as a market operator (MO), you can connect in admin mode:
 
 ```python
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, is_admin=True)
 ```
 
 ## Auditing XML Requests & Responses
@@ -170,13 +173,14 @@ class TestAuditPlugin(AuditPlugin):
     def audit_response(self, mms_response: bytes) -> None:
         self.response = mms_response
 
-client = MmsClient(participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
+client = MmsClient(domain="mydomain.com", participant="F100", user="FAKEUSER", client_type=ClientType.BSP, cert, plugins=[TestAuditPlugin()])
 ```
 
 This same input allows for the user to create their own plugins and add them to the Zeep client, allowing for a certain amount of extensibility.
 
 # Completeness
 This client is not complete. Currently, it supports the following endpoints:
+- MarketQuery_ReserveRequirementQuery
 - MarketSubmit_OfferData
 - MarketQuery_OfferQuery
 - MarketCancel_OfferCancel

{mms_client-1.5.1 → mms_client-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "mms_client"
-version = "v1.5.1"
+version = "v1.7.0"
 description = "API client for accessing the MMS"
 authors = ["Ryan Wood <ryan.wood@electroroute.co.jp>"]
 readme = "README.md"
@@ -32,6 +32,7 @@ cryptography = "^42.0.5"
 pydantic-xml = "^2.9.0"
 lxml = "^5.1.0"
 backoff = "^2.2.1"
+pycryptodomex = "^3.20.0"
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.2.0"

mms_client-1.7.0/src/mms_client/security/certs.py

@@ -0,0 +1,77 @@
+"""Contains functionality associated with certificates."""
+
+from pathlib import Path
+from ssl import PROTOCOL_TLSv1_2
+from typing import Union
+
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
+from cryptography.hazmat.primitives.serialization import Encoding
+from cryptography.hazmat.primitives.serialization import NoEncryption
+from cryptography.hazmat.primitives.serialization import PrivateFormat
+from cryptography.hazmat.primitives.serialization import PublicFormat
+from cryptography.hazmat.primitives.serialization.pkcs12 import load_key_and_certificates
+from requests_pkcs12 import Pkcs12Adapter
+
+
+class Certificate:
+    """Describes a certificate composed of a cert file and a key file."""
+
+    # The encoding to use for MMS certificates
+    encoding = Encoding.PEM
+
+    def __init__(self, cert: Union[str, Path, bytes], passphrase: str):
+        """Create a new Certificate.
+
+        Creates a new certificate from the absolute path to the certificate file and a passpharse.
+
+        Arguments:
+        cert:           The certificate file. If a string, it should be the absolute path to the certificate file. If
+                        bytes, it should be the contents of the certificate file.
+        passphrase:     The passphrase the certificate is encrypted with
+        """
+        # Get the certificate file contents
+        if isinstance(cert, (str, Path)):
+            with open(cert, "rb") as file:
+                self._cert = file.read()
+        else:
+            self._cert = cert
+
+        # Save the passphrase
+        self._passphrase = passphrase
+
+        # Load the private key using the cryptography library
+        private_key, _, _ = load_key_and_certificates(self._cert, self._passphrase.encode("UTF-8"))
+        if isinstance(private_key, RSAPrivateKey):
+            self._private = private_key
+        else:
+            raise TypeError(f"Private key of type ({type(private_key).__name__}) was not expected.")
+
+    @property
+    def certificate(self) -> bytes:
+        """Return the certificate data."""
+        return self._cert
+
+    @property
+    def passphrase(self) -> str:
+        """Return the full path to the passphrase."""
+        return self._passphrase
+
+    def public_key(self) -> bytes:
+        """Extract the public key from the certificate.
+
+        Returns: The public key in PEM format.
+        """
+        return self._private.public_key().public_bytes(Certificate.encoding, PublicFormat.PKCS1)
+
+    def private_key(self) -> bytes:
+        """Extract the private key from the certificate.
+
+        THIS SHOULD NOT, UNDER ANY CIRCUMSTANCES, BE PRINTED OR LOGGED!!!
+
+        Returns: The private key in PEM format.
+        """
+        return self._private.private_bytes(Certificate.encoding, PrivateFormat.PKCS8, NoEncryption())
+
+    def to_adapter(self) -> Pkcs12Adapter:
+        """Convert the certificate to a Pkcs12Adapter."""
+        return Pkcs12Adapter(pkcs12_data=self._cert, pkcs12_password=self._passphrase, ssl_protocol=PROTOCOL_TLSv1_2)

mms_client-1.7.0/src/mms_client/security/crypto.py

@@ -0,0 +1,65 @@
+"""Contains objects for cryptographic operations."""
+
+from base64 import b64decode
+from base64 import b64encode
+
+from Cryptodome.Hash import SHA256
+from Cryptodome.PublicKey import RSA
+from Cryptodome.Signature import pkcs1_15
+
+from mms_client.security.certs import Certificate
+
+
+class CryptoWrapper:
+    """Wraps the cryptographic operations necessary for signing and encrypting MMS payload data."""
+
+    def __init__(self, cert: Certificate):
+        """Create a new CryptoWrapper with the given certificate.
+
+        Arguments:
+        cert (Certificate): The certificate to use for cryptographic operations.
+        """
+        # Extract the public key and private key data from the certificate
+        private_key = RSA.import_key(cert.private_key())
+        public_key = RSA.import_key(cert.public_key())
+
+        # Create a new signer from the private key and a new verifier from the public key
+        self._signer = pkcs1_15.new(private_key)
+        self._verifier = pkcs1_15.new(public_key)
+
+    def verify(self, content: bytes, signature: bytes) -> bool:
+        """Verify a signature against the given content using the certificate.
+
+        Arguments:
+        content (bytes):    The content to verify.
+        signature (bytes):  The signature to verify against the content.
+
+        Returns:    True if the signature is valid, False otherwise.
+        """
+        # Hash the content using SHA256
+        hashed = SHA256.new(content)
+
+        # Verify the signature using the public key. This will raise a ValueError if the signature is invalid.
+        # We catch this exception and return False to indicate that the signature is invalid.
+        try:
+            self._verifier.verify(hashed, b64decode(signature))
+            return True
+        except ValueError:
+            return False
+
+    def sign(self, data: bytes) -> bytes:
+        """Create a signature from the given data using the certificate.
+
+        Arguments:
+        data (bytes):   The data to be encrypted.
+
+        Returns:    A base64-encoded string containing the signature.
+        """
+        # First, hash the data using SHA256
+        hashed = SHA256.new(data)
+
+        # Next, sign the hash using the private key
+        signature = self._signer.sign(hashed)
+
+        # Finally, return the base64-encoded signature
+        return b64encode(signature)

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/services/base.py

@@ -1,5 +1,6 @@
 """Contains the client layer for communicating with the MMS server."""
 
+from base64 import b64decode
 from dataclasses import dataclass
 from logging import getLogger
 from typing import Dict
@@ -28,6 +29,7 @@ from mms_client.types.transport import RequestType
 from mms_client.types.transport import ResponseDataType
 from mms_client.utils.errors import AudienceError
 from mms_client.utils.errors import MMSClientError
+from mms_client.utils.errors import MMSServerError
 from mms_client.utils.errors import MMSValidationError
 from mms_client.utils.serialization import Serializer
 from mms_client.utils.web import ClientType
@@ -247,6 +249,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
     def __init__(
         self,
+        domain: str,
         participant: str,
         user: str,
         client_type: ClientType,
@@ -258,6 +261,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         """Create a new MMS client with the given participant, user, client type, and authentication.
 
         Arguments:
+        domain (str):               The domain to use when signing the content ID to MTOM attachments.
         participant (str):          The MMS code of the business entity to which the requesting user belongs.
         user (str):                 The user name of the person making the request.
         client_type (ClientType):   The type of client to use for making requests to the MMS server.
@@ -268,6 +272,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         test (bool):                Whether to use the test server.
         """
         # First, save the base field associated with the client
+        self._domain = domain
         self._participant = participant
         self._user = user
         self._client_type = client_type
@@ -328,18 +333,23 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
         Returns:    The response from the MMS server.
         """
+        # Create a new ZWrapper for the given service
+        wrapper = self._get_wrapper(config.service)
+
         # First, create the MMS request from the payload and data.
         logger.debug(
             f"{config.name}: Starting request. Envelope: {type(envelope).__name__}, Data: {type(payload).__name__}",
         )
-        request = self._to_mms_request(config.request_type, config.service.serializer.serialize(envelope, payload))
+        request = self._to_mms_request(
+            wrapper, config.request_type, config.service.serializer.serialize(envelope, payload)
+        )
 
         # Next, submit the request to the MMS server and get and verify the response.
-        resp = self._get_wrapper(config.service).submit(request)
+        resp = wrapper.submit(request)
         self._verify_mms_response(resp, config)
 
         # Now, extract the attachments from the response
-        attachments = {a.name: a.data for a in resp.attachments}
+        attachments = {a.name: b64decode(a.data) for a in resp.attachments}
 
         # Finally, deserialize and verify the response
         envelope_type = config.response_envelope_type or type(envelope)
@@ -368,6 +378,9 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
         Returns:    The multi-response from the MMS server.
         """
+        # Create a new ZWrapper for the given service
+        wrapper = self._get_wrapper(config.service)
+
         # First, create the MMS request from the payload and data.
         is_list = isinstance(payload, list)
         data_type = type(payload[0]) if is_list else type(payload)  # type: ignore[index]
@@ -382,14 +395,14 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
             if is_list
             else config.service.serializer.serialize(envelope, payload)  # type: ignore[type-var]
         )
-        request = self._to_mms_request(config.request_type, serialized)
+        request = self._to_mms_request(wrapper, config.request_type, serialized)
 
         # Next, submit the request to the MMS server and get and verify the response.
-        resp = self._get_wrapper(config.service).submit(request)
+        resp = wrapper.submit(request)
         self._verify_mms_response(resp, config)
 
         # Now, extract the attachments from the response
-        attachments = {a.name: a.data for a in resp.attachments}
+        attachments = {a.name: b64decode(a.data) for a in resp.attachments}
 
         # Finally, deserialize and verify the response
         envelope_type = config.response_envelope_type or type(envelope)
@@ -409,6 +422,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
     def _to_mms_request(
         self,
+        client: ZWrapper,
         req_type: RequestType,
         data: bytes,
         return_req: bool = False,
@@ -417,6 +431,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         """Convert the given data to an MMS request.
 
         Arguments:
+        client (ZWrapper):              The Zeep client to use for submitting the request.
         req_type (RequestType):         The type of request to submit to the MMS server.
         data (bytes):                   The data to submit to the MMS server.
         return_req (bool):              Whether to return the request data in the response. This is False by default.
@@ -424,16 +439,14 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
 
         Arguments:    The MMS request to submit to the MMS server.
         """
-        # Convert the attachments to the correct the MMS format
+        # First, convert the attachments to the correct the MMS format
         attachment_data = (
-            [
-                Attachment(signature=self._signer.sign(data), name=name, binaryData=data)
-                for name, data in attachments.items()
-            ]
-            if attachments
-            else []
+            [self._to_mms_attachment(client, name, data) for name, data in attachments.items()] if attachments else []
         )
 
+        # Next, convert the payload to a base-64 string
+        tag, signature = self._register_and_sign(client, "payload", data)
+
         # Embed the data and the attachments in the MMS request and return it
         logger.debug(
             f"Creating MMS request of type {req_type.name} to send {len(data)} bytes of data and "
@@ -444,11 +457,36 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
             adminRole=self._is_admin,
             requestDataType=RequestDataType.XML,
             sendRequestDataOnSuccess=return_req,
-            requestSignature=self._signer.sign(data),
-            requestData=data,
+            requestSignature=signature,
+            requestData=tag,
             attachmentData=attachment_data,
         )
 
+    def _to_mms_attachment(self, client: ZWrapper, name: str, data: bytes) -> Attachment:  # pragma: no cover
+        """Convert the given data to an MMS attachment.
+
+        Arguments:
+        client (ZWrapper):  The Zeep client to use for submitting the request.
+        name (str):         The name of the attachment.
+        data (bytes):       The data to be attached.
+
+        Returns:    The MMS attachment.
+        """
+        # Convert the data to a base-64 string
+        tag, signature = self._register_and_sign(client, name, data)
+
+        # Create the MMS attachment and return it
+        return Attachment(signature=signature, name=name, binaryData=tag)
+
+    def _register_and_sign(self, client: ZWrapper, name: str, data: bytes) -> Tuple[str, str]:
+        tag = client.register_attachment(name, data)
+
+        # Next, sign the data
+        signature = self._signer.sign(data)
+
+        # Finally, convert the encoded data to a string and return it and the signature
+        return tag, signature.decode("UTF-8")
+
     def _verify_mms_response(self, resp: MmsResponse, config: EndpointConfiguration) -> None:
         """Verify that the given MMS response is valid.
 
@@ -459,7 +497,11 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         MMSClientError: If the response is not valid.
         """
         # Verify that the response is in the correct format. If it's not, raise an error.
-        if resp.data_type != ResponseDataType.XML:
+        # NOTE: We're disabling the no-else-raise rule here because both comparisons are on the same enum so if one is
+        # removed then the other will raise an error. This is a false positive.
+        if resp.data_type == ResponseDataType.TXT:  # pylint: disable=no-else-raise
+            raise MMSServerError(config.name, resp.payload.decode("UTF-8"))
+        elif resp.data_type != ResponseDataType.XML:
             raise MMSClientError(
                 config.name,
                 f"Invalid MMS response data type: {resp.data_type.name}. Only XML is supported.",
@@ -592,6 +634,7 @@ class BaseClient:  # pylint: disable=too-many-instance-attributes
         if service.interface not in self._wrappers:
             logger.debug(f"Creating wrapper for {service.interface.name} interface.")
             self._wrappers[service.interface] = ZWrapper(
+                self._domain,
                 self._client_type,
                 service.interface,
                 self._cert.to_adapter(),

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/services/market.py

@@ -18,6 +18,8 @@ from mms_client.types.market import MarketType
 from mms_client.types.offer import OfferCancel
 from mms_client.types.offer import OfferData
 from mms_client.types.offer import OfferQuery
+from mms_client.types.reserve import ReserveRequirement
+from mms_client.types.reserve import ReserveRequirementQuery
 from mms_client.types.transport import RequestType
 from mms_client.utils.serialization import SchemaType
 from mms_client.utils.serialization import Serializer
@@ -34,6 +36,36 @@ class MarketClientMixin:  # pylint: disable=unused-argument
     # The configuration for the market service
     config = ServiceConfiguration(Interface.MI, Serializer(SchemaType.MARKET, "MarketData"))
 
+    @mms_endpoint(
+        "MarketQuery_ReserveRequirementQuery",
+        config,
+        RequestType.INFO,
+        resp_envelope_type=MarketSubmit,
+        resp_data_type=ReserveRequirement,
+    )
+    def query_reserve_requirements(
+        self: ClientProto, request: ReserveRequirementQuery, days: int, date: Optional[Date] = None
+    ) -> List[ReserveRequirement]:
+        """Query the MMS server for reserve requirements.
+
+        This endpoint is accessible to all client types.
+
+        Arguments:
+        request (ReserveRequirementQuery):  The query to submit to the MMS server.
+        date (Date):                        The date of the transaction in the format "YYYY-MM-DD". This value defaults
+                                            to the current date.
+        days (int):                         The number of days ahead for which the data is being queried.
+
+        Returns:    A list of reserve requirements that match the query.
+        """
+        # NOTE: The return type does not match the method definition but the decorator will return the correct type
+        return MarketQuery(  # type: ignore[return-value]
+            date=date or Date.today(),
+            participant=self.participant,
+            user=self.user,
+            days=days,
+        )
+
     @mms_endpoint("MarketSubmit_OfferData", config, RequestType.INFO, [ClientType.BSP])
     def put_offer(
         self: ClientProto, request: OfferData, market_type: MarketType, days: int, date: Optional[Date] = None
@@ -124,6 +156,8 @@ class MarketClientMixin:  # pylint: disable=unused-argument
         days (int):                 The number of days ahead for which the data is being cancelled.
         date (Date):                The date of the transaction in the format "YYYY-MM-DD". This value defaults to the
                                     current date.
+
+        Returns:    Data identifying the offer that was cancelled.
         """
         # NOTE: The return type does not match the method definition but the decorator will return the correct type
         return MarketCancel(  # type: ignore[return-value]
@@ -134,7 +168,7 @@ class MarketClientMixin:  # pylint: disable=unused-argument
             days=days,
         )
 
-    @mms_endpoint("MarketQuery_AwardResultsQuery", config, RequestType.INFO, resp_data_type=AwardResponse)
+    @mms_endpoint("MarketQuery_AwardResultsQuery", config, RequestType.MARKET, resp_data_type=AwardResponse)
     def query_awards(self: ClientProto, request: AwardQuery, days: int, date: Optional[Date] = None) -> AwardResponse:
         """Query the MMS server for award results.
 

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/types/base.py

@@ -115,12 +115,9 @@ class SchemaType(Enum):
     OMI = "omi.xsd"
 
 
-class PayloadBase(BaseXmlModel, nsmap={"xsi": "http://www.w3.org/2001/XMLSchema-instance"}):
+class PayloadBase(BaseXmlModel):
     """Represents the base fields for an MMS request payload."""
 
-    # The XML schema to use for validation
-    location: SchemaType = attr(name="noNamespaceSchemaLocation", ns="xsi")
-
 
 class BaseResponse(BaseXmlModel, Generic[E], tag="BaseResponse"):
     """Contains the base data extracted from the MMS response in a format we can use."""

mms_client-1.7.0/src/mms_client/types/reserve.py

@@ -0,0 +1,71 @@
+"""Contains objects for MMS reserve requirements."""
+
+from typing import List
+from typing import Optional
+
+from pydantic_extra_types.pendulum_dt import DateTime
+from pydantic_xml import attr
+from pydantic_xml import element
+
+from mms_client.types.base import Payload
+from mms_client.types.enums import AreaCode
+from mms_client.types.enums import Direction
+from mms_client.types.fields import power_positive
+from mms_client.types.market import MarketType
+
+
+class Requirement(Payload):
+    """Represents a reserve requirement."""
+
+    # The start block of the requirement
+    start: DateTime = attr(name="StartTime")
+
+    # The end block of the requirement
+    end: DateTime = attr(name="EndTime")
+
+    # The direction of the requirement
+    direction: Direction = attr(name="Direction")
+
+    # The primary reserve quantity in kW
+    primary_qty_kw: Optional[int] = power_positive("PrimaryReserveQuantityInKw", True)
+
+    # The first secondary reserve quantity in kW
+    secondary_1_qty_kw: Optional[int] = power_positive("Secondary1ReserveQuantityInKw", True)
+
+    # The second secondary reserve quantity in kW
+    secondary_2_qty_kw: Optional[int] = power_positive("Secondary2ReserveQuantityInKw", True)
+
+    # The first tertiary reserve quantity in kW
+    tertiary_1_qty_kw: Optional[int] = power_positive("Tertiary1ReserveQuantityInKw", True)
+
+    # The second tertiary reserve quantity in kW
+    tertiary_2_qty_kw: Optional[int] = power_positive("Tertiary2ReserveQuantityInKw", True)
+
+    # The minimum reserve of compound primary and secondary 1 in kW
+    primary_secondary_1_qty_kw: Optional[int] = power_positive("CompoundPriSec1ReserveQuantityInKw", True)
+
+    # The minimum reserve of compound primary and secondary 2 in kW
+    primary_secondary_2_qty_kw: Optional[int] = power_positive("CompoundPriSec2ReserveQuantityInKw", True)
+
+    # The minimum reserve of compound primary and tertiary 1 in kW
+    primary_tertiary_1_qty_kw: Optional[int] = power_positive("CompoundPriTer1ReserveQuantityInKw", True)
+
+
+class ReserveRequirement(Payload):
+    """Represents a set of reserve requirements."""
+
+    # The area for which the reserve requirement applies
+    area: AreaCode = attr(name="Area")
+
+    # The requirements associated with the area
+    requirements: List[Requirement] = element(tag="Requirement", min_length=1)
+
+
+class ReserveRequirementQuery(Payload):
+    """Represents a request to query reserve requirements."""
+
+    # The market type for which to query reserve requirements
+    market_type: MarketType = attr(name="MarketType")
+
+    # The area for which to query reserve requirements
+    area: Optional[AreaCode] = attr(default=None, name="Area")

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/types/transport.py

@@ -55,7 +55,7 @@ class Attachment(BaseModel):
     name: str = Field(alias="name")
 
     # The attachment file data
-    data: bytes = Field(alias="binaryData")
+    data: str = Field(alias="binaryData")
 
 
 class MmsRequest(BaseModel):
@@ -83,7 +83,7 @@ class MmsRequest(BaseModel):
     signature: str = Field(alias="requestSignature")
 
     # The base-64 encoded payload of the request
-    payload: bytes = Field(alias="requestData")
+    payload: str = Field(alias="requestData")
 
     # Any attached files to be sent with the request. Only 20 of these are allowed for OMI requests. For MI requests,
     # the limit is 40.

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/utils/errors.py

@@ -38,6 +38,21 @@ class AudienceError(ValueError):
         super().__init__(self.message)
 
 
+class MMSServerError(RuntimeError):
+    """Error raised when the MMS server returns an error."""
+
+    def __init__(self, method: str, message: str):
+        """Initialize the error.
+
+        Arguments:
+        method (str):   The method that caused the error.
+        message (str):  The error message.
+        """
+        super().__init__(f"{method}: {message}")
+        self.message = message
+        self.method = method
+
+
 class MMSClientError(RuntimeError):
     """Base class for MMS client errors."""
 

mms_client-1.7.0/src/mms_client/utils/multipart_transport.py

@@ -0,0 +1,259 @@
+"""Contains a transport override supporting MTOMS attachments."""
+
+import string
+from base64 import b64encode
+from email.encoders import encode_7or8bit
+from email.mime.application import MIMEApplication
+from email.mime.base import MIMEBase
+from email.mime.multipart import MIMEMultipart
+from logging import getLogger
+from random import SystemRandom
+from typing import Dict
+from typing import Optional
+
+from lxml import etree
+from lxml.etree import _Element as Element
+from pendulum import now
+from requests import Session
+from zeep.cache import VersionedCacheBase
+from zeep.transports import Transport
+from zeep.wsdl.utils import etree_to_string
+
+# Set the default logger for the MMS client
+logger = getLogger(__name__)
+
+
+# Define the namespaces used in the XML
+XOP = "http://www.w3.org/2004/08/xop/include"
+XMIME5 = "http://www.w3.org/2005/05/xmlmime"
+FILETAG = "xop:Include:"
+ID_LEN = 16
+
+
+# Define a function to generate a randomized ID string
+def get_id(length: int = ID_LEN) -> str:
+    """Generate a randomized ID string.
+
+    Arguments:
+    length (int):   The length of the ID string to generate.
+
+    Returns:    The randomized ID string.
+    """
+    return "".join(SystemRandom().choice(string.ascii_uppercase + string.digits) for _ in range(length))
+
+
+def now_b64():
+    """Return a base64 encoded string of the current timestamp."""
+    return b64encode(f"{now().timestamp()}".replace(".", "").encode("UTF-8")).decode("UTF-8")
+
+
+def get_boundary() -> str:
+    """Return a randomized MIME boundary string."""
+    return f"MIMEBoundary_{now_b64()}".center(33, "=")
+
+
+def get_content_id(domain: str) -> str:
+    """Return a randomized MIME content ID string.
+
+    Arguments:
+    domain (str):   The domain of the content ID.
+
+    Returns:    The randomized MIME content ID string.
+    """
+    return f"<{now_b64()}@{domain}>"
+
+
+def overwrite_attachnode(node):
+    """Overwrite the attachment node.
+
+    Arguments:
+    node (Element):    The XML node to be overwritten.
+
+    Returns:    The attachment node.
+    """
+    cid = node.text[len(FILETAG) :]
+    node.text = None
+    etree.SubElement(node, f"{{{XOP}}}Include", nsmap={"xop": XOP}, href=f"cid:{cid}")
+    return cid
+
+
+def get_multipart(content_id: str) -> MIMEMultipart:
+    """Create a MIME multipart object.
+
+    Arguments:
+    content_id (str):   The content ID to be used for the attachment.
+
+    Returns:    The MIME multipart object.
+    """
+    part = MIMEMultipart(
+        "related", charset="UTF-8", type="application/xop+xml", boundary=get_boundary(), start=content_id
+    )
+    part.set_param("start-info", "application/soap+xml")
+    return part
+
+
+def get_envelope_part(envelope: Element, content_id: str) -> MIMEApplication:
+    """Create the MIME envelope part.
+
+    Arguments:
+    envelope (Element):    The XML envelope to be attached.
+    content_id (str):      The content ID to be used for the attachment.
+
+    Returns:    The MIME envelope part.
+    """
+    part = MIMEApplication(etree_to_string(envelope), "xop+xml", encode_7or8bit)
+    part.set_param("charset", "utf-8")
+    part.set_param("type", "text/xml")
+    part.add_header("Content-ID", content_id)
+    part.add_header("Content-Transfer-Encoding", "binary")
+    return part
+
+
+class Attachment:
+    """Represents an attachment to be sent with a multipart request."""
+
+    def __init__(self, name: str, data: bytes, domain: str):
+        """Create a new attachment.
+
+        Arguments:
+        name (str):   The name of the attachment.
+        data (bytes): The data to be attached.
+        domain (str): The domain of the content ID.
+        """
+        self.name = name
+        self.data = data
+        self.cid = f"{get_id()}-{name}@{domain}"
+        self.tag = FILETAG + self.cid
+
+
+class MultipartTransport(Transport):
+    """A transport that supports MTOMS attachments."""
+
+    def __init__(
+        self,
+        domain: str,
+        cache: Optional[VersionedCacheBase] = None,
+        timeout: int = 300,
+        operation_timeout: Optional[int] = None,
+        session: Optional[Session] = None,
+    ):
+        """Create a new MTOMS transport.
+
+        Arguments:
+        domain (str):                           The domain of the content ID to use.
+        cache (VersionedCacheBase, optional):   The cache to be used for the transport.
+        timeout (int):                          The timeout for the transport.
+        operation_timeout (int, optional):      The operation timeout for the transport.
+        session (Session, optional):            The session to be used for the transport.
+        """
+        # Save the domain for later use
+        self._domain = domain
+
+        # Setup a dictionary to store the attachments after they're registered
+        self._attachments: Dict[str, Attachment] = {}
+
+        # Call the parent constructor
+        super().__init__(
+            cache=cache,
+            timeout=timeout,
+            operation_timeout=operation_timeout,
+            session=session,
+        )
+
+    def register_attachment(self, name: str, data: bytes) -> str:
+        """Register an attachment.
+
+        Registered attachments will be sent with the request as MTOMS attachments. The content ID of the attachment
+        will be returned so that it can be used in the request.
+
+        Arguments:
+        name (str):     The name of the attachment.
+        data (bytes):   The data to be attached.
+
+        Returns:    The content ID of the attachment, which should be used in place of the attachment data.
+        """
+        attachment = Attachment(name, data, self._domain)
+        self._attachments[attachment.cid] = attachment
+        return attachment.tag
+
+    def post_xml(self, address: str, envelope: Element, headers: dict):
+        """Post the XML envelope and attachments.
+
+        Arguments:
+        address (str):      The address to post the data to.
+        envelope (Element): The XML envelope to be attached.
+        headers (dict):     The headers to be used for the request.
+
+        Returns:    The response from the server.
+        """
+        # Search for values that start with our FILETAG
+        filetags = envelope.xpath(f"//*[starts-with(text(), '{FILETAG}')]")
+
+        # if there are any attached files, we will set the attachments. Otherwise, just the envelope
+        if filetags:
+            message = self.create_mtom_request(filetags, envelope, headers).encode("UTF-8")
+        else:
+            message = etree_to_string(envelope)
+
+        # Post the request and return the response
+        return self.post(address, message, headers)
+
+    def create_mtom_request(self, filetags, envelope: Element, headers: dict) -> str:
+        """Set MTOM attachments and return the right envelope.
+
+        Arguments:
+        filetags (list):    The list of XML paths to the attachments.
+        envelope (Element): The XML envelope to be attached.
+        headers (dict):     The headers to be used for the request.
+
+        Returns:    The XML envelope with the attachments.
+        """
+        # First, get an identifier for the request and then use it to create a new multipart request
+        content_id = get_content_id(self._domain)
+        mtom_part = get_multipart(content_id)
+
+        # Next, let's set the XOP:Include nodes for each attachment
+        files = [overwrite_attachnode(f) for f in filetags]
+
+        # Now, create the request envelope and attach it to the multipart request
+        env_part = get_envelope_part(envelope, content_id)
+        mtom_part.attach(env_part)
+
+        # Attach each file to the multipart request
+        for cid in files:
+            mtom_part.attach(self.create_attachment(cid))
+
+        # Finally, create the final multipart request string
+        bound = f"--{mtom_part.get_boundary()}"
+        marray = mtom_part.as_string().split(bound)
+        mtombody = bound + bound.join(marray[1:])
+
+        # Set the content length and add the MTOM headers to the request
+        mtom_part.add_header("Content-Length", str(len(mtombody)))
+        headers.update(dict(mtom_part.items()))
+
+        # Decode the XML and return the request
+        message = mtom_part.as_string().split("\n\n", 1)[1]
+        message = message.replace("\n", "\r\n", 5)
+        return message
+
+    def create_attachment(self, cid):
+        """Create an attachment for the multipart request.
+
+        Arguments:
+        cid (str):   The content ID of the attachment.
+
+        Returns:    The attachment.
+        """
+        # First, get the attachment from the cache
+        attach = self._attachments[cid]
+
+        # Next, create the attachment
+        part = MIMEBase("application", "octet-stream")
+        part["Content-Transfer-Encoding"] = "binary"
+        part["Content-ID"] = f"<{attach.cid}>"
+        part.set_payload(attach.data, charset="utf-8")
+        del part["mime-version"]
+
+        # Finally, return the attachment
+        return part

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/utils/serialization.py

@@ -80,7 +80,7 @@ class Serializer:
 
         # Finally, convert the payload to XML and return it
         # NOTE: we provided the encoding here so this will return bytes, not a string
-        return payload.to_xml(skip_empty=True, encoding="utf-8", xml_declaration=True)  # type: ignore[return-value]
+        return self._to_canoncialized_xml(payload)
 
     def serialize_multi(self, request_envelope: E, request_data: List[P], request_type: Type[P]) -> bytes:
         """Serialize the envelope and data to a byte string for sending to the MMS server.
@@ -104,7 +104,7 @@ class Serializer:
 
         # Finally, convert the payload to XML and return it
         # NOTE: we provided the encoding here so this will return bytes, not a string
-        return payload.to_xml(skip_empty=True, encoding="utf-8", xml_declaration=True)  # type: ignore[return-value]
+        return self._to_canoncialized_xml(payload)
 
     def deserialize(self, data: bytes, envelope_type: Type[E], data_type: Type[P]) -> Response[E, P]:
         """Deserialize the data to a response object.
@@ -132,6 +132,30 @@ class Serializer:
         tree = self._from_xml(data)
         return self._from_tree_multi(tree, envelope_type, data_type)
 
+    def _to_canoncialized_xml(self, payload: PayloadBase) -> bytes:
+        """Convert the payload to a canonicalized XML string.
+
+        Arguments:
+        payload (PayloadBase): The payload to be converted.
+
+        Returns:    The canonicalized XML string.
+        """
+        # First, convert the payload to a raw XML string
+        raw: bytes = payload.to_xml(
+            skip_empty=True,
+            encoding="utf-8",
+            xml_declaration=False,
+        )  # type: ignore[assignment]
+
+        # Next, parse it back into an XML tree
+        unparsed = parse(BytesIO(raw))
+
+        # Finally, convert the XML tree to a canonicalized XML string and return it
+        buffer = BytesIO()
+        unparsed.write_c14n(buffer)
+        buffer.seek(0)
+        return buffer.read()
+
     def _from_tree(self, raw: Element, envelope_type: Type[E], data_type: Type[P]) -> Response[E, P]:
         """Convert the raw data to a response object.
 

{mms_client-1.5.1 → mms_client-1.7.0}/src/mms_client/utils/web.py

@@ -12,13 +12,13 @@ from requests import Session
 from requests_pkcs12 import Pkcs12Adapter
 from zeep import Client
 from zeep import Plugin
-from zeep import Transport
 from zeep.cache import SqliteCache
 from zeep.exceptions import TransportError
 from zeep.xsd.valueobjects import CompoundValue
 
 from mms_client.types.transport import MmsRequest
 from mms_client.types.transport import MmsResponse
+from mms_client.utils.multipart_transport import MultipartTransport
 
 # Set the default logger for the MMS client
 logger = getLogger(__name__)
@@ -134,6 +134,7 @@ class ZWrapper:
 
     def __init__(
         self,
+        domain: str,
         client: ClientType,
         interface: Interface,
         adapter: Pkcs12Adapter,
@@ -144,6 +145,7 @@ class ZWrapper:
         """Create a new Zeep wrapper object for a specific MMS service endpoint.
 
         Arguments:
+        domain (str):               The domain to use when signing the content ID to MTOM attachments.
         client (ClientType):        The type of client to use. This can be either "bsp" (Balancing Service Provider) or
                                     "tso" (Transmission System Operator). This will determine which service endpoint to
                                     use.
@@ -191,13 +193,25 @@ class ZWrapper:
 
         # Finally, we create the Zeep client with the given WSDL file location, session, and cache settings and then,
         # from that client, we create the SOAP service with the given service binding and selected endpoint.
+        self._transport = MultipartTransport(domain, cache=SqliteCache() if cache else None, session=sess)
         self._client = Client(
             wsdl=str(location.resolve()),
-            transport=Transport(cache=SqliteCache() if cache else None, session=sess),
+            transport=self._transport,
             plugins=plugins,
         )
         self._create_service()
 
+    def register_attachment(self, name: str, attachment: bytes) -> str:
+        """Register a multipart attachment.
+
+        Arguments:
+        name (str):         The name of the attachment.
+        attachment (bytes): The data to be attached.
+
+        Returns:    The content ID of the attachment, which should be used in place of the attachment data.
+        """
+        return self._transport.register_attachment(name, attachment)
+
     @on_exception(expo, TransportError, max_tries=3, giveup=fatal_code, logger=logger)  # type: ignore[arg-type]
     def submit(self, req: MmsRequest) -> MmsResponse:
         """Submit the given request to the MMS server and return the response.

mms_client-1.5.1/src/mms_client/security/certs.py

@@ -1,44 +0,0 @@
-"""Contains functionality associated with certificates."""
-
-from pathlib import Path
-from typing import Union
-
-from requests_pkcs12 import Pkcs12Adapter
-
-
-class Certificate:
-    """Describes a certificate composed of a cert file and a key file."""
-
-    def __init__(self, cert: Union[str, Path, bytes], passphrase: str):
-        """Create a new Certificate.
-
-        Creates a new certificate from the absolute path to the certificate file and a passpharse.
-
-        Arguments:
-        cert:           The certificate file. If a string, it should be the absolute path to the certificate file. If
-                        bytes, it should be the contents of the certificate file.
-        passphrase:     The passphrase the certificate is encrypted with
-        """
-        # Get the certificate file contents
-        if isinstance(cert, (str, Path)):
-            with open(cert, "rb") as file:
-                self._cert = file.read()
-        else:
-            self._cert = cert
-
-        # Save the passphrase
-        self._passphrase = passphrase
-
-    @property
-    def certificate(self) -> bytes:
-        """Return the certificate data."""
-        return self._cert
-
-    @property
-    def passphrase(self) -> str:
-        """Return the full path to the passphrase."""
-        return self._passphrase
-
-    def to_adapter(self) -> Pkcs12Adapter:
-        """Convert the certificate to a Pkcs12Adapter."""
-        return Pkcs12Adapter(pkcs12_data=self._cert, pkcs12_password=self._passphrase)

mms_client-1.5.1/src/mms_client/security/crypto.py

@@ -1,57 +0,0 @@
-"""Contains objects for cryptographic operations."""
-
-from base64 import b64encode
-from hashlib import sha256
-
-from cryptography.hazmat.backends import default_backend
-from cryptography.hazmat.primitives import hashes
-from cryptography.hazmat.primitives.asymmetric import padding
-from cryptography.hazmat.primitives.asymmetric.rsa import RSAPrivateKey
-from cryptography.hazmat.primitives.serialization.pkcs12 import load_key_and_certificates
-
-from mms_client.security.certs import Certificate
-
-
-class CryptoWrapper:
-    """Wraps the cryptographic operations necessary for signing and encrypting MMS payload data."""
-
-    def __init__(self, cert: Certificate):
-        """Create a new CryptoWrapper with the given certificate.
-
-        Arguments:
-        cert (Certificate): The certificate to use for cryptographic operations.
-        """
-        # First, save our certificate for later use
-        self._cert = cert
-
-        # Next, import the private key from the certificate
-        private_key, _, _ = load_key_and_certificates(
-            self._cert.certificate, self._cert.passphrase.encode(), default_backend()
-        )
-
-        # Now, we need to assert typing on this private key to make mypy happy
-        if isinstance(private_key, RSAPrivateKey):
-            self._private_key = private_key
-        else:
-            raise TypeError(f"Private key of type ({type(private_key).__name__}) was not expected.")
-
-        # Finally, save our padding and algorithm for later use
-        self._padding = padding.PKCS1v15()
-        self._algorithm = hashes.SHA256()
-
-    def sign(self, data: bytes) -> bytes:
-        """Create a signature from the given data using the certificate.
-
-        Arguments:
-        data (bytes):   The data to be encrypted.
-
-        Returns:    A base64-encoded string containing the signature.
-        """
-        # First, hash the data using SHA256
-        hashed = sha256(data)
-
-        # Next, sign the hash using the private key
-        signature = self._private_key.sign(hashed.digest(), self._padding, self._algorithm)
-
-        # Finally, return the base64-encoded signature
-        return b64encode(signature)