ACL testing and solutions to common issues

Whether you're setting up ACLs for the first time or debugging an existing configuration, this document provides practical solutions, testing strategies, and solutions to common issues.

Prerequisites

To get the most out of this document, make sure you're familiar with Access Control List (ACL) basics.

Test your ACL configuration

Follow this systematic approach to verify your ACL policies work correctly and provide clear feedback to users:

Start with permissive rules. Begin with broad allow rules.
Add specific restrictions. Layer on deny rules for sensitive areas.
Test different scenarios. Try accessing files as different user types.
Verify error messages. Ensure your failMessage values are helpful.

Common scenarios to test include:

✅ that users can access files they should have access to
❌ that sensitive files properly protected
👥 that team-based restrictions work as expected
🔄 that deny rules properly override allow rules
📝 that error messages clear and actionable

The ACL system is automatically integrated into all file operations in the code generation system:

readFile() checks read permissions.
writeFile() checks write permissions.
deleteFile() checks write permissions.
fileExists() checks read permissions.
listDir() checks list permissions.
stat() checks read permissions.

1. Use deny-first design

Structure policies with specific deny rules to override broader allow rules:

json{
  "entries": [
    {
      "action": "allow",
      "resource": "/**",
      "permissions": ["read", "write"]
    },
    {
      "action": "deny",
      "resource": "/secrets/**",
      "permissions": ["read", "write"],
      "failMessage": "Secret files are protected"
    }
  ]
}

2. Provide clear error messages

Always include a helpful failMessage for deny rules:

json{
  "action": "deny",
  "resource": "/production/**",
  "permissions": ["write"],
  "failMessage": "Production files require manual review. Please submit changes through the standard deployment process."
}

3. Use Specific Resource Patterns

Be as specific as possible to avoid unintended access restrictions:

json{
  "action": "deny",
  "resource": "/src/config/**/*.json",
  "permissions": ["write"],
  "failMessage": "JSON configuration files cannot be automatically modified"
}

4. Separate permissions by operation

Use different permissions for different use cases:

json{
  "entries": [
    {
      "action": "allow",
      "resource": "/logs/**",
      "permissions": ["read", "list"]
    },
    {
      "action": "allow",
      "resource": "/temp/**",
      "permissions": ["read", "write", "list"]
    },
    {
      "action": "allow",
      "resource": "/public/**",
      "permissions": ["read", "list"]
    }
  ]
}

5. Document your policies

Add comments to explain complex rules:

json{
  "entries": [
    {
      "action": "allow",
      "resource": "/src/**",
      "permissions": ["read", "write"],
      "principals": ["developer"],
      "comment": "Developers can modify all source code except production configs"
    },
    {
      "action": "deny",
      "resource": "/src/config/production.json",
      "permissions": ["write"],
      "principals": ["developer"],
      "failMessage": "Production config requires admin approval"
    }
  ]
}