conduit-lightning 0.1.0__py3-none-any.whl

conduit/__init__.py

@@ -0,0 +1,3 @@
+"""Conduit - Lightning Payment Rails for AI Agents."""
+
+__version__ = "0.1.0"

conduit/api/deps.py

@@ -0,0 +1,105 @@
+"""Shared API dependencies — auth, LND client, database sessions."""
+
+import hmac
+import sys
+from typing import Annotated
+
+from fastapi import Header, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from conduit.core.config import settings
+from conduit.core.database import async_session_factory
+from conduit.services.wallet_backend import WalletBackend
+
+# =============================================================================
+# Authentication
+# =============================================================================
+
+
+async def verify_api_key(
+    x_api_key: Annotated[str | None, Header()] = None,
+) -> str:
+    """Validate the X-API-Key header against the configured key.
+
+    The header is declared optional so a *missing* key returns 401
+    Unauthorized (the correct status for absent credentials) instead of
+    FastAPI's default 422 for a missing required header.
+
+    Uses a constant-time comparison so an attacker probing the API over
+    the network can't recover the key one character at a time via
+    response-timing differences.
+    """
+    expected = settings.conduit_api_key or ""
+    # Reject the default placeholder explicitly — otherwise a misconfigured
+    # server would accept "CHANGE-ME" as a valid key.
+    if not expected or expected.startswith("CHANGE-ME"):
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Server is not configured: CONDUIT_API_KEY is unset.",
+        )
+    provided = x_api_key or ""
+    # compare_digest against an empty string still runs (and fails) in constant
+    # time, so a missing key follows the same path and timing as a wrong one.
+    if not hmac.compare_digest(provided.encode("utf-8"), expected.encode("utf-8")):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid API key",
+        )
+    return x_api_key
+
+
+# =============================================================================
+# LND Client (lazy singleton)
+# =============================================================================
+
+_wallet: WalletBackend | None = None
+
+
+def get_lnd() -> WalletBackend:
+    """Get or create the wallet backend connection.
+
+    Name kept as get_lnd() for backward compatibility — all existing
+    callers use this function. The returned object implements
+    WalletBackend and may be LND, NWC, or any future backend.
+    """
+    global _wallet
+    if _wallet is None or not _wallet.is_connected:
+        _wallet = _create_wallet_backend()
+        _wallet.connect()
+    return _wallet
+
+
+def _create_wallet_backend() -> WalletBackend:
+    """Factory: pick the right backend based on config."""
+    backend = getattr(settings, "wallet_backend", "lnd").lower()
+
+    # Auto-detect: if NWC connection string is set, use NWC
+    nwc_uri = getattr(settings, "nwc_connection_string", "") or ""
+    if backend == "auto":
+        backend = "nwc" if nwc_uri else "lnd"
+
+    if backend == "nwc":
+        if not nwc_uri:
+            raise RuntimeError(
+                "WALLET_BACKEND=nwc but NWC_CONNECTION_STRING is not set. "
+                "Paste your nostr+walletconnect:// URI in .env."
+            )
+        from conduit.services.nwc import NwcWalletBackend
+        print("[api] Using NWC wallet backend", file=sys.stderr)
+        return NwcWalletBackend(nwc_uri)
+
+    # Default: LND
+    from conduit.services.lnd import LndClient
+    print("[api] Using LND wallet backend", file=sys.stderr)
+    return LndClient()
+
+
+# =============================================================================
+# Database Session
+# =============================================================================
+
+
+async def get_session() -> AsyncSession:
+    """Create a new async database session."""
+    async with async_session_factory() as session:
+        yield session

conduit/api/middleware/__init__.py

@@ -0,0 +1,7 @@
+"""Conduit API middleware."""
+
+from conduit.api.middleware.l402 import L402Middleware
+from conduit.api.middleware.rate_limit import RateLimitMiddleware
+from conduit.api.middleware.verification import VerificationEnforcementMiddleware
+
+__all__ = ["L402Middleware", "RateLimitMiddleware", "VerificationEnforcementMiddleware"]

conduit/api/middleware/l402.py

@@ -0,0 +1,205 @@
+"""
+L402 FastAPI middleware — adds HTTP 402 payment-gated authentication.
+
+How it works:
+  1. Request arrives at a protected endpoint.
+  2. Middleware checks for Authorization: L402 <macaroon>:<preimage> header.
+     - If present and valid → request passes through (authenticated via L402).
+     - If present but invalid → 401 with error details.
+  3. If no L402 header, checks for X-API-Key header (backward compat).
+     - If present and valid → request passes through (API key auth).
+  4. If neither credential is present:
+     - If L402 is enabled → 402 with WWW-Authenticate header + invoice.
+     - If L402 is disabled → 401 "API key required" (existing behavior).
+
+This means L402 and API key auth coexist. Operators who don't enable L402
+get the exact same behavior as before. Operators who enable it get a
+pay-per-request alternative that doesn't require pre-shared keys.
+
+The middleware is applied as a Starlette middleware, not a FastAPI dependency,
+so it intercepts requests before routing and can set the 402 response with
+the correct headers regardless of which router handles the endpoint.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from conduit.core.config import settings
+from conduit.services.l402 import (
+    create_l402_challenge,
+    format_www_authenticate,
+    parse_l402_header,
+    verify_l402,
+)
+
+
+class L402Middleware(BaseHTTPMiddleware):
+    """
+    Starlette middleware that implements the L402 payment-gate protocol.
+
+    When L402 is enabled (L402_ENABLED=true), endpoints that don't match
+    a free-route prefix will require either:
+      - A valid X-API-Key header (existing auth), OR
+      - A valid Authorization: L402 <macaroon>:<preimage> header.
+
+    If neither is present, the middleware returns 402 Payment Required
+    with a freshly minted invoice.
+    """
+
+    def __init__(self, app, get_lnd_fn: Callable | None = None):
+        """
+        Args:
+            app: the ASGI application.
+            get_lnd_fn: callable that returns an LndClient. Injected so the
+                        middleware doesn't import the LND singleton at module
+                        level (avoids circular imports and makes testing easier).
+        """
+        super().__init__(app)
+        self._get_lnd = get_lnd_fn
+
+    async def dispatch(self, request: Request, call_next):
+        # If L402 is not enabled, pass through — existing API key auth handles it.
+        if not settings.l402_enabled:
+            return await call_next(request)
+
+        # Check if this route is free (no payment required).
+        path = request.url.path
+        if self._is_free_route(path):
+            return await call_next(request)
+
+        # ── Try L402 credential first ───────────────────────────────
+        auth_header = request.headers.get("authorization", "")
+        l402_cred = parse_l402_header(auth_header)
+
+        if l402_cred is not None:
+            result = verify_l402(l402_cred)
+            if result.valid:
+                # Attach L402 metadata to request state for downstream use.
+                request.state.l402_payment_hash = result.payment_hash
+                request.state.l402_resource = result.resource
+                request.state.auth_method = "l402"
+                return await call_next(request)
+            else:
+                return JSONResponse(
+                    status_code=401,
+                    content={
+                        "error": "l402_invalid",
+                        "detail": result.error,
+                    },
+                )
+
+        # ── Try API key (backward compat) ───────────────────────────
+        api_key = request.headers.get("x-api-key", "")
+        if api_key:
+            # Let the existing verify_api_key dependency handle validation.
+            # We just pass through here; the router dependency will 401 if bad.
+            return await call_next(request)
+
+        # ── No credentials at all → issue 402 challenge ─────────────
+        return await self._issue_challenge(request)
+
+    async def _issue_challenge(self, request: Request) -> JSONResponse:
+        """Return a 402 Payment Required response with L402 challenge."""
+        if self._get_lnd is None:
+            return JSONResponse(
+                status_code=503,
+                content={"error": "L402 enabled but LND client not configured"},
+            )
+
+        try:
+            lnd = self._get_lnd()
+        except Exception as e:
+            print(f"[l402] Could not connect to LND: {e}", file=sys.stderr)
+            return JSONResponse(
+                status_code=503,
+                content={"error": "Lightning node unavailable for L402 challenge"},
+            )
+
+        # Determine price for this endpoint.
+        price = self._get_price_for_route(request.url.path)
+
+        # Determine resource scope from the route.
+        resource = self._route_to_resource(request.url.path)
+
+        try:
+            challenge = create_l402_challenge(
+                lnd,
+                amount_sats=price,
+                memo=f"Conduit L402: {request.method} {request.url.path}",
+                resource=resource,
+            )
+        except Exception as e:
+            print(f"[l402] Failed to create challenge: {e}", file=sys.stderr)
+            return JSONResponse(
+                status_code=503,
+                content={"error": "Failed to generate L402 invoice"},
+            )
+
+        return JSONResponse(
+            status_code=402,
+            content={
+                "error": "payment_required",
+                "message": (
+                    "Pay the Lightning invoice, then retry with "
+                    "Authorization: L402 <macaroon>:<preimage>"
+                ),
+                "macaroon": challenge.macaroon,
+                "invoice": challenge.invoice,
+                "payment_hash": challenge.payment_hash,
+                "amount_sats": challenge.amount_sats,
+                "expires_at": challenge.expires_at,
+            },
+            headers={
+                "WWW-Authenticate": format_www_authenticate(challenge),
+            },
+        )
+
+    def _is_free_route(self, path: str) -> bool:
+        """Check if a route is free (no L402 or API key required)."""
+        for prefix in settings.l402_free_route_list:
+            # Exact match for "/" to avoid matching everything
+            if prefix == "/":
+                if path == "/":
+                    return True
+            elif path.startswith(prefix):
+                return True
+        return False
+
+    def _get_price_for_route(self, path: str) -> int:
+        """
+        Determine the price in sats for an endpoint.
+
+        Currently uses the global default. Future: per-skill pricing
+        based on the skill's registered price_sats.
+        """
+        # Skill execution endpoints could use the skill's own price.
+        # For now, use the global default.
+        return settings.l402_default_price_sats
+
+    def _route_to_resource(self, path: str) -> str | None:
+        """
+        Map a route path to an L402 resource scope.
+
+        This constrains the minted token so it can only be used for the
+        resource the client originally requested — prevents a token bought
+        for GET /balance being replayed on POST /payments.
+        """
+        # Strip /api/v1 prefix for cleaner resource names
+        clean = path.removeprefix("/api/v1")
+
+        if clean.startswith("/lightning"):
+            return "lightning"
+        elif clean.startswith("/marketplace"):
+            return "marketplace"
+        elif clean.startswith("/security"):
+            return "security"
+        elif clean.startswith("/nostr"):
+            return "nostr"
+
+        return None

conduit/api/middleware/rate_limit.py

@@ -0,0 +1,151 @@
+"""
+Rate limiting middleware — applies per-client, per-tool rate limits at the
+HTTP layer.
+
+Maps each REST route + method to its corresponding MCP tool name, extracts
+the client identifier from the X-API-Key header (hashed for privacy), then
+delegates to the SlidingWindowRateLimiter. Returns 429 with a Retry-After
+header when the limit is exceeded.
+
+This replaces the inline try/except blocks previously duplicated in every
+router handler, centralizing rate limiting in one place so new endpoints
+get protected automatically.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from conduit.services.rate_limiter import RateLimitExceeded, rate_limiter
+
+# =============================================================================
+# Route → tool name mapping
+# =============================================================================
+
+# Each entry maps (HTTP method, route pattern) to a tool name.
+# Patterns are matched top-to-bottom; first match wins.
+# Use {param} for path parameters.
+
+_ROUTE_TOOL_MAP: list[tuple[str, str, str]] = [
+    # Lightning
+    ("GET",  "/api/v1/lightning/node-info",          "get_node_info"),
+    ("GET",  "/api/v1/lightning/balance",             "get_balance"),
+    ("POST", "/api/v1/lightning/invoices/decode",     "decode_invoice"),
+    ("POST", "/api/v1/lightning/invoices",            "create_invoice"),
+    ("POST", "/api/v1/lightning/payments",            "pay_invoice"),
+    ("GET",  "/api/v1/lightning/payments/{param}",    "check_payment"),
+
+    # Marketplace
+    ("GET",  "/api/v1/marketplace/skills",                          "discover_skills"),
+    ("POST", "/api/v1/marketplace/skills",                          "register_skill"),
+    ("GET",  "/api/v1/marketplace/skills/{param}",                  "get_skill_details"),
+    ("POST", "/api/v1/marketplace/executions",                      "request_skill_execution"),
+    ("POST", "/api/v1/marketplace/executions/{param}/confirm",      "confirm_skill_execution"),
+    ("POST", "/api/v1/marketplace/executions/{param}/rate",         "submit_rating"),
+
+    # Security
+    ("GET",  "/api/v1/security/spending",             "get_spending_status"),
+    ("POST", "/api/v1/security/macaroons",            "create_macaroon"),
+    ("GET",  "/api/v1/security/permissions",           "list_permissions"),
+    ("GET",  "/api/v1/security/anomalies",            "get_anomaly_report"),
+    ("POST", "/api/v1/security/verification/request", "request_verification"),
+    ("POST", "/api/v1/security/verification/submit",  "submit_verification"),
+    ("GET",  "/api/v1/security/verification/{param}", "get_verification_status"),
+
+    # Nostr
+    ("POST", "/api/v1/nostr/publish",                 "nostr_publish_skill"),
+    ("GET",  "/api/v1/nostr/discover",                "nostr_discover_skills"),
+    ("GET",  "/api/v1/nostr/profile",                 "nostr_get_profile"),
+    ("GET",  "/api/v1/nostr/relays/status",           "nostr_relay_status"),
+
+    # Admin (M7: rate-limit admin routes — very low limits)
+    ("GET",    "/api/v1/admin/stats",                  "admin_stats"),
+    ("DELETE", "/api/v1/admin/reset-demo",             "admin_reset"),
+    ("DELETE", "/api/v1/marketplace/skills/{param}",   "admin_delete_skill"),
+    ("DELETE", "/api/v1/marketplace/executions/{param}", "admin_delete_execution"),
+]
+
+# Pre-compile patterns: replace {param} with a regex group that matches
+# one path segment (no slashes).
+_COMPILED_ROUTES: list[tuple[str, re.Pattern, str]] = []
+for method, pattern, tool in _ROUTE_TOOL_MAP:
+    regex = re.escape(pattern).replace(r"\{param\}", r"[^/]+")
+    _COMPILED_ROUTES.append((method, re.compile(f"^{regex}$"), tool))
+
+
+def _resolve_tool(method: str, path: str) -> str | None:
+    """Match a request method + path to a tool name, or None if no match."""
+    for route_method, regex, tool in _COMPILED_ROUTES:
+        if method == route_method and regex.match(path):
+            return tool
+    return None
+
+
+# =============================================================================
+# Middleware
+# =============================================================================
+
+
+def _extract_client_id(request: Request) -> str | None:
+    """
+    Extract a client identifier from the request for per-client rate limiting.
+
+    Uses a SHA-256 hash of the API key so the actual key is never stored
+    in Redis or logs.  Returns None if no API key is present (the limiter
+    will use a global counter).
+    """
+    api_key = request.headers.get("x-api-key")
+    if not api_key:
+        return None
+    # Short hash — enough for uniqueness, not reversible
+    return hashlib.sha256(api_key.encode()).hexdigest()[:16]
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    """
+    Starlette middleware that enforces per-client, per-tool rate limits on
+    REST endpoints.
+
+    Sits early in the middleware stack so rate-limited requests are rejected
+    before touching auth, database, or LND. Unmatched routes (health, docs,
+    root) pass through without rate limiting.
+
+    Each API key gets its own independent rate limit window — one client
+    hitting the limit doesn't affect other clients.
+    """
+
+    async def dispatch(self, request: Request, call_next):
+        tool = _resolve_tool(request.method, request.url.path)
+
+        if tool is None:
+            # Unrecognized route — health, docs, OpenAPI, etc. Pass through.
+            return await call_next(request)
+
+        client_id = _extract_client_id(request)
+
+        try:
+            rate_limiter.check(tool, client_id=client_id)
+        except RateLimitExceeded as e:
+            # L2: Use structured retry_after_seconds instead of regex parsing
+            retry_after = getattr(e, "retry_after_seconds", 60)
+            return JSONResponse(
+                status_code=429,
+                content={
+                    "error": "rate_limit_exceeded",
+                    "detail": str(e),
+                    "tool": tool,
+                },
+                headers={
+                    "Retry-After": str(retry_after),
+                },
+            )
+
+        # Attach the resolved tool name to request state so downstream
+        # handlers can use it for logging/metrics without re-resolving.
+        request.state.rate_limit_tool = tool
+        return await call_next(request)

conduit/api/middleware/verification.py

@@ -0,0 +1,160 @@
+"""
+Verification enforcement middleware — warns or blocks on unverified skills.
+
+Applies to skill execution endpoints. When a consumer requests execution
+of an unverified skill, the middleware:
+
+  1. Adds an X-Conduit-Verification-Warning header to the response so the
+     consumer's agent can surface the risk to the user.
+  2. If the consumer set ?require_verified=true (or the operator configured
+     REQUIRE_VERIFIED_SKILLS=true), returns 403 instead of proceeding.
+
+This does NOT block skill discovery or registration — only execution of
+unverified skills carries a warning or gate.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from conduit.core.config import settings
+
+# Execution endpoints that should check verification status.
+# Match: POST /api/v1/marketplace/executions (request execution)
+# Match: POST /api/v1/marketplace/executions/{id}/confirm
+_EXECUTION_RE = re.compile(
+    r"^/api/v1/marketplace/executions(?:/[^/]+/confirm)?$"
+)
+
+
+class VerificationEnforcementMiddleware(BaseHTTPMiddleware):
+    """
+    Starlette middleware that enforces provider verification on execution.
+
+    Injects itself between rate-limiting and routing. For execution
+    endpoints, looks up the skill's verification status and either:
+      - Adds a warning header (default behavior), or
+      - Blocks the request with 403 if enforcement is strict.
+
+    The skill_id comes from the request body for new executions (POST
+    /executions with skill_id in JSON) or from the execution record for
+    confirmations. For confirmations we pass through since the skill was
+    already checked at request time.
+    """
+
+    def __init__(self, app, get_session_fn: Callable | None = None):
+        super().__init__(app)
+        self._get_session = get_session_fn
+
+    async def dispatch(self, request: Request, call_next):
+        # Only check POST to execution endpoints
+        if request.method != "POST":
+            return await call_next(request)
+
+        path = request.url.path
+
+        # Only enforce on new execution requests (not confirm/rate)
+        if path != "/api/v1/marketplace/executions":
+            return await call_next(request)
+
+        # Check if enforcement is required (operator config or query param)
+        require_verified = settings.require_verified_skills
+        if not require_verified:
+            # Check query param override
+            require_param = request.query_params.get("require_verified", "")
+            require_verified = require_param.lower() in ("true", "1", "yes")
+
+        # Read the skill_id from the request body
+        skill_id = await self._extract_skill_id(request)
+        if not skill_id:
+            # Can't determine skill — let the router handle validation
+            return await call_next(request)
+
+        # Look up verification status
+        verification_status = await self._get_verification_status(skill_id)
+
+        if verification_status is None:
+            # Skill not found — let the router 404
+            return await call_next(request)
+
+        is_verified = verification_status in ("node_verified", "domain_verified", "fully_verified")
+
+        if not is_verified and require_verified:
+            return JSONResponse(
+                status_code=403,
+                content={
+                    "error": "skill_not_verified",
+                    "detail": (
+                        f"Skill is '{verification_status}'. Execution of "
+                        f"unverified skills is blocked by policy. The provider "
+                        f"must complete node or domain verification first."
+                    ),
+                    "verification_status": verification_status,
+                    "skill_id": skill_id,
+                },
+                headers={
+                    "X-Conduit-Verification": verification_status,
+                },
+            )
+
+        # Proceed with the request, adding a warning header if unverified
+        response = await call_next(request)
+
+        if not is_verified:
+            response.headers["X-Conduit-Verification-Warning"] = (
+                f"Skill is '{verification_status}'. "
+                "Provider has not completed verification."
+            )
+        response.headers["X-Conduit-Verification"] = verification_status
+
+        return response
+
+    async def _extract_skill_id(self, request: Request) -> str | None:
+        """Extract skill_id from the JSON request body.
+
+        H11: Uses request.body() instead of request.json() so the raw
+        bytes are cached on the Request object. This avoids consuming
+        the ASGI receive stream, which would leave downstream handlers
+        with an empty body in some BaseHTTPMiddleware configurations.
+        """
+        try:
+            import json
+            raw = await request.body()
+            body = json.loads(raw)
+            return body.get("skill_id")
+        except Exception:
+            return None
+
+    async def _get_verification_status(self, skill_id: str) -> str | None:
+        """Look up a skill's verification status from the database."""
+        if not self._get_session:
+            return None
+
+        try:
+            import uuid
+
+            from sqlalchemy import select
+
+            from conduit.models.skill import Skill
+
+            uid = uuid.UUID(skill_id)
+            session_factory = self._get_session
+
+            async with session_factory() as session:
+                result = await session.execute(
+                    select(Skill.verification_status).where(Skill.id == uid)
+                )
+                row = result.scalar_one_or_none()
+                return row
+        except Exception as e:
+            print(
+                f"[verification-middleware] Could not check skill {skill_id}: {e}",
+                file=sys.stderr,
+            )
+            return None

conduit/api/routers/__init__.py

@@ -0,0 +1,5 @@
+"""API routers — Lightning, Marketplace, Security, Nostr."""
+
+from conduit.api.routers import lightning, marketplace, nostr, security
+
+__all__ = ["lightning", "marketplace", "security", "nostr"]