Filtering what a user sees

@evanion/acl filters the rows an endpoint returns with canMany, and strips each surviving row’s denied fields with canFields and pickAllowedFields.

Filtering a list endpoint with @evanion/acl

To protect a list endpoint like GET /orders, you must decide which rows a customer may read and which fields within those rows are visible. You perform this by using canMany to filter the rows and canFields combined with pickAllowedFields to strip the denied fields.

To ensure consistency across these steps, you use access.authorize(subject) to bind the subject and a single instant to a handle. Because both the row filter and the field strip use that same instant, a rule relying on p.before or p.after cannot flip its decision between the two operations.

import { pickAllowedFields, policy } from '@evanion/acl';
 
type Shopper = { id: string; roles: string[] };
type Order = {
  id: string;
  customerId: string;
  total: number;
  internalNote: string;
};
 
const access = policy<Shopper, { order: Order }>()
  .for('order', (p) =>
    p
      .allow('read', p.eq('object.customerId', 'subject.id'))
      .fields(['*', '!internalNote']),
  )
  .build();
 
const rows: Order[] = [
  { id: 'o1', customerId: 'c1', total: 40, internalNote: 'gift wrap' },
  { id: 'o2', customerId: 'c2', total: 15, internalNote: 'late payer' },
  { id: 'o3', customerId: 'c1', total: 22, internalNote: 'repeat buyer' },
];
 
// One handle holds the subject and one instant for the whole response.
const forCustomer = access.authorize({ id: 'c1', roles: [] });
const decisions = forCustomer.canMany('order', 'read', rows);
 
const response = rows
  .filter((_, i) => decisions[i]?.allowed)
  .map((row) =>
    pickAllowedFields(forCustomer.canFields('order', 'read', row, 'read'), row),
  );
 
response; // -> [{ id: 'o1', customerId: 'c1', total: 40 }, { id: 'o3', customerId: 'c1', total: 22 }]

In this example, order o2 belongs to another customer; its decision is no-rule-matched, so the filter drops it. Because internalNote is denied on the read axis, pickAllowedFields excludes it from o1 and o3. The resulting response contains only the rows and fields allowed by the rules.

The pickAllowedFields function throws ActionNotAllowedError if the action itself is refused. Since the row filter runs first, the strip only processes rows where read is already allowed. If canMany marks a row as unevaluable, it is treated as allowed: false and dropped. If your list query selected only some columns, Can this user do this? explains the second fetch required by missing.

For an example of a filter that incorrectly implements the field step by passing a projection, see Caveats and pitfalls.

Handling Nested Objects in @evanion/acl

To manage permissions for deep data structures, @evanion/acl uses path-based field rules. A rule names a path to a value: address refers to a top-level key of a row, while address.street refers to the street nested inside that object. If a key literally contains a . or \, escape it with a backslash (e.g., the flat key a.b is written as a\.b). Decision maps follow this same spelling.

How to hide a nested key

To deny access to a specific nested field, you must first establish a baseline of allowed access using * or a listed ancestor of the path.

For a row containing { id, address: { city, street } }:

• ['*', '!address.street'] allows id and address.city but denies address.street.
• ['id', 'address', '!address.street'] allows the id and the address object, except the street.

In both cases, pickAllowedFields returns the address without the street. Note that targets or transitions keys can also be paths, such as 'address.country'.

import { pickAllowedFields, policy } from '@evanion/acl';
import { expect } from 'vitest';
 
type Address = { city: string; street: string };
type Order = { id: string; address: Address };
 
// A rule names a path, and the exclusion hides exactly that key.
const access = policy<{ id: string }, { order: Order }>()
  .for('order', (p) =>
    p.allow('read', p.always).fields(['*', '!address.street']),
  )
  .build();
 
const customer = { id: 'c1' };
const order: Order = {
  id: 'o1',
  address: { city: 'Malmo', street: 'Storgatan 1' },
};
 
const decision = access.canFields(customer, 'order', 'read', order, 'read');
Object.keys(decision.fields); // -> ['id', 'address.city', 'address.street']
decision.fields['address.street']; // -> 'denied'
decision.allowed; // -> false
 
// The picked parent keeps the rest of the address.
pickAllowedFields(decision, order); // -> { id: 'o1', address: { city: 'Malmo' } }
 
// A segment through an array applies to every element, and the key carries no index.
type Basket = { id: string; lines: { sku: string; cost: number }[] };
const baskets = policy<{ id: string }, { basket: Basket }>()
  .for('basket', (p) => p.allow('read', p.always).fields(['*', '!lines.cost']))
  .build();
const basket: Basket = {
  id: 'b1',
  lines: [
    { sku: 'a', cost: 5 },
    { sku: 'b', cost: 7 },
  ],
};
const lineDecision = baskets.canFields(
  customer,
  'basket',
  'read',
  basket,
  'read',
);
Object.keys(lineDecision.fields); // -> ['id', 'lines.sku', 'lines.cost']
pickAllowedFields(lineDecision, basket); // -> { id: 'b1', lines: [{ sku: 'a' }, { sku: 'b' }] }
 
// A path that is also a flat key with a dot in it is escaped.
const flat = policy<{ id: string }, { order: { 'a.b': string } }>()
  .for('order', (p) => p.allow('read', p.always).fields(['*', '!a\\.b']))
  .build();
const flatDecision = flat.canFields(
  customer,
  'order',
  'read',
  { 'a.b': 'x' },
  'read',
);
flatDecision.fields; // -> { 'a\\.b': 'denied' }
expect(flatDecision.allowed).toBe(false);

Working with arrays

When a path segment reaches an array, the rule applies to every element within that array. To hide the cost field on every line in a list, use !lines.cost; the key remains lines.cost without a specific index.

The behavior differs by axis:

• Read Axis: The array is returned with every element and its index. If an element’s children are all withheld, that element returns as {}.
• Write Axis: Any array that a rule attempts to enter is refused in its entirety, as the engine cannot reliably match a stored element to a proposed one.

Arrays containing holes, extra own properties, or elements the walk cannot traverse are refused on both axes. To modify these, write the elements through their own dedicated action.

Handling non-traversable values

The permission walk only enters plain objects and arrays. The following are treated as “leaves”:

• Primitives, null, Date, Map, class instances, or objects with getters.
• Cycles (which become not-traversable where they repeat).

If a rule names a path below a leaf, the value is denied with the reason not-traversable. On read, the entire value is hidden; on write, it is refused. Because ORM rows are typically class instances with getters, a nested one is unwalkable. The top-level object is read as it is, whatever its class, and a wrapper that keeps data under an own property (Sequelize dataValues) leaks at the top level even with flat rules. Pass plain rows for the top level and nested values: toJSON(), get({ plain: true }) or .lean(). A raw dotted key on a read row is denied when its path reading is denied, and brackets in the key are ordinary characters.

To determine if a raw dotted key can be written in @evanion/acl, the system checks for both an explicit allowance and the absence of restrictions.

A raw dotted key is written when it is covered by a * or an allow entry naming its escaped column, provided nothing restricts its path. Conversely, the write is refused as not-traversable if any of the following apply:

• Path Exclusions: An exclusion covers the key’s path or any of its ancestors.
• Structural Blocks: A configuration exists on an ancestor, or a rule is positioned below the column’s path (or beside it under a ruled parent).
• Invalid Segments: The key contains a bracket, splits into an empty segment, or contains a constructor or prototype segment.

For the complete logic governing these interactions, see Field permissions.

This logic also protects stored data: a write that would erase a stored key the caller is not permitted to write is refused. If a stored parent contains a denied or undecidable key, that parent is marked not-traversable and pickAllowedFields excludes it. For further details, see Field permissions.

Validation and build errors

To ensure permission integrity, @evanion/acl raises an InvalidPermissionError (naming the permission key and entries) if the build encounters:

• An empty segment (e.g., a..b).
• A segment that is __proto__, *, or starts with !.
• An entry placed beside its own exclusion.
• An allow rule positioned below an excluded ancestor.
• A targets or transitions key that has another rule below it.
• A path exceeding 32 segments.

Additionally, a ! entry provided without a baseline raises a DenyWithoutBaselineError. Finally, because conditions are limited to a single field, a path like object.address.city inside a condition is refused at build time, as described in What can throw?.

Paging a filtered list with @evanion/acl

Because @evanion/acl decides on rows after they are fetched rather than producing a database filter, a query with LIMIT 20 may return fewer than 20 rows if some are filtered out. This can leave the client with a short page and no indication that more readable rows exist further down the table.

You can handle this using one of two strategies.

Over-fetch and refill

To ensure a full page, fetch a batch, filter it with canMany, and continue fetching until the page is full or the table is exhausted. In this scenario, the cursor returned to the client is the position after the last row examined, rather than a page number.

import { policy } from '@evanion/acl';
 
type Order = { id: string; customerId: string };
 
const access = policy<{ id: string }, { order: Order }>()
  .for('order', (p) => p.allow('read', p.eq('object.customerId', 'subject.id')))
  .build();
 
const table: Order[] = [
  { id: 'o1', customerId: 'c2' },
  { id: 'o2', customerId: 'c1' },
  { id: 'o3', customerId: 'c2' },
  { id: 'o4', customerId: 'c2' },
  { id: 'o5', customerId: 'c1' },
  { id: 'o6', customerId: 'c1' },
  { id: 'o7', customerId: 'c2' },
];
 
// Stands in for `SELECT ... ORDER BY id LIMIT :limit OFFSET :cursor`.
const fetchRows = (cursor: number, limit: number): Order[] =>
  table.slice(cursor, cursor + limit);
 
function readablePage(subject: { id: string }, cursor: number, want: number) {
  const forSubject = access.authorize(subject);
  const page: Order[] = [];
  let next = cursor;
  while (page.length < want) {
    const batch = fetchRows(next, want);
    if (batch.length === 0) break;
    const decisions = forSubject.canMany('order', 'read', batch);
    for (const [i, row] of batch.entries()) {
      if (page.length === want) break;
      next += 1;
      if (decisions[i]?.allowed) page.push(row);
    }
  }
  return { page, next };
}
 
// Batches of two: o1 and o2 hold one readable row, o3 and o4 none, o5 and o6 one.
const first = readablePage({ id: 'c1' }, 0, 2);
first.page.map((row) => row.id); // -> ['o2', 'o5']
first.next; // -> 5
readablePage({ id: 'c1' }, first.next, 2).page.map((row) => row.id); // -> ['o6']

When asked for two rows, c1 retrieves one readable row from the first batch (o1 and o2), none from the second, and the second readable row from the third. The returned next value is 5 (the position after o5), so the subsequent call resumes there to return o6.

This approach increases the number of queries and can result in unbounded work for subjects who can read very few rows. To prevent this, cap the number of rounds or total rows examined and return the current results with the cursor.

Put the coarse part of the rule in the query

To optimize performance, identify the coarse part of your read rules that the database can express—such as owner or tenant—and include it in the query. You then let @evanion/acl handle the fine-grained state-dependent decisions. This keeps the page mostly full because the database has already removed the majority of ineligible rows.

import { policy } from '@evanion/acl';
 
type Order = { id: string; customerId: string; status: string };
 
const access = policy<{ id: string; roles: string[] }, { order: Order }>()
  .for('order', (p) =>
    p
      .allow('read', p.eq('object.customerId', 'subject.id'))
      .deny('read', p.eq('object.status', 'withdrawn')),
  )
  .build();
 
const table: Order[] = [
  { id: 'o1', customerId: 'c2', status: 'paid' },
  { id: 'o2', customerId: 'c1', status: 'paid' },
  { id: 'o3', customerId: 'c1', status: 'withdrawn' },
  { id: 'o4', customerId: 'c1', status: 'paid' },
];
 
// Stands in for `WHERE customer_id = :customerId ORDER BY id LIMIT :limit`.
const fetchOwn = (customerId: string, limit: number): Order[] =>
  table.filter((row) => row.customerId === customerId).slice(0, limit);
 
const subject = { id: 'c1', roles: [] };
const rows = fetchOwn(subject.id, 2);
const decisions = access.canMany(subject, 'order', 'read', rows);
rows.filter((_, i) => decisions[i]?.allowed).map((row) => row.id); // -> ['o2']

Here, the query restricts customer_id to the subject, while @evanion/acl applies the deny rule on status, dropping o3 from the page. If the remaining fine rules still leave the page too short, you can pair this method with the refill loop.

The query acts as a performance filter; @evanion/acl still decides every row. A query that is too broad leaks nothing, while one that is too narrow may hide rows the rules would have allowed. Ensure the query’s condition stays in step with the rule, for instance by testing both against the same fixtures.

When the decision does not depend on the row

To avoid unnecessary filtering, use access.readsObject(kind, action) to determine if a permission actually reads the row. If it returns false, the decision is identical for every row. A single can call without an object decides the entire page, meaning the page is either fully returned or entirely refused without running a filter.

import { policy } from '@evanion/acl';
 
type Order = { id: string };
 
const access = policy<{ id: string; roles: string[] }, { order: Order }>()
  .for('order', (p) =>
    p.allow('read', p.contains('subject.roles', 'bookseller')),
  )
  .build();
 
access.readsObject('order', 'read'); // -> false
access.can({ id: 'b1', roles: ['bookseller'] }, 'order', 'read').allowed; // -> true
access.can({ id: 'c1', roles: [] }, 'order', 'read').allowed; // -> false

Perform this check once and then page normally. For more on readsObject, see Can this user do this?.