@zudojs/permissions 1.2.0 → 1.3.0

package/README.md

@@ -135,11 +135,15 @@ Conditions read request-scoped facts from `context.metadata`, supplied per
 check:
 
 ```typescript
-import { requireCurrentTenant } from "@zudojs/tenancy";
+import { createContextManager, getDefaultStorage } from "@zudojs/tenancy";
+
+const tenancy = createContextManager({ storage: getDefaultStorage() });
 
 await engine.can(actor, "invoice:read", invoice, {
   // The *verified* tenant — resolved and trust-checked by @zudojs/tenancy.
-  metadata: { tenantId: requireCurrentTenant().id },
+  // `requireCurrentTenant()` is a method on the context manager; it throws
+  // when no tenant context is active, rather than returning undefined.
+  metadata: { tenantId: tenancy.requireCurrentTenant().id },
 });
 ```
 
@@ -202,7 +206,11 @@ roles.define({ name: "auditor", permissions: ["audit:read"] });
 roles.remove("reader");
 // both take effect on the next check: the engine subscribes to the registry
 
-policies.define({ name: "lockdown", permissions: ["*:*"], evaluate: () => ({ allowed: false }) });
+policies.define({
+  name: "lockdown",
+  permissions: ["*:*"],
+  evaluate: () => ({ allowed: false }),
+});
 // enforced by the next check — through the engine or an existing Ability
 
 roles.require("auditor"); // throws RoleNotFoundError when unregistered
@@ -233,11 +241,17 @@ permissions.define("post:write", { implies: ["post:read"] });
 
 const engine = createPermissionEngine({
   roles,
-  expandImplied: (permission) => permissions.expandImplied(permission),
+  expandImplied: permissions,
 });
 // An actor granted post:admin now passes post:read.
 ```
 
+Pass the registry itself rather than a closure over it. The engine subscribes
+to it, so `permissions.remove("post:admin")` — or redefining it without the
+implication — drops the decisions that were cached while it stood. A bare
+`(permission) => permissions.expandImplied(permission)` still works, but it
+cannot announce a change, so an engine given one caches no decisions at all.
+
 ## Caching
 
 ```typescript
@@ -278,6 +292,12 @@ A check is cached only when the key can describe it completely:
   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;
+- an engine with a `roleResolver` or `permissionResolver` and no
+  `resolverCacheKey` caches **nothing**: the resolver reads state the key
+  cannot describe, so an entry would outlive a grant withdrawn upstream;
+- an engine whose `expandImplied` is a bare function rather than a
+  `createPermissionRegistry()` caches **nothing**, for the same reason: a
+  revoked implication cannot announce itself;
 - a TTL of `0` or less means "do not cache".
 
 `deniedPermissions` is evaluated before the cache is consulted, so a deny
@@ -298,22 +318,40 @@ const engine = createPermissionEngine({
 A resolver that fails is reported through `onError` and the check continues
 fail-closed, rather than throwing out of the authorization path.
 
+A resolver reads authorization state the engine does not own and cannot see
+change, and none of it is in the decision-cache key. **A resolver-backed
+engine therefore caches nothing** unless you describe that state with
+`resolverCacheKey`:
+
+```typescript
+const engine = createPermissionEngine({
+  roles,
+  cache: createMemoryPermissionCache(),
+  permissionResolver: { resolvePermissions: (actor) => db.rulesFor(actor.id) },
+  // Anything that changes when the resolver's answer could change.
+  resolverCacheKey: (actor) => db.grantsVersionFor(actor.id),
+});
+```
+
+Return `undefined` for an actor whose state you cannot describe, and that
+actor's decisions stay uncached.
+
 ## Failure behaviour
 
 Every failure denies:
 
-| Situation                   | Result                                                 |
-| --------------------------- | ------------------------------------------------------ |
-| Unknown role on the actor   | denied; reported to `onError`; other roles still apply |
-| Malformed permission string | denied, `reason: "invalid_permission"`                 |
-| 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`                          |
-| Role source throws          | denied; reported to `onError`                          |
-| `signal` aborted            | throws `AuthorizationAbortedError`                     |
+| Situation                     | Result                                                 |
+| ----------------------------- | ------------------------------------------------------ |
+| Unknown role on the actor     | denied; reported to `onError`; other roles still apply |
+| Malformed permission string   | denied, `reason: "invalid_permission"`                 |
+| 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`                          |
+| Role source throws            | denied; reported to `onError`                          |
+| `signal` aborted              | throws `AuthorizationAbortedError`                     |
 
 A value that is not an `Error` — a policy or resolver that throws a string —
 reaches `onError` wrapped in `PolicyError` or `PermissionResolverError`, with
@@ -380,7 +418,8 @@ const guard = authorize(engine, "post:update", {
   extractResource: (context) => loadPost(context.request.getParam?.("id")),
   // The tenant @zudojs/tenancy resolved and trust-checked — never a header.
   extractMetadata: (context) => ({
-    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")?.tenantId,
+    tenantId: context.state.get<{ tenantId: string }>("tenancy:context")
+      ?.tenantId,
   }),
   onError: (error, source) => logger.warn({ error, source }, "guard denied"),
 });

package/dist/evaluator/authorizationEngine.d.ts

@@ -28,6 +28,19 @@ export interface PolicySource {
     get(name: string): PermissionPolicyDefinition | undefined;
     subscribe?(listener: () => void): () => void;
 }
+/**
+ * Anything the engine will accept as its source of permission implications.
+ *
+ * A source with `subscribe` (every `createPermissionRegistry()`) is watched
+ * like the role and policy registries: revoking an implication drops every
+ * decision that was cached while it stood. A bare function cannot announce a
+ * change, so an engine given one caches nothing — see
+ * {@link PermissionEngineOptions.expandImplied}.
+ */
+export interface ImpliedPermissionSource {
+    expandImplied(permission: string): readonly string[];
+    subscribe?(listener: () => void): () => void;
+}
 /** Configuration for the permission engine. */
 export interface PermissionEngineOptions {
     /**
@@ -54,8 +67,31 @@ export interface PermissionEngineOptions {
     readonly permissionResolver?: PermissionResolver;
     /** Loads additional roles for an actor from an external source. */
     readonly roleResolver?: RoleResolver;
-    /** Expands a permission into the permissions it implies. */
-    readonly expandImplied?: (permission: string) => readonly string[];
+    /**
+     * Describes the state a resolver is answering from, so that decisions it
+     * influenced can be cached safely.
+     *
+     * A resolver reads authorization data the engine does not own and cannot
+     * see change — a grants table, another service. Nothing about it is in the
+     * decision-cache key, so an entry written while the resolver said "allow"
+     * kept answering after the grant was withdrawn upstream. Resolver-backed
+     * engines therefore **do not cache at all** unless this is supplied.
+     *
+     * Return a value that changes whenever the resolver's answer for this actor
+     * could change — a version column, an `updatedAt` stamp, a grants-table
+     * generation. Return `undefined` for an actor whose state cannot be
+     * described, and that actor's decisions stay uncached.
+     */
+    readonly resolverCacheKey?: (actor: PermissionActor) => string | undefined;
+    /**
+     * Expands a permission into the permissions it implies.
+     *
+     * Prefer passing a `createPermissionRegistry()` — the engine subscribes to
+     * it, so revoking an implication invalidates the decisions cached under it.
+     * A bare function cannot announce a change, so an engine given one caches
+     * no decisions rather than serving one from a revoked implication.
+     */
+    readonly expandImplied?: ((permission: string) => readonly string[]) | ImpliedPermissionSource;
     /** Emits an event for every completed check, including failures. */
     readonly emitter?: PermissionEventEmitter;
     /** Reports a failure authorization swallowed to stay fail-closed. */

package/dist/evaluator/authorizationEngine.js

@@ -20,6 +20,11 @@ function isPolicySource(policies) {
         !Array.isArray(policies) &&
         typeof policies.names === "function");
 }
+function isImpliedPermissionSource(source) {
+    return (source !== undefined &&
+        typeof source !== "function" &&
+        typeof source.expandImplied === "function");
+}
 /**
  * Create a permission engine.
  */
@@ -99,6 +104,34 @@ export function createPermissionEngine(options) {
         options.roles.subscribe?.(invalidateConfiguration);
     }
     policySource?.subscribe?.(invalidateConfiguration);
+    // The third registry the README wires in. Without this, revoking an
+    // implication left every decision it granted in the cache for the full TTL
+    // — `skipCache: true` said "deny" while `can()` kept saying "allow".
+    const impliedSource = isImpliedPermissionSource(options?.expandImplied)
+        ? options.expandImplied
+        : undefined;
+    const expandImplied = impliedSource
+        ? (permission) => impliedSource.expandImplied(permission)
+        : options?.expandImplied;
+    const impliedWatched = impliedSource?.subscribe?.(invalidateConfiguration) !== undefined;
+    // Two inputs the cache key cannot describe. An implication source that
+    // cannot announce a change, and a resolver reading state the engine does
+    // not own, both make a cached allow outlive the grant behind it — so the
+    // decision is not cached at all unless the caller closes the gap.
+    const impliedUnwatched = expandImplied !== undefined && !impliedWatched;
+    const resolverConfigured = options?.permissionResolver !== undefined ||
+        options?.roleResolver !== undefined;
+    const resolverCacheKey = options?.resolverCacheKey;
+    const cacheScope = (actor) => {
+        if (impliedUnwatched)
+            return undefined;
+        if (!resolverConfigured)
+            return `g${generation}`;
+        if (!resolverCacheKey)
+            return undefined;
+        const scope = resolverCacheKey(actor);
+        return scope === undefined ? undefined : `g${generation}|r${scope}`;
+    };
     // 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
@@ -116,9 +149,9 @@ export function createPermissionEngine(options) {
         cacheTtlMs: options?.cacheTtlMs,
         permissionResolver: options?.permissionResolver,
         roleResolver: options?.roleResolver,
-        expandImplied: options?.expandImplied,
+        expandImplied,
         onError: options?.onError,
-        cacheScope: () => `g${generation}`,
+        cacheScope,
     };
     const evaluatorOptions = () => liveOptions;
     const emitter = options?.emitter;

package/dist/evaluator/engineSupport/evaluator.cacheKey.d.ts

@@ -19,6 +19,10 @@ import type { EvaluatorOptions } from "../evaluator.pipeline.js";
  *   in the key as a digest; an actor the digest cannot describe is not cached.
  * - The engine's configuration generation is in the key, so a role removed
  *   from a live registry cannot be served from an entry written before.
+ * - An external resolver reads state the key knows nothing about, so a
+ *   resolver-backed engine is uncacheable unless it supplies
+ *   `resolverCacheKey`. So is one whose implication source cannot announce a
+ *   change.
  */
 export declare function decisionCacheKey(actor: PermissionActor, permissionStr: string, resource: unknown, options: EvaluatorOptions, authOptions?: AuthorizationOptions): string | undefined;
 //# sourceMappingURL=evaluator.cacheKey.d.ts.map

package/dist/evaluator/engineSupport/evaluator.cacheKey.js

@@ -38,6 +38,10 @@ function resourceIdOf(resource) {
  *   in the key as a digest; an actor the digest cannot describe is not cached.
  * - The engine's configuration generation is in the key, so a role removed
  *   from a live registry cannot be served from an entry written before.
+ * - An external resolver reads state the key knows nothing about, so a
+ *   resolver-backed engine is uncacheable unless it supplies
+ *   `resolverCacheKey`. So is one whose implication source cannot announce a
+ *   change.
  */
 export function decisionCacheKey(actor, permissionStr, resource, options, authOptions) {
     if (!options.cache || authOptions?.skipCache === true)
@@ -50,7 +54,17 @@ export function decisionCacheKey(actor, permissionStr, resource, options, authOp
     const digest = actorCacheDigest(actor);
     if (digest === undefined)
         return undefined;
-    const generation = options.cacheScope?.() ?? "";
+    // An engine that cannot describe its own configuration for this actor
+    // returns `undefined` here — an external resolver with no
+    // `resolverCacheKey`, or an implication source that cannot announce a
+    // change. Both would otherwise keep answering from a revoked grant.
+    let generation = "";
+    if (options.cacheScope !== undefined) {
+        const scope = options.cacheScope(actor);
+        if (scope === undefined)
+            return undefined;
+        generation = scope;
+    }
     return permissionCacheKey(actor.id, permissionStr, resourceId, `${generation}${digest}`);
 }
 //# sourceMappingURL=evaluator.cacheKey.js.map

package/dist/evaluator/evaluator.pipeline.d.ts

@@ -35,8 +35,13 @@ export interface EvaluatorOptions {
      * Extra decision-cache key scope, read on every evaluation. The engine
      * passes its configuration generation, so a role change invalidates every
      * entry written before it.
+     *
+     * Returning `undefined` means this decision must not be cached: the engine
+     * uses that for the inputs the key cannot describe — an implication source
+     * that cannot announce a change, and an external resolver with no
+     * `resolverCacheKey`.
      */
-    readonly cacheScope?: () => string;
+    readonly cacheScope?: (actor: PermissionActor) => string | undefined;
 }
 /** The permissions and rules an actor holds, once everything is resolved. */
 export interface ResolvedGrants {

package/dist/permission/permissionRegistry.d.ts

@@ -39,6 +39,16 @@ export interface PermissionRegistry {
     expandImplied(permission: string): readonly string[];
     remove(permission: string): boolean;
     clear(): void;
+    /**
+     * Be told whenever the permission set changes (`define`, a `remove` that
+     * removed something, `clear`). Returns an unsubscribe function.
+     *
+     * An engine given this registry as its `expandImplied` source subscribes
+     * itself, which is what makes revoking an implication take effect
+     * immediately: the engine's cached decisions were written under the old
+     * implication and would otherwise keep granting for the whole TTL.
+     */
+    subscribe(listener: () => void): () => void;
 }
 /**
  * Create a permission registry.
@@ -49,7 +59,10 @@ export interface PermissionRegistry {
  *
  * const engine = createPermissionEngine({
  *   roles,
- *   expandImplied: (permission) => permissions.expandImplied(permission),
+ *   // Pass the registry itself, not a closure over it: the engine
+ *   // subscribes, so revoking an implication drops the cached decisions
+ *   // that were made under it.
+ *   expandImplied: permissions,
  * });
  * ```
  */

package/dist/permission/permissionRegistry.js

@@ -4,6 +4,7 @@
  * @module permission/permissionRegistry
  */
 import { DuplicatePermissionError, InvalidPermissionError, PermissionNotFoundError, } from "../permissionErrors/index.js";
+import { createChangeNotifier } from "../utils/utils.notifier.js";
 import { formatPermission, isValidPermission, matchesPermission, parsePermission, } from "./permission.core.js";
 /**
  * Create a permission registry.
@@ -14,13 +15,17 @@ import { formatPermission, isValidPermission, matchesPermission, parsePermission
  *
  * const engine = createPermissionEngine({
  *   roles,
- *   expandImplied: (permission) => permissions.expandImplied(permission),
+ *   // Pass the registry itself, not a closure over it: the engine
+ *   // subscribes, so revoking an implication drops the cached decisions
+ *   // that were made under it.
+ *   expandImplied: permissions,
  * });
  * ```
  */
 export function createPermissionRegistry(options) {
     const permissions = new Map();
     const allowOverride = options?.allowOverride ?? false;
+    const changes = createChangeNotifier();
     function keyOf(permission) {
         if (typeof permission === "string") {
             // Validate strings and structured values alike; a structured value
@@ -53,6 +58,7 @@ export function createPermissionRegistry(options) {
                     ? Object.freeze([...defineOptions.implies])
                     : undefined,
             });
+            changes.notify();
         },
         get(permission) {
             return permissions.get(permission)?.parsed;
@@ -96,10 +102,17 @@ export function createPermissionRegistry(options) {
             return [...expanded];
         },
         remove(permission) {
-            return permissions.delete(permission);
+            const removed = permissions.delete(permission);
+            if (removed)
+                changes.notify();
+            return removed;
         },
         clear() {
             permissions.clear();
+            changes.notify();
+        },
+        subscribe(listener) {
+            return changes.subscribe(listener);
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/permissions",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.",
   "license": "MIT",
   "author": {
@@ -26,7 +26,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/errors": "1.2.0"
   },
   "engines": {
     "node": ">=24.0.0"