agentshield-sdk 7.0.0

package/src/enterprise.js

@@ -0,0 +1,405 @@
+'use strict';
+
+/**
+ * Agent Shield — Enterprise Features
+ *
+ * - Multi-tenant support
+ * - Role-based policies
+ * - Debug mode with detailed traces
+ * - Policy inheritance and overrides
+ */
+
+const { AgentShield } = require('./index');
+const { loadPolicy } = require('./policy');
+
+// =========================================================================
+// Multi-Tenant Shield
+// =========================================================================
+
+class MultiTenantShield {
+  constructor(options = {}) {
+    this.tenants = new Map();
+    this.defaultPolicy = options.defaultPolicy || { sensitivity: 'high', blockOnThreat: true };
+    this.globalOverrides = options.globalOverrides || {};
+    this.onTenantCreated = options.onTenantCreated || null;
+  }
+
+  /**
+   * Register a tenant with its own policy.
+   */
+  registerTenant(tenantId, policy = {}) {
+    const mergedPolicy = { ...this.defaultPolicy, ...policy, ...this.globalOverrides };
+    const shield = new AgentShield(mergedPolicy);
+
+    this.tenants.set(tenantId, {
+      id: tenantId,
+      policy: mergedPolicy,
+      shield,
+      stats: { scans: 0, threats: 0, blocked: 0 },
+      createdAt: new Date().toISOString()
+    });
+
+    if (this.onTenantCreated) {
+      this.onTenantCreated(tenantId, mergedPolicy);
+    }
+
+    return this;
+  }
+
+  /**
+   * Get or auto-create a tenant shield.
+   */
+  getTenant(tenantId) {
+    if (!this.tenants.has(tenantId)) {
+      this.registerTenant(tenantId);
+    }
+    return this.tenants.get(tenantId);
+  }
+
+  /**
+   * Scan input for a specific tenant.
+   */
+  scan(tenantId, text, options = {}) {
+    const tenant = this.getTenant(tenantId);
+    tenant.stats.scans++;
+
+    const result = tenant.shield.scan(text, options);
+
+    if (result.threats.length > 0) {
+      tenant.stats.threats += result.threats.length;
+    }
+    if (result.blocked) {
+      tenant.stats.blocked++;
+    }
+
+    return { ...result, tenantId };
+  }
+
+  /**
+   * Scan input for a specific tenant.
+   */
+  scanInput(tenantId, text) {
+    return this.scan(tenantId, text);
+  }
+
+  /**
+   * Scan output for a specific tenant.
+   */
+  scanOutput(tenantId, text) {
+    const tenant = this.getTenant(tenantId);
+    return tenant.shield.scanOutput(text);
+  }
+
+  /**
+   * Update a tenant's policy.
+   */
+  updatePolicy(tenantId, policy) {
+    const tenant = this.getTenant(tenantId);
+    tenant.policy = { ...tenant.policy, ...policy, ...this.globalOverrides };
+    tenant.shield = new AgentShield(tenant.policy);
+    return tenant.policy;
+  }
+
+  /**
+   * Get stats for all tenants.
+   */
+  getAllStats() {
+    const stats = {};
+    for (const [id, tenant] of this.tenants) {
+      stats[id] = { ...tenant.stats, policy: tenant.policy };
+    }
+    return stats;
+  }
+
+  /**
+   * Remove a tenant.
+   */
+  removeTenant(tenantId) {
+    return this.tenants.delete(tenantId);
+  }
+
+  /**
+   * Get tenant count.
+   */
+  get size() {
+    return this.tenants.size;
+  }
+}
+
+// =========================================================================
+// Role-Based Policies
+// =========================================================================
+
+const DEFAULT_ROLES = {
+  admin: {
+    name: 'Administrator',
+    sensitivity: 'medium',
+    blockOnThreat: false,
+    allowedTools: '*',
+    blockedTools: [],
+    bypassCircuitBreaker: true,
+    canViewAuditTrail: true,
+    canModifyPolicy: true
+  },
+  operator: {
+    name: 'Operator',
+    sensitivity: 'high',
+    blockOnThreat: true,
+    allowedTools: ['search', 'readFile', 'calculator'],
+    blockedTools: ['bash', 'shell', 'exec'],
+    bypassCircuitBreaker: false,
+    canViewAuditTrail: true,
+    canModifyPolicy: false
+  },
+  user: {
+    name: 'Standard User',
+    sensitivity: 'high',
+    blockOnThreat: true,
+    allowedTools: ['search', 'calculator'],
+    blockedTools: ['bash', 'shell', 'exec', 'readFile', 'writeFile'],
+    bypassCircuitBreaker: false,
+    canViewAuditTrail: false,
+    canModifyPolicy: false
+  },
+  restricted: {
+    name: 'Restricted User',
+    sensitivity: 'high',
+    blockOnThreat: true,
+    blockThreshold: 'low',
+    allowedTools: [],
+    blockedTools: '*',
+    bypassCircuitBreaker: false,
+    canViewAuditTrail: false,
+    canModifyPolicy: false
+  }
+};
+
+class RoleBasedPolicy {
+  constructor(options = {}) {
+    this.roles = { ...DEFAULT_ROLES, ...(options.customRoles || {}) };
+    this.userRoles = new Map();
+    this.shields = new Map();
+  }
+
+  /**
+   * Assign a role to a user.
+   */
+  assignRole(userId, role) {
+    if (!this.roles[role]) {
+      throw new Error(`Unknown role: ${role}. Available: ${Object.keys(this.roles).join(', ')}`);
+    }
+    this.userRoles.set(userId, role);
+
+    // Create a shield for this role if not exists
+    if (!this.shields.has(role)) {
+      const roleConfig = this.roles[role];
+      this.shields.set(role, new AgentShield({
+        sensitivity: roleConfig.sensitivity,
+        blockOnThreat: roleConfig.blockOnThreat,
+        blockThreshold: roleConfig.blockThreshold
+      }));
+    }
+
+    return this;
+  }
+
+  /**
+   * Get the effective policy for a user.
+   */
+  getPolicy(userId) {
+    const role = this.userRoles.get(userId) || 'user';
+    return { role, ...this.roles[role] };
+  }
+
+  /**
+   * Scan input with the user's role-based policy.
+   */
+  scan(userId, text, options = {}) {
+    const role = this.userRoles.get(userId) || 'user';
+
+    // Reuse shield created in assignRole, or create lazily
+    if (!this.shields.has(role)) {
+      this.assignRole(userId, role);
+    }
+
+    const result = this.shields.get(role).scan(text, options);
+    return { ...result, userId, role };
+  }
+
+  /**
+   * Check if a user can use a specific tool.
+   */
+  checkToolAccess(userId, toolName) {
+    const role = this.userRoles.get(userId) || 'user';
+    const roleConfig = this.roles[role];
+
+    if (roleConfig.blockedTools === '*') return { allowed: false, reason: 'All tools blocked for this role' };
+    if (Array.isArray(roleConfig.blockedTools) && roleConfig.blockedTools.includes(toolName)) {
+      return { allowed: false, reason: `Tool "${toolName}" is blocked for role "${role}"` };
+    }
+
+    if (roleConfig.allowedTools === '*') return { allowed: true };
+    if (Array.isArray(roleConfig.allowedTools) && roleConfig.allowedTools.includes(toolName)) {
+      return { allowed: true };
+    }
+
+    return { allowed: false, reason: `Tool "${toolName}" is not in the allowed list for role "${role}"` };
+  }
+
+  /**
+   * Define a custom role.
+   */
+  defineRole(name, config) {
+    this.roles[name] = { name: config.name || name, ...config };
+    return this;
+  }
+
+  /**
+   * Get all available roles.
+   */
+  getRoles() {
+    return Object.entries(this.roles).map(([key, val]) => ({ key, ...val }));
+  }
+}
+
+// =========================================================================
+// Debug Mode
+// =========================================================================
+
+class DebugShield {
+  constructor(options = {}) {
+    this.shield = new AgentShield(options);
+    this.traces = [];
+    this.enabled = options.debug !== false;
+    this.maxTraces = options.maxTraces || 1000;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Scan with full debug trace.
+   */
+  scan(text, options = {}) {
+    const startTime = this.enabled ? process.hrtime.bigint() : null;
+
+    // Scan
+    const result = this.shield.scan(text, options);
+
+    // Only build trace if debug is enabled
+    let trace = null;
+    if (this.enabled) {
+      const endTime = process.hrtime.bigint();
+      const elapsedMs = Number(endTime - startTime) / 1e6;
+
+      trace = {
+        id: `trace_${Date.now()}_${Math.random().toString(36).slice(2, 8).padEnd(6, '0')}`,
+        timestamp: new Date().toISOString(),
+        input: text.substring(0, 500),
+        inputLength: text.length,
+        options,
+        steps: [
+          {
+            step: 'input_received',
+            time: 0,
+            detail: { length: text.length, hasUnicode: /[^\x00-\x7F]/.test(text) }
+          },
+          {
+            step: 'pattern_matching',
+            time: elapsedMs,
+            detail: {
+              patternsChecked: this.shield.getPatterns().length,
+              threatsFound: result.threats.length,
+              threats: result.threats.map(t => ({
+                severity: t.severity,
+                category: t.category,
+                description: t.description,
+                confidence: t.confidence
+              }))
+            }
+          },
+          {
+            step: 'decision',
+            time: elapsedMs,
+            detail: {
+              status: result.status,
+              blocked: result.blocked,
+              threatCount: result.threats.length
+            }
+          }
+        ],
+        totalTimeMs: parseFloat(elapsedMs.toFixed(3)),
+        result: {
+          status: result.status,
+          blocked: result.blocked,
+          threatCount: result.threats.length
+        }
+      };
+
+      this.traces.push(trace);
+      while (this.traces.length > this.maxTraces) {
+        this.traces.shift();
+      }
+    }
+
+    if (this.verbose) {
+      const ms = trace ? trace.totalTimeMs : 0;
+      console.log(`[Agent Shield] DEBUG Scan: ${text.substring(0, 50)}... → ${result.status} (${ms.toFixed(1)}ms, ${result.threats.length} threats)`);
+    }
+
+    return { ...result, _trace: trace };
+  }
+
+  /**
+   * Get all traces.
+   */
+  getTraces() {
+    return this.traces;
+  }
+
+  /**
+   * Get the last N traces.
+   */
+  getRecentTraces(n = 10) {
+    return this.traces.slice(-n);
+  }
+
+  /**
+   * Export traces as JSON.
+   */
+  exportTraces() {
+    return JSON.stringify(this.traces, null, 2);
+  }
+
+  /**
+   * Clear traces.
+   */
+  clearTraces() {
+    this.traces = [];
+  }
+
+  /**
+   * Get timing statistics across all traces.
+   */
+  getTimingStats() {
+    if (this.traces.length === 0) return null;
+
+    const times = this.traces.map(t => t.totalTimeMs);
+    times.sort((a, b) => a - b);
+
+    return {
+      count: times.length,
+      min: times[0],
+      max: times[times.length - 1],
+      avg: parseFloat((times.reduce((a, b) => a + b, 0) / times.length).toFixed(3)),
+      median: times[Math.floor(times.length / 2)],
+      p95: times[Math.min(Math.floor(times.length * 0.95), times.length - 1)],
+      p99: times[Math.min(Math.floor(times.length * 0.99), times.length - 1)]
+    };
+  }
+}
+
+module.exports = {
+  MultiTenantShield,
+  RoleBasedPolicy,
+  DebugShield,
+  DEFAULT_ROLES
+};

package/src/errors.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Structured error codes for Agent Shield
+ * Format: AS-{CATEGORY}-{NUMBER}
+ *
+ * Categories:
+ *   DET  — Detection engine errors
+ *   CFG  — Configuration errors
+ *   PLG  — Plugin errors
+ *   INT  — Integration errors
+ *   POL  — Policy errors
+ *   NET  — Network/distributed errors
+ *   AUT  — Authentication/authorization errors
+ */
+
+const ERROR_CODES = {
+  // Detection
+  'AS-DET-001': { message: 'Detection engine not initialized', severity: 'critical' },
+  'AS-DET-002': { message: 'Invalid input type — expected string', severity: 'high' },
+  'AS-DET-003': { message: 'Pattern compilation failed', severity: 'high' },
+  'AS-DET-004': { message: 'Scan timeout exceeded', severity: 'medium' },
+  'AS-DET-005': { message: 'Input exceeds maximum length', severity: 'medium' },
+
+  // Configuration
+  'AS-CFG-001': { message: 'Invalid configuration object', severity: 'critical' },
+  'AS-CFG-002': { message: 'Unknown configuration key', severity: 'low' },
+  'AS-CFG-003': { message: 'Invalid threshold value — must be 0-1', severity: 'high' },
+  'AS-CFG-004': { message: 'Preset not found', severity: 'medium' },
+
+  // Plugin
+  'AS-PLG-001': { message: 'Plugin failed to load', severity: 'high' },
+  'AS-PLG-002': { message: 'Plugin version incompatible', severity: 'high' },
+  'AS-PLG-003': { message: 'Plugin hook threw an error', severity: 'medium' },
+
+  // Integration
+  'AS-INT-001': { message: 'Framework adapter not found', severity: 'high' },
+  'AS-INT-002': { message: 'Middleware setup failed', severity: 'critical' },
+  'AS-INT-003': { message: 'Hook registration failed', severity: 'medium' },
+
+  // Policy
+  'AS-POL-001': { message: 'Policy parse error', severity: 'critical' },
+  'AS-POL-002': { message: 'Policy rule conflict detected', severity: 'high' },
+  'AS-POL-003': { message: 'Policy file not found', severity: 'high' },
+
+  // Network/Distributed
+  'AS-NET-001': { message: 'Distributed sync failed', severity: 'high' },
+  'AS-NET-002': { message: 'Peer node unreachable', severity: 'medium' },
+
+  // Auth
+  'AS-AUT-001': { message: 'RBAC permission denied', severity: 'high' },
+  'AS-AUT-002': { message: 'Tenant not found', severity: 'high' },
+  'AS-AUT-003': { message: 'SSO token validation failed', severity: 'critical' },
+};
+
+/**
+ * Create a structured AgentShield error
+ * @param {string} code - Error code (e.g., 'AS-DET-001')
+ * @param {Object} [details] - Additional context
+ * @returns {Error}
+ */
+function createShieldError(code, details = {}) {
+  const entry = ERROR_CODES[code];
+  if (!entry) {
+    const err = new Error(`Unknown error code: ${code}`);
+    err.code = 'AS-CFG-002';
+    return err;
+  }
+  const err = new Error(`[Agent Shield ${code}] ${entry.message}`);
+  err.code = code;
+  err.severity = entry.severity;
+  err.details = details;
+  err.timestamp = Date.now();
+  return err;
+}
+
+/**
+ * Emit a deprecation warning (once per code)
+ * @param {string} feature - Deprecated feature name
+ * @param {string} replacement - Suggested replacement
+ * @param {string} removeVersion - Version when it will be removed
+ */
+const _warned = new Set();
+function deprecationWarning(feature, replacement, removeVersion) {
+  const key = `${feature}:${replacement}`;
+  if (_warned.has(key)) return;
+  _warned.add(key);
+  const msg = `[Agent Shield] DEPRECATED: "${feature}" is deprecated and will be removed in v${removeVersion}. Use "${replacement}" instead.`;
+  if (typeof process !== 'undefined' && process.emitWarning) {
+    process.emitWarning(msg, 'DeprecationWarning');
+  } else {
+    console.warn(msg); // [Agent Shield] prefix included in msg
+  }
+}
+
+module.exports = {
+  ERROR_CODES,
+  createShieldError,
+  deprecationWarning,
+};