vengtoo 0.1.0__tar.gz

vengtoo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vengtoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vengtoo-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: vengtoo
+Version: 0.1.0
+Summary: Vengtoo Python SDK — authorization client for Vengtoo Cloud and the Vengtoo Agent
+Author-email: Vengtoo <hello@vengtoo.com>
+License: MIT
+Project-URL: Homepage, https://vengtoo.com
+Project-URL: Documentation, https://docs.vengtoo.com
+Project-URL: Repository, https://github.com/vengtoo/vengtoo-python
+Project-URL: Issues, https://github.com/vengtoo/vengtoo-python/issues
+Keywords: authorization,vengtoo,rbac,abac,access-control,ai-agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Dynamic: license-file
+
+# Vengtoo Python SDK
+
+Python client for [Vengtoo](https://vengtoo.com) — works with both Vengtoo Cloud and the Vengtoo Agent.
+
+Supports sync and async. Requires Python 3.9+.
+
+## Install
+
+```bash
+pip install vengtoo
+```
+
+## Usage
+
+### Cloud Mode
+
+```python
+from vengtoo import Vengtoo, Subject, Resource
+
+client = Vengtoo(api_key="azx_...")
+
+allowed = client.check(
+    subject=Subject(id="user:123", type="user", roles=["editor"]),
+    action="read",
+    resource=Resource(type="document", id="doc:456"),
+)
+```
+
+### OAuth2 Client Credentials
+
+For service-to-service auth, pass `client_id` and `client_secret` (secret is prefixed `azx_cs_`). The SDK exchanges credentials at the token endpoint, caches the JWT in memory, and refreshes ~60s before expiry. Both sync and async calls share the same cache.
+
+```python
+client = Vengtoo(
+    client_id="my-client-id",
+    client_secret="azx_cs_...",
+)
+```
+
+Equivalent curl for the underlying token exchange:
+
+```bash
+curl -X POST https://api.vengtoo.com/identity-srv/v1/oauth/token \
+  -d grant_type=client_credentials \
+  -d client_id=my-client-id \
+  -d client_secret=azx_cs_...
+```
+
+Providing both `api_key` and OAuth credentials is rejected at construction. A bad `client_id` / `client_secret` surfaces as `VengtooOAuthError` (distinct from `VengtooError`) with a message pointing you at the OAuth exchange.
+
+### Agent Mode (local)
+
+```python
+client = Vengtoo(base_url="http://localhost:8181")
+```
+
+### Full Evaluate Response
+
+```python
+from vengtoo import AuthorizeRequest, Action
+
+resp = client.authorize(AuthorizeRequest(
+    subject=Subject(id="user:123", type="user"),
+    resource=Resource(type="document", id="doc:456"),
+    action=Action(name="read"),
+    context={"ip": "10.0.0.1"},
+))
+# resp.decision, resp.context.reason, resp.context.policy_id, resp.context.access_path
+```
+
+### Async
+
+```python
+allowed = await client.async_check(
+    subject=Subject(id="user:123", type="user"),
+    action="read",
+    resource=Resource(type="document", id="doc:456"),
+)
+
+resp = await client.async_authorize(request)
+```
+
+### FastAPI Dependency
+
+```python
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
+vengtoo = Vengtoo(api_key="azx_...")
+
+@app.get("/documents/{id}")
+async def get_doc(id: str, _=Depends(vengtoo.require("document", "read"))):
+    return {"id": id}
+```
+
+The `require()` dependency extracts subject ID from the `X-User-ID` header by default. Customize with:
+
+```python
+vengtoo.require("document", "read", subject_header="authorization-user-id")
+```
+
+### Options
+
+```python
+Vengtoo(
+    api_key="azx_...",                    # API key for cloud mode
+    base_url="http://localhost:8181",          # Custom URL (agent mode)
+    timeout=5.0,                               # Request timeout in seconds (default: 10)
+)
+```
+
+## Types
+
+| Type                | Fields                                              |
+| ------------------- | --------------------------------------------------- |
+| `Subject`           | `id`, `type`, `attributes`, `properties`, `roles`   |
+| `Resource`          | `id`, `type`, `attributes`, `properties`            |
+| `Action`            | `name`, `properties`                                |
+| `AuthorizeRequest`  | `subject`, `resource`, `action`, `context`          |
+| `AuthorizeContext`  | `reason`, `reason_code`, `policy_id`, `access_path` |
+| `AuthorizeResponse` | `decision`, `context`                               |

vengtoo-0.1.0/README.md

@@ -0,0 +1,121 @@
+# Vengtoo Python SDK
+
+Python client for [Vengtoo](https://vengtoo.com) — works with both Vengtoo Cloud and the Vengtoo Agent.
+
+Supports sync and async. Requires Python 3.9+.
+
+## Install
+
+```bash
+pip install vengtoo
+```
+
+## Usage
+
+### Cloud Mode
+
+```python
+from vengtoo import Vengtoo, Subject, Resource
+
+client = Vengtoo(api_key="azx_...")
+
+allowed = client.check(
+    subject=Subject(id="user:123", type="user", roles=["editor"]),
+    action="read",
+    resource=Resource(type="document", id="doc:456"),
+)
+```
+
+### OAuth2 Client Credentials
+
+For service-to-service auth, pass `client_id` and `client_secret` (secret is prefixed `azx_cs_`). The SDK exchanges credentials at the token endpoint, caches the JWT in memory, and refreshes ~60s before expiry. Both sync and async calls share the same cache.
+
+```python
+client = Vengtoo(
+    client_id="my-client-id",
+    client_secret="azx_cs_...",
+)
+```
+
+Equivalent curl for the underlying token exchange:
+
+```bash
+curl -X POST https://api.vengtoo.com/identity-srv/v1/oauth/token \
+  -d grant_type=client_credentials \
+  -d client_id=my-client-id \
+  -d client_secret=azx_cs_...
+```
+
+Providing both `api_key` and OAuth credentials is rejected at construction. A bad `client_id` / `client_secret` surfaces as `VengtooOAuthError` (distinct from `VengtooError`) with a message pointing you at the OAuth exchange.
+
+### Agent Mode (local)
+
+```python
+client = Vengtoo(base_url="http://localhost:8181")
+```
+
+### Full Evaluate Response
+
+```python
+from vengtoo import AuthorizeRequest, Action
+
+resp = client.authorize(AuthorizeRequest(
+    subject=Subject(id="user:123", type="user"),
+    resource=Resource(type="document", id="doc:456"),
+    action=Action(name="read"),
+    context={"ip": "10.0.0.1"},
+))
+# resp.decision, resp.context.reason, resp.context.policy_id, resp.context.access_path
+```
+
+### Async
+
+```python
+allowed = await client.async_check(
+    subject=Subject(id="user:123", type="user"),
+    action="read",
+    resource=Resource(type="document", id="doc:456"),
+)
+
+resp = await client.async_authorize(request)
+```
+
+### FastAPI Dependency
+
+```python
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
+vengtoo = Vengtoo(api_key="azx_...")
+
+@app.get("/documents/{id}")
+async def get_doc(id: str, _=Depends(vengtoo.require("document", "read"))):
+    return {"id": id}
+```
+
+The `require()` dependency extracts subject ID from the `X-User-ID` header by default. Customize with:
+
+```python
+vengtoo.require("document", "read", subject_header="authorization-user-id")
+```
+
+### Options
+
+```python
+Vengtoo(
+    api_key="azx_...",                    # API key for cloud mode
+    base_url="http://localhost:8181",          # Custom URL (agent mode)
+    timeout=5.0,                               # Request timeout in seconds (default: 10)
+)
+```
+
+## Types
+
+| Type                | Fields                                              |
+| ------------------- | --------------------------------------------------- |
+| `Subject`           | `id`, `type`, `attributes`, `properties`, `roles`   |
+| `Resource`          | `id`, `type`, `attributes`, `properties`            |
+| `Action`            | `name`, `properties`                                |
+| `AuthorizeRequest`  | `subject`, `resource`, `action`, `context`          |
+| `AuthorizeContext`  | `reason`, `reason_code`, `policy_id`, `access_path` |
+| `AuthorizeResponse` | `decision`, `context`                               |

vengtoo-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vengtoo"
+version = "0.1.0"
+description = "Vengtoo Python SDK — authorization client for Vengtoo Cloud and the Vengtoo Agent"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+keywords = ["authorization", "vengtoo", "rbac", "abac", "access-control", "ai-agents"]
+authors = [{name = "Vengtoo", email = "hello@vengtoo.com"}]
+dependencies = ["httpx>=0.25.0"]
+
+[project.urls]
+Homepage = "https://vengtoo.com"
+Documentation = "https://docs.vengtoo.com"
+Repository = "https://github.com/vengtoo/vengtoo-python"
+Issues = "https://github.com/vengtoo/vengtoo-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "respx"]
+
+[tool.setuptools.packages.find]
+include = ["vengtoo*"]

vengtoo-0.1.0/setup.cfg

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

vengtoo-0.1.0/tests/test_client.py

@@ -0,0 +1,150 @@
+import json
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import threading
+
+import pytest
+
+from vengtoo import Vengtoo, Subject, Resource, Action, AuthorizeRequest, VengtooError
+
+
+class MockHandler(BaseHTTPRequestHandler):
+    response_data = {"decision": True, "context": {"reason": "ok"}}
+    status_code = 200
+    call_count = 0
+
+    def do_POST(self):
+        MockHandler.call_count += 1
+        content_length = int(self.headers.get("Content-Length", 0))
+        self.rfile.read(content_length)
+
+        self.send_response(self.status_code)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(self.response_data).encode())
+
+    def log_message(self, format, *args):
+        pass  # suppress logs
+
+
+@pytest.fixture
+def mock_server():
+    MockHandler.call_count = 0
+    MockHandler.status_code = 200
+    MockHandler.response_data = {"decision": True, "context": {"reason": "ok"}}
+
+    server = HTTPServer(("127.0.0.1", 0), MockHandler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever)
+    thread.daemon = True
+    thread.start()
+    yield f"http://127.0.0.1:{port}"
+    server.shutdown()
+
+
+def test_check_allowed(mock_server):
+    MockHandler.response_data = {"decision": True, "context": {"reason": "role_match"}}
+    client = Vengtoo(api_key="test-key", base_url=mock_server)
+    allowed = client.check(
+        subject=Subject(id="user-1"),
+        action="read",
+        resource=Resource(id="doc-1"),
+    )
+    assert allowed is True
+
+
+def test_check_denied(mock_server):
+    MockHandler.response_data = {"decision": False, "context": {"reason": "no policy"}}
+    client = Vengtoo(api_key="test-key", base_url=mock_server)
+    allowed = client.check(
+        subject=Subject(id="user-1"),
+        action="delete",
+        resource=Resource(id="doc-1"),
+    )
+    assert allowed is False
+
+
+def test_authorize_full_response(mock_server):
+    MockHandler.response_data = {
+        "decision": True,
+        "context": {
+            "reason": "direct_access",
+            "policy_id": "pol-123",
+            "access_path": "direct",
+        },
+    }
+    client = Vengtoo(api_key="test-key", base_url=mock_server)
+    resp = client.authorize(AuthorizeRequest(
+        subject=Subject(id="user-1"),
+        resource=Resource(id="doc-1"),
+        action=Action(name="read"),
+    ))
+    assert resp.decision is True
+    assert resp.context is not None
+    assert resp.context.policy_id == "pol-123"
+    assert resp.context.access_path == "direct"
+
+
+def test_auth_error(mock_server):
+    MockHandler.status_code = 401
+    MockHandler.response_data = "invalid key"
+    client = Vengtoo(api_key="bad-key", base_url=mock_server)
+    with pytest.raises(VengtooError) as exc_info:
+        client.check(subject=Subject(id="user-1"), action="read", resource=Resource(id="doc-1"))
+    assert exc_info.value.status_code == 401
+    assert exc_info.value.is_auth_error
+
+
+def test_retry_on_500(mock_server):
+    call_sequence = [0]
+
+    original_handler = MockHandler.do_POST
+
+    def custom_handler(self):
+        content_length = int(self.headers.get("Content-Length", 0))
+        self.rfile.read(content_length)
+        call_sequence[0] += 1
+        if call_sequence[0] < 3:
+            body = json.dumps({"error": "internal"}).encode()
+            self.send_response(500)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+            return
+        body = json.dumps({"decision": True, "context": {"reason": "ok"}}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    MockHandler.do_POST = custom_handler
+    try:
+        client = Vengtoo(api_key="test-key", base_url=mock_server, max_retries=2)
+        allowed = client.check(subject=Subject(id="user-1"), action="read", resource=Resource(id="doc-1"))
+        assert allowed is True
+        assert call_sequence[0] == 3
+    finally:
+        MockHandler.do_POST = original_handler
+
+
+def test_no_retry_on_400(mock_server):
+    MockHandler.status_code = 400
+    MockHandler.call_count = 0
+    client = Vengtoo(api_key="test-key", base_url=mock_server)
+    with pytest.raises(VengtooError) as exc_info:
+        client.check(subject=Subject(id="user-1"), action="read", resource=Resource(id="doc-1"))
+    assert exc_info.value.status_code == 400
+    assert MockHandler.call_count == 1
+
+
+def test_subject_type_optional():
+    s = Subject(id="user-1")
+    d = s.to_dict()
+    assert "type" not in d
+
+
+def test_resource_type_optional():
+    r = Resource(id="doc-1")
+    d = r.to_dict()
+    assert "type" not in d

vengtoo-0.1.0/tests/test_oauth.py

@@ -0,0 +1,231 @@
+"""OAuth2 Client Credentials tests for the Vengtoo Python SDK."""
+
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs
+
+import pytest
+
+from vengtoo import (
+    Vengtoo,
+    VengtooError,
+    VengtooOAuthError,
+    Resource,
+    Subject,
+)
+
+
+class _State:
+    """Mutable state shared between the test and the mock server handler."""
+
+    token_calls: int = 0
+    api_calls: int = 0
+    # Token endpoint behavior
+    token_status: int = 200
+    token_body: dict | str = {"access_token": "tok-1", "token_type": "Bearer", "expires_in": 3600}
+    # Per-call token generation (overrides token_body when set)
+    token_sequence: list[dict] | None = None
+    # API behavior — either a dict (fixed response), or a callable
+    # (auth_header: str) -> tuple[int, dict].
+    api_responder = None
+    # Record the Authorization header seen on the last API call.
+    last_api_auth: str = ""
+    # Record the last token form body
+    last_token_form: dict[str, list[str]] | None = None
+
+
+def _reset_state() -> None:
+    _State.token_calls = 0
+    _State.api_calls = 0
+    _State.token_status = 200
+    _State.token_body = {"access_token": "tok-1", "token_type": "Bearer", "expires_in": 3600}
+    _State.token_sequence = None
+    _State.api_responder = None
+    _State.last_api_auth = ""
+    _State.last_token_form = None
+
+
+class _OAuthHandler(BaseHTTPRequestHandler):
+    def log_message(self, fmt, *args):  # noqa: D401
+        pass
+
+    def do_POST(self):  # noqa: N802
+        length = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(length)
+
+        if self.path == "/oauth/token":
+            _State.token_calls += 1
+            _State.last_token_form = parse_qs(raw.decode())
+            if _State.token_sequence:
+                body = _State.token_sequence[min(_State.token_calls - 1, len(_State.token_sequence) - 1)]
+                status = 200
+            else:
+                body = _State.token_body
+                status = _State.token_status
+            payload = json.dumps(body).encode() if isinstance(body, dict) else body.encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+            return
+
+        # API path
+        _State.api_calls += 1
+        auth_header = self.headers.get("Authorization", "")
+        _State.last_api_auth = auth_header
+        responder = _State.api_responder
+        if responder is not None:
+            status, body = responder(auth_header)
+        else:
+            status, body = 200, {"decision": True, "context": {"reason": "ok"}}
+        payload = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+
+@pytest.fixture
+def oauth_server():
+    _reset_state()
+    server = HTTPServer(("127.0.0.1", 0), _OAuthHandler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base = f"http://127.0.0.1:{port}"
+    yield {"base_url": base, "token_url": f"{base}/oauth/token"}
+    server.shutdown()
+
+
+def test_oauth_token_exchange_happy_path(oauth_server):
+    client = Vengtoo(
+        client_id="cid",
+        client_secret="azx_cs_secret",
+        base_url=oauth_server["base_url"],
+        token_url=oauth_server["token_url"],
+    )
+    allowed = client.check(
+        subject=Subject(id="u-1"),
+        action="read",
+        resource=Resource(id="d-1"),
+    )
+    assert allowed is True
+    assert _State.token_calls == 1
+    assert _State.api_calls == 1
+    assert _State.last_api_auth == "Bearer tok-1"
+    assert _State.last_token_form is not None
+    assert _State.last_token_form.get("grant_type") == ["client_credentials"]
+    assert _State.last_token_form.get("client_id") == ["cid"]
+    assert _State.last_token_form.get("client_secret") == ["azx_cs_secret"]
+
+
+def test_oauth_invalid_client_clear_error(oauth_server):
+    _State.token_status = 401
+    _State.token_body = {"error": "invalid_client"}
+
+    client = Vengtoo(
+        client_id="cid",
+        client_secret="azx_cs_wrong",
+        base_url=oauth_server["base_url"],
+        token_url=oauth_server["token_url"],
+    )
+    with pytest.raises(VengtooOAuthError) as exc_info:
+        client.check(
+            subject=Subject(id="u-1"),
+            action="read",
+            resource=Resource(id="d-1"),
+        )
+    assert "check client_id/client_secret" in str(exc_info.value)
+    assert exc_info.value.code == "invalid_client"
+    assert _State.api_calls == 0, "API should not be called on token exchange failure"
+
+
+def test_oauth_cached_token_reused(oauth_server):
+    client = Vengtoo(
+        client_id="cid",
+        client_secret="azx_cs_secret",
+        base_url=oauth_server["base_url"],
+        token_url=oauth_server["token_url"],
+    )
+    for _ in range(3):
+        client.check(
+            subject=Subject(id="u-1"),
+            action="read",
+            resource=Resource(id="d-1"),
+        )
+    assert _State.token_calls == 1
+    assert _State.api_calls == 3
+
+
+def test_oauth_401_triggers_refresh_and_retry(oauth_server):
+    _State.token_sequence = [
+        {"access_token": "tok-stale", "token_type": "Bearer", "expires_in": 3600},
+        {"access_token": "tok-fresh", "token_type": "Bearer", "expires_in": 3600},
+    ]
+
+    def responder(auth_header: str):
+        if auth_header == "Bearer tok-stale":
+            return 401, {"error": "stale"}
+        return 200, {"decision": True, "context": {"reason": "ok"}}
+
+    _State.api_responder = responder
+
+    client = Vengtoo(
+        client_id="cid",
+        client_secret="azx_cs_secret",
+        base_url=oauth_server["base_url"],
+        token_url=oauth_server["token_url"],
+    )
+    allowed = client.check(
+        subject=Subject(id="u-1"),
+        action="read",
+        resource=Resource(id="d-1"),
+    )
+    assert allowed is True
+    assert _State.token_calls == 2, "expected initial + refresh"
+    assert _State.api_calls == 2, "expected 401 + retry"
+
+
+def test_oauth_401_retry_only_once(oauth_server):
+    def responder(auth_header: str):
+        return 401, {"error": "bad token"}
+
+    _State.api_responder = responder
+
+    client = Vengtoo(
+        client_id="cid",
+        client_secret="azx_cs_secret",
+        base_url=oauth_server["base_url"],
+        token_url=oauth_server["token_url"],
+    )
+    with pytest.raises(VengtooError) as exc_info:
+        client.check(
+            subject=Subject(id="u-1"),
+            action="read",
+            resource=Resource(id="d-1"),
+        )
+    assert exc_info.value.status_code == 401
+    # One retry allowed — so 2 API calls total, no infinite loop.
+    assert _State.api_calls == 2
+
+
+def test_oauth_apikey_plus_oauth_is_construction_error():
+    with pytest.raises(ValueError) as exc_info:
+        Vengtoo(
+            api_key="azx_key",
+            client_id="cid",
+            client_secret="azx_cs_secret",
+        )
+    assert "either api_key or OAuth" in str(exc_info.value)
+
+
+def test_oauth_partial_credentials_is_construction_error():
+    with pytest.raises(ValueError):
+        Vengtoo(client_id="cid")  # missing client_secret
+    with pytest.raises(ValueError):
+        Vengtoo(client_secret="azx_cs_secret")  # missing client_id