shield-python 0.1.0__tar.gz

shield_python-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: shield-python
+Version: 0.1.0
+Summary: Official Shield SDK for Python
+License: MIT
+Project-URL: Homepage, https://getshield.dev
+Project-URL: Documentation, https://docs.getshield.dev
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+
+# Shield Python SDK
+
+Official Python SDK for [Shield](https://getshield.dev) — tamper-evident session recording for real estate transactions.
+
+## Installation
+
+```bash
+pip install shield-python
+```
+
+## Quick Start
+
+```python
+import shield
+
+client = shield.Client(api_key="sk_live_your_api_key")
+
+# Create a session
+session = client.sessions.create(title="123 Main St Closing")
+session_id = session["id"]
+
+# Record events
+client.events.create(
+    session_id=session_id,
+    event_type="shield.party.joined",
+    actor="agent@example.com",
+    data={"role": "listing_agent", "name": "Jane Smith"},
+)
+
+client.events.create(
+    session_id=session_id,
+    event_type="shield.content.uploaded",
+    actor="agent@example.com",
+    data={"filename": "purchase_agreement.pdf", "hash": "sha256:abc123..."},
+)
+
+client.events.create(
+    session_id=session_id,
+    event_type="shield.agreement.signed",
+    actor="buyer@example.com",
+    data={"document": "purchase_agreement.pdf"},
+)
+
+# Verify session integrity
+result = client.verify.session(session_id)
+print(result["intact"])  # True
+
+# Export session
+pdf_bytes = client.sessions.export(session_id, format="pdf")
+with open("audit_trail.pdf", "wb") as f:
+    f.write(pdf_bytes)
+```
+
+## HMAC Authentication
+
+For enhanced security, provide an HMAC secret to sign every request:
+
+```python
+client = shield.Client(
+    api_key="sk_live_your_api_key",
+    hmac_secret="your_hmac_secret",
+)
+```
+
+When an HMAC secret is configured, the SDK computes a signature for each request:
+
+- `X-Shield-Timestamp` — Unix timestamp of the request
+- `X-Shield-Signature` — HMAC-SHA256 of `{timestamp}.{METHOD}.{path}.{SHA256(body)}`
+
+The server validates these headers to ensure requests have not been tampered with or replayed.
+
+## Flask Integration
+
+```python
+from flask import Flask, request, jsonify
+import shield
+
+app = Flask(__name__)
+client = shield.Client(api_key="sk_live_your_api_key")
+
+@app.route("/sessions", methods=["POST"])
+def create_session():
+    data = request.get_json()
+    session = client.sessions.create(title=data["title"])
+
+    # Record who created the session
+    client.events.create(
+        session_id=session["id"],
+        event_type="shield.session.created",
+        actor=data["user_email"],
+    )
+    return jsonify(session), 201
+
+@app.route("/sessions/<session_id>/upload", methods=["POST"])
+def upload_document(session_id):
+    file = request.files["file"]
+    # ... save file logic ...
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.content.uploaded",
+        actor=request.headers.get("X-User-Email"),
+        data={"filename": file.filename},
+    )
+    return jsonify({"status": "uploaded"}), 200
+
+@app.route("/sessions/<session_id>/sign", methods=["POST"])
+def sign_agreement(session_id):
+    data = request.get_json()
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.agreement.signed",
+        actor=data["signer_email"],
+        data={"document": data["document_name"], "ip": request.remote_addr},
+    )
+    return jsonify({"status": "signed"}), 200
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI, UploadFile, Header
+from pydantic import BaseModel
+import shield
+
+app = FastAPI()
+client = shield.Client(
+    api_key="sk_live_your_api_key",
+    hmac_secret="your_hmac_secret",
+)
+
+class CreateSessionRequest(BaseModel):
+    title: str
+    user_email: str
+
+class SignRequest(BaseModel):
+    signer_email: str
+    document_name: str
+
+@app.post("/sessions")
+async def create_session(body: CreateSessionRequest):
+    session = client.sessions.create(title=body.title)
+    client.events.create(
+        session_id=session["id"],
+        event_type="shield.session.created",
+        actor=body.user_email,
+    )
+    return session
+
+@app.post("/sessions/{session_id}/upload")
+async def upload_document(
+    session_id: str,
+    file: UploadFile,
+    x_user_email: str = Header(...),
+):
+    # ... save file logic ...
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.content.uploaded",
+        actor=x_user_email,
+        data={"filename": file.filename},
+    )
+    return {"status": "uploaded"}
+
+@app.post("/sessions/{session_id}/sign")
+async def sign_agreement(session_id: str, body: SignRequest):
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.agreement.signed",
+        actor=body.signer_email,
+        data={"document": body.document_name},
+    )
+    return {"status": "signed"}
+
+@app.get("/sessions/{session_id}/verify")
+async def verify_session(session_id: str):
+    return client.verify.session(session_id)
+```
+
+## Event Types Reference
+
+Shield Standard Event Taxonomy v1.0 — 37 event types across 7 categories:
+
+### Party Events
+| Event Type | Description |
+|---|---|
+| `shield.party.joined` | A party joined the session |
+| `shield.party.left` | A party left the session |
+| `shield.party.identity.verified` | Party identity was verified |
+| `shield.party.identity.failed` | Party identity verification failed |
+| `shield.party.role.assigned` | A role was assigned to a party |
+
+### Session Events
+| Event Type | Description |
+|---|---|
+| `shield.session.created` | Session was created |
+| `shield.session.opened` | Session was opened |
+| `shield.session.closed` | Session was closed |
+| `shield.session.expired` | Session expired |
+| `shield.session.archived` | Session was archived |
+
+### Content Events
+| Event Type | Description |
+|---|---|
+| `shield.content.uploaded` | Content was uploaded |
+| `shield.content.viewed` | Content was viewed |
+| `shield.content.downloaded` | Content was downloaded |
+| `shield.content.deleted` | Content was deleted |
+| `shield.content.hash.verified` | Content hash was verified |
+
+### Negotiation Events
+| Event Type | Description |
+|---|---|
+| `shield.negotiation.terms.proposed` | Terms were proposed |
+| `shield.negotiation.terms.accepted` | Terms were accepted |
+| `shield.negotiation.terms.rejected` | Terms were rejected |
+| `shield.negotiation.terms.modified` | Terms were modified |
+| `shield.negotiation.terms.expired` | Terms expired |
+| `shield.negotiation.message.sent` | Negotiation message sent |
+| `shield.negotiation.message.read` | Negotiation message read |
+
+### Agreement Events
+| Event Type | Description |
+|---|---|
+| `shield.agreement.drafted` | Agreement was drafted |
+| `shield.agreement.reviewed` | Agreement was reviewed |
+| `shield.agreement.approved` | Agreement was approved |
+| `shield.agreement.signed` | Agreement was signed |
+| `shield.agreement.countersigned` | Agreement was countersigned |
+| `shield.agreement.voided` | Agreement was voided |
+| `shield.agreement.reached` | Agreement was reached |
+
+### Access Events
+| Event Type | Description |
+|---|---|
+| `shield.access.granted` | Access was granted |
+| `shield.access.revoked` | Access was revoked |
+| `shield.access.attempted` | Access was attempted |
+| `shield.access.denied` | Access was denied |
+
+### Disclosure Events
+| Event Type | Description |
+|---|---|
+| `shield.disclosure.presented` | Disclosure was presented |
+| `shield.disclosure.acknowledged` | Disclosure was acknowledged |
+| `shield.disclosure.declined` | Disclosure was declined |
+
+### Evidence Events
+| Event Type | Description |
+|---|---|
+| `shield.evidence.exported` | Evidence was exported |
+| `shield.evidence.verified` | Evidence was verified |
+| `shield.evidence.tampered_detected` | Evidence tampering was detected |

shield_python-0.1.0/README.md

@@ -0,0 +1,255 @@
+# Shield Python SDK
+
+Official Python SDK for [Shield](https://getshield.dev) — tamper-evident session recording for real estate transactions.
+
+## Installation
+
+```bash
+pip install shield-python
+```
+
+## Quick Start
+
+```python
+import shield
+
+client = shield.Client(api_key="sk_live_your_api_key")
+
+# Create a session
+session = client.sessions.create(title="123 Main St Closing")
+session_id = session["id"]
+
+# Record events
+client.events.create(
+    session_id=session_id,
+    event_type="shield.party.joined",
+    actor="agent@example.com",
+    data={"role": "listing_agent", "name": "Jane Smith"},
+)
+
+client.events.create(
+    session_id=session_id,
+    event_type="shield.content.uploaded",
+    actor="agent@example.com",
+    data={"filename": "purchase_agreement.pdf", "hash": "sha256:abc123..."},
+)
+
+client.events.create(
+    session_id=session_id,
+    event_type="shield.agreement.signed",
+    actor="buyer@example.com",
+    data={"document": "purchase_agreement.pdf"},
+)
+
+# Verify session integrity
+result = client.verify.session(session_id)
+print(result["intact"])  # True
+
+# Export session
+pdf_bytes = client.sessions.export(session_id, format="pdf")
+with open("audit_trail.pdf", "wb") as f:
+    f.write(pdf_bytes)
+```
+
+## HMAC Authentication
+
+For enhanced security, provide an HMAC secret to sign every request:
+
+```python
+client = shield.Client(
+    api_key="sk_live_your_api_key",
+    hmac_secret="your_hmac_secret",
+)
+```
+
+When an HMAC secret is configured, the SDK computes a signature for each request:
+
+- `X-Shield-Timestamp` — Unix timestamp of the request
+- `X-Shield-Signature` — HMAC-SHA256 of `{timestamp}.{METHOD}.{path}.{SHA256(body)}`
+
+The server validates these headers to ensure requests have not been tampered with or replayed.
+
+## Flask Integration
+
+```python
+from flask import Flask, request, jsonify
+import shield
+
+app = Flask(__name__)
+client = shield.Client(api_key="sk_live_your_api_key")
+
+@app.route("/sessions", methods=["POST"])
+def create_session():
+    data = request.get_json()
+    session = client.sessions.create(title=data["title"])
+
+    # Record who created the session
+    client.events.create(
+        session_id=session["id"],
+        event_type="shield.session.created",
+        actor=data["user_email"],
+    )
+    return jsonify(session), 201
+
+@app.route("/sessions/<session_id>/upload", methods=["POST"])
+def upload_document(session_id):
+    file = request.files["file"]
+    # ... save file logic ...
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.content.uploaded",
+        actor=request.headers.get("X-User-Email"),
+        data={"filename": file.filename},
+    )
+    return jsonify({"status": "uploaded"}), 200
+
+@app.route("/sessions/<session_id>/sign", methods=["POST"])
+def sign_agreement(session_id):
+    data = request.get_json()
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.agreement.signed",
+        actor=data["signer_email"],
+        data={"document": data["document_name"], "ip": request.remote_addr},
+    )
+    return jsonify({"status": "signed"}), 200
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI, UploadFile, Header
+from pydantic import BaseModel
+import shield
+
+app = FastAPI()
+client = shield.Client(
+    api_key="sk_live_your_api_key",
+    hmac_secret="your_hmac_secret",
+)
+
+class CreateSessionRequest(BaseModel):
+    title: str
+    user_email: str
+
+class SignRequest(BaseModel):
+    signer_email: str
+    document_name: str
+
+@app.post("/sessions")
+async def create_session(body: CreateSessionRequest):
+    session = client.sessions.create(title=body.title)
+    client.events.create(
+        session_id=session["id"],
+        event_type="shield.session.created",
+        actor=body.user_email,
+    )
+    return session
+
+@app.post("/sessions/{session_id}/upload")
+async def upload_document(
+    session_id: str,
+    file: UploadFile,
+    x_user_email: str = Header(...),
+):
+    # ... save file logic ...
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.content.uploaded",
+        actor=x_user_email,
+        data={"filename": file.filename},
+    )
+    return {"status": "uploaded"}
+
+@app.post("/sessions/{session_id}/sign")
+async def sign_agreement(session_id: str, body: SignRequest):
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.agreement.signed",
+        actor=body.signer_email,
+        data={"document": body.document_name},
+    )
+    return {"status": "signed"}
+
+@app.get("/sessions/{session_id}/verify")
+async def verify_session(session_id: str):
+    return client.verify.session(session_id)
+```
+
+## Event Types Reference
+
+Shield Standard Event Taxonomy v1.0 — 37 event types across 7 categories:
+
+### Party Events
+| Event Type | Description |
+|---|---|
+| `shield.party.joined` | A party joined the session |
+| `shield.party.left` | A party left the session |
+| `shield.party.identity.verified` | Party identity was verified |
+| `shield.party.identity.failed` | Party identity verification failed |
+| `shield.party.role.assigned` | A role was assigned to a party |
+
+### Session Events
+| Event Type | Description |
+|---|---|
+| `shield.session.created` | Session was created |
+| `shield.session.opened` | Session was opened |
+| `shield.session.closed` | Session was closed |
+| `shield.session.expired` | Session expired |
+| `shield.session.archived` | Session was archived |
+
+### Content Events
+| Event Type | Description |
+|---|---|
+| `shield.content.uploaded` | Content was uploaded |
+| `shield.content.viewed` | Content was viewed |
+| `shield.content.downloaded` | Content was downloaded |
+| `shield.content.deleted` | Content was deleted |
+| `shield.content.hash.verified` | Content hash was verified |
+
+### Negotiation Events
+| Event Type | Description |
+|---|---|
+| `shield.negotiation.terms.proposed` | Terms were proposed |
+| `shield.negotiation.terms.accepted` | Terms were accepted |
+| `shield.negotiation.terms.rejected` | Terms were rejected |
+| `shield.negotiation.terms.modified` | Terms were modified |
+| `shield.negotiation.terms.expired` | Terms expired |
+| `shield.negotiation.message.sent` | Negotiation message sent |
+| `shield.negotiation.message.read` | Negotiation message read |
+
+### Agreement Events
+| Event Type | Description |
+|---|---|
+| `shield.agreement.drafted` | Agreement was drafted |
+| `shield.agreement.reviewed` | Agreement was reviewed |
+| `shield.agreement.approved` | Agreement was approved |
+| `shield.agreement.signed` | Agreement was signed |
+| `shield.agreement.countersigned` | Agreement was countersigned |
+| `shield.agreement.voided` | Agreement was voided |
+| `shield.agreement.reached` | Agreement was reached |
+
+### Access Events
+| Event Type | Description |
+|---|---|
+| `shield.access.granted` | Access was granted |
+| `shield.access.revoked` | Access was revoked |
+| `shield.access.attempted` | Access was attempted |
+| `shield.access.denied` | Access was denied |
+
+### Disclosure Events
+| Event Type | Description |
+|---|---|
+| `shield.disclosure.presented` | Disclosure was presented |
+| `shield.disclosure.acknowledged` | Disclosure was acknowledged |
+| `shield.disclosure.declined` | Disclosure was declined |
+
+### Evidence Events
+| Event Type | Description |
+|---|---|
+| `shield.evidence.exported` | Evidence was exported |
+| `shield.evidence.verified` | Evidence was verified |
+| `shield.evidence.tampered_detected` | Evidence tampering was detected |

shield_python-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shield-python"
+version = "0.1.0"
+description = "Official Shield SDK for Python"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+dependencies = ["requests>=2.28.0"]
+
+[project.urls]
+Homepage = "https://getshield.dev"
+Documentation = "https://docs.getshield.dev"

shield_python-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shield_python-0.1.0/setup.py

@@ -0,0 +1,8 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="shield-python",
+    version="0.1.0",
+    packages=find_packages(),
+    install_requires=["requests>=2.28.0"],
+)

shield_python-0.1.0/shield/__init__.py

@@ -0,0 +1,5 @@
+from .client import Client
+from .exceptions import ShieldError
+
+__all__ = ["Client", "ShieldError"]
+__version__ = "0.1.0"

shield_python-0.1.0/shield/client.py

@@ -0,0 +1,130 @@
+import hashlib
+import hmac as hmac_mod
+import json
+import time
+from typing import Any, Dict, Optional
+from urllib.parse import urlparse
+
+import requests
+
+from .exceptions import ShieldError
+from .resources.sessions import Sessions
+from .resources.events import Events
+from .resources.verify import Verify
+
+
+class Client:
+    """Official Shield Python SDK client.
+
+    Args:
+        api_key: Your Shield API key.
+        base_url: Base URL for the Shield API. Defaults to https://getshield.dev/api/v1.
+        hmac_secret: Optional HMAC secret for request signing.
+        timeout: Request timeout in seconds. Defaults to 30.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://getshield.dev/api/v1",
+        hmac_secret: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.hmac_secret = hmac_secret
+        self.timeout = timeout
+        self._session = requests.Session()
+
+        # Resource instances
+        self.sessions = Sessions(self)
+        self.events = Events(self)
+        self.verify = Verify(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        raw_response: bool = False,
+    ) -> Any:
+        """Make an authenticated request to the Shield API.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE).
+            path: API path (e.g. /sessions).
+            json_data: JSON body for POST/PUT requests.
+            params: Query parameters.
+            raw_response: If True, return raw response content (bytes).
+
+        Returns:
+            Parsed JSON response as dict, or bytes if raw_response is True.
+
+        Raises:
+            ShieldError: On non-2xx responses or request failures.
+        """
+        url = f"{self.base_url}{path}"
+        method = method.upper()
+
+        headers = {
+            "X-Shield-Key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+        # Serialize body
+        body = b""
+        if json_data is not None:
+            body = json.dumps(json_data, separators=(",", ":")).encode("utf-8")
+
+        # HMAC signing
+        if self.hmac_secret:
+            timestamp = str(int(time.time()))
+            body_hash = hashlib.sha256(body).hexdigest()
+            message = f"{timestamp}.{method}.{path}.{body_hash}"
+            signature = hmac_mod.new(
+                self.hmac_secret.encode("utf-8"),
+                message.encode("utf-8"),
+                hashlib.sha256,
+            ).hexdigest()
+            headers["X-Shield-Signature"] = signature
+            headers["X-Shield-Timestamp"] = timestamp
+
+        try:
+            response = self._session.request(
+                method=method,
+                url=url,
+                headers=headers,
+                data=body if body else None,
+                params=params,
+                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"
+            try:
+                error_body = response.json()
+                error_message = error_body.get("error", error_message)
+                error_code = error_body.get("code", error_code)
+            except (ValueError, KeyError):
+                pass
+            raise ShieldError(
+                message=error_message,
+                status_code=response.status_code,
+                code=error_code,
+            )
+
+        if raw_response:
+            return response.content
+
+        if not response.content:
+            return {}
+
+        return response.json()

shield_python-0.1.0/shield/exceptions.py

@@ -0,0 +1,23 @@
+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})"
+        )

shield_python-0.1.0/shield/resources/events.py

@@ -0,0 +1,40 @@
+from typing import Any, Dict, Optional
+
+
+class Events:
+    """Record events within Shield sessions."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        session_id: str,
+        event_type: str,
+        actor: str,
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Create a new event in a session.
+
+        Args:
+            session_id: The session ID to record the event in.
+            event_type: Event type from the Shield Standard Event Taxonomy
+                        (e.g. "shield.party.joined").
+            actor: Identifier for the actor performing the action.
+            data: Optional additional event data.
+
+        Returns:
+            Created event object.
+        """
+        payload: Dict[str, Any] = {
+            "event_type": event_type,
+            "actor": actor,
+        }
+        if data is not None:
+            payload["data"] = data
+
+        return self._client._request(
+            "POST",
+            f"/sessions/{session_id}/events",
+            json_data=payload,
+        )

shield_python-0.1.0/shield/resources/sessions.py

@@ -0,0 +1,47 @@
+from typing import Any, Dict
+
+
+class Sessions:
+    """Manage Shield sessions."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(self, title: str) -> Dict[str, Any]:
+        """Create a new session.
+
+        Args:
+            title: Human-readable title for the session.
+
+        Returns:
+            Created session object.
+        """
+        return self._client._request("POST", "/sessions", json_data={"title": title})
+
+    def retrieve(self, session_id: str) -> Dict[str, Any]:
+        """Retrieve a session by ID.
+
+        Args:
+            session_id: The session ID.
+
+        Returns:
+            Session object.
+        """
+        return self._client._request("GET", f"/sessions/{session_id}")
+
+    def export(self, session_id: str, format: str = "json"):
+        """Export a session in the specified format.
+
+        Args:
+            session_id: The session ID.
+            format: Export format — "json" or "pdf". Defaults to "json".
+
+        Returns:
+            dict if format is "json", bytes for binary formats like "pdf".
+        """
+        raw = format != "json"
+        return self._client._request(
+            "GET",
+            f"/sessions/{session_id}/export/{format}",
+            raw_response=raw,
+        )

shield_python-0.1.0/shield/resources/verify.py

@@ -0,0 +1,19 @@
+from typing import Any, Dict
+
+
+class Verify:
+    """Verify Shield session integrity."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def session(self, session_id: str) -> Dict[str, Any]:
+        """Verify the integrity of a session's event chain.
+
+        Args:
+            session_id: The session ID to verify.
+
+        Returns:
+            Verification result with integrity status.
+        """
+        return self._client._request("GET", f"/sessions/{session_id}/verify")

shield_python-0.1.0/shield_python.egg-info/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: shield-python
+Version: 0.1.0
+Summary: Official Shield SDK for Python
+License: MIT
+Project-URL: Homepage, https://getshield.dev
+Project-URL: Documentation, https://docs.getshield.dev
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+
+# Shield Python SDK
+
+Official Python SDK for [Shield](https://getshield.dev) — tamper-evident session recording for real estate transactions.
+
+## Installation
+
+```bash
+pip install shield-python
+```
+
+## Quick Start
+
+```python
+import shield
+
+client = shield.Client(api_key="sk_live_your_api_key")
+
+# Create a session
+session = client.sessions.create(title="123 Main St Closing")
+session_id = session["id"]
+
+# Record events
+client.events.create(
+    session_id=session_id,
+    event_type="shield.party.joined",
+    actor="agent@example.com",
+    data={"role": "listing_agent", "name": "Jane Smith"},
+)
+
+client.events.create(
+    session_id=session_id,
+    event_type="shield.content.uploaded",
+    actor="agent@example.com",
+    data={"filename": "purchase_agreement.pdf", "hash": "sha256:abc123..."},
+)
+
+client.events.create(
+    session_id=session_id,
+    event_type="shield.agreement.signed",
+    actor="buyer@example.com",
+    data={"document": "purchase_agreement.pdf"},
+)
+
+# Verify session integrity
+result = client.verify.session(session_id)
+print(result["intact"])  # True
+
+# Export session
+pdf_bytes = client.sessions.export(session_id, format="pdf")
+with open("audit_trail.pdf", "wb") as f:
+    f.write(pdf_bytes)
+```
+
+## HMAC Authentication
+
+For enhanced security, provide an HMAC secret to sign every request:
+
+```python
+client = shield.Client(
+    api_key="sk_live_your_api_key",
+    hmac_secret="your_hmac_secret",
+)
+```
+
+When an HMAC secret is configured, the SDK computes a signature for each request:
+
+- `X-Shield-Timestamp` — Unix timestamp of the request
+- `X-Shield-Signature` — HMAC-SHA256 of `{timestamp}.{METHOD}.{path}.{SHA256(body)}`
+
+The server validates these headers to ensure requests have not been tampered with or replayed.
+
+## Flask Integration
+
+```python
+from flask import Flask, request, jsonify
+import shield
+
+app = Flask(__name__)
+client = shield.Client(api_key="sk_live_your_api_key")
+
+@app.route("/sessions", methods=["POST"])
+def create_session():
+    data = request.get_json()
+    session = client.sessions.create(title=data["title"])
+
+    # Record who created the session
+    client.events.create(
+        session_id=session["id"],
+        event_type="shield.session.created",
+        actor=data["user_email"],
+    )
+    return jsonify(session), 201
+
+@app.route("/sessions/<session_id>/upload", methods=["POST"])
+def upload_document(session_id):
+    file = request.files["file"]
+    # ... save file logic ...
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.content.uploaded",
+        actor=request.headers.get("X-User-Email"),
+        data={"filename": file.filename},
+    )
+    return jsonify({"status": "uploaded"}), 200
+
+@app.route("/sessions/<session_id>/sign", methods=["POST"])
+def sign_agreement(session_id):
+    data = request.get_json()
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.agreement.signed",
+        actor=data["signer_email"],
+        data={"document": data["document_name"], "ip": request.remote_addr},
+    )
+    return jsonify({"status": "signed"}), 200
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI, UploadFile, Header
+from pydantic import BaseModel
+import shield
+
+app = FastAPI()
+client = shield.Client(
+    api_key="sk_live_your_api_key",
+    hmac_secret="your_hmac_secret",
+)
+
+class CreateSessionRequest(BaseModel):
+    title: str
+    user_email: str
+
+class SignRequest(BaseModel):
+    signer_email: str
+    document_name: str
+
+@app.post("/sessions")
+async def create_session(body: CreateSessionRequest):
+    session = client.sessions.create(title=body.title)
+    client.events.create(
+        session_id=session["id"],
+        event_type="shield.session.created",
+        actor=body.user_email,
+    )
+    return session
+
+@app.post("/sessions/{session_id}/upload")
+async def upload_document(
+    session_id: str,
+    file: UploadFile,
+    x_user_email: str = Header(...),
+):
+    # ... save file logic ...
+
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.content.uploaded",
+        actor=x_user_email,
+        data={"filename": file.filename},
+    )
+    return {"status": "uploaded"}
+
+@app.post("/sessions/{session_id}/sign")
+async def sign_agreement(session_id: str, body: SignRequest):
+    client.events.create(
+        session_id=session_id,
+        event_type="shield.agreement.signed",
+        actor=body.signer_email,
+        data={"document": body.document_name},
+    )
+    return {"status": "signed"}
+
+@app.get("/sessions/{session_id}/verify")
+async def verify_session(session_id: str):
+    return client.verify.session(session_id)
+```
+
+## Event Types Reference
+
+Shield Standard Event Taxonomy v1.0 — 37 event types across 7 categories:
+
+### Party Events
+| Event Type | Description |
+|---|---|
+| `shield.party.joined` | A party joined the session |
+| `shield.party.left` | A party left the session |
+| `shield.party.identity.verified` | Party identity was verified |
+| `shield.party.identity.failed` | Party identity verification failed |
+| `shield.party.role.assigned` | A role was assigned to a party |
+
+### Session Events
+| Event Type | Description |
+|---|---|
+| `shield.session.created` | Session was created |
+| `shield.session.opened` | Session was opened |
+| `shield.session.closed` | Session was closed |
+| `shield.session.expired` | Session expired |
+| `shield.session.archived` | Session was archived |
+
+### Content Events
+| Event Type | Description |
+|---|---|
+| `shield.content.uploaded` | Content was uploaded |
+| `shield.content.viewed` | Content was viewed |
+| `shield.content.downloaded` | Content was downloaded |
+| `shield.content.deleted` | Content was deleted |
+| `shield.content.hash.verified` | Content hash was verified |
+
+### Negotiation Events
+| Event Type | Description |
+|---|---|
+| `shield.negotiation.terms.proposed` | Terms were proposed |
+| `shield.negotiation.terms.accepted` | Terms were accepted |
+| `shield.negotiation.terms.rejected` | Terms were rejected |
+| `shield.negotiation.terms.modified` | Terms were modified |
+| `shield.negotiation.terms.expired` | Terms expired |
+| `shield.negotiation.message.sent` | Negotiation message sent |
+| `shield.negotiation.message.read` | Negotiation message read |
+
+### Agreement Events
+| Event Type | Description |
+|---|---|
+| `shield.agreement.drafted` | Agreement was drafted |
+| `shield.agreement.reviewed` | Agreement was reviewed |
+| `shield.agreement.approved` | Agreement was approved |
+| `shield.agreement.signed` | Agreement was signed |
+| `shield.agreement.countersigned` | Agreement was countersigned |
+| `shield.agreement.voided` | Agreement was voided |
+| `shield.agreement.reached` | Agreement was reached |
+
+### Access Events
+| Event Type | Description |
+|---|---|
+| `shield.access.granted` | Access was granted |
+| `shield.access.revoked` | Access was revoked |
+| `shield.access.attempted` | Access was attempted |
+| `shield.access.denied` | Access was denied |
+
+### Disclosure Events
+| Event Type | Description |
+|---|---|
+| `shield.disclosure.presented` | Disclosure was presented |
+| `shield.disclosure.acknowledged` | Disclosure was acknowledged |
+| `shield.disclosure.declined` | Disclosure was declined |
+
+### Evidence Events
+| Event Type | Description |
+|---|---|
+| `shield.evidence.exported` | Evidence was exported |
+| `shield.evidence.verified` | Evidence was verified |
+| `shield.evidence.tampered_detected` | Evidence tampering was detected |

shield_python-0.1.0/shield_python.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+setup.py
+shield/__init__.py
+shield/client.py
+shield/exceptions.py
+shield/resources/__init__.py
+shield/resources/events.py
+shield/resources/sessions.py
+shield/resources/verify.py
+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-0.1.0/shield_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shield_python-0.1.0/shield_python.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28.0

shield_python-0.1.0/shield_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+shield