@evanion/acl

The concept. @evanion/acl keeps every authorization rule in one JSON document, called the matrix. What you get. A server handler and a browser control that answer from the same rules, through the same call. Why you want it. A rule copied into a second codebase by hand diverges the first time somebody edits one copy. How the library gets you there. policy() writes the document, and can, canMany, canFields and capabilities read it.

What the access object answers

policy() writes the JSON document, called the matrix, and hands back an access object. Four of its methods carry most of the work.

• can decides one action and carries the reasons beside the answer.
• capabilities decides every action at once.
• authorize binds one subject for the length of a request.
• canFields names the fields of a write you may set.

Each method is a local function over the frozen document, so no call waits on a network round trip. The matrix answers one question: may this subject take this action on this object? Baize, a board game shop, states three rules that way. A customer may edit their own question, a bookseller may edit anybody’s, and a locked question is editable by nobody.

import { policy } from '@evanion/acl';
 
type Question = { id: string; askedBy: string };
 
const access = policy<{ id: string }, { question: Question }>()
  .for('question', (p) =>
    p.allow('update', p.eq('object.askedBy', 'subject.id')),
  )
  .build();
 
const decision = access.can({ id: 's1' }, 'question', 'update', {
  askedBy: 's1',
});
decision.allowed; // -> true

can answers with a decision. allowed is the answer; reason, rule and missing are why.

One .for() block declares one object kind, and a policy chains a block per kind. The example declares only question because that is all it asks about.

The server that enforces the answer and the screen that renders it read the same rules, because both run over the same document. A rule copied by hand into a second place diverges from the first: you tighten the handler, forget the loader, and the UI greys out a button the API would have accepted.

When to reach for acl

acl fits rules that read one of these:

• Permissions that turn on which object is in front of the user as well as on the role. “The customer who asked may edit their own question”, “an open question may be deleted and a locked one may not”.
• The same rules on a server and in a UI. The document crosses an SSR boundary as access.matrix and rebuilds on the other side.
• A UI that explains a block as well as enforcing it: which rule refused, which field is read-only, and what is still missing.
• A field-level write, where the answer names which fields are yours.

When acl is the wrong tool

acl does not do these four jobs:

• Anything the document cannot state in the open. The matrix reaches the client in full, so every object kind, action, role string, field name and time boundary in it is public. Opaque predicates stay server-side, outside the matrix.
• Filtering a collection in the database. A decision is per instance, and generating a WHERE clause from the matrix is out of scope.
• Rules that call a function. Conditions are declarative because the matrix must pass through JSON.stringify unchanged.
• A non-JS backend. Only the JSON crosses, and a .NET or Go service uses its own evaluator.

What the acl package exports

The entry point exports these beside policy() and can:

The @evanion/acl entry point imports no framework. The React provider and hooks are a separate package, @evanion/react-acl.

Where to go next

Setup runs to four pages, separated by what a rule may read:

• Rules that read the subject. A handful of permissions, can and done.
• Rules that read the object. The typed builder, field permissions and the guarded save.
• Rules that another service wrote. The schema, versioning and the revalidate contract.
• One policy behind a screen. The fetched document driving an action bar, and where the wording of a refusal comes from.

Platforms follows those: one guide per stack, and Many services for a topology that spans them.

Then the question you arrived with:

• Can this user do this?. can, canMany, and what the decision carries beside allowed.
• What can they do at all?. The no-object contract, and how a menu draws itself from one call.
• Which fields may they write?. canFields and pickAllowedFields.
• Why was this refused?. The explanation fields, and the repairable unevaluable state.
• A policy from another service. parseMatrix and the closed mode.
• Giving my rules to another service. serialize and the reduced document.

The reference is below those, and one page of it is not optional:

• Caveats and pitfalls. The mistakes this API makes easy, and the two gaps it does not defend.
• Security contract. What the library prevents, what it hands you, and what remains yours.
• The matrix document, Typed authoring, Decisions, Field permissions. The mechanisms.
• API reference. Every export and every type it names, down to the error classes.