reqlo-sdk 0.1.0__tar.gz

reqlo_sdk-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+coverage
+
+# next.js
+.next/
+.next-dev/
+out/
+
+# production
+build
+dist/
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+!.env.example
+
+# turborepo
+.turbo
+
+# fumadocs generated content index
+.source

reqlo_sdk-0.1.0/LICENSE

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

reqlo_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: reqlo-sdk
+Version: 0.1.0
+Summary: Server-side Python client for ReQlo: authorization for AI agents.
+Project-URL: Homepage, https://reqlo.io
+Project-URL: Documentation, https://reqlo-web.vercel.app/docs/sdks/python
+Author: ReQlo
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ReQlo Python SDK
+
+Server-side client for [ReQlo](https://reqlo.io), authorization for AI agents (`pip install reqlo-sdk`, `import reqlo`). Python 3.10+, standard library only,
+sync and asyncio. Keep your project API key on your server.
+
+```bash
+pip install reqlo-sdk
+```
+
+```python
+import os
+from reqlo import Reqlo, ReqloDeniedError
+
+reqlo = Reqlo(api_key=os.environ["REQLO_API_KEY"])
+
+try:
+    reqlo.enforce(
+        agent={"id": "agt_7Hq2mK9xR4vTq8Lp"},
+        subject={"id": session.user_id, "kind": "user"},   # from your verified session
+        action="documents.read",
+        resource={"type": "document", "id": doc.id, "attributes": {"owner_id": doc.owner_id}},
+        context={"document_classification": doc.classification},
+    )
+except ReqloDeniedError as denied:
+    return {"error": "Not allowed", "reason": denied.decision["reason_code"]}
+# Any other ReqloError (timeout, network, HTTP error) propagates: the action does not run.
+```
+
+- `authorize(...)` returns the decision dict; act only when `decision["decision"] == "allow"`.
+- `enforce(...)` returns only on allow and raises `ReqloDeniedError` on deny or `approval_required`.
+- `AsyncReqlo` has the same methods for asyncio.
+- `approvals.list(status=)`, `approvals.retrieve(id)`.
+- `delegations.create(agent_id, subject, actions, expires_at)`, `list`, `retrieve`, `revoke`. Create is never retried.
+- `reqlo.webhooks.verify(body, signature_header, secret)` and `construct_event(...)` check webhook signatures.
+
+Retries `429` and `5xx` twice with backoff (3-second timeout). Timeouts and network errors are never retried and
+never mean allow. Documentation: <https://reqlo-web.vercel.app/docs/sdks/python>

reqlo_sdk-0.1.0/README.md

@@ -0,0 +1,37 @@
+# ReQlo Python SDK
+
+Server-side client for [ReQlo](https://reqlo.io), authorization for AI agents (`pip install reqlo-sdk`, `import reqlo`). Python 3.10+, standard library only,
+sync and asyncio. Keep your project API key on your server.
+
+```bash
+pip install reqlo-sdk
+```
+
+```python
+import os
+from reqlo import Reqlo, ReqloDeniedError
+
+reqlo = Reqlo(api_key=os.environ["REQLO_API_KEY"])
+
+try:
+    reqlo.enforce(
+        agent={"id": "agt_7Hq2mK9xR4vTq8Lp"},
+        subject={"id": session.user_id, "kind": "user"},   # from your verified session
+        action="documents.read",
+        resource={"type": "document", "id": doc.id, "attributes": {"owner_id": doc.owner_id}},
+        context={"document_classification": doc.classification},
+    )
+except ReqloDeniedError as denied:
+    return {"error": "Not allowed", "reason": denied.decision["reason_code"]}
+# Any other ReqloError (timeout, network, HTTP error) propagates: the action does not run.
+```
+
+- `authorize(...)` returns the decision dict; act only when `decision["decision"] == "allow"`.
+- `enforce(...)` returns only on allow and raises `ReqloDeniedError` on deny or `approval_required`.
+- `AsyncReqlo` has the same methods for asyncio.
+- `approvals.list(status=)`, `approvals.retrieve(id)`.
+- `delegations.create(agent_id, subject, actions, expires_at)`, `list`, `retrieve`, `revoke`. Create is never retried.
+- `reqlo.webhooks.verify(body, signature_header, secret)` and `construct_event(...)` check webhook signatures.
+
+Retries `429` and `5xx` twice with backoff (3-second timeout). Timeouts and network errors are never retried and
+never mean allow. Documentation: <https://reqlo-web.vercel.app/docs/sdks/python>

reqlo_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reqlo-sdk"
+version = "0.1.0"
+description = "Server-side Python client for ReQlo: authorization for AI agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+authors = [{ name = "ReQlo" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://reqlo.io"
+Documentation = "https://reqlo-web.vercel.app/docs/sdks/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reqlo"]

reqlo_sdk-0.1.0/src/reqlo/__init__.py

@@ -0,0 +1,10 @@
+"""ReQlo: authorization for AI agents. Server-side client; keep your project API key on your server."""
+from . import webhooks
+from ._client import AsyncReqlo, Reqlo
+from ._errors import (ReqloAPIError, ReqloConfigurationError, ReqloDeniedError, ReqloError, ReqloNetworkError,
+                      ReqloResponseError, ReqloSignatureError, ReqloTimeoutError)
+from ._version import VERSION
+
+__version__ = VERSION
+__all__ = ["Reqlo", "AsyncReqlo", "webhooks", "ReqloError", "ReqloConfigurationError", "ReqloAPIError", "ReqloTimeoutError",
+           "ReqloNetworkError", "ReqloResponseError", "ReqloDeniedError", "ReqloSignatureError", "__version__"]

reqlo_sdk-0.1.0/src/reqlo/_client.py

@@ -0,0 +1,225 @@
+import asyncio
+import json
+import random
+import re
+import socket
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, Dict, List, Optional
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from ._errors import (ReqloAPIError, ReqloConfigurationError, ReqloDeniedError, ReqloError, ReqloNetworkError,
+                      ReqloResponseError, ReqloTimeoutError)
+from ._validate import approval, approval_list, decision, delegation, delegation_list
+from ._version import VERSION
+
+# Only these codes are surfaced; anything else becomes None so response bodies never leak into logs.
+_CODES = {"method_not_allowed", "parameter_invalid", "attribute_invalid", "action_unknown", "request_too_large",
+          "invalid_json", "invalid_request", "api_key_required", "api_key_invalid", "api_key_revoked", "scope_missing",
+          "authentication_required", "user_session_required", "resource_missing", "rate_limited", "internal_error",
+          "service_unavailable"}
+_STATUSES = ("pending", "approved", "rejected", "expired", "consumed")
+_APPROVAL_ID = re.compile(r"^APR_[A-Za-z0-9]{16}$")
+_DELEGATION_ID = re.compile(r"^DEL_[A-Za-z0-9]{16}$")
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:  # never follow redirects with a credential
+        return None
+
+
+def _base_url(value: str) -> str:
+    parts = urlsplit(value)
+    local = parts.scheme == "http" and parts.hostname in ("localhost", "127.0.0.1", "::1")
+    if (parts.scheme != "https" and not local) or parts.username or parts.password or parts.query or parts.fragment \
+            or not re.match(r"^/v1/?$", parts.path or ""):
+        raise ReqloConfigurationError("base_url must be HTTPS with path /v1 and no credentials, query or fragment. "
+                                      "Loopback HTTP is allowed for development.")
+    return "%s://%s/v1" % (parts.scheme, parts.netloc)
+
+
+def _retry_delay(headers: Any, attempt: int) -> Optional[float]:
+    delay = min(5.0, 0.25 * 2 ** attempt * (0.75 + random.random() * 0.5))
+    header = headers.get("Retry-After") if headers is not None else None
+    if header:
+        header = header.strip()
+        try:
+            delay = max(0.0, float(header)) if re.match(r"^\d+(\.\d+)?$", header) else max(0.0, parsedate_to_datetime(header).timestamp() - time.time())
+        except (TypeError, ValueError):
+            pass
+    # Surface the error rather than wait a long, server-directed time.
+    return delay if delay <= 10.0 else None
+
+
+class _Approvals:
+    def __init__(self, client: "Reqlo") -> None:
+        self._client = client
+
+    def list(self, status: Optional[str] = None) -> Dict[str, Any]:
+        """Approvals in the key's environment, newest first: {"data": [...], "environment_id": ...}."""
+        if status is not None and status not in _STATUSES:
+            raise ReqloConfigurationError("status must be one of: %s." % ", ".join(_STATUSES))
+        return approval_list(self._client._request("GET", "/approvals" + ("?status=" + status if status else "")))
+
+    def retrieve(self, approval_id: str) -> Dict[str, Any]:
+        if not isinstance(approval_id, str) or not _APPROVAL_ID.match(approval_id):
+            raise ReqloConfigurationError("Use an approval ID returned by ReQlo.")
+        return approval(self._client._request("GET", "/approvals/" + approval_id))
+
+
+class _Delegations:
+    def __init__(self, client: "Reqlo") -> None:
+        self._client = client
+
+    def create(self, agent_id: str, subject: Dict[str, str], actions: List[str], expires_at: str) -> Dict[str, Any]:
+        """Record a person's grant. Call it from your backend after they consent. Never retried automatically."""
+        if not isinstance(agent_id, str) or not isinstance(subject, dict) or not isinstance(actions, list) or not isinstance(expires_at, str):
+            raise ReqloConfigurationError("Delegations need agent_id, subject, actions and expires_at.")
+        body = {"agent_id": agent_id, "subject": subject, "actions": actions, "expires_at": expires_at}
+        return delegation(self._client._request("POST", "/delegations", body, retry=False))
+
+    def list(self, agent_id: Optional[str] = None, subject_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        query = {k: v for k, v in (("agent_id", agent_id), ("subject_id", subject_id)) if v is not None}
+        return delegation_list(self._client._request("GET", "/delegations" + ("?" + urlencode(query) if query else "")))
+
+    def retrieve(self, delegation_id: str) -> Dict[str, Any]:
+        if not isinstance(delegation_id, str) or not _DELEGATION_ID.match(delegation_id):
+            raise ReqloConfigurationError("Use a delegation ID returned by ReQlo.")
+        return delegation(self._client._request("GET", "/delegations/" + delegation_id))
+
+    def revoke(self, delegation_id: str) -> Dict[str, Any]:
+        if not isinstance(delegation_id, str) or not _DELEGATION_ID.match(delegation_id):
+            raise ReqloConfigurationError("Use a delegation ID returned by ReQlo.")
+        return delegation(self._client._request("POST", "/delegations/%s/revoke" % delegation_id, {}))
+
+
+class Reqlo:
+    """Server-side ReQlo client. Keep the project API key on your server; never ship it to a browser or a prompt."""
+
+    def __init__(self, api_key: str, base_url: str = "https://api.reqlo.io/v1", timeout: float = 3.0, max_retries: int = 2) -> None:
+        if not isinstance(api_key, str) or not re.match(r"^rq_\S+$", api_key):
+            raise ReqloConfigurationError("A secret project API key (rq_...) is required.")
+        if not isinstance(timeout, (int, float)) or isinstance(timeout, bool) or not 0 < timeout <= 120:
+            raise ReqloConfigurationError("timeout must be between 0 and 120 seconds.")
+        if not isinstance(max_retries, int) or isinstance(max_retries, bool) or not 0 <= max_retries <= 5:
+            raise ReqloConfigurationError("max_retries must be between 0 and 5.")
+        self._api_key = api_key
+        self._base_url = _base_url(base_url)
+        self._timeout = float(timeout)
+        self._max_retries = max_retries
+        self._opener = build_opener(_NoRedirect())
+        self.approvals = _Approvals(self)
+        self.delegations = _Delegations(self)
+
+    def __repr__(self) -> str:  # never print the key
+        return "Reqlo(base_url=%r)" % self._base_url
+
+    def authorize(self, *, agent: Dict[str, str], action: str, resource: Dict[str, Any], subject: Optional[Dict[str, str]] = None,
+                  context: Optional[Dict[str, Any]] = None, delegation_id: Optional[str] = None, approval_id: Optional[str] = None) -> Dict[str, Any]:
+        """Returns the decision. Only act when decision["decision"] == "allow"."""
+        body: Dict[str, Any] = {"agent": agent, "action": action, "resource": resource}
+        for key, value in (("subject", subject), ("context", context), ("delegation_id", delegation_id), ("approval_id", approval_id)):
+            if value is not None:
+                body[key] = value
+        return decision(self._request("POST", "/authorize", body))
+
+    def enforce(self, **request: Any) -> Dict[str, Any]:
+        """Returns the decision only on allow. Raises ReqloDeniedError otherwise, and ReqloError on any failure."""
+        result = self.authorize(**request)
+        if result["decision"] != "allow":
+            raise ReqloDeniedError(result)
+        return result
+
+    def _request(self, method: str, path: str, body: Any = None, retry: bool = True) -> Any:
+        try:
+            data = None if body is None else json.dumps(body, allow_nan=False).encode("utf-8")
+        except (TypeError, ValueError):
+            raise ReqloConfigurationError("The request must be JSON serializable.") from None
+        headers = {"Authorization": "Bearer " + self._api_key, "Accept": "application/json", "User-Agent": "reqlo-python/" + VERSION}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            request = Request(self._base_url + path, data=data, method=method, headers=headers)
+            try:
+                with self._opener.open(request, timeout=self._timeout) as response:
+                    raw = response.read()
+                try:
+                    return json.loads(raw)
+                except ValueError:
+                    raise ReqloResponseError() from None
+            except HTTPError as error:
+                status = error.code
+                try:
+                    payload = json.loads(error.read())
+                except Exception:
+                    payload = None
+                finally:
+                    error.close()
+                err = payload.get("error") if isinstance(payload, dict) and isinstance(payload.get("error"), dict) else {}
+                code = err.get("code") if err.get("code") in _CODES else None
+                rid = err.get("request_id") or (error.headers.get("Reqlo-Request-Id") if error.headers else None)
+                rid = rid if isinstance(rid, str) and re.match(r"^[A-Za-z0-9_-]{1,128}$", rid) else None
+                delay = _retry_delay(error.headers, attempt) if retry and (status == 429 or 500 <= status <= 599) and attempt < self._max_retries else None
+                if delay is None:
+                    raise ReqloAPIError(status, code, rid) from None
+                time.sleep(delay)
+                attempt += 1
+            except ReqloError:
+                raise
+            except (socket.timeout, TimeoutError):
+                raise ReqloTimeoutError() from None
+            except URLError as error:
+                if isinstance(error.reason, (socket.timeout, TimeoutError)):
+                    raise ReqloTimeoutError() from None
+                raise ReqloNetworkError() from None
+            except OSError:
+                raise ReqloNetworkError() from None
+
+
+class _AsyncApprovals:
+    def __init__(self, sync: _Approvals) -> None:
+        self._sync = sync
+
+    async def list(self, status: Optional[str] = None) -> Dict[str, Any]:
+        return await asyncio.to_thread(self._sync.list, status)
+
+    async def retrieve(self, approval_id: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(self._sync.retrieve, approval_id)
+
+
+class _AsyncDelegations:
+    def __init__(self, sync: _Delegations) -> None:
+        self._sync = sync
+
+    async def create(self, agent_id: str, subject: Dict[str, str], actions: List[str], expires_at: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(self._sync.create, agent_id, subject, actions, expires_at)
+
+    async def list(self, agent_id: Optional[str] = None, subject_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        return await asyncio.to_thread(self._sync.list, agent_id, subject_id)
+
+    async def retrieve(self, delegation_id: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(self._sync.retrieve, delegation_id)
+
+    async def revoke(self, delegation_id: str) -> Dict[str, Any]:
+        return await asyncio.to_thread(self._sync.revoke, delegation_id)
+
+
+class AsyncReqlo:
+    """The same client for asyncio (FastAPI, agent frameworks). Requests run in a worker thread."""
+
+    def __init__(self, api_key: str, base_url: str = "https://api.reqlo.io/v1", timeout: float = 3.0, max_retries: int = 2) -> None:
+        self._sync = Reqlo(api_key, base_url=base_url, timeout=timeout, max_retries=max_retries)
+        self.approvals = _AsyncApprovals(self._sync.approvals)
+        self.delegations = _AsyncDelegations(self._sync.delegations)
+
+    def __repr__(self) -> str:
+        return "AsyncReqlo(base_url=%r)" % self._sync._base_url
+
+    async def authorize(self, **request: Any) -> Dict[str, Any]:
+        return await asyncio.to_thread(lambda: self._sync.authorize(**request))
+
+    async def enforce(self, **request: Any) -> Dict[str, Any]:
+        return await asyncio.to_thread(lambda: self._sync.enforce(**request))

reqlo_sdk-0.1.0/src/reqlo/_errors.py

@@ -0,0 +1,47 @@
+"""Every error means the protected action must stay stopped. None of them is ever an allow."""
+from typing import Any, Dict, Optional
+
+
+class ReqloError(Exception):
+    """Base class for every ReQlo error."""
+
+
+class ReqloConfigurationError(ReqloError):
+    """Invalid client options or arguments. Fix your code or configuration."""
+
+
+class ReqloAPIError(ReqloError):
+    """ReQlo returned an HTTP error. `code` is a stable error code when ReQlo sent a known one."""
+
+    def __init__(self, status: int, code: Optional[str], request_id: Optional[str]) -> None:
+        super().__init__("ReQlo returned HTTP %d. The protected action must remain stopped." % status)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+
+class ReqloTimeoutError(ReqloError):
+    def __init__(self) -> None:
+        super().__init__("The ReQlo request timed out. The protected action must remain stopped.")
+
+
+class ReqloNetworkError(ReqloError):
+    def __init__(self) -> None:
+        super().__init__("The ReQlo request could not be completed. The protected action must remain stopped.")
+
+
+class ReqloResponseError(ReqloError):
+    def __init__(self) -> None:
+        super().__init__("ReQlo returned an invalid response. The protected action must remain stopped.")
+
+
+class ReqloDeniedError(ReqloError):
+    """`enforce` got deny or approval_required. `decision` holds the full decision."""
+
+    def __init__(self, decision: Dict[str, Any]) -> None:
+        super().__init__("This action requires human approval." if decision.get("decision") == "approval_required" else "This action was denied.")
+        self.decision = decision
+
+
+class ReqloSignatureError(ReqloError):
+    """A webhook's signature is missing, invalid or too old."""

reqlo_sdk-0.1.0/src/reqlo/_validate.py

@@ -0,0 +1,85 @@
+"""Checks every response shape, so a malformed or unexpected response is an error, never an allow."""
+import re
+from datetime import datetime
+from typing import Any, Dict, List
+
+from ._errors import ReqloResponseError
+
+_STATUSES = ("pending", "approved", "rejected", "expired", "consumed")
+
+
+def _text(value: Any) -> bool:
+    return isinstance(value, str) and len(value) > 0
+
+
+def _nullable_text(value: Any) -> bool:
+    return value is None or isinstance(value, str)
+
+
+def _date(value: Any) -> bool:
+    """An ISO 8601 timestamp with date and time, as ReQlo returns (with or without fractions and offset)."""
+    if not isinstance(value, str) or not re.match(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}", value):
+        return False
+    try:
+        datetime.strptime(value[:19], "%Y-%m-%dT%H:%M:%S")
+        return True
+    except ValueError:
+        return False
+
+
+def _approval_id(value: Any) -> bool:
+    return isinstance(value, str) and re.match(r"^APR_[A-Za-z0-9]{16}$", value) is not None
+
+
+def decision(value: Any) -> Dict[str, Any]:
+    if not isinstance(value, dict) or not _text(value.get("id")) or value.get("object") != "decision" or not _text(value.get("reason_code")) \
+            or not isinstance(value.get("matched_rules"), list) or not all(_text(r) for r in value["matched_rules"]) \
+            or not _nullable_text(value.get("policy_version")) or not _text(value.get("environment")) \
+            or not isinstance(value.get("livemode"), bool) or not _date(value.get("created_at")) or not _text(value.get("request_id")):
+        raise ReqloResponseError()
+    if value.get("decision") == "approval_required":
+        a = value.get("approval")
+        if value.get("allowed") is not False or not isinstance(a, dict) or not _approval_id(a.get("id")) or a.get("status") != "pending" or not _date(a.get("expires_at")):
+            raise ReqloResponseError()
+    elif value.get("decision") not in ("allow", "deny") or value.get("allowed") is not (value["decision"] == "allow") or value.get("approval") is not None:
+        raise ReqloResponseError()
+    return value
+
+
+def approval(value: Any) -> Dict[str, Any]:
+    summary = value.get("summary") if isinstance(value, dict) else None
+    if not isinstance(value, dict) or not _approval_id(value.get("id")) or value.get("object") != "approval" or value.get("status") not in _STATUSES \
+            or not _nullable_text(value.get("decision_id")) or not isinstance(value.get("request_digest"), str) \
+            or not re.match(r"^sha256:[a-f0-9]{64}$", value["request_digest"]) \
+            or not isinstance(summary, dict) or not all(summary.get(k) is None or _text(summary.get(k)) for k in ("agent_id", "subject_id", "action", "resource")) \
+            or not _nullable_text(value.get("channel_id")) or not _date(value.get("expires_at")) or not _nullable_text(value.get("resolved_by")) \
+            or not (value.get("resolved_at") is None or _date(value.get("resolved_at"))) or not _nullable_text(value.get("note")) \
+            or not _date(value.get("created_at")):
+        raise ReqloResponseError()
+    return value
+
+
+def approval_list(value: Any) -> Dict[str, Any]:
+    if not isinstance(value, dict) or not isinstance(value.get("data"), list) or not _text(value.get("environment_id")):
+        raise ReqloResponseError()
+    return {"data": [approval(item) for item in value["data"]], "environment_id": value["environment_id"]}
+
+
+def delegation(value: Any) -> Dict[str, Any]:
+    subject = value.get("subject") if isinstance(value, dict) else None
+    verification = value.get("verification") if isinstance(value, dict) else None
+    if not isinstance(value, dict) or not isinstance(value.get("id"), str) or not re.match(r"^DEL_[A-Za-z0-9]{16}$", value["id"]) \
+            or value.get("object") != "delegation" or not _text(value.get("agent_id")) \
+            or not isinstance(subject, dict) or not _text(subject.get("id")) or not _text(subject.get("kind")) \
+            or not isinstance(value.get("actions"), list) or not all(_text(a) for a in value["actions"]) \
+            or not isinstance(verification, dict) or verification.get("method") != "server_session" \
+            or value.get("status") not in ("active", "revoked", "expired") or not _date(value.get("expires_at")) \
+            or not _date(value.get("created_at")) or not (value.get("revoked_at") is None or _date(value.get("revoked_at"))):
+        raise ReqloResponseError()
+    return value
+
+
+def delegation_list(value: Any) -> List[Dict[str, Any]]:
+    if not isinstance(value, dict) or not isinstance(value.get("data"), list):
+        raise ReqloResponseError()
+    return [delegation(item) for item in value["data"]]

reqlo_sdk-0.1.0/src/reqlo/_version.py

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

reqlo_sdk-0.1.0/src/reqlo/webhooks.py

@@ -0,0 +1,39 @@
+"""Verify ReQlo webhook signatures. An event never authorizes an action; it only tells you to look."""
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Dict, Optional, Union
+
+from ._errors import ReqloSignatureError
+
+TOLERANCE_SECONDS = 300
+_HEADER = re.compile(r"^t=(\d{1,12}),v1=([a-f0-9]{64})$")
+_SECRET = re.compile(r"^whsec_[a-f0-9]{64}$")
+
+
+def verify(payload: Union[bytes, str], header: Optional[str], secret: str, tolerance: int = TOLERANCE_SECONDS, now: Optional[int] = None) -> bool:
+    """True only if `header` (Reqlo-Signature) signs the exact raw body with `secret`, within the tolerance."""
+    match = _HEADER.match(header or "")
+    if not match or not isinstance(secret, str) or not _SECRET.match(secret):
+        return False
+    current = int(time.time()) if now is None else now
+    if abs(current - int(match.group(1))) > tolerance:
+        return False
+    body = payload.encode("utf-8") if isinstance(payload, str) else payload
+    expected = hmac.new(secret.encode("utf-8"), match.group(1).encode("ascii") + b"." + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, match.group(2))
+
+
+def construct_event(payload: Union[bytes, str], header: Optional[str], secret: str, tolerance: int = TOLERANCE_SECONDS, now: Optional[int] = None) -> Dict[str, Any]:
+    """Verifies the signature and returns the parsed event. Raises ReqloSignatureError if it isn't valid."""
+    if not verify(payload, header, secret, tolerance, now):
+        raise ReqloSignatureError("The webhook signature is missing, invalid or too old.")
+    try:
+        event = json.loads(payload)
+    except ValueError:
+        raise ReqloSignatureError("The webhook body isn't valid JSON.") from None
+    if not isinstance(event, dict) or event.get("object") != "event" or not isinstance(event.get("type"), str):
+        raise ReqloSignatureError("The webhook body isn't a ReQlo event.")
+    return event

reqlo_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,199 @@
+import asyncio
+import hashlib
+import hmac
+import json
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+import reqlo
+from reqlo import (AsyncReqlo, Reqlo, ReqloAPIError, ReqloConfigurationError, ReqloDeniedError, ReqloNetworkError,
+                   ReqloResponseError, ReqloSignatureError, ReqloTimeoutError, webhooks)
+
+NOW = "2026-11-09T10:42:07.123Z"
+APPROVAL = {"id": "APR_7Hq2mK9xR4vTq8Lp", "object": "approval", "status": "pending", "decision_id": None,
+            "request_digest": "sha256:" + "a" * 64, "summary": {"agent_id": "agt_x", "action": "documents.read"},
+            "channel_id": None, "expires_at": NOW, "resolved_by": None, "resolved_at": None, "note": None, "created_at": NOW}
+DELEGATION = {"id": "DEL_5Hq2mK9xR4vTq8Lp", "object": "delegation", "agent_id": "agt_x", "subject": {"id": "usr_94", "kind": "user"},
+              "actions": ["calendar.schedule"], "verification": {"method": "server_session"}, "status": "active",
+              "expires_at": NOW, "created_at": NOW, "revoked_at": None}
+
+
+def decision(kind):
+    base = {"id": "dec_1", "object": "decision", "decision": kind, "allowed": kind == "allow", "reason_code": "policy_allowed" if kind == "allow" else "policy_denied",
+            "matched_rules": [], "policy_version": "2026-11-09.1", "approval": None, "environment": "sandbox", "livemode": False, "created_at": NOW, "request_id": "r1"}
+    if kind == "approval_required":
+        base.update(reason_code="approval_required", approval={"id": APPROVAL["id"], "status": "pending", "expires_at": NOW})
+    return base
+
+
+class Server:
+    """Queue of (status, body, headers) responses; records every request."""
+
+    def __init__(self):
+        self.queue, self.requests = [], []
+        server = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def handle_any(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                body = json.loads(self.rfile.read(length)) if length else None
+                server.requests.append((self.command, self.path, dict(self.headers), body))
+                status, payload, headers = server.queue.pop(0) if server.queue else (500, {}, {})
+                if status == "sleep":
+                    time.sleep(payload)
+                    status, payload, headers = 200, decision("allow"), {}
+                raw = payload if isinstance(payload, bytes) else json.dumps(payload).encode()
+                self.send_response(status)
+                for key, value in headers.items():
+                    self.send_header(key, value)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(raw)))
+                self.end_headers()
+                self.wfile.write(raw)
+
+            do_GET = do_POST = handle_any
+
+        self.httpd = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=self.httpd.serve_forever, daemon=True).start()
+        self.url = "http://127.0.0.1:%d/v1" % self.httpd.server_port
+
+    def close(self):
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+
+REQUEST = dict(agent={"id": "agt_x"}, action="documents.read", resource={"type": "document", "id": "doc_1"})
+
+
+class ClientTest(unittest.TestCase):
+    def setUp(self):
+        self.server = Server()
+        self.client = Reqlo("rq_test_secret", base_url=self.server.url, max_retries=2)
+
+    def tearDown(self):
+        self.server.close()
+
+    def test_authorize_sends_the_request_and_returns_the_decision(self):
+        self.server.queue.append((200, decision("allow"), {}))
+        result = self.client.authorize(subject={"id": "usr_1", "kind": "user"}, context={"level": 2}, **REQUEST)
+        self.assertEqual(result["decision"], "allow")
+        method, path, headers, body = self.server.requests[0]
+        self.assertEqual((method, path), ("POST", "/v1/authorize"))
+        self.assertEqual(headers["Authorization"], "Bearer rq_test_secret")
+        self.assertEqual(body, {**REQUEST, "subject": {"id": "usr_1", "kind": "user"}, "context": {"level": 2}})
+
+    def test_enforce_returns_on_allow_and_raises_on_deny_or_approval(self):
+        self.server.queue += [(200, decision("allow"), {}), (200, decision("deny"), {}), (200, decision("approval_required"), {})]
+        self.assertEqual(self.client.enforce(**REQUEST)["decision"], "allow")
+        with self.assertRaises(ReqloDeniedError) as denied:
+            self.client.enforce(**REQUEST)
+        self.assertEqual(denied.exception.decision["reason_code"], "policy_denied")
+        with self.assertRaises(ReqloDeniedError) as held:
+            self.client.enforce(**REQUEST)
+        self.assertEqual(held.exception.decision["approval"]["id"], APPROVAL["id"])
+
+    def test_malformed_or_contradictory_responses_are_errors_not_allows(self):
+        bad = [{"decision": "allow"}, {**decision("allow"), "allowed": False}, {**decision("deny"), "allowed": True},
+               {**decision("allow"), "decision": "maybe"}, b"not json"]
+        for body in bad:
+            self.server.queue.append((200, body, {}))
+            with self.assertRaises(ReqloResponseError):
+                self.client.enforce(**REQUEST)
+
+    def test_retries_429_and_5xx_then_raises_with_code_and_request_id(self):
+        self.server.queue += [(503, {"error": {"code": "service_unavailable", "request_id": "r9"}}, {"Retry-After": "0"})] * 3
+        with self.assertRaises(ReqloAPIError) as error:
+            self.client.authorize(**REQUEST)
+        self.assertEqual((error.exception.status, error.exception.code, error.exception.request_id), (503, "service_unavailable", "r9"))
+        self.assertEqual(len(self.server.requests), 3)
+
+    def test_4xx_is_not_retried_and_unknown_codes_are_hidden(self):
+        self.server.queue.append((422, {"error": {"code": "something_secret", "message": "secret detail"}}, {}))
+        with self.assertRaises(ReqloAPIError) as error:
+            self.client.authorize(**REQUEST)
+        self.assertIsNone(error.exception.code)
+        self.assertNotIn("secret", str(error.exception))
+        self.assertEqual(len(self.server.requests), 1)
+
+    def test_timeouts_and_network_failures_raise_and_are_not_retried(self):
+        slow = Reqlo("rq_test_secret", base_url=self.server.url, timeout=0.2)
+        self.server.queue.append(("sleep", 1, {}))
+        with self.assertRaises(ReqloTimeoutError):
+            slow.enforce(**REQUEST)
+        self.assertEqual(len(self.server.requests), 1)
+        with self.assertRaises(ReqloNetworkError):
+            Reqlo("rq_test_secret", base_url="http://127.0.0.1:9/v1", max_retries=0).enforce(**REQUEST)
+
+    def test_delegation_create_is_never_retried(self):
+        self.server.queue.append((503, {"error": {"code": "service_unavailable"}}, {"Retry-After": "0"}))
+        with self.assertRaises(ReqloAPIError):
+            self.client.delegations.create("agt_x", {"id": "usr_94", "kind": "user"}, ["calendar.schedule"], NOW)
+        self.assertEqual(len(self.server.requests), 1)
+
+    def test_approvals_and_delegations(self):
+        self.server.queue += [(200, {"data": [APPROVAL], "environment_id": "env"}, {}), (200, APPROVAL, {}),
+                              (201, DELEGATION, {}), (200, {"data": [DELEGATION]}, {}), (200, DELEGATION, {}), (200, {**DELEGATION, "status": "revoked", "revoked_at": NOW}, {})]
+        self.assertEqual(self.client.approvals.list(status="pending")["data"][0]["id"], APPROVAL["id"])
+        self.assertEqual(self.client.approvals.retrieve(APPROVAL["id"])["status"], "pending")
+        self.assertEqual(self.client.delegations.create("agt_x", {"id": "usr_94", "kind": "user"}, ["calendar.schedule"], NOW)["status"], "active")
+        self.assertEqual(len(self.client.delegations.list(subject_id="usr_94")), 1)
+        self.assertEqual(self.client.delegations.retrieve(DELEGATION["id"])["id"], DELEGATION["id"])
+        self.assertEqual(self.client.delegations.revoke(DELEGATION["id"])["status"], "revoked")
+        paths = [(m, p) for m, p, _, _ in self.server.requests]
+        self.assertEqual(paths, [("GET", "/v1/approvals?status=pending"), ("GET", "/v1/approvals/" + APPROVAL["id"]), ("POST", "/v1/delegations"),
+                                 ("GET", "/v1/delegations?subject_id=usr_94"), ("GET", "/v1/delegations/" + DELEGATION["id"]), ("POST", "/v1/delegations/%s/revoke" % DELEGATION["id"])])
+
+    def test_async_client(self):
+        self.server.queue += [(200, decision("allow"), {}), (200, decision("deny"), {})]
+        client = AsyncReqlo("rq_test_secret", base_url=self.server.url)
+        self.assertEqual(asyncio.run(client.enforce(**REQUEST))["decision"], "allow")
+        with self.assertRaises(ReqloDeniedError):
+            asyncio.run(client.enforce(**REQUEST))
+
+    def test_configuration_is_checked_and_the_key_never_printed(self):
+        for kwargs in [dict(api_key="sk_nope"), dict(api_key="rq_test_x", base_url="http://api.reqlo.io/v1"), dict(api_key="rq_test_x", base_url="https://api.reqlo.io/v2"),
+                       dict(api_key="rq_test_x", timeout=0), dict(api_key="rq_test_x", max_retries=9)]:
+            with self.assertRaises(ReqloConfigurationError):
+                Reqlo(**kwargs)
+        self.assertNotIn("rq_test_secret", repr(self.client))
+        with self.assertRaises(ReqloConfigurationError):
+            self.client.approvals.retrieve("not-an-id")
+        with self.assertRaises(ReqloConfigurationError):
+            self.client.approvals.list(status="maybe")
+
+
+class WebhookTest(unittest.TestCase):
+    secret = "whsec_" + "b" * 64
+    body = json.dumps({"id": "EVT_1", "object": "event", "type": "approval.requested", "data": {"object": {"id": APPROVAL["id"]}}})
+
+    def sign(self, t, body=None, secret=None):
+        digest = hmac.new((secret or self.secret).encode(), ("%d." % t).encode() + (body or self.body).encode(), hashlib.sha256).hexdigest()
+        return "t=%d,v1=%s" % (t, digest)
+
+    def test_verify(self):
+        now = 1_800_000_000
+        self.assertTrue(webhooks.verify(self.body, self.sign(now), self.secret, now=now))
+        self.assertTrue(webhooks.verify(self.body.encode(), self.sign(now - 299), self.secret, now=now))
+        self.assertFalse(webhooks.verify(self.body, self.sign(now - 301), self.secret, now=now))
+        self.assertFalse(webhooks.verify(self.body + " ", self.sign(now), self.secret, now=now))
+        self.assertFalse(webhooks.verify(self.body, self.sign(now, secret="whsec_" + "c" * 64), self.secret, now=now))
+        self.assertFalse(webhooks.verify(self.body, None, self.secret, now=now))
+        self.assertFalse(webhooks.verify(self.body, self.sign(now), "not-a-secret", now=now))
+
+    def test_construct_event(self):
+        now = 1_800_000_000
+        self.assertEqual(webhooks.construct_event(self.body, self.sign(now), self.secret, now=now)["type"], "approval.requested")
+        with self.assertRaises(ReqloSignatureError):
+            webhooks.construct_event(self.body, "t=1,v1=" + "0" * 64, self.secret, now=now)
+
+    def test_version(self):
+        self.assertEqual(reqlo.__version__, "0.1.0")
+
+
+if __name__ == "__main__":
+    unittest.main()