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

{optimizely_opal_opal_tools_sdk-0.1.41.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.41.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.41.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/opal_tools_sdk/decorators.py

@@ -99,6 +99,7 @@ def tool(
     timeout: int | None = None,
     sensitive: str | bool | None = None,
     wait: bool = False,
+    skippable_interaction: bool = False,
 ):
     """Decorator to register a function as an Opal tool.
 
@@ -114,6 +115,8 @@ def tool(
             Example: "ui://my-app/create-form"
         wait: When True, invoking this tool pauses the agent execution until the caller
             signals completion.
+        skippable_interaction: When True, the tool's confirmation interaction (card) can be
+            skipped; a user who opts out has the tool run headless instead.
 
     Returns:
         Decorator function
@@ -309,6 +312,7 @@ def tool(
                 timeout=timeout,
                 sensitive=sensitive,
                 wait=wait,
+                skippable_interaction=skippable_interaction,
             )
 
         return func

{optimizely_opal_opal_tools_sdk-0.1.41.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/opal_tools_sdk/models.py

@@ -3,7 +3,7 @@ from enum import Enum
 from typing import Any, Literal
 
 from pydantic import BaseModel, Field
-from typing_extensions import TypedDict  # pydantic requires this on Python < 3.12
+from typing_extensions import NotRequired, TypedDict  # pydantic requires this on Python < 3.12
 
 
 class ParameterType(str, Enum):
@@ -83,14 +83,17 @@ class InteractionContext:
     auth_data: AuthData | None = None
 
 
-class Environment(TypedDict, total=False):
+class Environment(TypedDict):
     """Execution environment for an Opal tool.
 
     Interactive mode provides interaction islands, while headless does not.
+    `execution_mode` is always sent by TMS — required. `is_proteus_enabled`
+    was added later, so older TMS versions may omit it; mark it `NotRequired`
+    for cross-version forward compatibility.
     """
 
     execution_mode: Literal["headless", "interactive"]
-    is_proteus_enabled: bool
+    is_proteus_enabled: NotRequired[bool]
 
 
 @dataclass
@@ -110,6 +113,7 @@ class Function:
     # to a non-empty advisory string when sensitive, else None.
     sensitive: str | bool | None = None
     wait: bool = False  # When True, pauses the agent until the caller signals completion
+    skippable_interaction: bool = False  # When True, the tool's confirmation card can be skipped
 
     def __post_init__(self) -> None:
         # Normalize `sensitive` to the wire shape: a single nullable advisory
@@ -144,6 +148,8 @@ class Function:
             result["sensitive"] = self.sensitive
         if self.wait:
             result["wait"] = self.wait
+        if self.skippable_interaction:
+            result["skippable_interaction"] = self.skippable_interaction
 
         return result
 

{optimizely_opal_opal_tools_sdk-0.1.41.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/opal_tools_sdk/service.py

@@ -314,6 +314,7 @@ class ToolsService:
         timeout: int | None = None,
         sensitive: str | bool | None = None,
         wait: bool = False,
+        skippable_interaction: bool = False,
     ) -> None:
         """Register a tool function.
 
@@ -329,6 +330,8 @@ class ToolsService:
             timeout: Timeout in seconds for async mode
             sensitive: Sensitive data field declaration
             wait: When True, invoking this tool pauses the agent until the caller signals completion
+            skippable_interaction: When True, the tool's confirmation interaction (card) can be
+                skipped; a user who opts out has the tool run headless instead
         """
         logger.info(f"Registering tool: {name} with endpoint: {endpoint}")
 
@@ -359,6 +362,7 @@ class ToolsService:
             timeout=timeout,
             sensitive=sensitive,
             wait=wait,
+            skippable_interaction=skippable_interaction,
         )
 
         self.functions.append(function)

{optimizely_opal_opal_tools_sdk-0.1.41.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.41.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.41.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.41.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.41-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.41.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.41-dev",
+    version="0.1.43-dev",
     packages=find_packages(),
     install_requires=[
         "fastapi>=0.100.0",

{optimizely_opal_opal_tools_sdk-0.1.41.dev0 → optimizely_opal_opal_tools_sdk-0.1.43.dev0}/tests/test_integration.py

@@ -860,3 +860,22 @@ def test_v1_tool_bare_dict_unchanged():
     assert "application/json" in resp.headers["content-type"]
     # Should NOT be wrapped in envelope
     assert resp.json() == {"v1": True, "name": "Dave"}
+
+
+def test_tool_with_skippable_interaction_flag():
+    """A tool marked skippable_interaction advertises it in discovery; others omit the key."""
+    app = FastAPI()
+    _ = ToolsService(app)
+
+    @tool(name="skip_me", description="skippable tool", skippable_interaction=True)
+    async def skip_me(params: SimpleParams) -> dict:
+        return {"ok": True}
+
+    @tool(name="plain", description="plain tool")
+    async def plain(params: SimpleParams) -> dict:
+        return {"ok": True}
+
+    discovery = TestClient(app).get("/discovery").json()
+    by_name = {f["name"]: f for f in discovery["functions"]}
+    assert by_name["skip_me"]["skippable_interaction"] is True
+    assert "skippable_interaction" not in by_name["plain"]