shield-python 0.1.4__tar.gz → 0.1.6__tar.gz

{shield_python-0.1.4 → shield_python-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shield-python
-Version: 0.1.4
+Version: 0.1.6
 Summary: Official Shield SDK for Python
 License: MIT
 Project-URL: Homepage, https://getshield.dev
@@ -264,3 +264,12 @@ Shield Standard Event Taxonomy v1.0 ??37 event types across 7 categories:
 | `shield.evidence.exported` | Evidence was exported |
 | `shield.evidence.verified` | Evidence was verified |
 | `shield.evidence.tampered_detected` | Evidence tampering was detected |
+
+## Versioning & API compatibility
+
+This SDK follows [Semantic Versioning](https://semver.org/).
+
+- **Pre-1.0** (current): minor-version bumps may ship breaking changes. Pin the full version in `requirements.txt`.
+- **1.0 and later**: the public API is stable within a major version. Breaking changes require a major-version bump.
+
+The Shield HTTP API is versioned at the URL path (`/api/v1`). This SDK targets `/api/v1` and will not transparently follow a server-side version bump — a new server major version will be delivered as a new SDK major version so callers opt in explicitly.

{shield_python-0.1.4 → shield_python-0.1.6}/README.md

@@ -253,3 +253,12 @@ Shield Standard Event Taxonomy v1.0 ??37 event types across 7 categories:
 | `shield.evidence.exported` | Evidence was exported |
 | `shield.evidence.verified` | Evidence was verified |
 | `shield.evidence.tampered_detected` | Evidence tampering was detected |
+
+## Versioning & API compatibility
+
+This SDK follows [Semantic Versioning](https://semver.org/).
+
+- **Pre-1.0** (current): minor-version bumps may ship breaking changes. Pin the full version in `requirements.txt`.
+- **1.0 and later**: the public API is stable within a major version. Breaking changes require a major-version bump.
+
+The Shield HTTP API is versioned at the URL path (`/api/v1`). This SDK targets `/api/v1` and will not transparently follow a server-side version bump — a new server major version will be delivered as a new SDK major version so callers opt in explicitly.

{shield_python-0.1.4 → shield_python-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shield-python"
-version = "0.1.4"
+version = "0.1.6"
 description = "Official Shield SDK for Python"
 readme = "README.md"
 license = {text = "MIT"}

{shield_python-0.1.4 → shield_python-0.1.6}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="shield-python",
-    version="0.1.4",
+    version="0.1.6",
     packages=find_packages(),
     install_requires=["requests>=2.28.0"],
 )

{shield_python-0.1.4 → shield_python-0.1.6}/shield/__init__.py

@@ -2,4 +2,4 @@ from .client import Client
 from .exceptions import ShieldError
 
 __all__ = ["Client", "ShieldError"]
-__version__ = "0.1.4"
+__version__ = "0.1.5"

{shield_python-0.1.4 → shield_python-0.1.6}/shield/client.py

@@ -3,7 +3,7 @@ import hmac as hmac_mod
 import json
 import time
 from typing import Any, Dict, Optional
-from urllib.parse import urlparse
+from urllib.parse import urlencode
 
 import requests
 
@@ -12,6 +12,10 @@ from .resources.sessions import Sessions
 from .resources.events import Events
 from .resources.verify import Verify
 
+# ARCH-019: kept static to avoid leaking Python version / OS into server logs.
+# Bumped alongside setup.py version on each release.
+SDK_USER_AGENT = "shield-python/0.1.6"
+
 
 class Client:
     """Official Shield Python SDK client.
@@ -64,12 +68,29 @@ class Client:
         Raises:
             ShieldError: On non-2xx responses or request failures.
         """
-        url = f"{self.base_url}{path}"
         method = method.upper()
 
+        # C-1 (v0.1.6): fold query params into `path` BEFORE signing so the
+        # canonical message matches what the server validates against
+        # http.Request.URL.RequestURI(). Previously `params` was passed to
+        # requests.request() separately — requests would append them to the
+        # wire URL, but the SDK signed only the bare path, guaranteeing a
+        # signature mismatch on any request with query params. We pre-encode
+        # here and pass params=None to requests so there is exactly one
+        # canonical query string, controlled by this SDK, for both signing
+        # and transmission. doseq=True matches requests' own encoding for
+        # list-valued params (?tag=a&tag=b).
+        if params:
+            path_with_query = f"{path}?{urlencode(params, doseq=True)}"
+        else:
+            path_with_query = path
+
+        url = f"{self.base_url}{path_with_query}"
+
         headers = {
             "X-Shield-Key": self.api_key,
             "Content-Type": "application/json",
+            "User-Agent": SDK_USER_AGENT,
         }
 
         # Serialize body
@@ -83,7 +104,7 @@ class Client:
             timestamp = str(int(time.time()))
             nonce = str(uuid.uuid4())
             body_hash = hashlib.sha256(body).hexdigest()
-            message = f"{timestamp}.{method}.{path}.{body_hash}"
+            message = f"{timestamp}.{method}.{path_with_query}.{body_hash}"
             signature = hmac_mod.new(
                 self.hmac_secret.encode("utf-8"),
                 message.encode("utf-8"),
@@ -99,29 +120,31 @@ class Client:
                 url=url,
                 headers=headers,
                 data=body if body else None,
-                params=params,
+                params=None,
                 timeout=self.timeout,
             )
         except requests.RequestException as e:
             raise ShieldError(
                 message=f"Request failed: {str(e)}",
                 status_code=0,
-                code="request_error",
             )
 
         if not (200 <= response.status_code < 300):
-            error_message = response.text
-            error_code = "api_error"
+            # Backend returns {"error": "..."} (always) and sometimes
+            # {"message": "..."} with extra detail. Prefer message when present.
+            error_message = response.text or response.reason
             try:
                 error_body = response.json()
-                error_message = error_body.get("error", error_message)
-                error_code = error_body.get("code", error_code)
-            except (ValueError, KeyError):
+                error_message = (
+                    error_body.get("message")
+                    or error_body.get("error")
+                    or error_message
+                )
+            except ValueError:
                 pass
             raise ShieldError(
                 message=error_message,
                 status_code=response.status_code,
-                code=error_code,
             )
 
         if raw_response:

shield_python-0.1.6/shield/exceptions.py

@@ -0,0 +1,15 @@
+class ShieldError(Exception):
+    """Base exception for Shield SDK errors."""
+
+    def __init__(self, message: str, status_code: int = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __str__(self):
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+    def __repr__(self):
+        return f"ShieldError(message={self.message!r}, status_code={self.status_code!r})"

{shield_python-0.1.4 → shield_python-0.1.6}/shield_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shield-python
-Version: 0.1.4
+Version: 0.1.6
 Summary: Official Shield SDK for Python
 License: MIT
 Project-URL: Homepage, https://getshield.dev
@@ -264,3 +264,12 @@ Shield Standard Event Taxonomy v1.0 ??37 event types across 7 categories:
 | `shield.evidence.exported` | Evidence was exported |
 | `shield.evidence.verified` | Evidence was verified |
 | `shield.evidence.tampered_detected` | Evidence tampering was detected |
+
+## Versioning & API compatibility
+
+This SDK follows [Semantic Versioning](https://semver.org/).
+
+- **Pre-1.0** (current): minor-version bumps may ship breaking changes. Pin the full version in `requirements.txt`.
+- **1.0 and later**: the public API is stable within a major version. Breaking changes require a major-version bump.
+
+The Shield HTTP API is versioned at the URL path (`/api/v1`). This SDK targets `/api/v1` and will not transparently follow a server-side version bump — a new server major version will be delivered as a new SDK major version so callers opt in explicitly.

{shield_python-0.1.4 → shield_python-0.1.6}/shield_python.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ shield_python.egg-info/PKG-INFO
 shield_python.egg-info/SOURCES.txt
 shield_python.egg-info/dependency_links.txt
 shield_python.egg-info/requires.txt
-shield_python.egg-info/top_level.txt
+shield_python.egg-info/top_level.txt
+tests/test_signing.py

shield_python-0.1.6/tests/test_signing.py

@@ -0,0 +1,100 @@
+"""C-1 (v0.1.6): verify the Python SDK's canonical HMAC message covers the
+full request target (path + query string), not just the path.
+
+This test asserts the invariant directly from the Client internals: given a
+path and a params dict, the SDK must produce a signature over the SAME string
+that the server will see via http.Request.URL.RequestURI(). Different query
+strings → different signatures.
+
+Run with: pytest tests/
+"""
+
+import hashlib
+import hmac
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from shield.client import Client
+
+
+def _extract_signed_message(mock_request) -> str:
+    """Reconstruct the message the SDK signed, from the mock call args.
+
+    We capture the outgoing URL (which includes the final query string the
+    wire sees) and the X-Shield-Timestamp header, then recompute what the
+    canonical message would be if the SDK signed the URL's path+query.
+    Comparing that to the signature the SDK actually sent proves coverage.
+    """
+    call = mock_request.call_args
+    return call.kwargs["headers"]["X-Shield-Signature"], call.kwargs["url"], call.kwargs["headers"]
+
+
+def _expected_signature(secret: str, timestamp: str, method: str, path_with_query: str, body: bytes) -> str:
+    body_hash = hashlib.sha256(body).hexdigest()
+    message = f"{timestamp}.{method}.{path_with_query}.{body_hash}"
+    return hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()
+
+
+@patch("requests.Session.request")
+def test_params_are_included_in_signature(mock_req):
+    mock_req.return_value = MagicMock(status_code=200, content=b"{}", json=lambda: {})
+
+    secret = "a" * 64
+    client = Client("sk_test", base_url="https://api.getshield.dev/api/v1", hmac_secret=secret)
+
+    client._request("GET", "/sessions", params={"org": "A"})
+
+    sig, url, headers = _extract_signed_message(mock_req)
+    ts = headers["X-Shield-Timestamp"]
+
+    # Wire URL must include the query string exactly once.
+    assert url == "https://api.getshield.dev/api/v1/sessions?org=A"
+    # Signature must cover path+query, not just path.
+    assert sig == _expected_signature(secret, ts, "GET", "/sessions?org=A", b"")
+    # And must NOT match signing of path alone (the pre-0.1.6 behavior).
+    assert sig != _expected_signature(secret, ts, "GET", "/sessions", b"")
+
+
+@patch("requests.Session.request")
+def test_different_params_produce_different_signatures(mock_req):
+    mock_req.return_value = MagicMock(status_code=200, content=b"{}", json=lambda: {})
+    secret = "a" * 64
+    client = Client("sk_test", hmac_secret=secret)
+
+    client._request("GET", "/sessions", params={"org": "A"})
+    sig_a, _, _ = _extract_signed_message(mock_req)
+
+    client._request("GET", "/sessions", params={"org": "B"})
+    sig_b, _, _ = _extract_signed_message(mock_req)
+
+    assert sig_a != sig_b, "query tampering must invalidate the signature"
+
+
+@patch("requests.Session.request")
+def test_no_params_preserves_legacy_signature(mock_req):
+    """Backwards compat: requests without params sign just `path`, matching
+    the pre-0.1.6 SDK behavior. The C-1 fix only activates when params are
+    present, so existing callers see no signature change."""
+    mock_req.return_value = MagicMock(status_code=200, content=b"{}", json=lambda: {})
+
+    secret = "a" * 64
+    client = Client("sk_test", hmac_secret=secret)
+
+    client._request("POST", "/sessions", json_data={"title": "x"})
+    sig, _, headers = _extract_signed_message(mock_req)
+    ts = headers["X-Shield-Timestamp"]
+
+    body = b'{"title":"x"}'
+    assert sig == _expected_signature(secret, ts, "POST", "/sessions", body)
+
+
+@patch("requests.Session.request")
+def test_signature_is_lowercase_hex(mock_req):
+    mock_req.return_value = MagicMock(status_code=200, content=b"{}", json=lambda: {})
+    client = Client("sk_test", hmac_secret="secret")
+    client._request("GET", "/sessions")
+    sig, _, _ = _extract_signed_message(mock_req)
+    assert sig == sig.lower()
+    assert len(sig) == 64
+    assert all(c in "0123456789abcdef" for c in sig)

shield_python-0.1.4/shield/exceptions.py

@@ -1,23 +0,0 @@
-class ShieldError(Exception):
-    """Base exception for Shield SDK errors."""
-
-    def __init__(self, message: str, status_code: int = None, code: str = None):
-        super().__init__(message)
-        self.message = message
-        self.status_code = status_code
-        self.code = code
-
-    def __str__(self):
-        parts = []
-        if self.status_code:
-            parts.append(f"[{self.status_code}]")
-        if self.code:
-            parts.append(f"({self.code})")
-        parts.append(self.message)
-        return " ".join(parts)
-
-    def __repr__(self):
-        return (
-            f"ShieldError(message={self.message!r}, "
-            f"status_code={self.status_code!r}, code={self.code!r})"
-        )