access402-fastapi 0.3.0__tar.gz → 0.4.0__tar.gz

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: access402-fastapi
-Version: 0.3.0
+Version: 0.4.0
 Summary: Managed Access402 x402 v2 protection for FastAPI
 Project-URL: Homepage, https://access402.com
 Project-URL: Documentation, https://access402.com/docs/fastapi/get-started
@@ -64,6 +64,9 @@ access402 = Access402.from_env()
     price="0.05",
     access_type="per_request",
     description="Read one premium report",
+    discovery_enabled=True,
+    representative_queries=("Read report 42", "Get a premium research report"),
+    capabilities=("x402", "research"),
 )
 async def report(report_id: str):
     return {"id": report_id, "result": "..."}
@@ -71,6 +74,12 @@ async def report(report_id: str):
 access402.install(app)
 ```
 
+Live discoverable routes are published in an ARD 0.91 manifest at
+`/.well-known/ard.json`; `/.well-known/ai-catalog.json` is retained as a
+compatibility path. Each entry includes the route's media type, canonical URL,
+representative queries, capabilities, and Access402 payment metadata. Sandbox
+manifests remain valid but intentionally contain no public entries.
+
 On startup, the adapter authenticates the installation, uploads only decorated payment policies, and downloads HMAC-authenticated configuration. The configuration is cached in memory and refreshed periodically; payment requests go directly to the Access402 settlement function. No CDP credential is installed in this package.
 
 The dashboard displays a read-only mirror of code-owned policies and the mode reported by the deployment. The FastAPI environment controls the payment network, while protected routes fail closed if Access402 cannot confirm a matching server-side policy.

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/README.md

@@ -35,6 +35,9 @@ access402 = Access402.from_env()
     price="0.05",
     access_type="per_request",
     description="Read one premium report",
+    discovery_enabled=True,
+    representative_queries=("Read report 42", "Get a premium research report"),
+    capabilities=("x402", "research"),
 )
 async def report(report_id: str):
     return {"id": report_id, "result": "..."}
@@ -42,6 +45,12 @@ async def report(report_id: str):
 access402.install(app)
 ```
 
+Live discoverable routes are published in an ARD 0.91 manifest at
+`/.well-known/ard.json`; `/.well-known/ai-catalog.json` is retained as a
+compatibility path. Each entry includes the route's media type, canonical URL,
+representative queries, capabilities, and Access402 payment metadata. Sandbox
+manifests remain valid but intentionally contain no public entries.
+
 On startup, the adapter authenticates the installation, uploads only decorated payment policies, and downloads HMAC-authenticated configuration. The configuration is cached in memory and refreshed periodically; payment requests go directly to the Access402 settlement function. No CDP credential is installed in this package.
 
 The dashboard displays a read-only mirror of code-owned policies and the mode reported by the deployment. The FastAPI environment controls the payment network, while protected routes fail closed if Access402 cannot confirm a matching server-side policy.

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "access402-fastapi"
-version = "0.3.0"
+version = "0.4.0"
 description = "Managed Access402 x402 v2 protection for FastAPI"
 readme = "README.md"
 requires-python = ">=3.10"

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/src/access402_fastapi/adapter.py

@@ -2,13 +2,14 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import hashlib
 import inspect
 import json
 import logging
 import os
 import time
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 from decimal import Decimal, InvalidOperation
 from typing import Any, Awaitable, Callable
@@ -16,11 +17,13 @@ from urllib.parse import quote, urlsplit
 
 import httpx
 from fastapi import FastAPI
+from fastapi.responses import JSONResponse
 from fastapi.routing import APIRoute
 
 from .client import Access402Client, stable_hash
 from .models import Configuration, ResourcePolicy
 from .security import canonical_request_path, sign_grant, template_matches, valid_grant
+from .ard import ARD_COMPATIBILITY_PATH, ARD_PATH, build_manifest
 
 BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
@@ -38,6 +41,8 @@ class CodePolicy:
     description: str | None
     discovery_enabled: bool
     discovery_input_example: dict[str, Any]
+    representative_queries: tuple[str, ...]
+    capabilities: tuple[str, ...]
 
 
 @dataclass(frozen=True)
@@ -52,7 +57,7 @@ class Access402Settings:
     stale_after_seconds: int = 900
     fail_closed: bool = True
     cors_allow_origin: str = "*"
-    excluded_paths: tuple[str, ...] = ("/health", "/docs", "/redoc", "/openapi.json")
+    excluded_paths: tuple[str, ...] = ("/health", "/docs", "/redoc", "/openapi.json", ARD_PATH, ARD_COMPATIBILITY_PATH)
 
     @classmethod
     def from_env(cls) -> "Access402Settings":
@@ -104,6 +109,8 @@ class Access402:
         description: str | None = None,
         discovery_enabled: bool = False,
         discovery_input_example: dict[str, Any] | None = None,
+        representative_queries: tuple[str, ...] | list[str] | None = None,
+        capabilities: tuple[str, ...] | list[str] | None = None,
     ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
         """Declare an Access402 payment policy on a FastAPI endpoint."""
         try:
@@ -123,6 +130,12 @@ class Access402:
             raise ValueError("Access402 description must be 1 to 4000 characters")
         if not isinstance(discovery_input_example or {}, dict):
             raise ValueError("discovery_input_example must be a JSON object")
+        normalized_queries = tuple(item.strip() for item in (representative_queries or ()) if isinstance(item, str))
+        if representative_queries is not None and (len(normalized_queries) < 2 or len(normalized_queries) > 5 or any(len(item) < 3 or len(item) > 200 for item in normalized_queries)):
+            raise ValueError("representative_queries must contain 2 to 5 short strings")
+        normalized_capabilities = tuple(item.strip() for item in (capabilities or ()) if isinstance(item, str))
+        if capabilities is not None and (not normalized_capabilities or len(normalized_capabilities) > 20 or any(len(item) > 80 for item in normalized_capabilities)):
+            raise ValueError("capabilities must contain 1 to 20 short strings")
         policy = CodePolicy(
             price=format(normalized_price, "f"),
             access_type=access_type,
@@ -130,6 +143,8 @@ class Access402:
             description=description.strip() if description else None,
             discovery_enabled=discovery_enabled,
             discovery_input_example=discovery_input_example or {},
+            representative_queries=normalized_queries,
+            capabilities=normalized_capabilities,
         )
 
         def decorator(endpoint: Callable[..., Any]) -> Callable[..., Any]:
@@ -143,9 +158,47 @@ class Access402:
         # Build OpenAPI once at installation so invalid code-owned policy combinations
         # fail during application startup instead of on the first paid request.
         self.route_catalog()
+        async def ard_manifest() -> JSONResponse:
+            return JSONResponse(
+                self.ard_manifest(),
+                headers={"Cache-Control": "public, max-age=300", "Link": f'<{ARD_PATH}>; rel="ard"', "Access-Control-Allow-Origin": "*", "X-Content-Type-Options": "nosniff"},
+            )
+        app.add_api_route(ARD_PATH, ard_manifest, methods=["GET", "HEAD"], include_in_schema=False, name="access402_ard")
+        app.add_api_route(ARD_COMPATIBILITY_PATH, ard_manifest, methods=["GET", "HEAD"], include_in_schema=False, name="access402_ard_compatibility")
         app.router.add_event_handler("startup", self._startup_sync)
         app.add_middleware(Access402Middleware, manager=self)
 
+    def ard_manifest(self) -> dict[str, Any]:
+        if not self.app:
+            raise RuntimeError("Access402 is not installed on a FastAPI app")
+        schema = self.app.openapi()
+        resources: list[dict[str, Any]] = []
+        for route in self.app.routes:
+            if not isinstance(route, APIRoute):
+                continue
+            policy = getattr(route.endpoint, PROTECTED_POLICY_ATTRIBUTE, None)
+            if not isinstance(policy, CodePolicy):
+                continue
+            for method in sorted(route.methods or []):
+                operation = schema.get("paths", {}).get(route.path, {}).get(method.lower(), {})
+                responses = operation.get("responses", {})
+                success = next((value for key, value in responses.items() if str(key).startswith("2")), {})
+                output_content = success.get("content", {}) if isinstance(success, dict) else {}
+                resources.append({
+                    "operation_id": operation.get("operationId") or route.name,
+                    "display_name": operation.get("summary") or route.name or f"{method} {route.path}",
+                    "description": operation.get("description") or route.description or policy.description,
+                    "mime_type": next(iter(output_content), "application/json"),
+                    "url": f"{self.settings.public_base_url}{route.path}",
+                    "method": method,
+                    "price": policy.price,
+                    "access_type": policy.access_type,
+                    "discovery_enabled": policy.discovery_enabled,
+                    "representative_queries": policy.representative_queries,
+                    "capabilities": policy.capabilities,
+                })
+        return build_manifest(public_base_url=self.settings.public_base_url, mode=self.settings.mode, resources=resources)
+
     async def _startup_sync(self) -> None:
         try:
             await self.refresh(force=True)
@@ -304,6 +357,44 @@ class Access402Middleware:
                 return
             await self.app(scope, receive, send)
             return
+        headers = {key.decode("latin1").lower(): value.decode("latin1") for key, value in scope.get("headers", [])}
+        token = headers.get("x-access402-bootstrap", "")
+        try:
+            body = b""
+            if token:
+                if len(token) > 4096:
+                    raise ValueError("Bootstrap header too large")
+                async with asyncio.timeout(10):
+                    while True:
+                        chunk = await receive()
+                        if chunk["type"] != "http.request":
+                            raise ValueError("Bootstrap request disconnected")
+                        body += chunk.get("body", b"")
+                        if len(body) > 65536:
+                            raise ValueError("Bootstrap body too large")
+                        if not chunk.get("more_body"):
+                            break
+            request_url = self._challenge(configuration, policy, path)[0]["resource"]["url"]
+            query = scope.get("query_string", b"").decode("ascii")
+            if query:
+                request_url += "?" + query
+            gate = await self.manager.client.lifecycle(
+                policy, "live" if configuration.environment == "live" else "sandbox",
+                token=token, method=method, url=request_url,
+                body_hash=hashlib.sha256(body).hexdigest() if token else "",
+                payment=headers.get("payment-signature") or headers.get("x-payment", ""),
+            )
+            if gate["action"] == "respond":
+                await self._json(send, int(gate["status"]), gate["body"],
+                                 [(k.lower().encode(), v.encode()) for k, v in gate.get("headers", {}).items()])
+                return
+            if token or gate.get("lifecycle_state") != "active":
+                raise ValueError("Invalid active lifecycle")
+            policy = replace(policy, price=str(gate["configured_price"]))
+        except Exception:
+            await self._json(send, 503, {"error": "access402_lifecycle_unavailable"}, [(b"cache-control", b"private, no-store")])
+            return
+
         if self.manager.bypass:
             result = self.manager.bypass(scope)
             if await result if inspect.isawaitable(result) else result:

access402_fastapi-0.4.0/src/access402_fastapi/ard.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable
+from urllib.parse import urlsplit
+
+ARD_CONTEXT = "https://agenticresourcediscovery.org/context/v1"
+ARD_PATH = "/.well-known/ard.json"
+ARD_COMPATIBILITY_PATH = "/.well-known/ai-catalog.json"
+
+
+def _slug(value: str) -> str:
+    return re.sub(r"[^a-z0-9._-]+", "-", value.lower()).strip("-")[:100] or "resource"
+
+
+def build_manifest(*, public_base_url: str, mode: str, resources: Iterable[dict[str, Any]]) -> dict[str, Any]:
+    origin = urlsplit(public_base_url)
+    entries = []
+    if mode == "live":
+        for resource in resources:
+            if not resource.get("discovery_enabled"):
+                continue
+            display_name = str(resource["display_name"])
+            description = str(resource.get("description") or display_name)
+            queries = resource.get("representative_queries") or (
+                f"Use the {display_name} API",
+                f"Get {description.rstrip('.!?').lower()}",
+            )
+            entries.append({
+                "@context": ARD_CONTEXT,
+                "identifier": f"urn:air:{origin.hostname}:api:{_slug(str(resource['operation_id']))}",
+                "displayName": display_name,
+                "type": str(resource.get("mime_type") or "application/json"),
+                "url": str(resource["url"]),
+                "description": description,
+                "representativeQueries": list(queries),
+                "capabilities": list(resource.get("capabilities") or ("x402", "HTTP API")),
+                "metadata": {
+                    "access402.paymentProtocol": "x402",
+                    "access402.asset": "USDC",
+                    "access402.price": str(resource["price"]),
+                    "access402.method": str(resource["method"]),
+                    "access402.accessType": str(resource["access_type"]),
+                },
+            })
+    return {
+        "@context": ARD_CONTEXT,
+        "version": "0.91",
+        "publisher": {"name": origin.hostname, "url": f"{origin.scheme}://{origin.netloc}"},
+        "entries": entries,
+    }

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/src/access402_fastapi/client.py

@@ -21,7 +21,7 @@ class Access402Client:
         return {
             "Authorization": f"Bearer {self.api_key}", "Accept": "application/json",
             "X-Access402-Adapter-Version": "3", "X-Access402-Mode": mode,
-            "User-Agent": "Access402-FastAPI/0.3.0",
+            "User-Agent": "Access402-FastAPI/0.4.0",
         }
 
     async def close(self) -> None:
@@ -47,6 +47,18 @@ class Access402Client:
             raise ValueError("Invalid Access402 configuration")
         return Configuration(str(value.get("configuration_version")), str(value.get("generated_at")), environment, network, pay_to, resources)
 
+    async def lifecycle(self, policy: Any, mode: str, *, token: str = "", method: str = "", url: str = "", body_hash: str = "", payment: str = "") -> dict[str, Any]:
+        response = await self.http.post(
+            f"{self.base_url}/adapter/lifecycle", headers=self.headers(mode), timeout=40.0,
+            json={"rule_id": policy.local_rule_id, "bootstrap_token": token, "method": method,
+                  "url": url, "body_hash": body_hash, "payment_payload": payment},
+        )
+        response.raise_for_status()
+        result = response.json()
+        if result.get("action") not in ("active", "respond"):
+            raise ValueError("Invalid lifecycle response")
+        return result
+
     async def settle(self, policy: Any, payment: str, requirements: dict[str, Any], mode: str) -> dict[str, Any]:
         idempotency = hashlib.sha256(f"{policy.local_rule_id}|{payment}".encode()).hexdigest()
         response = await self.http.post(

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/src/access402_fastapi/models.py

@@ -24,6 +24,10 @@ class ResourcePolicy:
     route_method: str
     route_template: str
 
+    lifecycle_state: str = "active"
+    configured_price: str | None = None
+    effective_price: str | None = None
+
     @classmethod
     def from_dict(cls, value: dict[str, Any]) -> "ResourcePolicy":
         required = ("id", "local_rule_id", "resource_key", "resource_url", "route_method", "route_template")
@@ -33,6 +37,8 @@ class ResourcePolicy:
         if not isinstance(price, (str, int, float)) or not str(price):
             raise ValueError("Invalid Access402 resource policy price")
         return cls(
+            lifecycle_state=str(value.get("lifecycle_state", "active")),
+            configured_price=str(value.get("configured_price", price)), effective_price=str(value.get("effective_price", price)),
             id=value["id"], local_rule_id=value["local_rule_id"], resource_key=value["resource_key"],
             resource_url=value["resource_url"], display_name=str(value.get("display_name", "")),
             description=value.get("description") if isinstance(value.get("description"), str) else None,

{access402_fastapi-0.3.0 → access402_fastapi-0.4.0}/tests/test_adapter.py

@@ -31,6 +31,8 @@ def policy(**changes):
 
 def configured_app(handler=None, **policy_changes):
     async def backend(request: httpx.Request):
+        if request.url.path.endswith("/adapter/lifecycle"):
+            return httpx.Response(200, json={"action": "active", "lifecycle_state": "active", "configured_price": policy_changes.get("price", "0.01")})
         if handler:
             return await handler(request)
         return httpx.Response(200, json={"settled": True, "payer": "0xpayer", "payment_event_id": "33333333-3333-4333-8333-333333333333", "payment_response": "receipt"})
@@ -168,6 +170,40 @@ def test_rejects_invalid_code_owned_policy():
         manager.protect(price="0.0000001")
     with pytest.raises(ValueError, match="requires a positive"):
         manager.protect(price="0.01", access_type="time_limited")
+    with pytest.raises(ValueError, match="2 to 5"):
+        manager.protect(price="0.01", representative_queries=["Only one"])
+
+
+@pytest.mark.asyncio
+async def test_ard_manifest_publishes_live_discoverable_routes():
+    app = FastAPI()
+    manager = Access402(Access402Settings(
+        "installation", "a402_000000000000_" + "a" * 43, "https://weather.example", mode="live"
+    ))
+
+    @app.get("/forecast", summary="Local forecast")
+    @manager.protect(
+        price="0.01",
+        description="A hyper-local weather forecast",
+        discovery_enabled=True,
+        representative_queries=("Get a local forecast", "Check the weather for a trip"),
+        capabilities=("x402", "weather"),
+    )
+    async def forecast():
+        return {"temperature": 72}
+
+    manager.install(app)
+    manifest = manager.ard_manifest()
+    assert manifest["version"] == "0.91"
+    assert manifest["entries"][0]["identifier"].startswith("urn:air:weather.example:api:")
+    assert manifest["entries"][0]["metadata"]["access402.price"] == "0.01"
+    assert manifest["entries"][0]["representativeQueries"] == ["Get a local forecast", "Check the weather for a trip"]
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="https://weather.example") as client:
+        response = await client.get("/.well-known/ard.json")
+        compatibility = await client.get("/.well-known/ai-catalog.json")
+    assert response.status_code == compatibility.status_code == 200
+    assert response.headers["link"] == '</.well-known/ard.json>; rel="ard"'
+    assert response.json() == compatibility.json() == manifest
 
 
 def test_environment_requires_an_explicit_valid_payment_mode(monkeypatch):
@@ -240,3 +276,30 @@ async def test_configuration_rejects_the_wrong_installation_scope():
     async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="https://api.example.com") as client:
         response = await client.get("/route")
     assert response.status_code == 503
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("gate", [
+    {"action": "respond", "status": 503, "body": {"error": "resource_not_active"}, "headers": {}},
+    {"action": "respond", "status": 200, "body": {"bootstrap": True, "settled": True}, "headers": {"PAYMENT-RESPONSE": "receipt"}},
+])
+async def test_lifecycle_response_never_executes_handler_or_issues_grant(gate):
+    calls = []
+    async def backend(request):
+        calls.append(request.url.path)
+        return httpx.Response(200, json=gate)
+    app = FastAPI()
+    manager = Access402(Access402Settings("installation", "key", "https://api.example.com"), transport=httpx.MockTransport(backend))
+    @app.post("/reports/42")
+    @manager.protect(price="0.05")
+    async def protected():
+        pytest.fail("Bootstrap must never execute the customer handler")
+    manager.configuration = Configuration("v1", "now", "live", "eip155:8453", "0x" + "1" * 40, (policy(route_method="POST", route_template="/reports/42", access_type="wallet_once"),))
+    manager._loaded_at = manager._catalog_at = time.monotonic()
+    manager.install(app)
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="https://api.example.com") as client:
+        response = await client.post("/reports/42", json={"test": True}, headers={"X-Access402-Bootstrap": "server-token", "PAYMENT-SIGNATURE": "proof", "X-Access402-Grant": "old"})
+    assert response.status_code == gate["status"]
+    assert response.json() == gate["body"]
+    assert "X-Access402-Grant" not in response.headers
+    assert calls == ["/functions/v1/adapter/lifecycle"]
+    await manager.close()