@know-your-ai/firewall

Content safety validation integration for the Know Your AI SDK. Automatically validates AI inputs and outputs against the Know-Your-AI-Firewall API to detect and block harmful content.

Installation

npm install @know-your-ai/firewall @know-your-ai/node

Quick Start

import * as KnowYourAI from '@know-your-ai/node';
import { firewallIntegration } from '@know-your-ai/firewall';

KnowYourAI.init({
  dsn: 'your-dsn',
  integrations: [
    KnowYourAI.googleGenAIIntegration(),
    firewallIntegration({
      baseUrl: 'https://your-firewall-host.com',
      apiKey: 'fw_xxxxxxxx',
      validateInput: true,    // Validate prompts before sending
      validateOutput: true,   // Validate responses after receiving
      onInputViolation: 'block',  // Block dangerous prompts
      onOutputViolation: 'log',   // Log dangerous responses
    }),
  ],
});

How It Works

The firewall integration uses the SDK's hook system:

1. beforeRequest hook — Before each AI call, the input/prompt is sent to POST /api/validations/text/sync for validation. If a risk is detected, the request can be blocked (throws HookBlockedError).

2. afterResponse hook — After each AI call, both the prompt and response are sent to POST /api/validations/pair-text/sync for pair validation. This catches cases where the response is harmful in context.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseUrl | string | required | Firewall API base URL | | apiKey | string | required | Firewall API key (fw_xxxxxxxx) | | validateInput | boolean | true | Validate prompts before AI call | | validateOutput | boolean | true | Validate responses after AI call | | onInputViolation | 'block' \| 'log' \| 'callback' | 'block' | Action on input violation | | onOutputViolation | 'block' \| 'log' \| 'callback' | 'log' | Action on output violation | | violationCallback | function | — | Custom callback for violations | | riskThreshold | number | 0 | Minimum risk score (0-1) to trigger | | categories | string[] | — | Only trigger on specific categories | | timeout | number | 10000 | API request timeout (ms) | | debug | boolean | false | Enable debug logging |

Violation Actions

• block — Throws a HookBlockedError, preventing the AI request from being sent (input) or the response from being returned (output).
• log — Logs a warning via console.warn but allows the request/response to proceed.
• callback — Calls your custom violationCallback function with full context.

Standalone Client

You can also use the FirewallClient directly without the SDK integration:

import { FirewallClient } from '@know-your-ai/firewall';

const client = new FirewallClient({
  baseUrl: 'https://your-firewall-host.com',
  apiKey: 'fw_xxxxxxxx',
});

// Validate a single prompt
const result = await client.validateText('How to make a bomb');
console.log(result.has_issue); // true
console.log(result.risks);     // [{ category: 'VIOLENCE', score: 0.95, reason: '...' }]

// Validate prompt + response pair
const pairResult = await client.validatePairText(
  'How to make a bomb',
  'I cannot help with that.'
);

License

MIT