fastapi-mpp 0.2.0__tar.gz

fastapi_mpp-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Python cache and bytecode
+__pycache__/
+*.py[cod]
+*.pyo
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS files
+.DS_Store

fastapi_mpp-0.2.0/LICENSE

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

fastapi_mpp-0.2.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: fastapi-mpp
+Version: 0.2.0
+Summary: Add Machine Payments Protocol (MPP) support to FastAPI endpoints in a few lines.
+Project-URL: Homepage, https://github.com/your-org/fastapi-mpp
+Project-URL: Repository, https://github.com/your-org/fastapi-mpp
+Project-URL: Issues, https://github.com/your-org/fastapi-mpp/issues
+Author: fastapi-mpp contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,fastapi,machine-payments-protocol,mpp,payments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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 :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: all
+Requires-Dist: pympp>=0.4.1; extra == 'all'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
+Requires-Dist: stripe>=11.0.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.35.0; extra == 'dev'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dotenv'
+Provides-Extra: stripe
+Requires-Dist: stripe>=11.0.0; extra == 'stripe'
+Provides-Extra: tempo
+Requires-Dist: pympp>=0.4.1; extra == 'tempo'
+Description-Content-Type: text/markdown
+
+# fastapi-mpp
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-mpp.svg)](https://pypi.org/project/fastapi-mpp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-mpp.svg)](https://pypi.org/project/fastapi-mpp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/your-org/fastapi-mpp?style=social)](https://github.com/your-org/fastapi-mpp)
+
+Machine Payments Protocol middleware for FastAPI.
+
+Version `v0.2` hardens receipt validation, replay protection, session binding, and
+HTTP authentication semantics. This project is still beta.
+
+## Installation
+
+```bash
+pip install fastapi-mpp
+```
+
+For production validation, install Tempo support so default cryptographic validation
+is available:
+
+```bash
+pip install "fastapi-mpp[tempo]"
+```
+
+Optional extras:
+
+```bash
+pip install "fastapi-mpp[dotenv]"
+pip install "fastapi-mpp[stripe]"
+pip install "fastapi-mpp[all]"
+```
+
+## Usage
+
+### Server setup
+
+```python
+from fastapi import FastAPI, Request
+from mpp_fastapi.core import MPP
+
+app = FastAPI()
+
+# Production mode (default): requires receipt_validator or fastapi-mpp[tempo].
+mpp = MPP()
+
+@app.get("/premium")
+@mpp.charge(amount="0.05", currency="USD", description="Premium data")
+async def premium(request: Request):
+    return {"data": "paid content"}
+```
+
+### HTTP flow (v0.2 hardened)
+
+1. Client calls endpoint without credential.
+2. Server responds `402 Payment Required` with:
+    - `WWW-Authenticate: Payment challenge="<base64url(JSON)>", realm="MyAPI", expires="..."`
+    - challenge body containing `challenge_id`, `intent`, `amount`, `currency`, `expires_at`, `hints`
+3. Wallet pays and retries with:
+    - `Authorization: Payment credential="<base64url(receipt-json)>"`
+4. Server validates receipt (fail-closed in production), applies replay checks, and returns success with:
+    - `Payment-Receipt: <base64url(receipt-json)>`
+    - optional session headers when session mode is enabled.
+
+Legacy compatibility can be kept with `allow_legacy_headers=True`:
+- `X-MPP-Receipt`
+- `X-MPP-Session-Id`
+
+### Session budgets
+
+```python
+from fastapi import FastAPI, Request
+from mpp_fastapi.core import MPP
+from mpp_fastapi.types import MPPChargeOptions
+
+app = FastAPI()
+mpp = MPP()
+
+session_options = MPPChargeOptions(
+    amount="0.01",
+    currency="USD",
+    description="Session-metered call",
+    session=True,
+    max_amount="0.50",
+    require_idempotency_key=True,
+)
+
+@app.post("/agent/infer")
+@mpp.charge(options=session_options)
+async def infer(request: Request):
+    return {"result": "paid inference"}
+```
+
+Sessions are HMAC-signed opaque tokens bound to:
+- route scope
+- optional payer source
+- currency/provider
+- issued-at and expiry (default 15 minutes)
+- max budget tracked in store
+
+## Local Run
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+uvicorn examples.simple_app:app --reload
+```
+
+Then test:
+
+```bash
+curl -i http://127.0.0.1:8000/free
+curl -i http://127.0.0.1:8000/premium
+```
+
+Expected behavior demo:
+
+```text
+GET /free -> 200 OK
+GET /premium (without Authorization) -> 402 Payment Required
+GET /premium (with Authorization: Payment credential="...") -> 200 OK
+```
+
+## Security
+
+Read [SECURITY.md](SECURITY.md) before production usage.
+
+- Beta warning: use with caution.
+- In-memory replay/session/rate-limit stores are suitable for single-process deployments only.
+- Production mode is fail-closed when receipt validation is not configured.
+- HTTPS is enforced in production mode.
+
+## Headers
+
+Incoming:
+- `Authorization: Payment credential="..."` (preferred)
+- `Payment-Receipt` (supported)
+- `Payment-Session` (session spends)
+- `X-MPP-Receipt` and `X-MPP-Session-Id` in legacy mode
+- `Idempotency-Key` for safer retries
+
+Response on 402:
+- `WWW-Authenticate: Payment challenge="...", realm="...", expires="..."`
+- JSON challenge payload
+
+Response on success:
+- `Payment-Receipt`
+- `Payment-Session` when session authorization is established
+
+## Design Notes
+
+- In-memory stores are intentionally simple for `v0.2`; Redis-backed stores are planned.
+- Header size limit is enforced (`8KB`) for authorization and receipt headers.
+- A basic in-memory challenge rate limiter is enabled (default `10` challenges/IP/minute).
+
+## Roadmap
+
+- Redis-backed replay/session/rate-limit stores
+- Full conformance with evolving HTTP Payment auth draft semantics
+- Advanced rate limiting and abuse controls
+- Payment provider adapters and richer telemetry
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Add tests for behavior changes.
+4. Run:
+
+```bash
+uv pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+5. Open a PR with clear before/after behavior.
+
+## Credits
+
+Inspired by the MPP ecosystem work and early protocol specs from Tempo and Stripe collaborators.
+Please refer to official protocol repos/specs for normative behavior and updates.
+
+## License
+
+MIT

fastapi_mpp-0.2.0/README.md

@@ -0,0 +1,187 @@
+# fastapi-mpp
+
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-mpp.svg)](https://pypi.org/project/fastapi-mpp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-mpp.svg)](https://pypi.org/project/fastapi-mpp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/your-org/fastapi-mpp?style=social)](https://github.com/your-org/fastapi-mpp)
+
+Machine Payments Protocol middleware for FastAPI.
+
+Version `v0.2` hardens receipt validation, replay protection, session binding, and
+HTTP authentication semantics. This project is still beta.
+
+## Installation
+
+```bash
+pip install fastapi-mpp
+```
+
+For production validation, install Tempo support so default cryptographic validation
+is available:
+
+```bash
+pip install "fastapi-mpp[tempo]"
+```
+
+Optional extras:
+
+```bash
+pip install "fastapi-mpp[dotenv]"
+pip install "fastapi-mpp[stripe]"
+pip install "fastapi-mpp[all]"
+```
+
+## Usage
+
+### Server setup
+
+```python
+from fastapi import FastAPI, Request
+from mpp_fastapi.core import MPP
+
+app = FastAPI()
+
+# Production mode (default): requires receipt_validator or fastapi-mpp[tempo].
+mpp = MPP()
+
+@app.get("/premium")
+@mpp.charge(amount="0.05", currency="USD", description="Premium data")
+async def premium(request: Request):
+    return {"data": "paid content"}
+```
+
+### HTTP flow (v0.2 hardened)
+
+1. Client calls endpoint without credential.
+2. Server responds `402 Payment Required` with:
+    - `WWW-Authenticate: Payment challenge="<base64url(JSON)>", realm="MyAPI", expires="..."`
+    - challenge body containing `challenge_id`, `intent`, `amount`, `currency`, `expires_at`, `hints`
+3. Wallet pays and retries with:
+    - `Authorization: Payment credential="<base64url(receipt-json)>"`
+4. Server validates receipt (fail-closed in production), applies replay checks, and returns success with:
+    - `Payment-Receipt: <base64url(receipt-json)>`
+    - optional session headers when session mode is enabled.
+
+Legacy compatibility can be kept with `allow_legacy_headers=True`:
+- `X-MPP-Receipt`
+- `X-MPP-Session-Id`
+
+### Session budgets
+
+```python
+from fastapi import FastAPI, Request
+from mpp_fastapi.core import MPP
+from mpp_fastapi.types import MPPChargeOptions
+
+app = FastAPI()
+mpp = MPP()
+
+session_options = MPPChargeOptions(
+    amount="0.01",
+    currency="USD",
+    description="Session-metered call",
+    session=True,
+    max_amount="0.50",
+    require_idempotency_key=True,
+)
+
+@app.post("/agent/infer")
+@mpp.charge(options=session_options)
+async def infer(request: Request):
+    return {"result": "paid inference"}
+```
+
+Sessions are HMAC-signed opaque tokens bound to:
+- route scope
+- optional payer source
+- currency/provider
+- issued-at and expiry (default 15 minutes)
+- max budget tracked in store
+
+## Local Run
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+uvicorn examples.simple_app:app --reload
+```
+
+Then test:
+
+```bash
+curl -i http://127.0.0.1:8000/free
+curl -i http://127.0.0.1:8000/premium
+```
+
+Expected behavior demo:
+
+```text
+GET /free -> 200 OK
+GET /premium (without Authorization) -> 402 Payment Required
+GET /premium (with Authorization: Payment credential="...") -> 200 OK
+```
+
+## Security
+
+Read [SECURITY.md](SECURITY.md) before production usage.
+
+- Beta warning: use with caution.
+- In-memory replay/session/rate-limit stores are suitable for single-process deployments only.
+- Production mode is fail-closed when receipt validation is not configured.
+- HTTPS is enforced in production mode.
+
+## Headers
+
+Incoming:
+- `Authorization: Payment credential="..."` (preferred)
+- `Payment-Receipt` (supported)
+- `Payment-Session` (session spends)
+- `X-MPP-Receipt` and `X-MPP-Session-Id` in legacy mode
+- `Idempotency-Key` for safer retries
+
+Response on 402:
+- `WWW-Authenticate: Payment challenge="...", realm="...", expires="..."`
+- JSON challenge payload
+
+Response on success:
+- `Payment-Receipt`
+- `Payment-Session` when session authorization is established
+
+## Design Notes
+
+- In-memory stores are intentionally simple for `v0.2`; Redis-backed stores are planned.
+- Header size limit is enforced (`8KB`) for authorization and receipt headers.
+- A basic in-memory challenge rate limiter is enabled (default `10` challenges/IP/minute).
+
+## Roadmap
+
+- Redis-backed replay/session/rate-limit stores
+- Full conformance with evolving HTTP Payment auth draft semantics
+- Advanced rate limiting and abuse controls
+- Payment provider adapters and richer telemetry
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch.
+3. Add tests for behavior changes.
+4. Run:
+
+```bash
+uv pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src
+```
+
+5. Open a PR with clear before/after behavior.
+
+## Credits
+
+Inspired by the MPP ecosystem work and early protocol specs from Tempo and Stripe collaborators.
+Please refer to official protocol repos/specs for normative behavior and updates.
+
+## License
+
+MIT

fastapi_mpp-0.2.0/examples/session_app.py

@@ -0,0 +1,26 @@
+"""Advanced example focusing on MPP sessions."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI, Request
+
+from mpp_fastapi.core import MPP
+from mpp_fastapi.types import MPPChargeOptions
+
+app = FastAPI(title="MPP session demo")
+mpp = MPP(debug_mode=True, weak_debug_validation=True)
+
+session_options = MPPChargeOptions(
+    amount="0.02",
+    currency="USD",
+    description="Tokenized model inference call",
+    session=True,
+    max_amount="1.00",
+    require_idempotency_key=True,
+)
+
+
+@app.post("/session/infer")
+@mpp.charge(options=session_options)
+async def infer(request: Request) -> dict[str, str]:
+    return {"result": "Inference result after MPP authorization"}

fastapi_mpp-0.2.0/examples/simple_app.py

@@ -0,0 +1,51 @@
+"""Simple FastAPI app showing free, fixed and session MPP endpoints."""
+
+from __future__ import annotations
+
+import os
+
+from fastapi import FastAPI, Request
+
+from mpp_fastapi.core import MPP
+from mpp_fastapi.dependencies import WalletConfig
+from mpp_fastapi.types import MPPChargeOptions
+
+wallet_config = WalletConfig(
+    auto_retry_enabled=os.getenv("MPP_AUTO_RETRY", "true").lower() == "true",
+    tempo_wallet_url=os.getenv("TEMPO_WALLET_URL"),
+    tempo_api_key=os.getenv("TEMPO_API_KEY"),
+    stripe_shared_payment_token=os.getenv("STRIPE_SHARED_PAYMENT_TOKEN"),
+)
+
+mpp = MPP(wallet_config=wallet_config, debug_mode=True, weak_debug_validation=True)
+app = FastAPI(title="fastapi-mpp demo")
+
+
+@app.get("/free")
+async def free_endpoint() -> dict[str, str]:
+    return {"message": "This endpoint is free."}
+
+
+@app.get("/premium")
+@mpp.charge(amount="0.05", currency="USD", description="Access to premium data")
+async def premium_endpoint(request: Request) -> dict[str, str]:
+    return {"data": "Premium content unlocked via MPP receipt."}
+
+
+@app.get("/session")
+@mpp.charge(
+    options=MPPChargeOptions(
+        amount="0.01",
+        currency="USD",
+        description="Session-metered endpoint",
+        session=True,
+        max_amount="0.25",
+    )
+)
+async def session_endpoint(request: Request) -> dict[str, str]:
+    return {"data": "Charged from session budget."}
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}

fastapi_mpp-0.2.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-mpp"
+version = "0.2.0"
+description = "Add Machine Payments Protocol (MPP) support to FastAPI endpoints in a few lines."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "fastapi-mpp contributors" }
+]
+keywords = [
+  "fastapi",
+  "mpp",
+  "machine-payments-protocol",
+  "ai-agents",
+  "payments"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Framework :: FastAPI",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "fastapi>=0.115.0",
+  "pydantic>=2.7.0",
+  "httpx>=0.28.0"
+]
+
+[project.optional-dependencies]
+dotenv = [
+  "python-dotenv>=1.0.0"
+]
+tempo = [
+  "pympp>=0.4.1"
+]
+stripe = [
+  "stripe>=11.0.0"
+]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "ruff>=0.8.0",
+  "mypy>=1.10.0",
+  "uvicorn[standard]>=0.35.0"
+]
+all = [
+  "python-dotenv>=1.0.0",
+  "pympp>=0.4.1",
+  "stripe>=11.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/your-org/fastapi-mpp"
+Repository = "https://github.com/your-org/fastapi-mpp"
+Issues = "https://github.com/your-org/fastapi-mpp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mpp_fastapi"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/mpp_fastapi",
+  "examples",
+  "tests",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml"
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_return_any = true

fastapi_mpp-0.2.0/src/mpp_fastapi/__init__.py

@@ -0,0 +1,17 @@
+"""fastapi-mpp public package exports."""
+
+from .core import MPP
+from .exceptions import InvalidReceiptError, MPPError, PaymentRequiredError
+from .types import MPPChargeOptions, MPPReceipt, MPPSession
+
+__all__ = [
+    "MPP",
+    "MPPChargeOptions",
+    "MPPReceipt",
+    "MPPSession",
+    "MPPError",
+    "PaymentRequiredError",
+    "InvalidReceiptError",
+]
+
+__version__ = "0.2.0"