l402kit 0.1.0__tar.gz

l402kit-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+node_modules/
+dist/
+*.js.map
+*.d.ts.map
+
+# credentials — never commit
+.env
+.env.local
+.env.*.local
+CREDENTIALS.md
+OPERATIONS.md
+
+# claude code local settings (may contain api keys)
+.claude/
+
+# supabase temp (contains project ref and db urls)
+supabase/.temp/
+
+# python cache
+__pycache__/
+*.pyc
+*.pyo
+python/.env
+
+# test files
+test-server.ts
+test-invoice.sh
+
+# phoenixd (old infra, not part of npm package)
+phoenixd/

l402kit-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: l402kit
+Version: 0.1.0
+Summary: Lightning Network L402 payment middleware for FastAPI and Flask
+Project-URL: Homepage, https://github.com/shinydapps/l402-kit
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# l402kit
+
+**Bitcoin Lightning payment middleware for FastAPI and Flask. 3 lines of code.**
+
+```bash
+pip install l402kit
+```
+
+## Usage
+
+```python
+from l402kit import l402_required, BlinkProvider
+
+lightning = BlinkProvider(api_key="...", wallet_id="...")
+
+@app.get("/premium")
+@l402_required(price_sats=100, lightning=lightning)
+async def premium(request: Request):
+    return {"data": "You paid 100 sats!"}
+```
+
+Full docs: https://shinydapps.mintlify.app
+GitHub: https://github.com/ShinyDapps/l402-kit

l402kit-0.1.0/README.md

@@ -0,0 +1,23 @@
+# l402kit
+
+**Bitcoin Lightning payment middleware for FastAPI and Flask. 3 lines of code.**
+
+```bash
+pip install l402kit
+```
+
+## Usage
+
+```python
+from l402kit import l402_required, BlinkProvider
+
+lightning = BlinkProvider(api_key="...", wallet_id="...")
+
+@app.get("/premium")
+@l402_required(price_sats=100, lightning=lightning)
+async def premium(request: Request):
+    return {"data": "You paid 100 sats!"}
+```
+
+Full docs: https://shinydapps.mintlify.app
+GitHub: https://github.com/ShinyDapps/l402-kit

l402kit-0.1.0/examples/fastapi_example.py

@@ -0,0 +1,22 @@
+import os
+from fastapi import FastAPI, Request
+from l402kit import l402_required, BlinkProvider
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = FastAPI()
+
+lightning = BlinkProvider(
+    api_key=os.environ["BLINK_API_KEY"],
+    wallet_id=os.environ["BLINK_WALLET_ID"],
+)
+
+@app.get("/")
+async def root():
+    return {"message": "L402-kit Python SDK. Try GET /premium"}
+
+@app.get("/premium")
+@l402_required(price_sats=100, lightning=lightning)
+async def premium(request: Request):
+    return {"data": "Conteúdo premium — você pagou 100 sats!"}

l402kit-0.1.0/l402kit/__init__.py

@@ -0,0 +1,15 @@
+from .middleware import l402_required
+from .providers.blink import BlinkProvider
+from .providers.opennode import OpenNodeProvider
+from .providers.lnbits import LNbitsProvider
+from .types import LightningProvider, Invoice
+
+__version__ = "0.1.0"
+__all__ = [
+    "l402_required",
+    "BlinkProvider",
+    "OpenNodeProvider",
+    "LNbitsProvider",
+    "LightningProvider",
+    "Invoice",
+]

l402kit-0.1.0/l402kit/middleware.py

@@ -0,0 +1,100 @@
+import functools
+from typing import Callable
+from .types import LightningProvider
+from .verify import verify_token
+from .replay import check_and_mark_preimage
+
+
+def l402_required(price_sats: int, lightning: LightningProvider):
+    """
+    Decorator for FastAPI and Flask routes.
+
+    FastAPI:
+        @app.get("/premium")
+        @l402_required(price_sats=100, lightning=blink)
+        async def premium(): ...
+
+    Flask:
+        @app.route("/premium")
+        @l402_required(price_sats=100, lightning=blink)
+        def premium(): ...
+    """
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        async def fastapi_wrapper(*args, **kwargs):
+            # FastAPI: request comes via kwargs or dependency injection
+            request = kwargs.get("request")
+            if request is None:
+                # Try to find Request in args
+                from fastapi import Request
+                for arg in args:
+                    if isinstance(arg, Request):
+                        request = arg
+                        break
+
+            if request is not None:
+                auth = request.headers.get("authorization", "")
+                if auth.startswith("L402 "):
+                    token = auth[5:]
+                    if verify_token(token):
+                        macaroon, preimage = token.rsplit(":", 1)
+                        if check_and_mark_preimage(preimage):
+                            return await func(*args, **kwargs)
+                        else:
+                            from fastapi.responses import JSONResponse
+                            return JSONResponse({"error": "Token already used"}, status_code=401)
+
+                invoice = await lightning.create_invoice(price_sats)
+                from fastapi.responses import JSONResponse
+                return JSONResponse(
+                    {
+                        "error": "Payment Required",
+                        "price_sats": price_sats,
+                        "invoice": invoice.payment_request,
+                        "macaroon": invoice.macaroon,
+                    },
+                    status_code=402,
+                    headers={
+                        "WWW-Authenticate": f'L402 macaroon="{invoice.macaroon}", invoice="{invoice.payment_request}"'
+                    },
+                )
+
+            return await func(*args, **kwargs)
+
+        @functools.wraps(func)
+        def flask_wrapper(*args, **kwargs):
+            from flask import request, jsonify, make_response
+            import asyncio
+
+            auth = request.headers.get("Authorization", "")
+            if auth.startswith("L402 "):
+                token = auth[5:]
+                if verify_token(token):
+                    macaroon, preimage = token.rsplit(":", 1)
+                    if check_and_mark_preimage(preimage):
+                        return func(*args, **kwargs)
+                    else:
+                        return jsonify({"error": "Token already used"}), 401
+
+            invoice = asyncio.run(lightning.create_invoice(price_sats))
+            resp = make_response(
+                jsonify({
+                    "error": "Payment Required",
+                    "price_sats": price_sats,
+                    "invoice": invoice.payment_request,
+                    "macaroon": invoice.macaroon,
+                }),
+                402,
+            )
+            resp.headers["WWW-Authenticate"] = (
+                f'L402 macaroon="{invoice.macaroon}", invoice="{invoice.payment_request}"'
+            )
+            return resp
+
+        import asyncio
+        import inspect
+        if inspect.iscoroutinefunction(func):
+            return fastapi_wrapper
+        return flask_wrapper
+
+    return decorator

l402kit-0.1.0/l402kit/providers/__init__.py

@@ -0,0 +1,5 @@
+from .blink import BlinkProvider
+from .opennode import OpenNodeProvider
+from .lnbits import LNbitsProvider
+
+__all__ = ["BlinkProvider", "OpenNodeProvider", "LNbitsProvider"]

l402kit-0.1.0/l402kit/providers/blink.py

@@ -0,0 +1,69 @@
+import time
+import base64
+import json
+import httpx
+from ..types import Invoice
+
+
+class BlinkProvider:
+    """
+    Blink Lightning provider — free, no node needed.
+    Get API key at dashboard.blink.sv
+    """
+
+    def __init__(self, api_key: str, wallet_id: str):
+        self.api_key = api_key
+        self.wallet_id = wallet_id
+
+    async def create_invoice(self, amount_sats: int) -> Invoice:
+        query = """
+        mutation CreateInvoice($input: LnInvoiceCreateInput!) {
+          lnInvoiceCreate(input: $input) {
+            invoice { paymentRequest paymentHash }
+            errors { message }
+          }
+        }
+        """
+        async with httpx.AsyncClient() as client:
+            res = await client.post(
+                "https://api.blink.sv/graphql",
+                headers={"X-API-KEY": self.api_key},
+                json={"query": query, "variables": {
+                    "input": {"walletId": self.wallet_id, "amount": amount_sats, "memo": "L402 API access"}
+                }},
+            )
+            res.raise_for_status()
+            data = res.json()["data"]["lnInvoiceCreate"]
+
+            if data.get("errors"):
+                raise Exception(f"Blink error: {data['errors'][0]['message']}")
+
+            inv = data["invoice"]
+            macaroon = base64.b64encode(json.dumps({
+                "hash": inv["paymentHash"],
+                "exp": int(time.time()) + 3600,
+            }).encode()).decode()
+
+            return Invoice(
+                payment_request=inv["paymentRequest"],
+                payment_hash=inv["paymentHash"],
+                macaroon=macaroon,
+                amount_sats=amount_sats,
+                expires_at=int(time.time()) + 3600,
+            )
+
+    async def check_payment(self, payment_hash: str) -> bool:
+        query = """
+        query CheckInvoice($paymentHash: PaymentHash!) {
+          lnInvoice(paymentHash: $paymentHash) { status }
+        }
+        """
+        async with httpx.AsyncClient() as client:
+            res = await client.post(
+                "https://api.blink.sv/graphql",
+                headers={"X-API-KEY": self.api_key},
+                json={"query": query, "variables": {"paymentHash": payment_hash}},
+            )
+            if not res.is_success:
+                return False
+            return res.json().get("data", {}).get("lnInvoice", {}).get("status") == "PAID"

l402kit-0.1.0/l402kit/providers/lnbits.py

@@ -0,0 +1,26 @@
+import time, base64, json
+import httpx
+from ..types import Invoice
+
+
+class LNbitsProvider:
+    def __init__(self, api_key: str, base_url: str = "https://legend.lnbits.com"):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+
+    async def create_invoice(self, amount_sats: int) -> Invoice:
+        async with httpx.AsyncClient() as client:
+            res = await client.post(
+                f"{self.base_url}/api/v1/payments",
+                headers={"X-Api-Key": self.api_key},
+                json={"out": False, "amount": amount_sats, "memo": "L402 API access"},
+            )
+            res.raise_for_status()
+            data = res.json()
+            macaroon = base64.b64encode(json.dumps({"hash": data["payment_hash"], "exp": int(time.time()) + 3600}).encode()).decode()
+            return Invoice(data["payment_request"], data["payment_hash"], macaroon, amount_sats, int(time.time()) + 3600)
+
+    async def check_payment(self, payment_hash: str) -> bool:
+        async with httpx.AsyncClient() as client:
+            res = await client.get(f"{self.base_url}/api/v1/payments/{payment_hash}", headers={"X-Api-Key": self.api_key})
+            return res.is_success and res.json().get("paid", False)

l402kit-0.1.0/l402kit/providers/opennode.py

@@ -0,0 +1,26 @@
+import time, base64, json
+import httpx
+from ..types import Invoice
+
+
+class OpenNodeProvider:
+    def __init__(self, api_key: str, test_mode: bool = False):
+        self.api_key = api_key
+        self.base_url = "https://dev-api.opennode.com" if test_mode else "https://api.opennode.com"
+
+    async def create_invoice(self, amount_sats: int) -> Invoice:
+        async with httpx.AsyncClient() as client:
+            res = await client.post(
+                f"{self.base_url}/v1/charges",
+                headers={"Authorization": self.api_key},
+                json={"amount": amount_sats, "description": "L402 API access", "currency": "SATS"},
+            )
+            res.raise_for_status()
+            data = res.json()["data"]
+            macaroon = base64.b64encode(json.dumps({"hash": data["id"], "exp": int(time.time()) + 3600}).encode()).decode()
+            return Invoice(data["lightning_invoice"]["payreq"], data["id"], macaroon, amount_sats, int(time.time()) + 3600)
+
+    async def check_payment(self, charge_id: str) -> bool:
+        async with httpx.AsyncClient() as client:
+            res = await client.get(f"{self.base_url}/v1/charge/{charge_id}", headers={"Authorization": self.api_key})
+            return res.is_success and res.json().get("data", {}).get("status") == "paid"

l402kit-0.1.0/l402kit/replay.py

@@ -0,0 +1,11 @@
+import hashlib
+
+_used_preimages: set[str] = set()
+
+
+def check_and_mark_preimage(preimage: str) -> bool:
+    key = hashlib.sha256(preimage.encode()).hexdigest()
+    if key in _used_preimages:
+        return False
+    _used_preimages.add(key)
+    return True

l402kit-0.1.0/l402kit/types.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass
+class Invoice:
+    payment_request: str
+    payment_hash: str
+    macaroon: str
+    amount_sats: int
+    expires_at: int
+
+
+class LightningProvider(Protocol):
+    async def create_invoice(self, amount_sats: int) -> Invoice: ...
+    async def check_payment(self, payment_hash: str) -> bool: ...

l402kit-0.1.0/l402kit/verify.py

@@ -0,0 +1,33 @@
+import hashlib
+import base64
+import json
+import time
+import re
+
+
+def parse_token(token: str) -> tuple[str, str]:
+    idx = token.rfind(":")
+    if idx == -1:
+        raise ValueError("Invalid L402 token format")
+    return token[:idx], token[idx + 1:]
+
+
+def verify_token(token: str) -> bool:
+    try:
+        macaroon, preimage = parse_token(token)
+
+        if not macaroon or not re.fullmatch(r"[0-9a-fA-F]{64}", preimage):
+            return False
+
+        payload = json.loads(base64.b64decode(macaroon).decode())
+        if not payload.get("hash") or not payload.get("exp"):
+            return False
+
+        if int(time.time()) > payload["exp"]:
+            return False
+
+        digest = hashlib.sha256(bytes.fromhex(preimage)).hexdigest()
+        return digest == payload["hash"]
+
+    except Exception:
+        return False

l402kit-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "l402kit"
+version = "0.1.0"
+description = "Lightning Network L402 payment middleware for FastAPI and Flask"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110"]
+flask = ["flask>=3.0"]
+
+[project.urls]
+Homepage = "https://github.com/shinydapps/l402-kit"