Sasha Tools Permission System Guide

Generated: 2025-08-06 UTC
Purpose: Complete guide for implementing and managing the tool permission system
Audience: Administrators and developers working with tool permissions

---

Overview

The Permission System provides granular control over tool availability, ensuring:

• Security: High-risk tools are disabled by default
• Control: Administrators decide what tools are available
• Flexibility: Different permissions for different user roles
• Auditability: All permission changes are logged
• Safety: Risk-based classification and warnings

System Architecture

Permission Flow

User Request → Role Check → Tool Permission → Risk Assessment → Confirmation → Execution
      ↓            ↓              ↓               ↓                ↓            ↓
   Denied?    No Access?     Disabled?      Too Risky?      Not Confirmed?   Log Activity

Component Architecture

┌─────────────────────────────────────────────────────────┐
│                   Admin Interface                        │
│  Tool List │ Risk Levels │ Role Management │ Audit Log  │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│              Permission Service Layer                    │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Permission Engine                               │  │
│  │  - Load configuration                            │  │
│  │  - Validate permissions                          │  │
│  │  - Check role access                            │  │
│  │  - Enforce restrictions                         │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Audit Logger                                    │  │
│  │  - Track permission changes                      │  │
│  │  - Log access attempts                          │  │
│  │  - Generate compliance reports                  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│                Configuration Storage                     │
│  /config/tool-permissions.json                          │
│  /config/user-roles.json                                │
│  /logs/permission-audit.jsonl                           │
└─────────────────────────────────────────────────────────┘

Configuration Schema

Main Permission File: /config/tool-permissions.json

{
  "version": "1.0",
  "lastModified": "2025-08-06T10:00:00Z",
  "modifiedBy": "admin@example.com",
  
  "globalSettings": {
    "requireConfirmation": true,
    "auditLogging": true,
    "defaultRiskLevel": "medium",
    "rateLimiting": {
      "enabled": true,
      "maxPerHour": 100,
      "maxPerDay": 1000,
      "maxPerUser": 50
    },
    "maintenanceMode": false,
    "allowedHours": {
      "enabled": false,
      "start": "08:00",
      "end": "18:00",
      "timezone": "UTC"
    }
  },
  
  "riskLevels": {
    "low": {
      "color": "green",
      "requiresConfirmation": false,
      "allowedByDefault": true,
      "description": "Safe, read-only or creates new files"
    },
    "medium": {
      "color": "yellow",
      "requiresConfirmation": true,
      "allowedByDefault": true,
      "description": "Modifies existing files"
    },
    "high": {
      "color": "orange",
      "requiresConfirmation": true,
      "allowedByDefault": false,
      "description": "Deletes files or external communication"
    },
    "critical": {
      "color": "red",
      "requiresConfirmation": true,
      "allowedByDefault": false,
      "requiresAdminApproval": true,
      "description": "System commands or security-sensitive"
    }
  },
  
  "tools": [
    {
      "id": "create-ppt",
      "enabled": true,
      "name": "PowerPoint Creator",
      "description": "Creates presentation slides",
      "category": "creation",
      "riskLevel": "low",
      "requiresConfirmation": false,
      "permissions": {
        "allowedPaths": [
          "/workspace/presentations",
          "/workspace/docs"
        ],
        "restrictedPaths": [
          "/workspace/config",
          "/workspace/secrets"
        ],
        "maxFileSizeMB": 50,
        "allowedFormats": ["pptx", "pdf", "md"],
        "maxExecutionTime": 30000,
        "requiredRole": null
      },
      "rateLimits": {
        "maxPerHour": 20,
        "maxPerDay": 100
      },
      "customValidation": {
        "maxSlides": 100,
        "allowedThemes": ["corporate", "creative", "minimal"]
      }
    },
    {
      "id": "delete-files",
      "enabled": false,
      "name": "File Deletion Tool",
      "description": "Permanently deletes files",
      "category": "maintenance",
      "riskLevel": "high",
      "requiresConfirmation": true,
      "disabledReason": "High risk - enable only when needed",
      "permissions": {
        "allowedPaths": ["/workspace/temp"],
        "allowedPatterns": ["*.tmp", "*.log", "*.bak"],
        "maxFilesPerOperation": 50,
        "requiresAdminRole": true,
        "requiresSecondConfirmation": true
      }
    },
    {
      "id": "execute-code",
      "enabled": false,
      "name": "Code Executor",
      "description": "Executes arbitrary code",
      "category": "development",
      "riskLevel": "critical",
      "requiresConfirmation": true,
      "disabledReason": "Critical security risk",
      "permissions": {
        "allowedCommands": [],
        "requiresAdminRole": true,
        "requiresMFA": true,
        "sessionTimeout": 300000,
        "auditLevel": "verbose"
      }
    }
  ],
  
  "categories": {
    "creation": {
      "name": "Document Creation",
      "icon": "📝",
      "defaultEnabled": true
    },
    "enhancement": {
      "name": "Document Enhancement",
      "icon": "✨",
      "defaultEnabled": true
    },
    "maintenance": {
      "name": "System Maintenance",
      "icon": "🔧",
      "defaultEnabled": false
    },
    "development": {
      "name": "Development Tools",
      "icon": "💻",
      "defaultEnabled": false
    }
  }
}

User Roles Configuration: /config/user-roles.json

{
  "roles": {
    "admin": {
      "name": "Administrator",
      "description": "Full system access",
      "permissions": {
        "canModifyPermissions": true,
        "canEnableAllTools": true,
        "canBypassConfirmation": false,
        "canViewAllLogs": true,
        "canDeleteLogs": true,
        "maxRiskLevel": "critical"
      },
      "allowedTools": ["*"],
      "deniedTools": [],
      "rateLimits": {
        "multiplier": 2.0
      }
    },
    "developer": {
      "name": "Developer",
      "description": "Development and testing access",
      "permissions": {
        "canModifyPermissions": false,
        "canEnableAllTools": false,
        "canBypassConfirmation": false,
        "canViewOwnLogs": true,
        "maxRiskLevel": "medium"
      },
      "allowedTools": [
        "create-ppt",
        "create-excel",
        "beautify-document",
        "rewrite-document",
        "analyze-code"
      ],
      "deniedTools": [
        "delete-files",
        "execute-code"
      ],
      "rateLimits": {
        "multiplier": 1.5
      }
    },
    "user": {
      "name": "Standard User",
      "description": "Basic access",
      "permissions": {
        "canModifyPermissions": false,
        "canEnableAllTools": false,
        "canBypassConfirmation": false,
        "canViewOwnLogs": true,
        "maxRiskLevel": "low"
      },
      "allowedTools": [
        "create-ppt",
        "create-excel",
        "beautify-document"
      ],
      "deniedTools": ["*"],
      "rateLimits": {
        "multiplier": 1.0
      }
    },
    "viewer": {
      "name": "Viewer",
      "description": "Read-only access",
      "permissions": {
        "canModifyPermissions": false,
        "canEnableAllTools": false,
        "canBypassConfirmation": false,
        "canViewOwnLogs": false,
        "maxRiskLevel": "none"
      },
      "allowedTools": [],
      "deniedTools": ["*"]
    }
  },
  
  "userAssignments": {
    "admin@example.com": "admin",
    "dev@example.com": "developer",
    "user@example.com": "user",
    "viewer@example.com": "viewer"
  },
  
  "defaultRole": "user"
}

Admin Interface Design

Tool Management UI

<!-- Admin Settings Modal -->
<div id="admin-settings" class="modal">
  <div class="modal-content">
    <h2>🔐 Tool Permissions Management</h2>
    
    <!-- Quick Stats -->
    <div class="permission-stats">
      <div class="stat-card">
        <span class="stat-value">12</span>
        <span class="stat-label">Total Tools</span>
      </div>
      <div class="stat-card">
        <span class="stat-value">8</span>
        <span class="stat-label">Enabled</span>
      </div>
      <div class="stat-card">
        <span class="stat-value">4</span>
        <span class="stat-label">Disabled</span>
      </div>
      <div class="stat-card risk-high">
        <span class="stat-value">2</span>
        <span class="stat-label">High Risk</span>
      </div>
    </div>
    
    <!-- Filter Controls -->
    <div class="filter-controls">
      <input type="search" placeholder="Search tools..." id="tool-search">
      <select id="category-filter">
        <option value="">All Categories</option>
        <option value="creation">Creation</option>
        <option value="enhancement">Enhancement</option>
        <option value="maintenance">Maintenance</option>
      </select>
      <select id="risk-filter">
        <option value="">All Risk Levels</option>
        <option value="low">Low Risk</option>
        <option value="medium">Medium Risk</option>
        <option value="high">High Risk</option>
        <option value="critical">Critical Risk</option>
      </select>
    </div>
    
    <!-- Tools List -->
    <div class="tools-permission-list">
      <!-- Risk Group: Low -->
      <div class="risk-group">
        <h3 class="risk-header">
          <span class="risk-indicator low">●</span>
          Low Risk Tools
        </h3>
        <div class="tools-in-group">
          <!-- Tool Item -->
          <div class="tool-item">
            <div class="tool-toggle">
              <label class="switch">
                <input type="checkbox" checked data-tool="create-ppt">
                <span class="slider"></span>
              </label>
            </div>
            <div class="tool-info">
              <h4>PowerPoint Creator</h4>
              <p>Creates presentation slides</p>
              <div class="tool-meta">
                <span class="category-badge">Creation</span>
                <span class="usage-count">Used 145 times</span>
              </div>
            </div>
            <div class="tool-actions">
              <button class="btn-icon" title="Configure">⚙️</button>
              <button class="btn-icon" title="View Logs">📊</button>
            </div>
          </div>
        </div>
      </div>
      
      <!-- Risk Group: High -->
      <div class="risk-group">
        <h3 class="risk-header">
          <span class="risk-indicator high">●</span>
          High Risk Tools
          <span class="warning-badge">⚠️ Requires Confirmation</span>
        </h3>
        <div class="tools-in-group">
          <div class="tool-item disabled">
            <div class="tool-toggle">
              <label class="switch">
                <input type="checkbox" data-tool="delete-files">
                <span class="slider"></span>
              </label>
            </div>
            <div class="tool-info">
              <h4>File Deletion Tool</h4>
              <p>Permanently deletes files</p>
              <div class="disabled-reason">
                ⚠️ Disabled for safety - enable only when needed
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
    
    <!-- Global Settings -->
    <div class="global-settings">
      <h3>Global Settings</h3>
      <div class="settings-grid">
        <label class="setting-item">
          <input type="checkbox" id="global-confirmation" checked>
          <span>Require confirmation for all tools</span>
        </label>
        <label class="setting-item">
          <input type="checkbox" id="audit-logging" checked>
          <span>Enable audit logging</span>
        </label>
        <label class="setting-item">
          <input type="checkbox" id="rate-limiting" checked>
          <span>Enable rate limiting</span>
        </label>
        <label class="setting-item">
          <input type="checkbox" id="maintenance-mode">
          <span>Maintenance mode (disable all tools)</span>
        </label>
      </div>
    </div>
    
    <!-- Save Actions -->
    <div class="modal-footer">
      <button class="btn btn-primary" id="save-permissions">
        💾 Save Changes
      </button>
      <button class="btn btn-secondary" id="export-config">
        📤 Export Configuration
      </button>
      <button class="btn btn-secondary" id="view-audit-log">
        📋 View Audit Log
      </button>
    </div>
  </div>
</div>

CSS Styling

/* Risk Level Indicators */
.risk-indicator {
  display: inline-block;
  width: 12px;
  height: 12px;
  border-radius: 50%;
  margin-right: 8px;
}

.risk-indicator.low { background: #10b981; }
.risk-indicator.medium { background: #f59e0b; }
.risk-indicator.high { background: #ef4444; }
.risk-indicator.critical { 
  background: #991b1b;
  animation: pulse 2s infinite;
}

/* Tool Toggle Switch */
.switch {
  position: relative;
  width: 60px;
  height: 28px;
}

.switch input {
  opacity: 0;
  width: 0;
  height: 0;
}

.slider {
  position: absolute;
  cursor: pointer;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: #ccc;
  transition: .4s;
  border-radius: 28px;
}

.slider:before {
  position: absolute;
  content: "";
  height: 20px;
  width: 20px;
  left: 4px;
  bottom: 4px;
  background-color: white;
  transition: .4s;
  border-radius: 50%;
}

input:checked + .slider {
  background-color: #10b981;
}

input:checked + .slider:before {
  transform: translateX(32px);
}

/* Disabled State */
.tool-item.disabled {
  opacity: 0.6;
  background: #f9fafb;
}

.disabled-reason {
  color: #ef4444;
  font-size: 0.875rem;
  margin-top: 4px;
  padding: 4px 8px;
  background: #fef2f2;
  border-radius: 4px;
}

Security Implementation

Permission Service

class ToolPermissionService {
  constructor() {
    this.configPath = '/config/tool-permissions.json';
    this.rolesPath = '/config/user-roles.json';
    this.permissions = null;
    this.roles = null;
    this.cache = new Map();
    this.loadConfigurations();
  }
  
  async loadConfigurations() {
    this.permissions = await this.loadJson(this.configPath);
    this.roles = await this.loadJson(this.rolesPath);
  }
  
  async checkPermission(userId, toolId, context = {}) {
    // Get from cache if available
    const cacheKey = `${userId}:${toolId}`;
    if (this.cache.has(cacheKey)) {
      const cached = this.cache.get(cacheKey);
      if (Date.now() - cached.timestamp < 60000) { // 1 minute cache
        return cached.result;
      }
    }
    
    // Perform permission check
    const result = await this.performPermissionCheck(userId, toolId, context);
    
    // Cache result
    this.cache.set(cacheKey, {
      result,
      timestamp: Date.now()
    });
    
    return result;
  }
  
  async performPermissionCheck(userId, toolId, context) {
    // Get user role
    const userRole = this.getUserRole(userId);
    if (!userRole) {
      return { allowed: false, reason: 'No role assigned' };
    }
    
    // Get tool configuration
    const tool = this.getTool(toolId);
    if (!tool) {
      return { allowed: false, reason: 'Tool not found' };
    }
    
    // Check if tool is enabled
    if (!tool.enabled) {
      return { 
        allowed: false, 
        reason: tool.disabledReason || 'Tool is disabled' 
      };
    }
    
    // Check role permissions
    const role = this.roles.roles[userRole];
    
    // Check max risk level
    if (this.getRiskValue(tool.riskLevel) > this.getRiskValue(role.permissions.maxRiskLevel)) {
      return { 
        allowed: false, 
        reason: `Risk level ${tool.riskLevel} exceeds role maximum` 
      };
    }
    
    // Check specific tool allowlist/denylist
    if (role.deniedTools.includes(toolId) || 
        (role.deniedTools.includes('*') && !role.allowedTools.includes(toolId))) {
      return { 
        allowed: false, 
        reason: 'Tool not allowed for role' 
      };
    }
    
    // Check rate limits
    if (this.permissions.globalSettings.rateLimiting.enabled) {
      const limitExceeded = await this.checkRateLimits(userId, toolId, role);
      if (limitExceeded) {
        return { 
          allowed: false, 
          reason: 'Rate limit exceeded',
          retryAfter: limitExceeded.retryAfter 
        };
      }
    }
    
    // Check time restrictions
    if (this.permissions.globalSettings.allowedHours.enabled) {
      if (!this.isWithinAllowedHours()) {
        return { 
          allowed: false, 
          reason: 'Outside allowed hours' 
        };
      }
    }
    
    // Check maintenance mode
    if (this.permissions.globalSettings.maintenanceMode && userRole !== 'admin') {
      return { 
        allowed: false, 
        reason: 'System in maintenance mode' 
      };
    }
    
    // All checks passed
    return {
      allowed: true,
      requiresConfirmation: tool.requiresConfirmation || 
                           this.permissions.globalSettings.requireConfirmation,
      riskLevel: tool.riskLevel,
      permissions: tool.permissions
    };
  }
  
  getRiskValue(level) {
    const values = {
      'none': 0,
      'low': 1,
      'medium': 2,
      'high': 3,
      'critical': 4
    };
    return values[level] || 0;
  }
  
  async updateToolPermission(toolId, updates, adminUser) {
    // Validate admin permission
    const adminRole = this.getUserRole(adminUser);
    if (adminRole !== 'admin') {
      throw new Error('Unauthorized: Admin access required');
    }
    
    // Find and update tool
    const toolIndex = this.permissions.tools.findIndex(t => t.id === toolId);
    if (toolIndex === -1) {
      throw new Error(`Tool ${toolId} not found`);
    }
    
    // Log the change
    await this.logPermissionChange({
      timestamp: new Date().toISOString(),
      adminUser,
      toolId,
      previousState: { ...this.permissions.tools[toolIndex] },
      newState: updates,
      action: 'tool_permission_update'
    });
    
    // Apply updates
    this.permissions.tools[toolIndex] = {
      ...this.permissions.tools[toolIndex],
      ...updates
    };
    
    // Update metadata
    this.permissions.lastModified = new Date().toISOString();
    this.permissions.modifiedBy = adminUser;
    
    // Save configuration
    await this.saveConfiguration();
    
    // Clear cache
    this.cache.clear();
    
    // Broadcast update to all connected clients
    this.broadcastUpdate({
      type: 'permission_update',
      toolId,
      updates
    });
  }
  
  async checkRateLimits(userId, toolId, role) {
    const now = Date.now();
    const hourAgo = now - 3600000;
    const dayAgo = now - 86400000;
    
    // Get usage history
    const usage = await this.getUsageHistory(userId, toolId);
    
    // Calculate limits with role multiplier
    const multiplier = role.rateLimits?.multiplier || 1.0;
    const tool = this.getTool(toolId);
    
    const hourlyLimit = (tool.rateLimits?.maxPerHour || 
                        this.permissions.globalSettings.rateLimiting.maxPerHour) * multiplier;
    const dailyLimit = (tool.rateLimits?.maxPerDay || 
                       this.permissions.globalSettings.rateLimiting.maxPerDay) * multiplier;
    
    // Count recent usage
    const hourlyUsage = usage.filter(u => u.timestamp > hourAgo).length;
    const dailyUsage = usage.filter(u => u.timestamp > dayAgo).length;
    
    // Check limits
    if (hourlyUsage >= hourlyLimit) {
      const oldestHourly = usage.filter(u => u.timestamp > hourAgo)[0];
      return {
        exceeded: true,
        retryAfter: oldestHourly.timestamp + 3600000 - now,
        limit: 'hourly'
      };
    }
    
    if (dailyUsage >= dailyLimit) {
      const oldestDaily = usage.filter(u => u.timestamp > dayAgo)[0];
      return {
        exceeded: true,
        retryAfter: oldestDaily.timestamp + 86400000 - now,
        limit: 'daily'
      };
    }
    
    return null;
  }
}

Audit Logging

Permission Change Logging

class PermissionAuditLogger {
  constructor() {
    this.logPath = '/logs/permission-audit.jsonl';
  }
  
  async logPermissionChange(event) {
    const auditEntry = {
      id: uuid(),
      timestamp: event.timestamp,
      category: 'permission_change',
      actor: {
        userId: event.adminUser,
        role: 'admin',
        ip: event.ipAddress
      },
      action: event.action,
      target: {
        type: 'tool',
        id: event.toolId
      },
      changes: this.diffChanges(event.previousState, event.newState),
      previousState: event.previousState,
      newState: event.newState,
      metadata: {
        userAgent: event.userAgent,
        sessionId: event.sessionId
      }
    };
    
    // Write to audit log
    await this.appendToLog(auditEntry);
    
    // Send to activity logger
    await activityLogger.log({
      action: 'permission_changed',
      category: 'permission_management',
      data: auditEntry
    });
    
    // Trigger alerts if needed
    if (this.isHighRiskChange(auditEntry)) {
      await this.alertAdmins(auditEntry);
    }
  }
  
  diffChanges(previous, current) {
    const changes = [];
    
    for (const key in current) {
      if (JSON.stringify(previous[key]) !== JSON.stringify(current[key])) {
        changes.push({
          field: key,
          from: previous[key],
          to: current[key]
        });
      }
    }
    
    return changes;
  }
  
  isHighRiskChange(entry) {
    // Alert on critical tool enablement
    if (entry.newState.riskLevel === 'critical' && entry.newState.enabled) {
      return true;
    }
    
    // Alert on mass permission changes
    if (entry.changes.length > 5) {
      return true;
    }
    
    // Alert on security setting changes
    if (entry.changes.some(c => c.field === 'requiresAdminRole' || 
                                c.field === 'requiresMFA')) {
      return true;
    }
    
    return false;
  }
}

Best Practices

Security Guidelines

1. Principle of Least Privilege

   • Start with minimal permissions
   • Grant additional access as needed
   • Regular permission audits

2. Risk-Based Controls

   • Higher risk = more restrictions
   • Critical tools require admin approval
   • Automatic alerts for high-risk operations

3. Separation of Duties

   • Different roles for different responsibilities
   • No single user with all permissions
   • Require multiple approvals for critical changes

4. Defense in Depth

   • Multiple layers of security
   • Rate limiting + confirmation + audit
   • Fail-safe defaults

Administrative Guidelines

1. Regular Reviews

   • Weekly: Check disabled tools
   • Monthly: Review permission changes
   • Quarterly: Full permission audit

2. Documentation

   • Document why tools are disabled
   • Record permission change justifications
   • Maintain role assignment records

3. Training

   • Train admins on permission system
   • Educate users on available tools
   • Regular security awareness updates

4. Monitoring

   • Watch for permission bypass attempts
   • Track unusual usage patterns
   • Alert on critical changes

Metrics & Reporting

Permission Analytics

class PermissionAnalytics {
  async generateReport(startDate, endDate) {
    return {
      summary: {
        totalTools: this.countTools(),
        enabledTools: this.countEnabledTools(),
        disabledTools: this.countDisabledTools(),
        riskDistribution: this.getRiskDistribution()
      },
      usage: {
        mostUsedTools: await this.getMostUsedTools(10),
        leastUsedTools: await this.getLeastUsedTools(10),
        deniedRequests: await this.getDeniedRequests(),
        rateLimitHits: await this.getRateLimitHits()
      },
      changes: {
        permissionChanges: await this.getPermissionChanges(startDate, endDate),
        toolEnablements: await this.getToolEnablements(startDate, endDate),
        roleChanges: await this.getRoleChanges(startDate, endDate)
      },
      security: {
        highRiskUsage: await this.getHighRiskUsage(),
        failedAttempts: await this.getFailedAttempts(),
        suspiciousActivity: await this.detectSuspiciousActivity()
      }
    };
  }
}

Implementation Checklist

Phase 1: Setup

• Create permission configuration files
• Implement permission service
• Set up audit logging
• Create role definitions

Phase 2: Integration

• Integrate with tool executor
• Add permission checks to AI service
• Implement rate limiting
• Add confirmation workflows

Phase 3: UI Development

• Build admin interface
• Create permission toggles
• Add audit log viewer
• Implement real-time updates

Phase 4: Testing

• Test permission enforcement
• Verify rate limiting
• Check audit logging
• Security penetration testing

Phase 5: Deployment

• Deploy configuration
• Train administrators
• Document procedures
• Monitor initial usage

---

This comprehensive permission system ensures secure, controlled, and auditable access to all Sasha tools while maintaining flexibility for different use cases and user roles.