@zudojs/permissions 1.0.0 → 1.2.0

package/dist/rule/rule.core.js

@@ -3,42 +3,34 @@
  *
  * @module rule/rule
  */
+import { ruleBearsOn } from "./rule.pattern.js";
+export { ruleMatches, patternStrMatches } from "./rule.pattern.js";
 /**
- * Check if a rule matches a target permission.
- *
- * Matching is about resource and action only. Whether the rule *applies* also
- * depends on its condition, which needs a context and is therefore evaluated
- * by {@link evaluateRules}.
+ * Sort key for `priority` combining: higher priority first, and at equal
+ * priority a deny before an allow.
  */
-export function ruleMatches(rule, target) {
-    return (patternListMatches(rule.resource, target.resource) &&
-        patternListMatches(rule.action, target.action));
-}
-/** Check if any pattern in a rule field matches a target segment. */
-function patternListMatches(pattern, target) {
-    if (Array.isArray(pattern)) {
-        return pattern.some((entry) => patternStrMatches(entry, target));
-    }
-    return patternStrMatches(pattern, target);
+function byPriority(a, b) {
+    const priorityA = a.priority ?? 0;
+    const priorityB = b.priority ?? 0;
+    if (priorityA !== priorityB)
+        return priorityB - priorityA;
+    if (a.effect === "deny" && b.effect !== "deny")
+        return -1;
+    if (b.effect === "deny" && a.effect !== "deny")
+        return 1;
+    return 0;
 }
-/**
- * Check if a single pattern string matches a target, supporting wildcards.
- *
- * Two forms are supported, and they are the same two the permission matcher
- * supports, so a pattern means the same thing wherever it is written:
- *   `*`           — matches anything
- *   `billing.*`   — matches `billing` and any `billing.…` namespace
- */
-export function patternStrMatches(pattern, target) {
-    if (pattern === "*")
-        return true;
-    if (pattern === target)
-        return true;
-    if (pattern.endsWith(".*")) {
-        const prefix = pattern.slice(0, -2);
-        return target === prefix || target.startsWith(`${prefix}.`);
+function combineApplicable(applicable, algorithm) {
+    if (applicable.length === 0)
+        return { allowed: false, applicable: [] };
+    if (algorithm === "deny-overrides") {
+        const deny = applicable.find((rule) => rule.effect === "deny");
+        if (deny)
+            return { allowed: false, matchedRule: deny, applicable };
+        return { allowed: true, matchedRule: applicable[0], applicable };
     }
-    return false;
+    const top = [...applicable].sort(byPriority)[0];
+    return { allowed: top.effect === "allow", matchedRule: top, applicable };
 }
 /**
  * Evaluate a set of rules against a target permission.
@@ -48,9 +40,15 @@ export function patternStrMatches(pattern, target) {
  * has to mean "owners may", not "anyone may". Conditions are async, so this
  * function is too.
  *
- * A condition that throws is treated as unmet — an authorization check fails
- * closed. A rule that carries a condition when no context was supplied is
- * skipped for the same reason.
+ * 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* in the same position
+ * does apply: treating it as unmet dropped the deny and let the role's allow
+ * win, so a missing resource or a blocklist service that was down granted
+ * the very access the deny existed to refuse.
+ *
+ * A deny also applies when its patterns merely overlap a wildcard target —
+ * `can(actor, "post:*")` is refused by a deny on `post:delete`.
  *
  * Default combining algorithm: `deny-overrides`. Any applicable deny wins,
  * whatever its priority.
@@ -59,78 +57,43 @@ export async function evaluateRules(rules, target, context, options) {
     const algorithm = options?.algorithm ?? "deny-overrides";
     const applicable = [];
     for (const rule of rules) {
-        if (!ruleMatches(rule, target))
+        if (!ruleBearsOn(rule, target))
             continue;
         if (rule.condition) {
-            if (!context)
+            const failClosed = rule.effect === "deny";
+            if (!context) {
+                if (failClosed)
+                    applicable.push(rule);
                 continue;
-            let met = false;
+            }
+            let met;
             try {
                 met = await rule.condition(context);
             }
             catch (error) {
                 options?.onConditionError?.(rule, error);
-                met = false;
+                met = failClosed;
             }
             if (!met)
                 continue;
         }
         applicable.push(rule);
     }
-    if (applicable.length === 0) {
-        return { allowed: false, applicable: [] };
-    }
-    if (algorithm === "deny-overrides") {
-        const deny = applicable.find((rule) => rule.effect === "deny");
-        if (deny)
-            return { allowed: false, matchedRule: deny, applicable };
-        return { allowed: true, matchedRule: applicable[0], applicable };
-    }
-    const sorted = [...applicable].sort((a, b) => {
-        const priorityA = a.priority ?? 0;
-        const priorityB = b.priority ?? 0;
-        if (priorityA !== priorityB)
-            return priorityB - priorityA;
-        // Same priority: deny wins.
-        if (a.effect === "deny" && b.effect !== "deny")
-            return -1;
-        if (b.effect === "deny" && a.effect !== "deny")
-            return 1;
-        return 0;
-    });
-    const top = sorted[0];
-    return { allowed: top.effect === "allow", matchedRule: top, applicable };
+    return combineApplicable(applicable, algorithm);
 }
 /**
  * Evaluate rules that carry no conditions.
  *
  * Synchronous, for callers that build their own condition-free rule sets.
- * Any rule with a condition is skipped, because there is no way to evaluate
- * one without awaiting it — use {@link evaluateRules} for those.
+ * A conditional rule cannot be evaluated without awaiting it — use
+ * {@link evaluateRules} for those — so it fails closed the same way an
+ * unevaluable condition does there: a conditional allow is skipped, and a
+ * conditional deny applies.
  */
 export function evaluateRulesSync(rules, target, options) {
     const algorithm = options?.algorithm ?? "deny-overrides";
-    const applicable = rules.filter((rule) => rule.condition === undefined && ruleMatches(rule, target));
-    if (applicable.length === 0)
-        return { allowed: false, applicable: [] };
-    if (algorithm === "deny-overrides") {
-        const deny = applicable.find((rule) => rule.effect === "deny");
-        if (deny)
-            return { allowed: false, matchedRule: deny, applicable };
-        return { allowed: true, matchedRule: applicable[0], applicable };
-    }
-    const sorted = [...applicable].sort((a, b) => {
-        const priorityA = a.priority ?? 0;
-        const priorityB = b.priority ?? 0;
-        if (priorityA !== priorityB)
-            return priorityB - priorityA;
-        if (a.effect === "deny" && b.effect !== "deny")
-            return -1;
-        if (b.effect === "deny" && a.effect !== "deny")
-            return 1;
-        return 0;
-    });
-    const top = sorted[0];
-    return { allowed: top.effect === "allow", matchedRule: top, applicable };
+    const applicable = rules.filter((rule) => ruleBearsOn(rule, target) &&
+        (rule.condition === undefined || rule.effect === "deny"));
+    return combineApplicable(applicable, algorithm);
 }
 //# sourceMappingURL=rule.core.js.map

package/dist/rule/rule.pattern.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pattern matching shared by rules, grants, denies and policies.
+ *
+ * @module rule/rule.pattern
+ */
+import type { Permission, PermissionRule } from "../permissionTypes/index.js";
+/**
+ * Check if a single pattern string matches a target, supporting wildcards.
+ *
+ * Two forms are supported, and they are the same two the permission matcher
+ * supports, so a pattern means the same thing wherever it is written:
+ *   `*`           — matches anything
+ *   `billing.*`   — matches `billing` and any `billing.…` namespace
+ */
+export declare function patternStrMatches(pattern: string, target: string): boolean;
+/**
+ * Whether two segment patterns can name a common segment.
+ *
+ * For a concrete `target` this is exactly {@link patternStrMatches}. For a
+ * wildcard target it is what a *deny* has to test: `can(actor, "post:*")`
+ * asks about everything under `post`, so a deny of `post:delete` bears on it
+ * although `post:delete` does not match `post:*` as a pattern.
+ */
+export declare function patternsOverlap(a: string, b: string): boolean;
+/**
+ * Check if a rule matches a target permission.
+ *
+ * Matching is about resource and action only. Whether the rule *applies* also
+ * depends on its condition, which needs a context and is therefore evaluated
+ * by `evaluateRules`.
+ */
+export declare function ruleMatches(rule: PermissionRule, target: Permission): boolean;
+/** Check if a rule's patterns overlap a (possibly wildcard) target. */
+export declare function ruleOverlaps(rule: PermissionRule, target: Permission): boolean;
+/**
+ * Whether a rule bears on a target: allows by matching, denies by overlap.
+ *
+ * An allow must cover the whole target to grant it; a deny needs only to
+ * touch it. For a concrete target the two are the same test.
+ */
+export declare function ruleBearsOn(rule: PermissionRule, target: Permission): boolean;
+/** Whether a permission names more than one concrete permission. */
+export declare function isWildcardTarget(target: Permission): boolean;
+//# sourceMappingURL=rule.pattern.d.ts.map

package/dist/rule/rule.pattern.js

@@ -0,0 +1,72 @@
+/**
+ * Pattern matching shared by rules, grants, denies and policies.
+ *
+ * @module rule/rule.pattern
+ */
+/**
+ * Check if a single pattern string matches a target, supporting wildcards.
+ *
+ * Two forms are supported, and they are the same two the permission matcher
+ * supports, so a pattern means the same thing wherever it is written:
+ *   `*`           — matches anything
+ *   `billing.*`   — matches `billing` and any `billing.…` namespace
+ */
+export function patternStrMatches(pattern, target) {
+    if (pattern === "*")
+        return true;
+    if (pattern === target)
+        return true;
+    if (pattern.endsWith(".*")) {
+        const prefix = pattern.slice(0, -2);
+        return target === prefix || target.startsWith(`${prefix}.`);
+    }
+    return false;
+}
+/**
+ * Whether two segment patterns can name a common segment.
+ *
+ * For a concrete `target` this is exactly {@link patternStrMatches}. For a
+ * wildcard target it is what a *deny* has to test: `can(actor, "post:*")`
+ * asks about everything under `post`, so a deny of `post:delete` bears on it
+ * although `post:delete` does not match `post:*` as a pattern.
+ */
+export function patternsOverlap(a, b) {
+    return patternStrMatches(a, b) || patternStrMatches(b, a);
+}
+function patternList(pattern) {
+    return Array.isArray(pattern)
+        ? pattern
+        : [pattern];
+}
+/**
+ * Check if a rule matches a target permission.
+ *
+ * Matching is about resource and action only. Whether the rule *applies* also
+ * depends on its condition, which needs a context and is therefore evaluated
+ * by `evaluateRules`.
+ */
+export function ruleMatches(rule, target) {
+    return (patternList(rule.resource).some((entry) => patternStrMatches(entry, target.resource)) &&
+        patternList(rule.action).some((entry) => patternStrMatches(entry, target.action)));
+}
+/** Check if a rule's patterns overlap a (possibly wildcard) target. */
+export function ruleOverlaps(rule, target) {
+    return (patternList(rule.resource).some((entry) => patternsOverlap(entry, target.resource)) &&
+        patternList(rule.action).some((entry) => patternsOverlap(entry, target.action)));
+}
+/**
+ * Whether a rule bears on a target: allows by matching, denies by overlap.
+ *
+ * An allow must cover the whole target to grant it; a deny needs only to
+ * touch it. For a concrete target the two are the same test.
+ */
+export function ruleBearsOn(rule, target) {
+    return rule.effect === "deny"
+        ? ruleOverlaps(rule, target)
+        : ruleMatches(rule, target);
+}
+/** Whether a permission names more than one concrete permission. */
+export function isWildcardTarget(target) {
+    return target.resource.includes("*") || target.action.includes("*");
+}
+//# sourceMappingURL=rule.pattern.js.map

package/dist/utils/utils.notifier.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal change notifier for the live registries.
+ *
+ * @module utils/utils.notifier
+ */
+/** A set of change listeners. */
+export interface ChangeNotifier {
+    /** Register a listener. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Call every listener. All of them run even if one throws; the first
+     * error is rethrown afterwards, so one broken subscriber cannot stop an
+     * engine further down the list from dropping its stale decisions.
+     */
+    notify(): void;
+}
+/** Create a {@link ChangeNotifier}. */
+export declare function createChangeNotifier(): ChangeNotifier;
+//# sourceMappingURL=utils.notifier.d.ts.map

package/dist/utils/utils.notifier.js

@@ -0,0 +1,31 @@
+/**
+ * Minimal change notifier for the live registries.
+ *
+ * @module utils/utils.notifier
+ */
+/** Create a {@link ChangeNotifier}. */
+export function createChangeNotifier() {
+    const listeners = new Set();
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        notify() {
+            let failure;
+            for (const listener of [...listeners]) {
+                try {
+                    listener();
+                }
+                catch (error) {
+                    failure ??= { error };
+                }
+            }
+            if (failure)
+                throw failure.error;
+        },
+    };
+}
+//# sourceMappingURL=utils.notifier.js.map

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/permissions",
-  "version": "1.0.0",
+  "version": "1.2.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,15 +26,7 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
-  },
-  "peerDependencies": {
-    "@zudojs/http": "1.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@zudojs/http": {
-      "optional": true
-    }
+    "@zudojs/errors": "1.1.0"
   },
   "engines": {
     "node": ">=24.0.0"