safeprompt-middleware 0.1.0

package/src/next.ts

@@ -0,0 +1,132 @@
+import type { GuardConfig, NextHandler } from './types.js';
+import { validate, DEFAULT_PROVIDER } from './client.js';
+
+function getClientIP(req: any): string | undefined {
+  const forwarded = req.headers?.['x-forwarded-for'];
+  if (forwarded) return String(forwarded).split(',')[0].trim();
+  return req.socket?.remoteAddress;
+}
+
+/**
+ * Wraps a Next.js Pages Router API handler with prompt injection protection.
+ * Validates req.body[fieldName] before passing to the original handler.
+ *
+ * @example — Pages Router
+ * export default withGuard(handler, { apiKey: process.env.GUARD_API_KEY })
+ *
+ * @example — App Router (Route Handler)
+ * export const POST = withGuardRoute(handler, { apiKey: process.env.GUARD_API_KEY })
+ */
+export function withGuard(handler: NextHandler, config: GuardConfig): NextHandler {
+  const {
+    provider = DEFAULT_PROVIDER,
+    apiKey,
+    mode = 'balanced',
+    fieldName = 'prompt',
+    failOpen = false,
+    onBlock,
+    onError,
+  } = config;
+
+  if (!apiKey) throw new Error('ai-security-middleware: apiKey is required');
+
+  return async function guardedHandler(req: any, res: any) {
+    const input = req.body?.[fieldName];
+
+    if (input === undefined || input === null || typeof input !== 'string') {
+      return handler(req, res);
+    }
+
+    try {
+      const result = await validate(input, {
+        provider,
+        apiKey,
+        mode,
+        userIP: getClientIP(req),
+      });
+
+      if (!result.safe) {
+        if (onBlock) return onBlock(req, res, result);
+        return res.status(400).json({
+          error: 'Request blocked: prompt injection detected',
+          threats: result.threats,
+          confidence: result.confidence,
+        });
+      }
+
+      req.guardResult = result;
+      return handler(req, res);
+    } catch (err: any) {
+      if (onError) return onError(req, res, err);
+      if (failOpen) {
+        req.guardError = err;
+        return handler(req, res);
+      }
+      return res.status(500).json({ error: 'Security check unavailable' });
+    }
+  };
+}
+
+/**
+ * Wraps a Next.js App Router (Route Handler) with prompt injection protection.
+ * Reads the JSON body and validates the specified field.
+ *
+ * @example
+ * export const POST = withGuardRoute(async (req) => {
+ *   const { message } = await req.json()
+ *   return Response.json({ reply: await chat(message) })
+ * }, { apiKey: process.env.GUARD_API_KEY, fieldName: 'message' })
+ */
+export function withGuardRoute(
+  handler: (req: Request) => Promise<Response>,
+  config: GuardConfig,
+): (req: Request) => Promise<Response> {
+  const {
+    provider = DEFAULT_PROVIDER,
+    apiKey,
+    mode = 'balanced',
+    fieldName = 'prompt',
+    failOpen = false,
+  } = config;
+
+  if (!apiKey) throw new Error('ai-security-middleware: apiKey is required');
+
+  return async function guardedRouteHandler(req: Request): Promise<Response> {
+    let body: Record<string, any>;
+    try {
+      body = await req.clone().json();
+    } catch {
+      return handler(req);
+    }
+
+    const input = body[fieldName];
+    if (input === undefined || input === null || typeof input !== 'string') {
+      return handler(req);
+    }
+
+    const userIP = req.headers.get('x-forwarded-for')?.split(',')[0].trim() ?? undefined;
+
+    try {
+      const result = await validate(input, { provider, apiKey, mode, userIP });
+
+      if (!result.safe) {
+        return new Response(
+          JSON.stringify({
+            error: 'Request blocked: prompt injection detected',
+            threats: result.threats,
+            confidence: result.confidence,
+          }),
+          { status: 400, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+
+      return handler(req);
+    } catch (err) {
+      if (failOpen) return handler(req);
+      return new Response(
+        JSON.stringify({ error: 'Security check unavailable' }),
+        { status: 500, headers: { 'Content-Type': 'application/json' } },
+      );
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+export interface ValidationResult {
+  safe: boolean;
+  threats: string[];
+  confidence: number;
+  processingTimeMs: number;
+  passesUsed: number;
+  request_id?: string;
+  timestamp?: string;
+}
+
+export interface GuardConfig {
+  /**
+   * Provider base URL. Must be a conformant ai-security-gateway-spec endpoint.
+   * Defaults to SafePrompt reference implementation.
+   */
+  provider?: string;
+  /** API key for the provider. */
+  apiKey: string;
+  /**
+   * Detection sensitivity mode. Defaults to 'balanced'.
+   * - 'fast': pattern detection only, <5ms
+   * - 'balanced': pattern + AI pass 1 when needed (default)
+   * - 'strict': always uses full AI validation
+   */
+  mode?: 'fast' | 'balanced' | 'strict';
+  /**
+   * The req.body field to validate. Defaults to 'prompt'.
+   * Set to 'message' for chat-style APIs, 'input' for others.
+   */
+  fieldName?: string;
+  /**
+   * If the provider is unreachable, allow requests through (fail-open).
+   * Defaults to false (fail-closed — block on provider error).
+   */
+  failOpen?: boolean;
+  /**
+   * Called when a prompt is blocked. Default behaviour: 400 with threats array.
+   */
+  onBlock?: (req: any, res: any, result: ValidationResult) => void | Promise<void>;
+  /**
+   * Called when the provider returns an error or is unreachable.
+   * Default: fail-closed (500) or fail-open based on failOpen setting.
+   */
+  onError?: (req: any, res: any, error: Error) => void | Promise<void>;
+}
+
+export type NextHandler = (req: any, res: any) => any;
+export type ExpressMiddleware = (req: any, res: any, next: () => void) => void;