actpass 1.1.0__py3-none-any.whl

actpass/__init__.py

@@ -0,0 +1,30 @@
+"""ActPass Python SDK (spec section 14).
+
+Zero-dependency client mirroring the TypeScript ``@actpass/sdk`` surface.
+
+    from actpass import create_actpass
+
+    client = create_actpass(api_key="...", tenant_id="1", agent_id="support_agent")
+    result = client.guard(
+        goal="resolve_refund_request",
+        tool="stripe.refund.create",
+        args={"chargeId": "ch_123", "amount": 14900, "currency": "USD"},
+        execute_fn=lambda ctx: do_refund(),
+    )
+"""
+
+from .client import (
+    ActPassClient,
+    ActPassError,
+    create_actpass,
+    DEFAULT_BASE_URL,
+)
+
+__all__ = [
+    "ActPassClient",
+    "ActPassError",
+    "create_actpass",
+    "DEFAULT_BASE_URL",
+]
+
+__version__ = "0.1.0"

actpass/client.py

@@ -0,0 +1,348 @@
+"""ActPass Python SDK client (spec section 14).
+
+A zero-dependency client (Python standard library only) that mirrors the
+TypeScript ``packages/sdk`` surface: an :class:`ActPassClient` with
+``preflight()``, ``guard()``, ``issue_passport()``, ``verify_passport()``,
+``revoke_passport()`` and ``record_evidence()``.
+
+Design notes that mirror the TS client (``packages/sdk/src/client.ts``):
+
+* HTTP transport is ``urllib.request`` + ``json`` from the stdlib so the SDK
+  carries **zero third-party dependencies**.
+* Requests authenticate with a ``Bearer`` API key plus the
+  ``x-actpass-tenant`` header. The tenant is resolved server-side from the
+  authenticated principal (spec section 11.2) — it is sent only as a routing
+  hint, never trusted by the gateway.
+* The client **fails closed**: any non-2xx response raises
+  :class:`ActPassError`, except ``401``/``403`` which are returned as the
+  parsed JSON body so callers can inspect the auth failure (matching the TS
+  ``post()`` behaviour). ``guard()`` therefore only executes the caller's
+  function when the decision is ``allow`` or ``warn``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+__all__ = [
+    "ActPassClient",
+    "ActPassError",
+    "create_actpass",
+    "DEFAULT_BASE_URL",
+]
+
+DEFAULT_BASE_URL = "https://api.actpass.org"
+
+T = TypeVar("T")
+
+# Decisions for which guard() proceeds to execute the caller's function.
+_EXECUTABLE_DECISIONS = frozenset({"allow", "warn"})
+
+
+class ActPassError(Exception):
+    """Raised on non-2xx responses (other than 401/403) or transport errors.
+
+    Failing closed is the whole point: callers should treat an
+    :class:`ActPassError` as "deny / do not execute".
+    """
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Optional[str] = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class ActPassClient:
+    """HTTP client for the ActPass public v1 endpoints.
+
+    Mirrors ``ActPassClient`` from ``packages/sdk/src/client.ts``.
+
+    Args:
+        api_key: Bearer API key (``<key>`` half of an ``ACTPASS_API_KEYS`` pair).
+        tenant_id: Tenant routing hint sent as ``x-actpass-tenant``. The server
+            resolves the authoritative tenant from the principal.
+        agent_id: Identifier injected into preflight/passport request bodies.
+        base_url: API base URL. Falls back to the ``ACTPASS_API_BASE_URL`` env
+            var, then to :data:`DEFAULT_BASE_URL`.
+        timeout: Per-request socket timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.api_key = api_key
+        # Identity is resolved server-side from the key (§11.2); these are hints.
+        self.tenant_id = tenant_id
+        self.agent_id = agent_id or "sdk"
+        self.base_url = (
+            base_url
+            or os.environ.get("ACTPASS_API_BASE_URL")
+            or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------ #
+    # Low-level transport
+    # ------------------------------------------------------------------ #
+    def _headers(self, with_content_type: bool) -> Dict[str, str]:
+        headers = {"authorization": f"Bearer {self.api_key}"}
+        if self.tenant_id:
+            headers["x-actpass-tenant"] = self.tenant_id
+        if with_content_type:
+            headers["content-type"] = "application/json"
+        return headers
+
+    def _request(self, method: str, path: str, body: Optional[Any]) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers=self._headers(with_content_type=body is not None),
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return self._read_json(resp)
+        except urllib.error.HTTPError as exc:
+            # 401/403 carry an inspectable JSON body in the TS client; surface
+            # it the same way instead of raising. Everything else fails closed.
+            status = exc.code
+            raw = exc.read().decode("utf-8", "replace") if exc.fp else ""
+            if method == "POST" and status in (401, 403):
+                try:
+                    return json.loads(raw) if raw else {}
+                except (ValueError, TypeError):
+                    return {}
+            raise ActPassError(
+                f"ActPass {path} {status}: {raw}", status=status, body=raw
+            ) from exc
+        except urllib.error.URLError as exc:
+            # Network failure -> fail closed.
+            raise ActPassError(f"ActPass {path} unreachable: {exc.reason}") from exc
+
+    @staticmethod
+    def _read_json(resp: Any) -> Dict[str, Any]:
+        raw = resp.read().decode("utf-8", "replace")
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except (ValueError, TypeError) as exc:
+            raise ActPassError(f"ActPass returned non-JSON body: {raw}") from exc
+
+    def _post(self, path: str, body: Any) -> Dict[str, Any]:
+        return self._request("POST", path, body)
+
+    def _get(self, path: str) -> Dict[str, Any]:
+        return self._request("GET", path, None)
+
+    # ------------------------------------------------------------------ #
+    # Public API surface (mirrors packages/sdk/src/client.ts)
+    # ------------------------------------------------------------------ #
+    def preflight(
+        self,
+        goal: str,
+        tool: str,
+        args: Dict[str, Any],
+        resource: str = "",
+        user_id: Optional[str] = None,
+        passport: Optional[str] = None,
+        mode: str = "enforce",
+        idempotency_key: Optional[str] = None,
+        audience: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Evaluate the deterministic policy for a tool execution.
+
+        Returns the raw preflight decision dict (``decision``, ``reason_code``,
+        ``risk_tier``, ``explain``, ...).
+        """
+        return self._post(
+            "/api/v1/actions/preflight",
+            {
+                "agent_id": self.agent_id,
+                "goal": goal,
+                "tool": tool,
+                "resource": resource,
+                "args": args,
+                "user_id": user_id,
+                "passport": passport,
+                "mode": mode,
+                "idempotency_key": idempotency_key,
+                "audience": audience,
+            },
+        )
+
+    def guard(
+        self,
+        goal: str,
+        tool: str,
+        args: Dict[str, Any],
+        execute_fn: Callable[[Dict[str, Any]], T],
+        resource: str = "",
+        user_id: Optional[str] = None,
+        passport: Optional[str] = None,
+        mode: str = "enforce",
+        idempotency_key: Optional[str] = None,
+        audience: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Preflight + (optionally) execute in one call.
+
+        ``execute_fn`` is invoked with a ``{"credential": {...}}`` context only
+        when the decision is ``allow`` or ``warn``. Returns a dict shaped like
+        the TS ``GuardOutput``: ``{"decision": ..., "result"?: ..., "error"?: ...}``.
+        """
+        decision = self.preflight(
+            goal=goal,
+            tool=tool,
+            args=args,
+            resource=resource,
+            user_id=user_id,
+            passport=passport,
+            mode=mode,
+            idempotency_key=idempotency_key,
+            audience=audience,
+        )
+        if decision.get("decision") not in _EXECUTABLE_DECISIONS:
+            return {"decision": decision}
+        ctx = {"credential": {"token": "sdk-local", "expires_at": None}}
+        try:
+            result = execute_fn(ctx)
+            return {"decision": decision, "result": result}
+        except Exception as err:  # noqa: BLE001 - surface as GuardOutput.error
+            return {"decision": decision, "error": str(err)}
+
+    def issue_passport(
+        self,
+        audience: str,
+        goal: str,
+        allowed_tools: List[str],
+        allowed_resources: Optional[List[str]] = None,
+        resource_constraints: Optional[Dict[str, Any]] = None,
+        user_id: Optional[str] = None,
+        ttl_seconds: Optional[int] = None,
+        risk_tier: str = "medium",
+    ) -> Dict[str, Any]:
+        """Mint a scoped action passport (returns ``{token, jwks_uri}``)."""
+        return self._post(
+            "/api/v1/passports/issue",
+            {
+                "audience": audience,
+                "agent_id": self.agent_id,
+                "goal": goal,
+                "allowed_tools": allowed_tools,
+                "allowed_resources": allowed_resources or [],
+                "resource_constraints": resource_constraints or {},
+                "user_id": user_id,
+                "risk_tier": risk_tier,
+                "ttl_seconds": ttl_seconds,
+            },
+        )
+
+    def verify_passport(
+        self,
+        token: str,
+        audience: str,
+        agent_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        current_tool_manifest_hash: Optional[str] = None,
+        policy_hash: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Verify a passport (returns ``{valid, errors}``)."""
+        return self._post(
+            "/api/v1/passports/verify",
+            {
+                "token": token,
+                "audience": audience,
+                "agent_id": agent_id,
+                "user_id": user_id,
+                "current_tool_manifest_hash": current_tool_manifest_hash,
+                "policy_hash": policy_hash,
+            },
+        )
+
+    def revoke_passport(self, jti: str, reason: Optional[str] = None) -> Dict[str, Any]:
+        """Revoke a passport by its ``jti`` (returns ``{revoked}``)."""
+        return self._post("/api/v1/passports/revoke", {"jti": jti, "reason": reason})
+
+    def record_evidence(
+        self,
+        event_type: str,
+        chain_id: str,
+        tool_id: Optional[str] = None,
+        decision: Optional[str] = None,
+        reason_code: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        request_hash: Optional[str] = None,
+        response_hash: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Append an event to a tamper-evident evidence chain.
+
+        Returns ``{event_id, current_event_hash}``.
+        """
+        return self._post(
+            "/api/v1/evidence/events",
+            {
+                "event_type": event_type,
+                "chain_id": chain_id,
+                "tool_id": tool_id,
+                "decision": decision,
+                "reason_code": reason_code,
+                "metadata": metadata,
+                "request_hash": request_hash,
+                "response_hash": response_hash,
+            },
+        )
+
+    # ------------------------------------------------------------------ #
+    # Local helpers (stdlib hashing — no network, mirror TS canonical hashing)
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def hash_payload(payload: Any) -> str:
+        """SHA-256 of a canonical (sorted-key) JSON encoding of ``payload``.
+
+        Useful for ``request_hash`` / ``response_hash`` on evidence events.
+        """
+        canonical = json.dumps(
+            payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+        ).encode("utf-8")
+        return hashlib.sha256(canonical).hexdigest()
+
+    @staticmethod
+    def sign_payload(secret: str, payload: Any) -> str:
+        """HMAC-SHA256 hex signature over a canonical JSON encoding."""
+        canonical = json.dumps(
+            payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+        ).encode("utf-8")
+        return hmac.new(secret.encode("utf-8"), canonical, hashlib.sha256).hexdigest()
+
+
+def create_actpass(
+    api_key: str,
+    tenant_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> ActPassClient:
+    """Convenience factory mirroring the TS ``createActPass`` (spec section 14.2).
+
+    Only ``api_key`` is required: the server resolves tenant + agent from it.
+    """
+    return ActPassClient(
+        api_key=api_key,
+        tenant_id=tenant_id,
+        agent_id=agent_id,
+        base_url=base_url,
+    )

actpass-1.1.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: actpass
+Version: 1.1.0
+Summary: ActPass Python SDK — signed action authorization for AI agents (zero dependencies)
+Project-URL: Homepage, https://app.actpass.org
+Author: ActPass
+License: MIT
+Keywords: agents,ai,authorization,mcp,security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ActPass Python SDK
+
+Zero-dependency (stdlib-only) Python client for the ActPass runtime, mirroring
+the TypeScript `@actpass/sdk` surface (spec §14).
+
+## Install
+
+```bash
+pip install actpass
+```
+
+## Usage (§14.2)
+
+```python
+from actpass import create_actpass
+
+# The API key IS your identity: the server resolves tenant + agent from it.
+client = create_actpass(api_key="sk_...")
+
+# Preflight + guarded execution in one call. execute_fn runs ONLY on allow/warn.
+result = client.guard(
+    goal="resolve_refund_request",
+    tool="stripe.refund.create",
+    resource="stripe:charge:ch_123",
+    args={"chargeId": "ch_123", "amount": 14900, "currency": "USD"},
+    execute_fn=lambda ctx: stripe.Refund.create(charge="ch_123", amount=14900),
+)
+print(result["decision"]["decision"])   # allow | deny | require_approval | ...
+```
+
+Other methods: `preflight()`, `issue_passport()`, `verify_passport()`,
+`revoke_passport()`, `record_evidence()`, plus `hash_payload()` /
+`sign_payload()` helpers for evidence hashing.
+
+## Behavior
+- **Fails closed:** any non-2xx (except 401/403, which return the parsed body)
+  raises `ActPassError`; a network failure raises too. `guard()` only executes
+  your function on `allow`/`warn`.
+- **Tenant is a hint:** sent as `x-actpass-tenant`; the gateway resolves the
+  authoritative tenant from the authenticated principal (§11.2).
+- **Zero dependencies:** `urllib`/`json`/`hmac`/`hashlib` from the stdlib only.
+
+## Test
+
+```bash
+cd packages/sdk-python && python -m unittest discover -s tests
+```

actpass-1.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+actpass/__init__.py,sha256=hohXmKfVGOP0TBUnHWPkruaNMzEDujICT93ZDbnynA8,700
+actpass/client.py,sha256=Zd7xMKGHAKE1BF7h9v7OuToFsviZ3E83YNvlohkBQOM,12752
+actpass-1.1.0.dist-info/METADATA,sha256=Y8XIFzLhEf6TLBAaajtAd25dSKopw3msajgJv9jfLao,1986
+actpass-1.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+actpass-1.1.0.dist-info/RECORD,,

actpass-1.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any