axowl-sdk 0.1.0__tar.gz

axowl_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: axowl-sdk
+Version: 0.1.0
+Summary: Axowl backend SDK for Python — verify Axowl end-user JWTs against the org JWKS, wildcard permission checks, server-authoritative introspection.
+Author: Axowl Inc.
+License: MIT
+Project-URL: Homepage, https://axowl.com
+Project-URL: Documentation, https://docs.axowl.com/sdk/python/
+Project-URL: Source, https://github.com/Axowl-inc/axowl-sdk
+Keywords: axowl,authentication,jwt,jwks,permissions
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT[crypto]<3,>=2.8
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: cryptography>=41; extra == "test"
+
+# axowl-sdk (Python)
+
+Backend SDK for [Axowl](https://axowl.com): verify Axowl end-user access tokens on your server,
+read the caller's permissions, and — when a decision must see revocations made after the token was
+issued — ask Axowl directly. Mirrors `@axowl/sdk-backend` (Node) and `Axowl.Sdk.Identity.Client` (.NET).
+
+```bash
+pip install axowl-sdk            # + "axowl-sdk[fastapi]" for the FastAPI dependency
+```
+
+## Verify a token (no server round trip)
+
+```python
+from axowl import AxowlConfig, verify_token, has_permission, AxowlAuthError
+
+config = AxowlConfig(
+    org_slug="my-org",                 # your Axowl org
+    audience="app_my_main",            # optional: your application key — rejects tokens minted for another app
+    base_url="https://api.axowl.com",  # default
+)
+
+try:
+    ctx = verify_token(bearer_token, config)
+except AxowlAuthError as e:
+    ...  # e.reason ∈ missing_token | invalid_token | expired | signature | issuer | audience | jwks
+
+ctx.user_id, ctx.email, ctx.org_slug, ctx.connected_id, ctx.is_employee
+ctx.permissions                            # ["wallet.read", "report.*"] — decoded from the token
+has_permission(ctx.permissions, "report.monthly")   # True (wildcards honoured)
+```
+
+- Signature: RS256 against `{base_url}/api/public/orgs/{org_slug}/.well-known/jwks.json`.
+  Keys are cached for 10 minutes; an unknown `kid` (rotation) triggers a re-fetch.
+- Issuer must equal `{base_url}/api/public/orgs/{org_slug}` — what Axowl writes into the token.
+- `exp`/`nbf` enforced (`leeway_seconds` on the config if your clock drifts).
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from axowl import AxowlConfig, AxowlContext
+from axowl.fastapi import AxowlAuth
+
+auth = AxowlAuth(AxowlConfig(org_slug="my-org", audience="app_my_main"))
+app = FastAPI()
+
+@app.get("/wallet")
+def wallet(ctx: AxowlContext = Depends(auth)):
+    return {"user": ctx.email}
+
+@app.post("/wallet/withdraw")
+def withdraw(ctx: AxowlContext = Depends(auth.require("wallet.withdraw"))):
+    ...
+```
+
+401 `{"error": ..., "reason": ...}` for a missing/invalid token, 403 `{"error": ..., "required": [...]}`
+for a missing scope — the same shapes as the Express middleware.
+
+Any other framework: call `extract_bearer_token(request.headers["Authorization"])` then `verify_token`.
+
+## Server-authoritative checks
+
+The JWT fast path cannot see a permission revoked *after* the token was issued. For those decisions
+ask Axowl with your **org API key** (`ah_live_…`):
+
+```python
+from axowl import AxowlIdentityClient
+
+identity = AxowlIdentityClient(api_key="ah_live_...", base_url="https://api.axowl.com")
+
+res = identity.introspect(bearer_token)          # → IntrospectResult(active, principal, expires_at, issued_at)
+res = identity.check_permission(bearer_token, "wallet.withdraw")   # → PermissionCheckResult(granted, matched_scopes, reason)
+```
+
+Both are synchronous and stdlib-only (`urllib`); run them in a thread from async code.
+
+## Permission matching
+
+Same rules as every other Axowl SDK and the server:
+
+| pattern | scope | match |
+|---|---|---|
+| `sap.fi.document.post` | `sap.fi.document.post` | yes |
+| `sap.fi.*` | `sap.fi.document.post` | yes |
+| `*` | anything | yes |
+| `sap.fi` | `sap.fi.document.post` | **no** (a prefix without `*` is not a wildcard) |
+
+## Tests
+
+```bash
+pip install -e ".[test]" && pytest
+```

axowl_sdk-0.1.0/README.md

@@ -0,0 +1,92 @@
+# axowl-sdk (Python)
+
+Backend SDK for [Axowl](https://axowl.com): verify Axowl end-user access tokens on your server,
+read the caller's permissions, and — when a decision must see revocations made after the token was
+issued — ask Axowl directly. Mirrors `@axowl/sdk-backend` (Node) and `Axowl.Sdk.Identity.Client` (.NET).
+
+```bash
+pip install axowl-sdk            # + "axowl-sdk[fastapi]" for the FastAPI dependency
+```
+
+## Verify a token (no server round trip)
+
+```python
+from axowl import AxowlConfig, verify_token, has_permission, AxowlAuthError
+
+config = AxowlConfig(
+    org_slug="my-org",                 # your Axowl org
+    audience="app_my_main",            # optional: your application key — rejects tokens minted for another app
+    base_url="https://api.axowl.com",  # default
+)
+
+try:
+    ctx = verify_token(bearer_token, config)
+except AxowlAuthError as e:
+    ...  # e.reason ∈ missing_token | invalid_token | expired | signature | issuer | audience | jwks
+
+ctx.user_id, ctx.email, ctx.org_slug, ctx.connected_id, ctx.is_employee
+ctx.permissions                            # ["wallet.read", "report.*"] — decoded from the token
+has_permission(ctx.permissions, "report.monthly")   # True (wildcards honoured)
+```
+
+- Signature: RS256 against `{base_url}/api/public/orgs/{org_slug}/.well-known/jwks.json`.
+  Keys are cached for 10 minutes; an unknown `kid` (rotation) triggers a re-fetch.
+- Issuer must equal `{base_url}/api/public/orgs/{org_slug}` — what Axowl writes into the token.
+- `exp`/`nbf` enforced (`leeway_seconds` on the config if your clock drifts).
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from axowl import AxowlConfig, AxowlContext
+from axowl.fastapi import AxowlAuth
+
+auth = AxowlAuth(AxowlConfig(org_slug="my-org", audience="app_my_main"))
+app = FastAPI()
+
+@app.get("/wallet")
+def wallet(ctx: AxowlContext = Depends(auth)):
+    return {"user": ctx.email}
+
+@app.post("/wallet/withdraw")
+def withdraw(ctx: AxowlContext = Depends(auth.require("wallet.withdraw"))):
+    ...
+```
+
+401 `{"error": ..., "reason": ...}` for a missing/invalid token, 403 `{"error": ..., "required": [...]}`
+for a missing scope — the same shapes as the Express middleware.
+
+Any other framework: call `extract_bearer_token(request.headers["Authorization"])` then `verify_token`.
+
+## Server-authoritative checks
+
+The JWT fast path cannot see a permission revoked *after* the token was issued. For those decisions
+ask Axowl with your **org API key** (`ah_live_…`):
+
+```python
+from axowl import AxowlIdentityClient
+
+identity = AxowlIdentityClient(api_key="ah_live_...", base_url="https://api.axowl.com")
+
+res = identity.introspect(bearer_token)          # → IntrospectResult(active, principal, expires_at, issued_at)
+res = identity.check_permission(bearer_token, "wallet.withdraw")   # → PermissionCheckResult(granted, matched_scopes, reason)
+```
+
+Both are synchronous and stdlib-only (`urllib`); run them in a thread from async code.
+
+## Permission matching
+
+Same rules as every other Axowl SDK and the server:
+
+| pattern | scope | match |
+|---|---|---|
+| `sap.fi.document.post` | `sap.fi.document.post` | yes |
+| `sap.fi.*` | `sap.fi.document.post` | yes |
+| `*` | anything | yes |
+| `sap.fi` | `sap.fi.document.post` | **no** (a prefix without `*` is not a wildcard) |
+
+## Tests
+
+```bash
+pip install -e ".[test]" && pytest
+```

axowl_sdk-0.1.0/axowl/__init__.py

@@ -0,0 +1,52 @@
+"""Axowl backend SDK for Python.
+
+Verify Axowl end-user access tokens on your server (RS256 against the org JWKS),
+read the caller's permissions from the token, and — when a decision must reflect
+revocations made *after* the token was issued — ask Axowl directly (introspect /
+check-permission with your org API key).
+
+    from axowl import AxowlConfig, verify_token, has_permission
+
+    config = AxowlConfig(org_slug="my-org", base_url="https://api.axowl.com")
+    ctx = verify_token(bearer_token, config)
+    if not has_permission(ctx.permissions, "report.view"):
+        raise PermissionError
+
+The behaviour mirrors `@axowl/sdk-backend` (JS) and `Axowl.Sdk.Identity.Client` (.NET).
+"""
+
+from .errors import AxowlAuthError, AxowlPermissionError
+from .permissions import has_all_permissions, has_any_permission, has_permission, match_scope
+from .token import decode_jwt, is_token_expired
+from .verify import (
+    AxowlConfig,
+    AxowlContext,
+    extract_bearer_token,
+    resolve_issuer,
+    resolve_jwks_url,
+    verify_token,
+)
+from .identity import AxowlIdentityClient, AxowlPrincipal, IntrospectResult, PermissionCheckResult
+
+__all__ = [
+    "AxowlAuthError",
+    "AxowlPermissionError",
+    "AxowlConfig",
+    "AxowlContext",
+    "AxowlIdentityClient",
+    "AxowlPrincipal",
+    "IntrospectResult",
+    "PermissionCheckResult",
+    "decode_jwt",
+    "extract_bearer_token",
+    "has_all_permissions",
+    "has_any_permission",
+    "has_permission",
+    "is_token_expired",
+    "match_scope",
+    "resolve_issuer",
+    "resolve_jwks_url",
+    "verify_token",
+]
+
+__version__ = "0.1.0"

axowl_sdk-0.1.0/axowl/errors.py

@@ -0,0 +1,19 @@
+class AxowlAuthError(Exception):
+    """The token could not be accepted (missing, malformed, expired, bad signature, wrong issuer/audience).
+
+    `reason` is a short machine-readable code so a framework adapter can map it to a response
+    without parsing the message: ``missing_token``, ``invalid_token``, ``expired``,
+    ``signature``, ``issuer``, ``audience``, ``jwks``.
+    """
+
+    def __init__(self, message: str, reason: str = "invalid_token"):
+        super().__init__(message)
+        self.reason = reason
+
+
+class AxowlPermissionError(Exception):
+    """The caller is authenticated but lacks one of the required scopes."""
+
+    def __init__(self, required: list[str]):
+        super().__init__(f"Insufficient permissions: {', '.join(required)}")
+        self.required = list(required)

axowl_sdk-0.1.0/axowl/fastapi.py

@@ -0,0 +1,65 @@
+"""FastAPI adapter — optional (``pip install axowl-sdk[fastapi]``).
+
+    from fastapi import Depends, FastAPI
+    from axowl import AxowlConfig, AxowlContext
+    from axowl.fastapi import AxowlAuth
+
+    auth = AxowlAuth(AxowlConfig(org_slug="my-org", audience="app_my_main"))
+    app = FastAPI()
+
+    @app.get("/wallet")
+    def wallet(ctx: AxowlContext = Depends(auth)):
+        return {"user": ctx.email}
+
+    @app.post("/wallet/withdraw")
+    def withdraw(ctx: AxowlContext = Depends(auth.require("wallet.withdraw"))):
+        ...
+
+401 for a missing/invalid token, 403 for a missing scope — the same shape as the Express middleware
+(``{"error": ..., "required": [...]}``).
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+try:
+    from fastapi import HTTPException, Request
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("axowl.fastapi needs FastAPI: pip install 'axowl-sdk[fastapi]'") from exc
+
+from .errors import AxowlAuthError
+from .permissions import has_permission
+from .verify import AxowlConfig, AxowlContext, extract_bearer_token, verify_token
+
+
+class AxowlAuth:
+    def __init__(self, config: AxowlConfig):
+        self.config = config
+
+    def __call__(self, request: Request) -> AxowlContext:
+        token = extract_bearer_token(request.headers.get("authorization"))
+        if not token:
+            raise HTTPException(status_code=401, detail={"error": "Missing authorization token"})
+        try:
+            ctx = verify_token(token, self.config)
+        except AxowlAuthError as exc:
+            raise HTTPException(status_code=401, detail={"error": str(exc), "reason": exc.reason}) from exc
+        request.state.axowl = ctx
+        return ctx
+
+    def require(self, *scopes: str) -> Callable[[Request], AxowlContext]:
+        """Dependency that also demands every listed scope (wildcards in the token honoured)."""
+        required = list(scopes)
+
+        def dependency(request: Request) -> AxowlContext:
+            ctx = self(request)
+            missing: Optional[str] = next((s for s in required if not has_permission(ctx.permissions, s)), None)
+            if missing is not None:
+                raise HTTPException(
+                    status_code=403,
+                    detail={"error": "Insufficient permissions", "required": required},
+                )
+            return ctx
+
+        return dependency

axowl_sdk-0.1.0/axowl/identity.py

@@ -0,0 +1,151 @@
+"""Server-authoritative checks — ask Axowl instead of trusting the token's claims.
+
+Use this when a decision must see revocations made *after* the token was issued
+(the JWT fast path cannot). Both calls authenticate with your **org API key**
+(``ah_live_…``) and hit the same handler the gRPC ``IdentityService`` uses:
+
+    POST {base_url}/v1/identity/introspect         { "token": "<end-user jwt>" }
+    POST {base_url}/v1/identity/check-permission   { "token": "<end-user jwt>", "requiredScope": "wallet.withdraw" }
+
+Sync, stdlib-only (``urllib``). Wrap in a thread if you call it from an async handler.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+from .verify import DEFAULT_BASE_URL
+
+INTROSPECT_PATH = "/v1/identity/introspect"
+CHECK_PERMISSION_PATH = "/v1/identity/check-permission"
+
+
+@dataclass(frozen=True)
+class AxowlPrincipal:
+    end_user_id: str
+    organization_id: str
+    connected_id: Optional[str]
+    is_employee: bool
+    email: str
+    display_name: Optional[str]
+    application_key: Optional[str]
+    permissions: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class IntrospectResult:
+    active: bool
+    principal: Optional[AxowlPrincipal] = None
+    expires_at: Optional[datetime] = None
+    issued_at: Optional[datetime] = None
+
+
+@dataclass(frozen=True)
+class PermissionCheckResult:
+    granted: bool
+    matched_scopes: list[str] = field(default_factory=list)
+    reason: Optional[str] = None
+
+
+class AxowlIdentityError(Exception):
+    def __init__(self, status: int, body: str):
+        super().__init__(f"Axowl identity call failed ({status}): {body}")
+        self.status = status
+        self.body = body
+
+
+Transport = Callable[[str, dict[str, Any], dict[str, str]], tuple[int, str]]
+
+
+def _urllib_transport(url: str, body: dict[str, Any], headers: dict[str, str]) -> tuple[int, str]:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method="POST", headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:  # noqa: S310 — URL comes from config, not user input
+            return resp.status, resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", errors="replace")
+
+
+def _parse_dt(value: Any) -> Optional[datetime]:
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+class AxowlIdentityClient:
+    """``introspect(token)`` and ``check_permission(token, scope)`` with your org API key."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        transport: Optional[Transport] = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required (org API key, ah_live_…)")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._transport = transport or _urllib_transport
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        status, text = self._transport(
+            f"{self._base_url}{path}",
+            body,
+            {
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+        if status < 200 or status >= 300:
+            raise AxowlIdentityError(status, text)
+        parsed = json.loads(text) if text else {}
+        return parsed if isinstance(parsed, dict) else {}
+
+    def introspect(self, token: str) -> IntrospectResult:
+        if not token:
+            raise ValueError("token is required")
+        root = self._post(INTROSPECT_PATH, {"token": token})
+        if not root.get("active"):
+            return IntrospectResult(active=False)
+        perms = root.get("permissions")
+        principal = AxowlPrincipal(
+            end_user_id=str(root.get("endUserId", "")),
+            organization_id=str(root.get("organizationId", "")),
+            connected_id=root.get("connectedId") or None,
+            is_employee=bool(root.get("isEmployee", False)),
+            email=str(root.get("email", "")),
+            display_name=root.get("displayName") or None,
+            application_key=root.get("applicationKey") or None,
+            permissions=[str(p) for p in perms if p] if isinstance(perms, list) else [],
+        )
+        return IntrospectResult(
+            active=True,
+            principal=principal,
+            expires_at=_parse_dt(root.get("expiresAt")),
+            issued_at=_parse_dt(root.get("issuedAt")),
+        )
+
+    def check_permission(self, token: str, required_scope: str) -> PermissionCheckResult:
+        if not token:
+            raise ValueError("token is required")
+        if not required_scope:
+            raise ValueError("required_scope is required")
+        root = self._post(CHECK_PERMISSION_PATH, {"token": token, "requiredScope": required_scope})
+        matched = root.get("matchedScopes")
+        return PermissionCheckResult(
+            granted=bool(root.get("granted", False)),
+            matched_scopes=[str(s) for s in matched if s] if isinstance(matched, list) else [],
+            reason=root.get("reason") or None,
+        )

axowl_sdk-0.1.0/axowl/permissions.py

@@ -0,0 +1,46 @@
+"""Wildcard permission matching — byte-for-byte the same rules as `@axowl/sdk-core`
+(`matchScope`) and the server's `IdentityServiceImpl.MatchScope`.
+
+    match_scope("sap.fi.document.post", "sap.fi.document.post")  -> True
+    match_scope("sap.fi.*", "sap.fi.document.post")              -> True
+    match_scope("sap.*", "sap.fi.document.post")                 -> True
+    match_scope("*", "anything.at.all")                          -> True
+    match_scope("aws.ec2.start", "aws.ec2.stop")                 -> False
+    match_scope("sap.fi", "sap.fi.document.post")                -> False  (prefix without `*` is not a match)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def match_scope(pattern: str, scope: str) -> bool:
+    if pattern == scope:
+        return True
+    if pattern == "*":
+        return True
+
+    pattern_parts = pattern.split(".")
+    scope_parts = scope.split(".")
+
+    for i, part in enumerate(pattern_parts):
+        if part == "*":
+            return True
+        if i >= len(scope_parts) or part != scope_parts[i]:
+            return False
+
+    return len(pattern_parts) == len(scope_parts)
+
+
+def has_permission(permissions: Iterable[str], scope: str) -> bool:
+    return any(match_scope(p, scope) for p in permissions)
+
+
+def has_all_permissions(permissions: Iterable[str], scopes: Iterable[str]) -> bool:
+    perms = list(permissions)
+    return all(has_permission(perms, s) for s in scopes)
+
+
+def has_any_permission(permissions: Iterable[str], scopes: Iterable[str]) -> bool:
+    perms = list(permissions)
+    return any(has_permission(perms, s) for s in scopes)

axowl_sdk-0.1.0/axowl/token.py

@@ -0,0 +1,40 @@
+"""Decode-only helpers. Nothing here checks a signature — use `axowl.verify.verify_token` for that."""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from typing import Any
+
+
+def _b64url_decode(segment: str) -> bytes:
+    padding = "=" * (-len(segment) % 4)
+    return base64.urlsafe_b64decode(segment + padding)
+
+
+def decode_jwt(token: str) -> dict[str, Any]:
+    """Return the JWT payload as a dict **without** verifying the signature.
+
+    Raises ``ValueError`` when the token is not three base64url segments of JSON.
+    """
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("Invalid JWT format")
+    try:
+        payload = json.loads(_b64url_decode(parts[1]))
+    except (ValueError, json.JSONDecodeError) as exc:  # binascii.Error is a ValueError
+        raise ValueError("Invalid JWT payload") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("Invalid JWT payload")
+    return payload
+
+
+def is_token_expired(token: str, buffer_seconds: int = 0) -> bool:
+    """True when ``exp`` is at or before now (+ buffer). A malformed token counts as expired."""
+    try:
+        payload = decode_jwt(token)
+        exp = int(payload.get("exp", 0))
+    except (ValueError, TypeError):
+        return True
+    return exp <= int(time.time()) + buffer_seconds

axowl_sdk-0.1.0/axowl/verify.py

@@ -0,0 +1,195 @@
+"""RS256 verification of Axowl end-user access tokens against the org JWKS.
+
+What Axowl puts in an end-user token (server: ``PublicEndpoints.GenerateEndUserJwt``):
+
+    iss          {base_url}/api/public/orgs/{org_slug}
+    aud          the application key the user signed in to (``app_...``)
+    sub          end-user id
+    email        end-user e-mail
+    org          organization id       org_slug     organization slug
+    app          application key        app_group    application group id
+    type         "enduser"              is_employee  "true" / "false"
+    cid          ConnectedId (the user's badge in this org) — absent for a plain end-user
+    permissions  JSON-encoded string array, e.g. '["wallet.read","report.*"]' — absent when empty
+
+Keys come from ``{base_url}/api/public/orgs/{org_slug}/.well-known/jwks.json``. They are cached
+in-process for 10 minutes and re-fetched when a token carries an unknown ``kid`` (key rotation),
+with a 30-second cooldown so a flood of bad tokens cannot hammer the endpoint.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import jwt
+from jwt import PyJWKClient
+
+from .errors import AxowlAuthError
+
+DEFAULT_BASE_URL = "https://api.axowl.com"
+JWKS_CACHE_SECONDS = 600
+JWKS_COOLDOWN_SECONDS = 30
+
+
+@dataclass(frozen=True)
+class AxowlConfig:
+    """Where your org lives and how to reach Axowl.
+
+    ``org_slug`` is required unless both ``jwks_url`` and ``issuer`` are given explicitly.
+    ``audience`` — pass your application key to reject tokens minted for another app.
+    ``api_key`` — your org API key (``ah_live_…``); only needed for `AxowlIdentityClient`.
+    """
+
+    org_slug: Optional[str] = None
+    base_url: str = DEFAULT_BASE_URL
+    jwks_url: Optional[str] = None
+    issuer: Optional[str] = None
+    audience: Optional[str] = None
+    api_key: Optional[str] = None
+    leeway_seconds: int = 0
+
+
+@dataclass
+class AxowlContext:
+    """The verified caller. ``permissions`` is already a list even though the token stores a JSON string."""
+
+    token: dict[str, Any]
+    raw: str
+    user_id: str
+    email: Optional[str] = None
+    org_id: Optional[str] = None
+    org_slug: Optional[str] = None
+    app_key: Optional[str] = None
+    app_group_id: Optional[str] = None
+    connected_id: Optional[str] = None
+    type: Optional[str] = None
+    is_employee: bool = False
+    permissions: list[str] = field(default_factory=list)
+
+
+def resolve_jwks_url(config: AxowlConfig) -> str:
+    if config.jwks_url:
+        return config.jwks_url
+    if not config.org_slug:
+        raise ValueError("AxowlConfig needs org_slug (or an explicit jwks_url)")
+    return f"{config.base_url.rstrip('/')}/api/public/orgs/{config.org_slug}/.well-known/jwks.json"
+
+
+def resolve_issuer(config: AxowlConfig) -> str:
+    """The ``iss`` Axowl writes into end-user tokens: ``{base_url}/api/public/orgs/{org_slug}``."""
+    if config.issuer:
+        return config.issuer
+    if not config.org_slug:
+        raise ValueError("AxowlConfig needs org_slug (or an explicit issuer)")
+    return f"{config.base_url.rstrip('/')}/api/public/orgs/{config.org_slug}"
+
+
+_jwks_clients: dict[str, PyJWKClient] = {}
+_jwks_lock = threading.Lock()
+
+
+def _jwks_client(url: str) -> PyJWKClient:
+    with _jwks_lock:
+        client = _jwks_clients.get(url)
+        if client is None:
+            client = PyJWKClient(
+                url,
+                cache_keys=True,
+                lifespan=JWKS_CACHE_SECONDS,
+                max_cached_keys=16,
+            )
+            _jwks_clients[url] = client
+        return client
+
+
+def _parse_permissions(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except json.JSONDecodeError:
+            return []
+    if isinstance(value, list):
+        return [str(p) for p in value if p]
+    return []
+
+
+def _parse_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() == "true"
+    return False
+
+
+def build_context(payload: dict[str, Any], raw: str) -> AxowlContext:
+    return AxowlContext(
+        token=payload,
+        raw=raw,
+        user_id=str(payload.get("sub", "")),
+        email=payload.get("email"),
+        org_id=payload.get("org"),
+        org_slug=payload.get("org_slug") or None,
+        app_key=payload.get("app"),
+        app_group_id=payload.get("app_group") or None,
+        connected_id=payload.get("cid"),
+        type=payload.get("type"),
+        is_employee=_parse_bool(payload.get("is_employee")),
+        permissions=_parse_permissions(payload.get("permissions")),
+    )
+
+
+def verify_token(token: str, config: AxowlConfig, *, jwks_client: Optional[PyJWKClient] = None) -> AxowlContext:
+    """Verify signature (RS256, org JWKS), ``exp``/``nbf``, ``iss`` and — when configured — ``aud``.
+
+    Raises `AxowlAuthError` with a ``reason`` of ``expired``, ``signature``, ``issuer``,
+    ``audience``, ``jwks`` or ``invalid_token``. ``jwks_client`` is an injection point for tests.
+    """
+    if not token:
+        raise AxowlAuthError("Missing token", "missing_token")
+
+    client = jwks_client or _jwks_client(resolve_jwks_url(config))
+    try:
+        signing_key = client.get_signing_key_from_jwt(token)
+    except jwt.exceptions.PyJWKClientError as exc:
+        raise AxowlAuthError(f"Could not resolve signing key: {exc}", "jwks") from exc
+    except jwt.exceptions.DecodeError as exc:
+        raise AxowlAuthError(f"Invalid token: {exc}", "invalid_token") from exc
+
+    options = {"require": ["exp", "sub"], "verify_aud": config.audience is not None}
+    try:
+        payload = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["RS256"],
+            issuer=resolve_issuer(config),
+            audience=config.audience,
+            leeway=config.leeway_seconds,
+            options=options,
+        )
+    except jwt.ExpiredSignatureError as exc:
+        raise AxowlAuthError("Token expired", "expired") from exc
+    except jwt.InvalidIssuerError as exc:
+        raise AxowlAuthError("Token issuer mismatch", "issuer") from exc
+    except jwt.InvalidAudienceError as exc:
+        raise AxowlAuthError("Token audience mismatch", "audience") from exc
+    except jwt.InvalidSignatureError as exc:
+        raise AxowlAuthError("Token signature invalid", "signature") from exc
+    except jwt.InvalidTokenError as exc:
+        raise AxowlAuthError(f"Invalid token: {exc}", "invalid_token") from exc
+
+    return build_context(payload, token)
+
+
+def extract_bearer_token(authorization_header: Optional[str]) -> Optional[str]:
+    """``"Bearer eyJ…"`` → ``"eyJ…"``; anything else → ``None``."""
+    if not authorization_header:
+        return None
+    scheme, _, value = authorization_header.partition(" ")
+    if scheme.lower() != "bearer" or not value.strip():
+        return None
+    return value.strip()

axowl_sdk-0.1.0/axowl_sdk.egg-info/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: axowl-sdk
+Version: 0.1.0
+Summary: Axowl backend SDK for Python — verify Axowl end-user JWTs against the org JWKS, wildcard permission checks, server-authoritative introspection.
+Author: Axowl Inc.
+License: MIT
+Project-URL: Homepage, https://axowl.com
+Project-URL: Documentation, https://docs.axowl.com/sdk/python/
+Project-URL: Source, https://github.com/Axowl-inc/axowl-sdk
+Keywords: axowl,authentication,jwt,jwks,permissions
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyJWT[crypto]<3,>=2.8
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: cryptography>=41; extra == "test"
+
+# axowl-sdk (Python)
+
+Backend SDK for [Axowl](https://axowl.com): verify Axowl end-user access tokens on your server,
+read the caller's permissions, and — when a decision must see revocations made after the token was
+issued — ask Axowl directly. Mirrors `@axowl/sdk-backend` (Node) and `Axowl.Sdk.Identity.Client` (.NET).
+
+```bash
+pip install axowl-sdk            # + "axowl-sdk[fastapi]" for the FastAPI dependency
+```
+
+## Verify a token (no server round trip)
+
+```python
+from axowl import AxowlConfig, verify_token, has_permission, AxowlAuthError
+
+config = AxowlConfig(
+    org_slug="my-org",                 # your Axowl org
+    audience="app_my_main",            # optional: your application key — rejects tokens minted for another app
+    base_url="https://api.axowl.com",  # default
+)
+
+try:
+    ctx = verify_token(bearer_token, config)
+except AxowlAuthError as e:
+    ...  # e.reason ∈ missing_token | invalid_token | expired | signature | issuer | audience | jwks
+
+ctx.user_id, ctx.email, ctx.org_slug, ctx.connected_id, ctx.is_employee
+ctx.permissions                            # ["wallet.read", "report.*"] — decoded from the token
+has_permission(ctx.permissions, "report.monthly")   # True (wildcards honoured)
+```
+
+- Signature: RS256 against `{base_url}/api/public/orgs/{org_slug}/.well-known/jwks.json`.
+  Keys are cached for 10 minutes; an unknown `kid` (rotation) triggers a re-fetch.
+- Issuer must equal `{base_url}/api/public/orgs/{org_slug}` — what Axowl writes into the token.
+- `exp`/`nbf` enforced (`leeway_seconds` on the config if your clock drifts).
+
+## FastAPI
+
+```python
+from fastapi import Depends, FastAPI
+from axowl import AxowlConfig, AxowlContext
+from axowl.fastapi import AxowlAuth
+
+auth = AxowlAuth(AxowlConfig(org_slug="my-org", audience="app_my_main"))
+app = FastAPI()
+
+@app.get("/wallet")
+def wallet(ctx: AxowlContext = Depends(auth)):
+    return {"user": ctx.email}
+
+@app.post("/wallet/withdraw")
+def withdraw(ctx: AxowlContext = Depends(auth.require("wallet.withdraw"))):
+    ...
+```
+
+401 `{"error": ..., "reason": ...}` for a missing/invalid token, 403 `{"error": ..., "required": [...]}`
+for a missing scope — the same shapes as the Express middleware.
+
+Any other framework: call `extract_bearer_token(request.headers["Authorization"])` then `verify_token`.
+
+## Server-authoritative checks
+
+The JWT fast path cannot see a permission revoked *after* the token was issued. For those decisions
+ask Axowl with your **org API key** (`ah_live_…`):
+
+```python
+from axowl import AxowlIdentityClient
+
+identity = AxowlIdentityClient(api_key="ah_live_...", base_url="https://api.axowl.com")
+
+res = identity.introspect(bearer_token)          # → IntrospectResult(active, principal, expires_at, issued_at)
+res = identity.check_permission(bearer_token, "wallet.withdraw")   # → PermissionCheckResult(granted, matched_scopes, reason)
+```
+
+Both are synchronous and stdlib-only (`urllib`); run them in a thread from async code.
+
+## Permission matching
+
+Same rules as every other Axowl SDK and the server:
+
+| pattern | scope | match |
+|---|---|---|
+| `sap.fi.document.post` | `sap.fi.document.post` | yes |
+| `sap.fi.*` | `sap.fi.document.post` | yes |
+| `*` | anything | yes |
+| `sap.fi` | `sap.fi.document.post` | **no** (a prefix without `*` is not a wildcard) |
+
+## Tests
+
+```bash
+pip install -e ".[test]" && pytest
+```

axowl_sdk-0.1.0/axowl_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+axowl/__init__.py
+axowl/errors.py
+axowl/fastapi.py
+axowl/identity.py
+axowl/permissions.py
+axowl/token.py
+axowl/verify.py
+axowl_sdk.egg-info/PKG-INFO
+axowl_sdk.egg-info/SOURCES.txt
+axowl_sdk.egg-info/dependency_links.txt
+axowl_sdk.egg-info/requires.txt
+axowl_sdk.egg-info/top_level.txt
+tests/test_identity.py
+tests/test_permissions.py
+tests/test_verify.py

axowl_sdk-0.1.0/axowl_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

axowl_sdk-0.1.0/axowl_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+PyJWT[crypto]<3,>=2.8
+
+[fastapi]
+fastapi>=0.100
+
+[test]
+pytest>=8
+cryptography>=41

axowl_sdk-0.1.0/axowl_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+axowl

axowl_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "axowl-sdk"
+version = "0.1.0"
+description = "Axowl backend SDK for Python — verify Axowl end-user JWTs against the org JWKS, wildcard permission checks, server-authoritative introspection."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Axowl Inc." }]
+keywords = ["axowl", "authentication", "jwt", "jwks", "permissions"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Security",
+  "Framework :: FastAPI",
+]
+dependencies = [
+  "PyJWT[crypto]>=2.8,<3",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+test = ["pytest>=8", "cryptography>=41"]
+
+[project.urls]
+Homepage = "https://axowl.com"
+Documentation = "https://docs.axowl.com/sdk/python/"
+Source = "https://github.com/Axowl-inc/axowl-sdk"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["axowl*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

axowl_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

axowl_sdk-0.1.0/tests/test_identity.py

@@ -0,0 +1,77 @@
+import json
+
+import pytest
+
+from axowl import AxowlIdentityClient
+from axowl.identity import AxowlIdentityError
+
+
+class FakeTransport:
+    def __init__(self, status, body):
+        self.status = status
+        self.body = body
+        self.calls = []
+
+    def __call__(self, url, body, headers):
+        self.calls.append((url, body, headers))
+        return self.status, json.dumps(self.body) if isinstance(self.body, dict) else self.body
+
+
+def test_introspect_active_maps_principal():
+    t = FakeTransport(
+        200,
+        {
+            "active": True,
+            "endUserId": "3f2c9f0e2a1b4c5d8e9f0a1b2c3d4e5f",
+            "organizationId": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
+            "connectedId": "99999999888877776666555555555555",
+            "isEmployee": True,
+            "email": "user@example.com",
+            "displayName": "User",
+            "applicationKey": "app_acme_main",
+            "permissions": ["wallet.read", "", "report.*"],
+            "expiresAt": "2026-09-22T10:00:00Z",
+            "issuedAt": "2026-09-22T09:00:00+00:00",
+        },
+    )
+    client = AxowlIdentityClient("ah_live_x", "https://api.example.test/", transport=t)
+    res = client.introspect("tok")
+    assert res.active and res.principal is not None
+    assert res.principal.email == "user@example.com"
+    assert res.principal.permissions == ["wallet.read", "report.*"]
+    assert res.principal.is_employee is True
+    assert res.expires_at.isoformat() == "2026-09-22T10:00:00+00:00"
+    url, body, headers = t.calls[0]
+    assert url == "https://api.example.test/v1/identity/introspect"
+    assert body == {"token": "tok"}
+    assert headers["Authorization"] == "Bearer ah_live_x"
+
+
+def test_introspect_inactive():
+    client = AxowlIdentityClient("ah_live_x", transport=FakeTransport(200, {"active": False}))
+    res = client.introspect("tok")
+    assert res.active is False and res.principal is None
+
+
+def test_check_permission():
+    t = FakeTransport(200, {"granted": True, "matchedScopes": ["report.*"], "reason": None})
+    client = AxowlIdentityClient("ah_live_x", transport=t)
+    res = client.check_permission("tok", "report.view")
+    assert res.granted and res.matched_scopes == ["report.*"] and res.reason is None
+    assert t.calls[0][1] == {"token": "tok", "requiredScope": "report.view"}
+    assert t.calls[0][0] == "https://api.axowl.com/v1/identity/check-permission"
+
+
+def test_http_error_raises():
+    client = AxowlIdentityClient("ah_live_x", transport=FakeTransport(401, '{"error":"bad key"}'))
+    with pytest.raises(AxowlIdentityError) as ei:
+        client.introspect("tok")
+    assert ei.value.status == 401
+
+
+def test_argument_validation():
+    with pytest.raises(ValueError):
+        AxowlIdentityClient("")
+    client = AxowlIdentityClient("ah_live_x", transport=FakeTransport(200, {}))
+    with pytest.raises(ValueError):
+        client.check_permission("tok", "")

axowl_sdk-0.1.0/tests/test_permissions.py

@@ -0,0 +1,33 @@
+import pytest
+
+from axowl import has_all_permissions, has_any_permission, has_permission, match_scope
+
+
+@pytest.mark.parametrize(
+    "pattern,scope,expected",
+    [
+        ("sap.fi.document.post", "sap.fi.document.post", True),
+        ("sap.fi.*", "sap.fi.document.post", True),
+        ("sap.*", "sap.fi.document.post", True),
+        ("*", "anything.at.all", True),
+        ("aws.ec2.start", "aws.ec2.stop", False),
+        ("sap.fi", "sap.fi.document.post", False),      # prefix without `*` is not a match
+        ("sap.fi.document.post", "sap.fi", False),      # pattern longer than scope
+        ("sap.fi.*", "sap", False),
+        ("", "", True),
+    ],
+)
+def test_match_scope(pattern, scope, expected):
+    assert match_scope(pattern, scope) is expected
+
+
+def test_has_permission_family():
+    perms = ["wallet.read", "report.*"]
+    assert has_permission(perms, "wallet.read")
+    assert has_permission(perms, "report.monthly.export")
+    assert not has_permission(perms, "wallet.write")
+    assert has_all_permissions(perms, ["wallet.read", "report.view"])
+    assert not has_all_permissions(perms, ["wallet.read", "wallet.write"])
+    assert has_any_permission(perms, ["wallet.write", "report.view"])
+    assert not has_any_permission(perms, ["wallet.write", "billing.admin"])
+    assert not has_permission([], "wallet.read")

axowl_sdk-0.1.0/tests/test_verify.py

@@ -0,0 +1,125 @@
+import json
+import time
+
+import pytest
+
+from axowl import (
+    AxowlAuthError,
+    AxowlConfig,
+    decode_jwt,
+    extract_bearer_token,
+    is_token_expired,
+    resolve_issuer,
+    resolve_jwks_url,
+    verify_token,
+)
+from tests.conftest import APP_KEY, BASE, ORG
+
+
+def test_resolvers_default_to_axowl_layout():
+    cfg = AxowlConfig(org_slug="my-org")
+    assert resolve_jwks_url(cfg) == "https://api.axowl.com/api/public/orgs/my-org/.well-known/jwks.json"
+    assert resolve_issuer(cfg) == "https://api.axowl.com/api/public/orgs/my-org"
+
+
+def test_resolvers_honour_overrides():
+    cfg = AxowlConfig(jwks_url="https://x/jwks", issuer="https://x")
+    assert resolve_jwks_url(cfg) == "https://x/jwks"
+    assert resolve_issuer(cfg) == "https://x"
+    with pytest.raises(ValueError):
+        resolve_jwks_url(AxowlConfig())
+
+
+def test_verify_happy_path_maps_every_claim(make_token, config, jwks_client):
+    ctx = verify_token(make_token(), config, jwks_client=jwks_client)
+    assert ctx.user_id == "3f2c9f0e2a1b4c5d8e9f0a1b2c3d4e5f"
+    assert ctx.email == "user@example.com"
+    assert ctx.org_id == "0a1b2c3d4e5f60718293a4b5c6d7e8f9"
+    assert ctx.org_slug == ORG
+    assert ctx.app_key == APP_KEY
+    assert ctx.app_group_id == "11111111222233334444555555555555"
+    assert ctx.connected_id == "99999999888877776666555555555555"
+    assert ctx.type == "enduser"
+    assert ctx.is_employee is False
+    assert ctx.permissions == ["wallet.read", "report.*"]   # JSON string in the token → list
+    assert ctx.token["aud"] == APP_KEY
+    assert ctx.raw.count(".") == 2
+
+
+def test_permissions_absent_or_array_or_garbage(make_token, config, jwks_client):
+    assert verify_token(make_token(permissions=None), config, jwks_client=jwks_client).permissions == []
+    assert verify_token(make_token(permissions=["a.b"]), config, jwks_client=jwks_client).permissions == ["a.b"]
+    assert verify_token(make_token(permissions="not json"), config, jwks_client=jwks_client).permissions == []
+
+
+def test_is_employee_string_true(make_token, config, jwks_client):
+    assert verify_token(make_token(is_employee="true"), config, jwks_client=jwks_client).is_employee is True
+
+
+def test_expired(make_token, config, jwks_client):
+    with pytest.raises(AxowlAuthError) as ei:
+        verify_token(make_token(exp=int(time.time()) - 10), config, jwks_client=jwks_client)
+    assert ei.value.reason == "expired"
+
+
+def test_wrong_issuer(make_token, config, jwks_client):
+    with pytest.raises(AxowlAuthError) as ei:
+        verify_token(make_token(iss="https://evil.example"), config, jwks_client=jwks_client)
+    assert ei.value.reason == "issuer"
+
+
+def test_wrong_audience_only_when_configured(make_token, config, jwks_client):
+    with pytest.raises(AxowlAuthError) as ei:
+        verify_token(make_token(aud="app_other"), config, jwks_client=jwks_client)
+    assert ei.value.reason == "audience"
+    # no audience configured → any aud accepted
+    relaxed = AxowlConfig(org_slug=ORG, base_url=BASE)
+    assert verify_token(make_token(aud="app_other"), relaxed, jwks_client=jwks_client).app_key == APP_KEY
+
+
+def test_unknown_kid(make_token, config, jwks_client):
+    with pytest.raises(AxowlAuthError) as ei:
+        verify_token(make_token(_kid="rotated"), config, jwks_client=jwks_client)
+    assert ei.value.reason == "jwks"
+
+
+def test_tampered_signature(make_token, config, jwks_client):
+    token = make_token()
+    head, body, sig = token.split(".")
+    forged = json.loads(decode_jwt(token) and "{}")  # keep decode_jwt exercised
+    assert forged == {}
+    with pytest.raises(AxowlAuthError) as ei:
+        verify_token(f"{head}.{body}.{sig[:-2]}AA", config, jwks_client=jwks_client)
+    assert ei.value.reason in ("signature", "invalid_token")
+
+
+def test_missing_and_garbage_tokens(config, jwks_client):
+    with pytest.raises(AxowlAuthError) as ei:
+        verify_token("", config, jwks_client=jwks_client)
+    assert ei.value.reason == "missing_token"
+    with pytest.raises(AxowlAuthError):
+        verify_token("not.a.jwt", config, jwks_client=jwks_client)
+
+
+def test_jwks_is_cached_across_calls(make_token, config, jwks_client):
+    verify_token(make_token(), config, jwks_client=jwks_client)
+    verify_token(make_token(), config, jwks_client=jwks_client)
+    assert jwks_client.fetch_count == 1
+
+
+def test_decode_only_helpers(make_token):
+    t = make_token()
+    assert decode_jwt(t)["type"] == "enduser"
+    assert is_token_expired(t) is False
+    assert is_token_expired(make_token(exp=int(time.time()) - 1)) is True
+    assert is_token_expired("garbage") is True
+    with pytest.raises(ValueError):
+        decode_jwt("a.b")
+
+
+def test_extract_bearer_token():
+    assert extract_bearer_token("Bearer abc") == "abc"
+    assert extract_bearer_token("bearer abc") == "abc"
+    assert extract_bearer_token("Basic abc") is None
+    assert extract_bearer_token("Bearer ") is None
+    assert extract_bearer_token(None) is None