@zudojs/permissions 1.0.0 → 1.1.0

package/README.md

@@ -151,8 +151,8 @@ const engine = createPermissionEngine({
 
 Policies run highest priority first and stop at the first denial. A policy
 that throws, or exceeds `policyTimeout`, denies. A denying policy always wins;
-an allowing one can grant access the rules did not, but never overrides a
-denial.
+an allowing one can grant access the rules did not decide, but never overrides
+a denial — from another policy or from a deny rule that applied.
 
 `policyTimeout: 0` means "expire immediately", not "no timeout" — omit it to
 disable.
@@ -178,6 +178,9 @@ const engine = createPermissionEngine({ roles, policies });
 roles.define({ name: "auditor", permissions: ["audit:read"] });
 engine.invalidateRoles(); // pick up the change
 
+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
 ```
 
@@ -225,7 +228,8 @@ 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.
+decision. A `|` inside an actor or resource id is escaped, so two different
+(actor, permission, resource) triples can never share a key either.
 
 A check is cached only when the key can describe it completely:
 
@@ -265,6 +269,7 @@ 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                                    |
+| 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`                          |

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

@@ -8,7 +8,8 @@ import type { PermissionCache } from "../permissionTypes/index.js";
  * Generate a cache key for a permission check.
  *
  * The actor id is delimited, so invalidating actor `1` cannot also clear
- * actors `10` and `123`.
+ * actors `10` and `123`, and a delimiter inside an id is escaped so two
+ * different (actor, permission, resource) triples can never share a key.
  */
 export declare function permissionCacheKey(actorId: string, permission: string, resourceId?: string): string;
 /** Options for {@link createMemoryPermissionCache}. */

package/dist/cache/cache.core.js

@@ -5,19 +5,34 @@
  */
 /** Separates the actor id from the rest of the key. */
 const KEY_DELIMITER = "|";
+/**
+ * Escape a caller-supplied segment so it cannot forge a delimiter.
+ *
+ * Actor and resource ids are opaque strings and may contain `|`. Without
+ * escaping, actor `u|post:read` checking `x:y` produced the same key as
+ * actor `u` checking `post:read` on resource `x:y` — one actor's cached
+ * decision answering for another. Ids without `|` or `\` are unchanged, so
+ * existing keys keep their shape.
+ */
+function escapeSegment(segment) {
+    return segment.replace(/[\\|]/g, (char) => `\\${char}`);
+}
 /** Prefix identifying an actor's cache entries. */
 function actorPrefix(actorId) {
-    return `actor:${actorId}${KEY_DELIMITER}`;
+    return `actor:${escapeSegment(actorId)}${KEY_DELIMITER}`;
 }
 /**
  * Generate a cache key for a permission check.
  *
  * The actor id is delimited, so invalidating actor `1` cannot also clear
- * actors `10` and `123`.
+ * actors `10` and `123`, and a delimiter inside an id is escaped so two
+ * different (actor, permission, resource) triples can never share a key.
  */
 export function permissionCacheKey(actorId, permission, resourceId) {
     const base = `${actorPrefix(actorId)}${permission}`;
-    return resourceId ? `${base}${KEY_DELIMITER}${resourceId}` : base;
+    return resourceId
+        ? `${base}${KEY_DELIMITER}${escapeSegment(resourceId)}`
+        : base;
 }
 const DEFAULT_TTL_MS = 60_000;
 const DEFAULT_MAX_ENTRIES = 10_000;

package/dist/evaluator/authorizationEngine.js

@@ -8,6 +8,7 @@ import { createAbility } from "../ability/ability.core.js";
 import { PermissionDeniedError, InvalidRoleError, } from "../permissionErrors/index.js";
 import { isValidPermission } from "../permission/permission.core.js";
 import { memoizeRoleLookup } from "../role/roleHierarchy.js";
+import { freezeRoleDefinition } from "../role/roleRegistry.js";
 function isRoleSource(roles) {
     return (roles !== undefined &&
         !Array.isArray(roles) &&
@@ -68,7 +69,9 @@ export function createPermissionEngine(options) {
         const list = (options?.roles ?? []);
         if (validateConfiguration)
             validateRoles(list);
-        const roleMap = new Map(list.map((role) => [role.name, role]));
+        // Copy each role, so a caller still holding the arrays it passed in
+        // cannot widen a grant after validation has run.
+        const roleMap = new Map(list.map((role) => [role.name, freezeRoleDefinition(role)]));
         roleLookup = (name) => roleMap.get(name);
         invalidateRoleCache = () => { };
     }
@@ -86,9 +89,16 @@ export function createPermissionEngine(options) {
             .map((name) => policySource.get(name))
             .filter((policy) => policy !== undefined);
     };
-    const evaluatorOptions = () => ({
-        getRole: roleLookup,
-        policies: resolvePolicies(),
+    // 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
+    // created, so a policy defined afterwards was enforced by `engine.can()`
+    // and ignored by `ability.can()` for the same actor.
+    const liveOptions = {
+        getRole: (name) => roleLookup(name),
+        get policies() {
+            return resolvePolicies();
+        },
         rules: options?.rules,
         policyTimeout: options?.policyTimeout,
         algorithm: options?.algorithm,
@@ -98,7 +108,8 @@ export function createPermissionEngine(options) {
         roleResolver: options?.roleResolver,
         expandImplied: options?.expandImplied,
         onError: options?.onError,
-    });
+    };
+    const evaluatorOptions = () => liveOptions;
     const emitter = options?.emitter;
     /**
      * Runs a check and emits an audit event whichever way it ends — including

package/dist/evaluator/evaluator.core.js

@@ -186,7 +186,7 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
             });
         }
     }
-    const decision = combine(ruleResult.allowed, outcome.decision, permissionStr);
+    const decision = combine(ruleResult, outcome.decision, permissionStr);
     /* ── Cache write ─────────────────────────────────────────────────────── */
     if (options.cache && cacheKey && outcome.cacheable) {
         try {
@@ -205,12 +205,25 @@ export async function evaluate(actor, permissionStr, resource, options, authOpti
  *
  * A denying policy always wins. An allowing policy can grant access the rules
  * did not, which is what makes a policy an ABAC escape hatch rather than a
- * filter — but it can never override a denial.
+ * filter — but it can never override a denial, and that includes a denial
+ * the *rules* produced. "The rules did not allow" covers two cases: no rule
+ * matched, and a deny rule matched. Treating them alike let an allowing
+ * policy for `post:*` cancel a `deny post:update` rule — the exact inversion
+ * of `deny-overrides`.
  */
-function combine(ruleAllowed, policyDecision, permissionStr) {
+function combine(ruleResult, policyDecision, permissionStr) {
     if (policyDecision && !policyDecision.allowed)
         return policyDecision;
-    if (ruleAllowed) {
+    const denyRule = !ruleResult.allowed && ruleResult.matchedRule?.effect === "deny"
+        ? ruleResult.matchedRule
+        : undefined;
+    if (denyRule) {
+        return denied("rule_deny", {
+            matchedPermission: permissionStr,
+            ...(denyRule.name ? { policy: denyRule.name } : {}),
+        });
+    }
+    if (ruleResult.allowed) {
         return Object.freeze({
             allowed: true,
             reason: "role_permission",

package/dist/policy/policyRegistry.js

@@ -25,7 +25,12 @@ export function createPolicyRegistry(options) {
             if (policies.has(definition.name) && !allowOverride) {
                 throw new DuplicatePolicyError(definition.name);
             }
-            policies.set(definition.name, Object.freeze({ ...definition }));
+            // Copy the permission list: a caller mutating the array it passed in
+            // must not re-scope the policy after registration.
+            policies.set(definition.name, Object.freeze({
+                ...definition,
+                permissions: Object.freeze([...definition.permissions]),
+            }));
         },
         get(name) {
             return policies.get(name);

package/dist/role/roleRegistry.d.ts

@@ -27,6 +27,15 @@ export interface RoleRegistry {
     remove(name: string): boolean;
     clear(): void;
 }
+/**
+ * Copy a role definition so it no longer shares arrays with the caller.
+ *
+ * `Object.freeze({ ...definition })` froze the wrapper and kept the caller's
+ * `permissions`, `inherits` and `rules` arrays by reference — so pushing
+ * `"*:*"` onto an array *after* `define()` had validated it widened the role
+ * in silence.
+ */
+export declare function freezeRoleDefinition(definition: RoleDefinition): RoleDefinition;
 /**
  * Create a role registry.
  *

package/dist/role/roleRegistry.js

@@ -5,6 +5,24 @@
  */
 import { DuplicateRoleError, InvalidRoleError, RoleNotFoundError, } from "../permissionErrors/index.js";
 import { isValidPermission } from "../permission/permission.core.js";
+/**
+ * Copy a role definition so it no longer shares arrays with the caller.
+ *
+ * `Object.freeze({ ...definition })` froze the wrapper and kept the caller's
+ * `permissions`, `inherits` and `rules` arrays by reference — so pushing
+ * `"*:*"` onto an array *after* `define()` had validated it widened the role
+ * in silence.
+ */
+export function freezeRoleDefinition(definition) {
+    return Object.freeze({
+        ...definition,
+        permissions: Object.freeze([...definition.permissions]),
+        ...(definition.inherits
+            ? { inherits: Object.freeze([...definition.inherits]) }
+            : {}),
+        ...(definition.rules ? { rules: Object.freeze([...definition.rules]) } : {}),
+    });
+}
 /**
  * Create a role registry.
  *
@@ -40,7 +58,7 @@ export function createRoleRegistry(options) {
             if (roles.has(definition.name) && !allowOverride) {
                 throw new DuplicateRoleError(definition.name);
             }
-            roles.set(definition.name, Object.freeze({ ...definition }));
+            roles.set(definition.name, freezeRoleDefinition(definition));
         },
         get(name) {
             return roles.get(name);

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/permissions",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Generic authorization engine with RBAC, ABAC, resource authorization, wildcards, role hierarchy, policies, and abilities.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -22,10 +26,10 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.0.1"
   },
   "peerDependencies": {
-    "@zudojs/http": "1.0.0"
+    "@zudojs/http": "1.1.0"
   },
   "peerDependenciesMeta": {
     "@zudojs/http": {