veefore-py 1.1.0__py3-none-any.whl

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/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"
+    )