allowly 0.2.0__py3-none-any.whl

allowly/error.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class FieldError:
+    field: str
+    message: str
+
+
+class AllowlyAPIError(Exception):
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        fields: list[FieldError] | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.fields = fields or []
+        #: Parsed ``Retry-After`` response header, when the API sent one
+        #: (rate limits, contended idempotent replays). Honor it before retrying.
+        self.retry_after_seconds = retry_after_seconds
+
+    def __repr__(self) -> str:
+        return f"AllowlyAPIError(status={self.status}, code={self.code!r}, message={str(self)!r})"
+
+
+class AllowlyProtocolError(ValueError):
+    """The API returned a response that does not match its wire contract."""

allowly/identifiers.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+
+EMAIL_HMAC_VERSION = "v1"
+EMAIL_HMAC_PREFIX = "email_hmac"
+
+
+def normalize_email(email: str) -> str:
+    """Normalize an email address for Allowly's local identifier helper."""
+    normalized = email.strip().lower()
+    if not normalized:
+        raise ValueError("email must not be empty")
+    return normalized
+
+
+def from_email(email: str, *, pepper: str | bytes, version: str = EMAIL_HMAC_VERSION) -> str:
+    """Return a stable opaque user_id derived locally from an email address.
+
+    The raw email and pepper never leave the customer's application.
+    """
+    if version != EMAIL_HMAC_VERSION:
+        raise ValueError("unsupported email identifier version")
+
+    if isinstance(pepper, str):
+        key = pepper.encode("utf-8")
+    elif isinstance(pepper, bytes):
+        key = pepper
+    else:
+        raise TypeError("pepper must be str or bytes")
+    if not key:
+        raise ValueError("pepper must not be empty")
+
+    message = normalize_email(email).encode("utf-8")
+    digest = hmac.new(key, message, hashlib.sha256).digest()
+    encoded = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+    return f"{EMAIL_HMAC_PREFIX}:{version}:{encoded}"
+
+
+__all__ = [
+    "EMAIL_HMAC_PREFIX",
+    "EMAIL_HMAC_VERSION",
+    "from_email",
+    "normalize_email",
+]

allowly/mcp.py

@@ -0,0 +1,129 @@
+"""Allowly middleware for FastMCP 2.x servers.
+
+Usage:
+    from fastmcp import FastMCP
+
+    mcp = FastMCP("my-server")
+    mcp.add_middleware(AllowlyMCPMiddleware(
+        api_key="allowly_l1_s001_...",
+        user_id_fn=lambda context: context.fastmcp_context.session.user_id,
+        authorization_id_fn=lambda user_id: db.get_authorization_id(user_id),
+    ))
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Optional, Union
+
+import mcp.types as mt
+from fastmcp.exceptions import ToolError
+from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
+from fastmcp.tools.tool import ToolResult
+
+from allowly.client import Allowly
+
+
+AuthorizationIdResult = Optional[str]
+AuthorizationIdFn = Callable[[str], Union[AuthorizationIdResult, Awaitable[AuthorizationIdResult]]]
+UserIdResult = Optional[str]
+
+
+@dataclass(frozen=True)
+class MCPAuthorizationContext:
+    tool_name: str
+    arguments: dict[str, Any]
+    request: Any | None = None
+    fastmcp_context: Any | None = None
+
+
+UserIdFn = Callable[[MCPAuthorizationContext], Union[UserIdResult, Awaitable[UserIdResult]]]
+
+
+class AllowlyMCPMiddleware(Middleware):
+    """Gate every FastMCP tool call through Allowly.
+
+    ``user_id_fn`` must resolve identity from trusted host context, not
+    caller-controlled tool arguments. ``authorization_id_fn`` is then called with
+    that trusted user ID and must return the corresponding Allowly authorization
+    ID. Both callbacks may be sync or async. If either returns ``None`` the check
+    is denied immediately.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        authorization_id_fn: AuthorizationIdFn,
+        *,
+        base_url: Optional[str] = None,
+        user_id_fn: UserIdFn | None = None,
+    ) -> None:
+        kwargs: dict[str, Any] = {}
+        if base_url:
+            kwargs["base_url"] = base_url
+        self.client = Allowly(api_key, **kwargs)
+        self.authorization_id_fn = authorization_id_fn
+        self.user_id_fn = user_id_fn
+
+    async def aclose(self) -> None:
+        await self.client.aclose()
+
+    async def _resolve_authorization_id(self, context: MCPAuthorizationContext) -> Optional[str]:
+        user_id = await self._resolve_user_id(context)
+        if not user_id:
+            return None
+        result = self.authorization_id_fn(user_id)
+        if hasattr(result, "__await__"):
+            return await result  # type: ignore[return-value]
+        return result  # type: ignore[return-value]
+
+    async def _resolve_user_id(self, context: MCPAuthorizationContext) -> Optional[str]:
+        if self.user_id_fn is not None:
+            result = self.user_id_fn(context)
+            if hasattr(result, "__await__"):
+                return await result  # type: ignore[return-value]
+            return result  # type: ignore[return-value]
+        return None
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """FastMCP hook — called before every tool execution."""
+        name = context.message.name
+        args = context.message.arguments or {}
+        auth_context = MCPAuthorizationContext(
+            tool_name=name,
+            arguments=args,
+            fastmcp_context=context.fastmcp_context,
+        )
+        authorization_id = await self._resolve_authorization_id(auth_context)
+        if authorization_id is None:
+            raise ToolError("authorization_not_found")
+
+        result = await self.client.check(authorization_id=authorization_id, actions=[name])
+        action_result = result.results[name]
+        if action_result.decision == "allow":
+            return await call_next(context)
+        raise ToolError(json.dumps(_decision_payload(action_result)))
+
+
+def _decision_payload(action: Any) -> dict[str, Any]:
+    if action.decision == "confirm":
+        return {
+            "decision": "confirm",
+            "reason": action.reason,
+            "confirm_nonce": action.confirm_nonce,
+            "confirm_expires_at": action.confirm_expires_at,
+            "confirm_prompt_hint": action.confirm_prompt_hint,
+        }
+    if action.decision == "escalate":
+        return {
+            "decision": "escalate",
+            "reason": action.reason,
+            "escalation_id": action.escalation_id,
+            "escalation_to": action.escalation_to,
+            "escalation_expires_at": action.escalation_expires_at,
+        }
+    return {"decision": action.decision, "reason": action.reason}

allowly/types.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Union
+
+
+Decision = Literal["allow", "deny", "confirm", "escalate"]
+FallbackMode = Literal["fail_open", "fail_closed"]
+
+
+@dataclass
+class ReceiptEnvelopePending:
+    status: Literal["pending"]
+    receipt_id: str
+    ready_at_estimate: str | None
+    url: str
+
+
+@dataclass
+class ReceiptEnvelopeSigned:
+    status: Literal["signed"]
+    receipt: dict[str, Any]
+
+
+ReceiptEnvelope = Union[ReceiptEnvelopePending, ReceiptEnvelopeSigned]
+
+
+@dataclass
+class BudgetInfo:
+    limit_micros: int
+    spent_micros: int
+    estimated_cost_micros: int
+    spent_after_micros: int | None = None
+
+
+@dataclass
+class BudgetSettlementResponse:
+    check_receipt_id: str
+    authorization_id: str
+    estimated_cost_micros: int
+    actual_cost_micros: int
+    delta_micros: int
+    spent_before_micros: int
+    spent_after_micros: int
+    receipt: ReceiptEnvelope
+
+
+@dataclass
+class EscalationInfo:
+    escalation_id: str
+    status: str
+    escalation_to: str | None = None
+    expires_at: str | None = None
+
+
+@dataclass
+class PolicyConditionEvidence:
+    field: str
+    op: str
+    value: str | int | bool | None | list[str | int | bool | None]
+
+
+@dataclass
+class PolicyEvalInfo:
+    matched_condition: PolicyConditionEvidence | None
+    field_value: str | int | bool | None
+
+
+@dataclass(kw_only=True)
+class ActionCheckResultBase:
+    decision: Decision
+    reason: str
+    receipt: ReceiptEnvelope | None
+    is_fallback: bool = False
+    fallback_mode: FallbackMode | None = None
+    budget: BudgetInfo | None = None
+    escalation: EscalationInfo | None = None
+    policy_eval: PolicyEvalInfo | None = None
+
+
+@dataclass
+class ActionCheckResultAllow(ActionCheckResultBase):
+    decision: Literal["allow"]
+
+
+@dataclass
+class ActionCheckResultDeny(ActionCheckResultBase):
+    decision: Literal["deny"]
+    superseded_by: str | None = None
+
+
+@dataclass(kw_only=True)
+class ActionCheckResultConfirm(ActionCheckResultBase):
+    decision: Literal["confirm"]
+    confirm_nonce: str
+    confirm_expires_at: str
+    confirm_prompt_hint: str
+
+
+@dataclass(kw_only=True)
+class ActionCheckResultEscalate(ActionCheckResultBase):
+    decision: Literal["escalate"]
+    escalation_id: str
+    escalation_to: str | None = None
+    escalation_expires_at: str | None = None
+
+
+ActionCheckResult = Union[
+    ActionCheckResultAllow,
+    ActionCheckResultDeny,
+    ActionCheckResultConfirm,
+    ActionCheckResultEscalate,
+]
+
+
+@dataclass
+class CheckResponse:
+    authorization_id: str
+    user_id: str | None
+    agent_id: str | None
+    authorization_expires_at: str | None
+    engine_version: str
+    results: dict[str, ActionCheckResult]
+    #: X-Allowly-Billing-Warning response header, when the workspace is close
+    #: to a quota/payment boundary. Surface it to operators.
+    billing_warning: str | None = None
+
+
+@dataclass
+class ActionEntry:
+    name: str
+    constraints: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AuthorizationCreateResponse:
+    authorization_id: str
+    created_at: str
+    expires_at: str
+    receipt: ReceiptEnvelopePending
+    requires_confirm_for: list[str]
+    requires_escalation_for: list[str]
+    requires_deny_for: list[str]
+    escalation_targets: dict[str, str]
+    policy_id: str | None = None
+    budget_limit_micros: int | None = None
+    budget_spent_micros: int | None = None
+    replaced_authorization_id: str | None = None
+    revocation_receipt: ReceiptEnvelopePending | None = None
+    #: X-Allowly-Billing-Warning response header, when present.
+    billing_warning: str | None = None
+
+
+@dataclass
+class AuthorizationRevokeResponse:
+    authorization_id: str
+    revoked_at: str
+    receipt: ReceiptEnvelopePending
+    revoked_confirmations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ConfirmationApproveResponse:
+    decision: Literal["approved", "denied_by_user"]
+    authorization_id: str | None = None
+    expires_at: str | None = None
+
+
+@dataclass
+class EscalationResolveResponse:
+    escalation_id: str
+    status: Literal["approved", "rejected"]
+    resolved_by: str | None = None
+    resolved_at: str | None = None
+    receipt: ReceiptEnvelopePending | None = None

allowly/verify.py

@@ -0,0 +1,154 @@
+"""Offline Ed25519 receipt verification.
+
+Wraps the receipt-format reference verifier. No network call needed —
+fetch the workspace public keys once, cache them, verify locally forever.
+
+    from allowly.verify import fetch_keys_doc, verify_receipt, load_keys_from_json
+
+    keys_doc = fetch_keys_doc(workspace_id)
+    keys = load_keys_from_json(keys_doc)
+    verify_receipt(signed_receipt, keys, expected_workspace_id=workspace_id)
+"""
+from __future__ import annotations
+
+import copy
+import hashlib
+import httpx
+import json
+import time
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote, urlparse
+
+# Offline verification is powered by the published reference verifier,
+# allowly-receipt-format 3.x (import path allowly_receipt_format). It ships as an
+# optional extra so the core SDK stays dependency-light:
+#     pip install 'allowly[verifier]'
+def _import_verifier():
+    try:
+        from allowly_receipt_format import (
+            verify_receipt,
+            load_keys_from_json,
+            VerificationError,
+            PublicKey,
+        )
+        return verify_receipt, load_keys_from_json, VerificationError, PublicKey
+    except ImportError as exc:
+        raise ImportError(
+            "Receipt verification requires allowly-receipt-format>=3.0.0. "
+            "Install the verifier extra: pip install 'allowly[verifier]'"
+        ) from exc
+
+
+_verify_receipt, _load_keys_from_json, VerificationError, PublicKey = _import_verifier()
+
+DEFAULT_BASE_URL = "https://api.allowly.ai"
+DEFAULT_KEYS_DOC_CACHE_TTL_SECONDS = 300
+_keys_doc_cache: dict[tuple[str, str | None, int], tuple[float, dict[str, Any]]] = {}
+
+
+def verify_receipt(
+    receipt: dict[str, Any],
+    public_keys: list[PublicKey],
+    *,
+    expected_workspace_id: str,
+    now: datetime | None = None,
+) -> None:
+    _verify_receipt(
+        receipt,
+        public_keys,
+        now=now,
+        expected_workspace_id=expected_workspace_id,
+    )
+
+
+def load_keys_from_json(doc: dict[str, Any]) -> list[PublicKey]:
+    try:
+        return _load_keys_from_json(doc)
+    except VerificationError:
+        raise
+    except Exception as exc:
+        raise VerificationError(str(exc)) from exc
+
+
+def fetch_keys_doc(
+    workspace_id: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    cache_ttl_seconds: int = DEFAULT_KEYS_DOC_CACHE_TTL_SECONDS,
+    expected_sha256: str | None = None,
+    client: httpx.Client | None = None,
+    dangerously_allow_insecure_base_url: bool = False,
+    edge_token: str | None = None,
+) -> dict[str, Any]:
+    base_url = base_url.rstrip("/")
+    url = f"{base_url}/v1/workspaces/{quote(workspace_id, safe='')}/keys"
+    parsed = urlparse(url)
+    if not parsed.netloc:
+        raise VerificationError(f"keys document URL must be valid: {url}")
+    if parsed.scheme not in {"http", "https"}:
+        raise VerificationError(f"keys document URL must use HTTP or HTTPS: {url}")
+    if parsed.scheme != "https" and not dangerously_allow_insecure_base_url:
+        raise VerificationError(f"keys document URL must use HTTPS: {url}")
+
+    cache_key = (url, expected_sha256, cache_ttl_seconds)
+    cached = _keys_doc_cache.get(cache_key)
+    now = time.time()
+    if cached and cached[0] > now:
+        return copy.deepcopy(cached[1])
+
+    owns_client = client is None
+    if client is None:
+        client = httpx.Client(timeout=10.0)
+    try:
+        request_options: dict[str, Any] = {"follow_redirects": False}
+        if edge_token is not None:
+            request_options["headers"] = {"X-Allowly-Edge-Token": edge_token}
+        resp = client.get(url, **request_options)
+    except httpx.HTTPError as exc:
+        raise VerificationError(f"failed to fetch keys document: {exc}") from exc
+    finally:
+        if owns_client:
+            client.close()
+
+    if resp.status_code != 200:
+        raise VerificationError(
+            f"failed to fetch keys document: expected HTTP 200, got {resp.status_code}"
+        )
+    if resp.url != httpx.URL(url):
+        raise VerificationError(
+            f"keys document final URL changed: got {resp.url}, want {url}"
+        )
+    body = resp.content
+
+    if expected_sha256 is not None:
+        digest = hashlib.sha256(body).hexdigest()
+        if digest.lower() != expected_sha256.lower():
+            raise VerificationError("keys document SHA-256 hash did not match expected pin")
+
+    try:
+        doc = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise VerificationError("keys document was not valid JSON") from exc
+    if isinstance(doc, dict) and doc.get("workspace_id") != workspace_id:
+        raise VerificationError(
+            f"keys document workspace_id mismatch: got {doc.get('workspace_id')!r}, want {workspace_id!r}"
+        )
+
+    load_keys_from_json(doc)
+    _keys_doc_cache[cache_key] = (now + cache_ttl_seconds, doc)
+    return copy.deepcopy(doc)
+
+
+def clear_keys_doc_cache() -> None:
+    _keys_doc_cache.clear()
+
+
+__all__ = [
+    "verify_receipt",
+    "load_keys_from_json",
+    "fetch_keys_doc",
+    "clear_keys_doc_cache",
+    "VerificationError",
+    "PublicKey",
+]

allowly-0.2.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: allowly
+Version: 0.2.0
+Summary: Python SDK for the Allowly API
+Project-URL: Repository, https://github.com/Allowly-AI/allowly-sdk-python
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: allowly-receipt-format<4.0.0,>=3.0.0; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: fastmcp<3,>=2.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp<3,>=2.9; extra == 'fastmcp'
+Provides-Extra: verifier
+Requires-Dist: allowly-receipt-format<4.0.0,>=3.0.0; extra == 'verifier'
+Description-Content-Type: text/markdown
+
+# Allowly Python SDK
+
+Async Python client for the Allowly runtime API.
+
+MCP middleware ships inside this SDK: `pip install 'allowly[fastmcp]'`, then `from allowly.mcp import AllowlyMCPMiddleware`. In TypeScript, it lives in the separate `@allowly/mcp` package.
+
+## Subject authorization pattern
+
+Do not send raw user/customer PII to Allowly receipts unless you intentionally
+want it in your audit trail. Create one authorization per subject, store the
+returned authorization ID in your own app database, and use that ID for later checks.
+
+```python
+import asyncio
+import os
+
+from allowly import Allowly
+
+
+async def main() -> None:
+    async with Allowly(
+        api_key=os.environ["ALLOWLY_API_KEY"],
+        base_url=os.getenv("ALLOWLY_API_URL", "https://api.allowly.ai"),
+    ) as allowly:
+        # Your app creates a stable internal subject ID.
+        subject_id = "subject_abc123"
+
+        # Store this in your app table, for example:
+        # allowly_authorizations(subject_id, policy_id, allowly_authorization_id, status)
+        authorization = await allowly.authorizations.create(
+            user_id=f"subject:{subject_id}",
+            policy_id="research_agent",
+            metadata={"source": "import"},
+        )
+
+        # Before the agent acts, check whether this action is allowed.
+        decision = await allowly.check(
+            authorization_id=authorization.authorization_id,
+            actions=["web.search"],
+            resource=f"subject:{subject_id}",
+            context={"stage": "research"},
+        )
+
+    if decision.results["web.search"].decision != "allow":
+        raise RuntimeError("Action is not authorized")
+
+
+asyncio.run(main())
+```
+
+Local development against the documented Caddy endpoint requires the edge
+token that Cloudflare injects for public traffic. Pass it explicitly:
+
+```python
+Allowly(
+    api_key=os.environ["ALLOWLY_API_KEY"],
+    base_url="http://localhost:8443",
+    dangerously_allow_insecure_base_url=True,
+    edge_token=os.environ["ALLOWLY_EDGE_TOKEN"],
+)
+```
+
+The token is only sent when provided; never set it for the public API.
+
+Inline authorization creation requires `agent_id`, `actions`, and `expires_at`.
+Policy-based creation uses `policy_id` instead and rejects inline action or
+decision-override fields.
+
+Unavailable checks fail closed unless an action is explicitly mapped to
+`"fail_open"` with `fallback_by_action`. Unmapped actions always fail closed.
+
+For actions that need third-party approval, define the escalation rule on the
+agent policy, create the authorization from that `policy_id`, and then resolve
+returned escalation results with
+`await allowly.escalations.approve(escalation_id, resolved_by="manager:123")`
+or `reject(...)`, then re-check before running the action.
+
+If you need lookup by email later, import `from_email` from
+`allowly.identifiers` and store `from_email(email, pepper=APP_PII_PEPPER)`.
+The helper trims and lowercases only, prefixes the result with `email_hmac:v1`,
+and never sends the raw email or pepper to Allowly. Keep the pepper stable and
+backed up; changing it changes derived user IDs. Keep raw names, emails,
+documents, and profile URLs out of Allowly receipts unless those fields are
+intentionally part of your audit record.
+
+Do not add raw HTTP fallbacks in application code for APIs the SDK is missing.
+Patch this SDK first, then use the typed client from the app. That keeps the
+integration examples honest and makes SDK gaps visible early.
+
+## Offline receipt verification
+
+Install `allowly[verifier]` to verify signed receipts locally. The extra uses
+`allowly-receipt-format>=3.0.0,<4.0.0`, which verifies receipt wire format 3 (the package major equals the wire format). `alg` and
+`key_id` are signed top-level fields, and `signature` is the base64url string.
+
+Key-document fetching requires HTTPS by default. For the documented local
+Caddy endpoint only, pass `dangerously_allow_insecure_base_url=True` and its
+`edge_token` to `fetch_keys_doc`, matching the client options above.

allowly-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+allowly/__init__.py,sha256=B3bjOZjbJk_3Ozs0CQgqutAyD9JXNbjG27A60wBybLc,1353
+allowly/client.py,sha256=j4bFrUodmj36KJfdQs8cO_D-MeHa3AgJf1PqhNmTFO0,29624
+allowly/error.py,sha256=M9hh0JSDpVyEymBYqWG2HB-oAvKcXIhfzRsDvwJZ8CA,959
+allowly/identifiers.py,sha256=c7Hv10F9Cl5S8PeLUHykDYobEZ2m93Z7MP5OpHWPT0M,1358
+allowly/mcp.py,sha256=H9mf5Vl7w-oHygzSiXPFN5-YiB91v1Cg4Jf3Fyy5Kv0,4634
+allowly/types.py,sha256=-3q9uPoihGklWjZhjD2aQsNY9AP1epZ2q7moT1Edju4,4230
+allowly/verify.py,sha256=J8pk146a5GF5C0V9JVodu_l1jZZ8aK4qt4ssdhu-dC8,5134
+allowly-0.2.0.dist-info/METADATA,sha256=KTA8qaMXNoQ0CF6iogkRdcZ5YwRIomDht1Z6VETbyEw,4797
+allowly-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+allowly-0.2.0.dist-info/licenses/LICENSE,sha256=ZQy7j4VFJOfOyVDMPyC2CxlArjT6cU26htbgLC727go,1064
+allowly-0.2.0.dist-info/RECORD,,

allowly-0.2.0.dist-info/WHEEL

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