Tag Permission System - Admin Guide

Quick reference guide for administrators managing the tag permission system.

Quick Start

1. Access Admin Interface

Visit /admin/tags in your application to access the comprehensive tag management system.

Click the “Quick Setup” button to automatically create essential tags:

  • admin-tools: Administrative tools and system management (e.g., code_execution)
  • beta-testers: Beta features and experimental tools
  • company-wide: Tools available to all company members

3. Create Custom Tags

Use the “Create Tag” button or the examples below to create department-specific or role-based tags. Example Finance Department Tag:

{
  name: 'finance-dept',
  description: 'Finance department tools and assistants',
  accessControl: {
    type: 'specific',
    emails: ['alice@company.com', 'bob@company.com', 'finance-manager@company.com']
  }
}

4. Tag a Tool

Update the tool definition in src/components/ToolSelector.tsx:

{
  id: 'financial-analyzer',
  name: 'Financial Analyzer',
  tags: ['finance-dept'], // Add this line
  // ... other properties
}

Administrative Interface Features

Admin Tags Dashboard (/admin/tags)

The admin interface provides comprehensive tag management:

Quick Setup Button

  • Creates three essential tags automatically
  • Skips existing tags to prevent duplicates
  • Perfect for initial system setup

Tag Management

  • Create: Use the dialog to create custom tags with specific access controls
  • Edit: Click the edit icon on any tag to modify settings
  • Delete: Remove tags with confirmation dialog
  • View: See tag details, access lists, and metadata

Access Control Types

  • Specific Emails: Exact email addresses (most secure)
  • Domain: All users from a domain (e.g., @finance.company.com)
  • Multiple Domains: Users from multiple domains
  • Groups: Predefined groups (requires setup in src/lib/groups.ts)
  • Public: Available to all authenticated users

Common Administrative Tasks

  1. Visit /admin/tags - Access the admin dashboard
  2. Click “Quick Setup” - Create essential tags automatically
  3. Create custom tags - Use the “Create Tag” button for specific needs
  4. Edit existing tags - Click edit icon to modify access controls
  5. Monitor usage - Review tag lists and access patterns

Creating Tags via Firestore Console (Advanced)

  1. Navigate to Firestore Console
    • Go to Firebase Console → Firestore Database
    • Select the tags collection (create if it doesn’t exist)
  2. Add Document with Auto-ID 
    {
  "id": "", 
  "name": "team-leads",
  "description": "Team leaders and managers",
  "accessControl": {
    "type": "specific",
    "emails": [
      "manager1@company.com",
      "manager2@company.com", 
      "director@company.com"
    ]
  },
  "createdBy": "admin@company.com",
  "createdAt": 1703875200000,
  "updatedAt": 1703875200000
}
  3. Set Document ID
    • After creating, edit the document
    • Set the id field to match the document ID

Bulk Tag Creation

For large organizations, you may prefer to create multiple tags programmatically. The admin interface handles most use cases, but here’s a script for bulk operations:

// scripts/manageTags.ts
import FirebaseService from '@/lib/firebase';

export async function createCompanyTags() {
  const tags = [
    // Admin tags
    {
      name: 'admin-tools',
      description: 'Administrative tools and system management',
      accessControl: { type: 'specific', emails: ['admin@company.com'] },
      createdBy: 'admin@company.com'
    },
    
    // Department tags
    {
      name: 'finance',
      description: 'Finance department resources',
      accessControl: { type: 'domain', domain: 'finance.company.com' },
      createdBy: 'admin@company.com'
    },
    
    {
      name: 'hr',
      description: 'Human resources tools',
      accessControl: { 
        type: 'specific', 
        emails: ['hr1@company.com', 'hr2@company.com'] 
      },
      createdBy: 'admin@company.com'
    },
    
    {
      name: 'engineering',
      description: 'Engineering and development tools',
      accessControl: { type: 'domain', domain: 'eng.company.com' },
      createdBy: 'admin@company.com'
    },
    
    // Access level tags
    {
      name: 'managers',
      description: 'Management level access',
      accessControl: { type: 'group', groups: ['managers'] },
      createdBy: 'admin@company.com'
    },
    
    {
      name: 'beta-testers',
      description: 'Beta feature access',
      accessControl: { 
        type: 'specific',
        emails: [
          'beta1@company.com', 
          'beta2@company.com',
          'product-manager@company.com'
        ]
      },
      createdBy: 'admin@company.com'
    }
  ];

  for (const tag of tags) {
    try {
      const tagId = await FirebaseService.createTag(tag);
      console.log(`Created tag: ${tag.name} (${tagId})`);
    } catch (error) {
      console.error(`Failed to create tag ${tag.name}:`, error);
    }
  }
}

// Run the script
createCompanyTags();

Using Tags to Restrict Tool Access

Tags can be used to control which users have access to specific tools. Here’s how:

1. Tag a Tool

Tools can be tagged in their definition in ToolSelector.tsx:

{
  id: 'code_execution',
  name: 'Code Execution',
  description: 'Execute code to help inform answers',
  tags: ['beta-testers'], // Only users with access to beta-testers tag can use this
  // ... other properties
}

2. Multiple Tags (OR Logic)

Tools can have multiple tags - users need access to at least ONE tag:

{
  id: 'aitana-agent',
  name: 'Aitana Agents',
  tags: ['beta-testers', 'admin-tools'], // Users need EITHER tag
  // ... other properties
}

3. Common Tool Restrictions

Beta Features

tags: ['beta-testers']  // For tools in testing phase

Admin-Only Tools

tags: ['admin-tools']   // For dangerous or system tools

Department-Specific Tools

tags: ['finance-team']  // For finance department tools

4. Tool Access Behavior

  • No tags: Tool is available to everyone
  • With tags: Users must have access to at least one tag
  • Tool visibility: Tools without access are hidden from the UI
  • Owner override: Assistant owners can always use all tools

Using Tags for Configuration Options

Tags can control not just tool access, but also which configuration options users see within tools.

1. Restricting File Browser Buckets

options: [
  { label: 'Aitana Public Bucket', value: 'aitana-public-bucket' }, // Public
  { label: 'Aitana Documents Bucket', value: 'aitana-documents-bucket', 
    tags: ['company-wide', 'internal-access'] }, // Internal only
  { label: 'Finance Reports Bucket', value: 'finance-reports-bucket', 
    tags: ['finance-team', 'admin-tools'] }, // Finance only
]

2. Restricting Vertex Search Datastores

options: [
  { label: 'Aitana Public Welcome', value: 'aitana_public_welcome' }, // Public
  { label: 'Our New Energy Documents', value: 'aitana3', 
    tags: ['energy-team', 'company-wide'] }, // Energy team
  { label: 'Legal Documents', value: 'legal_docs', 
    tags: ['legal-team', 'admin-tools'] }, // Legal only
]

3. Configuration Option Behavior

  • No tags on option: Available to everyone who can access the tool
  • Tags on option: User needs at least one of the option’s tags
  • Hidden options: Options without access don’t appear in dropdowns
  • Seamless experience: Users only see what they can use

4. Example Tag Setup for Teams

Finance Team

{
  "name": "finance-team",
  "description": "Access to financial tools and data",
  "accessControl": {
    "type": "specific",
    "emails": ["cfo@company.com", "accountant@company.com"]
  }
}

Grants access to: Finance buckets, financial datastores, finance presets

Engineering Team

{
  "name": "engineering-team",
  "description": "Access to engineering resources",
  "accessControl": {
    "type": "domain",
    "domain": "eng.company.com"
  }
}

Grants access to: Engineering buckets, technical documentation, code repositories

See Tag-Based Tool Configuration for detailed implementation guide.

Tool Tagging Reference

Tools That Should Be Restricted

High-Risk Tools (Admin Only)

const adminOnlyTools = [
  'code_execution',      // Can execute arbitrary code
  'system-monitor',      // System access
  'user-manager',        // User data access
  'database-admin'       // Database access
];

// Tag them with admin-tools
adminOnlyTools.forEach(toolId => {
  // Update in AVAILABLE_TOOLS array
  const tool = AVAILABLE_TOOLS.find(t => t.id === toolId);
  if (tool) tool.tags = ['admin-tools'];
});

Department-Specific Tools

// Finance tools
const financeTools = ['budget-analyzer', 'expense-tracker', 'financial-reports'];
financeTools.forEach(toolId => {
  const tool = AVAILABLE_TOOLS.find(t => t.id === toolId);
  if (tool) tool.tags = ['finance'];
});

// HR tools
const hrTools = ['employee-directory', 'performance-tracker', 'payroll-assistant'];
hrTools.forEach(toolId => {
  const tool = AVAILABLE_TOOLS.find(t => t.id === toolId);
  if (tool) tool.tags = ['hr'];
});

Beta/Experimental Tools

const betaTools = ['ai-code-review', 'smart-scheduling', 'predictive-analytics'];
betaTools.forEach(toolId => {
  const tool = AVAILABLE_TOOLS.find(t => t.id === toolId);
  if (tool) tool.tags = ['beta-testers'];
});

Access Control Patterns

1. Email-Based Access (Most Secure)

{
  "accessControl": {
    "type": "specific",
    "emails": [
      "user1@company.com",
      "user2@company.com"
    ]
  }
}

Use for: Admin tools, sensitive features, individual access

2. Domain-Based Access

{
  "accessControl": {
    "type": "domain",
    "domain": "engineering.company.com"
  }
}

Use for: Department-wide access with subdomains

3. Multi-Domain Access

{
  "accessControl": {
    "type": "domains", 
    "domains": [
      "finance.company.com",
      "accounting.company.com"
    ]
  }
}

Use for: Related departments or multiple offices

4. Group-Based Access

{
  "accessControl": {
    "type": "group",
    "groups": ["managers", "directors"]
  }
}

Use for: Role-based access (requires group setup in src/lib/groups.ts)

5. Public Access

{
  "accessControl": {
    "type": "public"
  }
}

Use for: Company-wide tools, general utilities

Monitoring and Maintenance

Regular Tasks

1. Weekly Review

  • Check new user access requests
  • Review tag usage in analytics
  • Update group memberships

2. Monthly Audit

  • Review all tag permissions
  • Check for unused tags
  • Validate email addresses still active

3. Quarterly Cleanup

  • Remove access for departed employees
  • Archive old tags
  • Update tool categorizations

Validation Commands

Check Tag Status

// Get all tags and their usage
const tags = await FirebaseService.getAllTags();
tags.forEach(tag => {
  console.log(`Tag: ${tag.name}`);
  console.log(`  Type: ${tag.accessControl.type}`);
  console.log(`  Users: ${tag.accessControl.emails?.length || 0}`);
  console.log(`  Created: ${new Date(tag.createdAt).toLocaleDateString()}`);
});

Check User Access

// Check what a specific user can access
const userEmail = 'user@company.com';
const user = { email: userEmail }; // Mock user object
const accessibleTags = getAccessibleTags(tags, user);
console.log(`${userEmail} can access:`, accessibleTags.map(t => t.name));

Audit Tool Access

// Check which tools are restricted
const restrictedTools = AVAILABLE_TOOLS.filter(tool => tool.tags && tool.tags.length > 0);
console.log('Restricted tools:');
restrictedTools.forEach(tool => {
  console.log(`  ${tool.name}: ${tool.tags.join(', ')}`);
});

Security Best Practices

1. Tag Creation

  • ✅ Use descriptive, clear tag names
  • ✅ Include detailed descriptions
  • ✅ Start with restrictive access, expand as needed
  • ❌ Don’t create overly broad tags
  • ❌ Don’t use generic names like “users” or “access”

2. Access Control

  • ✅ Use specific emails for sensitive tools
  • ✅ Use domain access for department tools
  • ✅ Regular audit of access lists
  • ❌ Don’t use public access for sensitive tools
  • ❌ Don’t forget to remove access for former employees

3. Tool Tagging

  • ✅ Tag all sensitive/powerful tools
  • ✅ Use multiple tags for complex access patterns
  • ✅ Document why tools are tagged
  • ❌ Don’t leave powerful tools untagged
  • ❌ Don’t over-tag basic utility tools

Troubleshooting

Common Issues

User Can’t See Expected Tool

  1. Check if tool has tags: Look in AVAILABLE_TOOLS array
  2. Verify user has tag access: Use debug commands above
  3. Check tag exists: Verify in Firestore console
  4. Validate email match: Check exact email spelling

Tool Visible to Wrong Users

  1. Check tag access control settings
  2. Verify tool tag assignments
  3. Check for typos in email addresses
  4. Validate domain settings

Performance Issues

  1. Check number of tags (limit to <100 for performance)
  2. Monitor Firestore read operations
  3. Consider caching strategies for large user bases

Emergency Access

Temporarily Disable Tag Restrictions

// In ToolSelector.tsx, comment out the tag filtering:
// const filtered = AVAILABLE_TOOLS.filter(tool => {
//   if (!tool.tags || tool.tags.length === 0) return true;
//   return checkTagAccess(tool.tags, availableTags, user);
// });

// Use this instead:
const filtered = AVAILABLE_TOOLS; // Show all tools

Grant Emergency Access

Add user to admin-tools tag temporarily:

{
  "accessControl": {
    "type": "specific",
    "emails": [
      "admin@company.com",
      "emergency-user@company.com"  // Add temporarily
    ]
  }
}

Getting Started Checklist

Initial Setup

  • Visit /admin/tags interface
  • Click “Quick Setup” to create essential tags
  • Verify tags were created successfully
  • Test access by viewing the tag list

Configure Tools

  • Review src/components/ToolSelector.tsx for tools needing restrictions
  • Add tags: ['admin-tools'] to sensitive tools (e.g., code_execution)
  • Add appropriate tags to department-specific tools
  • Test tool visibility with different user accounts

Ongoing Management

  • Review user access requests weekly
  • Update tag permissions as team changes
  • Monitor tag usage and effectiveness
  • Remove access for departed team members

Contact and Support

For tag permission issues:

  1. Use the admin interface first - /admin/tags for most operations
  2. Check this documentation for common patterns and solutions
  3. Use debug commands to diagnose access issues
  4. Review Firestore console for direct tag data inspection
  5. Contact system administrator with specific error details

Remember: The tag system is designed to be secure by default. When in doubt, be more restrictive rather than permissive.