veefore-py 1.1.0__tar.gz

veefore_py-1.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: veefore-py
+Version: 1.1.0
+Summary: VEEFORE SDK for Python agent runtimes.
+Author: VEEFORE
+License: Apache-2.0
+Project-URL: Homepage, https://veefore.com
+Project-URL: Documentation, https://veefore.com/docs/build/python-sdk
+Project-URL: Repository, https://github.com/veefore/veefore
+Keywords: agent,identity,policy,authorization,enforcement
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# veefore-py
+
+Identity, policy and enforcement for AI agents. Every protected tool call is
+decided by the Veefore gateway before your code runs it.
+
+```bash
+pip install veefore-py
+```
+
+The package is `veefore-py`; the module is `veefore`. The quickest way to
+integrate is the CLI, which installs this package with pip, uv or poetry:
+
+```bash
+npm install -g veefore
+veefore              # sign in, scan your project, set it up, wrap your tools
+```
+
+Or by hand:
+
+```python
+from veefore import guard
+
+@tool
+@guard("refund_customer")
+def refund_customer(amount: int) -> str:
+    ...
+```
+
+`@guard` asks Veefore first and runs the function only if the call is
+permitted. A refusal raises `VeeforeBlockedError` (or
+`VeeforeApprovalRequiredError` when a human must decide). Put it directly above
+`def`, below your framework's decorator.
+
+Configuration is read from the environment variables `veefore init` writes to
+`.env.local`. Requires Python 3.9 or newer.

veefore_py-1.1.0/README.md

@@ -0,0 +1,35 @@
+# veefore-py
+
+Identity, policy and enforcement for AI agents. Every protected tool call is
+decided by the Veefore gateway before your code runs it.
+
+```bash
+pip install veefore-py
+```
+
+The package is `veefore-py`; the module is `veefore`. The quickest way to
+integrate is the CLI, which installs this package with pip, uv or poetry:
+
+```bash
+npm install -g veefore
+veefore              # sign in, scan your project, set it up, wrap your tools
+```
+
+Or by hand:
+
+```python
+from veefore import guard
+
+@tool
+@guard("refund_customer")
+def refund_customer(amount: int) -> str:
+    ...
+```
+
+`@guard` asks Veefore first and runs the function only if the call is
+permitted. A refusal raises `VeeforeBlockedError` (or
+`VeeforeApprovalRequiredError` when a human must decide). Put it directly above
+`def`, below your framework's decorator.
+
+Configuration is read from the environment variables `veefore init` writes to
+`.env.local`. Requires Python 3.9 or newer.

veefore_py-1.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "veefore-py"
+version = "1.1.0"
+description = "VEEFORE SDK for Python agent runtimes."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "VEEFORE" }]
+keywords = ["agent", "identity", "policy", "authorization", "enforcement"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+]
+
+# Only the standard library plus `cryptography` for Ed25519. No HTTP client
+# dependency: urllib is used so the SDK cannot conflict with the host app.
+dependencies = ["cryptography>=41.0.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://veefore.com"
+Documentation = "https://veefore.com/docs/build/python-sdk"
+Repository = "https://github.com/veefore/veefore"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# PEP 561: ships the marker that tells mypy and pyright this package's
+# annotations are real, so `guard` keeps its types in a user's project instead
+# of degrading to Any.
+[tool.setuptools.package-data]
+veefore = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

veefore_py-1.1.0/setup.cfg

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

veefore_py-1.1.0/src/veefore/__init__.py

@@ -0,0 +1,73 @@
+"""Veefore SDK for Python.
+
+The SDK is a convenience layer, never a security boundary. Every protected
+action is decided server-side by the gateway on every call. Nothing in this
+package can grant an agent authority it does not already have, and nothing here
+caches a permission.
+
+    from veefore import protect
+
+    agent = protect(my_agent)
+"""
+
+from __future__ import annotations
+
+from .assertion import (
+    ASSERTION_TTL_SECONDS,
+    canonical_json,
+    create_assertion,
+    generate_nonce,
+)
+from .client import SDK_NAME, SDK_VERSION, VeeforeClient
+from .errors import (
+    VeeforeApprovalDeniedError,
+    VeeforeApprovalRequiredError,
+    VeeforeAuthenticationError,
+    VeeforeBlockedError,
+    VeeforeConfigurationError,
+    VeeforeConnectionError,
+    VeeforeError,
+    VeeforeRateLimitError,
+)
+from .models import (
+    ActionDecision,
+    ActionRequest,
+    ApprovalStatus,
+    HandshakeResult,
+    StageResult,
+)
+from .guard import guard, guard_client, reset_guard_client
+from .protect import ProtectedAgent, config_from_env, create_client, protect
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "protect",
+    "guard",
+    "guard_client",
+    "reset_guard_client",
+    "create_client",
+    "config_from_env",
+    "ProtectedAgent",
+    "VeeforeClient",
+    "ActionRequest",
+    "ActionDecision",
+    "ApprovalStatus",
+    "HandshakeResult",
+    "StageResult",
+    "VeeforeError",
+    "VeeforeAuthenticationError",
+    "VeeforeBlockedError",
+    "VeeforeApprovalRequiredError",
+    "VeeforeApprovalDeniedError",
+    "VeeforeConnectionError",
+    "VeeforeConfigurationError",
+    "VeeforeRateLimitError",
+    "create_assertion",
+    "generate_nonce",
+    "canonical_json",
+    "ASSERTION_TTL_SECONDS",
+    "SDK_NAME",
+    "SDK_VERSION",
+    "__version__",
+]

veefore_py-1.1.0/src/veefore/assertion.py

@@ -0,0 +1,119 @@
+"""Agent identity assertions.
+
+A compact JWS (EdDSA / Ed25519) proving possession of the agent's private
+identity key, bound to the agent id, the gateway audience, a single-use nonce
+and a short expiry.
+
+The private key never leaves this module: it is not logged, not placed in a
+request body, and not written to disk.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+from datetime import datetime, timedelta, timezone
+from typing import Any, Optional, Tuple
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .errors import VeeforeConfigurationError
+
+__all__ = ["ASSERTION_TTL_SECONDS", "canonical_json", "create_assertion", "generate_nonce"]
+
+ASSERTION_TTL_SECONDS = 120
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def canonical_json(value: Any) -> str:
+    """RFC 8785-style canonical JSON: sorted keys, no insignificant whitespace.
+
+    Must match the server's canonicalisation byte for byte or signatures fail.
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return json.dumps(value)
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(canonical_json(item) for item in value) + "]"
+    if isinstance(value, dict):
+        items = sorted((k, v) for k, v in value.items() if v is not None)
+        return (
+            "{"
+            + ",".join(
+                f"{json.dumps(k, ensure_ascii=False)}:{canonical_json(v)}" for k, v in items
+            )
+            + "}"
+        )
+    return "null"
+
+
+def generate_nonce() -> str:
+    return secrets.token_urlsafe(18)
+
+
+def _load_private_key(base64_pkcs8: str) -> Ed25519PrivateKey:
+    try:
+        der = base64.b64decode(base64_pkcs8, validate=False)
+        key = serialization.load_der_private_key(der, password=None)
+    except Exception as error:  # noqa: BLE001 - surfaced as a config error
+        raise VeeforeConfigurationError(
+            "The agent private key could not be parsed. "
+            "Expected base64-encoded PKCS#8 Ed25519 material."
+        ) from error
+    if not isinstance(key, Ed25519PrivateKey):
+        raise VeeforeConfigurationError(
+            "The agent private key is not an Ed25519 key. Veefore agent identities use Ed25519."
+        )
+    return key
+
+
+def create_assertion(
+    *,
+    agent_id: str,
+    audience: str,
+    private_key: str,
+    key_id: str,
+    purpose: str = "agent_authentication",
+    nonce: Optional[str] = None,
+    ttl_seconds: int = ASSERTION_TTL_SECONDS,
+    now: Optional[datetime] = None,
+) -> Tuple[str, str]:
+    """Returns ``(assertion, nonce)``."""
+    issued_at = now or datetime.now(timezone.utc)
+    actual_nonce = nonce or generate_nonce()
+
+    header = {"typ": "veefore-assertion+jwt", "alg": "EdDSA", "kid": key_id}
+    payload = {
+        "sub": agent_id,
+        "aud": audience,
+        "purpose": purpose,
+        "nonce": actual_nonce,
+        "iat": _iso(issued_at),
+        "exp": _iso(issued_at + timedelta(seconds=ttl_seconds)),
+    }
+
+    signing_input = (
+        _b64url(json.dumps(header, separators=(",", ":")).encode("utf-8"))
+        + "."
+        + _b64url(canonical_json(payload).encode("utf-8"))
+    )
+    key = _load_private_key(private_key)
+    signature = key.sign(signing_input.encode("ascii"))
+    return f"{signing_input}.{_b64url(signature)}", actual_nonce
+
+
+def _iso(value: datetime) -> str:
+    """ISO-8601 with a trailing ``Z``, matching the server's format."""
+    return value.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace(
+        "+00:00", "Z"
+    )