acl-graphql

1.0.0 verified Fri May 01 auth: no javascript

A GraphQL ACL (Access Control List) transpiler that generates permission-based GraphQL schemas. Version 1.0.0 is the latest stable release. It transforms declarative ACL rules into GraphQL directives and resolvers, enabling fine-grained field-level access control without modifying existing schema definitions. Differentiates from other auth libraries by focusing on ACL-to-GraphQL transpilation rather than middleware-based enforcement.

Common errors

error TypeError: AclGraphql is not a constructor ↓

cause Using CommonJS require() with ESM-only package

fix

Use ES module import syntax: import { AclGraphql } from 'acl-graphql'

error Error: No schema provided ↓

cause Omitting required 'typeDefs' option in constructor

fix

Pass typeDefs in options object: new AclGraphql({ typeDefs, rules })

error Error: Invalid rule - path 'User.email' not found in schema ↓

cause Rule references a field that doesn't exist in the schema

fix

Verify field path exists in schema definition

Warnings

breaking As of v1.0.0, the constructor signature changed: new AclGraphql({ typeDefs, rules }) instead of positional arguments. ↓

fix Update instantiation to use options object: new AclGraphql({ typeDefs, rules })

gotcha Rules must use dot notation for fields (e.g., 'User.email'). Nested fields are not supported. ↓

fix Use flat dot notation for all field paths

deprecated The 'permissions' field in rules is deprecated since v1.0.0. Use 'fields' instead. ↓

fix Replace 'permissions' with 'fields' in rule definitions

Install

npm install acl-graphql

yarn add acl-graphql

pnpm add acl-graphql

Imports

AclGraphql

wrong

const AclGraphql = require('acl-graphql')

correct

import { AclGraphql } from 'acl-graphql'

ESM-only package since v1.0.0

AclRule
```
import { AclRule } from 'acl-graphql'
```
Named export for defining ACL rules

transpileAcl

wrong

import { transpileACL } from 'acl-graphql'

correct

import { transpileAcl } from 'acl-graphql'

Function name is camelCase, not PascalCase

default

wrong

import { default as AclGraphql } from 'acl-graphql'

correct

import AclGraphql from 'acl-graphql'

Default export also available and preferred

Quickstart

Creates an ACL-transpiled GraphQL schema from type definitions and rules, outputting schema with directives and authorization resolvers.

import { AclGraphql, AclRule } from 'acl-graphql';
import { buildSchema } from 'graphql';

const typeDefs = `
  type Query {
    user(id: ID!): User
  }
  type User {
    id: ID!
    name: String!
    email: String!
  }
`;

const rules: AclRule[] = [
  {
    role: 'admin',
    permissions: ['Query.user', 'User.id', 'User.name', 'User.email']
  },
  {
    role: 'user',
    permissions: ['Query.user', 'User.id', 'User.name']
  }
];

const acl = new AclGraphql({ typeDefs, rules });
const { schema, resolvers } = acl.transpile();

console.log(schema); // GraphQLSchema with @acl directives
console.log(resolvers); // Resolvers enforcing field-level access