optimizely-opal.opal-tools-sdk 0.1.42.dev0__tar.gz → 0.1.43.dev0__tar.gz

{optimizely_opal_opal_tools_sdk-0.1.42.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.42.dev0
+Version: 0.1.43.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

optimizely_opal_opal_tools_sdk-0.1.43.dev0/opal_tools_sdk/auth/__init__.py

@@ -0,0 +1,6 @@
+"""Authentication utilities for Opal Tools SDK."""
+
+from .epi_hmac import EpiHmac
+from .requires_auth import requires_auth
+
+__all__ = ["EpiHmac", "requires_auth"]

optimizely_opal_opal_tools_sdk-0.1.43.dev0/opal_tools_sdk/auth/epi_hmac.py

@@ -0,0 +1,156 @@
+"""epi-hmac signing and verification utility.
+
+Implements the canonical epi-hmac scheme used across Opal services
+(API Gateway, system-tools, file-server, instructions-service).
+
+Signing algorithm::
+
+    timestamp = milliseconds since epoch
+    nonce = UUID v4
+    body_md5 = base64(md5(body))  # empty body hashes to base64(md5(""))
+    message = app_key + method + endpoint + timestamp + nonce + body_md5
+    secret_bytes = base64_decode(hmac_secret)
+    signature = base64(HMAC-SHA256(secret_bytes, message))
+    header = "epi-hmac {app_key}:{timestamp}:{nonce}:{signature}"
+
+Replay protection (v1 posture): verification enforces the 5-minute timestamp
+window but does NOT track nonces, so a captured signed request can be replayed
+within that window. Nonce dedup (e.g. a shared store) is the caller's
+responsibility if stronger replay protection is required.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac as hmac_mod
+import time
+import uuid
+
+_TIMESTAMP_WINDOW_MS = 300_000  # 5 minutes (past timestamps)
+_MAX_FUTURE_SKEW_MS = 60_000  # 1 minute (clock skew tolerance)
+
+
+class EpiHmac:
+    """epi-hmac signing and verification utility.
+
+    Args:
+        app_key: Credential identifier.
+        secret: Base64-encoded HMAC secret.
+    """
+
+    def __init__(self, app_key: str, secret: str) -> None:
+        self.app_key = app_key
+        # Fail closed on a malformed secret rather than silently decoding to the
+        # wrong bytes (b64decode without validate ignores non-alphabet chars).
+        try:
+            self._secret_bytes = base64.b64decode(secret, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise ValueError("EpiHmac secret must be valid base64") from exc
+
+    def sign(
+        self,
+        method: str,
+        endpoint: str,
+        body: bytes = b"",
+    ) -> str:
+        """Generate an ``Authorization: epi-hmac ...`` header value.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            endpoint: Request path including query string.
+            body: Request body bytes (empty for GET/DELETE).
+
+        Returns:
+            The full Authorization header value.
+        """
+        timestamp = str(int(time.time() * 1000))
+        nonce = str(uuid.uuid4())
+        return self._build_header(method, endpoint, body, timestamp, nonce)
+
+    def verify(
+        self,
+        auth_header: str,
+        method: str,
+        endpoint: str,
+        body: bytes = b"",
+    ) -> bool:
+        """Verify an ``Authorization: epi-hmac ...`` header.
+
+        Checks app_key match, timestamp freshness (5-minute window),
+        and signature correctness using timing-safe comparison.
+
+        Args:
+            auth_header: The full Authorization header value.
+            method: HTTP method.
+            endpoint: Request path including query string.
+            body: Request body bytes.
+
+        Returns:
+            True if the header is valid.
+        """
+        if not auth_header.startswith("epi-hmac "):
+            return False
+
+        parts = auth_header[len("epi-hmac ") :].split(":")
+        if len(parts) != 4:
+            return False
+
+        recv_app_key, timestamp, nonce, recv_signature = parts
+
+        # Validate app_key
+        if not hmac_mod.compare_digest(recv_app_key, self.app_key):
+            return False
+
+        # Validate timestamp freshness: reject far-future timestamps (beyond clock
+        # skew) and old timestamps (beyond replay window). The original symmetric
+        # check `abs(now - ts) <= window` accepted timestamps up to 5 min in the
+        # FUTURE, doubling the replay surface. A future timestamp is never
+        # legitimate beyond small clock skew.
+        try:
+            ts_ms = int(timestamp)
+        except ValueError:
+            return False
+        now_ms = int(time.time() * 1000)
+        # Reject timestamps too far in the future (beyond clock skew tolerance)
+        if ts_ms - now_ms > _MAX_FUTURE_SKEW_MS:
+            return False
+        # Reject timestamps too far in the past (beyond replay window)
+        if now_ms - ts_ms > _TIMESTAMP_WINDOW_MS:
+            return False
+
+        # Recompute expected signature
+        expected_header = self._build_header(method, endpoint, body, timestamp, nonce)
+        expected_signature = expected_header.split(":")[-1]
+
+        return hmac_mod.compare_digest(recv_signature, expected_signature)
+
+    def _build_header(
+        self,
+        method: str,
+        endpoint: str,
+        body: bytes,
+        timestamp: str,
+        nonce: str,
+    ) -> str:
+        # Empty-body rule: when body is b"", we compute base64(md5(b"")) and
+        # include it in the signed message. The Python, C# and TypeScript SDKs
+        # all use this same canonical construction (proven by the shared golden
+        # vectors in test_hmac.py).
+        #
+        # CROSS-IMPL: this is the tool-provider trust boundary (TMS -> tool
+        # provider) and is SEPARATE from the api-gateway's inbound HMAC
+        # (external -> Opal). The gateway uses a different canonical (no body
+        # hash) on its own routes; the two boundaries are independent and are
+        # NOT expected to share a wire format. TMS itself has no HMAC
+        # implementation. This signer/verifier only needs to be internally
+        # consistent; do not assume interop with the gateway canonical.
+        body_md5 = base64.b64encode(hashlib.md5(body).digest()).decode()
+
+        message = f"{self.app_key}{method}{endpoint}{timestamp}{nonce}{body_md5}"
+        signature = base64.b64encode(
+            hmac_mod.new(self._secret_bytes, message.encode(), hashlib.sha256).digest()
+        ).decode()
+
+        return f"epi-hmac {self.app_key}:{timestamp}:{nonce}:{signature}"

optimizely_opal_opal_tools_sdk-0.1.43.dev0/opal_tools_sdk/auth/requires_auth.py

@@ -0,0 +1,41 @@
+from collections.abc import Callable
+from functools import wraps
+
+from fastapi import Header, HTTPException
+
+
+def requires_auth(provider: str, scope_bundle: str, required: bool = True):
+    """Decorator to indicate that a tool requires authentication.
+
+    Args:
+        provider: Authentication provider (e.g., "google", "microsoft")
+        scope_bundle: Scope bundle required (e.g., "calendar", "drive")
+        required: Whether authentication is mandatory (default: True)
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable):
+        @wraps(func)
+        async def wrapper(*args, authorization: str | None = Header(None), **kwargs):
+            if required and not authorization:
+                raise HTTPException(status_code=401, detail="Authentication required")
+
+            # The Tools Management Service will provide the appropriate token
+            # in the Authorization header
+            return await func(*args, authorization=authorization, **kwargs)
+
+        # Store auth requirements in function metadata
+        auth_req = {"provider": provider, "scope_bundle": scope_bundle, "required": required}
+
+        # Initialize the list if it doesn't exist
+        if not hasattr(wrapper, "__auth_requirements__"):
+            wrapper.__auth_requirements__ = []  # type: ignore[attr-defined]
+
+        # Add this auth requirement to the list
+        wrapper.__auth_requirements__.append(auth_req)  # type: ignore[attr-defined]
+
+        return wrapper
+
+    return decorator

{optimizely_opal_opal_tools_sdk-0.1.42.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/optimizely_opal.opal_tools_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optimizely-opal.opal-tools-sdk
-Version: 0.1.42.dev0
+Version: 0.1.43.dev0
 Summary: SDK for creating Opal-compatible tools services
 Home-page: https://github.com/optimizely/opal-tools-sdk
 Author: Optimizely

{optimizely_opal_opal_tools_sdk-0.1.42.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/optimizely_opal.opal_tools_sdk.egg-info/SOURCES.txt

@@ -12,6 +12,9 @@ opal_tools_sdk/proteus.py
 opal_tools_sdk/response.py
 opal_tools_sdk/service.py
 opal_tools_sdk/ui.py
+opal_tools_sdk/auth/__init__.py
+opal_tools_sdk/auth/epi_hmac.py
+opal_tools_sdk/auth/requires_auth.py
 optimizely_opal.opal_tools_sdk.egg-info/PKG-INFO
 optimizely_opal.opal_tools_sdk.egg-info/SOURCES.txt
 optimizely_opal.opal_tools_sdk.egg-info/dependency_links.txt

{optimizely_opal_opal_tools_sdk-0.1.42.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optimizely-opal.opal-tools-sdk"
-version = "0.1.42-dev"
+version = "0.1.43-dev"
 description = "SDK for creating Opal-compatible tools services"
 authors = [{ name = "Optimizely", email = "opal-team@optimizely.com" }]
 readme = "README.md"
@@ -32,8 +32,8 @@ dev = [
 "Homepage" = "https://github.com/optimizely/opal-tools-sdk"
 "Bug Tracker" = "https://github.com/optimizely/opal-tools-sdk/issues"
 
-[tool.setuptools]
-packages = ["opal_tools_sdk"]
+[tool.setuptools.packages.find]
+include = ["opal_tools_sdk*"]
 
 [tool.ruff]
 line-length = 100

{optimizely_opal_opal_tools_sdk-0.1.42.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import find_packages, setup
 
 setup(
     name="optimizely-opal.opal-tools-sdk",
-    version="0.1.42-dev",
+    version="0.1.43-dev",
     packages=find_packages(),
     install_requires=[
         "fastapi>=0.100.0",