angel-agent-guard 0.2.0__tar.gz

angel_agent_guard-0.2.0/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+*.tgz
+.env

angel_agent_guard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oroboros Design (Daouda Ndiaye)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

angel_agent_guard-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: angel-agent-guard
+Version: 0.2.0
+Summary: Guard an AI agent before it acts: pre-purchase check for any shop, checkout or payment link, paid API, x402 endpoint or token, and a prompt-injection check for untrusted content. Zero dependencies; browser-use, LangChain/LangGraph and CrewAI tools included.
+Project-URL: Homepage, https://github.com/daoudandiaye98-alt/angel-agent-guard/tree/main/python
+Project-URL: Repository, https://github.com/daoudandiaye98-alt/angel-agent-guard
+Project-URL: Documentation, https://angel.oroboros-design.com/docs/prompt-injection-defense/
+Project-URL: Issues, https://github.com/daoudandiaye98-alt/angel-agent-guard/issues
+Author: Oroboros Design
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-security,agentic-commerce,ai-agent,base,browser-use,checkout,crewai,langchain,langgraph,mcp,phishing,prompt-injection,shopping-agent,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: browser-use
+Requires-Dist: browser-use>=1.0; extra == 'browser-use'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# angel-agent-guard (Python)
+
+Two checks an AI agent should run before it acts:
+
+- **`verify_before_pay(url_or_token)`** before **any purchase or paid call**. That covers a shop or product page, a checkout or payment link (Stripe, Shopify, PayPal, SaaS checkout), an unknown paid API, an x402 endpoint, and a token swap or approval. It checks:
+  - TLS and domain age
+  - look-alike domains, and redirects to payment pages on other domains
+  - which payment provider takes the money
+  - card fields and plain-http forms in the page
+  - text in the page aimed at shopping agents
+  - for x402: the payment offer itself
+  - for an ERC-20: the contract's owner powers
+- **`guard_untrusted(text_or_url)`** before the model acts on a web page, email, document, RAG chunk or tool result written by someone else. A local pass runs first (invisible Unicode, tag smuggling, exfiltration images), then a hosted scan in 17 languages for text aimed at the model.
+- **`quick_scan(text)`** is the local pass on its own. It is fully offline.
+
+There are no dependencies (standard library only), and it works on Python 3.9+. It ships ready-made tools for **browser-use**, **LangChain / LangGraph** and **CrewAI**. The same API exists for TypeScript as the [npm package](https://www.npmjs.com/package/angel-agent-guard).
+
+```bash
+pip install angel-agent-guard
+```
+
+## Quick start
+
+```python
+from angel_agent_guard import verify_before_pay, guard_untrusted, fence
+
+# Before any purchase, payment link or paid call
+v = verify_before_pay("https://shop.example.com/checkout", payer_address="0xYourAgentWallet")
+if not v.ok:
+    print(v.verdict, v.risk_score, v.reasons[:3])   # "caution" -> ask the user; "do_not_pay" -> never pay
+# v.kind: checkout | shop | api | x402 | web
+# v.merchant: TLS, domain age, look-alike, redirect chain, payment providers, card fields, insecure forms
+# v.injection: the page scanned for instructions aimed at agents
+
+verify_before_pay("0xTokenYouAreAboutToApprove")                        # ERC-20 on Base (chain="ethereum" also works)
+verify_before_pay("https://api.example.com/v1/quote", method="POST")    # x402 API that only takes POST
+
+# Untrusted content: check it, then hand the model the cleaned text as data
+page = "...text of a web page..."
+g = guard_untrusted(page)
+if g.action == "drop":
+    raise RuntimeError(f"hostile content: {[f.get('kind') for f in g.findings]}")
+context = fence("https://example.com/article", g.cleaned or page)   # random boundary + "this is data"
+# g.action == "read_only" -> continue, but without send, write or payment tools in this step
+```
+
+`averify_before_pay` and `aguard_untrusted` are the async variants. Every result has `.to_dict()`, plus `.summary()`, a short JSON string to use as an LLM tool result. Neither function raises on network or payment problems. They fall back to the local result and put the reason in `error` / `errors`.
+
+## browser-use
+
+```python
+from browser_use import Agent, Tools
+from angel_agent_guard.integrations.browser_use import register
+
+tools = register(Tools(), payer_address="0xYourAgentWallet")   # adds verify_before_pay(url) and guard_page_text(text)
+agent = Agent(
+    "Buy a USB-C cable under 10 EUR on https://shop.example.com. "
+    "Call verify_before_pay on the checkout page and stop before paying unless the verdict is pay.",
+    tools=tools,
+)
+agent.run_sync()
+```
+
+## LangChain / LangGraph
+
+```python
+from langgraph.prebuilt import create_react_agent
+from angel_agent_guard.integrations.langchain import angel_langchain_tools
+
+tools = angel_langchain_tools(payer_address="0xYourAgentWallet")   # [verify_before_pay, guard_untrusted]
+agent = create_react_agent(model, tools)
+```
+
+Install with `pip install "angel-agent-guard[langchain]"`.
+
+## CrewAI
+
+```python
+from crewai import Agent
+from angel_agent_guard.integrations.crewai import VerifyBeforePayTool, GuardUntrustedTool
+
+buyer = Agent(
+    role="Purchasing agent",
+    goal="Buy what the user asked for, safely",
+    backstory="Checks every checkout before paying.",
+    tools=[VerifyBeforePayTool(payer_address="0xYourAgentWallet"), GuardUntrustedTool()],
+)
+```
+
+Install with `pip install "angel-agent-guard[crewai]"`.
+
+## CLI
+
+```bash
+angel-agent-guard-py verify https://shop.example.com/checkout
+angel-agent-guard-py verify --token 0x... --chain base
+angel-agent-guard-py scan "text to check"          # or a https URL, or - for stdin
+angel-agent-guard-py quick "text"                  # offline
+```
+
+Exit codes: `0` clean / pay, `1` caution / unchecked, `2` hostile / do_not_pay, `3` usage or error.
+
+## Pricing and paying
+
+The local checks are free. The hosted checks run on [Angel](https://angel.oroboros-design.com/docs/prompt-injection-defense/). Each agent gets 3 free calls, then pays per call in USDC on Base via x402:
+
+| Check | Price per call |
+|---|---|
+| pre-purchase check | 0.25 USDC |
+| input guard | 0.99 USDC |
+| token risk | 0.99 USDC |
+
+Pass `payer_address` (or set `ANGEL_PAYER_ADDRESS`) so that your wallet gets its own 3 free calls. Without it, the free calls are shared by IP. Once the free calls are used up, the result carries `payment`, which holds the x402 offer, the price and a card checkout link a human can open.
+
+To pay automatically, pass a paying HTTP client as `client=`. This can be any object with `.request()`, for example a paying client from the [x402 Python SDK](https://pypi.org/project/x402/) built on httpx or requests. The library checks an x402 offer locally (`check_offer`: official USDC, network, amount cap, same host) but never signs anything itself.
+
+## Limits and data
+
+- The local pass removes invisible characters and flags the riskiest markers. It does not judge meaning. If it finds nothing, it reports `unchecked`, never `clean`.
+- The hosted checks are deterministic: patterns, TLS, DNS, RDAP and on-chain reads, with no model. That makes them fast and repeatable, but a new attack, or a well-made fraud shop on an old domain, can pass. Keep the other layers:
+  - read external content as data
+  - give the step that reads content no dangerous tools
+  - require an approval the model cannot give itself before money moves
+- For a hosted check, the text or URL is sent to `angel.oroboros-design.com`. Use `remote=False` for content that must not leave your machine.
+
+Disclosure: the hosted checks are a paid service run by the author (Oroboros Design). The library is MIT-licensed.

angel_agent_guard-0.2.0/README.md

@@ -0,0 +1,126 @@
+# angel-agent-guard (Python)
+
+Two checks an AI agent should run before it acts:
+
+- **`verify_before_pay(url_or_token)`** before **any purchase or paid call**. That covers a shop or product page, a checkout or payment link (Stripe, Shopify, PayPal, SaaS checkout), an unknown paid API, an x402 endpoint, and a token swap or approval. It checks:
+  - TLS and domain age
+  - look-alike domains, and redirects to payment pages on other domains
+  - which payment provider takes the money
+  - card fields and plain-http forms in the page
+  - text in the page aimed at shopping agents
+  - for x402: the payment offer itself
+  - for an ERC-20: the contract's owner powers
+- **`guard_untrusted(text_or_url)`** before the model acts on a web page, email, document, RAG chunk or tool result written by someone else. A local pass runs first (invisible Unicode, tag smuggling, exfiltration images), then a hosted scan in 17 languages for text aimed at the model.
+- **`quick_scan(text)`** is the local pass on its own. It is fully offline.
+
+There are no dependencies (standard library only), and it works on Python 3.9+. It ships ready-made tools for **browser-use**, **LangChain / LangGraph** and **CrewAI**. The same API exists for TypeScript as the [npm package](https://www.npmjs.com/package/angel-agent-guard).
+
+```bash
+pip install angel-agent-guard
+```
+
+## Quick start
+
+```python
+from angel_agent_guard import verify_before_pay, guard_untrusted, fence
+
+# Before any purchase, payment link or paid call
+v = verify_before_pay("https://shop.example.com/checkout", payer_address="0xYourAgentWallet")
+if not v.ok:
+    print(v.verdict, v.risk_score, v.reasons[:3])   # "caution" -> ask the user; "do_not_pay" -> never pay
+# v.kind: checkout | shop | api | x402 | web
+# v.merchant: TLS, domain age, look-alike, redirect chain, payment providers, card fields, insecure forms
+# v.injection: the page scanned for instructions aimed at agents
+
+verify_before_pay("0xTokenYouAreAboutToApprove")                        # ERC-20 on Base (chain="ethereum" also works)
+verify_before_pay("https://api.example.com/v1/quote", method="POST")    # x402 API that only takes POST
+
+# Untrusted content: check it, then hand the model the cleaned text as data
+page = "...text of a web page..."
+g = guard_untrusted(page)
+if g.action == "drop":
+    raise RuntimeError(f"hostile content: {[f.get('kind') for f in g.findings]}")
+context = fence("https://example.com/article", g.cleaned or page)   # random boundary + "this is data"
+# g.action == "read_only" -> continue, but without send, write or payment tools in this step
+```
+
+`averify_before_pay` and `aguard_untrusted` are the async variants. Every result has `.to_dict()`, plus `.summary()`, a short JSON string to use as an LLM tool result. Neither function raises on network or payment problems. They fall back to the local result and put the reason in `error` / `errors`.
+
+## browser-use
+
+```python
+from browser_use import Agent, Tools
+from angel_agent_guard.integrations.browser_use import register
+
+tools = register(Tools(), payer_address="0xYourAgentWallet")   # adds verify_before_pay(url) and guard_page_text(text)
+agent = Agent(
+    "Buy a USB-C cable under 10 EUR on https://shop.example.com. "
+    "Call verify_before_pay on the checkout page and stop before paying unless the verdict is pay.",
+    tools=tools,
+)
+agent.run_sync()
+```
+
+## LangChain / LangGraph
+
+```python
+from langgraph.prebuilt import create_react_agent
+from angel_agent_guard.integrations.langchain import angel_langchain_tools
+
+tools = angel_langchain_tools(payer_address="0xYourAgentWallet")   # [verify_before_pay, guard_untrusted]
+agent = create_react_agent(model, tools)
+```
+
+Install with `pip install "angel-agent-guard[langchain]"`.
+
+## CrewAI
+
+```python
+from crewai import Agent
+from angel_agent_guard.integrations.crewai import VerifyBeforePayTool, GuardUntrustedTool
+
+buyer = Agent(
+    role="Purchasing agent",
+    goal="Buy what the user asked for, safely",
+    backstory="Checks every checkout before paying.",
+    tools=[VerifyBeforePayTool(payer_address="0xYourAgentWallet"), GuardUntrustedTool()],
+)
+```
+
+Install with `pip install "angel-agent-guard[crewai]"`.
+
+## CLI
+
+```bash
+angel-agent-guard-py verify https://shop.example.com/checkout
+angel-agent-guard-py verify --token 0x... --chain base
+angel-agent-guard-py scan "text to check"          # or a https URL, or - for stdin
+angel-agent-guard-py quick "text"                  # offline
+```
+
+Exit codes: `0` clean / pay, `1` caution / unchecked, `2` hostile / do_not_pay, `3` usage or error.
+
+## Pricing and paying
+
+The local checks are free. The hosted checks run on [Angel](https://angel.oroboros-design.com/docs/prompt-injection-defense/). Each agent gets 3 free calls, then pays per call in USDC on Base via x402:
+
+| Check | Price per call |
+|---|---|
+| pre-purchase check | 0.25 USDC |
+| input guard | 0.99 USDC |
+| token risk | 0.99 USDC |
+
+Pass `payer_address` (or set `ANGEL_PAYER_ADDRESS`) so that your wallet gets its own 3 free calls. Without it, the free calls are shared by IP. Once the free calls are used up, the result carries `payment`, which holds the x402 offer, the price and a card checkout link a human can open.
+
+To pay automatically, pass a paying HTTP client as `client=`. This can be any object with `.request()`, for example a paying client from the [x402 Python SDK](https://pypi.org/project/x402/) built on httpx or requests. The library checks an x402 offer locally (`check_offer`: official USDC, network, amount cap, same host) but never signs anything itself.
+
+## Limits and data
+
+- The local pass removes invisible characters and flags the riskiest markers. It does not judge meaning. If it finds nothing, it reports `unchecked`, never `clean`.
+- The hosted checks are deterministic: patterns, TLS, DNS, RDAP and on-chain reads, with no model. That makes them fast and repeatable, but a new attack, or a well-made fraud shop on an old domain, can pass. Keep the other layers:
+  - read external content as data
+  - give the step that reads content no dangerous tools
+  - require an approval the model cannot give itself before money moves
+- For a hosted check, the text or URL is sent to `angel.oroboros-design.com`. Use `remote=False` for content that must not leave your machine.
+
+Disclosure: the hosted checks are a paid service run by the author (Oroboros Design). The library is MIT-licensed.

angel_agent_guard-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "angel-agent-guard"
+version = "0.2.0"
+description = "Guard an AI agent before it acts: pre-purchase check for any shop, checkout or payment link, paid API, x402 endpoint or token, and a prompt-injection check for untrusted content. Zero dependencies; browser-use, LangChain/LangGraph and CrewAI tools included."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Oroboros Design" }]
+keywords = ["ai-agent", "agent-security", "prompt-injection", "shopping-agent", "agentic-commerce", "checkout", "phishing", "x402", "usdc", "base", "browser-use", "langchain", "langgraph", "crewai", "mcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+browser-use = ["browser-use>=1.0"]
+langchain = ["langchain-core>=0.3"]
+crewai = ["crewai>=0.80"]
+
+[project.urls]
+Homepage = "https://github.com/daoudandiaye98-alt/angel-agent-guard/tree/main/python"
+Repository = "https://github.com/daoudandiaye98-alt/angel-agent-guard"
+Documentation = "https://angel.oroboros-design.com/docs/prompt-injection-defense/"
+Issues = "https://github.com/daoudandiaye98-alt/angel-agent-guard/issues"
+
+[project.scripts]
+angel-agent-guard-py = "angel_agent_guard.__main__:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/angel_agent_guard"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/angel_agent_guard", "tests", "README.md", "LICENSE", "pyproject.toml"]

angel_agent_guard-0.2.0/src/angel_agent_guard/__init__.py

@@ -0,0 +1,30 @@
+"""angel-agent-guard: two checks an AI agent should run before it acts.
+
+- guard_untrusted(text_or_url): prompt-injection check for content written by someone else
+- verify_before_pay(url_or_token): pre-purchase check for any shop, checkout or payment link, paid API, x402 endpoint or token
+- quick_scan(text): offline pass (invisible Unicode, tag smuggling, exfiltration images), zero dependencies
+
+Integrations: angel_agent_guard.integrations.browser_use, .langchain, .crewai
+"""
+
+from ._guard import (
+    ANGEL_BASE,
+    PATHS,
+    VERSION,
+    GuardResult,
+    PaymentNeeded,
+    VerifyResult,
+    aguard_untrusted,
+    averify_before_pay,
+    guard_untrusted,
+    verify_before_pay,
+)
+from ._local import USDC, LocalFinding, OfferCheck, QuickScanResult, check_offer, decode_offer, fence, local_verdict, looks_like_url, quick_scan
+
+__version__ = VERSION
+__all__ = [
+    "VERSION", "ANGEL_BASE", "PATHS", "USDC",
+    "guard_untrusted", "verify_before_pay", "aguard_untrusted", "averify_before_pay",
+    "quick_scan", "local_verdict", "fence", "looks_like_url", "check_offer", "decode_offer",
+    "GuardResult", "VerifyResult", "PaymentNeeded", "QuickScanResult", "LocalFinding", "OfferCheck",
+]

angel_agent_guard-0.2.0/src/angel_agent_guard/__main__.py

@@ -0,0 +1,63 @@
+"""CLI: python -m angel_agent_guard (or angel-agent-guard-py) scan|verify|quick ...
+
+Exit codes: 0 clean/pay, 1 caution/unchecked, 2 hostile/do_not_pay, 3 usage or error.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import List
+
+from . import guard_untrusted, quick_scan, verify_before_pay
+from ._local import local_verdict
+
+USAGE = """usage:
+  angel-agent-guard-py scan "<text>" | <https-url> | -      prompt-injection check (local + hosted)
+  angel-agent-guard-py verify <https-url> [--post]          pre-purchase check (shop, checkout, payment link, API, x402)
+  angel-agent-guard-py verify --token 0x... [--chain base|ethereum]
+  angel-agent-guard-py quick "<text>" | -                    offline only"""
+
+
+def main(argv: List[str]) -> int:
+    if not argv or argv[0] in ("-h", "--help"):
+        print(USAGE)
+        return 3
+    cmd, rest = argv[0], argv[1:]
+    flag = lambda name: rest[rest.index(name) + 1] if name in rest and rest.index(name) + 1 < len(rest) else None  # noqa: E731
+    positional = [a for i, a in enumerate(rest) if not a.startswith("--") and (i == 0 or rest[i - 1] not in ("--token", "--chain"))]
+    if cmd in ("scan", "quick"):
+        text = sys.stdin.read() if positional[:1] == ["-"] else " ".join(positional)
+        if not text:
+            print(USAGE, file=sys.stderr)
+            return 3
+        if cmd == "quick":
+            q = quick_scan(text)
+            print(json.dumps(q.to_dict(), ensure_ascii=False, indent=2))
+            v = local_verdict(q)
+            return 2 if v == "hostile" else 1 if v == "caution" else 0
+        g = guard_untrusted(text)
+        print(json.dumps(g.to_dict(), ensure_ascii=False, indent=2))
+        return 0 if g.verdict == "clean" else 2 if g.verdict == "hostile" else 1
+    if cmd == "verify":
+        url, token = (positional[0] if positional else None), flag("--token")
+        if not url and not token:
+            print(USAGE, file=sys.stderr)
+            return 3
+        r = verify_before_pay(url=url, token=token, chain=flag("--chain") or "base", method="POST" if "--post" in rest else "GET")
+        print(json.dumps(r.to_dict(), ensure_ascii=False, indent=2, default=str))
+        return 0 if r.verdict == "pay" else 2 if r.verdict == "do_not_pay" else 1
+    print(USAGE, file=sys.stderr)
+    return 3
+
+
+def run() -> None:
+    try:
+        sys.exit(main(sys.argv[1:]))
+    except Exception as e:  # pragma: no cover
+        print(str(e), file=sys.stderr)
+        sys.exit(3)
+
+
+if __name__ == "__main__":
+    run()