Support secrets and signing

RELEASE_NOTES.md

@@ -10,7 +10,11 @@
 
 ## New Features
 
-* `Dispatch.started_at(now: datetime)` was added as alternative to the `started` property for when users want to use the same `now` for multiple calls, ensuring deterministic return values with respect to the same `now`.
+* Support secrets for signing and verifying messages.
+  * Use the new env variable `DISPATCH_API_SIGN_SECRET` to set the secret key.
+  * Use the new `sign_secret` parameter in the `DispatchClient` constructor to set the secret key.
+* Added `auth_key` parameter to the `dispatch-cli` and thew env variable `DISPATCH_API_AUTH_KEY` to set the authentication key for the Dispatch API.
+
 
 ## Bug Fixes
 

pyproject.toml

@@ -38,7 +38,7 @@ requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.13.0, < 5",
   "frequenz-api-dispatch == 1.0.0-rc2",
-  "frequenz-client-base >= 0.8.0, < 0.12.0",
+  "frequenz-client-base >= 0.11.0, < 0.12.0",
   "frequenz-client-common >= 0.3.2,  < 0.4.0",
   "frequenz-core >= 1.0.2, < 2.0.0",
   "grpcio >= 1.70.0, < 2",

src/frequenz/client/dispatch/__main__.py

@@ -171,11 +171,26 @@ def format_line(key: str, value: str, color: str = "cyan") -> str:
     show_envvar=True,
 )
 @click.option(
-    "--key",
-    help="API key for authentication",
+    "--api-key",
+    help="API key for authentication (deprecated, use --auth-key or DISPATCH_API_AUTH_KEY)",
     envvar="DISPATCH_API_KEY",
     show_envvar=True,
-    required=True,
+    required=False,
+)
+@click.option(
+    "--auth-key",
+    help="API auth key for authentication",
+    envvar="DISPATCH_API_AUTH_KEY",
+    show_envvar=True,
+    required=False,
+)
+@click.option(
+    "--sign-secret",
+    help="API signing secret for authentication",
+    envvar="DISPATCH_API_SIGN_SECRET",
+    show_envvar=True,
+    required=False,
+    default=None,
 )
 @click.option(
     "--raw",
@@ -185,29 +200,67 @@ def format_line(key: str, value: str, color: str = "cyan") -> str:
     default=False,
 )
 @click.pass_context
-async def cli(ctx: click.Context, url: str, key: str, raw: bool) -> None:
+async def cli(  # pylint: disable=too-many-arguments, too-many-positional-arguments
+    ctx: click.Context,
+    url: str,
+    api_key: str | None,
+    auth_key: str | None,
+    sign_secret: str | None,
+    raw: bool,
+) -> None:
     """Dispatch Service CLI."""
     if ctx.obj is None:
         ctx.obj = {}
 
+    key = auth_key or api_key
+
+    if not key:
+        raise click.BadParameter(
+            "You must provide an API auth key using --auth-key or "
+            "the DISPATCH_API_AUTH_KEY environment variable."
+        )
+
     click.echo(f"Using API URL: {url}", err=True)
+    click.echo(f"Using API Auth Key: {key[:4]}{'*' * 8}", err=True)
+
+    if sign_secret:
+        if len(sign_secret) > 8:
+            click.echo(
+                f"Using API Signing Secret: {sign_secret[:4]}{'*' * 8}", err=True
+            )
+        else:
+            click.echo("Using API Signing Secret (not shown).", err=True)
+
+    if api_key and auth_key is None:
+        click.echo(
+            click.style(
+                "Deprecation Notice: The --api-key option and the DISPATCH_API_KEY environment "
+                "variable are deprecated. "
+                "Please use --auth-key or set the DISPATCH_API_AUTH_KEY environment variable.",
+                fg="red",
+                bold=True,
+            ),
+            err=True,
+        )
 
     ctx.obj["client"] = DispatchApiClient(
         server_url=url,
-        key=key,
+        auth_key=key,
+        sign_secret=sign_secret,
         connect=True,
     )
 
     ctx.obj["params"] = {
         "url": url,
-        "key": key,
+        "auth_key": key,
+        "sign_secret": sign_secret,
     }
 
     ctx.obj["raw"] = raw
 
     # Check if a subcommand was given
     if ctx.invoked_subcommand is None:
-        await interactive_mode(url, key)
+        await interactive_mode(url, key, sign_secret)
 
 
 @cli.command("list")
@@ -533,8 +586,9 @@ async def repl(
     obj: dict[str, Any],
 ) -> None:
     """Start an interactive interface."""
-    click.echo(f"Parameters: {obj}")
-    await interactive_mode(obj["params"]["url"], obj["params"]["key"])
+    await interactive_mode(
+        obj["params"]["url"], obj["params"]["auth_key"], obj["params"]["sign_secret"]
+    )
 
 
 @cli.command()
@@ -574,7 +628,7 @@ async def delete(
         raise click.ClickException("Some deletions failed.")
 
 
-async def interactive_mode(url: str, key: str) -> None:
+async def interactive_mode(url: str, auth_key: str, sign_secret: str | None) -> None:
     """Interactive mode for the CLI."""
     hist_file = os.path.expanduser("~/.dispatch_cli_history.txt")
     session: PromptSession[str] = PromptSession(history=FileHistory(filename=hist_file))
@@ -614,12 +668,11 @@ async def display_help() -> None:
             break
         else:
             # Split, but keep quoted strings together
-            params = [
-                "--url",
-                url,
-                "--key",
-                key,
-            ] + click.parser.split_arg_string(user_input)
+            params = (
+                ["--url", url, "--auth-key", auth_key]
+                + (["--sign-secret", sign_secret] if sign_secret else [])
+                + click.parser.split_arg_string(user_input)
+            )
 
             try:
                 await cli.main(args=params, standalone_mode=False)

src/frequenz/client/dispatch/_client.py

@@ -60,7 +60,8 @@ def __init__(
         self,
         *,
         server_url: str,
-        key: str,
+        auth_key: str,
+        sign_secret: str | None = None,
         connect: bool = True,
         call_timeout: timedelta = timedelta(seconds=60),
         stream_timeout: timedelta = timedelta(minutes=5),
@@ -69,7 +70,8 @@ def __init__(
 
         Args:
             server_url: The URL of the server to connect to.
-            key: API key to use for authentication.
+            auth_key: API key to use for authentication.
+            sign_secret: Optional secret for signing requests.
             connect: Whether to connect to the service immediately.
             call_timeout: Timeout for gRPC calls, default is 60 seconds.
             stream_timeout: Timeout for gRPC streams, default is 5 minutes.
@@ -82,8 +84,9 @@ def __init__(
                 port=DEFAULT_DISPATCH_PORT,
                 ssl=SslOptions(enabled=True),
             ),
+            auth_key=auth_key,
+            sign_secret=sign_secret,
         )
-        self._metadata = (("key", key),)
         self._streams: dict[
             MicrogridId,
             GrpcStreamBroadcaster[StreamMicrogridDispatchesResponse, DispatchEvent],
@@ -138,7 +141,8 @@ async def list(
 
         ```python
         client = DispatchApiClient(
-            key="key",
+            auth_key="key",
+            sign_secret="secret", # Optional so far
             server_url="grpc://dispatch.url.goes.here.example.com"
         )
         async for page in client.list(microgrid_id=MicrogridId(1)):
@@ -199,7 +203,7 @@ def to_interval(
             response = await cast(
                 Awaitable[ListMicrogridDispatchesResponse],
                 self.stub.ListMicrogridDispatches(
-                    request, metadata=self._metadata, timeout=self._call_timeout_seconds
+                    request, timeout=self._call_timeout_seconds
                 ),
             )
 
@@ -256,7 +260,6 @@ def _get_stream(
                     AsyncIterator[StreamMicrogridDispatchesResponse],
                     self.stub.StreamMicrogridDispatches(
                         request,
-                        metadata=self._metadata,
                         timeout=self._stream_timeout_seconds,
                     ),
                 ),
@@ -327,7 +330,6 @@ async def create(  # pylint: disable=too-many-positional-arguments
             Awaitable[CreateMicrogridDispatchResponse],
             self.stub.CreateMicrogridDispatch(
                 request.to_protobuf(),
-                metadata=self._metadata,
                 timeout=self._call_timeout_seconds,
             ),
         )
@@ -419,9 +421,7 @@ async def update(
 
         response = await cast(
             Awaitable[UpdateMicrogridDispatchResponse],
-            self.stub.UpdateMicrogridDispatch(
-                msg, metadata=self._metadata, timeout=self._call_timeout_seconds
-            ),
+            self.stub.UpdateMicrogridDispatch(msg, timeout=self._call_timeout_seconds),
         )
 
         return Dispatch.from_protobuf(response.dispatch)
@@ -443,9 +443,7 @@ async def get(
         )
         response = await cast(
             Awaitable[GetMicrogridDispatchResponse],
-            self.stub.GetMicrogridDispatch(
-                request, metadata=self._metadata, timeout=self._call_timeout_seconds
-            ),
+            self.stub.GetMicrogridDispatch(request, timeout=self._call_timeout_seconds),
         )
         return Dispatch.from_protobuf(response.dispatch)
 
@@ -464,6 +462,6 @@ async def delete(
         await cast(
             Awaitable[None],
             self.stub.DeleteMicrogridDispatch(
-                request, metadata=self._metadata, timeout=self._call_timeout_seconds
+                request, timeout=self._call_timeout_seconds
             ),
         )