What may this user do at all?

access.capabilities(subject) answers every permission in the matrix for one subject in one call, so a navigation menu draws its items before any row is fetched.

One acl call behind a whole navigation menu

Baize’s sidebar draws its Reports and Listings entries before the page has fetched a report or a listing. A sidebar calling can once per entry keeps its own list of permission keys beside the policy, and that list stops matching the document the day somebody adds a permission to one and not the other.

capabilities(subject, now?) resolves every permission in the document against one subject, passing no object, and returns a map keyed by permission in document order. The optional now fixes the instant that rules comparing the clock read. Each entry is the decision can returns: allowed is the answer, and reason names which of seven outcomes decided it, as Can this user do this? tables. p.contains(path, value) holds when the array at path includes value:

import { policy } from '@evanion/acl';
import type { Action } from '@evanion/acl';
 
type Shopper = { id: string; roles: string[] };
 
// One policy, every object kind the app has. A `.for()` per kind, and the
// permissions they flatten to live in the same flat list.
const access = policy<
  Shopper,
  { report: { id: string }; listing: { id: string } },
  { report: Action | 'export' }
>()
  .for('report', (p) =>
    p
      .allow('read', p.contains('subject.roles', 'bookseller'))
      .allow('export', p.contains('subject.roles', 'owner')),
  )
  .for('listing', (p) => p.allow('read', p.contains('subject.roles', 'owner')))
  .build();
 
const caps = access.capabilities({ id: 'u1', roles: ['bookseller'] });
 
Object.keys(caps); // -> ['report.read', 'report.export', 'listing.read']
caps['report.read']?.allowed; // -> true
caps['report.export']?.reason; // -> 'no-rule-matched'
caps['listing.read']?.reason; // -> 'no-rule-matched'

One policy holds every object kind, so the chain of .for('report') and .for('listing') puts both kinds in one document and one call answers across them. An object kind’s actions default to Action: create, read, update and delete. policy’s third type argument widens that for one kind, so { report: Action | 'export' } lets report declare export. Only the owner role holds report.export and listing.read, so a bookseller gets no-rule-matched for both.

Why an acl capability map carries unevaluable entries

capabilities passes no object, and that decides what each entry can mean. A permission settles when it gets a definite true or false:

• A permission whose rules read only subject.* settles, because the server resolves the subject whole before the call.
• A rule that reads object.* also settles when one of its subject conditions already fails, because no row could make that rule match. It answers denied for a deny rule and no-rule-matched for an allow rule.
• A permission that still needs the row decides unevaluable, the answer for a path a rule needs and the call did not carry, with missing naming the paths.

p.always is the condition that always holds:

import { policy } from '@evanion/acl';
import type { Action } from '@evanion/acl';
 
type Shopper = { id: string; roles: string[] };
type Question = { askedBy: string; status: string };
 
const access = policy<
  Shopper,
  { question: Question },
  { question: Action | 'hide' }
>()
  .for('question', (p) =>
    p
      .allow('read', p.always)
      .allow('update', p.eq('object.askedBy', 'subject.id'))
      .allow(
        'hide',
        p.contains('subject.roles', 'bookseller'),
        p.eq('object.status', 'open'),
      ),
  )
  .build();
 
const customer = { id: 'customer-41', roles: [] };
const caps = access.capabilities(customer);
 
// Reads only the subject, so it settles.
caps['question.read'].reason; // -> 'allow'
 
// Needs the row to settle, and names what it would read.
caps['question.update'].reason; // -> 'unevaluable'
caps['question.update'].missing; // -> ['object.askedBy']
 
// The customer holds no `bookseller` role, so the row cannot change the answer.
caps['question.hide'].reason; // -> 'no-rule-matched'

The customer’s question.update entry is unevaluable because its one rule compares object.askedBy with the subject’s id and no question was passed. false there would say the customer may edit no question, which is wrong for the ones they asked. question.hide settles without the row: its rule also requires bookseller in subject.roles, and the customer holds no roles.

Drawing a menu from an acl capability map

The menu keeps an item when the map carries its key and the entry allows. The storefront below draws its menu from a document the stock service serves. It adopts that document with parseMatrix, the call that builds an evaluator over a document another service wrote and answers unknown-action for a key the document lacks:

import { parseMatrix, policy } from '@evanion/acl';
 
type Shopper = { id: string; roles: string[] };
 
// `stock` writes the report rules and serves the document as JSON. It declares
// nothing about listings.
const stock = policy<Shopper, { report: { id: string } }>()
  .for('report', (p) =>
    p.allow('read', p.contains('subject.roles', 'bookseller')),
  )
  .build();
 
const served = JSON.stringify(stock.matrix);
const access = parseMatrix(JSON.parse(served));
const caps = access.capabilities({ id: 'u1', roles: ['bookseller'] });
 
const menu = [
  { href: '/reports', label: 'Reports', key: 'report.read' },
  { href: '/listings', label: 'Listings', key: 'listing.read' },
];
 
const shown = menu.filter((item) => caps[item.key]?.allowed === true);
shown.map((item) => item.label); // -> ['Reports']
 
// Hiding only what the map refuses shows the key the document never declared.
const leaky = menu.filter((item) => caps[item.key]?.allowed !== false);
leaky.map((item) => item.label); // -> ['Reports', 'Listings']

A key the document does not carry is absent from the map, and listing.read is that key here. The leaky filter hides only what the map refuses, so it shows Listings to every subject. This document arrived as JSON, so its keys are string and the miss happens at runtime; ?. reaches the absent entry without throwing. A policy the builder authored types the map by its own keys, and caps['listing.read'] on it is a compile error.

Make one capabilities call per render. It reads the clock once for the whole document, where a loop of can reads it per permission. A rule built with p.before or p.after, the helpers that compare the current instant with a fixed one, can otherwise flip between two items of one render.

What an acl capability map does not answer

A control on one row, such as the Edit button under one question, needs that row. Ask can with the question, or canMany with the page of rows. An entry that came back unevaluable is the map saying so.

A capability map is also not a copy of the rules to ship to a browser. Ship access.matrix and let the browser rebuild an evaluator with hydratePolicy, as the Overview draws it. A map computed per subject is a second document to keep fresh.

Who can do this

To determine who among a group can perform an action, you use canEach. While capabilities answers every permission for one subject, canEach answers one permission for many subjects. This is useful for editors who need to know, for example, which specific users in a list have the right to delete a particular refund. Because @evanion/acl holds no subjects of its own, the caller must supply the candidates, whether they are saved scenarios or a sample of real users.

The access.canEach(subjects, key, action, object?, now?) call decides one permission for each subject against one object and returns a Decision[] in the order of the provided subjects. Since entry i is simply what can returns for subjects[i], the properties allowed, reason, rule, and missing retain their standard meanings. The caller is responsible for grouping these entries into allowed, denied, or undetermined categories.

import { policy } from '@evanion/acl';
 
type Refund = { id: string; ownerId: string };
type Agent = { id: string; roles: string[] };
 
const access = policy<Agent, { refund: Refund }>()
  .for('refund', (p) =>
    p
      .allow('delete', p.contains('subject.roles', 'admin'))
      .allow('delete', p.eq('object.ownerId', 'subject.id')),
  )
  .build();
 
const candidates: Agent[] = [
  { id: 'a1', roles: ['admin'] },
  { id: 'o1', roles: [] },
  { id: 'x1', roles: [] },
];
 
const refund = { id: 'r1', ownerId: 'o1' };
const decisions = access.canEach(candidates, 'refund', 'delete', refund);
decisions.map((decision) => decision.reason); // -> ['allow', 'allow', 'no-rule-matched']
 
// Without the row, an owner rule cannot be decided for anyone it might cover.
const unloaded = access.canEach(candidates, 'refund', 'delete');
unloaded.map((decision) => decision.reason); // -> ['allow', 'unevaluable', 'unevaluable']

To ensure consistency across the group, @evanion/acl reads the clock once for the entire list (similar to canMany); consequently, any rule built with p.before or p.after will evaluate every subject identically.

The results vary based on the input:

• Omitted object: An object rule becomes unevaluable, and missing names the required paths. These subjects remain undetermined until the row is loaded.
• Unknown action: Every entry returns unknown-action.
• Stale document: Every entry returns stale-contract.
• Empty list: Returns an empty list.

Note that canEach requires a list of subjects rather than a description of them. It cannot answer queries like “subjects where role is support and team is billing,” as that would require computing a predicate over the allow and deny rules—a feature @evanion/acl does not provide. Finally, federatedPolicies does not implement canEach. The call answers about one permission, so the caller already knows which origin holds it and reaches it with get(origin).