Typed authoring

policy<Subject, Objects, Verbs>() names the subject, the object kinds and the actions each kind answers for, then returns a builder.

The builder chain

Each .for() names its kind as a value and hands the condition helpers to a block, so a typo in an object.* or subject.* path is a compile error. Chain a .for() per kind and one policy covers the whole app. Every kind accumulates into the same key map and the same document.

import { policy } from '@evanion/acl';
import type { Action } from '@evanion/acl';
 
type Subject = { id: string; roles: string[] };
type Question = { askedBy: string; status: 'open' | 'locked' };
type Listing = { sellerId: string };
 
// One policy, every object kind the shop has. Each `.for()` adds a kind and
// keeps the ones before it, so `access` answers for questions and listings
// alike and there is one document to ship.
const access = policy<
  Subject,
  { question: Question; listing: Listing },
  { question: Action | 'hide' }
>()
  .for('question', (p) =>
    p
      .allow(
        'update',
        p.or(
          p.eq('object.askedBy', 'subject.id'),
          p.contains('subject.roles', 'bookseller'),
        ),
      )
      .allow('hide', p.contains('subject.roles', 'bookseller'))
      .deny('delete', p.eq('object.status', 'locked')),
  )
  .for('listing', (p) =>
    p.allow('update', p.eq('object.sellerId', 'subject.id')),
  )
  .build();
 
const subject = { id: 's1', roles: [] };
const question = { askedBy: 's1', status: 'open' } as const;
access.can(subject, 'question', 'update', question).allowed; // -> true
access.can(subject, 'listing', 'update', { sellerId: 's1' }).allowed; // -> true
access.can(subject, 'listing', 'update', { sellerId: 's2' }).allowed; // -> false

build() is the terminal call, and it flattens the blocks to the canonical matrix, so JSON.stringify(access.matrix) emits the same document a foreign backend would produce. Validation runs once over every block at that point, and no .for() validates on its own.

The block parameter

.for() hands its block one object carrying the whole permission model.

Conditions passed to one allow are AND-ed, and p.or inside them flattens to disjunctive normal form, one rule per branch. Two separate allow calls for the same action are two rules, the same OR.

Paths versus literals

The builder reads an operand as a path when its type matches `subject.${string}` | `object.${string}` | 'now', and as a literal value otherwise:

p.eq('object.status', 'locked'); // compares against the string 'locked'
p.eq('object.askedBy', 'subject.id'); // compares two paths
p.eq('object.askedBy', 'subject.idd'); // compile error naming the path

What is checked, and what is not

A kind whose vocabulary is string takes any action, because a foreign document may carry an action this one does not.

The vocabulary of a kind

policy() takes a third map, kind to the actions that kind answers for. A kind the map leaves out declares the four Action verbs and nothing else:

const access = policy<Subject, Objects, Verbs>()
  .for('question', (p) =>
    p
      .allow('read', p.always)
      .allow('answer', p.eq('object.askedBy', 'subject.id')),
  )
  .build();
 
access.can(subject, 'question', 'answer');
access.can(subject, 'question', 'answr');
Argument of type '"answr"' is not assignable to parameter of type '"read" | "answer"'.
 
const caps = access.capabilities(subject);
caps['question.read'];
caps['question.raed'];
Property 'question.raed' does not exist on type 'Record<"question.read" | "question.answer", Decision>'. Did you mean 'question.read'?

Only the block reaches the keys, so a 'reprice' the vocabulary lists and no block allows puts no question.reprice in capabilities().

A block whose body is a statement with no return hands back no chain to read the actions off, so its document answers Record<string, Decision>.

allowEach(actions, ...conditions) and denyEach write one rule across several actions, one ordinary permission each, so the document names every action it grants. CRUD_ACTIONS holds those four verbs at runtime, and an author hands it to allowEach to open all four at once.

The document a typed policy emits

policy() takes version and schema, both document fields, and puts them in the document it flattens to:

import { policy } from '@evanion/acl';
 
type Question = { askedBy: string; status: string };
 
const access = policy<{ id: string }, { question: Question }>({
  version: 'orders@7',
  schema: {
    subject: { fields: { id: 'string' } },
    objects: {
      question: { fields: { askedBy: 'string', status: 'string' } },
    },
  },
})
  .for('question', (p) =>
    p.allow('update', p.eq('object.askedBy', 'subject.id')),
  )
  .build();
 
JSON.stringify(access.matrix.version); // -> '"orders@7"'

You write a schema by hand. The object map holds Question at the type level only, so nothing derives a schema from it.

TypeScript and the schema are checked independently and can disagree. A path TypeScript accepts because the type declares the field is still an UnknownFieldError at construction when the schema does not declare it. The schema is binding wherever it is present.

A bound handle

access.object(key) binds one object kind so the key is named once:

const questions = access.object('question');
questions.can(subject, 'update', question);
questions.canFields(subject, 'update', question, 'write', proposed);

A bound handle carries can, canMany, canFields and readsObject. authorize(subject) binds the other axis and carries can, canMany, canFields and capabilities, dropping readsObject, which takes no subject. The two compose.

Construction errors

Every error below is an AclConfigError subclass raised while the policy is built, which is startup for a local matrix and adoption time for a foreign one.

The last two rows are raised by a query, never by construction. ActionNotAllowedError is the only error raised outside construction on either path, and the write path has it.