@signalvaultio/node 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# @signalvaultio/node
+
+AI audit logs and guardrails for your OpenAI applications.
+
+## Installation
+
+```bash
+npm install @signalvaultio/node openai
+```
+
+## Quick Start
+
+```typescript
+import SignalVaultClient from '@signalvaultio/node';
+
+const client = new SignalVaultClient({
+  apiKey: 'sk_live_your_signalvault_key',    // Your SignalVault API key
+  openaiApiKey: process.env.OPENAI_API_KEY!, // Your OpenAI API key
+  baseUrl: 'https://api.signalvault.io',     // SignalVault API URL
+  environment: 'production',
+});
+
+// Use exactly like OpenAI SDK — all calls are logged and guarded
+const response = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+console.log(response.choices[0].message.content);
+```
+
+## Streaming
+
+Streaming responses are fully supported. SignalVault logs the complete response once the stream finishes:
+
+```typescript
+const stream = await client.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Write a poem' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+```
+
+## Mirror Mode
+
+In mirror mode, requests go directly to OpenAI first and SignalVault audits them asynchronously — no latency added, never blocks:
+
+```typescript
+const client = new SignalVaultClient({
+  apiKey: 'sk_live_...',
+  openaiApiKey: process.env.OPENAI_API_KEY!,
+  mirrorMode: true,   // Monitor only, never block
+});
+```
+
+## Features
+
+- **Automatic Logging** — Every request and response is recorded in your SignalVault dashboard
+- **Pre-flight Guardrails** — Block or redact requests before they reach OpenAI
+- **PII Detection** — Automatically detect emails, phone numbers, SSNs in prompts
+- **Secret Detection** — Block API keys and tokens in prompts
+- **Token Limits** — Enforce cost controls per request
+- **Model Allowlists** — Restrict which AI models can be used
+- **Streaming Support** — Full support for streaming completions
+- **Mirror Mode** — Observe without blocking (zero added latency)
+
+## Configuration
+
+```typescript
+const client = new SignalVaultClient({
+  apiKey: 'sk_live_...',          // Your SignalVault API key
+  openaiApiKey: 'sk-...',         // Your OpenAI API key
+  baseUrl: 'https://api.signalvault.io', // SignalVault API URL
+  environment: 'production',      // 'development' | 'staging' | 'production'
+  debug: false,                   // Enable debug logging
+  mirrorMode: false,              // Monitor-only mode
+});
+```
+
+## Error Handling
+
+If a request is blocked by a guardrail, an error will be thrown:
+
+```typescript
+try {
+  const response = await client.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'my SSN is 123-45-6789' }],
+  });
+} catch (error) {
+  if (error.message.includes('[SignalVault]')) {
+    console.log('Request blocked by guardrail');
+  }
+}
+```
+
+## License
+
+MIT

package/dist/__tests__/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/index.test.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+// Minimal unit tests for the SDK (no network calls)
+describe('SignalVaultClient', () => {
+    it('should construct with required config', () => {
+        const client = new index_1.SignalVaultClient({
+            apiKey: 'sk_test_abc',
+            openaiApiKey: 'sk-fake',
+        });
+        expect(client).toBeDefined();
+        expect(client.chat).toBeDefined();
+        expect(client.chat.completions).toBeDefined();
+        expect(typeof client.chat.completions.create).toBe('function');
+    });
+    it('should default to localhost and production', () => {
+        const client = new index_1.SignalVaultClient({
+            apiKey: 'sk_test_abc',
+            openaiApiKey: 'sk-fake',
+        });
+        // Access private fields via bracket notation for testing
+        expect(client.signalvaultBaseUrl).toBe('http://localhost:4000');
+        expect(client.signalvaultEnvironment).toBe('production');
+        expect(client.debugMode).toBe(false);
+        expect(client.mirrorMode).toBe(false);
+    });
+    it('should accept custom baseUrl and environment', () => {
+        const client = new index_1.SignalVaultClient({
+            apiKey: 'sk_test_abc',
+            openaiApiKey: 'sk-fake',
+            baseUrl: 'https://api.signalvault.io/',
+            environment: 'staging',
+            debug: true,
+            mirrorMode: true,
+        });
+        expect(client.signalvaultBaseUrl).toBe('https://api.signalvault.io');
+        expect(client.signalvaultEnvironment).toBe('staging');
+        expect(client.debugMode).toBe(true);
+        expect(client.mirrorMode).toBe(true);
+    });
+    it('should strip trailing slashes from baseUrl', () => {
+        const client = new index_1.SignalVaultClient({
+            apiKey: 'sk_test_abc',
+            openaiApiKey: 'sk-fake',
+            baseUrl: 'https://example.com///',
+        });
+        expect(client.signalvaultBaseUrl).toBe('https://example.com');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import OpenAI from 'openai';
+export interface SignalVaultConfig {
+    apiKey: string;
+    openaiApiKey: string;
+    baseUrl?: string;
+    environment?: 'development' | 'staging' | 'production';
+    debug?: boolean;
+    mirrorMode?: boolean;
+}
+export interface SignalVaultDecision {
+    decision: 'allow' | 'warn' | 'block' | 'redact';
+    violations: Array<{
+        rule_id?: string;
+        type: string;
+        severity: number;
+        action: string;
+        details: Record<string, unknown>;
+    }>;
+    redactions: Array<{
+        start: number;
+        end: number;
+        replacement: string;
+    }>;
+}
+/**
+ * SignalVault Client — wraps OpenAI with guardrails and audit logging.
+ *
+ * @example
+ * ```typescript
+ * const client = new SignalVaultClient({
+ *   apiKey: 'sk_live_...',
+ *   openaiApiKey: process.env.OPENAI_API_KEY!,
+ *   baseUrl: 'https://api.signalvault.io',
+ * });
+ *
+ * // Non-streaming
+ * const res = await client.chat.completions.create({ model: 'gpt-4', messages: [...] });
+ *
+ * // Streaming
+ * const stream = await client.chat.completions.create({ model: 'gpt-4', messages: [...], stream: true });
+ * for await (const chunk of stream) { ... }
+ * ```
+ */
+export declare class SignalVaultClient {
+    private signalvaultApiKey;
+    private signalvaultBaseUrl;
+    private signalvaultEnvironment;
+    private debugMode;
+    private mirrorMode;
+    private openai;
+    constructor(config: SignalVaultConfig);
+    /**
+     * Chat completions with SignalVault guardrails.
+     * Supports both streaming and non-streaming.
+     */
+    get chat(): {
+        completions: {
+            create: (params: OpenAI.Chat.ChatCompletionCreateParams) => Promise<any>;
+        };
+    };
+    private handleMirrorMode;
+    private handleNormalMode;
+    private wrapStreamForAudit;
+    private wrapStreamForPostFlight;
+    private sendRequest;
+    private sendResponse;
+    private sendStreamResponse;
+    private sendAudit;
+    private sendStreamAudit;
+}
+export default SignalVaultClient;

package/dist/index.js

@@ -0,0 +1,335 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignalVaultClient = void 0;
+const openai_1 = __importDefault(require("openai"));
+const uuid_1 = require("uuid");
+/**
+ * SignalVault Client — wraps OpenAI with guardrails and audit logging.
+ *
+ * @example
+ * ```typescript
+ * const client = new SignalVaultClient({
+ *   apiKey: 'sk_live_...',
+ *   openaiApiKey: process.env.OPENAI_API_KEY!,
+ *   baseUrl: 'https://api.signalvault.io',
+ * });
+ *
+ * // Non-streaming
+ * const res = await client.chat.completions.create({ model: 'gpt-4', messages: [...] });
+ *
+ * // Streaming
+ * const stream = await client.chat.completions.create({ model: 'gpt-4', messages: [...], stream: true });
+ * for await (const chunk of stream) { ... }
+ * ```
+ */
+class SignalVaultClient {
+    constructor(config) {
+        this.signalvaultApiKey = config.apiKey;
+        this.signalvaultBaseUrl = (config.baseUrl || 'http://localhost:4000').replace(/\/+$/, '');
+        this.signalvaultEnvironment = config.environment || 'production';
+        this.debugMode = config.debug || false;
+        this.mirrorMode = config.mirrorMode || false;
+        this.openai = new openai_1.default({
+            apiKey: config.openaiApiKey,
+        });
+    }
+    /**
+     * Chat completions with SignalVault guardrails.
+     * Supports both streaming and non-streaming.
+     */
+    get chat() {
+        return {
+            completions: {
+                create: async (params) => {
+                    const requestId = (0, uuid_1.v4)();
+                    if (this.debugMode) {
+                        console.log('[SignalVault] Processing request:', requestId, this.mirrorMode ? '(MIRROR MODE)' : '', params.stream ? '(STREAMING)' : '');
+                    }
+                    // Mirror mode: call OpenAI first, then audit
+                    if (this.mirrorMode) {
+                        return this.handleMirrorMode(requestId, params);
+                    }
+                    // Normal mode: pre-flight checks first
+                    return this.handleNormalMode(requestId, params);
+                },
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Mirror mode — no latency added, audit asynchronously
+    // ---------------------------------------------------------------------------
+    async handleMirrorMode(requestId, params) {
+        try {
+            const response = await this.openai.chat.completions.create(params);
+            if (params.stream) {
+                // Wrap the stream to collect chunks for auditing
+                return this.wrapStreamForAudit(requestId, params, response);
+            }
+            // Non-streaming: audit in background
+            const completion = response;
+            this.sendAudit(requestId, params, completion).catch((err) => {
+                if (this.debugMode) {
+                    console.error('[SignalVault] Audit failed (non-blocking):', err);
+                }
+            });
+            return completion;
+        }
+        catch (error) {
+            if (this.debugMode) {
+                console.error('[SignalVault] OpenAI error:', error);
+            }
+            throw error;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Normal mode — pre-flight guardrails, then OpenAI, then post-flight
+    // ---------------------------------------------------------------------------
+    async handleNormalMode(requestId, params) {
+        try {
+            // Pre-flight check
+            const decision = await this.sendRequest(requestId, params);
+            if (decision.decision === 'block') {
+                throw new Error(`[SignalVault] Request blocked: ${JSON.stringify(decision.violations)}`);
+            }
+            if (decision.decision === 'warn' && this.debugMode) {
+                console.warn('[SignalVault] Warnings:', decision.violations);
+            }
+            const response = await this.openai.chat.completions.create(params);
+            if (params.stream) {
+                // Wrap stream to collect output for post-flight logging
+                return this.wrapStreamForPostFlight(requestId, params, response);
+            }
+            // Non-streaming: post-flight logging
+            const completion = response;
+            await this.sendResponse(requestId, completion, params.model);
+            return completion;
+        }
+        catch (error) {
+            if (this.debugMode) {
+                console.error('[SignalVault] Error:', error);
+            }
+            throw error;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Stream wrappers — collect chunks and send audit/post-flight events
+    // ---------------------------------------------------------------------------
+    async *wrapStreamForAudit(requestId, params, stream) {
+        const chunks = [];
+        let promptTokens = 0;
+        let completionTokens = 0;
+        for await (const chunk of stream) {
+            const content = chunk.choices[0]?.delta?.content || '';
+            if (content)
+                chunks.push(content);
+            // Collect usage if provided in final chunk
+            if (chunk.usage) {
+                promptTokens = chunk.usage.prompt_tokens || 0;
+                completionTokens = chunk.usage.completion_tokens || 0;
+            }
+            yield chunk;
+        }
+        // Send audit after stream completes
+        const fullOutput = chunks.join('');
+        this.sendStreamAudit(requestId, params, fullOutput, promptTokens, completionTokens).catch((err) => {
+            if (this.debugMode) {
+                console.error('[SignalVault] Stream audit failed:', err);
+            }
+        });
+    }
+    async *wrapStreamForPostFlight(requestId, params, stream) {
+        const chunks = [];
+        let promptTokens = 0;
+        let completionTokens = 0;
+        for await (const chunk of stream) {
+            const content = chunk.choices[0]?.delta?.content || '';
+            if (content)
+                chunks.push(content);
+            if (chunk.usage) {
+                promptTokens = chunk.usage.prompt_tokens || 0;
+                completionTokens = chunk.usage.completion_tokens || 0;
+            }
+            yield chunk;
+        }
+        // Post-flight logging
+        const fullOutput = chunks.join('');
+        try {
+            await this.sendStreamResponse(requestId, params.model, fullOutput, promptTokens, completionTokens);
+        }
+        catch (err) {
+            if (this.debugMode) {
+                console.error('[SignalVault] Post-flight logging failed:', err);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // API communication
+    // ---------------------------------------------------------------------------
+    async sendRequest(requestId, params) {
+        const response = await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.signalvaultApiKey}`,
+            },
+            body: JSON.stringify({
+                type: 'ai.request',
+                request_id: requestId,
+                environment: this.signalvaultEnvironment,
+                provider: 'openai',
+                model: params.model,
+                metadata: {},
+                payload: { messages: params.messages },
+            }),
+        });
+        if (!response.ok) {
+            if (this.debugMode) {
+                console.error('[SignalVault] API error:', response.status);
+            }
+            return { decision: 'allow', violations: [], redactions: [] };
+        }
+        return (await response.json());
+    }
+    async sendResponse(requestId, response, model) {
+        try {
+            const output = response.choices[0]?.message?.content || '';
+            await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.signalvaultApiKey}`,
+                },
+                body: JSON.stringify({
+                    type: 'ai.response',
+                    request_id: requestId,
+                    environment: this.signalvaultEnvironment,
+                    provider: 'openai',
+                    model,
+                    metadata: {},
+                    payload: {
+                        output,
+                        usage: {
+                            prompt_tokens: response.usage?.prompt_tokens || 0,
+                            completion_tokens: response.usage?.completion_tokens || 0,
+                        },
+                    },
+                }),
+            });
+        }
+        catch (error) {
+            if (this.debugMode) {
+                console.error('[SignalVault] Failed to send response:', error);
+            }
+        }
+    }
+    async sendStreamResponse(requestId, model, output, promptTokens, completionTokens) {
+        await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.signalvaultApiKey}`,
+            },
+            body: JSON.stringify({
+                type: 'ai.response',
+                request_id: requestId,
+                environment: this.signalvaultEnvironment,
+                provider: 'openai',
+                model,
+                metadata: {},
+                payload: {
+                    output,
+                    usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens },
+                },
+            }),
+        });
+    }
+    async sendAudit(requestId, params, response) {
+        const output = response.choices[0]?.message?.content || '';
+        // Send ai.request event
+        await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.signalvaultApiKey}`,
+            },
+            body: JSON.stringify({
+                type: 'ai.request',
+                request_id: requestId,
+                environment: this.signalvaultEnvironment,
+                provider: 'openai',
+                model: params.model,
+                metadata: {},
+                payload: { messages: params.messages, monitor_mode: true },
+            }),
+        });
+        // Send ai.response event
+        await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.signalvaultApiKey}`,
+            },
+            body: JSON.stringify({
+                type: 'ai.response',
+                request_id: requestId,
+                environment: this.signalvaultEnvironment,
+                provider: 'openai',
+                model: params.model,
+                metadata: {},
+                payload: {
+                    output,
+                    usage: {
+                        prompt_tokens: response.usage?.prompt_tokens || 0,
+                        completion_tokens: response.usage?.completion_tokens || 0,
+                    },
+                    monitor_mode: true,
+                },
+            }),
+        });
+    }
+    async sendStreamAudit(requestId, params, output, promptTokens, completionTokens) {
+        // Send ai.request event
+        await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.signalvaultApiKey}`,
+            },
+            body: JSON.stringify({
+                type: 'ai.request',
+                request_id: requestId,
+                environment: this.signalvaultEnvironment,
+                provider: 'openai',
+                model: params.model,
+                metadata: {},
+                payload: { messages: params.messages, monitor_mode: true },
+            }),
+        });
+        // Send ai.response event
+        await fetch(`${this.signalvaultBaseUrl}/v1/events`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.signalvaultApiKey}`,
+            },
+            body: JSON.stringify({
+                type: 'ai.response',
+                request_id: requestId,
+                environment: this.signalvaultEnvironment,
+                provider: 'openai',
+                model: params.model,
+                metadata: {},
+                payload: {
+                    output,
+                    usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens },
+                    monitor_mode: true,
+                },
+            }),
+        });
+    }
+}
+exports.SignalVaultClient = SignalVaultClient;
+exports.default = SignalVaultClient;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@signalvaultio/node",
+  "version": "0.1.0",
+  "description": "SignalVault SDK - AI audit logs and guardrails for safe production AI",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "jest --passWithNoTests"
+  },
+  "keywords": [
+    "ai",
+    "audit",
+    "guardrails",
+    "openai",
+    "llm",
+    "compliance",
+    "security",
+    "monitoring"
+  ],
+  "author": "SignalVault <support@signalvault.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/signalvaultio/signalvault-node"
+  },
+  "bugs": {
+    "url": "https://github.com/signalvaultio/signalvault-node/issues"
+  },
+  "homepage": "https://signalvault.io/docs",
+  "peerDependencies": {
+    "openai": "^4.0.0"
+  },
+  "dependencies": {
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "@types/uuid": "^9.0.0",
+    "jest": "^30.2.0",
+    "openai": "^4.0.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.0.0"
+  }
+}