Files · Mistral AI Security Guardrails for Etsy SMB Marketplace Messaging

# Mistral AI Security Guardrails for Etsy SMB Marketplace Messaging
 
> Automated content safety scanning for Etsy seller messages, blocking PII leaks, abuse, and phishing before they reach the recipient.
 
Small Etsy sellers receive hundreds of buyer messages daily and risk sharing personal data or falling for scams without automated protection. This recipe deploys a guardrail chain that scans incoming Etsy messages using Mistral AI's moderation capabilities, PII detection via `@presidio-dev/hai-guardrails`, and budget enforcement via `@reaatech/agent-budget-engine`.
 
## Architecture
 
```
Etsy Webhook → Hono POST /etsy-webhook
                 ↓
          PII Scanner (hai-guardrails)
                 ↓
          Mistral Moderation (abuse/phishing classifier)
                 ↓
          Guardrail Chain (PIIRedaction + ContentModeration + ToxicityFilter)
                 ↓
          Budget Check (@reaatech/agent-budget-engine)
                 ↓
          Quarantine / Alert
```
 
## Tech Stack
 
- **Hono** — Webhook endpoint for receiving Etsy message events
- **Next.js 16 App Router** — Dashboard UI and REST API for quarantined messages
- **@mistralai/mistralai** — Mistral AI chat completion + moderation classifiers
- **@presidio-dev/hai-guardrails** — PII detection via `piiGuard` and `GuardrailsEngine`
- **@reaatech/guardrail-chain** — Chain orchestration with `ChainBuilder`, budget-aware scheduling, circuit breaker
- **@reaatech/guardrail-chain-config** — YAML/env-based config loading via `loadConfig`
- **@reaatech/guardrail-chain-guardrails** — Built-in `PIIRedaction`, `ToxicityFilter`, `ContentModeration`, `CachedGuardrail`
- **@reaatech/agent-budget-engine** — Budget enforcement with `BudgetController`, pre-flight checks, spend recording
- **zod** — Schema validation for configuration
- **langfuse** — LLM observability and tracing
 
## Setup
 
```bash
pnpm install
```
 
Copy `.env.example` to `.env` and fill in your API keys:
 
```env
MISTRAL_API_KEY=<your-mistral-api-key>
ETSY_WEBHOOK_SECRET=<your-etsy-webhook-secret>
GUARDRAIL_CHAIN_BUDGET_MAX_LATENCY_MS=1000
GUARDRAIL_CHAIN_BUDGET_MAX_TOKENS=8000
LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
LANGFUSE_BASE_URL=<your-langfuse-base-url>
BUDGET_SCOPE_KEY=default-seller
BUDGET_LIMIT_USD=10.0
```
 
## Usage
 
1. **Webhook endpoint**: Deploy the app and configure Etsy webhooks to point at `POST /etsy-webhook`. The endpoint receives message events, scans for PII, classifies content for abuse/phishing, and quarantines flagged messages.
 
2. **Dashboard**: Navigate to the app root to view quarantined messages and budget status.
 
3. **API**: Use `GET /api/quarantine` to list quarantined messages, `PATCH /api/quarantine` to update status, and `GET /api/budget` to check budget usage.
 
## Configuration
 
Edit `guardrail.config.yaml` to tune guardrail thresholds:
 
```yaml
budget:
  maxLatencyMs: 1000
  maxTokens: 8000
  skipSlowGuardrailsUnderPressure: true
```
 
Environment variables override file config with the `GUARDRAIL_CHAIN_` prefix.
 
## Testing
 
```bash
pnpm test            # vitest run with coverage
pnpm typecheck       # tsc --noEmit
pnpm lint            # eslint .
```
 
Coverage target: 90%+ on lines, branches, functions, and statements for runtime code (`src/**/*.ts`, `app/**/route.ts`).
 
## API Reference
 
| Endpoint | Method | Description |
|---|---|---|
| `/etsy-webhook` | POST | Receive Etsy message events for scanning |
| `/health` | GET | Health check |
| `/api/quarantine` | GET | List quarantined messages |
| `/api/quarantine` | PATCH | Update quarantine status |
| `/api/quarantine/[id]` | GET | Get quarantine detail |
| `/api/quarantine/[id]` | DELETE | Remove quarantine entry |
| `/api/budget` | GET | Get budget status |
 
## License
 
MIT — see [LICENSE](./LICENSE).