Permissions & Contrôle d'Accès

Contrôle d'accès basé sur les rôles (RBAC) enterprise-ready pour agents IA.Permissions, journalisation d'audit et gestion d'équipes pour unegouvernance sécurisée des agents.

OrkaJS fournit un système complet de contrôle d'accès basé sur les rôles (RBAC) pour gérer qui peut accéder, exécuter, modifier et cloner vos agents IA. Combiné avec la journalisation d'audit, vous obtenez une traçabilité complète pour la conformité entreprise.

Actions de Permission

read, execute, edit, clone, delete, admin

Types de Principaux

user, team, role, service

Accès Conditionnel

Plages horaires, liste blanche IP, limites de débit

Journalisation d'Audit

Traçabilité complète de toutes les actions

Démarrage Rapide

import { 
  PermissionManager, 
  AuditLogger,
  globalPermissionManager,
  globalAuditLogger 
} from '@orka-js/agent';
 
// Create managers (or use global instances)
const permissions = new PermissionManager();
const audit = new AuditLogger();
 
// Set permissions for an agent
permissions.setPermissions('sales-agent', {
  agentId: 'sales-agent',
  owner: 'user:admin',
  rules: [
    { action: 'read', principals: ['team:sales', 'team:marketing'] },
    { action: 'execute', principals: ['role:sales-rep'] },
    { action: 'edit', principals: ['role:admin'] },
    { action: 'clone', principals: ['role:developer'] }
  ]
});
 
// Register user memberships
permissions.registerPrincipalMemberships('user:john', [
  'team:sales',
  'role:sales-rep'
]);
 
// Check permission
const result = permissions.check({
  principal: { type: 'user', id: 'john' },
  action: 'execute',
  agentId: 'sales-agent'
});
 
if (result.allowed) {
  // Execute agent and log
  audit.logAgentExecuted(
    { type: 'user', id: 'john' },
    'sales-agent',
    'success',
    { input: 'Qualify lead', output: 'Lead qualified' }
  );
} else {
  // Log access denied
  audit.logAccessDenied(
    { type: 'user', id: 'john' },
    'sales-agent',
    'execute',
    result.reason
  );
}

Actions de Permission

Action	Description
`read`	Voir les détails et la configuration de l'agent
`execute`	Exécuter l'agent avec des entrées
`edit`	Modifier la configuration de l'agent
`clone`	Créer une copie de l'agent
`delete`	Supprimer l'agent
`admin`	Contrôle total (propriétaire uniquement)

Types de Principaux

Les principaux sont des entités qui peuvent avoir des permissions. OrkaJS supporte quatre types :

// User - Individual user
{ type: 'user', id: 'john' }
// In rules: 'user:john'
 
// Team - Group of users
{ type: 'team', id: 'sales' }
// In rules: 'team:sales'
 
// Role - Permission role
{ type: 'role', id: 'admin' }
// In rules: 'role:admin'
 
// Service - External service/API
{ type: 'service', id: 'crm-integration' }
// In rules: 'service:crm-integration'
 
// Wildcard - Match all
// In rules: '*' or 'user:*'

Permissions Conditionnelles

Ajoutez des conditions aux règles de permission pour un contrôle d'accès fin :

permissions.setPermissions('sensitive-agent', {
  agentId: 'sensitive-agent',
  owner: 'user:admin',
  rules: [{
    action: 'execute',
    principals: ['team:operations'],
    conditions: [
      // Only during business hours (9 AM - 6 PM)
      {
        type: 'time_range',
        config: {
          allowedHours: { start: 9, end: 18 },
          allowedDays: [1, 2, 3, 4, 5] // Mon-Fri
        }
      },
      // Only from office IPs
      {
        type: 'ip_whitelist',
        config: {
          ips: ['192.168.1.0/24', '10.0.0.1']
        }
      }
    ]
  }]
});
 
// Check with context
const result = permissions.check({
  principal: { type: 'user', id: 'john' },
  action: 'execute',
  agentId: 'sensitive-agent',
  context: {
    ipAddress: '192.168.1.50'
  }
});
 
// Result includes condition evaluation details
console.log(result.evaluatedConditions);

Journalisation d'Audit

Suivez toutes les actions liées aux agents pour la conformité et le débogage :

import { AuditLogger } from '@orka-js/agent';
 
const audit = new AuditLogger({
  maxEvents: 10000,      // Max events to keep in memory
  eventTtlMs: 30 * 24 * 60 * 60 * 1000 // 30 days TTL
});
 
// Log various events
audit.logAgentRegistered(principal, 'new-agent');
audit.logAgentExecuted(principal, 'agent-id', 'success', { input, output });
audit.logAgentCloned(principal, 'source-agent', 'cloned-agent');
audit.logPermissionGranted(principal, 'agent-id', 'execute', ['team:sales']);
audit.logAccessDenied(principal, 'agent-id', 'execute', 'No matching rule');
 
// Query events
const events = audit.query({
  types: ['agent.executed', 'access.denied'],
  agentId: 'sales-agent',
  from: new Date('2025-01-01'),
  limit: 100
});
 
// Get statistics
const stats = audit.getStats();
console.log(stats.totalEvents);
console.log(stats.accessDeniedCount);
console.log(stats.topPrincipals);
console.log(stats.topAgents);
 
// Subscribe to events in real-time
audit.on('access.denied', (event) => {
  console.warn(`Access denied: ${event.principal.id} tried ${event.action} on ${event.agentId}`);
});
 
// Export for compliance
const jsonExport = audit.export();
const csvExport = audit.exportCsv();

Types d'Événements d'Audit

agent.registeredAgent enregistré

agent.updatedAgent mis à jour

agent.deletedAgent supprimé

agent.executedAgent exécuté

agent.clonedAgent cloné

permission.grantedPermission accordée

permission.revokedPermission révoquée

access.allowedAccès autorisé

access.deniedAccès refusé

Exemple d'Intégration Complète

import { 
  AgentRegistry, 
  PermissionManager, 
  AuditLogger,
  ReActAgent 
} from '@orka-js/agent';
import { OpenAIAdapter } from '@orka-js/openai';
 
// Initialize
const registry = new AgentRegistry();
const permissions = new PermissionManager();
const audit = new AuditLogger();
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY });
 
// Register agent
const agent = await registry.register({
  id: 'sales-assistant',
  name: 'Sales Assistant',
  role: 'Lead qualification',
  version: '1.0.0',
  description: 'Qualifies leads and schedules follow-ups',
  metadata: {
    tags: ['sales', 'crm'],
    capabilities: ['email', 'calendar'],
    author: 'user:admin'
  }
}, { goal: 'Qualify leads', tools: [] }, 'react');
 
// Set permissions
permissions.setPermissions('sales-assistant', {
  agentId: 'sales-assistant',
  owner: 'user:admin',
  rules: [
    { action: 'read', principals: ['team:sales', 'team:marketing'] },
    { action: 'execute', principals: ['role:sales-rep', 'role:manager'] },
    { action: 'edit', principals: ['role:admin'] },
    { action: 'clone', principals: ['role:developer'] }
  ]
});
 
// Log registration
audit.logAgentRegistered({ type: 'user', id: 'admin' }, 'sales-assistant');
 
// Execute with permission check
async function executeAgent(userId: string, input: string) {
  const principal = { type: 'user' as const, id: userId };
 
  // Check permission
  const check = permissions.check({
    principal,
    action: 'execute',
    agentId: 'sales-assistant'
  });
 
  if (!check.allowed) {
    audit.logAccessDenied(principal, 'sales-assistant', 'execute', check.reason);
    throw new Error(`Access denied: ${check.reason}`);
  }
 
  audit.logAccessAllowed(principal, 'sales-assistant', 'execute', check.reason);
 
  try {
    const reactAgent = new ReActAgent({
      llm,
      goal: 'Qualify the lead',
      tools: [],
      maxSteps: 5
    });
 
    const result = await reactAgent.run(input);
 
    audit.logAgentExecuted(principal, 'sales-assistant', 'success', {
      input,
      output: result.output,
      steps: result.steps.length
    });
 
    return result;
  } catch (error) {
    audit.logAgentExecuted(principal, 'sales-assistant', 'failure', {
      input,
      error: (error as Error).message
    });
    throw error;
  }
}
 
// Usage
permissions.registerPrincipalMemberships('user:john', ['team:sales', 'role:sales-rep']);
await executeAgent('john', 'Qualify lead: Acme Corp, $50k budget');

Bonnes Pratiques

Utilisez les Équipes et Rôles

Assignez les permissions aux équipes/rôles plutôt qu'aux utilisateurs individuels pour une gestion plus facile.

Principe du Moindre Privilège

Accordez uniquement les permissions minimales nécessaires. Commencez restrictif et ajoutez au besoin.

Toujours Journaliser les Accès Refusés

Suivez les tentatives d'accès refusées pour détecter les problèmes de sécurité potentiels ou les permissions mal configurées.

Utilisez les Conditions pour les Agents Sensibles

Ajoutez des conditions basées sur le temps ou l'IP pour les agents qui gèrent des données sensibles.

Revues d'Audit Régulières

Examinez périodiquement les journaux d'audit et les statistiques pour identifier les patterns inhabituels.

🚀 Prochaines Étapes

Explorez la Plateforme d'Agents pour voir comment les permissions s'intègrent avec le registre :

← Plateforme d'Agents