@bulwark-ai/gateway 0.1.2 → 0.1.3

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="banner.svg" alt="Bulwark AI" width="100%">
+  <img src="https://raw.githubusercontent.com/antonmacius-droid/bulwark-ai/main/banner.svg" alt="Bulwark AI" width="100%">
 </p>
 
 <p align="center">
@@ -20,10 +20,10 @@
 npm install @bulwark-ai/gateway
 ```
 
-**131 tests passing** (42 unit + 89 integration with real LLM calls) | **Zero type errors** | MIT + BSL 1.1
+**136 tests passing** (42 unit + 94 integration with real LLM calls) | **Zero type errors** | MIT + BSL 1.1
 
 <p align="center">
-  <img src="demo.svg" alt="Bulwark AI Pipeline" width="100%">
+  <img src="https://raw.githubusercontent.com/antonmacius-droid/bulwark-ai/main/demo.svg" alt="Bulwark AI Pipeline" width="100%">
 </p>
 
 ## Quick Start
@@ -31,6 +31,15 @@ npm install @bulwark-ai/gateway
 ```typescript
 import { AIGateway } from "@bulwark-ai/gateway";
 
+// Option A: Use a preset (recommended)
+const gateway = new AIGateway({
+  mode: "balanced",                  // "strict" | "balanced" | "dev"
+  failMode: "fail-closed",          // "fail-closed" | "fail-open"
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  database: "bulwark.db",
+});
+
+// Option B: Full control
 const gateway = new AIGateway({
   providers: {
     openai: { apiKey: process.env.OPENAI_API_KEY! },
@@ -56,13 +65,30 @@ const response = await gateway.chat({
 
 | Problem | Solution |
 |---------|---------|
-| Employees send PII to ChatGPT | Auto-detect & redact 15 PII types (input AND output) |
+| Employees send PII to ChatGPT | Auto-detect & redact 14 PII types (input AND output) |
 | No visibility into AI spend | Per-user/team budgets with real-time cost tracking |
 | Prompt injection attacks | Built-in guard with 20+ detection patterns |
 | No audit trail | Every request logged — user, model, tokens, cost, duration |
 | GDPR/SOC 2 compliance | Right to erasure, data export, retention, anomaly detection |
 | Different teams use different tools | One gateway, 6 LLM providers, unified policies |
 
+## Config Presets
+
+| Mode | PII | Budgets | Injection Guard | Best For |
+|------|-----|---------|----------------|----------|
+| `strict` | Block | 100K tokens, block | High sensitivity | Healthcare, finance, regulated |
+| `balanced` | Redact | 500K tokens | Medium sensitivity | General production use |
+| `dev` | Off | Off | On (audit only) | Development and testing |
+
+```typescript
+// Strict mode — blocks PII, tight budgets, aggressive injection detection
+new AIGateway({ mode: "strict", providers: { ... }, database: "bulwark.db" });
+
+// Fail strategy — what happens when governance itself breaks
+new AIGateway({ failMode: "fail-open", ... });   // availability-first (log failure, allow request)
+new AIGateway({ failMode: "fail-closed", ... });  // security-first (block request if governance fails)
+```
+
 ## Features
 
 ### 6 LLM Providers — Auto-Routing
@@ -88,6 +114,8 @@ await gateway.chat({ model: "llama3.2", ... });            // → Ollama
 
 Azure OpenAI also supported via `AzureOpenAIProvider`.
 
+**SSRF Protection**: All provider `baseUrl` values are validated — private IPs, cloud metadata endpoints (169.254.169.254), and non-HTTPS URLs are blocked automatically.
+
 ### Retry + Fallback
 
 ```typescript
@@ -117,7 +145,7 @@ pii: {
   action: "redact",  // "block" | "redact" | "warn"
   types: ["email", "phone", "ssn", "credit_card", "iban",
           "ip_address", "passport", "name", "vat_number",
-          "national_id", "medical_id"],  // 15 built-in types
+          "national_id", "medical_id"],  // 14 built-in types
   customPatterns: [
     { name: "employee_id", pattern: "EMP-\\d{6}", action: "redact" },
   ],
@@ -126,7 +154,9 @@ pii: {
 
 **Input**: PII redacted before sending to LLM. `"Contact john@test.com"` → `"Contact [EMAIL]"`
 **Output**: LLM response scanned and PII redacted before returning to user.
+**Credit card Luhn validation**: Only real card numbers are flagged (rejects random digit sequences).
 **ReDoS protected**: Malicious regex patterns (nested quantifiers) automatically rejected.
+**Security**: PII values are never stored in match objects or error responses — only type and position are recorded.
 
 ### Prompt Injection Guard
 
@@ -177,6 +207,8 @@ for await (const event of stream) {
 }
 ```
 
+Streaming runs the identical governance pipeline as non-streaming — all messages scanned for PII and injection, system prompts hardened.
+
 ### Budget Enforcement + Rate Limiting
 
 ```typescript
@@ -306,6 +338,117 @@ curl http://localhost:3100/v1/chat \
   -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'
 ```
 
+## Integration Guides
+
+### Add to Existing Express App (5 min)
+
+```typescript
+// 1. Install
+// npm install @bulwark-ai/gateway
+
+// 2. Create gateway (once, at app startup)
+import { AIGateway, bulwarkRouter } from "@bulwark-ai/gateway";
+
+const gateway = new AIGateway({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  database: "bulwark.db",
+  pii: { enabled: true, action: "redact" },
+  budgets: { enabled: true, defaultUserLimit: 500_000 },
+  audit: true,
+});
+
+// 3. Mount (one line)
+app.use("/api/ai", bulwarkRouter(gateway, {
+  auth: (req) => ({ userId: req.user.id, teamId: req.user.team }),
+}));
+
+// That's it. POST /api/ai/chat now has full governance.
+```
+
+### Add to Next.js App Router (5 min)
+
+```typescript
+// app/api/ai/chat/route.ts
+import { AIGateway, createNextHandler } from "@bulwark-ai/gateway";
+
+const gateway = new AIGateway({ /* same config */ });
+
+export const POST = createNextHandler(gateway, {
+  auth: (req) => ({
+    userId: req.headers.get("x-user-id") || undefined,
+  }),
+});
+```
+
+### Add to Fastify (5 min)
+
+```typescript
+import { AIGateway, bulwarkPlugin } from "@bulwark-ai/gateway";
+
+const gateway = new AIGateway({ /* same config */ });
+
+app.register(bulwarkPlugin, {
+  gateway,
+  prefix: "/api/ai",
+  auth: (req) => ({ userId: req.headers["x-user-id"] }),
+});
+```
+
+### Programmatic Usage (No Framework)
+
+```typescript
+// Use the gateway directly — no HTTP framework needed
+const gateway = new AIGateway({ /* config */ });
+await gateway.init();
+
+const response = await gateway.chat({
+  model: "gpt-4o",
+  userId: "user-123",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+// Streaming
+for await (const event of gateway.chatStream({ /* same params */ })) {
+  if (event.type === "delta") process.stdout.write(event.content);
+}
+```
+
+## Best Practices
+
+**Start small, add incrementally:**
+1. Start with `pii` + `audit` — instant visibility into what data flows through your AI
+2. Add `budgets` when you need cost control — set generous limits first, tighten later
+3. Add `policies` for specific compliance needs (block secrets, restrict topics)
+4. Add `rag` when you need document-grounded answers
+5. Add `fallbacks` for production reliability
+
+**Multi-tenant SaaS:**
+- Always pass `tenantId` from your auth layer — never from the request body
+- Each tenant's data is isolated: RAG, audit, budgets, usage
+- Use `gateway.tenants` API to manage tenant lifecycle
+
+**Production checklist:**
+- [ ] SQLite database with regular backups (Postgres support is experimental)
+- [ ] PII detection enabled with `action: "redact"`
+- [ ] Budget limits set per user and team
+- [ ] Auth function validates tokens (never trust request body for identity)
+- [ ] `BULWARK_LICENSE_KEY` set if using RAG/compliance modules commercially
+- [ ] Graceful shutdown: `process.on("SIGTERM", () => gateway.shutdown())`
+- [ ] Monitor audit logs for anomalies (see SOC 2 module)
+
+## Use Cases
+
+| Use Case | Key Features |
+|----------|-------------|
+| **Internal AI chatbot** | PII redaction, audit trail, budget per department |
+| **Customer-facing AI** | Prompt injection guard, content policies, rate limiting |
+| **Multi-tenant SaaS** | Tenant isolation, per-org budgets, separate KB per tenant |
+| **Healthcare AI** | HIPAA PHI logging, PII blocking, audit immutability |
+| **EU compliance** | GDPR erasure/export, data residency checks, PII redaction |
+| **Document Q&A** | RAG knowledge base, source citations, chunking strategies |
+| **AI cost management** | Per-user budgets, alert thresholds, cost tracking per model |
+| **Security-first AI** | Prompt hardening, injection guard, SSRF protection |
+
 ## Architecture
 
 ```
@@ -340,13 +483,13 @@ Your App
 | Store | Use Case | Config |
 |-------|----------|--------|
 | **SQLite** | Development, single instance | `database: "bulwark.db"` |
-| **PostgreSQL** | Production, pgvector for RAG | `database: "postgres://..."` |
+| **PostgreSQL** | Production, pgvector for RAG (experimental — use SQLite for production) | `database: "postgres://..."` |
 | **Redis** | Rate limiting, response caching | `cache: new RedisCacheStore(redis)` |
 | **In-Memory** | Testing | Default |
 
 ## Test Suite
 
-**131 tests, 100% pass rate.**
+**136 tests, 100% pass rate.**
 
 | Suite | Tests | What |
 |-------|-------|------|
@@ -377,6 +520,7 @@ Your App
 | Integration: RAG E2E | 3 | Ingest → search → chat with KB, tenant isolation, delete |
 | Integration: Retry + Fallback | 3 | Provider fallback, retry success, exhaustion |
 | Integration: Runtime Policies | 2 | Add/remove at runtime |
+| Integration: Security Regression | 5 | Streaming PII/injection scan, prompt hardening, PII value protection |
 
 Run integration tests: `OPENAI_API_KEY=sk-xxx npx vitest run src/__tests__/integration.test.ts`
 
@@ -389,6 +533,7 @@ Run integration tests: `OPENAI_API_KEY=sk-xxx npx vitest run src/__tests__/integ
 | Embeddable | Yes (`npm install`) | No (proxy) | No | No |
 | PII Detection | 15 types + custom | Plugin | Partial | No |
 | Output PII Scan | Yes | No | No | No |
+| Output PII Protection | Yes (non-streaming) | No | No | No |
 | Prompt Injection Guard | 20+ patterns | No | No | No |
 | Budget Control | Per-user/team | Yes | Yes | No |
 | Audit Log | Yes | Yes | Yes | Yes |
@@ -402,7 +547,7 @@ Run integration tests: `OPENAI_API_KEY=sk-xxx npx vitest run src/__tests__/integ
 | Redis Support | Yes | No | N/A | N/A |
 | Providers | 6 | 100+ | Many | Many |
 | Retry + Fallback | Yes | Yes | Yes | No |
-| Test Suite | 131 tests | ? | ? | ? |
+| Test Suite | 136 tests | ? | ? | ? |
 
 ## License
 

package/dist/index.d.ts

@@ -134,7 +134,26 @@ interface ProviderConfig {
     defaultModel?: string;
 }
 type GatewayProvider = "openai" | "anthropic" | "mistral" | "google" | "ollama" | "azure" | "custom";
+/**
+ * Quick-start presets — use instead of manual config.
+ * - `strict`: All protections on, PII blocked, low budgets, injection guard high sensitivity
+ * - `balanced`: PII redacted, moderate budgets, injection guard medium (default behavior)
+ * - `dev`: Minimal protections, no budgets, audit only — for development/testing
+ */
+type GatewayMode = "strict" | "balanced" | "dev";
+/**
+ * What happens when the governance system itself fails (e.g., DB down, PII scan crashes).
+ * - `fail-closed`: Block the request (safe default — no request passes without governance)
+ * - `fail-open`: Allow the request through (availability-first — log the failure, don't block users)
+ */
+type FailMode = "fail-closed" | "fail-open";
 interface GatewayConfig {
+    /** Quick-start preset — sets sensible defaults for all options. Individual settings override. */
+    mode?: GatewayMode;
+    /** What happens when governance checks fail (default: "fail-closed") */
+    failMode?: FailMode;
+    /** Global kill switch — set to false to block ALL requests instantly */
+    enabled?: boolean;
     /** LLM provider credentials */
     providers: Partial<Record<GatewayProvider, ProviderConfig>>;
     /** Database connection — SQLite path or Postgres URL */
@@ -158,6 +177,23 @@ interface GatewayConfig {
         input: number;
         output: number;
     }>;
+    /** Prompt injection guard config */
+    promptGuard?: {
+        enabled?: boolean;
+        action?: "block" | "warn";
+        sensitivity?: "low" | "medium" | "high";
+    };
+    /** LLM call timeout in ms (default: 120000) */
+    timeoutMs?: number;
+    /** Cache store for rate limiting + response caching */
+    cache?: unknown;
+    /** Rate limiting config */
+    rateLimit?: {
+        enabled?: boolean;
+        maxRequests?: number;
+        windowSeconds?: number;
+        scope?: "user" | "team" | "tenant" | "ip";
+    };
     /** Retry config for failed LLM calls */
     retry?: {
         /** Max retry attempts (default: 2) */
@@ -196,14 +232,18 @@ interface ChatRequest {
     teamId?: string;
     /** Tenant ID for multi-tenant isolation */
     tenantId?: string;
-    /** RAG knowledge base to search */
-    knowledgeBase?: string;
+    /** RAG knowledge base — set to true to enable, or pass a source ID to search specific source */
+    knowledgeBase?: boolean | string;
     /** Override PII settings for this request */
     pii?: boolean;
     /** Override policies for this request */
     skipPolicies?: boolean;
     /** Streaming */
     stream?: boolean;
+    /** Debug mode — returns pipeline trace showing what each governance step did */
+    debug?: boolean;
+    /** Custom metadata — stored in audit log for analytics (e.g., feature, product, environment) */
+    metadata?: Record<string, string | number | boolean>;
     /** Pass-through params (temperature, max_tokens, etc) */
     temperature?: number;
     maxTokens?: number;
@@ -233,6 +273,7 @@ interface ChatResponse {
     piiDetections?: {
         type: string;
         redacted: boolean;
+        direction?: "input" | "output";
     }[];
     /** Policy violations (if any) */
     policyViolations?: {
@@ -249,6 +290,13 @@ interface ChatResponse {
     auditId?: string;
     /** Request duration in ms */
     durationMs: number;
+    /** Debug trace — only present when `debug: true` in request */
+    trace?: {
+        stage: string;
+        result: string;
+        durationMs: number;
+        details?: unknown;
+    }[];
 }
 
 interface PolicyViolation {
@@ -416,7 +464,7 @@ declare class TenantManager {
         name?: string;
         settings?: Record<string, unknown>;
     }): void;
-    /** Delete a tenant and ALL its data */
+    /** Delete a tenant and ALL its data (transactional) */
     delete(id: string): void;
     /** Get usage stats for a tenant */
     getUsage(id: string): {
@@ -466,6 +514,8 @@ declare class AIGateway {
     private readonly timeoutMs;
     private readonly retryConfig;
     private readonly fallbacks;
+    private readonly failMode;
+    private _enabled;
     private initialized;
     private shutdownRequested;
     private activeRequests;
@@ -526,6 +576,9 @@ declare class AIGateway {
     get policies(): PolicyEngine;
     /** Get the tenant manager (multi-tenant mode only) */
     get tenants(): TenantManager | null;
+    /** Kill switch — disable/enable the gateway at runtime */
+    get enabled(): boolean;
+    set enabled(value: boolean);
 }
 /** Bulwark-specific error with code and metadata */
 declare class BulwarkError extends Error {
@@ -551,9 +604,11 @@ interface ScanResult {
     redacted: boolean;
 }
 declare class PIIDetector {
-    private config;
+    private _config;
     private activeTypes;
     constructor(config: PIIConfig);
+    /** Whether PII detection is enabled */
+    get config(): PIIConfig;
     /** Scan text for PII. Returns matches and optionally redacted text. */
     scan(text: string): ScanResult;
 }
@@ -608,6 +663,8 @@ declare class CostCalculator {
     }>);
     /** Calculate cost for a request. Returns USD amounts. */
     calculate(model: string, inputTokens: number, outputTokens: number): CostRecord;
+    /** Detect provider from model name */
+    private detectProvider;
     /** Update pricing for a model */
     setModelPrice(model: string, input: number, output: number): void;
 }
@@ -622,6 +679,8 @@ declare class BudgetManager {
     enabled: boolean;
     private config;
     private db;
+    /** Tracks which thresholds have already been crossed per scope to avoid duplicate alerts */
+    private crossedThresholds;
     constructor(db: Database, config: BudgetConfig);
     /** Check if a user/team has budget remaining this month */
     checkBudget(scope: {
@@ -678,6 +737,7 @@ declare function parsePDF(buffer: Buffer): Promise<string>;
 declare function parseHTML(html: string): string;
 /**
  * Parse a CSV string into text (row per line).
+ * Handles quoted fields containing commas.
  */
 declare function parseCSV(csv: string): string;
 /**
@@ -734,7 +794,10 @@ declare class MemoryCacheStore implements CacheStore {
     private store;
     private counters;
     private cleanupTimer;
-    constructor();
+    private maxEntries;
+    constructor(options?: {
+        maxEntries?: number;
+    });
     /** Stop background cleanup — call on shutdown */
     close(): void;
     private cleanup;
@@ -869,19 +932,6 @@ interface StreamEvent {
         durationMs?: number;
     };
 }
-/**
- * Creates an async iterable of stream events.
- * Pre-flight checks (PII, policies, budget, rate limit) run before streaming starts.
- * Token counting and audit logging happen after stream completes.
- */
-declare function createStreamAdapter(providerStream: AsyncIterable<string>, metadata: {
-    piiWarnings?: string[];
-    sources?: {
-        content: string;
-        source: string;
-        score: number;
-    }[];
-}): AsyncGenerator<StreamEvent>;
 
 /**
  * GDPR Compliance Module
@@ -1419,7 +1469,13 @@ declare function createNextHandler(gateway: AIGateway, options?: {
         tenantId?: string;
     } | null;
 }): (req: RequestLike) => Promise<Response>;
-declare function createNextAuditHandler(gateway: AIGateway): (req: RequestLike) => Promise<Response>;
+declare function createNextAuditHandler(gateway: AIGateway, options?: {
+    auth?: (req: RequestLike) => {
+        userId?: string;
+        teamId?: string;
+        tenantId?: string;
+    } | null;
+}): (req: RequestLike) => Promise<Response>;
 
 /**
  * Fastify plugin for Bulwark AI.
@@ -1487,4 +1543,4 @@ declare function createAdminRouter(gateway: AIGateway, options: {
     auth: (req: unknown) => boolean;
 }): any;
 
-export { AIGateway, type AdminDashboard, type AnomalyEvent, AnthropicProvider, type AuditEntry, type AuditQuery, type AuditStore, AzureOpenAIProvider, type BreachEvent, type BudgetAlert, type BudgetConfig, BudgetManager, BulwarkError, type CCPAConfig, CCPAManager, type CacheStore, type ChangeLogEntry, type ChatMessage, type ChatRequest, type ChatResponse, type Chunk, type ConsumerRequest, type ContentPolicy, CostCalculator, type CostRecord, type DataResidencyConfig, DataResidencyManager, type Database, type GDPRConfig, GDPRManager, type GatewayConfig, type GatewayProvider, GoogleProvider, type HIPAAConfig, HIPAAManager, HIPAA_IDENTIFIERS, type HealthStatus, KnowledgeBase, type KnowledgeSource, type LLMProvider, type LLMRequest, type LLMResponse, MODEL_PRICING, MemoryCacheStore, MistralProvider, OllamaProvider, OpenAIEmbeddings, OpenAIProvider, type PHIAccessLog, type PIIConfig, PIIDetector, type PIIMatch, type PIIType, PROVIDER_REGIONS, PolicyEngine, type ProcessingReport, PromptGuard, type PromptGuardConfig, type PromptGuardResult, type ProviderConfig, type RAGConfig, type RateLimitConfig, type RateLimitResult, RateLimiter, RedisCacheStore, ResponseCache, type ResponseCacheConfig, type SOC2Config, SOC2Manager, type SearchResult, type StreamEvent, type TenantConfig, TenantManager, type TransferAssessment, type UsageRecord, type UserDataExport, type VendorReport, bulwarkMiddleware, bulwarkPlugin, bulwarkRouter, chunkText, cosineSimilarity, createAdminRouter, createAuditStore, createDatabase, createNextAuditHandler, createNextHandler, createStreamAdapter, getDashboard, hardenSystemPrompt, parseCSV, parseDocument, parseHTML, parseMarkdown, parsePDF };
+export { AIGateway, type AdminDashboard, type AnomalyEvent, AnthropicProvider, type AuditEntry, type AuditQuery, type AuditStore, AzureOpenAIProvider, type BreachEvent, type BudgetAlert, type BudgetConfig, BudgetManager, BulwarkError, type CCPAConfig, CCPAManager, type CacheStore, type ChangeLogEntry, type ChatMessage, type ChatRequest, type ChatResponse, type Chunk, type ConsumerRequest, type ContentPolicy, CostCalculator, type CostRecord, type DataResidencyConfig, DataResidencyManager, type Database, type FailMode, type GDPRConfig, GDPRManager, type GatewayConfig, type GatewayMode, type GatewayProvider, GoogleProvider, type HIPAAConfig, HIPAAManager, HIPAA_IDENTIFIERS, type HealthStatus, KnowledgeBase, type KnowledgeSource, type LLMProvider, type LLMRequest, type LLMResponse, MODEL_PRICING, MemoryCacheStore, MistralProvider, OllamaProvider, OpenAIEmbeddings, OpenAIProvider, type PHIAccessLog, type PIIConfig, PIIDetector, type PIIMatch, type PIIType, PROVIDER_REGIONS, PolicyEngine, type ProcessingReport, PromptGuard, type PromptGuardConfig, type PromptGuardResult, type ProviderConfig, type RAGConfig, type RateLimitConfig, type RateLimitResult, RateLimiter, RedisCacheStore, ResponseCache, type ResponseCacheConfig, type SOC2Config, SOC2Manager, type SearchResult, type StreamEvent, type TenantConfig, TenantManager, type TransferAssessment, type UsageRecord, type UserDataExport, type VendorReport, bulwarkMiddleware, bulwarkPlugin, bulwarkRouter, chunkText, cosineSimilarity, createAdminRouter, createAuditStore, createDatabase, createNextAuditHandler, createNextHandler, getDashboard, hardenSystemPrompt, parseCSV, parseDocument, parseHTML, parseMarkdown, parsePDF };