node-ai-guard 1.0.0

package/README.md

@@ -0,0 +1,92 @@
+# 🛡️ node-ai-guard
+
+**The safety layer for AI Agents. Validate, sanitize, and govern AI-generated intents before they hit your production APIs.**
+
+[![npm version](https://img.shields.io/npm/v/node-ai-guard.svg)](https://www.npmjs.com/package/node-ai-guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+### **The Problem: AI Hallucinations & Excessive Agency**
+Large Language Models (LLMs) are great at calling tools, but they are unpredictable. When you give an AI Agent access to your APIs (Stripe, Slack, Database), you face critical risks:
+1. **Hallucinations:** The AI sends parameters that don't exist or are formatted incorrectly.
+2. **Excessive Agency:** The AI tries to refund $10,000 instead of $10 because it misread the prompt.
+3. **Security Risks:** A user tricks your AI into executing destructive commands via prompt injection.
+
+`node-ai-guard` provides a **Zod-powered guardrail wrapper** designed specifically for AI-generated JSON payloads. It ensures every action is structurally sound and follows strict business safety rules.
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install node-ai-guard zod
+```
+
+---
+
+## 🛠️ Quick Start
+
+Define a **Guard** with a schema and custom safety rules. If the AI violates a rule, the guard returns a clear error that you can feed back to the AI for self-correction.
+
+```typescript
+import { createGuard } from 'node-ai-guard';
+import { z } from 'zod';
+
+// 1. Define your safety guard
+const refundGuard = createGuard({
+  name: "process_refund",
+  description: "Used to issue a refund to a customer.",
+  schema: z.object({
+    orderId: z.string(),
+    amount: z.number(),
+    reason: z.string()
+  }),
+  // Hard safety rules the AI cannot bypass
+  rules: [
+    {
+      check: (data) => data.amount <= 100,
+      message: "Refunds over $100 require manual manager intervention."
+    }
+  ]
+});
+
+// 2. Validate the AI's intent (e.g., from an LLM tool call)
+const aiIntent = { orderId: "ORD-99", amount: 500, reason: "Defective" };
+
+const result = await refundGuard.validate(aiIntent);
+
+if (!result.success) {
+  console.log("🚫 Action Blocked:", result.error); 
+  // Output: "Refunds over $100 require manual manager intervention."
+}
+```
+
+---
+
+## ✨ Key Features
+
+* ✅ **Type-Safe Validation:** Full TypeScript support with [Zod](https://zod.dev/) integration.
+* 🛡️ **Business Rule Engine:** Go beyond data types. Set custom logic for risk scores and safety limits.
+* 🤖 **AI Self-Correction:** Returns detailed error messages designed to help LLMs realize their mistake and retry.
+* 📦 **Lightweight & Fast:** Zero bloat, optimized for high-throughput Node.js environments like Express or AWS Lambda.
+* 📜 **Audit Trail Ready:** Easily logs attempts to MongoDB or PostgreSQL for compliance and debugging.
+
+---
+
+## 🗺️ Roadmap (Phase 1 & 2)
+
+- [x] Core Zod Wrapper
+- [x] Custom Safety Rules Engine
+- [ ] **Middleware Support:** First-class support for Express.js and Fastify.
+- [ ] **Human-in-the-Loop:** Built-in hooks for Slack/Discord "Approve/Deny" buttons.
+- [ ] **Tool Definition Generator:** Automatically export OpenAI-compatible JSON tool definitions from your guards.
+
+---
+
+## 🤝 Contributing
+
+This is an early-stage project built to solve AI trust issues. If you have ideas for safety patterns (Human-in-the-loop, rate limiting for agents, etc.), feel free to open an issue!
+
+## 📄 License
+
+MIT © [josephallwin1996]

package/dist/index.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AIGuard: () => AIGuard,
+  createGuard: () => createGuard
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("zod");
+var AIGuard = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async validate(input) {
+    const result = await this.config.schema.safeParseAsync(input);
+    if (!result.success) {
+      return { success: false, error: result.error.format() };
+    }
+    if (this.config.maxLimit && result.data.amount > this.config.maxLimit) {
+      return { success: false, error: "Safety limit exceeded!" };
+    }
+    return { success: true, data: result.data };
+  }
+};
+function createGuard(config) {
+  return new AIGuard(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AIGuard,
+  createGuard
+});

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+interface GuardConfig<T extends z.ZodRawShape> {
+    name: string;
+    schema: z.ZodObject<T>;
+    maxLimit?: number;
+}
+declare class AIGuard<T extends z.ZodRawShape> {
+    private config;
+    constructor(config: GuardConfig<T>);
+    validate(input: unknown): Promise<{
+        success: boolean;
+        error: z.core.$ZodFormattedError<z.core.$InferObjectOutput<T, {}>, string>;
+        data?: never;
+    } | {
+        success: boolean;
+        error: string;
+        data?: never;
+    } | {
+        success: boolean;
+        data: z.core.$InferObjectOutput<T, {}>;
+        error?: never;
+    }>;
+}
+declare function createGuard<T extends z.ZodRawShape>(config: GuardConfig<T>): AIGuard<T>;
+
+export { AIGuard, type GuardConfig, createGuard };

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+interface GuardConfig<T extends z.ZodRawShape> {
+    name: string;
+    schema: z.ZodObject<T>;
+    maxLimit?: number;
+}
+declare class AIGuard<T extends z.ZodRawShape> {
+    private config;
+    constructor(config: GuardConfig<T>);
+    validate(input: unknown): Promise<{
+        success: boolean;
+        error: z.core.$ZodFormattedError<z.core.$InferObjectOutput<T, {}>, string>;
+        data?: never;
+    } | {
+        success: boolean;
+        error: string;
+        data?: never;
+    } | {
+        success: boolean;
+        data: z.core.$InferObjectOutput<T, {}>;
+        error?: never;
+    }>;
+}
+declare function createGuard<T extends z.ZodRawShape>(config: GuardConfig<T>): AIGuard<T>;
+
+export { AIGuard, type GuardConfig, createGuard };

package/dist/index.js

@@ -0,0 +1,24 @@
+// src/index.ts
+import "zod";
+var AIGuard = class {
+  constructor(config) {
+    this.config = config;
+  }
+  async validate(input) {
+    const result = await this.config.schema.safeParseAsync(input);
+    if (!result.success) {
+      return { success: false, error: result.error.format() };
+    }
+    if (this.config.maxLimit && result.data.amount > this.config.maxLimit) {
+      return { success: false, error: "Safety limit exceeded!" };
+    }
+    return { success: true, data: result.data };
+  }
+};
+function createGuard(config) {
+  return new AIGuard(config);
+}
+export {
+  AIGuard,
+  createGuard
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "node-ai-guard",
+  "version": "1.0.0",
+  "description": "A lightweight TypeScript/Node.js safety layer for AI Agents. Secure your APIs against LLM hallucinations and excessive agency using Zod-powered guardrails",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "lint": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/josephallwin1996/node-ai-guard.git"
+  },
+  "keywords": ["ai", "agents", "security", "guardrails", "zod"],
+  "author": "Joseph Allwin",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/josephallwin1996/node-ai-guard/issues"
+  },
+  "homepage": "https://github.com/josephallwin1996/node-ai-guard#readme",
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}