Why was this refused?

Every decision access.can returns carries reason beside allowed, and rule or missing where one applies, and a screen reads those three to tell a customer why an action is off.

Turning an acl refusal into what the screen says

The Edit button under a question is off, and the customer wants to know why. A button that says “Not allowed” for every allowed: false tells a customer whose row is still loading that they may never edit their own question.

allowed is still the only field a handler gates on, as Can this user do this? sets out. reason, rule and missing decide the label. The policy below carries a deny rule, written with p.deny, which refuses whenever it matches and outranks the allow, and .id(name) gives that rule the name a decision reports:

import { policy } from '@evanion/acl';
import type { Decision } from '@evanion/acl';
 
type Question = { askedBy: string; status: string };
 
const access = policy<{ id: string }, { question: Question }>()
  .for('question', (p) =>
    p
      .allow('update', p.eq('object.askedBy', 'subject.id'))
      .deny('update', p.eq('object.status', 'locked'))
      .id('locked-question'),
  )
  .build();
 
/** What the Edit button under a question says. */
function editLabel(decision: Decision): string {
  if (decision.allowed) return 'Edit';
  if (decision.reason === 'denied') return `Locked (${decision.rule})`;
  if (decision.reason === 'unevaluable') return 'Checking';
  return 'Not your question';
}
 
const asker = { id: 'customer-41' };
const ask = (row: Partial<Question>) =>
  access.can(asker, 'question', 'update', row);
 
editLabel(ask({ askedBy: 'customer-41', status: 'open' })); // -> 'Edit'
editLabel(ask({ askedBy: 'customer-41', status: 'locked' })); // -> 'Locked (locked-question)'
editLabel(ask({ askedBy: 'customer-92', status: 'open' })); // -> 'Not your question'
 
// The list query did not select `status`, so the deny rule could not be read.
const partial = ask({ askedBy: 'customer-41' });
editLabel(partial); // -> 'Checking'
partial.rule; // -> 'locked-question'
partial.missing; // -> ['object.status']

editLabel reads allowed first and then reason. denied means a deny rule matched, and rule names it, because .id('locked-question') gave the rule that name. The last call passed a row without status, so the deny rule could not be read: the decision is unevaluable, missing names object.status, and the button says Checking while the screen fetches that one field.

The seven reasons an acl decision carries

reason takes one of seven values, and each one tells a screen something different:

reason, rule and missing are output only, and no part of the library reads them back. A screen branches on reason to pick a label. A handler that branches on it to allow something has written a rule of its own beside the policy.

stale-contract comes from a document another service published. The service holding a copy tells parseMatrix, the call that adopts a foreign document, when it last fetched that copy, as fetchedAt. The document states how long a copy stays good, as maxStale in milliseconds, and past that bound every key answers stale-contract. A fresh fetch repairs it, and How long a consumer may keep deciding on an acl contract sets out the bound.

When the acl clock decides unusable-clock

can, canMany, canFields and capabilities take now as a trailing argument: an ISO 8601 string, epoch milliseconds or a Date. Omit it and the call reads the wall clock. A rule built with p.after or p.before compares that instant against a boundary, so p.after('now', '2026-10-01T09:00:00Z') holds once the call’s instant passes the boundary. The third type argument names place as an action of preorder, because the default actions are create, read, update and delete:

import { policy } from '@evanion/acl';
 
// Preorders for a new game open at one instant.
const access = policy<
  { id: string },
  { preorder: { game: string } },
  { preorder: 'place' }
>()
  .for('preorder', (p) =>
    p
      .allow('place', p.after('now', '2026-10-01T09:00:00Z'))
      .id('preorders-open'),
  )
  .build();
 
const shopper = { id: 'customer-41' };
const place = (now: string | number) =>
  access.can(shopper, 'preorder', 'place', undefined, now);
 
place('2026-10-02T12:00:00Z').allowed; // -> true
place(Date.parse('2026-09-30T12:00:00Z')).reason; // -> 'no-rule-matched'
 
// A header that was never a date. The rule that compared the clock is named.
const garbled = place('next tuesday');
garbled.reason; // -> 'unusable-clock'
garbled.rule; // -> 'preorders-open'
'missing' in garbled; // -> false

A now that does not parse never throws. The permission refuses with unusable-clock, names the rule that compared the clock, and carries no missing, because no refetch repairs it. Fix the value the call passes.

rule, the acl rule that decided

allow, denied and unusable-clock always carry rule. An unevaluable carries it only when a deny rule was unreadable: one deny rule refuses on its own, so the engine names it. When the unreadable rules were allow rules, any one of them could have granted, so no single rule is named.

The name comes from one of two places:

• A rule the author named reports that name. A policy written with policy() names a rule with .id(name) after the allow or deny that wrote it.
• A rule nobody named reports a derived id, the side it sits on and a hash of its conditions, such as allow-53eebf50.

Store a name the author wrote, and never store a derived one. A release of this library that changes how a condition is represented changes every derived id, so an audit row holding allow-53eebf50 stops matching its rule with nothing to report it.

Treat rule as a log line and a support answer, such as “denied by locked-question”. Never branch on it: two rules can grant the same thing, and which one matched is not a fact the app should depend on.

When the answer is unevaluable

unevaluable says the engine never reached an answer, because a rule read an object.* path the row did not carry. allowed is already false, so nothing leaks, and missing names exactly what to fetch. A caller meets it with no row at all, as a create button does, or with a projection, a row loaded with only some of its columns. Can this user do this? works the refetch through.

Both sides’ unreadable paths arrive in one missing, so one query settles the permission however many rules read the row. Every operator treats an absent object.* path as unevaluable, including ne (not equal) and not-in, because “not equal to locked” states no fact about a field nobody read. An absent subject.* path fails its condition instead, because the server resolves the subject whole and never projects it.

What to do with an acl unevaluable

Deciding before the row is loaded works the last row through.

Explaining one field of an acl field decision

canFields decides each field of a write separately, as Which fields may they write? covers, and gives every field a state and a FieldReason. A read-only input names its reason the way a refused button does:

Which fields may they write? builds a policy that produces allow, not-listed, transition-failed and missing-field, and Field permissions is the reference.

Debugging Decisions with explain

When a request is denied, a simple allowed: false doesn’t tell you why. A user might be blocked because they have the wrong role, or because a specific “deny” rule overrode their permissions. For developers building admin dashboards or permission checkers, knowing the difference is critical.

While access.can() returns a Decision that names only the deciding rule, access.explain() provides a full audit trail of the logic used to reach that conclusion.

How Explanation Works

The access.explain(subject, key, action, object, now) function accepts the same arguments as can(), but it returns an Explanation object.

The most significant difference between the two is their execution: can() stops the moment it finds a deciding rule to optimize performance. explain(), however, evaluates every condition of every rule. This means if a “suspended owner” is denied access, the explanation will show you both the deny rule that blocked them and the allow rule that would have granted access if they weren’t suspended.

Understanding the Explanation Object

The Explanation object breaks down the decision process into three primary areas:

1. The Final Result

• decision: The Decision can() returns for the same call.
• step: Indicates which precedence step (1 through 7) ultimately decided the outcome.

2. Rule Analysis The allow and deny lists enumerate every rule within the permission. Each rule is labeled with its status:

• matched: The rule’s conditions were met.
• not-matched: The rule’s conditions were not met.
• unevaluable: The row lacked a path a condition reads.
• unusable-clock: Occurs if the now argument passed to the call is not a valid instant.

3. Condition Details Within each rule, every condition is tracked individually:

• holds: The condition is true.
• fails: The condition is false.
• unevaluable: The row lacked a path the condition reads.
• missing: The object.* paths the row lacked, present only on unevaluable.
• unusable-clock: The now argument was not an instant.

import { policy } from '@evanion/acl';
 
type Question = { ownerId: string };
type Asker = { id: string; roles: string[] };
 
const access = policy<Asker, { question: Question }>()
  .for('question', (p) =>
    p
      .allow('update', p.eq('object.ownerId', 'subject.id'))
      .id('owner')
      .deny('update', p.contains('subject.roles', 'suspended'))
      .id('suspended'),
  )
  .build();
 
const owner = { id: 'customer-41', roles: ['suspended'] };
const why = access.explain(owner, 'question', 'update', {
  ownerId: 'customer-41',
});
 
why.decision.reason; // -> 'denied'
why.step; // -> 1
why.deny[0]?.state; // -> 'matched'
// The allow rule is reported too: the deny decided, and the owner condition held.
why.allow[0]?.conditions[0]?.state; // -> 'holds'
 
// Without the row, the owner condition names the path it could not read.
const unloaded = access.explain(
  { id: 'customer-41', roles: [] },
  'question',
  'update',
);
unloaded.decision.reason; // -> 'unevaluable'
unloaded.allow[0]?.conditions[0]?.state; // -> 'unevaluable'
unloaded.allow[0]?.conditions[0]?.missing; // -> ['object.ownerId']

Implementation Details

Safe for Logging The explanation object is designed to be portable. It stores states and paths, but it does not store actual values from the subject or the data row. This ensures you can log explanations to a client or external monitoring tool without leaking sensitive data.

Edge Cases and Scope

• Empty Explanations: If a document has exceeded its maxStale budget, or if the document does not carry the requested action, explain() returns the can decision with empty allow/deny lists and no step.
• Binding: You can use authorize(subject).explain(key, action, object) or object(key).explain(subject, action, object) to pre-bind the subject or the key.
• Field-Level Permissions: Because field-specific decisions carry their own reasons via canFields, the explain() function focuses exclusively on the primary action.