feat(auth): python client support for bearer auth (#240)

mint tokens in our client library if a secret key and other config has
been passed in

i will update #231 for
end-to-end testing of both clients

Ref FS-202

Author: matt-codecov

clients/python/README.md

@@ -14,11 +14,21 @@ import urllib3
 from objectstore_client import (
     Client,
     NoOpMetricsBackend,
+    Permission,
     TimeToIdle,
     TimeToLive,
+    TokenGenerator,
     Usecase,
 )
 
+# Necessary when using Objectstore instances that enforce authorization checks.
+token_generator = TokenGenerator(
+    "my-key-id",
+    "<securely inject EdDSA private key>",
+    expiry_seconds=60,
+    permissions=Permission.max(),
+)
+
 # This should be stored in a global variable and reused, in order to reuse the connection
 client = Client(
     "http://localhost:8888",
@@ -31,6 +41,8 @@ client = Client(
     retries=3,      # Number of connection retries
     # For further customization, provide additional kwargs for urllib3.HTTPConnectionPool
     connection_kwargs={"maxsize": 10},
+    # Optionally, provide a token generator for Objectstore instances with authorization enforced
+    token_generator=token_generator,
 )
 
 # This could also be stored in a global/shared variable, as you will deal with a fixed number of usecases with statically defined defaults

clients/python/pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
     "urllib3>=2.2.2",
     "zstandard>=0.18.0",
     "filetype>=1.2.0",
+    "PyJWT[crypto]>=2.10.1",
 ]
 
 [build-system]

clients/python/src/objectstore_client/__init__.py

@@ -1,3 +1,4 @@
+from objectstore_client.auth import Permission, TokenGenerator
 from objectstore_client.client import (
     Client,
     GetResponse,
@@ -23,8 +24,10 @@
     "Compression",
     "ExpirationPolicy",
     "Metadata",
+    "Permission",
     "TimeToIdle",
     "TimeToLive",
+    "TokenGenerator",
     "MetricsBackend",
     "NoOpMetricsBackend",
 ]

clients/python/src/objectstore_client/auth.py

@@ -0,0 +1,56 @@
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from typing import Self
+
+import jwt
+
+from objectstore_client.scope import Scope
+
+
+class Permission(StrEnum):
+    """
+    Enum listing permissions that Objectstore tokens may be granted.
+    """
+
+    OBJECT_READ = "object.read"
+    OBJECT_WRITE = "object.write"
+    OBJECT_DELETE = "object.delete"
+
+    @classmethod
+    def max(cls) -> list[Self]:
+        return list(cls.__members__.values())
+
+
+class TokenGenerator:
+    def __init__(
+        self,
+        kid: str,
+        secret_key: str,
+        expiry_seconds: int = 60,
+        permissions: list[Permission] = Permission.max(),
+    ):
+        self.kid = kid
+        self.secret_key = secret_key
+        self.expiry_seconds = expiry_seconds
+        self.permissions = permissions
+
+    def sign_for_scope(self, usecase: str, scope: Scope) -> str:
+        """
+        Sign a JWT for the passed-in usecase and scope using the configured key
+        information, expiry, and permissions.
+
+        The JWT is signed using EdDSA, so `self.secret_key` must be an EdDSA private
+        key. `self.kid` is used by the Objectstore server to load the corresponding
+        public key from its configuration.
+        """
+        headers = {"kid": self.kid}
+        claims = {
+            "res": {
+                "os:usecase": usecase,
+                **{k: str(v) for k, v in scope.dict().items()},
+            },
+            "permissions": self.permissions,
+            "exp": datetime.now(tz=UTC) + timedelta(seconds=self.expiry_seconds),
+        }
+
+        return jwt.encode(claims, self.secret_key, algorithm="EdDSA", headers=headers)

clients/python/src/objectstore_client/client.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import string
 from collections.abc import Mapping
 from dataclasses import asdict, dataclass
 from io import BytesIO
@@ -12,6 +11,7 @@
 import zstandard
 from urllib3.connectionpool import HTTPConnectionPool
 
+from objectstore_client.auth import TokenGenerator
 from objectstore_client.metadata import (
     HEADER_EXPIRATION,
     HEADER_META_PREFIX,
@@ -25,8 +25,7 @@
     NoOpMetricsBackend,
     measure_storage_operation,
 )
-
-Permission = Literal["read", "write"]
+from objectstore_client.scope import Scope
 
 
 class GetResponse(NamedTuple):
@@ -68,12 +67,6 @@ def __init__(
         self._expiration_policy = expiration_policy
 
 
-# Characters allowed in a Scope's key and value.
-# These are the URL safe characters, except for `.` which we use as separator between
-# key and value of Scope components.
-SCOPE_VALUE_ALLOWED_CHARS = set(string.ascii_letters + string.digits + "-_()$!+'")
-
-
 @dataclass
 class _ConnectionDefaults:
     retries: urllib3.Retry = urllib3.Retry(connect=3, read=0)
@@ -100,6 +93,7 @@ def __init__(
         retries: int | None = None,
         timeout_ms: float | None = None,
         connection_kwargs: Mapping[str, Any] | None = None,
+        token_generator: TokenGenerator | None = None,
     ):
         connection_kwargs_to_use = asdict(_ConnectionDefaults())
 
@@ -125,11 +119,12 @@ def __init__(
         self._base_path = urlparse(base_url).path
         self._metrics_backend = metrics_backend or NoOpMetricsBackend()
         self._propagate_traces = propagate_traces
+        self._token_generator = token_generator
 
     def session(self, usecase: Usecase, **scopes: str | int | bool) -> Session:
         """
         Create a [Session] with the Objectstore server, tied to a specific [Usecase] and
-        Scope.
+        [Scope].
 
         A Scope is a (possibly nested) namespace within a Usecase, given as a sequence
         of key-value pairs passed as kwargs.
@@ -148,37 +143,14 @@ def session(self, usecase: Usecase, **scopes: str | int | bool) -> Session:
         ```
         """
 
-        parts = []
-        for key, value in scopes.items():
-            if not key:
-                raise ValueError("Scope key cannot be empty")
-            if not value:
-                raise ValueError("Scope value cannot be empty")
-
-            if any(c not in SCOPE_VALUE_ALLOWED_CHARS for c in key):
-                raise ValueError(
-                    f"Invalid scope key {key}. The valid character set is: "
-                    f"{''.join(SCOPE_VALUE_ALLOWED_CHARS)}"
-                )
-
-            value = str(value)
-            if any(c not in SCOPE_VALUE_ALLOWED_CHARS for c in value):
-                raise ValueError(
-                    f"Invalid scope value {value}. The valid character set is: "
-                    f"{''.join(SCOPE_VALUE_ALLOWED_CHARS)}"
-                )
-
-            formatted = f"{key}={value}"
-            parts.append(formatted)
-        scope_str = ";".join(parts)
-
         return Session(
             self._pool,
             self._base_path,
             self._metrics_backend,
             self._propagate_traces,
             usecase,
-            scope_str,
+            Scope(**scopes),
+            self._token_generator,
         )
 
 
@@ -196,21 +168,28 @@ def __init__(
         metrics_backend: MetricsBackend,
         propagate_traces: bool,
         usecase: Usecase,
-        scope: str,
+        scope: Scope,
+        token_generator: TokenGenerator | None,
     ):
         self._pool = pool
         self._base_path = base_path
         self._metrics_backend = metrics_backend
         self._propagate_traces = propagate_traces
         self._usecase = usecase
         self._scope = scope
+        self._token_generator = token_generator
 
     def _make_headers(self) -> dict[str, str]:
         headers = dict(self._pool.headers)
         if self._propagate_traces:
             headers.update(
                 dict(sentry_sdk.get_current_scope().iter_trace_propagation_headers())
             )
+        if self._token_generator:
+            token = self._token_generator.sign_for_scope(
+                self._usecase.name, self._scope
+            )
+            headers["Authorization"] = f"Bearer {token}"
         return headers
 
     def _make_url(self, key: str | None, full: bool = False) -> str:

clients/python/src/objectstore_client/scope.py

@@ -0,0 +1,41 @@
+import string
+
+# Characters allowed in a Scope's key and value.
+# These are the URL safe characters, except for `.` which we use as separator between
+# key and value of Scope components.
+SCOPE_VALUE_ALLOWED_CHARS = set(string.ascii_letters + string.digits + "-_()$!+'")
+
+
+class Scope:
+    def __init__(self, **scopes: str | int | bool):
+        parts = []
+        for key, value in scopes.items():
+            if not key:
+                raise ValueError("Scope key cannot be empty")
+            if not value:
+                raise ValueError("Scope value cannot be empty")
+
+            if any(c not in SCOPE_VALUE_ALLOWED_CHARS for c in key):
+                raise ValueError(
+                    f"Invalid scope key {key}. The valid character set is: "
+                    f"{''.join(SCOPE_VALUE_ALLOWED_CHARS)}"
+                )
+
+            value = str(value)
+            if any(c not in SCOPE_VALUE_ALLOWED_CHARS for c in value):
+                raise ValueError(
+                    f"Invalid scope value {value}. The valid character set is: "
+                    f"{''.join(SCOPE_VALUE_ALLOWED_CHARS)}"
+                )
+
+            formatted = f"{key}={value}"
+            parts.append(formatted)
+
+        self._scope = scopes
+        self._scope_str = ";".join(parts)
+
+    def __str__(self) -> str:
+        return self._scope_str
+
+    def dict(self) -> dict[str, str | int | bool]:
+        return self._scope