AegisMandate

Deterministic containment plane isolating AI shopping agents from PayPal rails. Prevents wallet drains, prompt injections, and rogue spends via two-gate policy & audit ledgers.

Comment

🤖 How AI Runs in AegisMandate (Live Runtime Architecture)

AegisMandate runs a live, multi-turn Google Gemini autonomous shopping agent at runtime (apps/agent/src/llm.ts, exposed via POST /v1/agent/run and the interactive Live Gemini Shopper Agent console on our live deployment at https://aegismandate-production.up.railway.app):

  1. Live LLM Tool-Calling Loop (gemini-3.8-flash with automatic live failover to gemini-3.5-flash-lite):
    • When a user submits a natural-language shopping goal (or when the agent inspects merchant storefronts), the backend invokes the Google Gemini REST API live with multi-turn function calling (search_catalog, get_item_details, propose_purchase) and preserves cryptographic thoughtSignature tokens across turns.
    • The UI and API transparently display [AGENT_MODE: LIVE_LLM] along with the complete tool-call transcript and reasoning output. (When GEMINI_API_KEY is omitted in offline CI environments, it explicitly labels [AGENT_MODE: OFFLINE_FALLBACK]).
  2. Why a Deterministic Control Plane Sits Between Gemini and PayPal:
    • Because the shopping agent relies on a real LLM to interpret storefront content, it is inherently susceptible to indirect prompt injection (e.g., a malicious store page instructing the LLM to propose an unauthorized $500 transfer).
    • AegisMandate enforces strict Privilege Separation: the Gemini agent has zero PayPal SDK access and zero payment credentials (INV-1). Every LLM-generated propose_purchase call is intercepted by our 13-rule deterministic policy gateway (packages/policy, INV-5) and sealed inside a tamper-evident SHA-256 hash-chained SQLite audit ledger before touching PayPal Sandbox Orders v2.

Inspiration

Autonomous AI agents are rapidly moving from answering questions to executing real-world commerce. However, giving an LLM direct access to payment credentials creates an unacceptable blast radius: a single indirect prompt injection hidden in a product review or an LLM hallucination can trigger unauthorized transfers. We built AegisMandate to answer a fundamental question: How can we let a live AI agent shop autonomously using PayPal while guaranteeing mathematically that it can never violate human-defined financial boundaries?

What it does

AegisMandate is a zero-trust, deterministic policy control plane and human-in-the-loop mandate gateway that sits between an autonomous Google Gemini Shopper Agent and the PayPal Sandbox Orders v2 API:

  • Autonomous Gemini Shopping Agent: Parses user goals, searches registered merchant catalogs, inspects item details, and formulates structured PurchaseIntent proposals in real time.
  • Deterministic 13-Rule Policy Engine (ALLOW / STEP_UP / DENY): Evaluates every agent proposal against signed user mandates—enforcing per-transaction caps, daily budgets, merchant allowlists, currency locks, and provenance trust rules with zero LLM involvement in enforcement.
  • Two-Gate Human Approval & PayPal Sandbox Execution:
    • Low-value routine purchases within auto-approve limits (e.g., $9.00 Gel Pen Pack) receive ALLOW and initiate a real PayPal Sandbox order.
    • Mid-value purchases exceeding the autonomous threshold (e.g., $45.00 LED Desk Lamp) trigger STEP_UP, requiring cryptographic payload-hash confirmation from the human owner before PayPal checkout proceeds.
    • Out-of-bounds requests ($320.00 Standing Desk) or prompt-injected transfers ($500.00 to an attacker) are blocked immediately with DENY (0 PayPal API calls made).
  • Tamper-Evident SHA-256 Audit Ledger: Every intent, policy verdict, approval, and PayPal state transition is recorded in an append-only, hash-chained SQLite ledger verifiable with a single click.

How we built it

  • AI Agent Runtime (apps/agent): Built in TypeScript using native Node.js 22 fetch() against the Google Gemini REST API (gemini-3.8-flash with live failover to gemini-3.5-flash-lite), supporting multi-turn function calling and cryptographic thoughtSignature persistence.
  • Deterministic Policy & Security Core (packages/policy & packages/domain): Pure, side-effect-free TypeScript engine implementing 13 deterministic rules and 14 architectural security invariants (INV-1 through INV-14), enforced at compile/lint time via ESLint module boundary rules.
  • Control Plane API & Audit Ledger (apps/api): Built with Fastify, Node.js 22, and SQLite (WAL mode) featuring SHA-256 hash chaining, idempotency keys, and an atomic outbox worker.
  • PayPal Sandbox Integration (packages/paypal): Direct integration with PayPal Sandbox Orders v2 API for order creation, buyer approval redirects (sandbox.paypal.com/checkoutnow), and capture verification.
  • Interactive Simulation & Mandate Console (apps/web): Built with React and Vite, allowing evaluators to run live Gemini prompts, toggle defensive vs. hijack simulations, approve STEP_UP mandates, and verify ledger integrity.

Challenges we ran into

  1. Multi-Turn Function Calling Signatures with Gemini: Ensuring seamless multi-turn tool execution (search_catalog $\rightarrow$ get_item_details $\rightarrow$ propose_purchase) required capturing and re-attaching cryptographic thoughtSignature tokens on every assistant function call turn while handling free-tier rate limits gracefully via live model failover.
  2. Preventing TOCTOU (Time-of-Check to Time-of-Use) Payload Tampering: Between a human approving a STEP_UP mandate and the backend calling PayPal Sandbox, parameters could theoretically drift. We solved this by binding every human approval to the exact SHA-256 canonical hash of the PurchaseIntent payload.
  3. Strict Privilege Separation (INV-1): Keeping the cognitive agent package completely isolated from PayPal SDKs and credentials required designing a clean tool-mediated boundary where the agent can only propose intents, never execute payments directly.

Accomplishments that we're proud of

  • Zero-Trust Containment Proven Live: Successfully demonstrated a live Google Gemini agent performing autonomous multi-turn shopping while proving mathematically that compromised or out-of-policy intents are blocked before touching PayPal Sandbox.
  • 244/244 Passing Automated Tests: Built a comprehensive verification suite covering unit tests, property-based fuzzing, concurrency race tests, tamper-detection tests, and ESLint architectural boundary checks.
  • End-to-End PayPal Sandbox Flow: Delivered a live deployed web application (https://aegismandate-production.up.railway.app) where judges can test both the live Gemini agent and real PayPal Sandbox checkout in seconds.

What we learned

LLMs are extraordinary at reasoning over ambiguous user goals and unstructured product catalogs, but they should never act as their own security guardrails. Pairing probabilistic LLM reasoning with a deterministic, fail-closed policy control plane and cryptographic audit trail unlocks safe autonomous commerce without sacrificing user convenience.

What's next for AegisMandate

  • Cryptographic Merchant Attestations: Verifying signed merchant catalogs and invoices so item prices cannot be spoofed at the storefront layer.
  • Multi-User Organization Mandates: Supporting role-based spending policies, team budget pools, and automated webhook reconciliation with PayPal Dispute & Payout APIs.
  • Open-Source Policy SDK: Packaging the 13-rule deterministic engine and hash-chained ledger as a drop-in middleware for any MCP (Model Context Protocol) commerce agent.

Built With

Share this project:

Updates

Submission history