llm-trust-guard 4.0.0 → 4.0.2

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to `llm-trust-guard` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [4.0.2] - 2025-02-16
+
+### Fixed
+- Fixed broken links in README.md for npm display
+- Added CONTRIBUTING.md, SECURITY.md, CHANGELOG.md to package files
+
+## [4.0.0] - 2025-02-15
+
+### Added
+
+#### New Guards
+- **AutonomyEscalationGuard (L21)** - Prevention of unauthorized autonomy escalation (ASI10)
+- **StatePersistenceGuard (L22)** - State corruption and persistence attack prevention (ASI08)
+- **TrustExploitationGuard (L20)** - Protection against human-agent trust exploitation (ASI09)
+- **PromptLeakageGuard (L19)** - System prompt leakage prevention
+- **MCPSecurityGuard (L18)** - MCP tool shadowing and supply chain attack prevention
+- **DriftDetector (L17)** - Behavioral drift detection for agentic systems
+- **CircuitBreaker (L16)** - Cascading failure prevention with automatic recovery
+- **AgentCommunicationGuard (L15)** - Multi-agent communication security
+- **CodeExecutionGuard (L14)** - Safe code execution sandboxing
+
+#### Enhanced Guards
+- **InputSanitizer (L1)** - Added 40+ PAP (Persuasive Adversarial Prompts) detection patterns
+  - Authority appeals detection
+  - Scarcity/urgency tactics
+  - Social proof manipulation
+  - Emotional manipulation
+  - Compound attack detection
+- **EncodingDetector (L10)** - Added ROT13, Octal, Base32, enhanced Unicode detection
+  - Bidirectional text control character detection
+  - Tag character hiding detection
+  - Homoglyph detection
+  - Zero-width character detection
+- **MemoryGuard (L12)** - Added 25 injection patterns, Unicode obfuscation detection
+  - Goal hijacking detection
+  - Jailbreak persistence detection
+  - Cross-session contamination prevention
+- **ToolChainValidator (L9)** - Enhanced with ASI07/ASI04 compliance
+
+#### Testing
+- Added Vitest testing framework with 190+ tests
+- Coverage configuration targeting 80%+
+
+### Changed
+- Updated threat patterns for OWASP Top 10 for LLMs 2025 compliance
+- Updated patterns for OWASP Agentic AI 2026 compliance
+- Improved detection rates across all guards
+
+### Security
+- All guards now detect Unicode-based obfuscation attacks
+- Enhanced protection against trojan source attacks (bidi controls)
+- Improved MCP security with tool verification
+
+## [3.0.0] - 2024-12-01
+
+### Added
+- **RAGGuard (L13)** - RAG poisoning and embedding attack prevention
+- **MultiModalGuard (L11)** - Multi-modal content security
+- **MemoryGuard (L12)** - Memory persistence attack prevention
+- Initial PAP detection in InputSanitizer
+
+### Changed
+- Restructured guard layers for better modularity
+- Improved TypeScript type definitions
+
+## [2.0.0] - 2024-09-15
+
+### Added
+- **ConversationGuard (L8)** - Multi-turn conversation security
+- **OutputFilter (L7)** - Response filtering and sanitization
+- **ExecutionMonitor (L6)** - Runtime execution monitoring
+- **SchemaValidator (L5)** - Input/output schema validation
+
+### Changed
+- Refactored core architecture
+- Improved performance for high-throughput scenarios
+
+## [1.0.0] - 2024-06-01
+
+### Added
+- Initial release
+- **InputSanitizer (L1)** - Prompt injection detection
+- **ToolRegistry (L2)** - Tool access control
+- **PolicyGate (L3)** - RBAC policy enforcement
+- **TenantBoundary (L4)** - Multi-tenant isolation
+- **EncodingDetector (L10)** - Encoding bypass detection
+- **ToolChainValidator (L9)** - Tool chain validation
+
+## Migration Guides
+
+### Migrating from 3.x to 4.x
+
+1. **New Guards**: Consider adding the new guards (L14-L20) to your security pipeline
+2. **EncodingDetector**: New detection types are enabled by default - review `detectROT13`, `detectOctal`, `detectBase32` settings
+3. **MemoryGuard**: New Unicode detection may flag previously allowed content
+4. **InputSanitizer**: PAP detection is now enabled by default with `detectPAP: true`
+
+### Migrating from 2.x to 3.x
+
+1. **RAGGuard**: If using RAG, add RAGGuard to your pipeline
+2. **MultiModalGuard**: Required for applications processing images/audio
+3. **Type Changes**: Some interfaces have been updated - check TypeScript errors
+
+### Migrating from 1.x to 2.x
+
+1. **Layer Restructuring**: Guard layer numbers have changed
+2. **New Dependencies**: Update your imports to use new guard classes
+3. **Configuration**: Some config options have been renamed for consistency

package/CONTRIBUTING.md

@@ -0,0 +1,269 @@
+# Contributing to llm-trust-guard
+
+Thank you for your interest in contributing to `llm-trust-guard`! This document provides guidelines for contributing to the project.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. **Check existing issues** first to avoid duplicates
+2. **Use the bug report template** when creating issues
+3. Include:
+   - Clear description of the issue
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment details (Node.js version, OS, etc.)
+   - Minimal code example if possible
+
+### Suggesting Features
+
+1. **Check existing feature requests** first
+2. **Describe the use case** - why is this needed?
+3. Consider:
+   - Which OWASP threat does it address?
+   - How does it fit with existing guards?
+   - Performance implications
+
+### Submitting Code
+
+#### Setup
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/YOUR_USERNAME/llm-trust-guard.git
+cd llm-trust-guard
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+```
+
+#### Development Workflow
+
+1. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+2. **Make your changes** following the coding standards below
+
+3. **Write tests** for new functionality:
+   ```bash
+   # Run tests
+   npm test
+
+   # Run tests with coverage
+   npm run test:coverage
+   ```
+
+4. **Ensure all tests pass** and coverage meets requirements (80%+)
+
+5. **Commit your changes** with clear messages:
+   ```bash
+   git commit -m "feat: add ROT13 detection to EncodingDetector"
+   # or
+   git commit -m "fix: correct false positive in PAP detection"
+   ```
+
+6. **Push and create a Pull Request**
+
+#### Commit Message Format
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `test:` - Test additions or modifications
+- `refactor:` - Code refactoring
+- `perf:` - Performance improvements
+- `chore:` - Maintenance tasks
+
+Examples:
+```
+feat: add Base32 encoding detection
+fix: improve Unicode escape sequence handling
+docs: update README with new guard examples
+test: add tests for MemoryGuard context validation
+```
+
+### Coding Standards
+
+#### TypeScript
+
+- Use TypeScript strict mode
+- Export interfaces for public APIs
+- Document public methods with JSDoc comments
+- Use meaningful variable and function names
+
+```typescript
+/**
+ * Detects encoding-based bypass attempts in input
+ * @param input - The input string to analyze
+ * @param requestId - Optional request ID for logging
+ * @returns Detection result with analysis details
+ */
+detect(input: string, requestId?: string): EncodingDetectorResult {
+  // Implementation
+}
+```
+
+#### Testing
+
+- Write tests for all new functionality
+- Use descriptive test names
+- Group related tests with `describe` blocks
+- Test edge cases and error conditions
+
+```typescript
+describe("EncodingDetector", () => {
+  describe("Base64 Detection", () => {
+    it("should detect Base64 encoded threats", () => {
+      // Test implementation
+    });
+
+    it("should handle invalid Base64 gracefully", () => {
+      // Test implementation
+    });
+  });
+});
+```
+
+#### Pattern Guidelines
+
+When adding new detection patterns:
+
+1. **Document the threat** - Reference OWASP or research papers
+2. **Set appropriate weights** - Consider false positive risk
+3. **Test thoroughly** - Include both positive and negative cases
+4. **Consider performance** - Avoid expensive regex operations
+
+```typescript
+// Good: Clear, documented pattern
+{
+  pattern: /ignore\s+(all\s+)?(previous|prior)/i,
+  weight: 0.9,
+  name: "ignore_instructions",
+  // Addresses: LLM01:2025 Prompt Injection
+}
+
+// Avoid: Overly broad patterns
+{
+  pattern: /.*ignore.*/i,  // Too broad, high false positive risk
+  weight: 0.5,
+  name: "vague_ignore"
+}
+```
+
+### Adding New Guards
+
+1. **Create the guard file** in `src/guards/`:
+   ```
+   src/guards/your-new-guard.ts
+   ```
+
+2. **Follow the existing pattern**:
+   ```typescript
+   export interface YourNewGuardConfig {
+     // Configuration options
+   }
+
+   export interface YourNewGuardResult {
+     allowed: boolean;
+     reason?: string;
+     violations: string[];
+     // Additional analysis
+   }
+
+   export class YourNewGuard {
+     constructor(config: YourNewGuardConfig = {}) {
+       // Initialize
+     }
+
+     check(input: SomeType): YourNewGuardResult {
+       // Implementation
+     }
+   }
+   ```
+
+3. **Export from index.ts**:
+   ```typescript
+   export { YourNewGuard } from "./guards/your-new-guard";
+   ```
+
+4. **Add comprehensive tests** in `tests/your-new-guard.test.ts`
+
+5. **Update documentation**:
+   - Add to README.md
+   - Add to CHANGELOG.md
+   - Create usage examples
+
+### Pull Request Guidelines
+
+- **Title**: Clear, descriptive title following commit format
+- **Description**: Explain what changes and why
+- **Tests**: Include new tests for new functionality
+- **Documentation**: Update relevant docs
+- **Breaking Changes**: Clearly note any breaking changes
+
+#### PR Checklist
+
+- [ ] Tests pass (`npm test`)
+- [ ] Code follows style guidelines
+- [ ] Documentation updated
+- [ ] CHANGELOG.md updated (for features/fixes)
+- [ ] No console.log statements (except for intentional logging)
+- [ ] Types are properly defined
+
+### Review Process
+
+1. PRs require at least one approving review
+2. All CI checks must pass
+3. Address all review comments
+4. Squash commits before merging (if requested)
+
+## Project Structure
+
+```
+llm-trust-guard/
+├── src/
+│   ├── guards/           # Guard implementations
+│   │   ├── input-sanitizer.ts
+│   │   ├── encoding-detector.ts
+│   │   └── ...
+│   ├── types.ts          # Shared type definitions
+│   └── index.ts          # Public exports
+├── tests/                # Test files
+│   ├── input-sanitizer.test.ts
+│   └── ...
+├── dist/                 # Compiled output
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+## Getting Help
+
+- **Questions**: Open a GitHub Discussion
+- **Bugs**: Open a GitHub Issue
+- **Security**: See SECURITY.md
+
+## Recognition
+
+Contributors will be recognized in:
+- Release notes
+- README.md (for significant contributions)
+- GitHub contributors list
+
+Thank you for contributing to making AI applications more secure!

package/README.md

@@ -1,6 +1,6 @@
-# @nandakishoreleburu89/llm-trust-guard
+# llm-trust-guard
 
-[![npm version](https://img.shields.io/npm/v/@nandakishoreleburu89/llm-trust-guard.svg)](https://www.npmjs.com/package/@nandakishoreleburu89/llm-trust-guard)
+[![npm version](https://img.shields.io/npm/v/llm-trust-guard.svg)](https://www.npmjs.com/package/llm-trust-guard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Comprehensive security guards for LLM-powered and agentic AI applications. Implements 20+ protection layers covering **OWASP Top 10 for LLMs 2025**, **OWASP Agentic AI 2026**, and **MCP Security**.
@@ -21,13 +21,13 @@ Comprehensive security guards for LLM-powered and agentic AI applications. Imple
 ### Installation
 
 ```bash
-npm install @nandakishoreleburu89/llm-trust-guard
+npm install llm-trust-guard
 ```
 
 ### Basic Usage
 
 ```typescript
-import { InputSanitizer, EncodingDetector, MemoryGuard } from '@nandakishoreleburu89/llm-trust-guard';
+import { InputSanitizer, EncodingDetector, MemoryGuard } from 'llm-trust-guard';
 
 // Initialize guards
 const sanitizer = new InputSanitizer();
@@ -58,7 +58,7 @@ console.log('Safe input:', sanitizeResult.sanitizedInput);
 ### Using TrustGuard Facade
 
 ```typescript
-import { TrustGuard } from '@nandakishoreleburu89/llm-trust-guard';
+import { TrustGuard } from 'llm-trust-guard';
 
 const guard = new TrustGuard({
   sanitizer: { enabled: true, threshold: 0.3 },
@@ -86,7 +86,7 @@ if (!result.allowed) {
 
 ```typescript
 import express from 'express';
-import { createTrustGuardMiddleware } from '@nandakishoreleburu89/llm-trust-guard';
+import { createTrustGuardMiddleware } from 'llm-trust-guard';
 
 const app = express();
 app.use(express.json());
@@ -108,7 +108,7 @@ app.post('/api/chat', (req, res) => {
 ### LangChain Integration
 
 ```typescript
-import { TrustGuardLangChain } from '@nandakishoreleburu89/llm-trust-guard';
+import { TrustGuardLangChain } from 'llm-trust-guard';
 
 const guard = new TrustGuardLangChain({
   validateInput: true,
@@ -131,7 +131,7 @@ const { allowed, message } = processor.processUserMessage(userInput);
 
 ```typescript
 import OpenAI from 'openai';
-import { SecureOpenAI, wrapOpenAIClient } from '@nandakishoreleburu89/llm-trust-guard';
+import { SecureOpenAI, wrapOpenAIClient } from 'llm-trust-guard';
 
 const openai = new OpenAI();
 
@@ -224,7 +224,7 @@ const secureOpenAI = wrapOpenAIClient(openai, {
 ### InputSanitizer
 
 ```typescript
-import { InputSanitizer } from '@nandakishoreleburu89/llm-trust-guard';
+import { InputSanitizer } from 'llm-trust-guard';
 
 const sanitizer = new InputSanitizer({
   threshold: 0.3,
@@ -243,7 +243,7 @@ const result = sanitizer.sanitize("Ignore all previous instructions");
 ### EncodingDetector
 
 ```typescript
-import { EncodingDetector } from '@nandakishoreleburu89/llm-trust-guard';
+import { EncodingDetector } from 'llm-trust-guard';
 
 const detector = new EncodingDetector({
   detectBase64: true,
@@ -262,7 +262,7 @@ const result = detector.detect("aWdub3JlIGFsbA=="); // Base64 encoded
 ### MemoryGuard
 
 ```typescript
-import { MemoryGuard } from '@nandakishoreleburu89/llm-trust-guard';
+import { MemoryGuard } from 'llm-trust-guard';
 
 const guard = new MemoryGuard({
   enableIntegrityCheck: true,
@@ -297,22 +297,21 @@ LLMs cannot be trusted to enforce security. All security decisions happen in the
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See `CONTRIBUTING.md` in the installed package for guidelines.
 
 ## Security
 
-See [SECURITY.md](SECURITY.md) for security policy and reporting vulnerabilities.
+See `SECURITY.md` in the installed package for security policy and reporting vulnerabilities.
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for version history.
+See `CHANGELOG.md` in the installed package for version history.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License - see `LICENSE` in the installed package for details.
 
 ## Links
 
-- [npm Package](https://www.npmjs.com/package/llm-trust-guard)
 - [OWASP Top 10 for LLMs](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
 - [OWASP Agentic AI](https://owasp.org/www-project-agentic-ai/)

package/SECURITY.md

@@ -0,0 +1,144 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 4.x     | :white_check_mark: |
+| 3.x     | :white_check_mark: |
+| 2.x     | :x:                |
+| 1.x     | :x:                |
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security issue in `llm-trust-guard`, please report it responsibly.
+
+### How to Report
+
+1. **DO NOT** create a public GitHub issue for security vulnerabilities
+2. Email security concerns to: [security@example.com] (replace with actual contact)
+3. Include the following information:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+### What to Expect
+
+- **Acknowledgment**: Within 48 hours
+- **Initial Assessment**: Within 7 days
+- **Resolution Timeline**: Depends on severity
+  - Critical: 24-72 hours
+  - High: 1-2 weeks
+  - Medium: 2-4 weeks
+  - Low: Next release cycle
+
+### Severity Classification
+
+| Severity | Description | Example |
+|----------|-------------|---------|
+| Critical | Complete bypass of security controls | Guard returns `allowed: true` for known attack |
+| High | Significant reduction in protection | Pattern fails to detect major attack category |
+| Medium | Limited bypass under specific conditions | Edge case pattern evasion |
+| Low | Minor issues or improvements | Detection rate below optimal |
+
+## Security Best Practices
+
+### Using llm-trust-guard
+
+1. **Defense in Depth**: Use multiple guards in combination
+   ```typescript
+   // Recommended: Layer multiple guards
+   const sanitizer = new InputSanitizer();
+   const encoder = new EncodingDetector();
+   const memory = new MemoryGuard();
+
+   // Check all layers
+   const input1 = sanitizer.sanitize(userInput);
+   const input2 = encoder.detect(userInput);
+   const input3 = memory.validateContextInjection(context, sessionId);
+   ```
+
+2. **Keep Updated**: Always use the latest version
+   ```bash
+   npm update llm-trust-guard
+   ```
+
+3. **Configure Appropriately**: Adjust thresholds based on your risk tolerance
+   ```typescript
+   // Stricter configuration for high-security environments
+   const sanitizer = new InputSanitizer({
+     threshold: 0.5,        // Higher = stricter
+     papThreshold: 0.3,     // Lower = more sensitive to PAP
+     blockCompoundPersuasion: true
+   });
+   ```
+
+4. **Monitor and Log**: Enable logging for security events
+   ```typescript
+   const sanitizer = new InputSanitizer({
+     logMatches: true  // Log detected patterns
+   });
+   ```
+
+5. **Validate All Sources**: Don't trust external data
+   ```typescript
+   // Always validate RAG content
+   const ragGuard = new RAGGuard();
+   const result = ragGuard.validateDocument(externalDoc);
+
+   // Always validate memory/context
+   const memGuard = new MemoryGuard();
+   const ctxResult = memGuard.validateContextInjection(context, session);
+   ```
+
+### Known Attack Vectors Protected
+
+| Attack Vector | Guard(s) | OWASP Reference |
+|---------------|----------|-----------------|
+| Prompt Injection | InputSanitizer, EncodingDetector | LLM01:2025 |
+| Jailbreaks | InputSanitizer (PAP detection) | LLM01:2025 |
+| Sensitive Data Exposure | OutputFilter, PromptLeakageGuard | LLM02:2025 |
+| Supply Chain Attacks | MCPSecurityGuard | LLM03:2025 |
+| Data Poisoning | RAGGuard, MemoryGuard | LLM04:2025 |
+| Privilege Escalation | PolicyGate, TenantBoundary | LLM05:2025 |
+| System Prompt Leakage | PromptLeakageGuard | LLM07:2025 |
+| Vector DB Attacks | RAGGuard | LLM08:2025 |
+| Tool Misuse | ToolChainValidator | ASI04 |
+| Privilege Escalation | PolicyGate | ASI05 |
+| Memory Poisoning | MemoryGuard | ASI06 |
+| State Corruption | ToolChainValidator | ASI07 |
+| Trust Exploitation | TrustExploitationGuard | ASI09 |
+
+### Security Limitations
+
+1. **Not a Complete Solution**: This library is one layer of defense. Always implement:
+   - Input validation at application level
+   - Output sanitization
+   - Rate limiting
+   - Authentication/Authorization
+   - Logging and monitoring
+
+2. **Pattern-Based Detection**: Relies on known patterns; novel attacks may evade detection initially
+
+3. **Performance Trade-offs**: More thorough checks = higher latency
+
+4. **False Positives**: Aggressive settings may block legitimate content
+
+## Disclosure Policy
+
+- We follow responsible disclosure practices
+- Security fixes are released as soon as possible
+- CVEs are requested for critical vulnerabilities
+- Security advisories are published on GitHub
+
+## Security Updates
+
+Subscribe to security updates:
+1. Watch this repository for releases
+2. Check the CHANGELOG.md for security-related changes
+3. Monitor npm advisories: `npm audit`
+
+## Acknowledgments
+
+We thank all security researchers who responsibly disclose vulnerabilities. Contributors will be acknowledged (with permission) in release notes.

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "llm-trust-guard",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Comprehensive security guards for LLM-powered and agentic AI applications - 18+ protection layers covering OWASP Top 10 for LLMs 2025, Agentic Applications 2026, and MCP Security. Features prompt injection (PAP/persuasion), multi-modal attacks, RAG poisoning with embedding attack detection, memory persistence attacks, code execution sandboxing, multi-agent security, MCP tool shadowing prevention, system prompt leakage protection, human-agent trust exploitation (ASI09), tool chain validation v2 (ASI07/ASI04), and more",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CHANGELOG.md"
   ],
+  "homepage": "https://www.npmjs.com/package/llm-trust-guard",
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",