Files · Mistral AI Security Guardrails for Square Payment Dispute Resolution

# Mistral AI Security Guardrails for Square Payment Dispute Resolution
 
> AI agent drafts responses to Square payment disputes while guardrails prevent unauthorized actions and redact PII, using Mistral and REAA’s guardrail chain.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Running locally
 
```bash
pnpm install
pnpm test            # vitest run with coverage
pnpm dev             # next dev
```
 
## Project layout
 
```
app/                  Next.js App Router pages + API routes
src/                  services, lib, adapters
tests/                vitest suite (mirrors src/)
packages/             API references for every dependency (read these first)
DEV_PLAN.md           build plan for this recipe
```
 
## License
 
MIT — see [LICENSE](./LICENSE).
 
## What it does
 
The agent fetches Square payment disputes, analyzes evidence, and drafts professional responses using Mistral AI. Multiple guardrail layers enforce PII redaction, prompt injection detection, and output sanitization. Drafted responses require human approval via Slack before they can be submitted back to Square. A budget engine caps monthly spend and telemetry tracks every LLM call.
 
## Architecture
 
The pipeline: Square Webhook → DisputeHandler → Guardrails (hai-guardrails + REAA chain) → Mistral draft → Budget check → PIIScan/Toxicity → ApprovalWorkflow (Slack) → Square submitEvidence
 
## Packages used
 
| Package | Version | Purpose |
|---|---|---|
| @reaatech/guardrail-chain | 0.1.0 | Core guardrail chain framework |
| @reaatech/guardrail-chain-guardrails | 0.1.0 | Built-in PII, injection, toxicity guardrails |
| @reaatech/tool-use-firewall-approvals | 0.1.0 | Human-in-the-loop approval workflow (Slack) |
| @reaatech/llm-cost-telemetry | 0.1.0 | Cost span types, utilities, config loaders |
| @reaatech/agent-budget-engine | 0.1.0 | Budget enforcement with per-scope state machine |
| @mistralai/mistralai | 2.2.5 | Mistral AI SDK |
| square | 44.1.0 | Square SDK |
| @presidio-dev/hai-guardrails | 1.12.0 | Injection, PII, secret detection guards |
| langfuse | 3.38.20 | LLM observability |
| zod | 4.4.3 | Runtime schema validation |
 
## Environment Variables
 
| Variable | Description |
|---|---|
| MISTRAL_API_KEY | Mistral AI API key |
| SQUARE_ACCESS_TOKEN | Square OAuth access token |
| SQUARE_LOCATION_ID | Square location ID |
| SQUARE_WEBHOOK_SIGNATURE_KEY | Square webhook signature verification key |
| SLACK_WEBHOOK_URL | Slack incoming webhook for approval notifications |
| APPROVAL_API_KEY | Bearer token for the approvals API |
| MONTHLY_BUDGET_USD | Monthly budget cap for LLM spend |
| LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST | Langfuse observability credentials |
 
## API Endpoints
 
- POST /api/webhook/square — Square dispute event webhook (verified via HMAC-SHA256)
- GET /api/disputes — List all disputes from Square
- POST /api/disputes — Trigger AI draft for a dispute by { disputeId }
- GET /api/disputes/[id] — Get single dispute detail
- GET /api/approvals — List pending approval requests
- POST /api/approvals — Approve or deny a draft submission by { approvalId, action: "approve" \| "deny" }
- GET /api/approvals/[id] — Get single approval status
 
## Getting Started
 
1. Copy .env.example to .env and fill in credentials
2. pnpm install
3. pnpm dev
4. POST to /api/webhook/square with valid Square payload, or POST to /api/disputes with { disputeId }
 
## Guardrail Chain
 
Two guardrail layers: (1) GuardrailsEngine from @presidio-dev/hai-guardrails pre-screens input for prompt injection, PII, and secrets. (2) GuardrailChain from @reaatech/guardrail-chain runs PIIRedaction (mask) + PromptInjection on input, PIIScan + ToxicityFilter on output.
 
## Approval Workflow
 
Submitted dispute evidence requires admin approval. SlackApprover posts to the configured Slack webhook. ApprovalWorkflow enforces a 5-minute timeout. Admin can approve/deny via the /api/approvals endpoint.
 
## Budget & Observability
 
BudgetController tracks spend per scope (Active → Warned → Degraded → Stopped). Mandatory pre-flight check runs before each Mistral call. After each call, spend is recorded. Cost spans are created via @reaatech/llm-cost-telemetry and traced through Langfuse.
 
## Testing
 
pnpm test runs the vitest suite. 90+ tests cover 100% of runtime code across services, lib, adapters, and route handlers. Externals are mocked via vi.mock and MSW.