Add SigV4 event stream empty-frame signing (#692)

* Add SigV4 event stream empty-frame signing

Add AsyncEventSigner.sign_empty for SigV4-signed Amazon Event Stream
terminator frames with zero-byte payloads.

Share the common signing flow between normal event messages and empty
terminator payloads, and cover both behaviors with tests.

* Trim sign_empty docstring

* Address PR feedback

Author: jonathan343

packages/aws-sdk-signers/.changes/next-release/aws-sdk-signers-enhancement-d97ea923259e448da2f865cd60bb7768.json

@@ -0,0 +1,4 @@
+{
+  "type": "enhancement",
+  "description": "Added `AsyncEventSigner.sign_empty` for SigV4-signed Amazon Event Stream terminator frames. This supports services that require a final signed empty message before the HTTP body stream closes."
+}

packages/aws-sdk-signers/src/aws_sdk_signers/signers.py

@@ -835,17 +835,69 @@ def __init__(
         self._prior_signature = initial_signature
         self._signing_lock = asyncio.Lock()
         self._event_encoder_cls = event_encoder_cls
+        self._is_finalized = False
 
     async def sign(
         self,
         *,
         event: "EventMessage",
         identity: _AWSCredentialsIdentity,
         properties: SigV4SigningProperties,
+    ) -> "EventMessage":
+        return await self._sign_payload(
+            event=event,
+            payload=event.encode(),
+            identity=identity,
+            properties=properties,
+        )
+
+    async def sign_empty(
+        self,
+        *,
+        event: "EventMessage",
+        identity: _AWSCredentialsIdentity,
+        properties: SigV4SigningProperties,
+    ) -> "EventMessage":
+        """Sign an Amazon Event Stream final empty message.
+
+        The supplied ``event`` must have no headers and an empty payload.
+        Calling ``sign`` with an empty event message is not equivalent because
+        ``sign`` wraps the encoded event message as the payload.
+
+        The returned message contains ``:date`` and ``:chunk-signature``
+        headers and advances the running signature chain. After this method
+        returns, the signer cannot sign additional event stream messages.
+        """
+        if event.headers or event.payload:
+            raise ValueError(
+                "sign_empty requires an event with no headers and an empty payload."
+            )
+
+        return await self._sign_payload(
+            event=event,
+            payload=b"",
+            identity=identity,
+            properties=properties,
+            is_final=True,
+        )
+
+    async def _sign_payload(
+        self,
+        *,
+        event: "EventMessage",
+        payload: bytes,
+        identity: _AWSCredentialsIdentity,
+        properties: SigV4SigningProperties,
+        is_final: bool = False,
     ) -> "EventMessage":
         async with self._signing_lock:
-            # Copy and prepopulate any missing values in the
-            # signing properties.
+            if self._is_finalized:
+                raise RuntimeError(
+                    "Cannot sign event stream messages after the final empty event "
+                    "has been signed."
+                )
+
+            # Copy and prepopulate any missing values in the signing properties.
             new_signing_properties = SigV4SigningProperties(  # type: ignore
                 **properties
             )
@@ -862,8 +914,6 @@ async def sign(
             encoder.encode_headers(headers)
             encoded_headers = encoder.get_result()
 
-            payload = event.encode()
-
             string_to_sign = await self._event_string_to_sign(
                 timestamp=timestamp,
                 scope=self._scope(new_signing_properties),
@@ -882,8 +932,10 @@ async def sign(
             event.headers = headers
             event.payload = payload
 
-            # set new prior signature before releasing the lock
+            # Set new prior signature before releasing the lock.
             self._prior_signature = hexlify(event_signature)
+            if is_final:
+                self._is_finalized = True
 
         return event
 

packages/aws-sdk-signers/tests/unit/test_signers.py

@@ -9,6 +9,7 @@
 
 import pytest
 from aws_sdk_signers import (
+    AsyncEventSigner,
     AsyncSigV4Signer,
     AWSCredentialIdentity,
     AWSRequest,
@@ -18,6 +19,7 @@
     SigV4SigningProperties,
     URI,
 )
+from smithy_aws_event_stream.events import Event, EventHeaderEncoder, EventMessage
 
 SIGV4_RE = re.compile(
     r"AWS4-HMAC-SHA256 "
@@ -146,6 +148,111 @@ async def __anext__(self) -> bytes:
         raise Exception("Read should not have been called!")
 
 
+class TestAsyncEventSigner:
+    async def test_sign_wraps_event_message_payload(
+        self,
+        aws_identity: AWSCredentialIdentity,
+    ) -> None:
+        signer = AsyncEventSigner(
+            initial_signature=b"initial-signature",
+            event_encoder_cls=EventHeaderEncoder,
+        )
+        message = EventMessage(
+            headers={":message-type": "event", ":event-type": "AudioEvent"},
+            payload=b"audio",
+        )
+
+        signed = await signer.sign(
+            event=message,
+            identity=aws_identity,
+            properties=SigV4SigningProperties(region="us-west-2", service="transcribe"),
+        )
+
+        assert (
+            signed.payload
+            == EventMessage(
+                headers={":message-type": "event", ":event-type": "AudioEvent"},
+                payload=b"audio",
+            ).encode()
+        )
+        assert ":date" in signed.headers
+        assert ":chunk-signature" in signed.headers
+
+    async def test_sign_empty_uses_zero_byte_outer_payload(
+        self,
+        aws_identity: AWSCredentialIdentity,
+    ) -> None:
+        signer = AsyncEventSigner(
+            initial_signature=b"initial-signature",
+            event_encoder_cls=EventHeaderEncoder,
+        )
+
+        signed = await signer.sign_empty(
+            event=EventMessage(),
+            identity=aws_identity,
+            properties=SigV4SigningProperties(region="us-west-2", service="transcribe"),
+        )
+
+        decoded = Event.decode(BytesIO(signed.encode()))
+        assert decoded is not None
+        assert decoded.message.payload == b""
+        assert ":date" in decoded.message.headers
+        assert ":chunk-signature" in decoded.message.headers
+
+    async def test_sign_empty_rejects_non_empty_event(
+        self,
+        aws_identity: AWSCredentialIdentity,
+    ) -> None:
+        signer = AsyncEventSigner(
+            initial_signature=b"initial-signature",
+            event_encoder_cls=EventHeaderEncoder,
+        )
+
+        with pytest.raises(ValueError):
+            await signer.sign_empty(
+                event=EventMessage(headers={"foo": "bar"}),
+                identity=aws_identity,
+                properties=SigV4SigningProperties(
+                    region="us-west-2", service="transcribe"
+                ),
+            )
+
+        with pytest.raises(ValueError):
+            await signer.sign_empty(
+                event=EventMessage(payload=b"audio"),
+                identity=aws_identity,
+                properties=SigV4SigningProperties(
+                    region="us-west-2", service="transcribe"
+                ),
+            )
+
+    async def test_sign_rejects_events_after_empty_event(
+        self,
+        aws_identity: AWSCredentialIdentity,
+    ) -> None:
+        signer = AsyncEventSigner(
+            initial_signature=b"initial-signature",
+            event_encoder_cls=EventHeaderEncoder,
+        )
+        properties = SigV4SigningProperties(region="us-west-2", service="transcribe")
+
+        await signer.sign_empty(
+            event=EventMessage(),
+            identity=aws_identity,
+            properties=properties,
+        )
+
+        with pytest.raises(RuntimeError, match="final empty event"):
+            await signer.sign(
+                event=EventMessage(
+                    headers={":message-type": "event", ":event-type": "AudioEvent"},
+                    payload=b"audio",
+                ),
+                identity=aws_identity,
+                properties=properties,
+            )
+
+
 class TestAsyncSigV4Signer:
     SIGV4_ASYNC_SIGNER = AsyncSigV4Signer()