Rules about who the user is

In a real application, authorization is rarely as simple as “all staff can do X.” You often need to handle exceptions—such as preventing a suspended employee from accessing sensitive reports—or differentiate between different levels of staff.

When these rules depend only on the user’s properties (like their roles or account status), they are called subject-only rules. Because they don’t need to know which specific object is being accessed, they are extremely fast and can be evaluated without any database reads.

Handling exceptions with deny rules

While p.allow grants permission, you often need a way to explicitly revoke it. @evanion/acl provides p.deny for this purpose. A deny rule is a “hard stop”: if a deny rule matches, the permission is refused, even if an allow rule also matches.

Consider the Baize shop’s stock report. We want any staff member with the bookseller role to read the report, unless their account has been suspended.

import { policy } from '@evanion/acl';
 
// Anyone signed in to Baize: a customer, or a bookseller on the shop's staff.
type Shopper = { id: string; roles: string[] };
type Question = { id: string; askedBy: string };
type Report = { id: string };
 
// Baize suspends an account by adding the `suspended` role, and the account
// keeps `bookseller`. The deny sits beside the allow it overrides, and `.id()`
// names each rule so a decision can report which one decided.
const access = policy<Shopper, { question: Question; report: Report }>()
  .for('question', (p) =>
    p.allow('delete', p.contains('subject.roles', 'bookseller')),
  )
  .for('report', (p) =>
    p
      .allow('read', p.contains('subject.roles', 'bookseller'))
      .id('booksellers-read')
      .deny('read', p.contains('subject.roles', 'suspended'))
      .id('suspended-reads-nothing'),
  )
  .build();
 
const bookseller = { id: 'staff-3', roles: ['bookseller'] };
const suspended = { id: 'staff-5', roles: ['bookseller', 'suspended'] };
const customer = { id: 'customer-41', roles: ['customer'] };
 
access.can(bookseller, 'report', 'read').reason; // -> 'allow'
access.can(suspended, 'report', 'read').reason; // -> 'denied'
access.can(suspended, 'report', 'read').rule; // -> 'suspended-reads-nothing'
access.can(customer, 'report', 'read').reason; // -> 'no-rule-matched'

In this policy, the report.read permission is decided by two rules:

1. An allow rule that grants access to anyone with the bookseller role.
2. A deny rule that refuses access to anyone with the suspended role.

When can() is called, the engine checks deny rules first. If a user is both a bookseller and suspended, the deny rule wins, and the result is denied. If they are only a bookseller, they are allowed. If they are neither, the result is no-rule-matched (the default deny).

Identifying rules with .id

By default, @evanion/acl generates an internal hash of the rule’s conditions as the ID for every rule. The hash stays stable and names the rule in a log, but it tells a reader nothing when debugging.

You can use .id(name) to give a rule a human-readable name. For example, naming a rule suspended-reads-nothing allows your application to log exactly why a user was blocked, making it much easier to provide helpful feedback to the user or support staff.

The scope of subject-only rules

A subject-only rule is a powerful tool because it is completely decoupled from the resource. This leads to two major advantages:

1. Instant Answers: Because the server resolves the subject (the user) once per request, subject-only rules can be evaluated immediately without triggering additional database queries.
2. Pre-flight Checks: You can ask about these permissions before you’ve even fetched a specific object. For example, a navigation menu can use subject-only rules to decide whether to show the “Admin Dashboard” link without needing to know which specific admin resource is being targeted.

However, once you need to check a relationship—such as “Can this user edit this specific question?”—you have moved beyond the subject. You now need to read the object itself.

Rules about the thing being accessed explains how to write conditions that compare the user to the resource.