qerexa 0.1.0__py3-none-any.whl

qerexa/__init__.py

@@ -0,0 +1,22 @@
+"""Qerexa Python clients (preview).
+
+``QerexaGateMiddleware`` runs a wrapped function only after a direct,
+unexpired Qerexa ``allowed`` decision. ``QerexaVCClient`` manages verifiable
+credentials, federation tokens, and trust relationships.
+"""
+
+from ._version import __version__
+from .autogen_middleware import QerexaGateMiddleware
+from .gate import ExecutionAuthorizationRequiredError, GateBlockedError, QerexaError
+from .vc_client import QerexaVCClient, VCClientConfig, create_vc_client
+
+__all__ = [
+    "ExecutionAuthorizationRequiredError",
+    "GateBlockedError",
+    "QerexaError",
+    "QerexaGateMiddleware",
+    "QerexaVCClient",
+    "VCClientConfig",
+    "__version__",
+    "create_vc_client",
+]

qerexa/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

qerexa/autogen_middleware.py

@@ -0,0 +1,203 @@
+"""Fail-closed Qerexa gate decorator for AutoGen (or any Python) functions."""
+
+import logging
+from functools import wraps
+from typing import Any, Callable, Dict, Optional, Tuple
+
+import requests
+
+from .gate import QerexaError, enforce, read_string
+
+logger = logging.getLogger("qerexa")
+
+
+class GateEvaluationRequest:
+    """Gate evaluation request payload."""
+
+    def __init__(
+        self,
+        action: str,
+        actor: str,
+        reasoning: str,
+        scope: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        federation_token: Optional[str] = None,
+    ):
+        self.action = action
+        self.actor = actor
+        self.reasoning = reasoning
+        self.scope = scope
+        self.metadata = metadata or {}
+        self.federation_token = federation_token
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = {
+            "action": self.action,
+            "actor": self.actor,
+            "reasoning": self.reasoning,
+            "scope": self.scope,
+            "metadata": self.metadata,
+        }
+        if self.federation_token:
+            result["federation_token"] = self.federation_token
+        return result
+
+
+class QerexaGateMiddleware:
+    """
+    Wraps functions so they run only after a direct, unexpired Qerexa allow.
+
+    ``approval_required`` raises ExecutionAuthorizationRequiredError; blocked,
+    expired, malformed, and failed requests raise GateBlockedError or
+    QerexaError. Function arguments are never sent to Qerexa: the gate sees
+    the action, the function name (or your ``reasoning``), and ``metadata``.
+
+    Usage:
+        middleware = QerexaGateMiddleware(api_key=os.environ["QEREXA_API_KEY"])
+
+        @middleware.gate_check(action="report.export")
+        def export_report(report_id: str) -> str:
+            ...
+
+    The decorator wraps the function itself, so it also guards CrewAI or
+    LangChain tools whose implementation is a plain Python function.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_url: str = "https://api.qerexa.com/api/v1/gates/evaluate",
+        actor: str = "autogen-agent",
+        federation_token: Optional[str] = None,
+        timeout: float = 10.0,
+    ):
+        """
+        Args:
+            api_key: Qerexa API key (Bearer token)
+            api_url: Qerexa Gate API endpoint
+            actor: Actor identifier for gate logs
+            federation_token: Optional federation token for cross-org execution
+            timeout: Request timeout in seconds
+        """
+        self.api_key = api_key
+        self.api_url = api_url
+        self.actor = actor
+        self.federation_token = federation_token
+        self.timeout = timeout
+
+    def _evaluate(
+        self,
+        action: str,
+        reasoning: str,
+        metadata: Optional[Dict[str, Any]],
+        federation_token: Optional[str],
+    ) -> Tuple[int, Any]:
+        request = GateEvaluationRequest(
+            action=action,
+            actor=self.actor,
+            reasoning=reasoning,
+            metadata=metadata or {},
+            federation_token=federation_token or self.federation_token,
+        )
+        try:
+            response = requests.post(
+                self.api_url,
+                json=request.to_dict(),
+                headers={
+                    "Content-Type": "application/json",
+                    "Authorization": f"Bearer {self.api_key}",
+                },
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise QerexaError(f"Failed to reach Qerexa gate for {action}: {exc}") from exc
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        return response.status_code, data
+
+    def evaluate_gate(
+        self,
+        action: str,
+        reasoning: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        federation_token: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Return the raw gate response body without enforcing it.
+
+        Use gate_check() or wrap_function() to enforce the decision.
+
+        Raises:
+            QerexaError: If the API cannot be reached or returns a non-object body
+        """
+        _, data = self._evaluate(action, reasoning, metadata, federation_token)
+        if not isinstance(data, dict):
+            raise QerexaError(f"Qerexa gate returned an invalid response for {action}")
+        return data
+
+    def gate_check(
+        self,
+        action: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        federation_token: Optional[str] = None,
+        reasoning: Optional[str] = None,
+    ):
+        """
+        Decorator that runs the function only after a direct, unexpired allow.
+
+        Args:
+            action: Action being gated (e.g., "report.export")
+            metadata: Custom metadata for the audit trail; do not include secrets
+            federation_token: Optional federation token for cross-org execution
+            reasoning: Why the action is needed; defaults to the function name
+
+        Example:
+            @middleware.gate_check(action="report.export")
+            def export_report(report_id: str) -> str:
+                ...
+        """
+
+        def decorator(func: Callable) -> Callable:
+            @wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                status, data = self._evaluate(
+                    action,
+                    reasoning or f"Function call: {func.__name__}",
+                    metadata or {"function": func.__name__},
+                    federation_token,
+                )
+                try:
+                    enforce(action, status, data)
+                except QerexaError as error:
+                    logger.warning("Qerexa gate stopped %s: %s", func.__name__, error)
+                    raise
+                decision_id = read_string(data.get("decision_id"))
+                logger.info("Qerexa allowed %s (decision_id: %s)", func.__name__, decision_id)
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def wrap_function(
+        self,
+        func: Callable,
+        action: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        federation_token: Optional[str] = None,
+        reasoning: Optional[str] = None,
+    ) -> Callable:
+        """
+        Wrap a function with a gate check at runtime (same rules as gate_check).
+
+        Example:
+            gated_export = middleware.wrap_function(export_report, action="report.export")
+        """
+        return self.gate_check(
+            action=action,
+            metadata=metadata,
+            federation_token=federation_token,
+            reasoning=reasoning,
+        )(func)

qerexa/gate.py

@@ -0,0 +1,103 @@
+"""Gate decision parsing shared by the Qerexa Python helpers.
+
+Only a direct, well-formed, unexpired ``allowed`` decision lets an action run.
+Review approval is never execution authorization. This mirrors the decision
+rules of the ``qerexa-langchain`` client.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Any, Optional
+
+
+class QerexaError(Exception):
+    """Base error for Qerexa SDK failures. The guarded action did not run."""
+
+
+class GateBlockedError(QerexaError):
+    """The gate blocked the action, or the response was not a valid allow."""
+
+    def __init__(self, action: str, reason: str, decision_id: Optional[str] = None):
+        super().__init__(f"Qerexa blocked {action}: {reason}")
+        self.action = action
+        self.reason = reason
+        self.decision_id = decision_id
+
+
+class ExecutionAuthorizationRequiredError(QerexaError):
+    """Human review is required. Approval alone does not authorize execution."""
+
+    def __init__(self, action: str, flow_id: Optional[str], decision_id: Optional[str] = None):
+        super().__init__(
+            f"Qerexa requires review for {action} (flow {flow_id}); review approval is not "
+            "execution authorization, so the action was not run"
+        )
+        self.action = action
+        self.flow_id = flow_id
+        self.decision_id = decision_id
+
+
+def read_string(value: Any) -> Optional[str]:
+    return value if isinstance(value, str) and value else None
+
+
+def _timestamp(value: str) -> float:
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        raise ValueError("timestamp must include a timezone")
+    return parsed.timestamp()
+
+
+def is_direct_allow(status: int, data: Any) -> bool:
+    """True only for HTTP 200 with a complete, unexpired ``allowed`` decision."""
+    if status != 200 or not isinstance(data, dict):
+        return False
+    expires_at = read_string(data.get("expires_at"))
+    if not (
+        data.get("decision") == "allowed"
+        and data.get("allowed") is True
+        and read_string(data.get("decision_id"))
+        and expires_at
+    ):
+        return False
+    try:
+        return _timestamp(expires_at) > time.time()
+    except ValueError:
+        return False
+
+
+def is_review_required(status: int, data: Any) -> bool:
+    return (
+        status == 202
+        and isinstance(data, dict)
+        and data.get("decision") == "approval_required"
+        and data.get("allowed") is False
+        and read_string(data.get("flow_id")) is not None
+    )
+
+
+def block_reason(data: Any, status: int) -> str:
+    if isinstance(data, dict):
+        reason = read_string(data.get("reason")) or read_string(data.get("error"))
+        if reason:
+            return reason
+        gates = data.get("gates_checked")
+        if isinstance(gates, list):
+            for gate in gates:
+                if isinstance(gate, dict) and gate.get("status") == "failed":
+                    detail = read_string(gate.get("reason")) or read_string(gate.get("gate"))
+                    if detail:
+                        return detail
+    return f"no valid allow decision (HTTP {status})"
+
+
+def enforce(action: str, status: int, data: Any) -> None:
+    """Return normally only for a direct allow; otherwise raise."""
+    if is_direct_allow(status, data):
+        return
+    decision_id = read_string(data.get("decision_id")) if isinstance(data, dict) else None
+    if is_review_required(status, data):
+        raise ExecutionAuthorizationRequiredError(action, data["flow_id"], decision_id)
+    raise GateBlockedError(action, block_reason(data, status), decision_id)

qerexa/vc_client.py

@@ -0,0 +1,196 @@
+"""
+WS4 Verifiable Credentials SDK (Python)
+Client for issuing and verifying VCs across organizations
+"""
+
+from typing import Optional, Dict, Any
+from dataclasses import dataclass
+from urllib.parse import quote
+import requests
+
+from .gate import QerexaError
+
+
+@dataclass
+class VCClientConfig:
+    """Configuration for VC Client"""
+    org_id: str
+    api_key: str
+    base_url: str = "https://api.qerexa.com"
+    timeout: float = 10.0
+
+
+class QerexaVCClient:
+    """SDK client for Qerexa Verifiable Credentials"""
+
+    def __init__(self, config: VCClientConfig):
+        self.org_id = config.org_id
+        self.api_key = config.api_key
+        self.base_url = config.base_url
+        self.timeout = config.timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            "x-org-id": self.org_id,
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        })
+
+    def issue_competence_vc(
+        self,
+        member_id: str,
+        include_reputation: bool = True,
+        include_hardware_key: bool = True,
+        ttl_days: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Issue a competence credential for a member"""
+        payload = {
+            "member_id": member_id,
+            "include_reputation": include_reputation,
+            "include_hardware_key": include_hardware_key,
+        }
+        if ttl_days:
+            payload["ttl_days"] = ttl_days
+
+        return self._request("POST", "/api/v1/vc/issue/competence", payload)
+
+    def issue_risk_assessment_vc(
+        self,
+        approval_id: str,
+        actor_name: str,
+        action: str,
+        risk_level: str,
+        risk_score: int,
+        approved_by_member_id: str,
+        amount_usd: Optional[int] = None,
+        ttl_days: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Issue a risk assessment credential"""
+        payload = {
+            "approval_id": approval_id,
+            "actor_name": actor_name,
+            "action": action,
+            "risk_level": risk_level,
+            "risk_score": risk_score,
+            "approved_by_member_id": approved_by_member_id,
+        }
+        if amount_usd:
+            payload["amount_usd"] = amount_usd
+        if ttl_days:
+            payload["ttl_days"] = ttl_days
+
+        return self._request("POST", "/api/v1/vc/issue/risk-assessment", payload)
+
+    def generate_federation_token(
+        self,
+        recipient_org_id: str,
+        member_id: str,
+        domains: Optional[list] = None,
+        ttl_hours: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Generate a federation token for cross-org approval"""
+        payload = {
+            "recipient_org_id": recipient_org_id,
+            "member_id": member_id,
+        }
+        if not domains:
+            raise ValueError("domains must contain at least one approved domain")
+        payload["domains"] = domains
+        if ttl_hours:
+            payload["ttl_hours"] = ttl_hours
+
+        return self._request("POST", "/api/v1/federation/tokens", payload)
+
+    def verify_federation_token(self, token: str) -> Dict[str, Any]:
+        """Verify a federation token"""
+        payload = {"token": token}
+        return self._request("POST", "/api/v1/federation/verify", payload)
+
+    def create_trust_relationship(
+        self,
+        trusted_org_id: str,
+        trust_level: str,
+        approved_domains: Optional[list] = None,
+        expires_at: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a trust relationship with another organization"""
+        payload = {
+            "trusted_org_id": trusted_org_id,
+            "trust_level": trust_level,
+        }
+        if not approved_domains:
+            raise ValueError("approved_domains must contain at least one domain")
+        payload["approved_domains"] = approved_domains
+        if expires_at:
+            payload["expires_at"] = expires_at
+
+        return self._request("POST", "/api/v1/trust-relationships", payload)
+
+    def list_trust_relationships(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """List trust relationships"""
+        params = {"limit": limit, "offset": offset}
+        return self._request("GET", "/api/v1/trust-relationships", params=params)
+
+    def list_federation_tokens(
+        self,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """List federation tokens received"""
+        params = {"limit": limit, "offset": offset}
+        return self._request("GET", "/api/v1/federation/tokens", params=params)
+
+    def revoke_federation_token(
+        self, token_jti: str, reason: Optional[str] = None
+    ) -> Dict[str, Any]:
+        payload = {"reason": reason} if reason else {}
+        return self._request(
+            "POST", f"/api/v1/federation/tokens/{quote(token_jti, safe='')}/revoke", payload
+        )
+
+    def revoke_credential(
+        self, credential_id: str, reason: Optional[str] = None
+    ) -> Dict[str, Any]:
+        payload = {"reason": reason} if reason else {}
+        return self._request(
+            "POST", f"/api/v1/vc/{quote(credential_id, safe='')}/revoke", payload
+        )
+
+    def rotate_signing_key(self) -> Dict[str, Any]:
+        return self._request("POST", "/api/v1/vc/keys/rotate", {})
+
+    def revoke_signing_key(self, key_id: str) -> Dict[str, Any]:
+        return self._request(
+            "POST", f"/api/v1/vc/keys/{quote(key_id, safe='')}/revoke", {}
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Make authenticated API request"""
+        url = f"{self.base_url}{path}"
+
+        try:
+            if method == "GET":
+                response = self.session.get(url, params=params, timeout=self.timeout)
+            elif method == "POST":
+                response = self.session.post(url, json=payload, timeout=self.timeout)
+            else:
+                raise ValueError(f"Unsupported HTTP method: {method}")
+
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.RequestException as e:
+            raise QerexaError(f"API Error: {str(e)}") from e
+
+
+def create_vc_client(config: VCClientConfig) -> QerexaVCClient:
+    """Factory function for quick SDK setup"""
+    return QerexaVCClient(config)

qerexa-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: qerexa
+Version: 0.1.0
+Summary: Qerexa clients for verifiable credentials and fail-closed gate checks (preview).
+Project-URL: Homepage, https://qerexa.com
+Project-URL: Documentation, https://qerexa.com/docs
+Project-URL: Repository, https://github.com/rodriguew/Trust-Rails/tree/main/packages/sdk-python
+Project-URL: Issues, https://github.com/rodriguew/Trust-Rails/issues
+Author: Qerexa
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,autogen,governance,trust,verifiable-credentials
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests<3,>=2.28
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: twine<7,>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# qerexa (Python, preview)
+
+Python clients for Qerexa:
+
+- `QerexaGateMiddleware` — decorator that runs a function only after a
+  direct, unexpired Qerexa `allowed` decision. Works for AutoGen functions and
+  any plain Python function, including CrewAI or LangChain tool functions.
+- `QerexaVCClient` — issue and verify verifiable credentials, federation
+  tokens, and trust relationships.
+
+## Install
+
+```bash
+pip install qerexa
+```
+
+## Gate a function
+
+```python
+import os
+from qerexa import (
+    ExecutionAuthorizationRequiredError,
+    GateBlockedError,
+    QerexaGateMiddleware,
+)
+
+gate = QerexaGateMiddleware(api_key=os.environ["QEREXA_API_KEY"])
+
+@gate.gate_check(action="report.export", reasoning="Monthly compliance export")
+def export_report(report_id: str) -> str:
+    ...
+
+try:
+    export_report("rpt_123")
+except ExecutionAuthorizationRequiredError as e:
+    # Human review was requested (flow e.flow_id). Approval of that review does
+    # not authorize this call; stop here or use an action-bound execution flow.
+    ...
+except GateBlockedError as e:
+    ...
+```
+
+The wrapped function runs only for HTTP 200 with `decision: "allowed"`,
+`allowed: true`, a `decision_id`, and a future, timezone-aware `expires_at`.
+Everything else raises and the function does not run: `blocked`,
+`approval_required`, expired or malformed allows, non-JSON responses, and
+network errors (`QerexaError`, the base of both errors above).
+
+Function arguments are never sent. Qerexa receives the action, the actor, the
+`reasoning` you pass (default: the function name), and `metadata`. Do not put
+credentials or customer data in either.
+
+For CrewAI, decorate the function that implements the tool before handing it
+to CrewAI; the gate then runs on every call regardless of CrewAI callbacks.
+
+## Verifiable credentials
+
+```python
+from qerexa import VCClientConfig, create_vc_client
+
+vc = create_vc_client(VCClientConfig(org_id="org_123", api_key=os.environ["QEREXA_API_KEY"]))
+relationships = vc.list_trust_relationships(limit=10)
+```
+
+Requests time out after 10 seconds by default (`VCClientConfig(timeout=...)`).
+
+## Preview limits
+
+This package is not a regulated execution adapter. It does not verify
+receipts, poll or resume review flows, or bind an approval to a specific
+execution. Use the documented API proof flow and an independently reviewed
+execution contract for high-impact actions.
+
+## Development
+
+```bash
+python -m pip install -e "./packages/sdk-python[dev]"
+ruff check packages/sdk-python
+pytest packages/sdk-python
+```
+
+Releases follow [the SDK release runbook](../../apps/sdk/SDK_RELEASE.md).

qerexa-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+qerexa/__init__.py,sha256=imN2Ee8Ds7cb_hSx-uXqABpvITGH6sH8-0IgiRfJBvs,706
+qerexa/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+qerexa/autogen_middleware.py,sha256=j6Q4SjWIrU2d3SbjQXOPjyT4U6cYqRnTT9jarOedyi8,6759
+qerexa/gate.py,sha256=QDD6vtvb4-mWMXo0l_SelA1H2HdmF7IZxOE_1Uzkex0,3658
+qerexa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qerexa/vc_client.py,sha256=6cDxkUgIyIZ8wWhQLRH5DdT5pGSdXNj5EzfNw5yoQtg,6477
+qerexa-0.1.0.dist-info/METADATA,sha256=2hGygqCFiSgbz1XkMhD-KGf_WGsDV9lYFudic539ccE,3942
+qerexa-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+qerexa-0.1.0.dist-info/licenses/LICENSE,sha256=0YvlA1nYl07sp4IyrhL9TGihfDXD8DGDErrrub5ZvZI,1068
+qerexa-0.1.0.dist-info/RECORD,,

qerexa-0.1.0.dist-info/WHEEL

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

qerexa-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qerexa Inc.
+
+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.