access402-fastapi 0.1.0__tar.gz

access402_fastapi-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+supabase/.temp
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Python adapter build and test output
+__pycache__/
+*.py[cod]
+.pytest_cache/
+*.egg-info/
+.venv/
+adapters/fastapi/dist/

access402_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: access402-fastapi
+Version: 0.1.0
+Summary: Managed Access402 x402 v2 protection for FastAPI
+Project-URL: Homepage, https://access402.com
+Project-URL: Documentation, https://access402.com/how-it-works
+Project-URL: Repository, https://github.com/JonathanRoyere/Access402Dash
+Project-URL: Issues, https://github.com/JonathanRoyere/Access402Dash/issues
+Author: Jonathan Royere
+Keywords: access402,api-monetization,fastapi,payments,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.8
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8.3; extra == 'test'
+Requires-Dist: uvicorn>=0.30; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Access402 FastAPI adapter
+
+This package protects FastAPI routes with Access402's managed x402 v2 payment service. Route shapes and OpenAPI schemas come from the running application; pricing, enablement, sandbox/live mode, reusable access, and discovery remain dashboard settings.
+
+## Install locally
+
+```bash
+pip install -e "./adapters/fastapi[test]"
+```
+
+## Connect an application
+
+Create a **FastAPI** installation in the Access402 dashboard, then configure server-only environment variables:
+
+```bash
+ACCESS402_INSTALLATION_ID=your-installation-uuid
+ACCESS402_API_KEY=your-installation-key
+ACCESS402_PUBLIC_BASE_URL=https://api.example.com
+ACCESS402_ALLOW_LIVE=false
+```
+
+The API key belongs only in the FastAPI server environment. Never expose it in browser code, logs, OpenAPI documents, or a committed `.env` file. `ACCESS402_API_BASE_URL` is intentionally optional and should only be overridden for local Access402 backend development.
+
+Define routes first, then install Access402:
+
+```python
+from fastapi import FastAPI
+from access402_fastapi import Access402
+
+app = FastAPI()
+
+@app.get("/reports/{report_id}")
+async def report(report_id: str):
+    return {"id": report_id, "result": "..."}
+
+access402 = Access402.from_env()
+access402.install(app)
+```
+
+On its first request, the adapter authenticates the installation, uploads a compact route catalog, and downloads an 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.
+
+After the first catalog sync, open the installation's **Manage API routes** screen in the dashboard to choose routes, prices, access policies, environment, and Bazaar publication.
+
+Dynamic path routes such as `/reports/{report_id}` can be protected. Discovery publication for those routes stays disabled until Access402 supports a dashboard-provided concrete path-parameter example; publishing a literal template URL would create a broken Bazaar entry.
+
+Live mode requires both the dashboard toggle and `ACCESS402_ALLOW_LIVE=true`. This second switch is a deployment safety ceiling, not another credential.
+
+The adapter answers its own 402 responses with `Access-Control-Allow-Origin: *` by default so agent and browser clients can read the payment challenge. Set `ACCESS402_CORS_ALLOW_ORIGIN` to the API's exact browser origin when credentials are involved. CORS preflight (`OPTIONS`) is never paywalled.
+
+## Bypasses
+
+There is no header-based administrator bypass. If an application needs trusted internal access, pass a callback that validates the application's real authentication state:
+
+```python
+async def trusted_internal_request(scope):
+    user = scope.get("state", {}).get("user")
+    return bool(user and user.is_admin)
+
+access402 = Access402.from_env(bypass=trusted_internal_request)
+```
+
+Put authentication middleware outside Access402 if the callback depends on middleware-populated state. A spoofable header must never be used as the bypass decision.
+
+## Tests
+
+```bash
+cd adapters/fastapi
+python -m pip install -e ".[test]"
+pytest
+```

access402_fastapi-0.1.0/README.md

@@ -0,0 +1,70 @@
+# Access402 FastAPI adapter
+
+This package protects FastAPI routes with Access402's managed x402 v2 payment service. Route shapes and OpenAPI schemas come from the running application; pricing, enablement, sandbox/live mode, reusable access, and discovery remain dashboard settings.
+
+## Install locally
+
+```bash
+pip install -e "./adapters/fastapi[test]"
+```
+
+## Connect an application
+
+Create a **FastAPI** installation in the Access402 dashboard, then configure server-only environment variables:
+
+```bash
+ACCESS402_INSTALLATION_ID=your-installation-uuid
+ACCESS402_API_KEY=your-installation-key
+ACCESS402_PUBLIC_BASE_URL=https://api.example.com
+ACCESS402_ALLOW_LIVE=false
+```
+
+The API key belongs only in the FastAPI server environment. Never expose it in browser code, logs, OpenAPI documents, or a committed `.env` file. `ACCESS402_API_BASE_URL` is intentionally optional and should only be overridden for local Access402 backend development.
+
+Define routes first, then install Access402:
+
+```python
+from fastapi import FastAPI
+from access402_fastapi import Access402
+
+app = FastAPI()
+
+@app.get("/reports/{report_id}")
+async def report(report_id: str):
+    return {"id": report_id, "result": "..."}
+
+access402 = Access402.from_env()
+access402.install(app)
+```
+
+On its first request, the adapter authenticates the installation, uploads a compact route catalog, and downloads an 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.
+
+After the first catalog sync, open the installation's **Manage API routes** screen in the dashboard to choose routes, prices, access policies, environment, and Bazaar publication.
+
+Dynamic path routes such as `/reports/{report_id}` can be protected. Discovery publication for those routes stays disabled until Access402 supports a dashboard-provided concrete path-parameter example; publishing a literal template URL would create a broken Bazaar entry.
+
+Live mode requires both the dashboard toggle and `ACCESS402_ALLOW_LIVE=true`. This second switch is a deployment safety ceiling, not another credential.
+
+The adapter answers its own 402 responses with `Access-Control-Allow-Origin: *` by default so agent and browser clients can read the payment challenge. Set `ACCESS402_CORS_ALLOW_ORIGIN` to the API's exact browser origin when credentials are involved. CORS preflight (`OPTIONS`) is never paywalled.
+
+## Bypasses
+
+There is no header-based administrator bypass. If an application needs trusted internal access, pass a callback that validates the application's real authentication state:
+
+```python
+async def trusted_internal_request(scope):
+    user = scope.get("state", {}).get("user")
+    return bool(user and user.is_admin)
+
+access402 = Access402.from_env(bypass=trusted_internal_request)
+```
+
+Put authentication middleware outside Access402 if the callback depends on middleware-populated state. A spoofable header must never be used as the bypass decision.
+
+## Tests
+
+```bash
+cd adapters/fastapi
+python -m pip install -e ".[test]"
+pytest
+```

access402_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "access402-fastapi"
+version = "0.1.0"
+description = "Managed Access402 x402 v2 protection for FastAPI"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Jonathan Royere" }]
+keywords = ["access402", "x402", "fastapi", "payments", "api-monetization"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["fastapi>=0.115", "httpx>=0.27", "pydantic>=2.8"]
+
+[project.urls]
+Homepage = "https://access402.com"
+Documentation = "https://access402.com/how-it-works"
+Repository = "https://github.com/JonathanRoyere/Access402Dash"
+Issues = "https://github.com/JonathanRoyere/Access402Dash/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8.3", "pytest-asyncio>=0.24", "uvicorn>=0.30"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/access402_fastapi"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/access402_fastapi", "tests", "README.md", "pyproject.toml"]

access402_fastapi-0.1.0/src/access402_fastapi/__init__.py

@@ -0,0 +1,3 @@
+from .adapter import Access402, Access402Settings
+
+__all__ = ["Access402", "Access402Settings"]

access402_fastapi-0.1.0/src/access402_fastapi/adapter.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import inspect
+import json
+import os
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Any, Awaitable, Callable
+from urllib.parse import quote, urlsplit
+
+import httpx
+from fastapi import FastAPI
+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
+
+BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+BASE_SEPOLIA_USDC = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+Bypass = Callable[[dict[str, Any]], bool | Awaitable[bool]]
+
+
+@dataclass(frozen=True)
+class Access402Settings:
+    installation_id: str
+    api_key: str
+    public_base_url: str
+    api_base_url: str = "https://sfowjygkbsubaeggmckp.supabase.co/functions/v1"
+    refresh_seconds: int = 60
+    catalog_refresh_seconds: int = 300
+    stale_after_seconds: int = 900
+    allow_live: bool = False
+    fail_closed: bool = True
+    cors_allow_origin: str = "*"
+    excluded_paths: tuple[str, ...] = ("/health", "/docs", "/redoc", "/openapi.json")
+
+    @classmethod
+    def from_env(cls) -> "Access402Settings":
+        required = {
+            name: os.environ.get(name, "").strip()
+            for name in ("ACCESS402_INSTALLATION_ID", "ACCESS402_API_KEY", "ACCESS402_PUBLIC_BASE_URL")
+        }
+        missing = [name for name, value in required.items() if not value]
+        if missing:
+            raise RuntimeError(f"Missing Access402 environment variables: {', '.join(missing)}")
+        return cls(
+            installation_id=required["ACCESS402_INSTALLATION_ID"],
+            api_key=required["ACCESS402_API_KEY"],
+            public_base_url=required["ACCESS402_PUBLIC_BASE_URL"].rstrip("/"),
+            api_base_url=os.environ.get("ACCESS402_API_BASE_URL", cls.api_base_url).rstrip("/"),
+            refresh_seconds=int(os.environ.get("ACCESS402_REFRESH_SECONDS", "60")),
+            catalog_refresh_seconds=int(os.environ.get("ACCESS402_CATALOG_REFRESH_SECONDS", "300")),
+            stale_after_seconds=int(os.environ.get("ACCESS402_STALE_AFTER_SECONDS", "900")),
+            allow_live=os.environ.get("ACCESS402_ALLOW_LIVE", "false").lower() == "true",
+            cors_allow_origin=os.environ.get("ACCESS402_CORS_ALLOW_ORIGIN", "*"),
+        )
+
+
+class Access402:
+    def __init__(self, settings: Access402Settings, *, bypass: Bypass | None = None, transport: httpx.AsyncBaseTransport | None = None):
+        self.settings = settings
+        self.bypass = bypass
+        self.client = Access402Client(settings.api_base_url, settings.api_key, settings.installation_id, transport=transport)
+        self.app: FastAPI | None = None
+        self.configuration: Configuration | None = None
+        self._loaded_at = 0.0
+        self._catalog_at = 0.0
+        self._lock = asyncio.Lock()
+        self._refresh_task: asyncio.Task[Configuration] | None = None
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> "Access402":
+        return cls(Access402Settings.from_env(), **kwargs)
+
+    def install(self, app: FastAPI) -> None:
+        self.app = app
+        app.add_middleware(Access402Middleware, manager=self)
+
+    async def close(self) -> None:
+        await self.client.close()
+
+    def route_catalog(self) -> list[dict[str, Any]]:
+        if not self.app:
+            raise RuntimeError("Access402 is not installed on a FastAPI app")
+        schema = self.app.openapi()
+        base = self.settings.public_base_url
+        routes: list[dict[str, Any]] = []
+        for route in self.app.routes:
+            if not isinstance(route, APIRoute) or route.path in self.settings.excluded_paths:
+                continue
+            path_item = schema.get("paths", {}).get(route.path, {})
+            for method in sorted(route.methods or []):
+                if method not in {"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"}:
+                    continue
+                operation = path_item.get(method.lower(), {})
+                content = operation.get("requestBody", {}).get("content", {})
+                input_schema = next((entry.get("schema", {}) for entry in content.values() if isinstance(entry, dict)), {})
+                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 {}
+                output_schema = next((entry.get("schema", {}) for entry in output_content.values() if isinstance(entry, dict)), {})
+                mime_type = next(iter(output_content), "application/json")
+                identity = f"{method} {route.path}"
+                route_key = stable_hash(identity)
+                item = {
+                    "route_key": route_key, "method": method, "path_template": route.path,
+                    "resource_url": f"{base}{route.path}", "operation_id": operation.get("operationId") or route.name,
+                    "display_name": operation.get("summary") or route.name or identity,
+                    "description": operation.get("description") or route.description or None,
+                    "mime_type": mime_type, "input_schema": input_schema if isinstance(input_schema, dict) else {},
+                    "output_schema": output_schema if isinstance(output_schema, dict) else {},
+                }
+                item["catalog_hash"] = stable_hash(item)
+                routes.append(item)
+        return routes
+
+    async def refresh(self, *, force: bool = False) -> Configuration:
+        now = time.monotonic()
+        if self.configuration and not force and now - self._loaded_at < self.settings.refresh_seconds:
+            return self.configuration
+        async with self._lock:
+            now = time.monotonic()
+            if self.configuration and not force and now - self._loaded_at < self.settings.refresh_seconds:
+                return self.configuration
+            if not self._catalog_at or now - self._catalog_at >= self.settings.catalog_refresh_seconds:
+                await self.client.sync_catalog(self.route_catalog())
+                self._catalog_at = now
+            configuration = await self.client.configuration()
+            if configuration.environment == "live" and not self.settings.allow_live:
+                raise RuntimeError("Live settlement is disabled by ACCESS402_ALLOW_LIVE")
+            self.configuration = configuration
+            self._loaded_at = now
+            return configuration
+
+    async def current_configuration(self) -> Configuration:
+        now = time.monotonic()
+        if self.configuration and now - self._loaded_at < self.settings.stale_after_seconds:
+            if now - self._loaded_at >= self.settings.refresh_seconds and (
+                self._refresh_task is None or self._refresh_task.done()
+            ):
+                self._refresh_task = asyncio.create_task(self.refresh(force=True))
+                self._refresh_task.add_done_callback(lambda task: task.exception() if not task.cancelled() else None)
+            return self.configuration
+        return await self.refresh(force=True)
+
+    def policy_for(self, method: str, path: str) -> ResourcePolicy | None:
+        if not self.configuration:
+            return None
+        return next((policy for policy in self.configuration.resources
+                     if policy.enabled and policy.route_method == method and template_matches(policy.route_template, path)), None)
+
+    def stale(self) -> bool:
+        return not self.configuration or time.monotonic() - self._loaded_at > self.settings.stale_after_seconds
+
+
+class Access402Middleware:
+    def __init__(self, app: Any, manager: Access402):
+        self.app = app
+        self.manager = manager
+
+    async def __call__(self, scope: dict[str, Any], receive: Any, send: Any) -> None:
+        if scope["type"] == "lifespan":
+            try:
+                await self.app(scope, receive, send)
+            finally:
+                await self.manager.close()
+            return
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        try:
+            path = canonical_request_path(scope.get("raw_path") or scope.get("path", "/").encode())
+        except ValueError:
+            await self._json(send, 400, {"error": "ambiguous_request_path"})
+            return
+        if path in self.manager.settings.excluded_paths:
+            await self.app(scope, receive, send)
+            return
+
+        if str(scope.get("method", "GET")).upper() == "OPTIONS":
+            await self.app(scope, receive, send)
+            return
+
+        try:
+            configuration = await self.manager.current_configuration()
+        except Exception:
+            if self.manager.settings.fail_closed and self.manager.stale():
+                await self._json(send, 503, {"error": "access402_configuration_unavailable"}, [(b"cache-control", b"no-store")])
+                return
+            configuration = self.manager.configuration
+        if not configuration:
+            await self.app(scope, receive, send)
+            return
+
+        method = str(scope.get("method", "GET")).upper()
+        policy = self.manager.policy_for(method, path)
+        if not policy:
+            await self.app(scope, receive, send)
+            return
+        if self.manager.bypass:
+            result = self.manager.bypass(scope)
+            if await result if inspect.isawaitable(result) else result:
+                await self.app(scope, receive, send)
+                return
+
+        headers = {key.decode("latin1").lower(): value.decode("latin1") for key, value in scope.get("headers", [])}
+        grant = headers.get("x-access402-grant")
+        if policy.access_type != "per_request" and valid_grant(self.manager.settings.api_key, grant, policy.local_rule_id):
+            await self._downstream(scope, receive, send, [(b"x-access402-grant", grant.encode())])
+            self._event(configuration, policy, "delivered", {"access_grant": True})
+            return
+
+        challenge, requirements = self._challenge(configuration, policy, path)
+        encoded_challenge = base64.b64encode(json.dumps(challenge, separators=(",", ":")).encode()).decode()
+        payment = headers.get("payment-signature") or headers.get("x-payment")
+        if not payment:
+            self._event(configuration, policy, "payment_required")
+            await self._json(send, 402, challenge, self._challenge_headers(encoded_challenge, "payment_required"))
+            return
+        try:
+            settled = await self.manager.client.settle(
+                policy, payment, requirements, "live" if configuration.environment == "live" else "sandbox"
+            )
+        except httpx.HTTPStatusError as error:
+            code = "settlement_failed" if error.response.status_code < 500 else "settlement_service_unavailable"
+            status = 402 if error.response.status_code < 500 else 503
+            self._event(configuration, policy, code)
+            await self._json(send, status, {**challenge, "error": code}, self._challenge_headers(encoded_challenge, code))
+            return
+        except Exception:
+            self._event(configuration, policy, "settlement_service_unavailable")
+            await self._json(send, 503, {**challenge, "error": "settlement_service_unavailable"}, self._challenge_headers(encoded_challenge, "settlement_service_unavailable"))
+            return
+        if settled.get("settled") is not True:
+            self._event(configuration, policy, "settlement_failed")
+            await self._json(send, 402, {**challenge, "error": "settlement_failed"}, self._challenge_headers(encoded_challenge, "settlement_failed"))
+            return
+
+        response_headers: list[tuple[bytes, bytes]] = []
+        if isinstance(settled.get("payment_response"), str):
+            response_headers.append((b"payment-response", settled["payment_response"].encode()))
+        if policy.access_type != "per_request":
+            expires = None if policy.access_type == "wallet_once" else int(time.time()) + int(policy.access_duration_seconds or 0)
+            token = sign_grant(self.manager.settings.api_key, policy.local_rule_id, str(settled.get("payer", "")), expires)
+            response_headers.append((b"x-access402-grant", token.encode()))
+        response_headers.append((b"access-control-expose-headers", b"PAYMENT-RESPONSE, X-Access402-Grant"))
+        await self._downstream(scope, receive, send, response_headers)
+        self._event(configuration, policy, "payment_settled", {"access_type": policy.access_type}, settled.get("payment_event_id"))
+
+    def _challenge(self, configuration: Configuration, policy: ResourcePolicy, path: str) -> tuple[dict[str, Any], dict[str, Any]]:
+        amount = str(int(Decimal(policy.price) * Decimal(1_000_000)))
+        asset = BASE_USDC if configuration.network == "eip155:8453" else BASE_SEPOLIA_USDC
+        requirements = {
+            "scheme": "exact", "network": configuration.network, "amount": amount, "asset": asset,
+            "payTo": configuration.pay_to, "maxTimeoutSeconds": 60,
+            "extra": {"assetTransferMethod": "eip3009", "name": "USD Coin" if configuration.network == "eip155:8453" else "USDC", "version": "2"},
+        }
+        extension: dict[str, Any] = {}
+        if policy.discovery_enabled:
+            metadata = policy.discovery_metadata
+            method = policy.discovery_method
+            input_value: dict[str, Any] = {"type": "http", "method": method}
+            if method in ("POST", "PUT", "PATCH"):
+                input_value.update({"bodyType": "json", "body": metadata.get("input_example", {})})
+            else:
+                input_value["queryParams"] = metadata.get("input_example", {})
+            extension = {"bazaar": {"info": {"input": input_value}, "schema": {"$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object"}}}
+        resource_url = f"{self.manager.settings.public_base_url}{quote(path, safe='/:@-._~!$&\'()*+,;=')}"
+        challenge = {
+            "x402Version": 2, "error": "PAYMENT-SIGNATURE header is required",
+            "resource": {"url": resource_url, "description": policy.description or policy.display_name,
+                         "mimeType": policy.mime_type or "application/json"},
+            "accepts": [requirements], "extensions": extension,
+        }
+        return challenge, requirements
+
+    @staticmethod
+    def _challenge_headers(encoded: str, error: str) -> list[tuple[bytes, bytes]]:
+        return [(b"cache-control", b"no-store"), (b"payment-required", encoded.encode()),
+                (b"x-access402-error", error.encode()),
+                (b"access-control-expose-headers", b"PAYMENT-REQUIRED, X-Access402-Error")]
+
+    async def _downstream(self, scope: dict[str, Any], receive: Any, send: Any, extra: list[tuple[bytes, bytes]]) -> None:
+        async def wrapped(message: dict[str, Any]) -> None:
+            if message["type"] == "http.response.start":
+                message["headers"] = list(message.get("headers", [])) + extra
+            await send(message)
+        await self.app(scope, receive, wrapped)
+
+    async def _json(self, send: Any, status: int, body: dict[str, Any], headers: list[tuple[bytes, bytes]] | None = None) -> None:
+        payload = json.dumps(body, separators=(",", ":")).encode()
+        response_headers = list(headers or [])
+        if not any(name.lower() == b"access-control-allow-origin" for name, _ in response_headers):
+            response_headers.append((b"access-control-allow-origin", self.manager.settings.cors_allow_origin.encode()))
+        await send({"type": "http.response.start", "status": status,
+                    "headers": [(b"content-type", b"application/json"), (b"content-length", str(len(payload)).encode()), *response_headers]})
+        await send({"type": "http.response.body", "body": payload})
+
+    def _event(self, configuration: Configuration, policy: ResourcePolicy, event_type: str,
+               details: dict[str, Any] | None = None, payment_event_id: Any = None) -> None:
+        event = {"event_id": str(uuid.uuid4()), "event_type": event_type,
+                 "occurred_at": datetime.now(timezone.utc).isoformat(), "local_rule_id": policy.local_rule_id,
+                 "resource_key": policy.resource_key,
+                 "payment_event_id": payment_event_id if event_type == "payment_settled" else None,
+                 "details": details or {}}
+        try:
+            asyncio.get_running_loop().create_task(self.manager.client.publish_event(
+                "live" if configuration.environment == "live" else "sandbox", event
+            ))
+        except RuntimeError:
+            pass

access402_fastapi-0.1.0/src/access402_fastapi/client.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+import httpx
+
+from .models import Configuration
+from .security import verify_configuration_signature
+
+
+class Access402Client:
+    def __init__(self, base_url: str, api_key: str, installation_id: str, timeout: float = 8.0, transport: httpx.AsyncBaseTransport | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.installation_id = installation_id
+        self.http = httpx.AsyncClient(timeout=timeout, follow_redirects=False, transport=transport)
+
+    def headers(self, mode: str = "sandbox") -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}", "Accept": "application/json",
+            "X-Access402-Adapter-Version": "1", "X-Access402-Mode": mode,
+            "User-Agent": "Access402-FastAPI/0.1.0",
+        }
+
+    async def close(self) -> None:
+        await self.http.aclose()
+
+    async def sync_catalog(self, routes: list[dict[str, Any]]) -> str:
+        response = await self.http.put(f"{self.base_url}/adapter/catalog", headers=self.headers(), json={"routes": routes})
+        response.raise_for_status()
+        value = response.json()
+        return str(value["configuration_version"])
+
+    async def configuration(self) -> Configuration:
+        response = await self.http.get(f"{self.base_url}/adapter/configuration", headers=self.headers())
+        response.raise_for_status()
+        verify_configuration_signature(self.api_key, response.content, response.headers.get("X-Access402-Configuration-Signature"))
+        value = response.json()
+        from .models import ResourcePolicy
+        resources = tuple(ResourcePolicy.from_dict(item) for item in value.get("resources", []))
+        environment = str(value.get("environment"))
+        network = str(value.get("network"))
+        pay_to = str(value.get("pay_to") or "")
+        if value.get("x402_version") != 2 or value.get("installation_id") != self.installation_id or environment not in ("test", "live") or not network or not pay_to:
+            raise ValueError("Invalid Access402 configuration")
+        return Configuration(str(value.get("configuration_version")), str(value.get("generated_at")), environment, network, pay_to, resources)
+
+    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(
+            f"{self.base_url}/payments/settle", headers={**self.headers(mode), "Content-Type": "application/json"},
+            json={"rule_id": policy.local_rule_id, "resource_key": policy.resource_key,
+                  "payment_payload": payment, "payment_requirements": requirements, "idempotency_key": idempotency},
+        )
+        if response.status_code >= 500:
+            raise RuntimeError("Access402 settlement service unavailable")
+        response.raise_for_status()
+        return response.json()
+
+    async def publish_event(self, mode: str, event: dict[str, Any]) -> None:
+        try:
+            await self.http.post(f"{self.base_url}/adapter/events", headers={**self.headers(mode), "Content-Type": "application/json"}, json={"events": [event]})
+        except Exception:
+            return
+
+
+def stable_hash(value: Any) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()

access402_fastapi-0.1.0/src/access402_fastapi/models.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ResourcePolicy:
+    id: str
+    local_rule_id: str
+    resource_key: str
+    resource_url: str
+    display_name: str
+    description: str | None
+    price: str
+    asset: str
+    mime_type: str | None
+    access_type: str
+    access_duration_seconds: int | None
+    enabled: bool
+    discovery_enabled: bool
+    discovery_method: str
+    discovery_metadata: dict[str, Any]
+    route_method: str
+    route_template: str
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> "ResourcePolicy":
+        required = ("id", "local_rule_id", "resource_key", "resource_url", "route_method", "route_template")
+        if any(not isinstance(value.get(key), str) or not value[key] for key in required):
+            raise ValueError("Invalid Access402 resource policy")
+        price = value.get("price")
+        if not isinstance(price, (str, int, float)) or not str(price):
+            raise ValueError("Invalid Access402 resource policy price")
+        return cls(
+            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,
+            price=str(price), asset=str(value.get("asset", "USDC")),
+            mime_type=value.get("mime_type") if isinstance(value.get("mime_type"), str) else None,
+            access_type=str(value.get("access_type", "per_request")),
+            access_duration_seconds=value.get("access_duration_seconds") if isinstance(value.get("access_duration_seconds"), int) else None,
+            enabled=value.get("enabled") is True, discovery_enabled=value.get("discovery_enabled") is True,
+            discovery_method=str(value.get("discovery_method", "GET")),
+            discovery_metadata=value.get("discovery_metadata") if isinstance(value.get("discovery_metadata"), dict) else {},
+            route_method=value["route_method"].upper(), route_template=value["route_template"],
+        )
+
+
+@dataclass(frozen=True)
+class Configuration:
+    version: str
+    generated_at: str
+    environment: str
+    network: str
+    pay_to: str
+    resources: tuple[ResourcePolicy, ...] = field(default_factory=tuple)

access402_fastapi-0.1.0/src/access402_fastapi/py.typed

@@ -0,0 +1 @@
+

access402_fastapi-0.1.0/src/access402_fastapi/security.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any
+from urllib.parse import unquote
+
+
+AMBIGUOUS_ENCODING = re.compile(br"%2f|%5c", re.IGNORECASE)
+PARAMETER = re.compile(r"^\{[A-Za-z_][A-Za-z0-9_]*\}$")
+PATH_PARAMETER = re.compile(r"^\{[A-Za-z_][A-Za-z0-9_]*:path\}$")
+
+
+def base64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode().rstrip("=")
+
+
+def verify_configuration_signature(api_key: str, body: bytes, header: str | None) -> None:
+    if not header or not header.startswith("v1="):
+        raise ValueError("Missing Access402 configuration signature")
+    expected = base64url(hmac.new(api_key.encode(), body, hashlib.sha256).digest())
+    if not hmac.compare_digest(expected, header[3:]):
+        raise ValueError("Invalid Access402 configuration signature")
+
+
+def canonical_request_path(raw_path: bytes) -> str:
+    if not raw_path.startswith(b"/") or b"\\" in raw_path or AMBIGUOUS_ENCODING.search(raw_path):
+        raise ValueError("Ambiguous request path")
+    try:
+        path = unquote(raw_path.decode("ascii"), errors="strict")
+    except (UnicodeDecodeError, ValueError):
+        raise ValueError("Invalid request path") from None
+    if "\\" in path or "//" in path or any(segment in (".", "..") for segment in path.split("/")):
+        raise ValueError("Ambiguous request path")
+    return path[:-1] if len(path) > 1 and path.endswith("/") else path
+
+
+def template_matches(template: str, path: str) -> bool:
+    normalized = template[:-1] if len(template) > 1 and template.endswith("/") else template
+    template_parts, path_parts = normalized.split("/"), path.split("/")
+    for index, part in enumerate(template_parts):
+        if PATH_PARAMETER.match(part):
+            return index < len(path_parts) and bool("/".join(path_parts[index:]))
+        if index >= len(path_parts):
+            return False
+        if PARAMETER.match(part):
+            if not path_parts[index]:
+                return False
+        elif part != path_parts[index]:
+            return False
+    return len(template_parts) == len(path_parts)
+
+
+def sign_grant(api_key: str, rule_id: str, payer: str, expires_at: int | None) -> str:
+    payload = base64url(json.dumps({"v": 1, "r": rule_id, "p": payer, "e": expires_at}, separators=(",", ":"), sort_keys=True).encode())
+    signature = base64url(hmac.new(api_key.encode(), payload.encode(), hashlib.sha256).digest())
+    return f"{payload}.{signature}"
+
+
+def valid_grant(api_key: str, token: str | None, rule_id: str) -> bool:
+    if not token or token.count(".") != 1:
+        return False
+    payload, supplied = token.split(".", 1)
+    expected = base64url(hmac.new(api_key.encode(), payload.encode(), hashlib.sha256).digest())
+    if not hmac.compare_digest(expected, supplied):
+        return False
+    try:
+        value: dict[str, Any] = json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+    except Exception:
+        return False
+    expires = value.get("e")
+    return value.get("v") == 1 and value.get("r") == rule_id and (
+        expires is None or isinstance(expires, int) and expires >= int(time.time())
+    )

access402_fastapi-0.1.0/tests/test_adapter.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import base64
+import json
+import hashlib
+import hmac
+import time
+
+import httpx
+import pytest
+from fastapi import FastAPI
+
+from access402_fastapi import Access402, Access402Settings
+from access402_fastapi.models import Configuration, ResourcePolicy
+
+
+def policy(**changes):
+    values = dict(
+        id="22222222-2222-4222-8222-222222222222",
+        local_rule_id="11111111-1111-4111-8111-111111111111",
+        resource_key="rest_route:fastapi:" + "a" * 64,
+        resource_url="https://api.example.com/reports/{report_id}",
+        display_name="Read report", description="Read one report", price="0.01", asset="USDC",
+        mime_type="application/json", access_type="per_request", access_duration_seconds=None,
+        enabled=True, discovery_enabled=False, discovery_method="GET", discovery_metadata={},
+        route_method="GET", route_template="/reports/{report_id}",
+    )
+    values.update(changes)
+    return ResourcePolicy(**values)
+
+
+def configured_app(handler=None, **policy_changes):
+    async def backend(request: httpx.Request):
+        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"})
+
+    app = FastAPI()
+    @app.get("/reports/{report_id}")
+    async def report(report_id: str):
+        return {"id": report_id}
+    settings = Access402Settings("installation", "a402_000000000000_" + "a" * 43, "https://api.example.com", allow_live=True)
+    manager = Access402(settings, transport=httpx.MockTransport(backend))
+    manager.configuration = Configuration("v1", "now", "test", "eip155:84532", "0x0000000000000000000000000000000000000001", (policy(**policy_changes),))
+    manager._loaded_at = time.monotonic()
+    manager._catalog_at = time.monotonic()
+    manager.install(app)
+    return app
+
+
+@pytest.mark.asyncio
+async def test_returns_x402_v2_challenge():
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=configured_app()), base_url="https://api.example.com") as client:
+        response = await client.get("/reports/42")
+    assert response.status_code == 402
+    challenge = json.loads(base64.b64decode(response.headers["PAYMENT-REQUIRED"]))
+    assert challenge["x402Version"] == 2
+    assert challenge["resource"]["url"] == "https://api.example.com/reports/42"
+    assert challenge["accepts"][0]["network"] == "eip155:84532"
+    assert challenge["accepts"][0]["amount"] == "10000"
+
+
+@pytest.mark.asyncio
+async def test_rejects_double_slash_bypass():
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=configured_app()), base_url="https://api.example.com") as client:
+        response = await client.get("https://api.example.com//reports/42")
+    assert response.status_code == 400
+    assert response.json()["error"] == "ambiguous_request_path"
+
+
+@pytest.mark.asyncio
+async def test_successful_settlement_releases_route_and_receipt():
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=configured_app()), base_url="https://api.example.com") as client:
+        response = await client.get("/reports/42", headers={"PAYMENT-SIGNATURE": "payload"})
+    assert response.status_code == 200
+    assert response.json() == {"id": "42"}
+    assert response.headers["PAYMENT-RESPONSE"] == "receipt"
+
+
+@pytest.mark.asyncio
+async def test_failed_settlement_fails_closed():
+    async def handler(_request):
+        return httpx.Response(503, json={"error": "payment_service_unavailable"})
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=configured_app(handler)), base_url="https://api.example.com") as client:
+        response = await client.get("/reports/42", headers={"PAYMENT-SIGNATURE": "bad"})
+    assert response.status_code == 503
+    assert response.json()["error"] == "settlement_service_unavailable"
+
+
+@pytest.mark.asyncio
+async def test_reusable_grant_avoids_second_settlement():
+    calls = 0
+    async def handler(_request):
+        nonlocal calls
+        calls += 1
+        return httpx.Response(200, json={"settled": True, "payer": "0xpayer", "payment_event_id": "33333333-3333-4333-8333-333333333333"})
+    app = configured_app(handler, access_type="wallet_once")
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="https://api.example.com") as client:
+        first = await client.get("/reports/42", headers={"PAYMENT-SIGNATURE": "payload"})
+        second = await client.get("/reports/42", headers={"X-Access402-Grant": first.headers["X-Access402-Grant"]})
+    assert first.status_code == second.status_code == 200
+    assert calls == 1
+
+
+@pytest.mark.asyncio
+async def test_cold_start_fails_closed_when_configuration_is_unavailable():
+    async def handler(_request):
+        return httpx.Response(503, json={"error": "unavailable"})
+    app = FastAPI()
+    @app.get("/public-looking-route")
+    async def route():
+        return {"secret": True}
+    settings = Access402Settings("installation", "a402_000000000000_" + "a" * 43, "https://api.example.com")
+    Access402(settings, transport=httpx.MockTransport(handler)).install(app)
+    async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="https://api.example.com") as client:
+        response = await client.get("/public-looking-route")
+    assert response.status_code == 503
+    assert response.json()["error"] == "access402_configuration_unavailable"
+
+
+@pytest.mark.asyncio
+async def test_configuration_rejects_the_wrong_installation_scope():
+    api_key = "a402_000000000000_" + "a" * 43
+    async def handler(request):
+        if request.url.path.endswith("/adapter/catalog"):
+            return httpx.Response(200, json={"configuration_version": "v1"})
+        body = json.dumps({
+            "x402_version": 2, "installation_id": "other-installation", "configuration_version": "v1",
+            "generated_at": "now", "environment": "test", "network": "eip155:84532",
+            "pay_to": "0x0000000000000000000000000000000000000001", "resources": [],
+        }, separators=(",", ":")).encode()
+        signature = base64.urlsafe_b64encode(hmac.new(api_key.encode(), body, hashlib.sha256).digest()).decode().rstrip("=")
+        return httpx.Response(200, content=body, headers={"X-Access402-Configuration-Signature": f"v1={signature}"})
+    app = FastAPI()
+    @app.get("/route")
+    async def route():
+        return {}
+    manager = Access402(Access402Settings("installation", api_key, "https://api.example.com"), transport=httpx.MockTransport(handler))
+    manager.install(app)
+    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