Strict Mode, Errors & Names

Access management is sensitive, so AccessControl never fails silently. This page covers how it surfaces problems and the knobs that control naming and error output.

Strict mode (typo protection)

policy.strict turns unknown names into loud errors instead of silent denials. It’s a boolean or a per‑key object.

new AccessControl(grants, {
  policy: { strict: { actions: true, resources: true } }
});

key	default	effect
roles	on	unknown role at check time → throws ROLE_NOT_FOUND
checks	on	an unverifiable own check (record/owner missing) → deny
actions	off	unknown action → throws UNKNOWN_ACTION (else silent deny)
resources	off	unknown resource → throws UNKNOWN_RESOURCE (else deny)

strict: true turns all four on; strict: false, all off. The known sets come from the grants, plus CRUD (actions), plus anything you declared via setup() or the policy.actions / policy.resources allow‑lists.

Develop strict, fail loud

Enable actions/resources in development and use can() so a typo throws in tests. On the request path use tryCan() so the same situation denies instead.

strict: true is not automatically “more secure”

Strict mode is typo/misconfiguration protection, not an access control. It doesn’t change who can do what — denials are identical with it on or off. It only turns an unknown name from a silent granted:false into a throw. That can even work against you: a thrown error a caller mishandles (a catch that falls through to “allow”) fails open. So treat strict as a development aid, keep it paired with tryCan() on the request path, and never rely on it as a security boundary.

Errors never fail open

A denial returns granted: false. A genuine fault throws an AccessControlError. Detect it and branch on its code — not its message.

import { AccessControl } from 'accesscontrol';

try {
  ac.can(role).readAny('post');
} catch (err) {
  if (AccessControl.isACError(err)) {
    log(err.code, err.role, err.resource, err.action);
  }
}

A thrown error means deny, never allow

On the request path, don’t let a catch fall through to “allow”. Either branch explicitly on a denial, or use tryCan(), which never throws. See Security › Fail-closed checks.

Error codes

Every AccessControlError carries a stable err.code (the ErrorCode enum) — the part of the API you should branch on. Messages are redacted by default and may change wording.

The phase column tells you when a code can reach you: author codes throw while the policy is being built or loaded (grant chainers, the constructor, setGrants(), require(), restore()) — they mean the policy itself is bad, and they surface at startup, not per request. check codes throw while resolving a permission — the policy loaded fine, but this particular check couldn’t be answered.

code	when	phase
INVALID_NAME	empty/malformed name	both
RESERVED_NAME	a reserved keyword (__proto__, prototype, constructor, _)	both
INVALID_QUERY	malformed check query (IQueryInfo)	check
INVALID_SETUP	malformed setup() vocabulary	author
INVALID_GRANT	invalid grant rule / grants object	author
INVALID_ACTION	invalid action name or possession	both
ROLE_NOT_FOUND	referenced role doesn’t exist	both
INVALID_INHERITANCE	self / cross / non‑existent inheritance	author
UNKNOWN_ACTION / UNKNOWN_RESOURCE	strict‑mode unknown name	check
LOCKED	mutation attempted after lock()	author
ASYNC_REQUIRED	a { fn } condition was hit on the sync path	check
INVALID_CONDITION	malformed / too‑deeply‑nested condition	author
UNKNOWN_CONDITION_FN	unregistered custom function name	check
REGEX_DISABLED / UNSAFE_REGEX	matches disabled, or an unsafe pattern	check
INVALID_DTREXP	malformed or over‑long during expression	author
DTREXP_NEVER_MATCHES	a during expression that can never match (e.g. D30 M2)	author

import { ErrorCode } from 'accesscontrol';

if (err.code === ErrorCode.ROLE_NOT_FOUND) { /* … */ }

The split is what makes tryCan() safe to use on the request path: check-phase throws are swallowed into a denial (the error event still fires for your logs), while author-phase throws happen where you want a crash — at load time, before any request is served. The full generated reference lives at API › ErrorCode.

Namespacing codes (engine.errorCodePrefix)

Codes like INVALID_NAME or INVALID_QUERY are generic and may collide with your own system’s codes. Prefix every AC code to namespace them:

const ac = new AccessControl(grants, { engine: { errorCodePrefix: 'AC_' } });
// now err.code === 'AC_ROLE_NOT_FOUND'

A prefix changes the comparison

With a prefix set, the bare‑enum comparison no longer matches — compare against the prefixed value:

const PREFIX = 'AC_';
if (err.code === PREFIX + ErrorCode.ROLE_NOT_FOUND) { /* … */ }

The default prefix is '', so err.code === ErrorCode.X works out of the box.

Safe error messages

By default (engine.safeErrors: true), error messages omit caller‑supplied values so request data doesn’t leak into logs. The values remain on the structured fields.

const e = grab(() => ac.can('ghost').readAny('post').granted);
e.message; // "Role not found."   (redacted — safe to log)
e.role;    // "ghost"             (available programmatically)

Turn it off for verbose, developer‑friendly messages:

new AccessControl(grants, { engine: { safeErrors: false } });
// → "Role not found. Got: \"ghost\"."

See Security › Error messages.

Charset

Names (roles, resources, actions, groups, categories) are validated against a character set. The default is ASCII; opt into Unicode for i18n.

import { Charset } from 'accesscontrol';

new AccessControl(grants, { engine: { charset: Charset.UNICODE } });
ac.grant('café').readAny('café');  // allowed under UNICODE

value	allowed	notes
Charset.ASCII (default)	[A-Za-z0-9_-]	rules out homograph attacks
Charset.UNICODE	Unicode letters/digits + _ -	⚠️ homograph risk

Unicode names carry homograph risk

аdmin (Cyrillic а) is a different role from admin (Latin a). Under UNICODE, NFC‑normalize names before passing them in. Structural characters (/ : $ * !) and the reserved gadget names stay rejected in every mode. See Security › Names & homographs.