qerexa 0.1.0__tar.gz

qerexa-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]

qerexa-0.1.0/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.

qerexa-0.1.0/PKG-INFO

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

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

@@ -0,0 +1,65 @@
+[build-system]
+# Keep emitted Core Metadata compatible with the current Twine/PyPI path.
+# Hatchling 1.28+ may emit Metadata-Version 2.5, which Twine 6 rejects.
+requires = ["hatchling>=1.26,<1.28"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qerexa"
+dynamic = ["version"]
+description = "Qerexa clients for verifiable credentials and fail-closed gate checks (preview)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Qerexa" }]
+keywords = ["ai-agents", "governance", "trust", "verifiable-credentials", "autogen"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.28,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1,<2",
+    "pytest>=7",
+    "ruff>=0.1",
+    "twine>=5,<7",
+]
+
+[project.urls]
+Homepage = "https://qerexa.com"
+Documentation = "https://qerexa.com/docs"
+Repository = "https://github.com/rodriguew/Trust-Rails/tree/main/packages/sdk-python"
+Issues = "https://github.com/rodriguew/Trust-Rails/issues"
+
+[tool.hatch.version]
+path = "qerexa/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qerexa"]
+
+[tool.hatch.build.targets.sdist]
+include = ["qerexa", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

qerexa-0.1.0/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-0.1.0/qerexa/_version.py

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

qerexa-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-0.1.0/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-0.1.0/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/tests/test_package.py

@@ -0,0 +1,175 @@
+from datetime import datetime, timedelta, timezone
+from unittest import mock
+
+import pytest
+import requests
+
+import qerexa
+from qerexa import (
+    ExecutionAuthorizationRequiredError,
+    GateBlockedError,
+    QerexaError,
+    QerexaGateMiddleware,
+    QerexaVCClient,
+    VCClientConfig,
+)
+
+
+def _iso(delta_seconds):
+    return (datetime.now(timezone.utc) + timedelta(seconds=delta_seconds)).isoformat()
+
+
+def _response(status, body):
+    response = mock.Mock()
+    response.ok = 200 <= status < 300
+    response.status_code = status
+    if isinstance(body, Exception):
+        response.json.side_effect = body
+    else:
+        response.json.return_value = body
+    return response
+
+
+def _allow(**overrides):
+    body = {
+        "decision": "allowed",
+        "allowed": True,
+        "decision_id": "dec_1",
+        "expires_at": _iso(300),
+        "gates_checked": [],
+    }
+    body.update(overrides)
+    return body
+
+
+def _run_gated(status, body, **gate_kwargs):
+    middleware = QerexaGateMiddleware(api_key="qrx_test")
+    executed = []
+
+    @middleware.gate_check(action="report.export", **gate_kwargs)
+    def export_report(report_id, secret_note=None):
+        executed.append(report_id)
+        return "ok"
+
+    with mock.patch(
+        "qerexa.autogen_middleware.requests.post", return_value=_response(status, body)
+    ) as post:
+        try:
+            result = export_report("rpt_1", secret_note="hunter2")
+        except QerexaError as error:
+            return None, error, executed, post
+    return result, None, executed, post
+
+
+def test_version_is_exposed():
+    assert isinstance(qerexa.__version__, str) and qerexa.__version__
+
+
+def test_direct_unexpired_allow_runs_the_function():
+    result, error, executed, _ = _run_gated(200, _allow())
+    assert error is None and result == "ok" and executed == ["rpt_1"]
+
+
+@pytest.mark.parametrize(
+    "status, body",
+    [
+        (200, _allow(expires_at=_iso(-1))),  # expired
+        (200, _allow(expires_at=None)),  # no expiry
+        (200, _allow(expires_at="2999-01-01T00:00:00")),  # no timezone
+        (200, _allow(expires_at="not-a-date")),
+        (200, _allow(allowed="true")),  # truthy but not True
+        (200, _allow(decision="approval_required")),
+        (200, _allow(decision_id="")),
+        (201, _allow()),  # allow body on an unexpected status
+        (200, ["allowed"]),  # not an object
+        (200, ValueError("not json")),
+    ],
+)
+def test_anything_but_a_valid_direct_allow_is_blocked(status, body):
+    _, error, executed, _ = _run_gated(status, body)
+    assert isinstance(error, GateBlockedError)
+    assert executed == []
+
+
+def test_blocked_decision_reports_the_failed_gate():
+    body = {
+        "decision": "blocked",
+        "allowed": False,
+        "decision_id": "dec_2",
+        "gates_checked": [{"gate": "hipaa", "status": "failed", "reason": "phi detected"}],
+    }
+    _, error, executed, _ = _run_gated(403, body)
+    assert isinstance(error, GateBlockedError)
+    assert error.reason == "phi detected" and error.decision_id == "dec_2"
+    assert executed == []
+
+
+def test_review_required_never_runs_the_function():
+    body = {
+        "decision": "approval_required",
+        "allowed": False,
+        "decision_id": "dec_3",
+        "flow_id": "flow_1",
+        "gates_checked": [],
+    }
+    _, error, executed, _ = _run_gated(202, body)
+    assert isinstance(error, ExecutionAuthorizationRequiredError)
+    assert error.flow_id == "flow_1"
+    assert executed == []
+
+
+def test_network_failure_fails_closed():
+    middleware = QerexaGateMiddleware(api_key="qrx_test")
+    executed = []
+
+    @middleware.gate_check(action="report.export")
+    def export_report():
+        executed.append(True)
+
+    with mock.patch(
+        "qerexa.autogen_middleware.requests.post",
+        side_effect=requests.ConnectionError("down"),
+    ):
+        with pytest.raises(QerexaError):
+            export_report()
+    assert executed == []
+
+
+def test_function_arguments_are_never_sent():
+    _, _, _, post = _run_gated(200, _allow())
+    sent = post.call_args.kwargs["json"]
+    assert "rpt_1" not in str(sent) and "hunter2" not in str(sent)
+    assert sent["reasoning"] == "Function call: export_report"
+    assert post.call_args.kwargs["timeout"] == 10.0
+
+
+def test_explicit_reasoning_is_used():
+    _, _, _, post = _run_gated(200, _allow(), reasoning="Monthly export")
+    assert post.call_args.kwargs["json"]["reasoning"] == "Monthly export"
+
+
+def test_vc_client_sends_bearer_and_org_headers():
+    client = QerexaVCClient(VCClientConfig(org_id="org_1", api_key="qrx_test"))
+    assert client.session.headers["Authorization"] == "Bearer qrx_test"
+    assert client.session.headers["x-org-id"] == "org_1"
+
+
+def test_vc_client_rejects_empty_federation_domains():
+    client = QerexaVCClient(VCClientConfig(org_id="org_1", api_key="qrx_test"))
+    with pytest.raises(ValueError):
+        client.generate_federation_token("org_2", "member_1", domains=[])
+
+
+def test_vc_client_quotes_path_parameters_and_sets_timeout():
+    client = QerexaVCClient(VCClientConfig(org_id="org_1", api_key="qrx_test", timeout=3))
+    with mock.patch.object(client.session, "post", return_value=_response(200, {})) as post:
+        client.revoke_credential("a/b")
+    assert post.call_args.args[0].endswith("/api/v1/vc/a%2Fb/revoke")
+    assert post.call_args.kwargs["timeout"] == 3
+
+
+def test_vc_client_wraps_transport_errors():
+    client = QerexaVCClient(VCClientConfig(org_id="org_1", api_key="qrx_test"))
+    with mock.patch.object(client.session, "get", side_effect=requests.ConnectionError("down")):
+        with pytest.raises(QerexaError):
+            client.list_trust_relationships()