nxtid-sdk 0.1.0__py3-none-any.whl

nxtid_sdk/__init__.py

@@ -0,0 +1,5 @@
+from .client import NxtidSDK
+from .entra import EntraAuth
+from .exceptions import ToolCallBlockedError
+
+__all__ = ["NxtidSDK", "EntraAuth", "ToolCallBlockedError"]

nxtid_sdk/client.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import httpx
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    """Like raise_for_status() but includes the response body in the exception message."""
+    if resp.is_error:
+        try:
+            detail = resp.json()
+        except Exception:
+            detail = resp.text
+        raise httpx.HTTPStatusError(
+            f"Client error '{resp.status_code} {resp.reason_phrase}' for url '{resp.url}' — {detail}",
+            request=resp.request,
+            response=resp,
+        )
+
+
+@dataclass
+class WalletResult:
+    wallet_address: str
+    email: str
+
+
+@dataclass
+class VerifyStartResult:
+    flow: str  # 'onboarding' | 'login' | 'choose_document'
+    widget_url: Optional[str] = None
+    operation_id: Optional[str] = None
+    transaction_id: Optional[str] = None
+
+
+@dataclass
+class VerifyCompleteResult:
+    is_verified: bool
+
+
+@dataclass
+class PermissionsResult:
+    allowed: bool
+    allowed_tools: list[str] = field(default_factory=list)
+    denied_tools: list[str] = field(default_factory=list)
+    reason: Optional[str] = None
+
+    def has_permission(self, tool_name: str) -> bool:
+        if not self.allowed:
+            return False
+        if not self.allowed_tools or "ALL" in self.allowed_tools:
+            return True
+        return tool_name in self.allowed_tools
+
+
+_ENV_URLS: dict[str, dict[str, str]] = {
+    "production": {
+        "ait": "https://ait-service.nxtlinq.ai",
+        "dashboard": "https://dashboard.nxtlinq.ai",
+    },
+    "staging": {
+        "ait": "https://staging-ait-service.nxtlinq.ai",
+        "dashboard": "https://dashboard-staging.nxtlinq.ai",
+    },
+}
+
+
+class NxtidSDK:
+    """
+    nxtID Python SDK.
+
+    Provides wallet connection, AuthID identity verification, and AIT
+    permission checks.
+
+    Usage::
+
+        sdk = NxtidSDK(
+            api_key="...",
+            api_secret="...",
+            env="production",        # "production" (default) or "staging"
+            service_id="your-service-id",  # optional, for log_chat
+        )
+
+        # Register tools on startup
+        await sdk.register_tools([{"name": "transfer_funds", "description": "..."}])
+
+        # Connect wallet
+        wallet = await sdk.connect_wallet(email="user@example.com")
+
+        # Start IDV (returns widget URL for the user to complete)
+        verify = await sdk.start_verification(wallet.wallet_address, id_type="40")
+
+        # After user completes the widget:
+        result = await sdk.complete_verification(
+            wallet.wallet_address,
+            operation_id=verify.operation_id,
+        )
+
+        # Check AIT permissions
+        perms = await sdk.get_permissions(wallet.wallet_address)
+        if perms.has_permission("transfer_funds"):
+            ...
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_secret: str,
+        env: str = "production",
+        service_id: Optional[str] = None,
+    ) -> None:
+        if env not in _ENV_URLS:
+            raise ValueError(f"env must be 'production' or 'staging', got '{env}'")
+        urls = _ENV_URLS[env]
+        self._base_url = urls["ait"]
+        self._dashboard_url = urls["dashboard"]
+        self._service_id = service_id
+        self._headers = {
+            "x-api-key": api_key,
+            "x-api-secret": api_secret,
+            "Content-Type": "application/json",
+        }
+
+    def _url(self, path: str) -> str:
+        return f"{self._base_url}{path}"
+
+    def _dashboard_api_url(self, path: str) -> str:
+        if not self._dashboard_url:
+            raise ValueError("dashboard_url is required for this operation")
+        return f"{self._dashboard_url}{path}"
+
+    # ── Wallet ────────────────────────────────────────────────────────────────
+
+    async def connect_wallet(self, email: str) -> WalletResult:
+        """Get (or create) a MetaKeep-managed wallet for the given email."""
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(
+                self._url("/api/wallet/connect"),
+                json={"email": email},
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        data = resp.json()
+        return WalletResult(wallet_address=data["walletAddress"], email=data["email"])
+
+    # ── Verification ──────────────────────────────────────────────────────────
+
+    async def start_verification(
+        self,
+        wallet_address: str,
+        id_type: Optional[str] = None,
+    ) -> VerifyStartResult:
+        """
+        Start AuthID identity verification.
+
+        Returns a widget URL for the user to open in a browser or iframe.
+        - Returning users:  flow='login'          (face scan)
+        - New users:        flow='onboarding'      (document capture, id_type required)
+        - New users w/o id_type: flow='choose_document' (prompt user to pick)
+        """
+        body: dict = {"walletAddress": wallet_address}
+        if id_type:
+            body["idType"] = id_type
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(
+                self._url("/api/verify/start"),
+                json=body,
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        data = resp.json()
+        return VerifyStartResult(
+            flow=data["flow"],
+            widget_url=data.get("widgetUrl"),
+            operation_id=data.get("operationId"),
+            transaction_id=data.get("transactionId"),
+        )
+
+    async def complete_verification(
+        self,
+        wallet_address: str,
+        operation_id: Optional[str] = None,
+        transaction_id: Optional[str] = None,
+    ) -> VerifyCompleteResult:
+        """
+        Call after the user completes the AuthID widget.
+
+        Pass operation_id (onboarding flow) or transaction_id (login flow)
+        from the VerifyStartResult.
+        """
+        body: dict = {"walletAddress": wallet_address}
+        if operation_id:
+            body["operationId"] = operation_id
+        if transaction_id:
+            body["transactionId"] = transaction_id
+
+        # Generous timeout: complete_verification polls AuthID for up to 60s
+        async with httpx.AsyncClient(timeout=90.0) as client:
+            resp = await client.post(
+                self._url("/api/verify/complete"),
+                json=body,
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        data = resp.json()
+        return VerifyCompleteResult(is_verified=data["isVerified"])
+
+    # ── Permissions ───────────────────────────────────────────────────────────
+
+    async def set_permissions(
+        self,
+        wallet_address: str,
+        permissions: list[str],
+        granted_by: Optional[str] = None,
+    ) -> dict:
+        """
+        Create an AIT on-chain with the given permissions for wallet_address.
+
+        requested_by: email or identifier of whoever triggered this request —
+                      stored in the AIT record for audit purposes. Optional;
+                      existing callers that omit it are unaffected.
+        """
+        body: dict = {"address": wallet_address, "permissions": permissions}
+        if granted_by:
+            body["grantedBy"] = granted_by
+
+        async with httpx.AsyncClient(timeout=60.0) as client:
+            resp = await client.post(
+                self._url("/api/ait/set-permissions"),
+                json=body,
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        return resp.json()
+
+    async def get_admin_granted_tools(self, wallet_address: str) -> list[str]:
+        """
+        Return the tools admin has pre-approved for this user to self-service request.
+
+        Empty list means admin hasn't granted this user any tools yet — the caller
+        should show "waiting for administrator" rather than checkboxes.
+        """
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.get(
+                self._url("/api/agent/permissions"),
+                params={"walletAddress": wallet_address},
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        return resp.json().get("allowedTools", [])
+
+    async def get_permissions(self, wallet_address: str) -> PermissionsResult:
+        """Query admin-granted AIT tool permissions for the given wallet address."""
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.get(
+                self._url("/api/agent/user-permission"),
+                params={"walletAddress": wallet_address},
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        data = resp.json()
+        return PermissionsResult(
+            allowed=data.get("allowed", False),
+            allowed_tools=data.get("allowedTools", []),
+            denied_tools=data.get("deniedTools", []),
+            reason=data.get("reason"),
+        )
+
+    # ── Agent management ─────────────────────────────────────────────────────
+
+    async def register_tools(self, tools: list) -> int:
+        """
+        Register this agent's tool list with nxtlinq so admins can grant permissions.
+
+        Call once at agent startup. Each tool should be a dict with 'name' and
+        optionally 'description'.
+
+        Returns the number of tools registered.
+
+        Usage::
+
+            tool_count = await sdk.register_tools([
+                {"name": "transfer_funds", "description": "Move money between accounts"},
+                {"name": "get_account_balance", "description": "Read-only finance access"},
+            ])
+        """
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            resp = await client.post(
+                self._url("/api/agent/tools"),
+                json={"tools": tools},
+                headers=self._headers,
+            )
+        _raise_for_status(resp)
+        return resp.json().get("toolCount", len(tools))
+
+    async def log_chat(
+        self,
+        session_id: str,
+        user_message: str,
+        assistant_message: str,
+        external_user_id: str,
+        user_name: str,
+        model: str = "",
+        has_tool_call: bool = False,
+        tool_name: str = "",
+        turn_index: Optional[int] = None,
+    ) -> None:
+        """
+        Send one conversation turn to the nxtlinq Dashboard for monitoring.
+
+        Requires dashboard_url and service_id to be set at SDK init time.
+        Fails silently — chat logging is non-fatal.
+
+        Usage::
+
+            await sdk.log_chat(
+                session_id="abc123",
+                user_message="What's my balance?",
+                assistant_message="Your balance is $500.",
+                external_user_id="user@example.com",
+                user_name="Alice",
+                has_tool_call=True,
+                tool_name="get_account_balance",
+            )
+        """
+        if not self._dashboard_url or not self._service_id:
+            return
+        payload: dict = {
+            "aiType": model,
+            "hasToolCall": has_tool_call,
+            "toolName": tool_name,
+            "userInfo": {
+                "externalUserId": external_user_id,
+                "userName": user_name,
+            },
+            "chatHistory": {
+                "externalChatHistoryId": session_id,
+                "userMessage": user_message,
+                "assistantMessage": assistant_message,
+            },
+        }
+        if turn_index is not None:
+            payload["chatHistory"]["externalTurnIndex"] = turn_index
+        try:
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                await client.post(
+                    self._dashboard_api_url(f"/api/service/{self._service_id}/external-service-call-log"),
+                    json=payload,
+                    headers=self._headers,
+                )
+        except Exception:
+            pass
+

nxtid_sdk/entra.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+
+class EntraAuth:
+    """
+    Optional Microsoft Entra SSO module for the nxtID SDK.
+
+    When enabled, mounts two FastAPI routes onto the host app:
+      GET  /auth/entra/config  — returns client_id/tenant_id for MSAL
+      POST /auth/entra         — receives MSAL token claims, writes session state
+
+    Usage::
+
+        from nxtid_sdk import EntraAuth
+
+        entra = EntraAuth(
+            client_id="...",
+            tenant_id="...",
+            get_session=get_or_create_session,   # callable: session_id -> Session
+        )
+        entra.mount(app)                         # app is a FastAPI instance
+
+        # Check if enabled
+        if entra.enabled:
+            ...
+    """
+
+    def __init__(
+        self,
+        client_id: Optional[str],
+        tenant_id: Optional[str],
+        get_session,
+    ) -> None:
+        self._client_id = client_id or ""
+        self._tenant_id = tenant_id or ""
+        self._get_session = get_session
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self._client_id and self._tenant_id)
+
+    def mount(self, app) -> None:
+        """Mount /auth/entra/config and /auth/entra routes onto a FastAPI app."""
+        router = self._build_router()
+        app.include_router(router)
+
+    def _build_router(self) -> APIRouter:
+        router = APIRouter()
+        client_id = self._client_id
+        tenant_id = self._tenant_id
+        enabled = self.enabled
+        get_session = self._get_session
+
+        class _EntraAuthRequest(BaseModel):
+            session_id: str
+            name: str
+            email: str
+            tenant_id: Optional[str] = None
+            roles: List[str] = []
+
+        @router.get("/auth/entra/config")
+        async def entra_config() -> dict:
+            return {
+                "enabled": enabled,
+                "client_id": client_id,
+                "tenant_id": tenant_id,
+            }
+
+        @router.post("/auth/entra")
+        async def auth_entra(req: _EntraAuthRequest) -> dict:
+            session = get_session(req.session_id)
+            session.entra_authenticated = True
+            session.entra_name = req.name
+            session.entra_email = req.email
+            session.entra_tenant_id = req.tenant_id
+            session.entra_roles = req.roles
+            return {
+                "session_id": session.session_id,
+                "entra_authenticated": True,
+                "name": req.name,
+                "email": req.email,
+                "roles": req.roles,
+            }
+
+        return router

nxtid_sdk/exceptions.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+
+class ToolCallBlockedError(Exception):
+    """
+    Raised to block a tool execution before it reaches the LLM tool handler.
+
+    reason: 'verification_required' | 'permission_denied'
+    message: user-facing explanation
+    """
+
+    def __init__(self, reason: str, message: str) -> None:
+        self.reason = reason
+        self.message = message
+
+    @classmethod
+    def permission_denied(cls, tool_name: str, allowed_tools: list[str]) -> "ToolCallBlockedError":
+        tools_str = ", ".join(allowed_tools) if allowed_tools else "none"
+        return cls(
+            "permission_denied",
+            f"You don't have permission to use '{tool_name}'. "
+            f"Your current permissions: [{tools_str}]. "
+            "Contact your administrator.",
+        )

nxtid_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: nxtid-sdk
+Version: 0.1.0
+Summary: nxtID Python SDK — AIT-gated AI agent tool permissions
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27

nxtid_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+nxtid_sdk/__init__.py,sha256=AfqMHUgVM3Co__RV75hYLp6LrNL9Cd_5mmTB2yKcXKw,164
+nxtid_sdk/client.py,sha256=tSt8-2ThR0Tg1s3LjQij7d9eI-18VbhMfmt1LR7Pg4Y,12477
+nxtid_sdk/entra.py,sha256=-JrQMuiySH-oxKZG5-_fxcmVks1ibZx6_Lw4WxkkyzM,2707
+nxtid_sdk/exceptions.py,sha256=rX8xPS6q0-JyBMMIlzVqlJfKSFI1seNK1TyQs0o2BJ0,804
+nxtid_sdk-0.1.0.dist-info/METADATA,sha256=uCV3DhntSLVS4Kk2HhEUG6prMN6hT5xQxcipFkmD0Ak,170
+nxtid_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nxtid_sdk-0.1.0.dist-info/top_level.txt,sha256=6iYVrtyl5MlEgcQpmR1EXAkEamhhEA6KTQjHvD94eA8,10
+nxtid_sdk-0.1.0.dist-info/RECORD,,

nxtid_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nxtid_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nxtid_sdk