agentscore-gate 1.0.0__tar.gz

agentscore_gate-1.0.0/.claude/CLAUDE.md

@@ -0,0 +1,46 @@
+# agentscore-gate
+
+Trust-gating middleware for Python web frameworks using AgentScore. Includes adapters for Flask, Django, and Starlette/FastAPI.
+
+## Architecture
+
+Single-package Python library published to PyPI.
+
+| File | Purpose |
+|------|---------|
+| `agentscore_gate/` | Source code |
+| `agentscore_gate/flask.py` | Flask adapter |
+| `agentscore_gate/django.py` | Django adapter |
+| `agentscore_gate/middleware.py` | ASGI/Starlette middleware |
+| `tests/` | pytest tests |
+
+## Tooling
+
+- **uv** — package manager. Use `uv sync`, `uv run`.
+- **ruff** — linting + formatting. `uv run ruff check .` and `uv run ruff format --check .`.
+- **vulture** — dead code detection.
+- **pytest** — tests. `uv run pytest tests/`.
+- **Lefthook** — git hooks. Pre-commit: ruff. Pre-push: vulture.
+
+## Key Commands
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run ruff format .
+uv run pytest tests/
+```
+
+## Workflow
+
+1. Create a branch
+2. Make changes
+3. Lefthook runs ruff on commit, vulture on push
+4. Open a PR — CI runs automatically
+5. Merge (squash)
+
+## Rules
+
+- **No silent refactors**
+- **Never commit .env files or secrets**
+- **Use PRs** — never push directly to main

agentscore_gate-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: Report a bug
+title: ''
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**To reproduce**
+Steps to reproduce the behavior.
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- Package version:
+- Runtime (Node.js/Python version):
+- OS:

agentscore_gate-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature Request
+about: Suggest an improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+**Describe the feature**
+A clear description of what you'd like.
+
+**Use case**
+Why is this needed? What problem does it solve?

agentscore_gate-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## Summary
+
+<!-- What does this PR do? -->
+
+## Test plan
+
+<!-- How was this tested? -->

agentscore_gate-1.0.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    labels: ["dependencies", "python"]
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "America/New_York"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    labels: ["dependencies", "ci"]
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "America/New_York"
+

agentscore_gate-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Vulture
+        run: uv run vulture agentscore_gate/ vulture_whitelist.py
+
+      - name: Tests
+        run: uv run pytest tests/ -v

agentscore_gate-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Set version from tag
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Commit version bump
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "chore: bump version to $VERSION" || true
+          git push origin HEAD:main
+

agentscore_gate-1.0.0/.github/workflows/security.yml

@@ -0,0 +1,50 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  osv-scan:
+    name: Dependency Scan
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install osv-scanner
+        run: |
+          curl -fsSL https://github.com/google/osv-scanner/releases/download/v2.3.2/osv-scanner_linux_amd64 -o osv-scanner
+          chmod +x osv-scanner
+
+      - name: Scan dependencies
+        run: ./osv-scanner --lockfile=uv.lock --format=table || true
+
+  pip-audit:
+    name: Python Audit
+    runs-on: blacksmith-2vcpu-ubuntu-2404
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Audit dependencies
+        run: |
+          uv export --format requirements-txt --no-hashes > requirements.txt
+          pip-audit -r requirements.txt --disable-pip --no-deps || true
+

agentscore_gate-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.swp
+*.swo
+.DS_Store

agentscore_gate-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at engineering@agentscore.sh. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

agentscore_gate-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to AgentScore
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+1. Fork the repo and clone it locally
+2. Install dependencies (see README for tooling)
+3. Create a branch from `main`
+4. Make your changes
+5. Run linting and tests
+6. Open a pull request
+
+## Pull Requests
+
+- All PRs require 1 approval before merging
+- Squash merge to `main` is the standard
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new functionality
+- Make sure CI passes before requesting review
+
+## Reporting Issues
+
+Open an issue on GitHub with:
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, runtime version)
+
+## Code Style
+
+- **TypeScript repos**: ESLint handles formatting and style. Run `bun run lint` before committing.
+- **Python repos**: Ruff handles linting and formatting. Run `uv run ruff check .` and `uv run ruff format .` before committing.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

agentscore_gate-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentScore
+
+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.

agentscore_gate-1.0.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: agentscore-gate
+Version: 1.0.0
+Summary: Trust-gating middleware for Python web frameworks using AgentScore
+Project-URL: Homepage, https://agentscore.sh
+Project-URL: Repository, https://github.com/agentscore/python-gate
+Project-URL: Issues, https://github.com/agentscore/python-gate/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agentic-payments,agentscore,ai-agent,blockchain,django,erc-8004,fastapi,flask,gate,middleware,reputation,starlette,trust,wallet,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Provides-Extra: django
+Requires-Dist: django>=4.0; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0.0; extra == 'flask'
+Provides-Extra: starlette
+Requires-Dist: starlette>=0.27.0; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+# agentscore-gate
+
+[![PyPI version](https://img.shields.io/pypi/v/agentscore-gate.svg)](https://pypi.org/project/agentscore-gate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+ASGI middleware for trust-gating requests using [AgentScore](https://agentscore.sh). Verify AI agent wallet reputation before allowing requests through, built for the [x402](https://github.com/coinbase/x402) payment ecosystem and [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) agent registry. Works with FastAPI, Starlette, and any ASGI framework.
+
+## Install
+
+```bash
+pip install agentscore-gate
+```
+
+## Quick Start
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from agentscore_gate import AgentScoreGate
+
+app = FastAPI()
+app.add_middleware(AgentScoreGate, api_key="ask_...", min_score=50)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello, trusted agent!"}
+```
+
+### Starlette
+
+```python
+from starlette.applications import Starlette
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+from agentscore_gate import AgentScoreGate
+
+async def homepage(request):
+    agentscore_data = request.state.agentscore
+    return PlainTextResponse("Hello, trusted agent!")
+
+app = Starlette(routes=[Route("/", homepage)])
+app.add_middleware(AgentScoreGate, api_key="ask_...", min_score=50)
+```
+
+## Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | *required* | API key from [agentscore.sh](https://agentscore.sh) |
+| `min_score` | `int \| None` | `None` | Minimum score (0–100) |
+| `min_grade` | `str \| None` | `None` | Minimum grade (A–F) |
+| `require_verified_activity` | `bool \| None` | `None` | Require verified payment activity |
+| `fail_open` | `bool` | `False` | Allow requests when API is unreachable |
+| `cache_seconds` | `int` | `300` | Cache TTL for results |
+| `base_url` | `str` | `https://api.agentscore.sh` | API base URL |
+| `extract_address` | `callable` | Reads `x-wallet-address` header | Custom address extractor |
+| `on_denied` | `async callable` | Returns 403 JSON | Custom denial handler |
+
+## How It Works
+
+1. Extracts wallet address from request header (`x-wallet-address`)
+2. Checks in-memory cache for a previous result
+3. Calls AgentScore `/v1/assess` with your policy
+4. Allows or blocks based on the decision
+5. Attaches data to `request.state.agentscore` on allowed requests
+
+## Documentation
+
+- [API Reference](https://docs.agentscore.sh)
+- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004)
+- [x402 Protocol](https://github.com/coinbase/x402)
+
+## License
+
+[MIT](LICENSE)

agentscore_gate-1.0.0/README.md

@@ -0,0 +1,76 @@
+# agentscore-gate
+
+[![PyPI version](https://img.shields.io/pypi/v/agentscore-gate.svg)](https://pypi.org/project/agentscore-gate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+ASGI middleware for trust-gating requests using [AgentScore](https://agentscore.sh). Verify AI agent wallet reputation before allowing requests through, built for the [x402](https://github.com/coinbase/x402) payment ecosystem and [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) agent registry. Works with FastAPI, Starlette, and any ASGI framework.
+
+## Install
+
+```bash
+pip install agentscore-gate
+```
+
+## Quick Start
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from agentscore_gate import AgentScoreGate
+
+app = FastAPI()
+app.add_middleware(AgentScoreGate, api_key="ask_...", min_score=50)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello, trusted agent!"}
+```
+
+### Starlette
+
+```python
+from starlette.applications import Starlette
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+from agentscore_gate import AgentScoreGate
+
+async def homepage(request):
+    agentscore_data = request.state.agentscore
+    return PlainTextResponse("Hello, trusted agent!")
+
+app = Starlette(routes=[Route("/", homepage)])
+app.add_middleware(AgentScoreGate, api_key="ask_...", min_score=50)
+```
+
+## Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | *required* | API key from [agentscore.sh](https://agentscore.sh) |
+| `min_score` | `int \| None` | `None` | Minimum score (0–100) |
+| `min_grade` | `str \| None` | `None` | Minimum grade (A–F) |
+| `require_verified_activity` | `bool \| None` | `None` | Require verified payment activity |
+| `fail_open` | `bool` | `False` | Allow requests when API is unreachable |
+| `cache_seconds` | `int` | `300` | Cache TTL for results |
+| `base_url` | `str` | `https://api.agentscore.sh` | API base URL |
+| `extract_address` | `callable` | Reads `x-wallet-address` header | Custom address extractor |
+| `on_denied` | `async callable` | Returns 403 JSON | Custom denial handler |
+
+## How It Works
+
+1. Extracts wallet address from request header (`x-wallet-address`)
+2. Checks in-memory cache for a previous result
+3. Calls AgentScore `/v1/assess` with your policy
+4. Allows or blocks based on the decision
+5. Attaches data to `request.state.agentscore` on allowed requests
+
+## Documentation
+
+- [API Reference](https://docs.agentscore.sh)
+- [ERC-8004 Standard](https://eips.ethereum.org/EIPS/eip-8004)
+- [x402 Protocol](https://github.com/coinbase/x402)
+
+## License
+
+[MIT](LICENSE)

agentscore_gate-1.0.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Instead, email us at **security@agentscore.sh** with:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and aim to release a fix within 7 days for critical issues.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.x     | ✅        |
+| < 1.0   | ❌        |

agentscore_gate-1.0.0/agentscore_gate/__init__.py

@@ -0,0 +1,22 @@
+"""Trust-gating middleware for Python web frameworks using AgentScore."""
+
+from agentscore_gate.client import GateClient
+from agentscore_gate.types import AssessResult, DenialReason, Grade
+
+# ASGI middleware is the default import.
+# Flask and Django adapters are imported from their submodules:
+#   from agentscore_gate.flask import agentscore_gate
+#   from agentscore_gate.django import AgentScoreMiddleware
+try:
+    from agentscore_gate.middleware import AgentScoreGate
+except ImportError:
+    # starlette not installed
+    AgentScoreGate = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "AgentScoreGate",
+    "AssessResult",
+    "DenialReason",
+    "GateClient",
+    "Grade",
+]

agentscore_gate-1.0.0/agentscore_gate/cache.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class TTLCache(Generic[T]):
+    """Simple in-memory cache with per-entry TTL expiry."""
+
+    def __init__(self, default_ttl_seconds: float, max_size: int = 10000) -> None:
+        self._store: dict[str, tuple[T, float]] = {}
+        self._default_ttl = default_ttl_seconds
+        self._max_size = max_size
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> T | None:
+        """Return the cached value, or ``None`` if missing or expired."""
+        with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            value, expires_at = entry
+            if time.monotonic() > expires_at:
+                del self._store[key]
+                return None
+            return value
+
+    def set(self, key: str, value: T, ttl: float | None = None) -> None:
+        """Store *value* under *key* with an optional custom TTL (seconds)."""
+        with self._lock:
+            if len(self._store) >= self._max_size and key not in self._store:
+                self._sweep_expired()
+                if len(self._store) >= self._max_size:
+                    self._evict_oldest()
+            self._store[key] = (value, time.monotonic() + (ttl if ttl is not None else self._default_ttl))
+
+    def _sweep_expired(self) -> None:
+        """Remove all expired entries. Must be called with ``_lock`` held."""
+        now = time.monotonic()
+        expired = [k for k, (_, exp) in self._store.items() if now > exp]
+        for k in expired:
+            del self._store[k]
+
+    def _evict_oldest(self) -> None:
+        """Evict entries with the earliest expiry until under max_size. Must be called with ``_lock`` held."""
+        entries = sorted(self._store.items(), key=lambda item: item[1][1])
+        while len(self._store) >= self._max_size and entries:
+            del self._store[entries.pop(0)[0]]