AccessControl

When writing conditions, follow this rule of thumb to decide where data belongs:

• context: Use this for data that the condition reads using the $. prefix (e.g., data belonging to the specific record being checked).
• policy: Use this for data that the AccessControl engine reads to decide its internal behavior or logic.

In v3, grants are purely additive. A child grant cannot 'shrink' an inherited grant by simply defining fewer attributes. To remove access that was inherited, you must use an explicit deny rule.

Note: deny does not cascade across possession. For example, deny create:any will not affect create:own permissions.

ac.grant('user').readAny('post', ['*']);
ac.grant('moderator').extend('user');
ac.deny('moderator').readAny('post', ['secret']);   // carve a field back

ac.can('moderator').readAny('post').attributes;     // ['*', '!secret']

A condition determines whether a grant applies at check time by evaluating a context object. You attach conditions to grants using the .where() method. This implements Attribute-Based Access Control (ABAC) by comparing data provided during the access check against the policy requirements.

ac.grant('manager')
  .where('$.order.value <= 100000')
  .updateAny('order', ['*']);

ac.can('manager')
  .with({ order: { value: 5000 } })
  .updateAny('order').granted; // true

ac.can('manager')
  .with({ order: { value: 250000 } })
  .updateAny('order').granted; // false

AccessControl includes built-in protections against prototype pollution and inherited key attacks:

1. Reserved Names: The names __proto__, prototype, and constructor are rejected during validation with err.code === 'RESERVED_NAME'. Attempting to grant these will throw an error.
2. Inherited Keys: Names that collide with built-in object properties (like toString or hasOwnProperty) are treated as plain data. The library uses Object.hasOwn for all internal lookups, so these names will simply return granted: false rather than accessing or mutating the prototype.
3. JSON/DB Imports: If you import a grants object from an external source, any __proto__ keys are rejected rather than merged.

ac.can('user').readAny('toString').granted; // false (never throws)
ac.grant('__proto__');                       // throws RESERVED_NAME

Create roles using .grant(role) or .deny(role). Roles can inherit permissions from other roles using .extend(). Grants are additive, but an explicit deny always takes precedence over inherited grants. Note that deny does not cascade across possession (e.g., a deny create:any does not automatically deny create:own).

ac.grant('user').readAny('post', ['*']);
ac.grant('moderator').extend('user');
ac.deny('moderator').readAny('post', ['secret']);   // carve a field back

ac.can('moderator').readAny('post').attributes;     // ['*', '!secret']

Because AccessControl stores only the name + args of a custom function in a grant, your permission model remains JSON/DB-serializable.

When loading a model from a database or JSON file, you must re-register the corresponding functions using defineCondition() on the new instance. If you attempt to use a function name that has not been registered, the check will fail closed with err.code === 'UNKNOWN_CONDITION_FN'.

AccessControl protects the integrity of the authorization model through several mechanisms:

• Detached Copies: Methods like getGrants(), getGrantsList(), and getRequirements() return deep copies. Mutating these results will not affect the live AccessControl instance.
• Model Locking: You can call lock() to deep-freeze the model. Once locked, any attempt to use mutator methods will throw an error with err.code === 'LOCKED'.
• Frozen Attributes: Permission.attributes and .roles are also returned as frozen copies.