x402-firewall 0.1.0__tar.gz

x402_firewall-0.1.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: x402-firewall
+Version: 0.1.0
+Summary: Spending firewall middleware for x402 payments. Policy engine, approval queue, and audit log for AI agents.
+License: Apache-2.0
+Project-URL: Homepage, https://bonanza-labs.com
+Project-URL: Repository, https://github.com/c6zks4gssn-droid/x402-firewall
+Project-URL: Issues, https://github.com/c6zks4gssn-droid/x402-firewall/issues
+Keywords: x402,payments,ai,agents,firewall,policy,spending,mcp,blockchain,base,usdc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+
+# x402-firewall
+
+**Spending firewall middleware for x402 payments.**
+
+```python
+@guard(budget_usd=25.00, require_approval_above=5.00)
+async def my_agent():
+    fw = get_firewall()
+    data = await fw.pay_x402("https://data.example.com/report", max_usd=1.50)
+```
+
+Every x402 payment inside the decorated function is checked against your policy before it executes. Too expensive → blocked. Above the approval threshold → paused until a human approves. Over budget → raises immediately. Everything is audit-logged.
+
+---
+
+## Install
+
+```bash
+pip install x402-firewall
+```
+
+Zero required dependencies.
+
+---
+
+## Quickstart
+
+```python
+import asyncio
+from x402_firewall import guard, get_firewall, PaymentBlocked, PaymentPendingApproval
+
+@guard(
+    budget_usd=25.00,           # max total spend per call
+    require_approval_above=5.00, # payments ≥ $5 need human approval
+    block_vendors=["untrusted-vendor.com"],
+)
+async def research_agent(query: str):
+    fw = get_firewall()
+
+    # This payment is $1.50 — allowed immediately
+    result = await fw.pay_x402(
+        "https://data.example.com/report",
+        max_usd=1.50,
+        chain="base",
+    )
+
+    # This payment is $8.00 — escalated to approval queue
+    # (blocks here until a human approves or timeout)
+    premium = await fw.pay_x402(
+        "https://premium.example.com/dataset",
+        max_usd=8.00,
+        chain="base",
+    )
+
+    return result, premium
+
+asyncio.run(research_agent("latest AI research"))
+```
+
+---
+
+## Policy options
+
+```python
+@guard(
+    budget_usd=25.00,               # session budget cap
+    max_single_payment_usd=10.00,   # hard cap per payment
+    require_approval_above=5.00,    # escalate above this amount
+    block_vendors=["spam.com", r".*\.evil\.com$"],  # regex supported
+    allow_vendors=["trusted.com"],  # allowlist mode (blocks all others)
+    allow_chains=["base", "solana"],# only these chains
+    block_chains=["ethereum"],      # block specific chains
+    max_payments_per_session=10,    # max number of payments
+)
+async def my_agent(): ...
+```
+
+---
+
+## Human approval queue
+
+When a payment exceeds `require_approval_above`, the agent pauses and waits for a human decision. You can wire up any notification channel.
+
+### Webhook (Slack, custom server)
+
+```python
+@guard(
+    budget_usd=50.00,
+    require_approval_above=2.00,
+    webhook_url="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+    approval_timeout=300.0,  # seconds to wait (default: 300)
+)
+async def my_agent(): ...
+```
+
+The webhook receives a POST with:
+```json
+{
+  "request_id": "abc-123",
+  "amount_usd": 8.50,
+  "vendor": "premium.example.com",
+  "chain": "base",
+  "session_id": "sess-4f2a"
+}
+```
+
+Your server calls `queue.resolve(request_id, approved=True)` to unblock the agent.
+
+### Custom notification (callback)
+
+```python
+from x402_firewall import ApprovalQueue
+
+queue = ApprovalQueue(
+    on_pending=lambda req: send_telegram(
+        f"Approve payment of ${req.amount_usd:.2f} to {req.vendor}? "
+        f"ID: {req.request_id}"
+    )
+)
+
+@guard(budget_usd=50.00, require_approval_above=2.00, approval_queue=queue)
+async def my_agent(): ...
+
+# From your Telegram bot handler:
+queue.resolve("abc-123", approved=True, approver="Clarence")
+```
+
+### In-process approval (for testing)
+
+```python
+from x402_firewall import ApprovalQueue
+import asyncio
+
+queue = ApprovalQueue()
+
+@guard(budget_usd=50.00, require_approval_above=2.00, approval_queue=queue)
+async def my_agent(): ...
+
+async def main():
+    task = asyncio.create_task(my_agent())
+    await asyncio.sleep(0.1)          # let the agent reach the payment
+    queue.auto_approve()              # approve all pending
+    await task
+```
+
+---
+
+## Audit log
+
+Every payment decision is recorded — blocked, allowed, escalated, approved, rejected.
+
+```python
+from x402_firewall import AuditLog, guard, get_firewall
+
+log = AuditLog(path="/var/log/x402-agent.jsonl")  # or None for in-memory
+
+@guard(budget_usd=25.00, audit_log=log)
+async def my_agent(): ...
+
+# After the run:
+entries = log.entries_for_session("sess-abc")
+print(f"Total spent: ${log.total_spent('sess-abc'):.4f}")
+```
+
+Each JSONL line:
+```json
+{
+  "decision": "allowed",
+  "amount_usd": 1.5,
+  "vendor": "data.example.com",
+  "chain": "base",
+  "session_id": "sess-4f2a",
+  "timestamp": 1750000000.0,
+  "reason": "",
+  "approver": ""
+}
+```
+
+---
+
+## Manual firewall (no decorator)
+
+```python
+from x402_firewall import Firewall, FirewallContext, Policy, AuditLog
+
+fw = Firewall(
+    policy=Policy(budget_usd=25.00, require_approval_above=5.00),
+    audit_log=AuditLog(path="/var/log/x402.jsonl"),
+)
+ctx = FirewallContext(session_id="my-agent-session")
+
+# Pre-flight check
+await fw.check_payment(1.50, "https://data.example.com/r", "base", ctx)
+
+# Or full payment flow
+response = await fw.pay_x402("https://data.example.com/r", max_usd=1.50, ctx=ctx)
+```
+
+---
+
+## Load from YAML config
+
+```yaml
+# policy.yaml
+budget_usd: 25.00
+require_approval_above: 5.00
+block_vendors:
+  - "untrusted.com"
+  - ".*\\.spam\\..*"
+allow_chains:
+  - base
+  - solana
+max_payments_per_session: 20
+```
+
+```python
+import yaml
+from x402_firewall import Policy, Firewall
+
+with open("policy.yaml") as f:
+    policy = Policy.from_dict(yaml.safe_load(f))
+
+fw = Firewall(policy=policy)
+```
+
+---
+
+## EU AI Act compliance
+
+The `require_approval_above` threshold combined with the audit log gives you **Article 14 (human-in-the-loop) compliance** for AI agents making financial decisions. Every escalated payment is:
+- Paused before execution
+- Sent to a designated human approver
+- Logged with approver identity and timestamp
+
+This is the documented compliance mechanism for high-risk AI systems under the EU AI Act (enforcement starts August 2026).
+
+For teams needing a managed dashboard, hosted approval queue, and compliance reports:
+→ **[bonanza-labs.com/firewall](https://bonanza-labs.com/firewall)**
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+
+Built by [Bonanza Labs](https://bonanza-labs.com).

x402_firewall-0.1.0/README.md

@@ -0,0 +1,246 @@
+# x402-firewall
+
+**Spending firewall middleware for x402 payments.**
+
+```python
+@guard(budget_usd=25.00, require_approval_above=5.00)
+async def my_agent():
+    fw = get_firewall()
+    data = await fw.pay_x402("https://data.example.com/report", max_usd=1.50)
+```
+
+Every x402 payment inside the decorated function is checked against your policy before it executes. Too expensive → blocked. Above the approval threshold → paused until a human approves. Over budget → raises immediately. Everything is audit-logged.
+
+---
+
+## Install
+
+```bash
+pip install x402-firewall
+```
+
+Zero required dependencies.
+
+---
+
+## Quickstart
+
+```python
+import asyncio
+from x402_firewall import guard, get_firewall, PaymentBlocked, PaymentPendingApproval
+
+@guard(
+    budget_usd=25.00,           # max total spend per call
+    require_approval_above=5.00, # payments ≥ $5 need human approval
+    block_vendors=["untrusted-vendor.com"],
+)
+async def research_agent(query: str):
+    fw = get_firewall()
+
+    # This payment is $1.50 — allowed immediately
+    result = await fw.pay_x402(
+        "https://data.example.com/report",
+        max_usd=1.50,
+        chain="base",
+    )
+
+    # This payment is $8.00 — escalated to approval queue
+    # (blocks here until a human approves or timeout)
+    premium = await fw.pay_x402(
+        "https://premium.example.com/dataset",
+        max_usd=8.00,
+        chain="base",
+    )
+
+    return result, premium
+
+asyncio.run(research_agent("latest AI research"))
+```
+
+---
+
+## Policy options
+
+```python
+@guard(
+    budget_usd=25.00,               # session budget cap
+    max_single_payment_usd=10.00,   # hard cap per payment
+    require_approval_above=5.00,    # escalate above this amount
+    block_vendors=["spam.com", r".*\.evil\.com$"],  # regex supported
+    allow_vendors=["trusted.com"],  # allowlist mode (blocks all others)
+    allow_chains=["base", "solana"],# only these chains
+    block_chains=["ethereum"],      # block specific chains
+    max_payments_per_session=10,    # max number of payments
+)
+async def my_agent(): ...
+```
+
+---
+
+## Human approval queue
+
+When a payment exceeds `require_approval_above`, the agent pauses and waits for a human decision. You can wire up any notification channel.
+
+### Webhook (Slack, custom server)
+
+```python
+@guard(
+    budget_usd=50.00,
+    require_approval_above=2.00,
+    webhook_url="https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
+    approval_timeout=300.0,  # seconds to wait (default: 300)
+)
+async def my_agent(): ...
+```
+
+The webhook receives a POST with:
+```json
+{
+  "request_id": "abc-123",
+  "amount_usd": 8.50,
+  "vendor": "premium.example.com",
+  "chain": "base",
+  "session_id": "sess-4f2a"
+}
+```
+
+Your server calls `queue.resolve(request_id, approved=True)` to unblock the agent.
+
+### Custom notification (callback)
+
+```python
+from x402_firewall import ApprovalQueue
+
+queue = ApprovalQueue(
+    on_pending=lambda req: send_telegram(
+        f"Approve payment of ${req.amount_usd:.2f} to {req.vendor}? "
+        f"ID: {req.request_id}"
+    )
+)
+
+@guard(budget_usd=50.00, require_approval_above=2.00, approval_queue=queue)
+async def my_agent(): ...
+
+# From your Telegram bot handler:
+queue.resolve("abc-123", approved=True, approver="Clarence")
+```
+
+### In-process approval (for testing)
+
+```python
+from x402_firewall import ApprovalQueue
+import asyncio
+
+queue = ApprovalQueue()
+
+@guard(budget_usd=50.00, require_approval_above=2.00, approval_queue=queue)
+async def my_agent(): ...
+
+async def main():
+    task = asyncio.create_task(my_agent())
+    await asyncio.sleep(0.1)          # let the agent reach the payment
+    queue.auto_approve()              # approve all pending
+    await task
+```
+
+---
+
+## Audit log
+
+Every payment decision is recorded — blocked, allowed, escalated, approved, rejected.
+
+```python
+from x402_firewall import AuditLog, guard, get_firewall
+
+log = AuditLog(path="/var/log/x402-agent.jsonl")  # or None for in-memory
+
+@guard(budget_usd=25.00, audit_log=log)
+async def my_agent(): ...
+
+# After the run:
+entries = log.entries_for_session("sess-abc")
+print(f"Total spent: ${log.total_spent('sess-abc'):.4f}")
+```
+
+Each JSONL line:
+```json
+{
+  "decision": "allowed",
+  "amount_usd": 1.5,
+  "vendor": "data.example.com",
+  "chain": "base",
+  "session_id": "sess-4f2a",
+  "timestamp": 1750000000.0,
+  "reason": "",
+  "approver": ""
+}
+```
+
+---
+
+## Manual firewall (no decorator)
+
+```python
+from x402_firewall import Firewall, FirewallContext, Policy, AuditLog
+
+fw = Firewall(
+    policy=Policy(budget_usd=25.00, require_approval_above=5.00),
+    audit_log=AuditLog(path="/var/log/x402.jsonl"),
+)
+ctx = FirewallContext(session_id="my-agent-session")
+
+# Pre-flight check
+await fw.check_payment(1.50, "https://data.example.com/r", "base", ctx)
+
+# Or full payment flow
+response = await fw.pay_x402("https://data.example.com/r", max_usd=1.50, ctx=ctx)
+```
+
+---
+
+## Load from YAML config
+
+```yaml
+# policy.yaml
+budget_usd: 25.00
+require_approval_above: 5.00
+block_vendors:
+  - "untrusted.com"
+  - ".*\\.spam\\..*"
+allow_chains:
+  - base
+  - solana
+max_payments_per_session: 20
+```
+
+```python
+import yaml
+from x402_firewall import Policy, Firewall
+
+with open("policy.yaml") as f:
+    policy = Policy.from_dict(yaml.safe_load(f))
+
+fw = Firewall(policy=policy)
+```
+
+---
+
+## EU AI Act compliance
+
+The `require_approval_above` threshold combined with the audit log gives you **Article 14 (human-in-the-loop) compliance** for AI agents making financial decisions. Every escalated payment is:
+- Paused before execution
+- Sent to a designated human approver
+- Logged with approver identity and timestamp
+
+This is the documented compliance mechanism for high-risk AI systems under the EU AI Act (enforcement starts August 2026).
+
+For teams needing a managed dashboard, hosted approval queue, and compliance reports:
+→ **[bonanza-labs.com/firewall](https://bonanza-labs.com/firewall)**
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).
+
+Built by [Bonanza Labs](https://bonanza-labs.com).

x402_firewall-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "x402-firewall"
+version = "0.1.0"
+description = "Spending firewall middleware for x402 payments. Policy engine, approval queue, and audit log for AI agents."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+keywords = [
+    "x402", "payments", "ai", "agents", "firewall", "policy",
+    "spending", "mcp", "blockchain", "base", "usdc",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+yaml = ["pyyaml>=6.0"]
+dev  = ["pytest>=8", "pytest-asyncio>=0.23", "pyyaml>=6.0"]
+
+[project.urls]
+Homepage   = "https://bonanza-labs.com"
+Repository = "https://github.com/c6zks4gssn-droid/x402-firewall"
+Issues     = "https://github.com/c6zks4gssn-droid/x402-firewall/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["x402_firewall*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

x402_firewall-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+