allowly 0.2.0__tar.gz

allowly-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish Python SDK
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/allowly
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Require tag commit on main
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package and build tools
+        run: python -m pip install ".[dev]" build twine
+      - run: pytest -q
+      - name: Check tag matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+
+          with open("pyproject.toml", "rb") as file:
+              version = tomllib.load(file)["project"]["version"]
+          assert os.environ["GITHUB_REF_NAME"] == f"v{version}"
+          PY
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

allowly-0.2.0/.github/workflows/verify.yml

@@ -0,0 +1,24 @@
+name: verify
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify Python SDK
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package and build tools
+        run: python -m pip install ".[dev]" build twine
+      - run: pytest -q
+      - run: python -m build
+      - run: python -m twine check dist/*

allowly-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.DS_Store
+.pytest_cache/
+__pycache__/
+*.py[cod]
+.coverage
+dist/
+build/
+*.egg-info/

allowly-0.2.0/LICENSE

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

allowly-0.2.0/PKG-INFO

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

@@ -0,0 +1,98 @@
+# 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/allowly/__init__.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from .client import Allowly
+from .error import AllowlyAPIError, AllowlyProtocolError, FieldError
+from .types import (
+    ActionCheckResult,
+    ActionCheckResultAllow,
+    ActionCheckResultConfirm,
+    ActionCheckResultDeny,
+    ActionCheckResultEscalate,
+    ActionEntry,
+    CheckResponse,
+    ConfirmationApproveResponse,
+    AuthorizationCreateResponse,
+    AuthorizationRevokeResponse,
+    BudgetInfo,
+    BudgetSettlementResponse,
+    Decision,
+    EscalationInfo,
+    EscalationResolveResponse,
+    FallbackMode,
+    PolicyConditionEvidence,
+    PolicyEvalInfo,
+    ReceiptEnvelope,
+    ReceiptEnvelopePending,
+    ReceiptEnvelopeSigned,
+)
+
+__all__ = [
+    "Allowly",
+    "AllowlyAPIError",
+    "AllowlyProtocolError",
+    "FieldError",
+    "ActionCheckResult",
+    "ActionCheckResultAllow",
+    "ActionCheckResultConfirm",
+    "ActionCheckResultDeny",
+    "ActionCheckResultEscalate",
+    "ActionEntry",
+    "CheckResponse",
+    "BudgetInfo",
+    "BudgetSettlementResponse",
+    "EscalationInfo",
+    "EscalationResolveResponse",
+    "AuthorizationCreateResponse",
+    "AuthorizationRevokeResponse",
+    "ConfirmationApproveResponse",
+    "PolicyConditionEvidence",
+    "PolicyEvalInfo",
+    "ReceiptEnvelope",
+    "ReceiptEnvelopePending",
+    "ReceiptEnvelopeSigned",
+    "Decision",
+    "FallbackMode",
+]