Access Control Lists (ACL) basics

Access Control Lists (ACL) provide fine-grained security for your Builder.io code generation projects. With ACLs, you can control exactly which files and directories users can access, and what operations they're allowed to perform.

What ACLs do

ACLs help protect sensitive files like configuration files or API keys while controlling team permissions by giving different access levels to different roles. They prevent accidental modifications to critical parts of your codebase and maintain project security during collaborative development.

ACLs in Builder

When Builder generates or modifies code in your project, ACLs ensure that AI-generated code changes only affect approved directories and team members can only access files relevant to their role.

Critical configuration files remain protected from accidental changes while maintaining security standards across automated and manual changes.The ACL system provides resource-based access control with support for:

Resource pattern matching: use flexible glob patterns to match files and directories
Allow and deny rules: explicit grant and revoke permissions with proper precedence
Multiple permission types: control read, write, and list operations
Custom failure messages: provide helpful error messages when access is denied

Configuration

Each ACL entry defines a single access rule with these components:

interface AclEntry {
  action: "allow" | "deny";        // Whether to grant or deny access
  resource: string;                // What resources (supports glob patterns)
  permissions: Permission[];       // Which operations (read/write/list)
  failMessage?: string;           // Custom error message (deny rules only)
  principals?: string[];           // Array of teams/roles this rule applies to
}

Where to add ACL policies

Configure ACL policies in your fusion.config.json file under the accessControl property:

{
  "devCommand": "npm run dev",
  "serverUrl": "http://localhost:3000",
  "accessControl": {
    "entries": [
      {
        "action": "allow",
        "resource": "/public/**",
        "permissions": ["read"]
      },
      {
        "action": "deny",
        "resource": "/admin/**",
        "permissions": ["read", "write"],
        "failMessage": "Admin area access is restricted"
      }
    ]
  }
}

Core concepts

ACL rules are built from a few key components that work together to control access. Understanding these building blocks helps you create effective security policies for your project.

Actions

Actions determine whether access is granted or denied:

Action	Description
`allow`	grants access to matching resources
`deny`	denies access to matching resources (always takes precedence)

Permissions

Permissions specify what operations users can perform:

Permission	Description
`read`	view and read files and directories
`write`	create, modify, and delete files and directories
`list`	view directory contents and file listings

Resource patterns

ACLs use glob patterns to match files and directories, for example:

Pattern example	Description
`/src/app.js`	exact file match
`/src/*.js`	all `.js` files in the `/src` directory
`/src/*/.ts`	all TypeScript files in `/src` and all subdirectories
`/**`	all files and directories
`/assets/**`	everything in the assets directory

Glob patterns are case-sensitive and always use forward slashes (/), even on Windows.

Rule precedence

The ACL system uses a deny-first precedence model:

Deny rules checked first. If any deny rule matches, access is immediately denied.
Allow rules checked second. If no deny rules matched and an allow rule matches, access is granted.
Default deny. If no rules match, access is denied by default.

In this way, deny rules always take precedence over allow rules, regardless of their order in the policy.

How ACLs work with code generation

When Builder generates or modifies code, every file operation is checked against your ACL rules:

Reading files for context or analysis requires read permission.
Creating or modifying files requires write permission.
Listing directories to understand project structure requires list permission.
Checking if files exist requires read permission.

What happens when access is denied

When an ACL rule denies access, the operation fails with an error message in this format:

ACL denied: [your custom message or default explanation]

The default message gives only the most basic context:

"ACL denied: Access to /src/secrets/api-key.txt denied by rule"

Ideally, provide a custom message so users know exactly why access is denied:

"ACL denied: Database configuration cannot be modified automatically"

Common use cases

This section covers some practical examples of how to configure ACLs for typical project scenarios.

Basic file access control

Allow users to read markdown files and work with source code, but restrict TypeScript modifications to keep those files read-only:

{
  "accessControl": {
    "entries": [
      {
        "action": "allow",
        "resource": "/**/*.md",
        "permissions": ["read"]
      },
      {
        "action": "allow",
        "resource": "/src/**",
        "permissions": ["read", "write"]
      },
      {
        "action": "deny",
        "resource": "/src/**/*.ts", 
        "permissions": ["write"],
        "failMessage": "TypeScript files are read-only"
      }
    ]
  }
}

Directory access control

Specify different access levels for different directories:

{
  "accessControl": {
    "entries": [
      {
        "action": "allow",
        "resource": "/docs/**",
        "permissions": ["read", "write", "list"]
      },
      {
        "action": "allow", 
        "resource": "/src/**",
        "permissions": ["read", "write"]
      },
      {
        "action": "allow",
        "resource": "/assets/**",
        "permissions": ["read", "write", "list"]
      },
      {
        "action": "deny",
        "resource": "/config/secrets/**", 
        "permissions": ["read", "write", "list"],
        "failMessage": "Access to secrets is restricted"
      }
    ]
  }
}

Public and private file structure

Allow public access to documentation but restrict source code:

{
  "accessControl": {
    "entries": [
      {
        "action": "allow",
        "resource": "/docs/**",
        "permissions": ["read", "list"]
      },
      {
        "action": "allow", 
        "resource": "/public/**",
        "permissions": ["read", "list"]
      },
      {
        "action": "allow",
        "resource": "/src/**", 
        "permissions": ["read", "write"]
      },
      {
        "action": "deny",
        "resource": "/src/config/**",
        "permissions": ["write"],
        "failMessage": "Configuration files cannot be modified"
      }
    ]
  }
}

File type restrictions

Control access based on file types:

{
  "accessControl": {
    "entries": [
      {
        "action": "allow",
        "resource": "/**/*.md",
        "permissions": ["read", "write"]
      },
      {
        "action": "allow",
        "resource": "/**/*.js",
        "permissions": ["read", "write"],
        "principals": ["developer", "admin"]
      },
      {
        "action": "allow",
        "resource": "/**/*.ts",
        "permissions": ["read"],
        "principals": ["developer", "admin"]
      },
      {
        "action": "deny",
        "resource": "/**/*.ts",
        "permissions": ["write"],
        "failMessage": "TypeScript files are currently read-only"
      }
    ]
  }
}

What's next

Explore more advanced features:

Principal-based permissions: ideal for working with different roles—like developers, designers, and admins—and need to give different permissions to different team members.
ACL testing and solutions to common issues: get tips on testing your policies, debugging common issues, and ensuring your ACL configuration works as expected.

Was this article helpful?