actpass 1.1.0__tar.gz

actpass-1.1.0/.gitignore

@@ -0,0 +1,83 @@
+
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# Local admin/ops scripts — powerful (reset any password, mint any key, change
+# any plan). Intentionally kept out of version control.
+scripts/reset-password.ts
+scripts/mint-device-key.ts
+scripts/set-plan.ts
+scripts/create-policy.ts
+scripts/stress-test.ts
+
+# dependencies
+node_modules/
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+.vscode
+
+# Docker
+postgres_data/
+.env*.local
+
+# local test files
+test-keys.mjs
+sqlite.db
+supabase-jwks.json
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+
+# E2E suite outputs (regenerable: screenshots, HTML report, run artifacts, auth session)
+/tests/e2e/__screenshots__/
+/tests/e2e/__report__/
+/tests/e2e/__results__/
+/tests/e2e/.auth/
+
+# Local agent/tooling caches (not part of the project)
+.claude/
+.codesight/
+.serena/
+
+# Compiled CLI/SDK output (regenerated by tsc)
+packages/*/dist/
+
+# Generated demo media (~500MB of webm/mp4/wav/png) — regenerated by the demo
+# scripts, not source. Keep out of history.
+scripts/demo-video/
+
+# Browser-tooling scratch from agent sessions (not part of the project)
+.playwright-mcp/
+scripts/demo/.demo-state

actpass-1.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,47 @@
+# 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/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-1.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/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "actpass"
+version = "1.1.0"
+description = "ActPass Python SDK — signed action authorization for AI agents (zero dependencies)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "ActPass" }]
+keywords = ["ai", "agents", "security", "authorization", "mcp"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://app.actpass.org"
+
+[tool.hatch.build.targets.wheel]
+packages = ["actpass"]

actpass-1.1.0/tests/test_client.py

@@ -0,0 +1,85 @@
+"""Unit tests for the ActPass Python SDK (stdlib unittest, HTTP mocked).
+
+Run: python -m unittest discover -s tests
+"""
+import json
+import sys
+import unittest
+from pathlib import Path
+from unittest import mock
+
+# Make the package importable when running from this directory.
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from actpass import ActPassClient, ActPassError, create_actpass, DEFAULT_BASE_URL  # noqa: E402
+
+
+def _client():
+    return create_actpass(api_key="k", tenant_id="1", agent_id="support_agent",
+                          base_url="https://api.test")
+
+
+class TestActPassClient(unittest.TestCase):
+    def test_preflight_posts_expected_body(self):
+        c = _client()
+        captured = {}
+
+        def fake_request(method, path, body):
+            captured["method"] = method
+            captured["path"] = path
+            captured["body"] = body
+            return {"decision": "allow", "reason_code": "ok"}
+
+        with mock.patch.object(ActPassClient, "_request", side_effect=fake_request):
+            res = c.preflight(goal="g", tool="stripe.refund.create", args={"amount": 100})
+
+        self.assertEqual(captured["method"], "POST")
+        self.assertEqual(captured["path"], "/api/v1/actions/preflight")
+        self.assertEqual(captured["body"]["tool"], "stripe.refund.create")
+        self.assertEqual(captured["body"]["agent_id"], "support_agent")
+        self.assertEqual(res["decision"], "allow")
+
+    def test_guard_executes_only_on_allow(self):
+        c = _client()
+        with mock.patch.object(ActPassClient, "preflight", return_value={"decision": "allow"}):
+            out = c.guard(goal="g", tool="t", args={}, execute_fn=lambda ctx: "done")
+        self.assertEqual(out["result"], "done")
+
+    def test_guard_blocks_on_deny(self):
+        c = _client()
+        calls = []
+        with mock.patch.object(ActPassClient, "preflight", return_value={"decision": "deny"}):
+            out = c.guard(goal="g", tool="t", args={}, execute_fn=lambda ctx: calls.append(1))
+        self.assertNotIn("result", out)
+        self.assertEqual(calls, [])  # execute_fn never ran
+
+    def test_hash_payload_is_canonical(self):
+        a = ActPassClient.hash_payload({"b": 1, "a": 2})
+        b = ActPassClient.hash_payload({"a": 2, "b": 1})
+        self.assertEqual(a, b)  # key order independent
+        self.assertEqual(len(a), 64)  # sha256 hex
+
+    def test_sign_payload_deterministic(self):
+        s1 = ActPassClient.sign_payload("secret", {"x": 1})
+        s2 = ActPassClient.sign_payload("secret", {"x": 1})
+        self.assertEqual(s1, s2)
+        self.assertNotEqual(s1, ActPassClient.sign_payload("other", {"x": 1}))
+
+
+class TestDistributionContract(unittest.TestCase):
+    def test_default_base_url_is_canonical(self):
+        # D1: exactly one canonical host, and the client defaults to it.
+        self.assertEqual(DEFAULT_BASE_URL, "https://api.actpass.org")
+        self.assertEqual(ActPassClient(api_key="x").base_url, DEFAULT_BASE_URL)
+
+    def test_api_key_only_construction(self):
+        # D2: no tenant_id / agent_id required; agent_id falls back to 'sdk'.
+        c = create_actpass(api_key="x")
+        self.assertEqual(c.agent_id, "sdk")
+        self.assertIsNone(c.tenant_id)
+        # tenant header omitted when there is no tenant_id.
+        self.assertNotIn("x-actpass-tenant", c._headers(with_content_type=False))
+
+
+if __name__ == "__main__":
+    unittest.main()