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

{access402_fastapi-0.2.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.2.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
@@ -45,7 +45,7 @@ Create a **FastAPI** installation in the Access402 dashboard, then configure ser
 ACCESS402_INSTALLATION_ID=your-installation-uuid
 ACCESS402_API_KEY=your-installation-key
 ACCESS402_PUBLIC_BASE_URL=https://api.example.com
-ACCESS402_ALLOW_LIVE=false
+ACCESS402_MODE=sandbox
 ```
 
 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.
@@ -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,15 +74,21 @@ 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. It controls the installation payment environment, while protected routes fail closed if Access402 cannot confirm a matching server-side policy.
+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.
 
 Dynamic path routes such as `/reports/{report_id}` can be protected. Discovery publication for those routes stays disabled until Access402 supports a concrete path-parameter example; publishing a literal template URL would create a broken Bazaar entry.
 
 `ACCESS402_PUBLIC_BASE_URL` remains required. It is the trusted canonical origin placed in x402 resource URLs and validated against the installation's authorized origins. Inferring it from an incoming `Host` or forwarding header would allow a spoofed request to alter payment and discovery metadata. Use a separate FastAPI installation for local, staging, and production deployments; replicas of the same deployment may share one installation.
 
-Live mode requires both the dashboard toggle and `ACCESS402_ALLOW_LIVE=true`. This second switch is a deployment safety ceiling, not another credential.
+Set `ACCESS402_MODE=sandbox` for Base Sepolia or `ACCESS402_MODE=live` for Base mainnet, then restart the deployment. There is no dashboard mode override.
 
 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.
 

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

@@ -16,7 +16,7 @@ Create a **FastAPI** installation in the Access402 dashboard, then configure ser
 ACCESS402_INSTALLATION_ID=your-installation-uuid
 ACCESS402_API_KEY=your-installation-key
 ACCESS402_PUBLIC_BASE_URL=https://api.example.com
-ACCESS402_ALLOW_LIVE=false
+ACCESS402_MODE=sandbox
 ```
 
 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.
@@ -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,15 +45,21 @@ 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. It controls the installation payment environment, while protected routes fail closed if Access402 cannot confirm a matching server-side policy.
+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.
 
 Dynamic path routes such as `/reports/{report_id}` can be protected. Discovery publication for those routes stays disabled until Access402 supports a concrete path-parameter example; publishing a literal template URL would create a broken Bazaar entry.
 
 `ACCESS402_PUBLIC_BASE_URL` remains required. It is the trusted canonical origin placed in x402 resource URLs and validated against the installation's authorized origins. Inferring it from an incoming `Host` or forwarding header would allow a spoofed request to alter payment and discovery metadata. Use a separate FastAPI installation for local, staging, and production deployments; replicas of the same deployment may share one installation.
 
-Live mode requires both the dashboard toggle and `ACCESS402_ALLOW_LIVE=true`. This second switch is a deployment safety ceiling, not another credential.
+Set `ACCESS402_MODE=sandbox` for Base Sepolia or `ACCESS402_MODE=live` for Base mainnet, then restart the deployment. There is no dashboard mode override.
 
 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.
 

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

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

{access402_fastapi-0.2.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)
@@ -45,33 +50,36 @@ class Access402Settings:
     installation_id: str
     api_key: str
     public_base_url: str
+    mode: str = "sandbox"
     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")
+    excluded_paths: tuple[str, ...] = ("/health", "/docs", "/redoc", "/openapi.json", ARD_PATH, ARD_COMPATIBILITY_PATH)
 
     @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")
+            for name in ("ACCESS402_INSTALLATION_ID", "ACCESS402_API_KEY", "ACCESS402_PUBLIC_BASE_URL", "ACCESS402_MODE")
         }
         missing = [name for name, value in required.items() if not value]
         if missing:
             raise RuntimeError(f"Missing Access402 environment variables: {', '.join(missing)}")
+        mode = required["ACCESS402_MODE"].lower()
+        if mode not in ("sandbox", "live"):
+            raise RuntimeError("ACCESS402_MODE must be either sandbox or live")
         return cls(
             installation_id=required["ACCESS402_INSTALLATION_ID"],
             api_key=required["ACCESS402_API_KEY"],
             public_base_url=required["ACCESS402_PUBLIC_BASE_URL"].rstrip("/"),
+            mode=mode,
             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", "*"),
         )
 
@@ -101,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:
@@ -120,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,
@@ -127,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]:
@@ -140,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)
@@ -211,11 +267,12 @@ class Access402:
             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())
+                await self.client.sync_catalog(self.route_catalog(), self.settings.mode)
                 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")
+            configuration = await self.client.configuration(self.settings.mode)
+            expected_environment = "live" if self.settings.mode == "live" else "test"
+            if configuration.environment != expected_environment:
+                raise RuntimeError("Access402 returned configuration for the wrong payment mode")
             self.configuration = configuration
             self._loaded_at = now
             return configuration
@@ -300,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.2.0 → access402_fastapi-0.4.0}/src/access402_fastapi/client.py

@@ -20,21 +20,21 @@ class Access402Client:
     def headers(self, mode: str = "sandbox") -> dict[str, str]:
         return {
             "Authorization": f"Bearer {self.api_key}", "Accept": "application/json",
-            "X-Access402-Adapter-Version": "2", "X-Access402-Mode": mode,
-            "User-Agent": "Access402-FastAPI/0.2.0",
+            "X-Access402-Adapter-Version": "3", "X-Access402-Mode": mode,
+            "User-Agent": "Access402-FastAPI/0.4.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})
+    async def sync_catalog(self, routes: list[dict[str, Any]], mode: str) -> str:
+        response = await self.http.put(f"{self.base_url}/adapter/catalog", headers=self.headers(mode), 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())
+    async def configuration(self, mode: str) -> Configuration:
+        response = await self.http.get(f"{self.base_url}/adapter/configuration", headers=self.headers(mode))
         response.raise_for_status()
         verify_configuration_signature(self.api_key, response.content, response.headers.get("X-Access402-Configuration-Signature"))
         value = response.json()
@@ -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.2.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.2.0 → access402_fastapi-0.4.0}/tests/test_adapter.py

@@ -31,12 +31,14 @@ 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"})
 
     app = FastAPI()
-    settings = Access402Settings("installation", "a402_000000000000_" + "a" * 43, "https://api.example.com", allow_live=True)
+    settings = Access402Settings("installation", "a402_000000000000_" + "a" * 43, "https://api.example.com")
     manager = Access402(settings, transport=httpx.MockTransport(backend))
     @app.get("/reports/{report_id}")
     @manager.protect(price="0.01")
@@ -168,6 +170,87 @@ 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):
+    values = {
+        "ACCESS402_INSTALLATION_ID": "installation",
+        "ACCESS402_API_KEY": "a402_000000000000_" + "a" * 43,
+        "ACCESS402_PUBLIC_BASE_URL": "https://api.example.com",
+    }
+    for name, value in values.items():
+        monkeypatch.setenv(name, value)
+    monkeypatch.delenv("ACCESS402_MODE", raising=False)
+    with pytest.raises(RuntimeError, match="ACCESS402_MODE"):
+        Access402Settings.from_env()
+    monkeypatch.setenv("ACCESS402_MODE", "production")
+    with pytest.raises(RuntimeError, match="sandbox or live"):
+        Access402Settings.from_env()
+    monkeypatch.setenv("ACCESS402_MODE", "live")
+    assert Access402Settings.from_env().mode == "live"
+
+
+@pytest.mark.asyncio
+async def test_live_mode_is_sent_by_the_deployment_for_catalog_and_configuration():
+    api_key = "a402_000000000000_" + "a" * 43
+    seen_modes = []
+
+    async def handler(request):
+        seen_modes.append(request.headers.get("X-Access402-Mode"))
+        if request.url.path.endswith("/adapter/catalog"):
+            return httpx.Response(200, json={"configuration_version": "v1"})
+        body = json.dumps({
+            "x402_version": 2, "installation_id": "installation", "configuration_version": "v1",
+            "generated_at": "now", "environment": "live", "network": "eip155:8453",
+            "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()
+    manager = Access402(
+        Access402Settings("installation", api_key, "https://api.example.com", mode="live"),
+        transport=httpx.MockTransport(handler),
+    )
+    manager.install(app)
+    configuration = await manager.refresh(force=True)
+    await manager.close()
+    assert configuration.environment == "live"
+    assert seen_modes == ["live", "live"]
 
 
 @pytest.mark.asyncio
@@ -193,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()