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.

Nested objects in @evanion/acl field rules

To define which parts of a data row are visible, @evanion/acl evaluates top-level keys via Object.keys. Because field rules name top-level keys only, nested paths are not supported; for example, address is a field, but address.street is not.

If you attempt to use a dotted key—whether in a field list like ['*', '!address.street'] or within targets or transitions rules—the build will refuse it. This results in an InvalidPermissionError that names the specific permission key and the invalid entry. The build also refuses a name containing a backslash, which is reserved as the path escape. A flat data key that literally contains a dot cannot be named by a rule.

The example below demonstrates a refused build followed by the correct way to hide a nested field.

import {
  InvalidPermissionError,
  pickAllowedFields,
  policy,
} from '@evanion/acl';
import { expect } from 'vitest';
 
type Address = { city: string; street: string };
type Order = { id: string; address: Address };
 
// Field rules name top-level keys, and a dotted entry is refused.
const dotted = () =>
  policy<{ id: string }, { order: Order }>()
    .for('order', (p) =>
      p.allow('read', p.always).fields(['*', '!address.street']),
    )
    .build();
expect(dotted).toThrow(InvalidPermissionError);
 
// The nested shape gets its own object kind, decided with its own call.
const access = policy<{ id: string }, { order: Order; address: Address }>()
  .for('order', (p) => p.allow('read', p.always))
  .for('address', (p) => p.allow('read', p.always).fields(['*', '!street']))
  .build();
 
const customer = { id: 'c1' };
const order: Order = {
  id: 'o1',
  address: { city: 'Malmo', street: 'Storgatan 1' },
};
 
const top = access.canFields(customer, 'order', 'read', order, 'read');
Object.keys(top.fields); // -> ['id', 'address']
top.fields['address']; // -> 'allowed'
 
const nested = pickAllowedFields(top, order).address ?? {
  city: '',
  street: '',
};
const address = access.canFields(customer, 'address', 'read', nested, 'read');
pickAllowedFields(address, nested); // -> { city: 'Malmo' }

Conditions share this same limitation, as a path can only read one field of a scope. As detailed in What can throw?, a path like object.address.city will cause the policy to be refused during the build process.

To hide a specific part of a nested object, you must decide its visibility separately. You can achieve this by giving the nested shape its own object kind with its own field rules, then calling canFields on the nested value after the parent has been picked. In this pattern, the row-level gate remains on the parent kind, while the nested kind permits read unconditionally.

Because @evanion/acl does not automatically walk into values, a response containing three nested objects requires three additional canFields calls per row. To reduce this overhead, you can flatten sensitive nested data into its own top-level field on the row.

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?.