Checking permissions in your UI

An action bar calls access.can once per button it might draw and draws the buttons whose decision is allowed. The rules stay in the policy, so the component holds a list of actions and tests no role itself.

The listing policy behind Baize’s action bar

Baize’s page for the Brass: Birmingham listing draws an action bar with three buttons: Review, Edit and Publish. Baize’s stock service owns the listing rules, and there are four:

• Everyone signed in reviews a listing.
• A bookseller or the owner edits a listing.
• The owner publishes a listing.
• Nobody edits a published listing.

stock builds them with policy() and serves stock.matrix as JSON. The storefront adopts that document with parseMatrix, which builds an evaluator from a document another service served and answers unknown-action for an action the document does not carry. The action bar asks that evaluator:

import { parseMatrix, policy } from '@evanion/acl';
 
/** Who is signed in. `role` is what the policy reads. */
interface Shopper {
  role: 'customer' | 'bookseller' | 'owner';
}
 
/** A game listing in the shop. A status, because that is all a rule reads. */
interface Listing {
  status: 'draft' | 'published';
}
 
// `stock` writes the listing rules and serves `stock.matrix` as JSON.
const stock = policy<
  Shopper,
  { listing: Listing },
  { listing: 'review' | 'edit' | 'publish' }
>()
  .for('listing', (p) =>
    p
      .allow('review', p.always)
      .allow('edit', p.in('subject.role', ['bookseller', 'owner']))
      .allow('publish', p.in('subject.role', ['owner']))
      .deny('edit', p.eq('object.status', 'published')),
  )
  .build();
 
// The storefront adopts the document it fetched, and the action bar asks it.
const access = parseMatrix<Shopper, { listing: Listing }>(stock.matrix);
 
const bookseller: Shopper = { role: 'bookseller' };
const draft: Listing = { status: 'draft' };
 
access.can(bookseller, 'listing', 'review', draft).allowed; // -> true
access.can(bookseller, 'listing', 'edit', draft).allowed; // -> true
access.can(bookseller, 'listing', 'publish', draft).reason; // -> 'no-rule-matched'
access.can(bookseller, 'listing', 'edit', { status: 'published' }).reason; // -> 'denied'
access.can(bookseller, 'listing', 'edit', {}).reason; // -> 'unevaluable'
access.can(bookseller, 'listing', 'archive', draft).reason; // -> 'unknown-action'

The third type argument to policy() names the actions each object kind may declare. A kind it leaves out may declare only create, read, update and delete, so review, edit and publish are listed there, and a misspelled p.allow('publsh', …) fails to compile.

Two condition helpers are new in that block:

• p.always holds for every subject, so review is granted to anybody the storefront asks about.
• p.in(path, values) holds when the value at path is one of values. Shopper carries role as one string, so p.in tests it against the roles written in the rule.

.deny('edit', …) reads object.status off the listing in hand. A deny that matches outranks every allow that matches with it, so nobody edits a published listing, the owner included.

What Baize’s action bar draws for each shopper

The bar loops over review, edit and publish, calls access.can(shopper, 'listing', action, listing) for each, and draws a button where allowed is true. A granted decision carries the reason allow. Every reason the four rules produce, per shopper and per listing status:

Publishing the listing moves the bar with no change to the policy. The status becomes published, the deny matches, and edit answers denied for every shopper. The customer gets denied too, where no allow would have matched, because the engine checks the deny rules before the allow rules.

A fourth button takes a rule in stock’s policy, with its action added to the third type argument, and one more action in the bar’s list. A role test in the component is a rule the policy cannot see, and the handler the button posts to never reads it.

Try Baize’s action bar against the listing policy

The demo draws the listing’s action bar from the four rules. Sign in as each of the three shoppers and the bar rebuilds itself from access.can. The panel shows the roles each p.in lists: press a role to strike it out of that list, and the button that rule produced disappears. Press Publish and the deny matches, so neither the bookseller nor the owner is offered Edit.

The interactive example this release showed here runs against the current source, so it is on the same page under /next/ and not on this one.

The demo builds its policy with the same policy() call stock runs and asks it directly, and each button is one decision’s allowed.

Only the server’s acl decision guards a listing write

The decisions the action bar draws are convenience. The stock service runs the same can in its own runtime, over a subject it resolved itself, before any listing is edited or published. A hidden button leaves the handler it posts to reachable, so that handler decides for itself.

Wording a refused button from the acl decision

A bar that greys a button out, where Baize’s action bar removes it, has to say why. allowed still decides whether the button works, and reason only picks the words. Baize’s action bar can get four refusals:

Where to go next

• Choosing a framework integration. Where the server’s can sits on each stack.
• Why was this refused?. Every reason a decision carries, and which of them a refetch can repair.
• Security contract. Why a decision the browser makes enforces nothing.