authoxi 0.1.0__tar.gz

authoxi-0.1.0/.gitignore

@@ -0,0 +1,148 @@
+# ─────────────────────────────────────────────────────────────────────────────
+#  authoxi — .gitignore
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# ANCHORED to the repo root, deliberately. These come from the stock Python .gitignore, where
+# `lib/` means "the Python build output". Unanchored, it matches ANY directory called lib at
+# any depth — which silently swallowed the console's entire src/lib/ (the API client, the
+# Ed25519 signer, the store). Everything still built locally, because Docker copies the working
+# tree rather than what git tracks; only a clean clone revealed it. Keep these anchored.
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv*
+venv/
+ENV/
+env/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# Environments / secrets (never commit)
+.env
+.env.local
+*.env
+credentials.json
+*.pem
+*.key
+secrets/
+
+# Node
+node_modules/
+*node_modules*
+.npm
+.pnp.*
+.yarn/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Logs & local data
+*.log
+*.sqlite
+*.sqlite3
+
+# Telemetry spool (runtime trace output)
+*_spool*.jsonl
+.telemetry_spool.jsonl
+
+# Linter cache
+.ruff*
+.mypy*
+
+# Local agent settings
+.claude/settings.local.json
+
+# Backup files (caveman-compress etc.)
+*.original
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# The loss-event pump / SDK spool signed evidence to disk when the sink is
+# unreachable — real amounts, real vendors, real approver signatures. The rule
+# above only catches `*_spool*` (underscore); the pump writes
+# `authoxi-loss-events.spool.jsonl` (dot), which slipped straight through.
+*.spool.jsonl
+*.spool
+
+# `*.sqlite` was covered; `*.db` was not — and a local memory-backend DB lands here.
+*.db

authoxi-0.1.0/LICENSE

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

authoxi-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: authoxi
+Version: 0.1.0
+Summary: Python SDK for the authoxi authentication platform
+Project-URL: Homepage, https://authoxi.com
+Project-URL: Documentation, https://authoxi.com
+Project-URL: Source, https://github.com/aeternm/authoxi/tree/main/sdk/python
+Project-URL: Issues, https://github.com/aeternm/authoxi/issues
+Author: aeternm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-identity,auth,authentication,authoxi,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# authoxi — Python SDK
+
+The official Python client for the [authoxi](https://authoxi.com) authentication and agent-identity
+platform: human auth (`/auth`), agent authority + mandates (`/agent`, `/admin`), and the MCP firewall
+(`/mcp`). Agents generate their own Ed25519 keypair and sign proof-of-possession challenges
+client-side.
+
+```bash
+pip install authoxi
+```
+
+```python
+from authoxi import Authoxi
+
+client = Authoxi(base_url="https://api.authoxi.com", api_key="sk_live_...")
+```
+
+- **Docs:** https://authoxi.com
+- **API:** https://api.authoxi.com
+- **Source:** https://github.com/aeternm/authoxi/tree/main/sdk/python
+- **JS SDK** (browser): [`@authoxi/js`](https://www.npmjs.com/package/@authoxi/js)
+
+## License
+
+MIT — see [LICENSE](./LICENSE). The SDK is MIT so you can embed it freely; the authoxi service itself
+is proprietary.

authoxi-0.1.0/README.md

@@ -0,0 +1,26 @@
+# authoxi — Python SDK
+
+The official Python client for the [authoxi](https://authoxi.com) authentication and agent-identity
+platform: human auth (`/auth`), agent authority + mandates (`/agent`, `/admin`), and the MCP firewall
+(`/mcp`). Agents generate their own Ed25519 keypair and sign proof-of-possession challenges
+client-side.
+
+```bash
+pip install authoxi
+```
+
+```python
+from authoxi import Authoxi
+
+client = Authoxi(base_url="https://api.authoxi.com", api_key="sk_live_...")
+```
+
+- **Docs:** https://authoxi.com
+- **API:** https://api.authoxi.com
+- **Source:** https://github.com/aeternm/authoxi/tree/main/sdk/python
+- **JS SDK** (browser): [`@authoxi/js`](https://www.npmjs.com/package/@authoxi/js)
+
+## License
+
+MIT — see [LICENSE](./LICENSE). The SDK is MIT so you can embed it freely; the authoxi service itself
+is proprietary.

authoxi-0.1.0/authoxi/__init__.py

@@ -0,0 +1,49 @@
+"""authoxi Python SDK."""
+
+from .agents import (
+    Agent,
+    AgentControl,
+    BudgetExceeded,
+    Denied,
+    Escalated,
+    keygen,
+    sign,
+)
+from .client import AsyncAuthoxiClient, AuthoxiClient
+from .exceptions import (
+    AuthoxiError,
+    EmailTaken,
+    InvalidCredentials,
+    InvalidToken,
+    NotFound,
+    OTPExpired,
+    OTPInvalidCode,
+    OTPLocked,
+    RateLimited,
+)
+from .models import OTPState, Tenant, Tokens, User
+
+__all__ = [
+    "Agent",
+    "AgentControl",
+    "BudgetExceeded",
+    "Denied",
+    "Escalated",
+    "keygen",
+    "sign",
+    "AsyncAuthoxiClient",
+    "AuthoxiClient",
+    "AuthoxiError",
+    "EmailTaken",
+    "InvalidCredentials",
+    "InvalidToken",
+    "NotFound",
+    "OTPExpired",
+    "OTPInvalidCode",
+    "OTPLocked",
+    "RateLimited",
+    "OTPState",
+    "Tenant",
+    "Tokens",
+    "User",
+]

authoxi-0.1.0/authoxi/agents.py

@@ -0,0 +1,297 @@
+"""Agent control-plane SDK surface.
+
+Thin, typed wrappers over the agent endpoints, so a customer drives the whole control plane
+(identity · keyring · meter · wallet) from code instead of raw HTTP. Plus a small runtime
+``Agent`` helper that holds the keypair, manages its short-lived passport, and exposes a
+**mocked** model call (``chat``) that is metered exactly like a real one — the governance is
+real, the LLM is a stub.
+
+The client is transport-agnostic: pass any object with ``.post`` / ``.get`` returning an
+httpx-style response (an ``httpx.Client``, or a FastAPI ``TestClient`` for in-process demos).
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, Protocol
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .exceptions import AuthoxiError
+
+
+class _Http(Protocol):
+    def post(self, url: str, **kwargs: Any) -> Any: ...
+    def get(self, url: str, **kwargs: Any) -> Any: ...
+
+
+def _b64url(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def keygen() -> tuple[Ed25519PrivateKey, str]:
+    """A fresh Ed25519 keypair. Returns (private key object, public key as base64url) — the
+    private key never leaves the agent; only the public key is registered."""
+    priv = Ed25519PrivateKey.generate()
+    from cryptography.hazmat.primitives import serialization
+
+    pub_raw = priv.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw
+    )
+    return priv, _b64url(pub_raw)
+
+
+def sign(priv: Ed25519PrivateKey, message: bytes) -> str:
+    return _b64url(priv.sign(message))
+
+
+class BudgetExceeded(AuthoxiError):
+    """A metered call was blocked because the agent is over budget."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__("budget_exceeded", message)
+
+
+class Denied(AuthoxiError):
+    """An action was denied by policy. ``reason_code`` says why."""
+
+    def __init__(self, reason_code: str) -> None:
+        super().__init__("denied", f"denied: {reason_code}")
+        self.reason_code = reason_code
+
+
+class Escalated(AuthoxiError):
+    """An action needs a human. ``pending_id`` is the decision awaiting a signature."""
+
+    def __init__(self, pending_id: str) -> None:
+        super().__init__("escalate", f"escalate: {pending_id}")
+        self.pending_id = pending_id
+
+
+class AgentControl:
+    """Control-plane operations for a tenant (authenticated with its secret key)."""
+
+    def __init__(
+        self,
+        http: _Http,
+        *,
+        secret_key: str | None = None,
+        master_key: str | None = None,
+    ) -> None:
+        self._http = http
+        self._sk = {"Authorization": f"Bearer {secret_key}"} if secret_key else {}
+        self._mk = {"Authorization": f"Bearer {master_key}"} if master_key else {}
+
+    # -- low level --------------------------------------------------------
+    def _json(self, resp: Any) -> Any:
+        if resp.status_code >= 400:
+            raise AuthoxiError("http_error", f"{resp.status_code}: {resp.text}")
+        return resp.json()
+
+    def _post(
+        self, path: str, body: Any, *, master: bool = False, raw: bool = False
+    ) -> Any:
+        resp = self._http.post(
+            path, json=body, headers=self._mk if master else self._sk
+        )
+        return resp if raw else self._json(resp)
+
+    def _get(self, path: str, **params: Any) -> Any:
+        return self._json(self._http.get(path, params=params, headers=self._sk))
+
+    # -- tenants (master key) --------------------------------------------
+    def create_tenant(self, name: str) -> dict[str, Any]:
+        return self._post("/admin/tenants", {"name": name}, master=True)
+
+    # -- identity ---------------------------------------------------------
+    def register_agent(
+        self, *, public_key: str, name: str, allowed_scopes: list[str] | None = None
+    ) -> dict[str, Any]:
+        return self._post(
+            "/agent/register",
+            {
+                "public_key": public_key,
+                "name": name,
+                "allowed_scopes": allowed_scopes or [],
+            },
+        )
+
+    def passport(
+        self, *, agent_id: str, priv: Ed25519PrivateKey, scopes: list[str] | None = None
+    ) -> str:
+        challenge = self._post("/agent/challenge", {"agent_id": agent_id})["challenge"]
+        sig = sign(priv, challenge.encode())
+        resp = self._http.post(
+            "/agent/passport",
+            json={
+                "agent_id": agent_id,
+                "challenge": challenge,
+                "signature": sig,
+                "scopes": scopes or [],
+            },
+        )
+        if resp.status_code == 402:
+            raise BudgetExceeded(resp.text)
+        return self._json(resp)["passport"]
+
+    # -- IAM (roles) + keyring -------------------------------------------
+    def create_type(
+        self, *, name: str, policy: dict[str, Any], description: str = ""
+    ) -> dict[str, Any]:
+        return self._post(
+            "/agent/types", {"name": name, "description": description, "policy": policy}
+        )
+
+    def assign_type(self, *, agent_id: str, type_id: str) -> Any:
+        return self._post(f"/agent/{agent_id}/type", {"type_id": type_id})
+
+    def grant(self, *, agent_id: str, system: str, scopes: list[str]) -> dict[str, Any]:
+        resp = self._http.post(
+            "/agent/grants",
+            json={"agent_id": agent_id, "system": system, "scopes": scopes},
+            headers=self._sk,
+        )
+        if resp.status_code == 403:
+            raise Denied("grant_exceeds_policy")
+        return self._json(resp)
+
+    # -- meter ------------------------------------------------------------
+    def set_budget(
+        self,
+        *,
+        agent_id: str,
+        limit_units: int,
+        resource: str = "inference_usd",
+        period: str = "day",
+    ) -> dict[str, Any]:
+        return self._post(
+            "/agent/usage/policy",
+            {
+                "agent_id": agent_id,
+                "resource": resource,
+                "limit_units": limit_units,
+                "period": period,
+            },
+        )
+
+    def consume(
+        self, *, agent_id: str, units: int, resource: str = "inference_usd"
+    ) -> dict[str, Any]:
+        return self._post(
+            "/agent/usage/consume",
+            {"agent_id": agent_id, "resource": resource, "units": units},
+        )
+
+    # -- wallet -----------------------------------------------------------
+    def issue_mandate(
+        self,
+        *,
+        agent_id: str,
+        budget: str,
+        escalate_over: str,
+        actions: list[str],
+        subject_kind: str = "agent",
+        subject_did: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "subject_kind": subject_kind,
+            "subject_id": agent_id,
+            "budget": budget,
+            "currency": "USD",
+            "escalate_over": escalate_over,
+            "allowed_actions": actions,
+        }
+        if subject_did:
+            body["subject_did"] = subject_did
+        return self._post("/agent/mandate", body)
+
+    def authorize(
+        self, *, agent_id: str, mandate_id: str, action: str, amount: str
+    ) -> dict[str, Any]:
+        return self._post(
+            "/agent/authorize",
+            {
+                "agent_id": agent_id,
+                "mandate_id": mandate_id,
+                "action": action,
+                "amount": amount,
+                "currency": "USD",
+            },
+        )
+
+    def to_sign(
+        self,
+        *,
+        pending_id: str,
+        approver_mandate_id: str,
+        reason_class: str,
+        reason_code: str,
+    ) -> Any:
+        return self._get(
+            f"/agent/pending/{pending_id}",
+            approver_mandate_id=approver_mandate_id,
+            reason_class=reason_class,
+            reason_code=reason_code,
+        )
+
+    def resolve(
+        self,
+        *,
+        pending_id: str,
+        resolution: str,
+        approver_mandate_id: str,
+        signature: str,
+        reason_class: str,
+        reason_code: str,
+    ) -> dict[str, Any]:
+        return self._post(
+            "/agent/resolve",
+            {
+                "pending_id": pending_id,
+                "resolution": resolution,
+                "approver_mandate_id": approver_mandate_id,
+                "signature": signature,
+                "reason_class": reason_class,
+                "reason_code": reason_code,
+            },
+        )
+
+    def events(self) -> list[dict[str, Any]]:
+        return self._get("/agent/events")["events"]
+
+    # -- connections (safe custody) --------------------------------------
+    def connect(self, *, provider: str, secret: str) -> dict[str, Any]:
+        """HOSTED: the secret is sealed under the tenant's KMS at the control plane."""
+        return self._post("/connections", {"provider": provider, "secret": secret})
+
+    def declare_connection(self, *, provider: str) -> dict[str, Any]:
+        """SELF-HOSTED: no secret sent — the credential lives in the customer's data plane."""
+        return self._post("/connections/declare", {"provider": provider})
+
+
+class Agent:
+    """A runtime agent: holds its keypair, refreshes its passport, and makes a **mocked**
+    model call that is metered exactly like a real one."""
+
+    def __init__(
+        self, control: AgentControl, *, agent_id: str, priv: Ed25519PrivateKey
+    ) -> None:
+        self._c = control
+        self.agent_id = agent_id
+        self._priv = priv
+
+    def refresh_passport(self, scopes: list[str] | None = None) -> str:
+        """Obtain a fresh passport. Raises ``BudgetExceeded`` if the agent is over its meter —
+        the enforcement lever for direct model calls (over budget → no passport → cut off)."""
+        return self._c.passport(agent_id=self.agent_id, priv=self._priv, scopes=scopes)
+
+    def chat(self, prompt: str, *, cost_units: int) -> str:
+        """A MOCKED LLM call. The model is a stub; the metering is real: it consumes ``cost_units``
+        against the agent's inference budget and raises ``BudgetExceeded`` when over."""
+        out = self._c.consume(agent_id=self.agent_id, units=cost_units)
+        if not out["allowed"]:
+            raise BudgetExceeded(
+                f"inference budget exhausted (used {out['used']}/{out['limit']})"
+            )
+        # --- the real LLM call would go here; mocked for the demo ---
+        return f"[mocked completion for: {prompt[:40]}…]"

authoxi-0.1.0/authoxi/client.py

@@ -0,0 +1,478 @@
+"""authoxi Python SDK — sync and async clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .exceptions import AuthoxiError, from_api_error
+from .models import OTPState, Tenant, Tokens, User
+
+_TIMEOUT = httpx.Timeout(10.0, connect=5.0)
+
+
+def _build_signup_body(
+    email: str,
+    password: str,
+    name: str | None,
+    metadata: dict[str, Any] | None,
+) -> dict[str, Any]:
+    return {
+        "email": email,
+        "password": password,
+        "name": name,
+        "metadata": metadata or {},
+    }
+
+
+def _build_otp_body(
+    email: str | None,
+    phone: str | None,
+    purpose: str,
+    name: str | None,
+    first_name: str | None,
+    last_name: str | None,
+    metadata: dict[str, Any] | None,
+) -> tuple[str, dict[str, Any]]:
+    if not email and not phone:
+        raise ValueError("request_otp requires email or phone")
+    body: dict[str, Any] = {}
+    if email is not None:
+        body["email"] = email
+    if phone is not None:
+        body["phone"] = phone
+    if purpose == "signup":
+        if name is not None:
+            body["name"] = name
+        if first_name is not None:
+            body["first_name"] = first_name
+        if last_name is not None:
+            body["last_name"] = last_name
+        if metadata is not None:
+            body["metadata"] = metadata
+        return "/auth/signup/otp", body
+    return "/auth/signin/otp", body
+
+
+def _raise_for_response(resp: httpx.Response) -> dict[str, Any]:
+    if resp.status_code == 204 or not resp.content:
+        if resp.is_success:
+            return {}
+    data = resp.json()
+    if not resp.is_success:
+        err = data.get("error", {}) if isinstance(data, dict) else {}
+        raise from_api_error(
+            err.get("code", "error"),
+            err.get("message", str(data)),
+            resp.status_code,
+        )
+    return data  # type: ignore[return-value]
+
+
+class _Headers:
+    """Mixin: assemble tenant/master headers from credentials."""
+
+    _publishable_key: str | None
+    _master_key: str | None
+
+    def _tenant_headers(self) -> dict[str, str]:
+        if not self._publishable_key:
+            raise AuthoxiError(
+                "missing_key", "publishable_key is required for /auth operations"
+            )
+        return {"X-Authoxi-Key": self._publishable_key}
+
+    def _master_headers(self) -> dict[str, str]:
+        if not self._master_key:
+            raise AuthoxiError(
+                "missing_key", "master_key is required for admin operations"
+            )
+        return {"Authorization": f"Bearer {self._master_key}"}
+
+
+class AsyncAuthoxiClient(_Headers):
+    """
+    Async authoxi client.
+
+    Two credential modes:
+      * ``publishable_key`` — required for ``/auth/*`` flows. Sent as ``X-Authoxi-Key``.
+      * ``master_key`` — required for ``admin_*`` operations. Sent as
+        ``Authorization: Bearer <master_key>``.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        publishable_key: str | None = None,
+        master_key: str | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._publishable_key = publishable_key
+        self._master_key = master_key
+        self._http = httpx.AsyncClient(base_url=self._base_url, timeout=_TIMEOUT)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncAuthoxiClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        resp = await self._http.request(method, path, json=json, headers=headers or {})
+        return _raise_for_response(resp)
+
+    # Admin -----------------------------------------------------------------
+
+    async def admin_create_tenant(
+        self,
+        name: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> Tenant:
+        data = await self._request(
+            "POST",
+            "/admin/tenants",
+            json={"name": name, "metadata": metadata or {}},
+            headers=self._master_headers(),
+        )
+        return Tenant.from_dict(data)
+
+    async def admin_get_tenant(self, tenant_id: str) -> Tenant:
+        data = await self._request(
+            "GET",
+            f"/admin/tenants/{tenant_id}",
+            headers=self._master_headers(),
+        )
+        return Tenant.from_dict(data)
+
+    async def admin_rotate_secret(self, tenant_id: str) -> str:
+        data = await self._request(
+            "POST",
+            f"/admin/tenants/{tenant_id}/rotate-secret",
+            headers=self._master_headers(),
+        )
+        return data["secret_key"]  # type: ignore[no-any-return]
+
+    # Auth ------------------------------------------------------------------
+
+    async def signup(
+        self,
+        email: str,
+        password: str,
+        *,
+        name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> tuple[User, Tokens]:
+        data = await self._request(
+            "POST",
+            "/auth/signup",
+            json=_build_signup_body(email, password, name, metadata),
+            headers=self._tenant_headers(),
+        )
+        return User.from_dict(data), Tokens.from_dict(data)
+
+    async def signin(self, email: str, password: str) -> Tokens:
+        data = await self._request(
+            "POST",
+            "/auth/signin",
+            json={"email": email, "password": password},
+            headers=self._tenant_headers(),
+        )
+        return Tokens.from_dict(data)
+
+    async def request_otp(
+        self,
+        email: str | None = None,
+        *,
+        phone: str | None = None,
+        purpose: str = "signin",
+        name: str | None = None,
+        first_name: str | None = None,
+        last_name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> OTPState:
+        path, body = _build_otp_body(
+            email, phone, purpose, name, first_name, last_name, metadata
+        )
+        data = await self._request(
+            "POST", path, json=body, headers=self._tenant_headers()
+        )
+        return OTPState.from_dict(data)
+
+    async def verify_otp(self, otp_id: str, code: str) -> tuple[User, Tokens]:
+        data = await self._request(
+            "POST",
+            "/auth/otp/verify",
+            json={"otp_id": otp_id, "code": code},
+            headers=self._tenant_headers(),
+        )
+        return User.from_dict(data), Tokens.from_dict(data)
+
+    async def me(self, access_token: str) -> User:
+        data = await self._request(
+            "GET",
+            "/auth/me",
+            headers={
+                **self._tenant_headers(),
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+        return User.from_dict(data)
+
+    async def verify_token(self, access_token: str) -> User:
+        """Validate a bearer token, return its ``User``. Raises ``InvalidToken`` on 401."""
+        return await self.me(access_token)
+
+    async def signout(self, refresh_token: str, *, access_token: str) -> None:
+        await self._request(
+            "POST",
+            "/auth/signout",
+            json={"refresh_token": refresh_token},
+            headers={
+                **self._tenant_headers(),
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+    async def refresh(self, refresh_token: str) -> Tokens:
+        data = await self._request(
+            "POST",
+            "/auth/refresh",
+            json={"refresh_token": refresh_token},
+            headers=self._tenant_headers(),
+        )
+        return Tokens.from_dict(data)
+
+    async def forgot_password(
+        self, email: str, *, redirect_url: str | None = None
+    ) -> None:
+        body: dict[str, Any] = {"email": email}
+        if redirect_url is not None:
+            body["redirect_url"] = redirect_url
+        await self._request(
+            "POST",
+            "/auth/forgot-password",
+            json=body,
+            headers=self._tenant_headers(),
+        )
+
+    async def reset_password(self, token: str, new_password: str) -> None:
+        await self._request(
+            "POST",
+            "/auth/reset-password",
+            json={"token": token, "new_password": new_password},
+            headers=self._tenant_headers(),
+        )
+
+    async def update_password(self, access_token: str, new_password: str) -> None:
+        """Set/update the current user's password (Bearer-authenticated)."""
+        await self._request(
+            "POST",
+            "/auth/password/update",
+            json={"new_password": new_password},
+            headers={
+                **self._tenant_headers(),
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+
+class AuthoxiClient(_Headers):
+    """
+    Sync authoxi client. Uses a persistent ``httpx.Client`` — safe to call repeatedly.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        publishable_key: str | None = None,
+        master_key: str | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._publishable_key = publishable_key
+        self._master_key = master_key
+        self._http = httpx.Client(base_url=self._base_url, timeout=_TIMEOUT)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "AuthoxiClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        resp = self._http.request(method, path, json=json, headers=headers or {})
+        return _raise_for_response(resp)
+
+    # Admin -----------------------------------------------------------------
+
+    def admin_create_tenant(
+        self,
+        name: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> Tenant:
+        data = self._request(
+            "POST",
+            "/admin/tenants",
+            json={"name": name, "metadata": metadata or {}},
+            headers=self._master_headers(),
+        )
+        return Tenant.from_dict(data)
+
+    def admin_get_tenant(self, tenant_id: str) -> Tenant:
+        data = self._request(
+            "GET",
+            f"/admin/tenants/{tenant_id}",
+            headers=self._master_headers(),
+        )
+        return Tenant.from_dict(data)
+
+    def admin_rotate_secret(self, tenant_id: str) -> str:
+        data = self._request(
+            "POST",
+            f"/admin/tenants/{tenant_id}/rotate-secret",
+            headers=self._master_headers(),
+        )
+        return data["secret_key"]  # type: ignore[no-any-return]
+
+    # Auth ------------------------------------------------------------------
+
+    def signup(
+        self,
+        email: str,
+        password: str,
+        *,
+        name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> tuple[User, Tokens]:
+        data = self._request(
+            "POST",
+            "/auth/signup",
+            json=_build_signup_body(email, password, name, metadata),
+            headers=self._tenant_headers(),
+        )
+        return User.from_dict(data), Tokens.from_dict(data)
+
+    def signin(self, email: str, password: str) -> Tokens:
+        data = self._request(
+            "POST",
+            "/auth/signin",
+            json={"email": email, "password": password},
+            headers=self._tenant_headers(),
+        )
+        return Tokens.from_dict(data)
+
+    def request_otp(
+        self,
+        email: str | None = None,
+        *,
+        phone: str | None = None,
+        purpose: str = "signin",
+        name: str | None = None,
+        first_name: str | None = None,
+        last_name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> OTPState:
+        path, body = _build_otp_body(
+            email, phone, purpose, name, first_name, last_name, metadata
+        )
+        data = self._request("POST", path, json=body, headers=self._tenant_headers())
+        return OTPState.from_dict(data)
+
+    def verify_otp(self, otp_id: str, code: str) -> tuple[User, Tokens]:
+        data = self._request(
+            "POST",
+            "/auth/otp/verify",
+            json={"otp_id": otp_id, "code": code},
+            headers=self._tenant_headers(),
+        )
+        return User.from_dict(data), Tokens.from_dict(data)
+
+    def me(self, access_token: str) -> User:
+        data = self._request(
+            "GET",
+            "/auth/me",
+            headers={
+                **self._tenant_headers(),
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+        return User.from_dict(data)
+
+    def verify_token(self, access_token: str) -> User:
+        """Validate a bearer token, return its ``User``. Raises ``InvalidToken`` on 401."""
+        return self.me(access_token)
+
+    def signout(self, refresh_token: str, *, access_token: str) -> None:
+        self._request(
+            "POST",
+            "/auth/signout",
+            json={"refresh_token": refresh_token},
+            headers={
+                **self._tenant_headers(),
+                "Authorization": f"Bearer {access_token}",
+            },
+        )
+
+    def refresh(self, refresh_token: str) -> Tokens:
+        data = self._request(
+            "POST",
+            "/auth/refresh",
+            json={"refresh_token": refresh_token},
+            headers=self._tenant_headers(),
+        )
+        return Tokens.from_dict(data)
+
+    def forgot_password(self, email: str, *, redirect_url: str | None = None) -> None:
+        body: dict[str, Any] = {"email": email}
+        if redirect_url is not None:
+            body["redirect_url"] = redirect_url
+        self._request(
+            "POST",
+            "/auth/forgot-password",
+            json=body,
+            headers=self._tenant_headers(),
+        )
+
+    def reset_password(self, token: str, new_password: str) -> None:
+        self._request(
+            "POST",
+            "/auth/reset-password",
+            json={"token": token, "new_password": new_password},
+            headers=self._tenant_headers(),
+        )
+
+    def update_password(self, access_token: str, new_password: str) -> None:
+        """Set/update the current user's password (Bearer-authenticated)."""
+        self._request(
+            "POST",
+            "/auth/password/update",
+            json={"new_password": new_password},
+            headers={
+                **self._tenant_headers(),
+                "Authorization": f"Bearer {access_token}",
+            },
+        )

authoxi-0.1.0/authoxi/exceptions.py

@@ -0,0 +1,69 @@
+"""Typed exceptions for the authoxi Python SDK."""
+
+from __future__ import annotations
+
+
+class AuthoxiError(Exception):
+    """Base exception for all authoxi errors."""
+
+    def __init__(self, code: str, message: str, status_code: int = 0) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(code={self.code!r}, message={self.message!r})"
+        )
+
+
+class InvalidCredentials(AuthoxiError):
+    """Email or password is incorrect."""
+
+
+class EmailTaken(AuthoxiError):
+    """Email is already registered for this tenant."""
+
+
+class OTPExpired(AuthoxiError):
+    """OTP code has expired."""
+
+
+class OTPInvalidCode(AuthoxiError):
+    """OTP code is incorrect."""
+
+
+class OTPLocked(AuthoxiError):
+    """Too many incorrect OTP attempts — must request a new code."""
+
+
+class RateLimited(AuthoxiError):
+    """Too many requests. Slow down."""
+
+
+class InvalidToken(AuthoxiError):
+    """Access or refresh token is invalid or expired."""
+
+
+class NotFound(AuthoxiError):
+    """Requested resource not found."""
+
+
+_CODE_MAP: dict[str, type[AuthoxiError]] = {
+    "invalid_credentials": InvalidCredentials,
+    "email_taken": EmailTaken,
+    "otp_expired": OTPExpired,
+    "invalid_otp_code": OTPInvalidCode,
+    "otp_locked": OTPLocked,
+    "rate_limited": RateLimited,
+    "invalid_token": InvalidToken,
+    "token_expired": InvalidToken,
+    "not_found": NotFound,
+    "user_not_found": NotFound,
+}
+
+
+def from_api_error(code: str, message: str, status_code: int) -> AuthoxiError:
+    cls = _CODE_MAP.get(code, AuthoxiError)
+    return cls(code=code, message=message, status_code=status_code)

authoxi-0.1.0/authoxi/fastapi.py

@@ -0,0 +1,79 @@
+"""FastAPI integration for the authoxi SDK.
+
+Drop-in dependency that validates the ``Authorization: Bearer <token>`` header
+against authoxi and returns the authenticated :class:`User`.
+
+Usage::
+
+    from fastapi import Depends, FastAPI
+    from authoxi import AuthoxiClient
+    from authoxi.fastapi import authed_user
+
+    client = AuthoxiClient(base_url="https://api.authoxi.com", publishable_key="pk_live_...")
+    app = FastAPI()
+
+    @app.get("/profile")
+    def profile(user = Depends(authed_user(client))):
+        return {"email": user.email, "tenant_id": user.tenant_id}
+
+Works with both :class:`AuthoxiClient` (sync) and :class:`AsyncAuthoxiClient` (async).
+``fastapi`` must be installed: ``pip install authoxi[fastapi]``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Callable
+
+from fastapi import Header, HTTPException, status
+
+from .client import AsyncAuthoxiClient, AuthoxiClient
+from .exceptions import AuthoxiError, InvalidToken
+from .models import User
+
+
+def _extract_bearer(authorization: str | None) -> str:
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail={
+                "code": "missing_auth",
+                "message": "Authorization: Bearer <token> required",
+            },
+        )
+    return authorization.split(" ", 1)[1].strip()
+
+
+def _http_error_for(exc: AuthoxiError) -> HTTPException:
+    code = exc.status_code or status.HTTP_401_UNAUTHORIZED
+    return HTTPException(
+        status_code=code, detail={"code": exc.code, "message": exc.message}
+    )
+
+
+def authed_user(client: AuthoxiClient | AsyncAuthoxiClient) -> Callable[..., Any]:
+    """Build a FastAPI dependency that validates the bearer token and returns a ``User``."""
+    if isinstance(client, AsyncAuthoxiClient):
+
+        async def dep_async(
+            authorization: Annotated[str | None, Header()] = None,
+        ) -> User:
+            token = _extract_bearer(authorization)
+            try:
+                return await client.verify_token(token)
+            except InvalidToken as exc:
+                raise _http_error_for(exc) from exc
+            except AuthoxiError as exc:
+                raise _http_error_for(exc) from exc
+
+        return dep_async
+
+    def dep_sync(authorization: Annotated[str | None, Header()] = None) -> User:
+        token = _extract_bearer(authorization)
+        try:
+            return client.verify_token(token)
+        except InvalidToken as exc:
+            raise _http_error_for(exc) from exc
+        except AuthoxiError as exc:
+            raise _http_error_for(exc) from exc
+
+    return dep_sync

authoxi-0.1.0/authoxi/models.py

@@ -0,0 +1,93 @@
+"""Domain types returned by the authoxi SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class User:
+    user_id: str
+    tenant_id: str
+    email: str | None
+    phone: str | None
+    name: str | None
+    metadata: dict[str, Any]
+    status: str
+    created_at: datetime
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "User":
+        u = d.get("user", d)
+        return cls(
+            user_id=u["user_id"],
+            tenant_id=u["tenant_id"],
+            email=u.get("email"),
+            phone=u.get("phone"),
+            name=u.get("name"),
+            metadata=u.get("metadata", {}),
+            status=u.get("status", "active"),
+            created_at=datetime.fromisoformat(u["created_at"].replace("Z", "+00:00")),
+        )
+
+
+@dataclass
+class Tokens:
+    access_token: str
+    refresh_token: str
+    token_type: str
+    expires_in: int
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Tokens":
+        return cls(
+            access_token=d["access_token"],
+            refresh_token=d["refresh_token"],
+            token_type=d.get("token_type", "bearer"),
+            expires_in=d["expires_in"],
+        )
+
+
+@dataclass
+class OTPState:
+    otp_id: str
+    expires_in: int
+    test_code: str | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "OTPState":
+        return cls(
+            otp_id=d["otp_id"],
+            expires_in=d["expires_in"],
+            test_code=d.get("test_code"),
+        )
+
+
+@dataclass
+class Tenant:
+    tenant_id: str
+    name: str
+    publishable_key: str
+    status: str
+    metadata: dict[str, Any]
+    created_at: datetime
+    secret_key: str | None = None
+    updated_at: datetime | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "Tenant":
+        updated_raw = d.get("updated_at")
+        return cls(
+            tenant_id=d["tenant_id"],
+            name=d["name"],
+            publishable_key=d["publishable_key"],
+            status=d.get("status", "active"),
+            metadata=d.get("metadata", {}),
+            created_at=datetime.fromisoformat(d["created_at"].replace("Z", "+00:00")),
+            secret_key=d.get("secret_key"),
+            updated_at=datetime.fromisoformat(updated_raw.replace("Z", "+00:00"))
+            if updated_raw
+            else None,
+        )

authoxi-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "authoxi"
+version = "0.1.0"
+description = "Python SDK for the authoxi authentication platform"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "aeternm" }]
+keywords = ["authentication", "auth", "agent-identity", "mcp", "authoxi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    # Agents generate their own Ed25519 keypair and sign PoP challenges client-side.
+    "cryptography>=42.0.0",
+]
+
+[project.urls]
+Homepage = "https://authoxi.com"
+Documentation = "https://authoxi.com"
+Source = "https://github.com/aeternm/authoxi/tree/main/sdk/python"
+Issues = "https://github.com/aeternm/authoxi/issues"
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.110.0",
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "fastapi>=0.110.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["authoxi"]
+
+[tool.hatch.build.targets.sdist]
+# The wheel carries the package; the sdist ships the license + readme too, so PyPI and
+# downstream repackagers have them.
+include = ["authoxi", "README.md", "LICENSE"]