PayPal Agent Shield

## Inspiration
Autonomous AI agents can already browse product catalogs, negotiate deals, and reason about
corporate procurement. Yet **no enterprise CFO will hand an LLM direct access to a         
corporate PayPal account**. Why?                                                           

Because Large Language Models are probabilistic systems operating in a deterministic
financial world:                                                                           
1. **Price & SKU Hallucinations:** An LLM can hallucinate a $\$1.00$ price tag or invent a
non-existent SKU and trigger an invalid settlement.
2. **Prompt Injection & Unauthorized Spend:** A malicious merchant description or    
compromised prompt can instruct an agent to drain corporate funds beyond approved limits.
3. **In-Transit Payload Tampering (MitM):** Without cryptographic non-repudiation between
the human policy maker and the AI agent, checkout payloads can be altered before reaching  
the payment rail. 
4. **Credential Exposure:** Passing raw payment credentials into an LLM context window is a
critical security anti-pattern. 

We built **PayPal Agent Shield** to bridge this gap—creating a **Zero-Trust Cryptographic
Firewall & CFO Control Plane** that allows AI agents to shop autonomously across    
$100\text{M}+$ real products while mathematically guaranteeing they can never hallucinate 
prices, exceed CFO budgets, or leak PayPal credentials.

---

## What it does

**PayPal Agent Shield** sits between autonomous **Google ADK (Gemini)** procurement agents
and the **PayPal Orders v2 Sandbox API**. Instead of trusting an LLM's text output, every 
checkout intent must pass through a **5-Gate Deterministic & Cryptographic Verification 
Pipeline** before a single cent moves on PayPal:

$$\text{Valid Settlement} \iff \text{Verify}_{\text{Ed25519}}(\sigma_{\text{CFO}}) \land
\text{Verify}_{\text{Ed25519}}(\sigma_{\text{Agent}}) \land \left(P_{\text{agent}} =
P_{\text{Channel3}}\right) \land \left(H_{\text{parent}} =
\text{SHA256}(M_{\text{CFO}})\right) \land \left(\text{Amount} \le B_{\text{rem}}\right)$$

1. **🔐 Dual-Identity Ed25519 Cryptographic Governance (AP2 Protocol):**                   
   - **CFO Governance Keypair:** Signs budget allowances directly from an interactive **AG 
   Grid** console (`AP2_POLICY_V1`).
   - **ADK Procurement Agent Keypair:** Signs every checkout intent (`AP2_CHECKOUT_V1`),   
   cryptographically binding the SKU, total amount, merchant PayPal email, and the parent  
   CFO Policy $\text{SHA-256}$ hash.
2. **🧠 Anti-Hallucination Ground-Truth Oracle (Channel3 Integration):**                   
   - When the agent searches the **Channel3 Product Graph ($100\text{M}+$ products)**, the 
   Shield Control Plane intercepts and locks the official SKU, merchant, and real-time     
   price in an immutable `TRUSTED_CATALOG`. If the LLM hallucinates or alters a price      
   during checkout, **Gate 3** blocks the transaction immediately.
3. **📊 Live Editable CFO Policy Plane (AG Grid + AG Studio 3):**                          
   - Finance leaders edit `Max Budget (USD)` inline inside **AG Grid**. Pressing `Enter`   
   triggers an instant **Ed25519 CFO re-signature** and broadcasts the new `AP2 Policy     
   Hash` to all connected clients in real time via Server-Sent Events (SSE).
   - Includes a custom **AG Studio 3 BI Widget** (`ap2-shield-posture`) and a dedicated    
   **Studio Forensic Auditor Agent** (`ap2-shield-auditor`) that joins `audit_ledger`      
   $\bowtie$ `agent_policies` to analyze protection and settlement rates.                  
4. **📋 Human-in-the-Loop (HITL) Quarantine & Drag-to-Settle (Bryntum TaskBoard + ADK 2.0  
Graph):**
   - Maps every node of our **Google ADK 2.0 Graph Workflow**
   (`ap2_zero_trust_checkout_graph`) 1-to-1 onto a 4-column **Bryntum TaskBoard**          
   (`CHANNEL3_DISCOVERY`, `QUARANTINED`, `PAYPAL_SETTLED`, `BLOCKED_THREAT`).
   - When a legitimate purchase exceeds the active budget, it pauses deterministically at  
   `adk_node_cfo_hitl_quarantine`. The CFO can **drag the card to `PAYPAL_SETTLED`** (or   
   click Approve) to auto-expand the budget, re-sign the Ed25519 policy, resume the ADK    
   Graph Workflow, and settle on PayPal Sandbox.
5. **💳 Cryptographically Stamped PayPal Settlement (APIMatic SDK + Render Workflows):**   
   - Approved mandates are orchestrated across isolated **Render Workflows** tasks         
   (`verify_ap2_mandate_task` $\rightarrow$ `settle_paypal_sandbox_task`) and executed     
   against **PayPal Orders v2 Sandbox** using the **APIMatic-generated
   `paypal-server-sdk`**.
   - Every PayPal order is permanently stamped with the cryptographic policy proof         
   (`custom_id="AP2_POLICY:<sha256>"`) and native idempotency
   (`paypal_request_id=mandate_id`).

---

## How we built it

- **Agent Orchestration & Deterministic Graph (`google-adk`):** Built our autonomous       
procurement agent and 6-node deterministic state machine (`ap2_zero_trust_checkout_graph`)
using **Google ADK 2.0** and **Gemini**, separating conversational reasoning from         
deterministic cryptographic verification gates. 
- **PayPal Settlement Engine (`paypal-server-sdk` via APIMatic Context Plugin):** Installed
the official **APIMatic Context Plugin for PayPal** (`npx context-plugins install
https://github.com/paypaldev/server-sdk-context-plugin-preview`) to implement best-practice
SDK patterns: flat `PaypalServersdkClient` initialization,
`ClientCredentialsAuthCredentials` with immutable `config.clone_with(...)` hot-reloading,  
masked header logging, `ApiResponse.body` unwrapping, and typed error handling
(`AuthValidationException`, `ErrorException`, `ApiException`).
- **Cryptographic Core (`cryptography`):** Implemented deterministic canonical JSON        
serialization (`sort_keys=True`), **Ed25519** digital signatures for both CFO and Agent    
identities, and **SHA-256** policy lineage hashing in `ap2_crypto.py`.
- **Real-Time Product Catalog (`channel3-sdk`):** Integrated `AsyncChannel3` across product
search (`products.search` with price filters), SKU enrichment (`products.retrieve`), and   
budget-compliant alternatives (`products.find_similar`).
- **Unified CFO Frontend (`React`, `AG Grid`, `AG Studio 3`, `Bryntum TaskBoard`):** Built 
a real-time executive command center connected via SSE (`EventSource`), featuring inline   
budget editing, cross-filtering BI widgets, and drag-and-drop HITL quarantine resolution.  
- **Distributed Cloud Infrastructure (`Render` + `FastAPI`):** Deployed via a declarative
`render.yaml` Blueprint provisioning both the FastAPI web control plane
(`paypal-agent-shield-web`) and an isolated distributed worker (`paypal-shield-workflow`)
powered by the **Render Workflows SDK** (`@app.task`). 

---

## Challenges we ran into 

1. **Preventing LLM Context Contamination of Secrets & Prices:** If an LLM has access to   
raw payment APIs or is trusted to pass prices directly to checkout, prompt injection can 
easily override system instructions. We solved this by air-gapping `PAYPAL_CLIENT_SECRET`
inside the FastAPI/Render control plane and caching Channel3's ground-truth prices    
server-side the moment `search_catalog_channel3` executes.
2. **Resuming Paused Graph Workflows Across Async UI Events:** When a transaction hits a
budget limit (`BUDGET_EXCEEDED`), pausing the agent's checkout mandate and allowing a human
CFO to drag a card on the **Bryntum TaskBoard** required careful state synchronization. We 
engineered an atomic HITL approval pipeline that expands the allowance by the exact delta:
   $$\Delta B = \text{Amount}_{\text{mandate}} - B_{\text{remaining}}$$
   re-signs the `AP2_POLICY_V1` mandate with the CFO's Ed25519 private key, updates the    
   parent policy hash on the quarantined checkout intent, and triggers the PayPal Sandbox 
   settlement workflow. 
3. **Hot-Reloading Bring-Your-Own-Key (BYOK) Across Distributed Workers:** To let hackathon
judges test live with their own keys without restarting servers, we had to flush Google
ADK's cached Gemini client on key rotation, clone the immutable APIMatic
`PaypalServersdkClient` configuration via `config.clone_with(...)`, and securely forward
runtime credentials to the isolated **Render Workflows** container. 

---

## Accomplishments that we're proud of

- **Zero-Trust Cryptographic Guarantee:** Even if an attacker compromises the LLM prompt or
intercepts the network payload in transit (MitM), they cannot forge an Ed25519 signature or
bypass the 5-Gate Firewall. 
- **1-Click Red-Team & Green-Team Live Simulation Suite:** We built 5 interactive test 
chips directly into the UI (*Explore Catalog*, *Legitimate Purchase*, *Budget Quarantine
HITL*, *MitM Cryptographic Tampering*, and *LLM Price Hallucination*) so anyone can watch
the firewall block attacks and settle legitimate PayPal orders in real time.
- **End-to-End Cryptographic Audit Trail Inside PayPal:** Every settled transaction embeds 
`AP2_POLICY:<sha256>` inside PayPal's `custom_id` field, allowing auditors to verify     
directly in the PayPal Developer Dashboard which exact CFO policy authorized an AI agent's 
spend.
- **Zero-Friction Graceful Degradation + Live BYOK:** The entire platform works            
out-of-the-box with zero configuration and upgrades live to real Gemini, Channel3, Render
Workflows, and PayPal Sandbox APIs at runtime.

---

## What we learned 

- **Probabilistic AI Requires Deterministic Guardrails:** You cannot solve LLM financial 
security with better system prompts alone. Combining **Google ADK 2.0 Graph Workflows**
with **Ed25519 signatures** and **server-side ground-truth oracles** turns autonomous   
commerce from a liability into an auditable enterprise capability.
- **SDK Ergonomics with APIMatic Context Plugins:** Using the APIMatic Context Plugin 
skills accelerated our `paypal-server-sdk` integration significantly—especially around  
immutable client configuration cloning, OAuth 2 client credentials lifecycle, and    
structured error recovery.
- **Visual Governance Matters as Much as Backend Security:** Pairing cryptographic hashes
with tactile UI patterns—like inline **AG Grid** budget editing, **AG Studio 3** forensic 
analytics, and **Bryntum TaskBoard** drag-to-settle quarantine—makes complex cryptographic
workflows intuitive for finance teams. 

---

## What's next for PayPal Agent Shield

- **Hardware Security Module (HSM) & WebAuthn CFO Signing:** Moving the CFO Ed25519 private
key into browser WebAuthn / YubiKey passkeys so every budget increase or HITL quarantine
approval is signed directly by the CFO's biometric hardware token.
- **Multi-Agent Department Hierarchies & PayPal Payouts:** Expanding policy lineages so a 
Master CFO Policy can delegate sub-budgets to specialized department agents (Cloud Ops, 
Vendor Payouts, Marketing) with automated split settlements. 
- **Cryptographic Disputes & Chargeback Evidence Packages:** Automatically generating 
verifiable Ed25519 + Channel3 ground-truth proof bundles attached to PayPal Dispute APIs
whenever a merchant delivery deviates from the signed `AP2_CHECKOUT_V1` mandate.