@vinhnt-sdk/guardrails 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nguyen Thanh Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @vinhnt-sdk/guardrails
+
+> Version: 0.4.0 | Status: BETA
+
+Guardrail tripwires for agent inputs/outputs — pattern-based safety checks.
+
+## Install
+
+```bash
+# npm
+npm install @vinhnt-sdk/guardrails
+
+# pnpm (monorepo)
+pnpm add @vinhnt-sdk/guardrails
+```
+
+## Quick Start
+
+```typescript
+import { runGuardrails, maxLengthGuardrail, blocklistGuardrail } from '@vinhnt-sdk/guardrails';
+
+const guardrails = [
+  maxLengthGuardrail(10000),
+  blocklistGuardrail([/ignore previous instructions/gi]),
+];
+
+const result = await runGuardrails(guardrails, {
+  direction: 'input',
+  content: 'user input here',
+  toolName: 'chat',
+});
+
+if (result.decision === 'deny') {
+  throw new Error(`Blocked: ${result.reason}`);
+}
+```
+
+## Exports
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `Guardrail` | Guardrail interface |
+| `GuardrailContext` | Context passed to guardrails |
+| `GuardrailResult` | Result of a guardrail check |
+| `GuardrailScope` | When the check runs (`input` / `output` / `both`) |
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `runGuardrails(guardrails, ctx)` | Run guardrails in priority order with monotonic semantics |
+| `maxLengthGuardrail(maxChars)` | Maximum input length guardrail |
+| `blocklistGuardrail(patterns)` | Blocklist pattern guardrail |
+| `secretDetectionGuardrail(redactor)` | Secret detection guardrail |
+
+## Dependencies
+
+- `@vinhnt-sdk/schema`
+- `@vinhnt-sdk/guard`

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Guardrail tripwires for agent inputs/outputs.
+ *
+ * Inspired by OpenAI Agents SDK guardrail pattern.
+ * Pattern-based safety checks that run before/after tool execution.
+ *
+ * @module guardrails
+ * @packageDocumentation
+ */
+import type { GuardDecision } from "@vinhnt-sdk/guard";
+/** Guardrail scope - when the check runs */
+export type GuardrailScope = "input" | "output" | "both";
+/** Priority order - lower runs first */
+export type GuardrailPriority = number;
+/** A guardrail tripwire that checks inputs/outputs */
+export interface Guardrail {
+    readonly name: string;
+    readonly scope: GuardrailScope;
+    readonly priority: GuardrailPriority;
+    check: (ctx: GuardrailContext) => Promise<GuardrailResult>;
+}
+/** Context passed to guardrails */
+export interface GuardrailContext {
+    readonly direction: "input" | "output";
+    readonly toolName?: string;
+    readonly content: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Result of a guardrail check */
+export interface GuardrailResult {
+    readonly passed: boolean;
+    readonly decision: GuardDecision;
+    readonly reason?: string;
+    /** Optional modified content (e.g., redacted) */
+    readonly modifiedContent?: unknown;
+}
+/** Maximum input length guardrail */
+export declare function maxLengthGuardrail(maxChars: number, source?: string): Guardrail;
+/** Blocklist pattern guardrail - blocks content matching patterns */
+export declare function blocklistGuardrail(patterns: RegExp[], name?: string): Guardrail;
+/** Secret detection guardrail - redacts detected secrets */
+export declare function secretDetectionGuardrail(redactor: {
+    redact: (text: string) => string;
+}): Guardrail;
+/**
+ * Run guardrails in priority order with monotonic semantics.
+ * Once a guardrail denies, subsequent guardrails cannot override.
+ */
+export declare function runGuardrails(guardrails: Guardrail[], ctx: GuardrailContext): Promise<GuardrailResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAMvD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAEvC,sDAAsD;AACtD,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,KAAK,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5D;AAED,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAMD,qCAAqC;AACrC,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAY,GAAG,SAAS,CAiBlF;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,SAAc,GAAG,SAAS,CAoBpF;AAED,4DAA4D;AAC5D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE;IAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,GAAG,SAAS,CAmBlG;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,SAAS,EAAE,EACvB,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,eAAe,CAAC,CA+B1B"}

package/dist/index.js

@@ -0,0 +1,108 @@
+/**
+ * Guardrail tripwires for agent inputs/outputs.
+ *
+ * Inspired by OpenAI Agents SDK guardrail pattern.
+ * Pattern-based safety checks that run before/after tool execution.
+ *
+ * @module guardrails
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Built-in Guardrails
+// ---------------------------------------------------------------------------
+/** Maximum input length guardrail */
+export function maxLengthGuardrail(maxChars, source = "unknown") {
+    return {
+        name: "max-length",
+        scope: "input",
+        priority: 10,
+        check: async (ctx) => {
+            const text = typeof ctx.content === "string" ? ctx.content : JSON.stringify(ctx.content);
+            if (text.length > maxChars) {
+                return {
+                    passed: false,
+                    decision: "deny",
+                    reason: `${source}: input exceeds ${maxChars} chars (got ${text.length})`,
+                };
+            }
+            return { passed: true, decision: "allow" };
+        },
+    };
+}
+/** Blocklist pattern guardrail - blocks content matching patterns */
+export function blocklistGuardrail(patterns, name = "blocklist") {
+    return {
+        name,
+        scope: "both",
+        priority: 20,
+        check: async (ctx) => {
+            const text = typeof ctx.content === "string" ? ctx.content : JSON.stringify(ctx.content);
+            for (const pattern of patterns) {
+                pattern.lastIndex = 0;
+                if (pattern.test(text)) {
+                    return {
+                        passed: false,
+                        decision: "deny",
+                        reason: `${name}: blocked pattern matched`,
+                    };
+                }
+            }
+            return { passed: true, decision: "allow" };
+        },
+    };
+}
+/** Secret detection guardrail - redacts detected secrets */
+export function secretDetectionGuardrail(redactor) {
+    return {
+        name: "secret-detection",
+        scope: "output",
+        priority: 30,
+        check: async (ctx) => {
+            const text = typeof ctx.content === "string" ? ctx.content : JSON.stringify(ctx.content);
+            const redacted = redactor.redact(text);
+            if (redacted !== text) {
+                return {
+                    passed: true,
+                    decision: "allow",
+                    reason: "secrets detected and redacted",
+                    modifiedContent: redacted,
+                };
+            }
+            return { passed: true, decision: "allow" };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Guardrail Runner
+// ---------------------------------------------------------------------------
+/**
+ * Run guardrails in priority order with monotonic semantics.
+ * Once a guardrail denies, subsequent guardrails cannot override.
+ */
+export async function runGuardrails(guardrails, ctx) {
+    const sorted = [...guardrails]
+        .filter((g) => g.scope === "both" || g.scope === ctx.direction)
+        .sort((a, b) => a.priority - b.priority);
+    let current = { passed: true, decision: "allow" };
+    for (const guardrail of sorted) {
+        // Monotonic: once denied, stop
+        if (current.decision === "deny")
+            break;
+        const result = await guardrail.check(ctx);
+        // Deny takes precedence
+        if (result.decision === "deny") {
+            current = result;
+            break;
+        }
+        // Escalate if not already denied
+        if (result.decision === "escalate" && current.decision === "allow") {
+            current = result;
+        }
+        // Carry forward modified content
+        if (result.modifiedContent !== undefined) {
+            current = { ...current, modifiedContent: result.modifiedContent };
+        }
+    }
+    return current;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vinhnt-sdk/guardrails",
+  "version": "0.4.0",
+  "description": "Guardrail tripwires for agent inputs/outputs - pattern-based safety",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vinhnt-develop/vinhnt-sdk.git",
+    "directory": "packages/guardrails"
+  },
+  "homepage": "https://github.com/vinhnt-develop/vinhnt-sdk/tree/main/packages/guardrails",
+  "bugs": {
+    "url": "https://github.com/vinhnt-develop/vinhnt-sdk/issues"
+  },
+  "keywords": [
+    "vnt",
+    "guardrails",
+    "safety",
+    "input-validation",
+    "output-validation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vinhnt-sdk/guard": "0.4.0",
+    "@vinhnt-sdk/schema": "0.4.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}