Files · Vertical-specific Safety Guardrails for SMB SaaS

# Vertical-specific Safety Guardrails for SMB SaaS
 
*Enforce HIPAA, PCI, or other compliance rules per tenant with customizable guardrails.*
 
## Problem
 
As a compliance officer at a vertical SaaS provider, you must ensure that AI features adhere to industry-specific regulations like HIPAA for vet-tech or PCI for restaurant-tech. Off-the-shelf guardrails are too generic and don't map to your vertical workflows. You need a way to define and enforce safety policies per tenant, with observability into violations. Your current approach relies on manual reviews, which doesn't scale.
 
## Architecture
 
This recipe demonstrates how to compose per-tenant safety guardrails and a tool-use firewall into a Next.js + Hono API application:
 
- **Hono API layer** (`src/lib/hono-app.ts`) — All API routes are served through a Hono app using the `hono/vercel` adapter, exposed via a Next.js catch-all route at `app/api/[[...route]]/route.ts`.
- **Per-vertical Guardrail Chain** (`src/services/guardrail-service.ts`) — Uses `@reaatech/guardrail-chain`'s `ChainBuilder` to compose input and output guardrails (PII redaction, prompt injection, topic boundary, toxicity filter, etc.) tailored to HIPAA, PCI, and SOC2 compliance verticals.
- **Tool-Use Firewall** (`src/services/firewall-service.ts`) — Uses `@reaatech/tool-use-firewall-policies`'s `PolicyEngine` and `SecretScanner` to block unauthorized tool calls and detect secrets in tool arguments.
- **Config loader** (`src/services/config-loader.ts`) — Loads vertical-specific guardrail configurations from YAML files using `@reaatech/guardrail-chain-config`.
- **Observability** (`src/services/observability.ts`) — Sets up logging, metrics, and tracing via `@reaatech/guardrail-chain-observability`.
- **Tenant store** (`src/services/tenant-store.ts`) — In-memory store seeded with three default tenants (HIPAA, PCI, SOC2).
 
## REAA packages
 
| Package | Version | Purpose |
|---------|---------|---------|
| `@reaatech/guardrail-chain` | 0.1.0 | Core guardrail chain orchestration, budget management, and type system |
| `@reaatech/guardrail-chain-config` | 0.1.0 | Load and validate guardrail configuration from YAML/JSON/env |
| `@reaatech/guardrail-chain-guardrails` | 0.1.0 | 13 built-in guardrail implementations (PII, injection, toxicity, etc.) |
| `@reaatech/guardrail-chain-observability` | 0.1.0 | Pluggable logging, metrics, and tracing interfaces |
| `@reaatech/tool-use-firewall-core` | 0.1.0 | Core types, error classes, and redaction utilities for tool-use firewall |
| `@reaatech/tool-use-firewall-policies` | 0.1.0 | Policy engine, rate limiter, secret scanner, and argument validators |
 
## Vertical configurations
 
Three YAML configuration files in `config/` define guardrail compositions:
 
### HIPAA (`config/hipaa.guardrail.yaml`)
- **Input**: PIIRedaction (masks SSN, phone, email), PromptInjection detection, TopicBoundary (blocks PHI topics)
- **Output**: PIIScan (scans for remaining PHI), ToxicityFilter, HallucinationCheck
 
### PCI DSS (`config/pci.guardrail.yaml`)
- **Input**: PIIRedaction (removes credit card data), PromptInjection, TopicBoundary (blocks payment data), CostPrecheck
- **Output**: PIIScan, ToxicityFilter
 
### SOC2 (`config/soc2.guardrail.yaml`)
- **Input**: ContentModeration, PromptInjection, MemoryLimit
- **Output**: ToxicityFilter, HallucinationCheck, SentimentAnalysis
 
## API endpoints
 
### Guardrail evaluation
 
```
POST /api/guardrails/evaluate
```
 
Evaluate user input (and optional output) against a tenant's guardrail chain.
 
Request:
```json
{
  "tenantId": "tenant-hipaa",
  "input": "What is the patient's medical record number?",
  "output": "The patient's MRN is 123-45-6789"
}
```
 
Response:
```json
{
  "passed": false,
  "violations": ["pii-redaction"],
  "metadata": { "correlationId": "abc-123", "totalDuration": 42, "phase": "input" }
}
```
 
### Tool-call protection
 
```
POST /api/middleware/protect
```
 
Check whether a tool call is allowed by the tenant's firewall policies.
 
Request:
```json
{
  "tenantId": "tenant-soc2",
  "toolName": "db_query",
  "arguments": { "query": "SELECT * FROM users" },
  "sessionId": "session-abc"
}
```
 
Response:
```json
{
  "allowed": true,
  "action": "CONTINUE"
}
```
 
### Tenant management
 
```
GET    /api/tenants              — List all tenants
POST   /api/tenants              — Create a tenant
GET    /api/tenants/:id          — Get tenant by ID
PUT    /api/tenants/:id          — Update tenant
DELETE /api/tenants/:id          — Delete tenant
```
 
### Health
 
```
GET /api/health
```
 
Response: `{ "status": "ok" }`
 
## Setup
 
```bash
# Install dependencies
pnpm install
 
# Start the development server
pnpm dev
 
# Run type checking
pnpm typecheck
 
# Run linting
pnpm lint
 
# Run tests with coverage
pnpm test
```
 
## Environment variables
 
Copy `.env.example` to `.env` and set:
 
| Variable | Description |
|----------|-------------|
| `GUARDRAIL_CHAIN_BUDGET_MAX_LATENCY_MS` | Max latency budget for guardrail chain (ms) |
| `GUARDRAIL_CHAIN_BUDGET_MAX_TOKENS` | Max token budget for guardrail chain |
| `GUARDRAIL_CHAIN_BUDGET_SKIP_SLOW` | Whether to skip slow guardrails under pressure |
| `GUARDRAIL_CHAIN_CONFIG` | Optional JSON config override |
 
## Usage examples
 
```bash
# Evaluate input against HIPAA guardrails
curl -X POST http://localhost:3000/api/guardrails/evaluate \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "tenant-hipaa", "input": "My email is john@hospital.com"}'
 
# Protect a tool call
curl -X POST http://localhost:3000/api/middleware/protect \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "tenant-soc2", "toolName": "db_query", "arguments": {"query": "SELECT 1"}, "sessionId": "s1"}'
 
# List tenants
curl http://localhost:3000/api/tenants
 
# Create a tenant
curl -X POST http://localhost:3000/api/tenants \
  -H "Content-Type: application/json" \
  -d '{"id": "my-tenant", "name": "My SaaS", "vertical": "hipaa"}'
```
 
## License
 
MIT