agentvisa-fastapi 0.1.0__py3-none-any.whl

agentvisa_fastapi/__init__.py

@@ -0,0 +1,42 @@
+"""
+agentvisa-fastapi — AgentVisa verification middleware for FastAPI.
+
+Quick start:
+
+    from agentvisa_fastapi import AgentVisaConfig, AgentVisaMiddleware, require_agentvisa
+
+    config = AgentVisaConfig(
+        api_key="your_widget_api_key",   # server-side only
+        widget_id="your_widget_id",       # from your AgentVisa dashboard
+    )
+
+    # Option A: middleware (enriches all requests, doesn't block)
+    app.add_middleware(AgentVisaMiddleware, config=config)
+
+    # Option B: per-route dependency (blocks unverified agents with 401)
+    @app.get("/protected")
+    async def handler(av=Depends(require_agentvisa(config))):
+        return {"verified": True, "plan": av.plan}
+
+    # Option C: both (recommended — middleware caches result, dependency enforces)
+    app.add_middleware(AgentVisaMiddleware, config=config)
+
+    @app.get("/protected")
+    async def handler(av=Depends(require_agentvisa(config))):
+        return {"plan": av.plan, "human_name": av.human_name}
+"""
+
+from .config import AgentVisaConfig
+from .middleware import AgentVisaMiddleware
+from .dependencies import get_agentvisa, require_agentvisa
+from .models import AgentVisaResult
+
+__all__ = [
+    "AgentVisaConfig",
+    "AgentVisaMiddleware",
+    "get_agentvisa",
+    "require_agentvisa",
+    "AgentVisaResult",
+]
+
+__version__ = "0.1.0"

agentvisa_fastapi/client.py

@@ -0,0 +1,44 @@
+"""
+Async HTTP client for POST /v1/verify.
+Uses httpx with a shared client for connection pooling.
+"""
+from __future__ import annotations
+import httpx
+from .config import AgentVisaConfig
+from .models import AgentVisaResult
+
+
+async def verify_token(
+    token: str,
+    config: AgentVisaConfig,
+    human_assertion: str | None = None,
+) -> AgentVisaResult:
+    """
+    Call POST /v1/verify and return a parsed AgentVisaResult.
+    Never raises — returns AgentVisaResult.error() on any network/API failure.
+    """
+    url = f"{config.api_base}/v1/verify"
+    params: dict = {"token": token, "widget_id": config.widget_id}
+    if human_assertion is not None:
+        params["human_assertion"] = human_assertion
+
+    try:
+        async with httpx.AsyncClient(timeout=config.timeout) as client:
+            response = await client.post(
+                url,
+                params=params,
+                headers={"X-Widget-Api-Key": config.api_key},
+            )
+            if response.status_code == 401:
+                return AgentVisaResult.error("invalid_api_key")
+            if response.status_code == 404:
+                return AgentVisaResult.error("invalid_widget")
+            if not response.is_success:
+                return AgentVisaResult.error(f"api_error_{response.status_code}")
+
+            return AgentVisaResult.from_api(response.json())
+
+    except httpx.TimeoutException:
+        return AgentVisaResult.error("verification_timeout")
+    except Exception:
+        return AgentVisaResult.error("verification_error")

agentvisa_fastapi/config.py

@@ -0,0 +1,30 @@
+"""
+AgentVisa configuration — holds the Widget Holder's credentials.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+
+@dataclass
+class AgentVisaConfig:
+    """
+    Configuration for the AgentVisa middleware and dependencies.
+
+    Args:
+        api_key:    Your Widget Holder API key (X-Widget-Api-Key).
+                    Keep this server-side only — never expose in client code.
+        widget_id:  Your widget ID (public, from your AgentVisa dashboard).
+        api_base:   Override the AgentVisa API base URL (default: https://api.agentvisa.ai).
+        timeout:    HTTP timeout in seconds for /v1/verify calls (default: 5).
+    """
+    api_key: str
+    widget_id: str
+    api_base: str = "https://api.agentvisa.ai"
+    timeout: float = 5.0
+
+    def __post_init__(self):
+        if not self.api_key:
+            raise ValueError("AgentVisaConfig: api_key is required")
+        if not self.widget_id:
+            raise ValueError("AgentVisaConfig: widget_id is required")
+        self.api_base = self.api_base.rstrip("/")

agentvisa_fastapi/dependencies.py

@@ -0,0 +1,92 @@
+"""
+FastAPI dependencies for AgentVisa verification.
+
+Two options:
+
+1. get_agentvisa(config) — returns the result, never blocks.
+   Use when you want to check verification status yourself.
+
+2. require_agentvisa(config) — returns the result OR raises HTTP 401.
+   Use when the route must be verified to proceed.
+
+Both work with or without AgentVisaMiddleware installed.
+If the middleware is present, the cached result is reused (no second API call).
+If not, the dependency calls /v1/verify itself.
+"""
+from __future__ import annotations
+from fastapi import Depends, HTTPException, Request
+from .config import AgentVisaConfig
+from .client import verify_token
+from .models import AgentVisaResult
+
+
+def get_agentvisa(config: AgentVisaConfig):
+    """
+    FastAPI dependency — returns AgentVisaResult, never raises.
+
+    Usage:
+        @app.get("/my-route")
+        async def handler(av: AgentVisaResult = Depends(get_agentvisa(config))):
+            if av.valid:
+                ...
+    """
+    async def _dependency(request: Request) -> AgentVisaResult:
+        # If middleware already ran, reuse its result
+        existing = getattr(request.state, "agentvisa", None)
+        if existing is not None:
+            return existing
+
+        token = request.headers.get("X-AgentVisa-Token")
+        if not token:
+            return AgentVisaResult.not_present()
+
+        return await verify_token(token, config)
+
+    return _dependency
+
+
+def require_agentvisa(config: AgentVisaConfig):
+    """
+    FastAPI dependency — returns AgentVisaResult or raises HTTP 401.
+
+    Usage:
+        @app.get("/protected")
+        async def handler(av: AgentVisaResult = Depends(require_agentvisa(config))):
+            # Only reaches here if av.valid is True
+            return {"human_name": av.human_name}
+    """
+    async def _dependency(
+        result: AgentVisaResult = Depends(get_agentvisa(config)),
+    ) -> AgentVisaResult:
+        if not result.valid:
+            reason = result.reason
+
+            # Tell the agent what it needs to do next
+            if reason == "token_not_present":
+                raise HTTPException(
+                    status_code=401,
+                    detail="AgentVisa token required",
+                    headers={"X-AgentVisa-Required": config.widget_id},
+                )
+            if reason == "reverification_required":
+                raise HTTPException(
+                    status_code=401,
+                    detail="AgentVisa reverification required — check email",
+                    headers={"X-AgentVisa-Required": config.widget_id},
+                )
+            if reason in ("expired", "revoked"):
+                raise HTTPException(
+                    status_code=401,
+                    detail=f"AgentVisa token {reason}",
+                    headers={"X-AgentVisa-Required": config.widget_id},
+                )
+
+            raise HTTPException(
+                status_code=401,
+                detail=f"AgentVisa verification failed: {reason}",
+                headers={"X-AgentVisa-Required": config.widget_id},
+            )
+
+        return result
+
+    return _dependency

agentvisa_fastapi/middleware.py

@@ -0,0 +1,47 @@
+"""
+AgentVisa Starlette middleware.
+
+Reads X-AgentVisa-Token from the request, calls /v1/verify,
+and injects the result into request.state.agentvisa.
+
+Does NOT block requests — use the require_agentvisa dependency for that.
+This lets you enrich all requests and make per-route decisions.
+"""
+from __future__ import annotations
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+from .config import AgentVisaConfig
+from .client import verify_token
+from .models import AgentVisaResult
+
+
+class AgentVisaMiddleware(BaseHTTPMiddleware):
+    """
+    Drop-in Starlette/FastAPI middleware.
+
+    Usage:
+        app.add_middleware(
+            AgentVisaMiddleware,
+            config=AgentVisaConfig(api_key="...", widget_id="..."),
+        )
+
+    After adding, every request will have request.state.agentvisa set
+    to an AgentVisaResult. No requests are blocked — use require_agentvisa
+    as a dependency on individual routes to enforce verification.
+    """
+
+    def __init__(self, app, config: AgentVisaConfig):
+        super().__init__(app)
+        self.config = config
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        token = request.headers.get("X-AgentVisa-Token")
+
+        if token:
+            result = await verify_token(token, self.config)
+        else:
+            result = AgentVisaResult.not_present()
+
+        request.state.agentvisa = result
+        return await call_next(request)

agentvisa_fastapi/models.py

@@ -0,0 +1,71 @@
+"""
+AgentVisa result models — mirroring the /v1/verify response schema.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal, Optional
+
+
+@dataclass
+class AgentVisaResult:
+    """
+    The parsed response from POST /v1/verify.
+    Injected into request.state.agentvisa by the middleware.
+    """
+    # Always present
+    valid: bool
+    reason: str
+    plan: str
+    widget_id: str
+
+    # Present on valid tokens
+    verified_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+
+    # Pro plan metadata
+    human_name: Optional[str] = None
+    five_factor: Optional[Literal["y", "n"]] = None
+    age_over_18: Optional[Literal["y", "n", "null"]] = None
+    age_over_21: Optional[Literal["y", "n", "null"]] = None
+    multiple_agents_authorized: Optional[Literal["y", "n"]] = None
+    verifications_today: Optional[int] = None
+
+    # Set when no token was present in the request at all
+    skipped: bool = False
+
+    @classmethod
+    def from_api(cls, data: dict) -> "AgentVisaResult":
+        """Build from the raw /v1/verify JSON response."""
+        def parse_dt(val: Optional[str]) -> Optional[datetime]:
+            if not val:
+                return None
+            try:
+                return datetime.fromisoformat(val.replace("Z", "+00:00"))
+            except Exception:
+                return None
+
+        return cls(
+            valid=data.get("valid", False),
+            reason=data.get("reason", "unknown"),
+            plan=data.get("plan", "basic"),
+            widget_id=data.get("widget_id", ""),
+            verified_at=parse_dt(data.get("verified_at")),
+            expires_at=parse_dt(data.get("expires_at")),
+            human_name=data.get("human_name"),
+            five_factor=data.get("five_factor"),
+            age_over_18=data.get("age_over_18"),
+            age_over_21=data.get("age_over_21"),
+            multiple_agents_authorized=data.get("multiple_agents_authorized"),
+            verifications_today=data.get("verifications_today"),
+        )
+
+    @classmethod
+    def not_present(cls) -> "AgentVisaResult":
+        """Returned when no X-AgentVisa-Token header was in the request."""
+        return cls(valid=False, reason="token_not_present", plan="basic", widget_id="", skipped=True)
+
+    @classmethod
+    def error(cls, reason: str = "verification_error") -> "AgentVisaResult":
+        """Returned when the /v1/verify call itself failed."""
+        return cls(valid=False, reason=reason, plan="basic", widget_id="")

agentvisa_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: agentvisa-fastapi
+Version: 0.1.0
+Summary: FastAPI middleware for AgentVisa AI agent verification
+Author-email: AgentVisa <info@agentvisa.ai>
+License: MIT License
+        
+        Copyright (c) 2026 AgentVisa
+        
+        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.
+        
+Project-URL: Homepage, https://agentvisa.ai
+Project-URL: Repository, https://github.com/AgentVisa-ai/agentvisa-fastapi
+Project-URL: Documentation, https://agentvisa.ai/docs
+Project-URL: Bug Tracker, https://github.com/AgentVisa-ai/agentvisa-fastapi/issues
+Keywords: agentvisa,fastapi,middleware,ai-agent,verification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: starlette>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Dynamic: license-file
+
+# agentvisa-fastapi
+
+FastAPI middleware for [AgentVisa](https://agentvisa.ai) — verify that incoming AI agents were authorized by a real, 5-factor biometric-verified human before granting access.
+
+## Install
+
+```bash
+pip install agentvisa-fastapi
+```
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Depends
+from agentvisa_fastapi import AgentVisaConfig, AgentVisaMiddleware, require_agentvisa
+
+app = FastAPI()
+
+config = AgentVisaConfig(
+    api_key=os.environ["AGENTVISA_API_KEY"],   # your Widget Holder API key — server-side only
+    widget_id=os.environ["AGENTVISA_WIDGET_ID"],  # from your AgentVisa dashboard
+)
+
+# Add middleware — enriches every request with request.state.agentvisa
+app.add_middleware(AgentVisaMiddleware, config=config)
+
+# Protected route — agents without a valid AgentVisa token get 401
+@app.get("/api/orders")
+async def get_orders(av=Depends(require_agentvisa(config))):
+    return {"orders": [...], "verified_human": av.human_name}
+
+# Unprotected route — check manually if you want soft enforcement
+@app.get("/api/public")
+async def public(request: Request):
+    av = request.state.agentvisa
+    if av.valid:
+        return {"message": "Hello, verified agent!", "plan": av.plan}
+    return {"message": "Hello — consider getting an AgentVisa for full access."}
+```
+
+## How it works
+
+When an AI agent hits your site, AgentVisa requires a two-step handshake:
+
+1. **Your server returns 401** with `X-AgentVisa-Required: your_widget_id` — this middleware does that automatically via `require_agentvisa`.
+2. **The agent calls AgentVisa** to get a short-lived TemporaryToken scoped to your site.
+3. **The agent retries** with `X-AgentVisa-Token: tmp_...` in the header.
+4. **This middleware calls `/v1/verify`** with your API key and returns the result.
+
+The human behind the agent completed 5-factor biometric verification (email, phone, cross-verification, Face ID / Touch ID, and a human assertion) when they got their AgentVisa.
+
+## Configuration
+
+```python
+AgentVisaConfig(
+    api_key="wk_...",            # required — your Widget Holder API key
+    widget_id="wgt_...",         # required — your widget ID
+    api_base="https://api.agentvisa.ai",  # optional — override for self-hosted
+    timeout=5.0,                 # optional — /v1/verify timeout in seconds
+)
+```
+
+**Security note:** Never expose `api_key` in client-side code, environment variables that get bundled, or logs. Treat it like a database password.
+
+## AgentVisaResult fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `valid` | `bool` | Whether the agent is verified |
+| `reason` | `str` | `"ok"`, `"invalid"`, `"expired"`, `"revoked"`, `"reverification_required"`, `"token_not_present"` |
+| `plan` | `str` | `"basic"` or `"pro"` |
+| `widget_id` | `str` | Your widget ID |
+| `verified_at` | `datetime \| None` | When the token was issued |
+| `expires_at` | `datetime \| None` | When the token expires |
+| `human_name` | `str \| None` | Pro plan only |
+| `five_factor` | `"y" \| "n" \| None` | Pro plan only |
+| `age_over_18` | `"y" \| "n" \| "null" \| None` | Pro plan only |
+| `age_over_21` | `"y" \| "n" \| "null" \| None` | Pro plan only |
+| `multiple_agents_authorized` | `"y" \| "n" \| None` | Pro plan only |
+| `verifications_today` | `int \| None` | Pro plan only |
+| `skipped` | `bool` | True when no token was in the request |
+
+## Using without the middleware
+
+If you don't want to add middleware, use the dependency standalone — it will call `/v1/verify` directly:
+
+```python
+from agentvisa_fastapi import AgentVisaConfig, require_agentvisa
+
+config = AgentVisaConfig(api_key="...", widget_id="...")
+
+@app.post("/checkout")
+async def checkout(av=Depends(require_agentvisa(config))):
+    # verified agents only
+    ...
+```
+
+## Using get_agentvisa for soft enforcement
+
+```python
+from agentvisa_fastapi import AgentVisaConfig, get_agentvisa, AgentVisaResult
+
+config = AgentVisaConfig(api_key="...", widget_id="...")
+
+@app.get("/search")
+async def search(av: AgentVisaResult = Depends(get_agentvisa(config))):
+    results = perform_search()
+    if not av.valid:
+        # Return limited results for unverified agents
+        return {"results": results[:3], "note": "Get an AgentVisa for full results"}
+    return {"results": results}
+```
+
+## Reverification
+
+When an agent's daily verification limit is hit, `/v1/verify` returns `reason: "reverification_required"`. This middleware propagates that reason in the 401 response so your users know to check their email.
+
+The `require_agentvisa` dependency returns:
+```
+HTTP 401
+X-AgentVisa-Required: your_widget_id
+{"detail": "AgentVisa reverification required — check email"}
+```
+
+The AgentVisa MCP server handles this automatically — it calls `POST /v1/holder/reverify` to trigger the re-verification email without the human needing to intervene.
+
+## License
+
+MIT

agentvisa_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agentvisa_fastapi/__init__.py,sha256=-IYxB2Q4cjIZeTCLAwbjDlcyoU8uRhdJyx2ttLpNE7c,1323
+agentvisa_fastapi/client.py,sha256=HBv5nmXajTCTn7jj9MKY4ywUsppZy8EHhYJud8C51OI,1540
+agentvisa_fastapi/config.py,sha256=N9g-fD-WGPZzc1V9ljnuSdwFwUTlIfrbQp-AcTCPnGo,1062
+agentvisa_fastapi/dependencies.py,sha256=7mT265uhfloIIREA2uXtp9JHLH2OlKIMAEWwFYZ4htI,3133
+agentvisa_fastapi/middleware.py,sha256=4YcDovZ4g-Li-KR30mOoaGvQxWtI3WQcPypZeeKAuxA,1512
+agentvisa_fastapi/models.py,sha256=8DyFugHdQEIOrX2qnx0XTieAoHN3SllucqG7VOs47mA,2560
+agentvisa_fastapi-0.1.0.dist-info/licenses/LICENSE,sha256=2ZWgZFz10QZvvgGbDGi58YRqYwa7fClyV4ryle_u3fs,1066
+agentvisa_fastapi-0.1.0.dist-info/METADATA,sha256=YB4bSB4HKwllNxWDIdgkJfWSuEgPoJimfUu5KU0vldY,7476
+agentvisa_fastapi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentvisa_fastapi-0.1.0.dist-info/top_level.txt,sha256=QblYKfRccBIqklfxQ7rqeolfg3XL5U3r8-th0-QCj0c,18
+agentvisa_fastapi-0.1.0.dist-info/RECORD,,

agentvisa_fastapi-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
+

agentvisa_fastapi-0.1.0.dist-info/licenses/LICENSE

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

agentvisa_fastapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentvisa_fastapi