@sandrobuilds/tracerney 0.9.9 → 0.9.11

package/README.md

@@ -5,13 +5,13 @@
 [![npm version](https://badge.fury.io/js/tracerney.svg)](https://www.npmjs.com/package/tracerney)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Tracerney is a production-ready security middleware that sits between your application and LLM providers. It detects and blocks prompt injection attacks with **three hardened layers**:
+Tracerney is a lightweight, free SDK for detecting prompt injection attacks. It runs 100% locally with no dependencies and no data collection.
 
-1. **Layer 1 (Vanguard)**: Regex patterns with Unicode normalization — <2ms, blocks known attacks
-2. **Layer 2 (Sentinel)**: Backend LLM verification for novel attacks, with rate limiting to prevent cost spikes
-3. **Layer 3 (Jitter)**: Random response delays to mask which layer blocked an attack
-
-**Zero data leaves your infrastructure** — you control the backend endpoints.
+**Free SDK includes:**
+- **Layer 1 (Pattern Detection)**: 238 embedded attack patterns with Unicode normalization
+- <2ms detection latency per prompt
+- Zero network overhead — all detection is local
+- Works offline — no backend required
 
 ## 🚀 Quick Start
 
@@ -20,18 +20,41 @@ Tracerney is a production-ready security middleware that sits between your appli
 npm install @sandrobuilds/tracerney
 ```
 
-**Setup (30 seconds) — RECOMMENDED approach:**
+**Simplest Setup (Free SDK — Pattern Detection):**
+```typescript
+import { Tracerney } from '@sandrobuilds/tracerney';
+
+const tracer = new Tracerney({
+  allowedTools: ['search', 'calculator'],
+});
+
+// Check if a prompt is suspicious
+const result = await tracer.scanPrompt(userInput);
+
+console.log(result);
+// {
+//   suspicious: true,          // Layer 1 detected pattern match
+//   patternName: "Ignore Instructions",
+//   severity: "CRITICAL",
+//   blocked: false             // No backend verification yet
+// }
+
+if (result.suspicious) {
+  console.log(`⚠️  Suspicious: ${result.patternName}`);
+  // Handle the suspicious prompt (log, rate-limit, etc.)
+}
+```
+
+**Advanced Setup (with Backend LLM Verification):**
 ```typescript
 import { Tracerney, ShieldBlockError } from '@sandrobuilds/tracerney';
 
-// Just provide your domain URL — paths are auto-constructed!
 const shield = new Tracerney({
-  baseUrl: 'http://localhost:3000',        // Automatically creates all endpoints
+  baseUrl: 'http://localhost:3000',        // Backend with LLM Sentinel
   allowedTools: ['search', 'calculator'],
   apiKey: process.env.TRACERNY_API_KEY,
 });
 
-// Wrap your LLM call (detects at Layer 1 + Layer 2)
 try {
   const response = await shield.wrap(() =>
     openai.chat.completions.create({
@@ -43,13 +66,12 @@ try {
 } catch (error) {
   if (error instanceof ShieldBlockError) {
     console.error('🛡️ Attack blocked:', error.event.blockReason);
-    // Layer 1 hit: error.event.metadata.patternName
-    // Layer 2 hit: "LLM Sentinel" detected novel attack
+    // Only throws if LLM Sentinel confirms attack
   }
 }
 ```
 
-That's it! Your LLM is now protected.
+Start with the simple setup. Add backend verification when ready!
 
 ## Philosophy
 
@@ -304,17 +326,34 @@ try {
 
 ### Scanning Prompts Pre-LLM
 
-For defense-in-depth, scan prompts before calling the LLM:
+Check if a prompt is suspicious before calling the LLM:
 
 ```typescript
-try {
-  shield.scanPrompt(userInput);
-  // Safe to proceed
-} catch (err) {
-  if (err instanceof ShieldBlockError) {
-    console.error('Blocked at edge:', err.event);
+const result = await shield.scanPrompt(userInput);
+
+if (result.suspicious) {
+  console.log(`⚠️  Suspicious: ${result.patternName}`);
+  console.log(`Severity: ${result.severity}`);
+  // Log, rate-limit, or notify security team
+
+  if (result.blocked) {
+    // Only true if LLM Sentinel confirmed (requires backend)
+    return res.status(403).json({ error: 'Request blocked' });
   }
 }
+
+// Safe to call LLM
+const response = await openai.chat.completions.create({...});
+```
+
+**Result object:**
+```typescript
+interface ScanResult {
+  suspicious: boolean;    // Layer 1 detected pattern match
+  patternName?: string;   // e.g., "Ignore Instructions"
+  severity?: string;      // "low" | "medium" | "high" | "critical"
+  blocked: boolean;       // true only if LLM Sentinel confirmed (requires backend)
+}
 ```
 
 ### Updating Allowed Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrobuilds/tracerney",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "Transparent proxy runtime sentinel for prompt injection defense",
   "type": "module",
   "main": "dist/index.js",