npm package: @know-your-ai/firewall
Description: Firewall integration for Know Your AI SDK - AI content safety validation
Author: HydroxAI
Latest version: 0.1.0

# @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

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

## Quick Start

```typescript
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:

```typescript
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