@riotprompt/riotprompt 0.0.21 → 1.0.1-dev.0

package/guide/security.md

@@ -0,0 +1,237 @@
+# Security Guide
+
+## Overview
+
+This guide covers security best practices when using RiotPrompt and related packages for AI/LLM workflows.
+
+## Threat Model
+
+### Assets to Protect
+- **API Keys**: OpenAI, Anthropic, Gemini, and other provider credentials
+- **User Data**: Prompts, conversations, and context containing sensitive information
+- **File System**: Access to local files and directories
+- **External APIs**: Network access to LLM providers and other services
+
+### Threat Categories
+
+| Threat | Description | Severity |
+|--------|-------------|----------|
+| Tool Injection | LLM generates malicious tool parameters | 🔴 Critical |
+| Path Traversal | Accessing files outside intended directories | 🔴 Critical |
+| Secret Leakage | API keys or sensitive data in logs/errors | 🔴 Critical |
+| Resource Exhaustion | Infinite loops, ReDoS, timeout failures | 🟠 High |
+| Prompt Injection | LLM output influences security-critical operations | 🟠 High |
+| Information Disclosure | Error messages reveal system details | 🟡 Medium |
+
+### Mitigations
+
+| Threat | Mitigation | Package |
+|--------|------------|---------|
+| Tool Injection | ToolGuard with Zod schema validation | agentic |
+| Path Traversal | PathGuard with base path restrictions | riotprompt |
+| Secret Leakage | SecretGuard with automatic redaction | offrecord, spotclean |
+| Resource Exhaustion | TimeoutGuard, SafeRegex, rate limiting | riotprompt, pressurelid |
+| Prompt Injection | Careful tool design, output validation | Application level |
+| Information Disclosure | Error sanitization in production | spotclean |
+
+## Configuration Examples
+
+### Development Mode
+
+For local development with verbose logging:
+
+```typescript
+import { Security } from '@theunwalked/riotprompt';
+
+// Permissive configuration for development
+Security.configurePathGuard({
+  enabled: false, // Disable for easier development
+});
+
+Security.configureTimeoutGuard({
+  enabled: true,
+  llmTimeout: 300000, // 5 minutes for debugging
+});
+
+// Enable logging
+process.env.RIOTPROMPT_LOGGING = 'true';
+```
+
+### Production Mode
+
+Recommended configuration for production:
+
+```typescript
+import { Security, initializeErrorHandling } from '@theunwalked/riotprompt';
+
+// Initialize error handling first
+initializeErrorHandling({
+  environment: 'production',
+  basePaths: [process.cwd()],
+});
+
+// Configure path security
+Security.configurePathGuard({
+  enabled: true,
+  basePaths: [process.cwd()],
+  allowAbsolute: false,
+  allowSymlinks: false,
+  denyPatterns: [
+    '\\.\\.',        // Parent directory
+    '~',             // Home directory
+    '\\$\\{',        // Variable expansion
+    '\\$\\(',        // Command substitution
+  ],
+});
+
+// Configure timeout protection
+Security.configureTimeoutGuard({
+  enabled: true,
+  defaultTimeout: 30000,
+  llmTimeout: 120000,
+  toolTimeout: 30000,
+  fileTimeout: 5000,
+});
+
+// Configure audit logging
+Security.configureAuditLogger({
+  enabled: true,
+  logLevel: 'warning',
+  onEvent: (event) => {
+    // Send to monitoring system
+    if (event.severity === 'error') {
+      alertOps(event);
+    }
+  },
+});
+```
+
+### High Security Mode
+
+For handling PII or sensitive data:
+
+```typescript
+import { Security } from '@theunwalked/riotprompt';
+import { ToolGuard, ToolSandbox } from '@theunwalked/agentic';
+
+// Strict path security
+Security.configurePathGuard({
+  enabled: true,
+  basePaths: ['./approved-prompts'],
+  allowAbsolute: false,
+  allowSymlinks: false,
+});
+
+// Tool validation with strict schemas
+const guard = new ToolGuard({
+  enabled: true,
+  validateParams: true,
+  detectPrototypePollution: true,
+  allowedTools: ['read_file', 'search'], // Explicit allowlist
+});
+
+// Sandboxed execution
+const sandbox = new ToolSandbox({
+  enabled: true,
+  maxExecutionTime: 10000, // Shorter timeout
+  maxConcurrent: 2,        // Limit concurrency
+  maxOutputSize: 100000,   // 100KB max
+});
+
+// Rate limiting
+Security.configureRateLimiter({
+  windowMs: 60000,  // 1 minute
+  maxRequests: 10,  // 10 requests per minute
+});
+```
+
+## Best Practices
+
+### API Key Management
+
+1. **Never** pass API keys via CLI flags
+   ```bash
+   # BAD - key visible in process list
+   riotprompt execute --api-key sk-xxx...
+   
+   # GOOD - use environment variable
+   export OPENAI_API_KEY=sk-xxx...
+   riotprompt execute
+   ```
+
+2. Use environment variables or a secrets manager
+3. Rotate keys regularly
+4. Use separate keys for development and production
+5. Monitor key usage for anomalies
+
+### Tool Development
+
+1. **Define Zod schemas** for all parameters:
+   ```typescript
+   const schema = z.object({
+     path: z.string().max(1000).refine(
+       p => !p.includes('..'),
+       'Path traversal not allowed'
+     ),
+     content: z.string().max(100000),
+   });
+   ```
+
+2. **Validate outputs** as well as inputs
+3. **Implement proper error handling** that doesn't leak information
+4. **Avoid shell commands** when possible
+5. **Log security-relevant operations** to audit log
+
+### Prompt Security
+
+1. **Don't include secrets in prompts**
+   ```typescript
+   // BAD
+   const prompt = `Use API key ${apiKey} to...`;
+   
+   // GOOD - pass via secure context
+   const prompt = `Use the configured API key to...`;
+   ```
+
+2. **Sanitize user input** before including in prompts
+3. **Be cautious with user-provided file paths**
+4. **Review LLM outputs** before executing tools
+5. **Use structured output** (JSON mode) for tool calls
+
+### Logging Security
+
+1. **Keep logging disabled** in production by default
+2. **Use correlation IDs** for debugging without exposing details
+3. **Monitor audit logs** for security events
+4. **Set up alerts** for critical security events
+
+## Security Events
+
+The `SecurityAuditLogger` tracks these event types:
+
+| Event Type | Description | Severity |
+|------------|-------------|----------|
+| `path_traversal_blocked` | Directory traversal attempt blocked | warning |
+| `tool_validation_failed` | Tool parameter validation failed | warning |
+| `tool_execution_timeout` | Tool execution timed out | warning |
+| `secret_redacted` | Secret was redacted from output | info |
+| `regex_blocked` | Unsafe regex pattern blocked | warning |
+| `request_timeout` | External request timed out | warning |
+| `api_key_used` | API key was used (for auditing) | info |
+
+## Incident Response
+
+If you suspect a security incident:
+
+1. **Rotate all API keys** immediately
+2. **Review audit logs** for suspicious activity
+3. **Check for unauthorized file access**
+4. **Review recent tool executions**
+5. **Report the incident** following your organization's procedures
+
+## Additional Resources
+
+- [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
+- [API Security Best Practices](https://owasp.org/www-project-api-security/)
+- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
+

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@riotprompt/riotprompt",
-  "version": "0.0.21",
+  "version": "1.0.1-dev.0",
+  "_versionReset": "2026-01-15",
   "keywords": [
     "prompt",
     "llm",
@@ -35,11 +36,13 @@
     "test": "npm run test:coverage",
     "test:coverage": "vitest run --coverage",
     "test:debug": "vitest --run --coverage --reporter verbose",
+    "test:security": "vitest run tests/security",
+    "test:security:watch": "vitest tests/security",
     "test:readme": "doccident -c .markdown-doctest-setup.mjs README.md",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "clean": "rm -rf dist",
-    "precommit": "npm run lint && npm run test",
+    "precommit": "npm run build && npm run lint && npm run test",
     "prepublishOnly": "npm run clean && npm run build",
     "docs:dev": "cd docs && cp ../README.md public/ && npm install && npm run dev",
     "docs:build": "cd docs && cp ../README.md public/ && npm install && npm run build",
@@ -50,7 +53,6 @@
   "author": "Tim O'Brien <tobrien@discursive.com>",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.71.2",
     "@babel/core": "^7.28.0",
     "@babel/plugin-transform-modules-commonjs": "^7.27.1",
     "@babel/plugin-transform-typescript": "^7.28.0",
@@ -58,17 +60,16 @@
     "@doccident/doccident": "^0.0.1",
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.30.1",
-    "@google/generative-ai": "^0.24.1",
     "@rollup/plugin-replace": "^6.0.2",
     "@swc/core": "^1.12.11",
     "@types/node": "^24.0.12",
     "@typescript-eslint/eslint-plugin": "^8.36.0",
     "@typescript-eslint/parser": "^8.36.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "ajv": "^8.17.1",
     "eslint": "^9.30.1",
     "eslint-plugin-import": "^2.32.0",
     "globals": "^16.3.0",
-    "openai": "^6.15.0",
     "typescript": "^5.8.3",
     "vite": "^7.0.4",
     "vite-plugin-dts": "^4.5.4",
@@ -76,25 +77,31 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@theunwalked/cardigantime": "^0.0.17",
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@fjell/logging": "^4.4.68",
+    "@google/generative-ai": "^0.24.1",
+    "@theunwalked/cardigantime": "^0.0.22",
+    "@theunwalked/pressurelid": "^1.0.2",
+    "@theunwalked/spotclean": "^0.0.3",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
     "fast-xml-parser": "^5.3.3",
     "glob": "^11.0.3",
     "js-yaml": "^4.1.1",
     "marked": "^16.0.0",
+    "openai": "^6.15.0",
     "tiktoken": "^1.0.22",
     "zod": "^4.0.2",
     "zod-to-json-schema": "^3.25.1"
   },
   "peerDependencies": {
-    "@riotprompt/execution": "^0.0.4",
-    "@riotprompt/execution-openai": "^0.0.4",
-    "@riotprompt/execution-anthropic": "^0.0.4",
-    "@riotprompt/execution-gemini": "^0.0.4",
-    "@riotprompt/agentic": "^0.0.5",
     "@anthropic-ai/sdk": "^0.71.2",
     "@google/generative-ai": "^0.24.1",
+    "@riotprompt/agentic": "^1.0.2",
+    "@riotprompt/execution": "^1.0.1",
+    "@riotprompt/execution-anthropic": "^1.0.1",
+    "@riotprompt/execution-gemini": "^1.0.1",
+    "@riotprompt/execution-openai": "^1.0.1",
     "openai": "^6.15.0",
     "tiktoken": "^1.0.22"
   },