safeprompt-middleware

Vendor-neutral AI security middleware for Express and Next.js.

Works with any ai-security-gateway-spec compliant provider. Defaults to SafePrompt.

npm install safeprompt-middleware

Quick Start

Express

import express from 'express';
import { createGuard } from 'safeprompt-middleware';

const app = express();
app.use(express.json());

app.use('/api/chat', createGuard({
  apiKey: process.env.GUARD_API_KEY,
}));

app.post('/api/chat', (req, res) => {
  // req.body.prompt is safe — attach your LLM call here
  res.json({ reply: 'response from LLM' });
});

Next.js (Pages Router)

// pages/api/chat.ts
import { withGuard } from 'safeprompt-middleware/next';
import type { NextApiRequest, NextApiResponse } from 'next';

async function handler(req: NextApiRequest, res: NextApiResponse) {
  // req.body.prompt is safe
  res.json({ reply: 'response from LLM' });
}

export default withGuard(handler, {
  apiKey: process.env.GUARD_API_KEY!,
  fieldName: 'message', // the field to validate
});

Next.js (App Router)

// app/api/chat/route.ts
import { withGuardRoute } from 'safeprompt-middleware/next';

async function POST(req: Request) {
  const { message } = await req.json();
  return Response.json({ reply: 'response from LLM' });
}

export { withGuardRoute(POST, {
  apiKey: process.env.GUARD_API_KEY!,
  fieldName: 'message',
}) as POST };

Configuration

interface GuardConfig {
  provider?: string;    // Default: 'https://api.safeprompt.dev'
  apiKey: string;       // Required
  mode?: 'fast' | 'balanced' | 'strict';  // Default: 'balanced'
  fieldName?: string;   // req.body field to validate. Default: 'prompt'
  failOpen?: boolean;   // Allow through on provider error. Default: false
  onBlock?: (req, res, result) => void;
  onError?: (req, res, error) => void;
}

| Option | Default | Description | |--------|---------|-------------| | provider | https://api.safeprompt.dev | Any ai-security-gateway-spec URL | | apiKey | — | Required. API key for the provider | | mode | balanced | fast (<5ms, patterns only), balanced, strict (always AI) | | fieldName | prompt | Which req.body field to validate | | failOpen | false | Fail-closed by default — blocks on provider error | | onBlock | 400 + threats | Custom handler when a prompt is blocked | | onError | 500 or pass-through | Custom handler when provider is unreachable |

Changing Providers

The default provider is SafePrompt. To use any other conformant provider:

createGuard({
  provider: 'https://your-provider.com',
  apiKey: process.env.YOUR_PROVIDER_KEY,
})

The middleware spec is defined in ai-security-gateway-spec.

What Gets Attached

On a safe request, req.guardResult is set:

req.guardResult = {
  safe: true,
  threats: [],
  confidence: 0.99,
  processingTimeMs: 4,
  passesUsed: 1,
  request_id: 'uuid',
  timestamp: '2026-03-19T...',
}

On a provider error with failOpen: true, req.guardError is set with the error.

License

MIT