<div align="center">

# MandatePay

### The authorization firewall for agentic payments

**Identity · Intent · Policy · Human approval · Cryptographic proof**

[![CI](https://img.shields.io/github/actions/workflow/status/muhammadashir0/mandatepay/ci.yml?branch=main&style=for-the-badge&label=TESTS)](https://github.com/muhammadashir0/mandatepay/actions)
![Python](https://img.shields.io/badge/Python-3.11+-101722?style=for-the-badge&logo=python)
![MCP](https://img.shields.io/badge/MCP-tool_server-C8FF4D?style=for-the-badge)
![License](https://img.shields.io/badge/license-Apache--2.0-101722?style=for-the-badge)

</div>

> Autonomous agents can propose payments. They should not receive unlimited financial authority. MandatePay verifies every machine-initiated payment against a signed human mandate before execution.

## Why this exists

Agentic commerce introduces a new control problem: **how can a payment provider prove that an AI agent acted within authority delegated by a human or organization?** Traditional checkout assumes a person is present. API keys establish application access, but not purpose, limits, geography, merchant scope, or the exact boundary of delegated intent.

MandatePay is a research-grade control plane that sits between agents and payment rails. It does **not** hold or move funds.

## What makes it different

- **Signed mandates:** authority is machine-verifiable and tamper-evident.
- **Policy-as-code:** deterministic limits for value, total spend, currency, country, merchant, purpose, expiry, and velocity.
- **Human challenge:** higher-risk intents pause for approval bound to the exact payment.
- **Agent identity binding:** a mandate cannot be reused by a different agent.
- **Replay safety:** idempotency keys return the original decision.
- **Verifiable events:** every decision enters a hash-chained journal.
- **MCP tool:** agents can request authorization through a constrained tool interface.
- **Fail closed:** invalid signatures, malformed money, expired authority, and scope escape are denied.

## Authorization lifecycle

```mermaid
sequenceDiagram
    participant H as Human / Organization
    participant A as AI Agent
    participant M as MandatePay
    participant P as Payment Provider
    H->>M: Sign bounded mandate
    A->>M: Submit payment intent
    M->>M: Verify identity + signature + policy + state
    alt within authority
        M-->>A: Single-use authorization
        A->>P: Execute with authorization proof
    else approval threshold
        M-->>H: Challenge exact intent
    else policy violation
        M-->>A: Deny with reason codes
    end
    M->>M: Append decision to audit chain
```

## Quick start

```bash
git clone https://github.com/muhammadashir0/mandatepay.git
cd mandatepay
python -m unittest discover -s tests -v
python app.py
```

Open `http://localhost:8080`.

Try four scenarios in the console:

1. `€299 / software / DE` → authorize
2. `€400 / software / DE` → human challenge
3. `€900 / software / DE` → deny: payment limit
4. `€100 / travel / GB` → deny: purpose and country

Use a fresh idempotency key when changing a scenario.

## MCP server

```bash
python -m mandatepay.mcp_server
```

The zero-dependency JSON-RPC server exposes one deliberately narrow tool: `request_payment_authorization`. The tool returns a decision, not money movement.

## Threat model

MandatePay is designed around:

- stolen or over-privileged agent credentials;
- prompt injection causing unintended purchases;
- mandate tampering and scope escalation;
- duplicate execution and replay;
- velocity abuse and cumulative overspend;
- ambiguous human approval;
- incomplete forensic evidence.

See [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) for trust boundaries, non-goals, and production controls.

## Repository architecture

```text
mandatepay/
├── mandatepay/
│   ├── core.py          # signed mandate + deterministic policy engine
│   ├── store.py         # state, idempotency, tamper-evident journal
│   └── mcp_server.py    # constrained MCP-compatible tool server
├── web/index.html       # premium operator console
├── tests/               # policy and adversarial scenarios
├── docs/                # protocol, threat model, product direction
└── app.py               # sandbox HTTP API
```

## Evaluation, not just a demo

The tests verify authorization, approval challenges, identity mismatch, scope escape, velocity limits, and signed-mandate tampering. The next benchmark layer will measure false authorizations, false denials, replay resistance, policy coverage, decision latency, and approval burden across adversarial scenarios.

## Roadmap

- [ ] Ed25519/JWS production signing and key rotation
- [ ] OAuth-attested agent identity and workload identity
- [ ] Approval ceremony bound to intent hash
- [ ] Single-use authorization tokens for payment providers
- [ ] Durable SQL ledger with concurrency guarantees
- [ ] OpenTelemetry decision traces and signed audit export
- [ ] Adversarial evaluation corpus for agent-payment attacks
- [ ] Stripe/Adyen sandbox adapter behind an execution interface
- [ ] Multi-currency decimal and FX policy

## Responsible-use boundary

This repository is a security and FinTech research MVP using synthetic identities and no real funds. HMAC is used only to keep the demonstration dependency-free. Production deployment requires reviewed asymmetric cryptography, hardened identity, durable transactional storage, authentication and authorization, regulatory analysis, privacy controls, independent security testing, and payment-provider certification.

## Strategic context

Agentic payment systems need mandate-based authorization, separation between decision and execution, agent identity, programmable controls, audit trails, and tiered human oversight. MandatePay turns those design requirements into an inspectable open-source prototype.

## License

Apache License 2.0.