provisioning/config/cedar-policies/QUICK_REFERENCE.md

# Cedar Authorization Quick Reference

**Version**: 1.0.0 | **Date**: 2025-10-08

---

## 📋 Quick Stats

| Metric | Value |
|--------|-------|
| **Total Policy Lines** | 889 lines |
| **Rust Code Lines** | 2,498 lines |
| **Policy Files** | 4 files (schema + 3 policies) |
| **Test Cases** | 30+ tests |
| **Actions Supported** | 11 actions |
| **Resource Types** | 7 resource types |
| **Team Types** | 5 teams |

---

## 🎯 Policy Files

| File | Lines | Purpose |
|------|-------|---------|
| `schema.cedar` | 221 | Entity/action definitions |
| `production.cedar` | 224 | Production policies (strict) |
| `development.cedar` | 213 | Development policies (relaxed) |
| `admin.cedar` | 231 | Administrative policies |

---

## 🔐 Key Production Policies

| Policy ID | Description | Enforced |
|-----------|-------------|----------|
| `prod-deploy-mfa` | MFA required for deployments | ✅ |
| `prod-deploy-approval` | Approval required for deployments | ✅ |
| `prod-deploy-hours` | Business hours only (08:00-18:00 UTC) | ✅ |
| `prod-delete-mfa` | MFA required for deletions | ✅ |
| `prod-delete-no-force` | No force deletion without emergency approval | ❌ |
| `prod-ip-restriction` | Corporate network only | ✅ |
| `prod-ssh-restricted` | SSH limited to platform-admin/SRE | ✅ |
| `prod-cluster-admin-only` | Only platform-admin manages clusters | ✅ |

---

## 👥 Team Permissions

| Team | Production | Staging | Development |
|------|------------|---------|-------------|
| **platform-admin** | Full access | Full access | Full access |
| **sre** | Deploy, rollback, SSH (with approval) | Deploy, rollback | Full access |
| **developers** | Read-only | Deploy (with approval) | Full access |
| **audit** | Read-only | Read-only | Read-only |
| **security** | Read-only + lockdown | Read-only + lockdown | Read-only |

---

## 🛠️ Actions

| Action | Description | Example Resource |
|--------|-------------|------------------|
| `create` | Create new resources | Server, Cluster, Workspace |
| `delete` | Delete resources | Server, Taskserv, Workflow |
| `update` | Modify existing resources | Server, Cluster |
| `read` | Read resource details | Server, Taskserv |
| `list` | List all resources | Servers, Clusters |
| `deploy` | Deploy infrastructure | Server, Taskserv, Cluster |
| `rollback` | Rollback deployments | Server, Taskserv |
| `ssh` | SSH access | Server |
| `execute` | Execute workflows | Workflow |
| `monitor` | View monitoring data | Server, Cluster |
| `admin` | Administrative operations | All resources |

---

## 📦 Resources

| Resource | Fields | Example |
|----------|--------|---------|
| `Server` | id, hostname, workspace, environment | prod-web-01 |
| `Taskserv` | id, name, workspace, environment | kubernetes, postgres |
| `Cluster` | id, name, workspace, environment, node_count | k8s-cluster (3 nodes) |
| `Workspace` | id, name, environment, owner_id | production-workspace |
| `Workflow` | id, workflow_type, workspace, environment | deployment-workflow |
| `User` | id, email, username, teams | user@example.com |
| `Team` | id, name | platform-admin, developers |

---

## 🧩 Context Variables

| Variable | Type | Required | Example |
|----------|------|----------|---------|
| `mfa_verified` | bool | ✅ | true |
| `ip_address` | string | ✅ | 10.0.0.1 |
| `time` | string (ISO 8601) | ✅ | 2025-10-08T14:30:00Z |
| `approval_id` | string | ❌ | APPROVAL-12345 |
| `reason` | string | ❌ | Emergency hotfix |
| `force` | bool | ❌ | true |
| `ssh_key_fingerprint` | string | ❌ (SSH only) | SHA256:abc123... |

---

## 💻 Usage Examples

### Basic Authorization Check

```rust
use provisioning_orchestrator::security::{
    CedarEngine, AuthorizationRequest, Principal, Action, Resource, AuthorizationContext
};

let request = AuthorizationRequest {
    principal: Principal::User {
        id: "user123".to_string(),
        email: "user@example.com".to_string(),
        username: "developer".to_string(),
        teams: vec!["developers".to_string()],
    },
    action: Action::Deploy,
    resource: Resource::Server {
        id: "server123".to_string(),
        hostname: "prod-web-01".to_string(),
        workspace: "production".to_string(),
        environment: "production".to_string(),
    },
    context: AuthorizationContext {
        mfa_verified: true,
        ip_address: "10.0.0.1".to_string(),
        time: "2025-10-08T14:30:00Z".to_string(),
        approval_id: Some("APPROVAL-12345".to_string()),
        reason: None,
        force: false,
        additional: HashMap::new(),
    },
};

let result = engine.authorize(&request).await?;
match result.decision {
    AuthorizationDecision::Allow => println!("✅ Authorized"),
    AuthorizationDecision::Deny => println!("❌ Denied: {:?}", result.diagnostics),
}
```

### Load Policies with Hot Reload

```rust
use provisioning_orchestrator::security::{CedarEngine, PolicyLoader, PolicyLoaderConfigBuilder};
use std::sync::Arc;

let engine = Arc::new(CedarEngine::new());

let config = PolicyLoaderConfigBuilder::new()
    .policy_dir("provisioning/config/cedar-policies")
    .hot_reload(true)
    .schema_file("schema.cedar")
    .add_policy_file("production.cedar")
    .add_policy_file("development.cedar")
    .add_policy_file("admin.cedar")
    .build();

let mut loader = PolicyLoader::new(config, engine.clone());
loader.load().await?;
loader.start_hot_reload()?;
```

### Axum Middleware Integration

```rust
use axum::{Router, routing::post, middleware};
use provisioning_orchestrator::security::{SecurityContext, auth_middleware};

let public_key = std::fs::read("keys/public.pem")?;
let security = Arc::new(
    SecurityContext::new(&public_key, "control-center", "orchestrator")?
        .with_cedar(engine.clone())
);

let app = Router::new()
    .route("/servers", post(create_server))
    .layer(middleware::from_fn_with_state(security.clone(), auth_middleware));
```

---

## 🧪 Testing

### Run All Tests
```bash
cd provisioning/platform/orchestrator
cargo test security::tests
```

### Validate Policies
```bash
cedar validate --schema schema.cedar --policies production.cedar
```

### Test Specific Authorization
```bash
cedar authorize \
    --policies production.cedar \
    --schema schema.cedar \
    --principal 'Provisioning::User::"user123"' \
    --action 'Provisioning::Action::"deploy"' \
    --resource 'Provisioning::Server::"server123"' \
    --context '{"mfa_verified": true, "ip_address": "10.0.0.1", "time": "2025-10-08T14:00:00Z"}'
```

---

## 📊 Decision Matrix

| Scenario | Principal | Action | Resource | MFA | Approval | Decision |
|----------|-----------|--------|----------|-----|----------|----------|
| Dev creates dev server | developers | create | dev server | ❌ | ❌ | ✅ ALLOW |
| Dev deploys to prod | developers | deploy | prod server | ✅ | ✅ | ❌ DENY (read-only) |
| SRE deploys to prod | sre | deploy | prod server | ✅ | ✅ | ✅ ALLOW |
| Admin deploys to prod | platform-admin | deploy | prod server | ❌ | ❌ | ✅ ALLOW |
| Audit reads prod | audit | read | prod server | ❌ | ❌ | ✅ ALLOW |
| Audit deletes prod | audit | delete | prod server | ✅ | ✅ | ❌ DENY (forbid) |
| SRE SSH to prod | sre | ssh | prod server | ❌ | ❌ | ✅ ALLOW |
| Dev SSH to prod | developers | ssh | prod server | ❌ | ❌ | ❌ DENY |

---

## 🔥 Common Scenarios

### Emergency Production Deployment

**Required:**
- Principal: `platform-admin` or `sre`
- MFA: ✅ Verified
- Approval: `EMERGENCY-*` prefix
- IP: Corporate network

**Example:**
```rust
context: AuthorizationContext {
    mfa_verified: true,
    approval_id: Some("EMERGENCY-OUTAGE-2025-10-08".to_string()),
    ip_address: "10.0.0.5".to_string(),
    time: "2025-10-08T22:30:00Z".to_string(),  // Outside business hours OK with emergency
    // ...
}
```

### Developer Self-Service

**Allowed in Development:**
- Create/delete servers
- Deploy without approval
- Force deletion
- Unlimited SSH access

**Not Allowed:**
- Cluster size > 5 nodes
- Modify other users' workspaces

### Audit Compliance

**Audit Team:**
- ✅ Read all resources (all environments)
- ✅ Monitor all systems
- ❌ Cannot modify anything
- ❌ Cannot deploy or delete

---

## 📖 Cedar Syntax Quick Reference

### Basic Permit
```cedar
permit(principal, action, resource);
```

### Conditional Permit
```cedar
permit(principal, action, resource) when {
    context.mfa_verified == true
};
```

### Forbid Policy
```cedar
forbid(principal, action, resource) when {
    context.force == true
};
```

### Unless Clause
```cedar
forbid(principal, action, resource) unless {
    context.approval_id.startsWith("EMERGENCY-")
};
```

### Team Membership
```cedar
permit(
    principal in Team::"developers",
    action,
    resource
);
```

### Resource Hierarchy
```cedar
permit(
    principal,
    action,
    resource in Environment::"production"
);
```

---

## 🚨 Security Best Practices

1. **Always Validate MFA** for production operations
2. **Require Approvals** for destructive operations
3. **IP Restrictions** for production access
4. **Time Windows** for maintenance operations
5. **Audit Logging** for all authorization decisions
6. **Version Control** all policy files
7. **Test Policies** before deploying to production
8. **Emergency Access** only with proper approvals

---

## 🔧 Troubleshooting

### Always Denied?
1. Check if policies loaded: `engine.policy_stats().await`
2. Verify context: `println!("{:#?}", request.context)`
3. Check diagnostics: `println!("{:?}", result.diagnostics)`
4. Validate entity types match schema

### Hot Reload Not Working?
1. Check file permissions
2. View logs: `tail -f orchestrator.log | grep -i policy`
3. Verify `hot_reload: true` in config

### MFA Not Enforced?
1. Ensure `context.mfa_verified == true`
2. Check production policies loaded
3. Verify `resource.environment == "production"`

---

## 📚 Resources

- **Full Documentation**: `docs/architecture/CEDAR_AUTHORIZATION_IMPLEMENTATION.md`
- **Cedar Docs**: https://docs.cedarpolicy.com/
- **Cedar Playground**: https://www.cedarpolicy.com/en/playground
- **Implementation**: `provisioning/platform/orchestrator/src/security/`
- **Tests**: `provisioning/platform/orchestrator/src/security/tests.rs`

---

**Last Updated**: 2025-10-08