@zudojs/permissions 1.1.0 → 1.2.0

package/README.md

@@ -2,6 +2,12 @@
 
 Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-permissions](https://zudojs.oyinlola.site/docs/packages-permissions) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-permissions.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -102,8 +108,19 @@ await engine.can(actor, "post:update", { ownerId: "user_1" }); // true
 await engine.can(actor, "post:update", { ownerId: "user_9" }); // false
 ```
 
-Conditions may be async. A condition that throws is treated as unmet — an
-authorization check fails closed.
+Conditions may be async. A condition that cannot be evaluated fails closed,
+and what "closed" means depends on the rule's effect:
+
+- an **allow** whose condition throws (or that has a condition but no
+  context) does not apply;
+- a **deny** whose condition throws **applies**. In the example above,
+  `locked-posts` throws when no resource is passed, and the check is denied —
+  treating the deny as unmet would let the role's allow win. The error is
+  reported through `onError`, and the decision is not cached.
+
+A deny also bears on a wildcard check: `can(actor, "post:*")` is refused by a
+deny on `post:delete`, whether it comes from `deniedPermissions`, a deny rule,
+or a policy registered for `post:delete`.
 
 **Combining.** The default is `deny-overrides`: any applicable deny wins,
 whatever its priority. Pass `algorithm: "priority"` for highest-priority-wins,
@@ -118,13 +135,19 @@ Conditions read request-scoped facts from `context.metadata`, supplied per
 check:
 
 ```typescript
+import { requireCurrentTenant } from "@zudojs/tenancy";
+
 await engine.can(actor, "invoice:read", invoice, {
-  metadata: { tenantId: request.tenantId },
+  // The *verified* tenant — resolved and trust-checked by @zudojs/tenancy.
+  metadata: { tenantId: requireCurrentTenant().id },
 });
 ```
 
 `tenantIsolation()` compares that value against the resource's tenant, and
-denies when either is missing.
+denies when either is missing. It is only as good as the value you pass: fill
+`tenantId` from a source the client cannot choose (a verified token claim, or
+the tenant `@zudojs/tenancy` resolved), **never from a request header** — a
+caller would set the header to the resource's tenant and pass.
 
 ## Policies
 
@@ -176,7 +199,8 @@ const policies = createPolicyRegistry();
 const engine = createPermissionEngine({ roles, policies });
 
 roles.define({ name: "auditor", permissions: ["audit:read"] });
-engine.invalidateRoles(); // pick up the change
+roles.remove("reader");
+// both take effect on the next check: the engine subscribes to the registry
 
 policies.define({ name: "lockdown", permissions: ["*:*"], evaluate: () => ({ allowed: false }) });
 // enforced by the next check — through the engine or an existing Ability
@@ -188,9 +212,17 @@ All three registries reject a duplicate name — re-registering a role or a
 policy is an authorization rule disappearing without a trace. Pass
 `{ allowOverride: true }` when replacement is what you mean.
 
-`validateConfiguration` (default `true`) applies to a registry as well as to
-an inline array: a role whose grant could never match is rejected when the
-engine looks it up, and the check denies.
+The engine subscribes to a role or policy registry it is given. Every
+`define`, `remove` and `clear` discards the memoized roles **and every cached
+decision**, so revoking a role is not undone by a cache entry written before
+the revocation. `engine.invalidateRoles()` does the same for a custom source.
+
+`validateConfiguration` (default `true`) rejects a pattern that could never
+match wherever it is written — a role grant, a role's rules, a static rule, or
+a policy's `permissions` — because a malformed pattern in a deny or a lockdown
+policy would fail open in silence. Arrays are checked at construction; a
+registry checks on `define` (`InvalidRoleError` / `InvalidPermissionError`),
+and a custom source is checked when the engine reads it.
 
 A permission registry records descriptions and implications:
 
@@ -226,10 +258,13 @@ await engine.can(actor, "post:read", post, { skipCache: true });
 await engine.invalidateActor("user_1");
 ```
 
-Keys include the actor, the permission and the resource id (from
-`resource.id`, or `options.resourceId`), so two resources never share one
-decision. A `|` inside an actor or resource id is escaped, so two different
-(actor, permission, resource) triples can never share a key either.
+Keys include the actor id, a digest of everything else the actor carries
+(`roles`, `permissions`, `type`, any other field a condition may read), the
+permission and the resource id (from `resource.id`, or `options.resourceId`).
+The same user id with different roles — an admin token in one tenant and a
+viewer token in another, or a demoted token — never shares a decision. A `|`
+inside an actor or resource id is escaped, so two different checks can never
+share a key either.
 
 A check is cached only when the key can describe it completely:
 
@@ -239,7 +274,10 @@ A check is cached only when the key can describe it completely:
 - a check carrying `metadata` is **not cached**, because conditions such as
   `tenantIsolation()` read the tenant from there and it is not part of the
   key;
-- a decision produced by a policy marked `cacheable: false` is not stored;
+- an actor carrying something the digest cannot describe (a function, a class
+  instance, a `Map`) is **not cached**;
+- a decision produced by a policy marked `cacheable: false`, or forced by a
+  condition that threw, is not stored;
 - a TTL of `0` or less means "do not cache".
 
 `deniedPermissions` is evaluated before the cache is consulted, so a deny
@@ -268,7 +306,9 @@ Every failure denies:
 | --------------------------- | ------------------------------------------------------ |
 | Unknown role on the actor   | denied; reported to `onError`; other roles still apply |
 | Malformed permission string | denied, `reason: "invalid_permission"`                 |
-| Condition throws            | rule does not apply                                    |
+| Allow condition throws      | the allow does not apply                               |
+| Deny condition throws       | denied, `reason: "rule_deny"`; reported to `onError`   |
+| Malformed rule/policy pattern | rejected at construction or `define`                 |
 | A deny rule applies         | denied, `reason: "rule_deny"`, even if a policy allows |
 | Policy throws or times out  | denied, `reason: "policy_error:<name>"`                |
 | Role inheritance cycle      | denied; reported to `onError`                          |
@@ -324,8 +364,10 @@ emitter.on((event) => auditLog.write(event));
 const engine = createPermissionEngine({ roles, emitter });
 ```
 
-Every check emits — allowed, denied, and the ones that throw. A handler that
-throws cannot break authorization, but it is reported rather than swallowed.
+Every check emits — allowed, denied, and the ones that throw — including
+`explain()` on the engine and on an Ability, which make the same real
+decision. A handler that throws cannot break authorization, but it is reported
+rather than swallowed.
 
 ## HTTP middleware
 
@@ -334,10 +376,13 @@ import { authorize, createActorMiddleware } from "@zudojs/permissions";
 
 const guard = authorize(engine, "post:update", {
   extractActor: (context) => context.state.get("auth:user"),
-  extractResource: (context) => loadPost(context.request.params.get("id")),
+  // May be async: it is awaited, and a loader that rejects denies (403).
+  extractResource: (context) => loadPost(context.request.getParam?.("id")),
+  // The tenant @zudojs/tenancy resolved and trust-checked — never a header.
   extractMetadata: (context) => ({
-    tenantId: context.request.headers.get("x-tenant"),
+    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")?.tenantId,
   }),
+  onError: (error, source) => logger.warn({ error, source }, "guard denied"),
 });
 ```
 
@@ -351,11 +396,16 @@ const guard = authorize(engine, "post:update", {
   decision.
 - `context.signal` is forwarded, so a client disconnect stops policy
   evaluation.
+- `extractResource` is awaited. A loader that throws or rejects answers
+  **403** (`reason: "resource_error"`) and reports through `onError`; it never
+  lets the request through.
 - `createRequirePermissionsMiddleware(engine, permissions, { mode })` checks
   several permissions, short-circuiting on the first that decides the outcome.
+  An empty list denies in either mode.
 
-`@zudojs/http` is an optional peer dependency; the middleware types are
-mirrored locally so this package works without it.
+The middleware composes with the real `@zudojs/http` pipeline without
+depending on it: the HTTP types are mirrored structurally (headers, params and
+query may be plain objects, as `@zudojs/http` provides them, or maps).
 
 ## Errors
 

package/dist/ability/ability.core.js

@@ -5,33 +5,13 @@
  */
 import { evaluate, evaluateWithTrace } from "../evaluator/evaluator.core.js";
 import { PermissionDeniedError } from "../permissionErrors/index.js";
+import { observed } from "../evaluator/engineSupport/index.js";
 /**
  * Create an Ability for an actor.
  */
 export function createAbility(actor, evaluatorOptions, emitter) {
-    async function run(permission, resource, options) {
-        const start = performance.now();
-        let decision;
-        let failure;
-        try {
-            decision = await evaluate(actor, permission, resource, evaluatorOptions, options);
-            return decision;
-        }
-        catch (error) {
-            failure = error;
-            throw error;
-        }
-        finally {
-            emitter?.emit({
-                actorId: actor.id,
-                permission,
-                allowed: decision?.allowed ?? false,
-                reason: decision?.reason ??
-                    (failure instanceof Error ? `error:${failure.name}` : undefined),
-                durationMs: performance.now() - start,
-                errored: failure !== undefined,
-            });
-        }
+    function run(permission, resource, options) {
+        return observed(emitter, actor, permission, resource, () => evaluate(actor, permission, resource, evaluatorOptions, options), (decision) => decision);
     }
     return {
         actor,
@@ -45,7 +25,7 @@ export function createAbility(actor, evaluatorOptions, emitter) {
             return run(permission, resource, options);
         },
         async explain(permission, resource, options) {
-            return evaluateWithTrace(actor, permission, resource, evaluatorOptions, options);
+            return observed(emitter, actor, permission, resource, () => evaluateWithTrace(actor, permission, resource, evaluatorOptions, options), (result) => result.decision);
         },
         async authorize(permission, resource, options) {
             const decision = await run(permission, resource, options);

package/dist/cache/cache.actorDigest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Actor digest for the decision cache key.
+ *
+ * A decision depends on everything the actor carries, not only its id:
+ * `roles`, `permissions` and `type` travel on the actor object for each
+ * request (a tenant-scoped token, `auth.checkAccess`), and a condition may
+ * read any other field on it. Keying on the id alone let an admin decision
+ * made in one tenant answer for the same user as a viewer in another, and a
+ * demoted token keep its old grants until the entry expired.
+ *
+ * @module cache/cache.actorDigest
+ */
+import type { PermissionActor } from "../permissionTypes/index.js";
+/** Longest digest worth keying on; a longer one is not cached at all. */
+export declare const MAX_ACTOR_DIGEST_LENGTH = 4096;
+/**
+ * A stable description of everything an actor carries besides its id.
+ *
+ * Returns `undefined` when the actor holds something the digest cannot
+ * describe faithfully — a function, a class instance, a `Map`, nesting past
+ * six levels, or a digest longer than {@link MAX_ACTOR_DIGEST_LENGTH}. The
+ * engine does not cache such a decision rather than key it on a partial
+ * description.
+ */
+export declare function actorCacheDigest(actor: PermissionActor): string | undefined;
+//# sourceMappingURL=cache.actorDigest.d.ts.map

package/dist/cache/cache.actorDigest.js

@@ -0,0 +1,90 @@
+/**
+ * Actor digest for the decision cache key.
+ *
+ * A decision depends on everything the actor carries, not only its id:
+ * `roles`, `permissions` and `type` travel on the actor object for each
+ * request (a tenant-scoped token, `auth.checkAccess`), and a condition may
+ * read any other field on it. Keying on the id alone let an admin decision
+ * made in one tenant answer for the same user as a viewer in another, and a
+ * demoted token keep its old grants until the entry expired.
+ *
+ * @module cache/cache.actorDigest
+ */
+/** Longest digest worth keying on; a longer one is not cached at all. */
+export const MAX_ACTOR_DIGEST_LENGTH = 4096;
+/** Deepest nesting the digest will describe. */
+const MAX_DEPTH = 6;
+/** Marks a value the digest cannot describe faithfully. */
+const UNDESCRIBABLE = Symbol("undescribable");
+function isPlainRecord(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function canonical(value, depth) {
+    if (depth > MAX_DEPTH)
+        return UNDESCRIBABLE;
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return JSON.stringify(value);
+        case "number":
+            return Number.isFinite(value) ? JSON.stringify(value) : UNDESCRIBABLE;
+        case "object":
+            break;
+        default:
+            return UNDESCRIBABLE;
+    }
+    const object = value;
+    if (object instanceof Date) {
+        const time = object.getTime();
+        return Number.isNaN(time) ? UNDESCRIBABLE : `D${JSON.stringify(time)}`;
+    }
+    if (Array.isArray(object)) {
+        const parts = [];
+        for (const entry of object) {
+            const part = canonical(entry, depth + 1);
+            if (part === UNDESCRIBABLE)
+                return UNDESCRIBABLE;
+            parts.push(part);
+        }
+        return `[${parts.join(",")}]`;
+    }
+    if (!isPlainRecord(object))
+        return UNDESCRIBABLE;
+    return canonicalRecord(object, depth, []);
+}
+function canonicalRecord(record, depth, skip) {
+    const parts = [];
+    for (const key of Object.keys(record).sort()) {
+        if (skip.includes(key))
+            continue;
+        const entry = record[key];
+        if (entry === undefined)
+            continue;
+        const part = canonical(entry, depth + 1);
+        if (part === UNDESCRIBABLE)
+            return UNDESCRIBABLE;
+        parts.push(`${JSON.stringify(key)}:${part}`);
+    }
+    return `{${parts.join(",")}}`;
+}
+/**
+ * A stable description of everything an actor carries besides its id.
+ *
+ * Returns `undefined` when the actor holds something the digest cannot
+ * describe faithfully — a function, a class instance, a `Map`, nesting past
+ * six levels, or a digest longer than {@link MAX_ACTOR_DIGEST_LENGTH}. The
+ * engine does not cache such a decision rather than key it on a partial
+ * description.
+ */
+export function actorCacheDigest(actor) {
+    if (typeof actor !== "object" || actor === null)
+        return undefined;
+    const digest = canonicalRecord(actor, 0, ["id"]);
+    if (digest === UNDESCRIBABLE)
+        return undefined;
+    return digest.length > MAX_ACTOR_DIGEST_LENGTH ? undefined : digest;
+}
+//# sourceMappingURL=cache.actorDigest.js.map

package/dist/cache/cache.core.d.ts

@@ -10,8 +10,14 @@ import type { PermissionCache } from "../permissionTypes/index.js";
  * The actor id is delimited, so invalidating actor `1` cannot also clear
  * actors `10` and `123`, and a delimiter inside an id is escaped so two
  * different (actor, permission, resource) triples can never share a key.
+ *
+ * `scope` carries whatever else the decision depends on — the engine passes
+ * a digest of the actor's roles, permissions and attributes, so the same id
+ * holding different grants never shares a key. It sits after the actor
+ * prefix behind a `~`, which no permission string can start with, so
+ * `invalidateActor` still finds every entry for the actor.
  */
-export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string): string;
+export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string, scope?: string): string;
 /** Options for {@link createMemoryPermissionCache}. */
 export interface MemoryPermissionCacheOptions {
     /** Default TTL in milliseconds. Defaults to 60,000 (1 minute). */

package/dist/cache/cache.core.js

@@ -27,9 +27,16 @@ function actorPrefix(actorId) {
  * The actor id is delimited, so invalidating actor `1` cannot also clear
  * actors `10` and `123`, and a delimiter inside an id is escaped so two
  * different (actor, permission, resource) triples can never share a key.
+ *
+ * `scope` carries whatever else the decision depends on — the engine passes
+ * a digest of the actor's roles, permissions and attributes, so the same id
+ * holding different grants never shares a key. It sits after the actor
+ * prefix behind a `~`, which no permission string can start with, so
+ * `invalidateActor` still finds every entry for the actor.
  */
-export function permissionCacheKey(actorId, permission, resourceId) {
-    const base = `${actorPrefix(actorId)}${permission}`;
+export function permissionCacheKey(actorId, permission, resourceId, scope) {
+    const scoped = scope === undefined ? "" : `~${escapeSegment(scope)}${KEY_DELIMITER}`;
+    const base = `${actorPrefix(actorId)}${scoped}${permission}`;
     return resourceId
         ? `${base}${KEY_DELIMITER}${escapeSegment(resourceId)}`
         : base;

package/dist/cache/index.d.ts

@@ -4,4 +4,5 @@
  * @module cache
  */
 export { createMemoryPermissionCache, permissionCacheKey, type MemoryPermissionCacheOptions, } from "./cache.core.js";
+export { actorCacheDigest, MAX_ACTOR_DIGEST_LENGTH, } from "./cache.actorDigest.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cache/index.js

@@ -4,4 +4,5 @@
  * @module cache
  */
 export { createMemoryPermissionCache, permissionCacheKey, } from "./cache.core.js";
+export { actorCacheDigest, MAX_ACTOR_DIGEST_LENGTH, } from "./cache.actorDigest.js";
 //# sourceMappingURL=index.js.map

package/dist/evaluator/authorizationEngine.d.ts

@@ -6,14 +6,27 @@
 import type { PermissionActor, PermissionDecision, ExplainResult, PermissionRule, PermissionPolicyDefinition, PermissionCache, PermissionResolver, RoleResolver, RoleDefinition, RuleCombiningAlgorithm, AuthorizationOptions } from "../permissionTypes/index.js";
 import { type Ability } from "../ability/ability.core.js";
 import type { PermissionEventEmitter } from "../observability/observability.core.js";
-/** Anything the engine will accept as its source of roles. */
+/**
+ * Anything the engine will accept as its source of roles.
+ *
+ * A source with `subscribe` (every `createRoleRegistry()`) is watched: a
+ * `define`, `remove` or `clear` discards the engine's memoized roles and
+ * every cached decision, so revoking a role takes effect on the next check.
+ */
 export interface RoleSource {
     get(name: string): RoleDefinition | undefined;
+    subscribe?(listener: () => void): () => void;
 }
-/** Anything the engine will accept as its source of policies. */
+/**
+ * Anything the engine will accept as its source of policies.
+ *
+ * A source with `subscribe` (every `createPolicyRegistry()`) is watched the
+ * same way, so a policy added or removed is not bypassed by a cached decision.
+ */
 export interface PolicySource {
     names(): readonly string[];
     get(name: string): PermissionPolicyDefinition | undefined;
+    subscribe?(listener: () => void): () => void;
 }
 /** Configuration for the permission engine. */
 export interface PermissionEngineOptions {
@@ -79,7 +92,11 @@ export interface PermissionEngine {
     createAbility(actor: PermissionActor): Ability;
     /** Drop cached decisions for one actor. */
     invalidateActor(actorId: string): Promise<void>;
-    /** Re-read the role source, discarding the memoized lookups. */
+    /**
+     * Re-read the role source, discarding the memoized lookups and every
+     * cached decision. Registries created with `createRoleRegistry()` and
+     * `createPolicyRegistry()` trigger this themselves on every change.
+     */
     invalidateRoles(): void;
 }
 /**

package/dist/evaluator/authorizationEngine.js

@@ -5,10 +5,11 @@
  */
 import { evaluate, evaluateWithTrace } from "./evaluator.core.js";
 import { createAbility } from "../ability/ability.core.js";
-import { PermissionDeniedError, InvalidRoleError, } from "../permissionErrors/index.js";
-import { isValidPermission } from "../permission/permission.core.js";
+import { PermissionDeniedError } from "../permissionErrors/index.js";
 import { memoizeRoleLookup } from "../role/roleHierarchy.js";
 import { freezeRoleDefinition } from "../role/roleRegistry.js";
+import { validatePolicy, validateRole, validateRoles, validateRule, } from "./engineSupport/index.js";
+import { observed } from "./engineSupport/index.js";
 function isRoleSource(roles) {
     return (roles !== undefined &&
         !Array.isArray(roles) &&
@@ -19,35 +20,15 @@ function isPolicySource(policies) {
         !Array.isArray(policies) &&
         typeof policies.names === "function");
 }
-/** Rejects a role whose grants could never match. */
-function validateRole(role) {
-    if (!role.name || role.name.trim() === "") {
-        throw new InvalidRoleError("Role name cannot be empty");
-    }
-    for (const permission of role.permissions) {
-        if (!isValidPermission(permission)) {
-            // A malformed grant can never match, so it is a silent no-op unless
-            // it is rejected here.
-            throw new InvalidRoleError(`Role "${role.name}" grants "${permission}", which is not a valid ` +
-                `"resource:action" permission`);
-        }
-    }
-}
-function validateRoles(roles) {
-    const seen = new Set();
-    for (const role of roles) {
-        validateRole(role);
-        if (seen.has(role.name)) {
-            throw new InvalidRoleError(`Role "${role.name}" is defined more than once`);
-        }
-        seen.add(role.name);
-    }
-}
 /**
  * Create a permission engine.
  */
 export function createPermissionEngine(options) {
     const validateConfiguration = options?.validateConfiguration ?? true;
+    if (validateConfiguration) {
+        for (const rule of options?.rules ?? [])
+            validateRule(rule);
+    }
     let roleLookup;
     let invalidateRoleCache;
     if (isRoleSource(options?.roles)) {
@@ -81,14 +62,43 @@ export function createPermissionEngine(options) {
     const policyList = policySource
         ? undefined
         : (options?.policies ?? []);
+    if (validateConfiguration)
+        policyList?.forEach(validatePolicy);
+    // A policy source is read lazily, so its validation is lazy too. Each
+    // definition is checked once; a malformed one makes the check throw, which
+    // never reads as an allow.
+    const validatedPolicies = new WeakSet();
     const resolvePolicies = () => {
         if (!policySource)
             return policyList ?? [];
         return policySource
             .names()
             .map((name) => policySource.get(name))
-            .filter((policy) => policy !== undefined);
+            .filter((policy) => policy !== undefined)
+            .map((policy) => {
+            if (validateConfiguration && !validatedPolicies.has(policy)) {
+                validatePolicy(policy);
+                validatedPolicies.add(policy);
+            }
+            return policy;
+        });
+    };
+    // Every change to the configuration bumps the generation, which is part
+    // of every decision-cache key: an entry written under an older role or
+    // policy set can no longer be found, whatever cache adapter is in use.
+    let generation = 0;
+    const invalidateConfiguration = () => {
+        generation += 1;
+        invalidateRoleCache();
+        const cleared = options?.cache?.clear?.();
+        cleared?.catch((error) => {
+            options?.onError?.(error, "PermissionCache.clear");
+        });
     };
+    if (isRoleSource(options?.roles)) {
+        options.roles.subscribe?.(invalidateConfiguration);
+    }
+    policySource?.subscribe?.(invalidateConfiguration);
     // One live view over the configuration. `policies` is a getter so a
     // registry-backed engine re-reads the registry on every evaluation — an
     // Ability used to capture a snapshot of the policy list when it was
@@ -108,38 +118,13 @@ export function createPermissionEngine(options) {
         roleResolver: options?.roleResolver,
         expandImplied: options?.expandImplied,
         onError: options?.onError,
+        cacheScope: () => `g${generation}`,
     };
     const evaluatorOptions = () => liveOptions;
     const emitter = options?.emitter;
-    /**
-     * Runs a check and emits an audit event whichever way it ends — including
-     * when it throws. An authorization trail that records only the successful
-     * paths is not a trail.
-     */
-    async function runCheck(actor, permission, resource, authOptions) {
-        const start = performance.now();
-        let decision;
-        let failure;
-        try {
-            decision = await evaluate(actor, permission, resource, evaluatorOptions(), authOptions);
-            return decision;
-        }
-        catch (error) {
-            failure = error;
-            throw error;
-        }
-        finally {
-            emitter?.emit({
-                actorId: actor.id,
-                permission,
-                resourceType: resourceTypeOf(resource),
-                allowed: decision?.allowed ?? false,
-                reason: decision?.reason ??
-                    (failure instanceof Error ? `error:${failure.name}` : undefined),
-                durationMs: performance.now() - start,
-                errored: failure !== undefined,
-            });
-        }
+    /** Runs a check and emits an audit event whichever way it ends. */
+    function runCheck(actor, permission, resource, authOptions) {
+        return observed(emitter, actor, permission, resource, () => evaluate(actor, permission, resource, evaluatorOptions(), authOptions), (decision) => decision);
     }
     return {
         async can(actor, permission, resource, authOptions) {
@@ -163,7 +148,7 @@ export function createPermissionEngine(options) {
             }
         },
         async explain(actor, permission, resource, authOptions) {
-            return evaluateWithTrace(actor, permission, resource, evaluatorOptions(), authOptions);
+            return observed(emitter, actor, permission, resource, () => evaluateWithTrace(actor, permission, resource, evaluatorOptions(), authOptions), (result) => result.decision);
         },
         createAbility(actor) {
             return createAbility(actor, evaluatorOptions(), emitter);
@@ -172,18 +157,8 @@ export function createPermissionEngine(options) {
             await options?.cache?.invalidateActor(actorId);
         },
         invalidateRoles() {
-            invalidateRoleCache();
+            invalidateConfiguration();
         },
     };
 }
-/** Best-effort resource type for an audit event. */
-function resourceTypeOf(resource) {
-    if (typeof resource !== "object" || resource === null)
-        return undefined;
-    const record = resource;
-    if (typeof record.type === "string")
-        return record.type;
-    const name = record.constructor?.name;
-    return name && name !== "Object" ? name : undefined;
-}
 //# sourceMappingURL=authorizationEngine.js.map

package/dist/evaluator/engineSupport/authorizationEngine.validation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration validation for the authorization engine.
+ *
+ * A malformed pattern can never match. In a grant that is a silent no-op; in
+ * a denying policy or a deny rule it is a restriction that fails open. The
+ * same pattern therefore has to be rejected wherever it can be written, not
+ * only in a role's grant list.
+ *
+ * @module evaluator/authorizationEngine.validation
+ */
+import type { PermissionPolicyDefinition, PermissionRule, RoleDefinition } from "../../permissionTypes/index.js";
+/**
+ * The first `resource:action` pair a rule names that is not a valid
+ * permission pattern, or `undefined` when every pair is valid.
+ */
+export declare function invalidRulePattern(rule: PermissionRule): string | undefined;
+/**
+ * Reject a rule whose resource or action could never match.
+ *
+ * @throws {InvalidPermissionError} naming the offending pair.
+ */
+export declare function validateRule(rule: PermissionRule): void;
+/**
+ * Reject a policy scoped to a pattern that could never match.
+ *
+ * @throws {InvalidPermissionError} naming the offending pattern.
+ */
+export declare function validatePolicy(policy: PermissionPolicyDefinition): void;
+/**
+ * Reject a role whose grants or rules could never match.
+ *
+ * @throws {InvalidRoleError} naming the role and the offending pattern.
+ */
+export declare function validateRole(role: RoleDefinition): void;
+/** Validate a role list, rejecting duplicates as well. */
+export declare function validateRoles(roles: readonly RoleDefinition[]): void;
+//# sourceMappingURL=authorizationEngine.validation.d.ts.map