Field permissions

canFields answers which parts of an object a subject may touch, on one of two axes.

The two axes canFields decides

read is a projection and write is what a form submits. Field rules hang off one permission, declared per object kind and per action. A .for('listing') beside the policy below carries its own field rules in the same document.

import { policy } from '@evanion/acl';
 
const access = policy<{ id: string }, { listing: { status: string } }>()
  .for('listing', (p) => p.allow('read', p.always).fields(['*', '!status']))
  .build();
 
const fd = access.canFields(
  { id: 's1' },
  'listing',
  'read',
  { status: 'draft' },
  'read',
);
fd.fields['status']; // -> 'denied'

What canFields returns

canFields returns a FieldDecision: the field maps fields and reasons, the action-level Decision they hang off as action, and allowed, which is true when the action is allowed and every field is allowed.

import { policy } from '@evanion/acl';
import type { FieldDecision } from '@evanion/acl';
 
type Listing = {
  sellerId: string;
  title: string;
  price: number;
  status: string;
};
 
const access = policy<{ id: string }, { listing: Listing }>()
  .for('listing', (p) =>
    p
      .allow('update', p.eq('object.sellerId', 'subject.id'))
      .fields(['title', 'price']),
  )
  .build();
 
const current = {
  sellerId: 's1',
  title: 'Wingspan',
  price: 499,
  status: 'draft',
};
const proposed = { price: 449, status: 'published' };
 
const fd: FieldDecision = access.canFields(
  { id: 's1' },
  'listing',
  'update',
  current,
  'write',
  proposed,
);
 
fd.action.allowed; // -> true
fd.allowed; // -> false
fd.fields; // -> { sellerId: 'denied', title: 'allowed', price: 'allowed', status: 'denied' }
fd.reasons; // -> { sellerId: 'not-listed', title: 'allow', price: 'allow', status: 'not-listed' }

Every name in fields carries one FieldState:

• allowed: the subject may read the field, or write it with this value.
• denied: the rules refuse it.
• unevaluable: the decision needs data the call did not carry.

canFields fills the field maps whatever the action says, so a blocked caller still learns which fields would be editable. Only the top-level allowed is gated on the action, and that flag composes both halves. A caller who reads the maps as the gate skips the action entirely.

reasons carries one FieldReason per name.

Naming the fields

fields takes either a name list or an object carrying one plus the per-field configs.

import { policy } from '@evanion/acl';
 
type Listing = {
  id: string;
  title: string;
  price: number;
  status: 'draft' | 'published';
  visibility: string;
};
 
const access = policy<
  { id: string },
  { listing: Listing },
  { listing: 'read' | 'update' | 'publish' }
>()
  .for('listing', (p) =>
    p
      .allow('read', p.always)
      .fields(['*', '!status']) // everything except status
      .allow('update', p.always)
      .fields(['title', 'price']) // exactly these two
      .allow('publish', p.always)
      .fields({
        fields: ['*', '!id'],
        status: { transitions: { draft: ['published'], published: [] } },
        visibility: { targets: ['public', 'private'] },
      }),
  )
  .build();
 
const bookseller = { id: 'u1' };
const listing: Listing = {
  id: 'l1',
  title: 'Wingspan',
  price: 499,
  status: 'draft',
  visibility: 'private',
};
 
const read = access.canFields(bookseller, 'listing', 'read', listing, 'read');
read.fields['status']; // -> 'denied'
 
const update = access.canFields(
  bookseller,
  'listing',
  'update',
  listing,
  'write',
  {
    title: 'Wingspan (second edition)',
    status: 'published',
  },
);
update.fields['title']; // -> 'allowed'
update.fields['status']; // -> 'denied'
 
const publish = access.canFields(
  bookseller,
  'listing',
  'publish',
  listing,
  'write',
  {
    id: 'l2',
    status: 'published',
    visibility: 'secret',
  },
);
publish.reasons; // -> { id: 'not-listed', title: 'allow', price: 'allow', status: 'allow', visibility: 'targets-failed' }

* is the baseline and !name subtracts from it. Both are authoring syntax and never field names, wherever they turn up: in the rules, on the object, or in a proposed write.

With no name list at all, every unnamed key is writable. A targets or transitions config restricts the field it names and no other, so an author who reads one as the writable-field list leaves the rest open.

targets and transitions

targets allow-lists the proposed value. transitions is a state machine over the current value: the key is the value the object holds now, the array is what it may become.

The object form keys the configs by field name and takes fields for the name list, so a field called fields gets no config. The name list can still allow or deny it.

Construction refuses these authoring mistakes.

Which fields are decided

The matrix does not know the object’s shape, so the decision covers four sources of names:

• every field the object carries;
• every field the rules name;
• every name in the list;
• on the write axis, every key of the proposed write.

That last source is the mass-assignment case: a key that exists nowhere but the write still gets a state.

The read axis takes no write. targets and transitions are write concepts, and on read only the name list denies.

Passing a projection

canFields takes a partial object, so a caller holding a projection can ask. A field the projection omits, that no rule names and that the write does not propose, appears in neither fields nor reasons.

A name absent from the map is a question nobody asked, and pickAllowedFields withholds it. Caveats and pitfalls has the filter that gets this wrong.

access.readsObject(key, action) says whether the action behind the fields needs the row at all.

Writing

Pass the proposed object to canFields on the write axis.

import { policy, pickAllowedFields } from '@evanion/acl';
 
const access = policy<
  { id: string },
  { question: { askedBy: string; body: string; status: string } }
>()
  .for('question', (p) =>
    p
      .allow('update', p.eq('object.askedBy', 'subject.id'))
      .fields(['*', '!status']),
  )
  .build();
 
const current = { askedBy: 'customer-41', body: 'In stock?', status: 'open' };
const proposed = { body: 'Wingspan in stock?', status: 'locked' };
 
const fd = access.canFields(
  { id: 'customer-41' },
  'question',
  'update',
  current,
  'write',
  proposed,
);
 
fd.action.allowed; // -> true
fd.fields['status']; // -> 'denied'
JSON.stringify(pickAllowedFields(fd, proposed)); // -> '{"body":"Wingspan in stock?"}'

Pass what pickAllowedFields returns to the ORM, and pass only that.

• Every key it carries was marked allowed by the decision.
• denied and unevaluable are both withheld, and so is any key the decision does not carry.
• pickAllowedFields throws ActionNotAllowedError when the action itself is refused.
• A field the action allows and the field rules deny is a partial write, so that call returns the allowed subset and throws nothing.

__proto__ names no field, so it never enters a decision map and never leaves the narrowing. The narrowed result is safe to spread onto a row.

Reading

The read axis answers which fields of an instance this subject may see.

import { pickAllowedFields, policy } from '@evanion/acl';
 
type Question = { askedBy: string; body: string; askerEmail: string };
 
const access = policy<{ id: string }, { question: Question }>()
  .for('question', (p) =>
    p.allow('read', p.always).fields(['*', '!askerEmail']),
  )
  .build();
 
// The row as the handler fetched it, email included.
const question = {
  askedBy: 'customer-41',
  body: 'Is Wingspan in stock?',
  askerEmail: '[email protected]',
};
 
const view = access.canFields(
  { id: 'customer-92' },
  'question',
  'read',
  question,
  'read',
);
 
view.fields['askerEmail']; // -> 'denied'
pickAllowedFields(view, question); // -> { askedBy: 'customer-41', body: 'Is Wingspan in stock?' }

canFields decides a projection on read and runs no query: the row was already fetched, and a field decided denied here was still read out of the database.

How to manage nested fields in @evanion/acl

To control access to deeply nested data, you use paths. While address refers to a top-level key of a row, address.street targets the street property inside that object.

Defining Path Rules

You define access by listing paths in a name list. An entry allows that path and everything below it, while an entry starting with ! hides that path and its descendants.

Because exclusions only work if there is something to exclude, a ! entry requires a * or a listed ancestor, in any order. For example:

• ['*', '!address.street'] allows everything except the street.
• ['id', 'address', '!address.street'] allows the ID and the address, but hides the street.

These paths apply to both axes; for instance, a targets or transitions key can be a path like 'address.country'.

Path Constraints and Escaping

A path can have a maximum of 32 segments. Segments cannot be empty, cannot be *, cannot be __proto__, and cannot start with !.

If a key contains a literal . or \, you must escape it with a backslash:

• The flat key a.b is written as a\.b.
• The key a\b is written as a\\b. The decision maps use this same spelling.

Resolving Leaves

The map tracks only the “leaves” that the rules reach. If you apply ['*', '!address.street'] to { id, address: { city, street } }, the resulting keys are id, address.city and address.street, and the last is denied. Note that address itself is not a key; a key and its descendant never both appear in the result.

Writing to Nested Objects

When you use pickAllowedFields to filter a row, it rebuilds every parent as a new object containing only the allowed children. This means a parent becomes a “partial” object if some of its children are withheld.

Object.assign(row, picked) replaces a full stored parent with one of these partial parents, which would erase any stored key the caller isn’t allowed to write. To prevent that, the engine denies the parent before pickAllowedFields runs when the stored parent holds such a key.

The engine determines traversability based on the stored object:

• Denied (not-traversable): If a stored parent contains a key that is denied, cannot be decided, is not a field name, or is a symbol/non-enumerable property, the parent is marked not-traversable and pickAllowedFields omits it.
• Unevaluable (missing-field): If a rule descends into a parent that the write operation provides but the stored object lacks, the parent is marked missing-field.

import { pickAllowedFields, policy } from '@evanion/acl';
import { expect } from 'vitest';
 
type Row = {
  id: string;
  address: { city: string; street?: string; zip?: string };
};
 
const access = policy<{ id: string }, { row: Row }>()
  .for('row', (p) => p.allow('update', p.always).fields(['id', 'address.city']))
  .build();
const editor = { id: 'u1' };
 
// The stored address holds a street the editor may not write. A parent that
// would erase it is denied, so the write never reaches the row.
const stored: Row = {
  id: 'r1',
  address: { city: 'Malmo', street: 'Storgatan 1' },
};
const write = { id: 'r1', address: { city: 'Lund' } };
const refused = access.canFields(
  editor,
  'row',
  'update',
  stored,
  'write',
  write,
);
refused.fields; // -> { id: 'allowed', address: 'denied' }
refused.reasons.address; // -> 'not-traversable'
pickAllowedFields(refused, write); // -> { id: 'r1' }
 
// The stored address holds only the city, so the whole parent is writable.
const bare: Row = { id: 'r1', address: { city: 'Malmo' } };
const allowed = access.canFields(editor, 'row', 'update', bare, 'write', write);
allowed.fields; // -> { id: 'allowed', 'address.city': 'allowed' }
const picked = pickAllowedFields(allowed, write);
picked; // -> { id: 'r1', address: { city: 'Lund' } }
 
// Object.assign replaces row.address with the picked address whole. Here the
// stored address held only the city, so the replace drops nothing.
const row = structuredClone(bare);
Object.assign(row, picked);
expect(row).toEqual({ id: 'r1', address: { city: 'Lund' } });
 
// A stored key the editor may write, left out of the write, is erased by the
// replace. The write must carry every sibling it keeps.
const withZip = policy<{ id: string }, { row: Row }>()
  .for('row', (p) =>
    p.allow('update', p.always).fields(['id', 'address.city', 'address.zip']),
  )
  .build();
const zipped = { id: 'r1', address: { city: 'Malmo', zip: '211' } };
const partial = { address: { city: 'Lund' } };
const lost = withZip.canFields(
  editor,
  'row',
  'update',
  zipped,
  'write',
  partial,
);
lost.allowed; // -> true
const merged = structuredClone(zipped);
Object.assign(merged, pickAllowedFields(lost, partial));
merged; // -> { id: 'r1', address: { city: 'Lund' } }
 
// A deep merge keeps the siblings the write left out. It recurses only into
// own plain objects, and skips the names that lead to a prototype.
const UNSAFE = new Set(['__proto__', 'constructor', 'prototype']);
const isPlain = (value: unknown): value is Record<string, unknown> =>
  typeof value === 'object' &&
  value !== null &&
  [Object.prototype, null].includes(Object.getPrototypeOf(value));
function deepMerge(
  target: Record<string, unknown>,
  patch: Record<string, unknown>,
): void {
  for (const key of Object.keys(patch)) {
    if (UNSAFE.has(key)) continue;
    const next = patch[key];
    const own = Object.hasOwn(target, key) ? target[key] : undefined;
    if (isPlain(next) && isPlain(own)) deepMerge(own, next);
    else target[key] = next;
  }
}
const kept = structuredClone(zipped);
deepMerge(kept, pickAllowedFields(lost, partial));
kept; // -> { id: 'r1', address: { city: 'Lund', zip: '211' } }
 
// A subtree the decision does not descend into is copied by reference, so it
// can carry an own __proto__ key from JSON.parse. The merge skips it.
const open = policy<{ id: string }, { row: Row }>()
  .for('row', (p) => p.allow('update', p.always).fields(['*']))
  .build();
const hostile = JSON.parse('{"address":{"__proto__":{"isAdmin":true}}}');
const target = structuredClone(zipped);
deepMerge(
  target,
  pickAllowedFields(
    open.canFields(editor, 'row', 'update', zipped, 'write', hostile),
    hostile,
  ),
);
'isAdmin' in target.address; // -> false
 
// A raw dotted key whose path leaves a ruled node is refused, because Mongo $set
// and lodash set would apply it as a path.
const guarded = policy<{ id: string }, { row: Row }>()
  .for('row', (p) =>
    p.allow('update', p.always).fields(['*', '!address.street']),
  )
  .build();
const dotted = { 'address.city': 'Lund' } as Partial<Row>;
const pathKey = guarded.canFields(
  editor,
  'row',
  'update',
  bare,
  'write',
  dotted,
);
pathKey.reasons['address\\.city']; // -> 'not-traversable'
expect(pathKey.allowed).toBe(false);

Recommendation: To change a single nested key without risking its siblings, give the nested object its own action and permission, or define it as its own object kind. This allows the caller to write the street or city via rules that name them directly.

What a picked parent replaces

To update a nested value, you must provide the entire parent object because a picked parent replaces the stored parent in its entirety. The engine only protects stored keys that the caller is explicitly forbidden from writing; any key the caller is allowed to write—but omits from the update—is erased by the replacement.

To prevent data loss during updates, you must choose how to apply the filtered data to your stored records.

Consider a scenario where your allowed rules are ['id', 'address.city', 'address.zip'] and the stored row is { address: { city, zip } }. If a user submits a write containing only { address: { city } }, the write is permitted, but a shallow Object.assign would drop the zip from the stored row. To avoid this, the write must either carry every sibling it intends to keep, or the application code must deep-merge the picked value into the row.

A deep merge recurses only into own plain objects and copies all other values as-is. To prevent prototype pollution, it explicitly skips __proto__, constructor, and prototype. Because pickAllowedFields copies subtrees that the decision does not descend into by reference, those subtrees could potentially carry an own __proto__ key (e.g., from JSON.parse). A subsequent merge would then set the prototype of the stored object. The example above concludes with such a merge.

Some tools handle this natively. An ORM with a nested update form, for instance, applies only the keys it is given and leaves other stored keys untouched, removing the need for a manual merge. For example, Prisma’s update({ data: { address: { update: picked.address } } }) updates the city while preserving the zip.

Even when every specific field is marked as allowed, @evanion/acl will refuse a write in two specific scenarios to prevent data loss or traversal errors.

Array-Based Configuration

If a targets or transitions configuration path passes through an array (for example, 'lines.cost'), the array is refused as not-traversable on every write. This occurs because the write axis is not designed to walk through arrays.

Nested Allow Entries

When using nested allow entries or configurations—such as address.city or 'address.country': { targets: ['SE'] }—the library may refuse the parent object as not-traversable. This happens if the stored parent contains a sibling that the caller is forbidden from writing (e.g., a street defined under !address.street). Because the write operation would replace the entire parent object, it would inadvertently erase the protected sibling.

Rows with dotted column names

A row can carry flat keys with a dot in them, such as SQL aliases or Sequelize raw columns.

When a raw key contains a ., it is decided twice: once as a flat key and once as a path. A dotted key is allowed only if the flat reading permits it and the path spelled by splitting the key at the dot is not excluded. The path reading acts as a filter that can only tighten the result.

For example, if your allowed list is ['a'], a flat key of { 'a.b': 1 } remains hidden, because the flat reading does not list it and the path reading never loosens a decision. Similarly, ['id', 'address.city'] hides a flat address.city column. To explicitly allow a flat column containing a dot, use a backslash to escape the character: address\.city. On the read axis, an allow entry using this escaped flat key tells the library to let the flat reading decide alone. This allows a specific flat column to remain visible even if an ancestor in its path has been excluded. For example, given the pattern ['*', '!address', 'address\.city'], the @evanion/acl package hides the nested address object but ensures the flat address.city column is shown.

Reading Segmented Keys

On the read axis, brackets are treated as ordinary characters within a segment. This means a key containing brackets splits on the . character like any other key.

For example, if your rules are ['*', '!data'], the key data.x[0] is denied because it starts with the denied data segment. Similarly, under ['*', '!address.street'], the key address.street[0] is marked as not-traversable.

A bracket does not split a key; the entire string, including the brackets, is a single segment. For example, under the rule ['*', '!data'], the key data[0] is allowed because the segment data[0] is not strictly equal to data. Consequently, a rule targeting data will not cover query-string style keys like data[0].

Traversal and Escaping

The path reading enforces boundaries using the not-traversable denial. A dotted key is denied if its spelled path ends at a rule node that has further rules below it, or if the path attempts to leave that node.

This behavior ensures strict isolation. For instance:

• Under ['*', '!address.street'], the flat key address.x is denied as not-traversable.
• Under !lines.cost, the key lines.0.cost is similarly denied.

If a split is not “clean,” the library utilizes the clean prefix. Finally, any rule written with an escape, such as a\.b, refers specifically to the flat key a.b itself.

import { pickAllowedFields, policy } from '@evanion/acl';
 
// A row with flat columns whose names hold a dot, such as SQL aliases.
type Flat = Record<string, unknown>;
const row: Flat = {
  id: 'r1',
  'address.street': 'Storgatan 1',
  'address.city': 'Malmo',
  'other.col': 'x',
};
const viewer = { id: 'u1' };
 
// The exclusion names address.street, so the flat column of that name is hidden.
const hidden = policy<{ id: string }, { row: Flat }>()
  .for('row', (p) => p.allow('read', p.always).fields(['*', '!address.street']))
  .build();
const hiddenDecision = hidden.canFields(viewer, 'row', 'read', row, 'read');
hiddenDecision.reasons['address\\.street']; // -> 'not-listed'
// address.city is a flat column under a parent that has rules, so it is hidden too.
hiddenDecision.reasons['address\\.city']; // -> 'not-traversable'
// A dotted column no rule touches stays visible.
pickAllowedFields(hiddenDecision, row); // -> { id: 'r1', 'other.col': 'x' }
 
// An allow entry that escapes the dot names the flat column, and the flat reading decides alone.
const shown = policy<{ id: string }, { row: Flat }>()
  .for('row', (p) =>
    p.allow('read', p.always).fields(['id', 'address\\.street']),
  )
  .build();
const shownDecision = shown.canFields(viewer, 'row', 'read', row, 'read');
pickAllowedFields(shownDecision, row); // -> { id: 'r1', 'address.street': 'Storgatan 1' }
 
const edit = { 'address.street': 'Lilla Torg 2' };
 
// An allow entry naming the escaped column writes that column and no other dotted one.
const columnEdit = policy<{ id: string }, { row: Flat }>()
  .for('row', (p) =>
    p.allow('update', p.always).fields(['id', 'address\\.street']),
  )
  .build();
const withOther = { ...edit, 'other.col': 'y' };
const written = columnEdit.canFields(
  viewer,
  'row',
  'update',
  row,
  'write',
  withOther,
);
written.reasons['address\\.street']; // -> 'allow'
written.reasons['other\\.col']; // -> 'not-listed'
pickAllowedFields(written, withOther); // -> { 'address.street': 'Lilla Torg 2' }
 
// An exclusion on an ancestor of the column's path still refuses it.
const fenced = policy<{ id: string }, { row: Flat }>()
  .for('row', (p) =>
    p.allow('update', p.always).fields(['*', '!address', 'address\\.street']),
  )
  .build();
const fencedDecision = fenced.canFields(
  viewer,
  'row',
  'update',
  row,
  'write',
  edit,
);
fencedDecision.reasons['address\\.street']; // -> 'not-traversable'
 
// * alone writes a dotted column no rule touches, and every other column too.
const starEdit = policy<{ id: string }, { row: Flat }>()
  .for('row', (p) => p.allow('update', p.always).fields(['*']))
  .build();
const everything = { ...withOther, id: 'r2' };
const starDecision = starEdit.canFields(
  viewer,
  'row',
  'update',
  row,
  'write',
  everything,
);
pickAllowedFields(starDecision, everything); // -> { 'address.street': 'Lilla Torg 2', 'other.col': 'y', id: 'r2' }
 
// On read a bracket is part of its segment: data.x[0] spells a path through
// data, and data[0] is a segment of its own.
const noData = policy<{ id: string }, { row: Flat }>()
  .for('row', (p) => p.allow('read', p.always).fields(['*', '!data']))
  .build();
const bracketed: Flat = { id: 'r1', 'data.x[0]': 1, 'data[0]': 2 };
const bracketDecision = noData.canFields(
  viewer,
  'row',
  'read',
  bracketed,
  'read',
);
bracketDecision.reasons['data\\.x[0]']; // -> 'not-listed'
pickAllowedFields(bracketDecision, bracketed); // -> { id: 'r1', 'data[0]': 2 }

Pass plain rows

The walk reads the top-level object exactly as it is, regardless of its class, though all nested values must be plain objects. If an ORM wrapper stores data under an own property (such as Sequelize’s dataValues), that wrapper will leak at the top level even when using flat rules.

To ensure consistent behavior, pass plain rows for both the top level and all nested values using methods like toJSON(), get({ plain: true }), or .lean().

Write-Axis Restrictions

On the write axis, the engine prevents “raw” keys from being used if a path writer would interpret them as a path. Because tools like Mongo’s $set and lodash’s set apply keys as paths to write below a parent, the engine imposes stricter restrictions to prevent accidental traversal.

A key is marked not-traversable on the write axis if:

• It contains brackets ([ or ]).
• Its dots do not split into a clean path.
• It attempts to leave the rule tree (e.g., address.city when the rules are !address.street).
• It holds a constructor or prototype segment, which a merge that splits the key would follow to a prototype.

The engine determines which dotted columns a write updates from how your entries name them. When an allow entry explicitly names an escaped column, the engine writes to that raw dotted key. For example, if an updateCity action has the fields ['id', 'address\.city'], the engine writes the flat address.city column and no other dotted column; any other, such as other.col, remains not-listed.

To specify which columns are written, you use a list of fields. The * symbol acts as a catch-all: it writes every dotted column that no other rule touches, along with every other column in the row.

Adding an escaped entry beside * (for example, ['*', 'address\.city']) does not narrow the operation; the * still captures everything. To write exactly one dotted column and no others, list that column escaped without the *, alongside the fields the action requires: ['id', 'address\.city'].

Even if a dotted key is explicitly listed, the engine refuses the write as not-traversable if the path to that column is restricted. This happens in three scenarios:

1. An exclusion on the column’s path or any of its ancestors, as in ['*', '!address', 'address\.city'] or ['*', '!address.city', 'address\.city'].
2. A config on an ancestor in the path, such as address: { targets: ['x'] }.
3. A rule node with further rules beneath it, where the path ends at that node (address.city.x is in the list) or departs from it (!address.street is in the list).

While these rules determine whether a path is traversable, the config on the column itself determines what is written. For instance, 'address.city': { targets: ['Lund'] } still controls which values the write is permitted to carry. The list cannot override structural invalidity: any key containing brackets, or dots that do not resolve into a clean path, is always refused.

The nested form cannot reach a flat column. Consider these two scenarios:

• Under ['id', 'address\.city'], the engine refuses address as not-listed.
• Under ['id', 'address.city'], if the stored row holds no address object, the engine marks address as missing-field.

In every refused case, pickAllowedFields drops the key, ensuring the write never reaches the column.

Handling Arrays

When a path segment reaches an array, the rule applies to every element within that array. For example, !lines.cost hides the cost field on every line; the resulting key is lines.cost without a specific index. The keys available under an array are the union of all keys carried by its elements.

Rules in @evanion/acl cannot index into arrays. If a rule attempts to index into an array (such as !items.0 or !items.0.price), the array is marked as denied and not-traversable on both axes, preventing any element from being read or written.

Note that this restriction only applies to actual arrays; a numeric segment used as a key in a plain object (such as byId.1.name) is treated as an ordinary key and remains valid.

Write Limitations: Because the engine cannot reliably match a stored array element to a proposed one, any array that a rule descends into is refused entirely on the write axis. Additionally, any array with holes, extra own properties, or elements the walk cannot see into is refused on both axes. pickAllowedFields never drops individual array elements; you must write array elements through their own dedicated action.

Values the Walk Cannot See Into

The engine’s walk only penetrates plain objects and arrays. The following are treated as leaves:

• Primitives, null, Date, Map, class instances, or objects with getters.

If a rule names a path below one of these leaves, the value is denied as not-traversable. On read, the entire value is hidden; on write, it is refused. Circular references are also marked not-traversable at the point of repetition.

ORM Warning: Since ORM rows are typically class instances with getters, a nested one is unwalkable. Convert an ORM row to a plain object before calling canFields, otherwise every value under a descending rule will be hidden. The top-level object is read as it is, whatever its class, so a wrapper that keeps its data under an own property leaks (see Pass plain rows above).

import { pickAllowedFields, policy } from '@evanion/acl';
 
type Shop = { id: string; owner: unknown; opened: unknown };
const access = policy<{ id: string }, { shop: Shop }>()
  .for('shop', (p) =>
    p.allow('read', p.always).fields(['*', '!owner.email', '!opened.at']),
  )
  .build();
const viewer = { id: 'u1' };
 
// A class instance and a Date are values the walk cannot see into.
class Owner {
  email = '[email protected]';
}
const shop: Shop = { id: 's1', owner: new Owner(), opened: new Date(0) };
const decision = access.canFields(viewer, 'shop', 'read', shop, 'read');
decision.reasons; // -> { id: 'allow', owner: 'not-traversable', opened: 'not-traversable' }
pickAllowedFields(decision, shop); // -> { id: 's1' }
 
// A plain copy of the same row is walkable.
const plain = {
  id: 's1',
  owner: { email: '[email protected]', name: 'A' },
  opened: { at: 1 },
};
const copy = access.canFields(viewer, 'shop', 'read', plain, 'read');
pickAllowedFields(copy, plain); // -> { id: 's1', owner: { name: 'A' } }

Typed Paths

When using the typed builder, .fields() validates every path against the object kind’s type. If a path is unknown, it results in a compile error.

If a kind is typed as Record<string, unknown>, the builder accepts any path. If the kind is a generic type parameter, the builder cannot list its paths, so use the untyped builder.

To resolve a path, the system uses different logic for types and values: the type check follows the declared type, while the runtime walk follows the actual value.

If you define a path through a class-typed property—for example, owner.email where owner is an Owner instance—the code will compile because the type exists. However, the runtime walk cannot see into the class instance, so the value is denied as not-traversable.