Vapora/docs/architecture/roles-permissions-profiles.md

👥 Roles, Permissions & Profiles

Cedar-Based Access Control for Multi-Agent Teams

Version: 0.1.0 Status: Specification (VAPORA v1.0 - Authorization) Purpose: Fine-grained RBAC + team profiles for agents and humans

---

🎯 Objetivo

Sistema de autorización multinivel basado en Cedar Policy Engine (de provisioning):

• ✅ 12 roles especializados (agentes + humanos)
• ✅ Perfiles agrupando roles (equipos)
• ✅ Políticas granulares (resource-level, context-aware)
• ✅ Audit trail completo
• ✅ Dynamic policy reload (sin restart)

---

👥 Los 12 Roles (+ Admin/Guest)

Technical Roles

Architect

• Permisos: Create ADRs, propose decisions, review architecture
• Restricciones: Can't deploy, can't approve own decisions
• Resources: Design documents, ADR files, architecture diagrams

Developer

• Permisos: Create code, push to dev branches, request reviews
• Restricciones: Can't merge to main, can't delete
• Resources: Code files, dev branches, PR creation

CodeReviewer

• Permisos: Comment on PRs, approve/request changes, merge to dev
• Restricciones: Can't approve own code, can't force push
• Resources: PRs, review comments, dev branches

Tester

• Permisos: Create/modify tests, run benchmarks, report issues
• Restricciones: Can't deploy, can't modify code outside tests
• Resources: Test files, benchmark results, issue reports

Documentation Roles

Documenter

• Permisos: Modify docs/, README, CHANGELOG, update docs/adr/
• Restricciones: Can't modify source code
• Resources: docs/ directory, markdown files

Marketer

• Permisos: Create marketing content, modify website
• Restricciones: Can't modify code, docs, or infrastructure
• Resources: marketing/, website, blog posts

Presenter

• Permisos: Create presentations, record demos
• Restricciones: Read-only on all code
• Resources: presentations/, demo assets

Operations Roles

DevOps

• Permisos: Approve PRs for deployment, trigger CI/CD, modify manifests
• Restricciones: Can't modify business logic, can't delete environments
• Resources: Kubernetes manifests, CI/CD configs, deployment status

Monitor

• Permisos: View all metrics, create alerts, read logs
• Restricciones: Can't modify infrastructure
• Resources: Monitoring dashboards, alert rules, logs

Security

• Permisos: Scan code, audit logs, block PRs if critical vulnerabilities
• Restricciones: Can't approve deployments
• Resources: Security scans, audit logs, vulnerability database

Management Roles

ProjectManager

• Permisos: View all tasks, update roadmap, assign work
• Restricciones: Can't merge code, can't approve technical decisions
• Resources: Tasks, roadmap, timelines

DecisionMaker

• Permisos: Approve critical decisions, resolve conflicts
• Restricciones: Can't implement decisions
• Resources: Decision queue, escalations

Orchestrator

• Permisos: Assign agents to tasks, coordinate workflows
• Restricciones: Can't execute tasks directly
• Resources: Agent registry, task queue, workflows

Default Roles

Admin

• Permisos: Everything
• Restricciones: None
• Resources: All

Guest

• Permisos: Read public docs, view public status
• Restricciones: Can't modify anything
• Resources: Public docs, public dashboards

---

🏢 Perfiles (Team Groupings)

Frontend Team

[profile]
name = "Frontend Team"
members = ["alice@example.com", "bob@example.com", "developer-frontend-001"]

roles = ["Developer", "CodeReviewer", "Tester"]
permissions = [
    "create_pr_frontend",
    "review_pr_frontend",
    "test_frontend",
    "commit_dev_branch",
]
resource_constraints = [
    "path_prefix:frontend/",
]

Backend Team

[profile]
name = "Backend Team"
members = ["charlie@example.com", "developer-backend-001", "developer-backend-002"]

roles = ["Developer", "CodeReviewer", "Tester", "Security"]
permissions = [
    "create_pr_backend",
    "review_pr_backend",
    "test_backend",
    "security_scan",
]
resource_constraints = [
    "path_prefix:backend/",
    "exclude_path:backend/secrets/",
]

Full Stack Team

[profile]
name = "Full Stack Team"
members = ["alice@example.com", "architect-001", "reviewer-001"]

roles = ["Architect", "Developer", "CodeReviewer", "Tester", "Documenter"]
permissions = [
    "design_features",
    "implement_features",
    "review_code",
    "test_features",
    "document_features",
]

DevOps Team

[profile]
name = "DevOps Team"
members = ["devops-001", "devops-002", "security-001"]

roles = ["DevOps", "Monitor", "Security"]
permissions = [
    "trigger_ci_cd",
    "deploy_staging",
    "deploy_production",
    "modify_manifests",
    "monitor_health",
    "security_audit",
]

Management

[profile]
name = "Management"
members = ["pm-001", "decision-maker-001", "orchestrator-001"]

roles = ["ProjectManager", "DecisionMaker", "Orchestrator"]
permissions = [
    "create_tasks",
    "assign_agents",
    "make_decisions",
    "view_metrics",
]

---

🔐 Cedar Policies (Authorization Rules)

Policy Structure

// Policy: Only CodeReviewers can approve PRs
permit(
    principal in Role::"CodeReviewer",
    action == Action::"approve_pr",
    resource
) when {
    // Can't approve own PR
    principal != resource.author
    && principal.team == resource.team
};

// Policy: Developers can only commit to dev branches
permit(
    principal in Role::"Developer",
    action == Action::"commit",
    resource in Branch::"dev"
) when {
    resource.protection_level == "standard"
};

// Policy: Security can block PRs if critical vulns found
permit(
    principal in Role::"Security",
    action == Action::"block_pr",
    resource
) when {
    resource.vulnerability_severity == "critical"
};

// Policy: DevOps can only deploy approved code
permit(
    principal in Role::"DevOps",
    action == Action::"deploy",
    resource
) when {
    resource.approved_by.has_element(principal)
    && resource.tests_passing == true
};

// Policy: Monitor can view all logs (read-only)
permit(
    principal in Role::"Monitor",
    action == Action::"view_logs",
    resource
);

// Policy: Documenter can only modify docs/
permit(
    principal in Role::"Documenter",
    action == Action::"modify",
    resource
) when {
    resource.path.starts_with("docs/")
    || resource.path == "README.md"
    || resource.path == "CHANGELOG.md"
};

Dynamic Policies (Hot Reload)

# vapora.toml
[authorization]
cedar_policies_path = ".vapora/policies/"
reload_interval_secs = 30
enable_audit_logging = true

# .vapora/policies/custom-rules.cedar
// Custom rule: Only Architects from Backend Team can design backend features
permit(
    principal in Team::"Backend Team",
    action == Action::"design_architecture",
    resource in ResourceType::"backend_feature"
) when {
    principal.role == Role::"Architect"
};

---

🔍 Audit Trail

Audit Log Entry

pub struct AuditLogEntry {
    pub id: String,
    pub timestamp: DateTime<Utc>,
    pub principal_id: String,
    pub principal_type: String,  // "agent" or "human"
    pub action: String,
    pub resource: String,
    pub result: AuditResult,     // Permitted, Denied, Error
    pub reason: String,
    pub context: HashMap<String, String>,
}

pub enum AuditResult {
    Permitted,
    Denied { reason: String },
    Error { error: String },
}

Audit Retention Policy

[audit]
retention_days = 2555          # 7 years for compliance
export_formats = ["json", "csv", "syslog"]
sensitive_fields = ["api_key", "password", "token"]  # Redact these

---

🚀 Implementation

Cedar Policy Engine Integration

pub struct AuthorizationEngine {
    pub cedar_schema: cedar_policy_core::Schema,
    pub policies: cedar_policy_core::PolicySet,
    pub audit_log: Vec<AuditLogEntry>,
}

impl AuthorizationEngine {
    pub async fn check_permission(
        &mut self,
        principal: Principal,
        action: Action,
        resource: Resource,
        context: Context,
    ) -> anyhow::Result<AuthorizationResult> {
        let request = cedar_policy_core::Request::new(
            principal,
            action,
            resource,
            context,
        );

        let response = self.policies.evaluate(&request);

        let allowed = response.decision == Decision::Allow;
        let reason = response.reason.join(", ");

        let entry = AuditLogEntry {
            id: uuid::Uuid::new_v4().to_string(),
            timestamp: Utc::now(),
            principal_id: principal.id,
            principal_type: principal.principal_type.to_string(),
            action: action.name,
            resource: resource.id,
            result: if allowed {
                AuditResult::Permitted
            } else {
                AuditResult::Denied { reason: reason.clone() }
            },
            reason,
            context: Default::default(),
        };

        self.audit_log.push(entry);

        Ok(AuthorizationResult { allowed, reason })
    }

    pub async fn hot_reload_policies(&mut self) -> anyhow::Result<()> {
        // Read .vapora/policies/ and reload
        // Notify all agents of policy changes
        Ok(())
    }
}

Context-Aware Authorization

pub struct Context {
    pub time: DateTime<Utc>,
    pub ip_address: String,
    pub environment: String,  // "dev", "staging", "prod"
    pub is_business_hours: bool,
    pub request_priority: Priority,  // Low, Normal, High, Critical
}

// Policy example: Can only deploy to prod during business hours
permit(
    principal in Role::"DevOps",
    action == Action::"deploy_production",
    resource
) when {
    context.is_business_hours == true
    && context.environment == "production"
};

---

🎯 Implementation Checklist

• Define Principal (agent_id, role, team, profile)
• Define Action (create_pr, approve, deploy, etc.)
• Define Resource (PR, code file, branch, deployment)
• Implement Cedar policy evaluation
• Load policies from .vapora/policies/
• Implement hot reload (30s interval)
• Audit logging for every decision
• CLI: vapora auth check --principal X --action Y --resource Z
• CLI: vapora auth policies list/reload
• Audit log export (JSON, CSV)
• Tests (policy enforcement)

---

📊 Success Metrics

✅ Policy evaluation < 10ms ✅ Hot reload works without restart ✅ Audit log complete and queryable ✅ Multi-team isolation working ✅ Context-aware rules enforced ✅ Deny reasons clear and actionable

---

Version: 0.1.0 Status: ✅ Specification Complete (VAPORA v1.0) Purpose: Cedar-based authorization for multi-agent multi-team platform