@zudojs/permissions 0.1.0 → 1.1.0

package/dist/role/roleRegistry.js

@@ -3,62 +3,84 @@
  *
  * @module role/roleRegistry
  */
-import { DuplicateRoleError, InvalidRoleError, } from "../permissionErrors/index.js";
+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.
+ *
+ * Pass it straight to `createPermissionEngine({ roles: registry })`.
  */
 export function createRoleRegistry(options) {
     const roles = new Map();
     const allowOverride = options?.allowOverride ?? false;
+    const validatePermissions = options?.validatePermissions ?? true;
     return {
         /**
          * Register a role definition.
+         *
+         * A role with no permissions of its own is valid: a role that exists only
+         * to combine others through `inherits` is the normal way to build a
+         * hierarchy.
          */
         define(definition) {
             if (!definition.name || definition.name.trim() === "") {
                 throw new InvalidRoleError("Role name cannot be empty");
             }
-            if (!definition.permissions || definition.permissions.length === 0) {
-                throw new InvalidRoleError(`Role "${definition.name}" must have at least one permission`);
+            if (!Array.isArray(definition.permissions)) {
+                throw new InvalidRoleError(`Role "${definition.name}" must declare a permissions array`);
+            }
+            if (validatePermissions) {
+                for (const permission of definition.permissions) {
+                    if (!isValidPermission(permission)) {
+                        throw new InvalidRoleError(`Role "${definition.name}" grants "${permission}", which is not a ` +
+                            `valid "resource:action" permission`);
+                    }
+                }
             }
             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 a role by name.
-         */
         get(name) {
             return roles.get(name);
         },
-        /**
-         * Check if a role exists.
-         */
+        require(name) {
+            const role = roles.get(name);
+            if (!role)
+                throw new RoleNotFoundError(name);
+            return role;
+        },
         has(name) {
             return roles.has(name);
         },
-        /**
-         * Get all registered role names.
-         */
         names() {
-            return Array.from(roles.keys());
+            return [...roles.keys()];
         },
-        /**
-         * Get all registered role definitions.
-         */
         all() {
-            return Array.from(roles.values());
+            return [...roles.values()];
         },
-        /**
-         * Remove a role from the registry.
-         */
         remove(name) {
             return roles.delete(name);
         },
-        /**
-         * Clear all registered roles.
-         */
         clear() {
             roles.clear();
         },

package/dist/rule/index.d.ts

@@ -3,6 +3,6 @@
  *
  * @module rule
  */
-export { ruleMatches, evaluateRules } from "./rule.core.js";
-export { compileRules, findMatchingRules } from "./ruleCompiler.js";
+export { ruleMatches, patternStrMatches, evaluateRules, evaluateRulesSync, } from "./rule.core.js";
+export { compileRules, findMatchingRules, type RuleIndex, } from "./ruleCompiler.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rule/index.js

@@ -3,6 +3,6 @@
  *
  * @module rule
  */
-export { ruleMatches, evaluateRules } from "./rule.core.js";
-export { compileRules, findMatchingRules } from "./ruleCompiler.js";
+export { ruleMatches, patternStrMatches, evaluateRules, evaluateRulesSync, } from "./rule.core.js";
+export { compileRules, findMatchingRules, } from "./ruleCompiler.js";
 //# sourceMappingURL=index.js.map

package/dist/rule/rule.core.d.ts

@@ -1,24 +1,53 @@
 /**
- * Rule matching and compilation for permission evaluation.
+ * Rule matching and evaluation for permission decisions.
  *
  * @module rule/rule
  */
-import type { PermissionRule, Permission } from "../permissionTypes/index.js";
+import type { PermissionRule, Permission, PermissionContext, RuleCombiningAlgorithm, RuleEvaluation } from "../permissionTypes/index.js";
 /**
  * Check if a rule matches a target permission.
  *
- * A rule matches if its resource and action patterns match the target,
- * considering wildcard support.
+ * 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}.
  */
 export declare function ruleMatches(rule: PermissionRule, target: Permission): boolean;
+/**
+ * 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;
 /**
  * Evaluate a set of rules against a target permission.
  *
- * Returns the effective decision after applying deny-overrides and priority.
- * Default: deny.
+ * A rule with a condition applies only when that condition returns `true`,
+ * which is what makes ABAC work: `{ effect: "allow", condition: isOwner() }`
+ * 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.
+ *
+ * Default combining algorithm: `deny-overrides`. Any applicable deny wins,
+ * whatever its priority.
+ */
+export declare function evaluateRules(rules: readonly PermissionRule[], target: Permission, context?: PermissionContext, options?: {
+    readonly algorithm?: RuleCombiningAlgorithm;
+    readonly onConditionError?: (rule: PermissionRule, error: unknown) => void;
+}): Promise<RuleEvaluation>;
+/**
+ * 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.
  */
-export declare function evaluateRules(rules: readonly PermissionRule[], target: Permission): {
-    readonly allowed: boolean;
-    readonly matchedRule?: PermissionRule;
-};
+export declare function evaluateRulesSync(rules: readonly PermissionRule[], target: Permission, options?: {
+    readonly algorithm?: RuleCombiningAlgorithm;
+}): RuleEvaluation;
 //# sourceMappingURL=rule.core.d.ts.map

package/dist/rule/rule.core.js

@@ -1,45 +1,39 @@
 /**
- * Rule matching and compilation for permission evaluation.
+ * Rule matching and evaluation for permission decisions.
  *
  * @module rule/rule
  */
 /**
  * Check if a rule matches a target permission.
  *
- * A rule matches if its resource and action patterns match the target,
- * considering wildcard support.
+ * 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}.
  */
 export function ruleMatches(rule, target) {
-    return (resourceMatches(rule.resource, target.resource) &&
-        actionMatches(rule.action, target.action));
+    return (patternListMatches(rule.resource, target.resource) &&
+        patternListMatches(rule.action, target.action));
 }
-/**
- * Check if a rule's resource pattern matches a target resource.
- */
-function resourceMatches(pattern, target) {
+/** Check if any pattern in a rule field matches a target segment. */
+function patternListMatches(pattern, target) {
     if (Array.isArray(pattern)) {
-        return pattern.some((p) => patternStrMatches(p, target));
-    }
-    return patternStrMatches(pattern, target);
-}
-/**
- * Check if a rule's action pattern matches a target action.
- */
-function actionMatches(pattern, target) {
-    if (Array.isArray(pattern)) {
-        return pattern.some((p) => patternStrMatches(p, target));
+        return pattern.some((entry) => patternStrMatches(entry, target));
     }
     return patternStrMatches(pattern, target);
 }
 /**
  * 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
  */
-function patternStrMatches(pattern, target) {
+export function patternStrMatches(pattern, target) {
     if (pattern === "*")
         return true;
     if (pattern === target)
         return true;
-    // Namespace wildcard: "billing.*" matches "billing.invoice"
     if (pattern.endsWith(".*")) {
         const prefix = pattern.slice(0, -2);
         return target === prefix || target.startsWith(`${prefix}.`);
@@ -49,21 +43,87 @@ function patternStrMatches(pattern, target) {
 /**
  * Evaluate a set of rules against a target permission.
  *
- * Returns the effective decision after applying deny-overrides and priority.
- * Default: deny.
+ * A rule with a condition applies only when that condition returns `true`,
+ * which is what makes ABAC work: `{ effect: "allow", condition: isOwner() }`
+ * 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.
+ *
+ * Default combining algorithm: `deny-overrides`. Any applicable deny wins,
+ * whatever its priority.
+ */
+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))
+            continue;
+        if (rule.condition) {
+            if (!context)
+                continue;
+            let met = false;
+            try {
+                met = await rule.condition(context);
+            }
+            catch (error) {
+                options?.onConditionError?.(rule, error);
+                met = false;
+            }
+            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 };
+}
+/**
+ * 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.
  */
-export function evaluateRules(rules, target) {
-    const matching = rules.filter((r) => ruleMatches(r, target));
-    if (matching.length === 0) {
-        return { allowed: false };
+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 };
     }
-    // Sort by priority descending; same priority: deny wins (deny has higher effective priority)
-    const sorted = [...matching].sort((a, b) => {
-        const priA = a.priority ?? 0;
-        const priB = b.priority ?? 0;
-        if (priA !== priB)
-            return priB - priA;
-        // Same priority: deny wins
+    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")
@@ -71,9 +131,6 @@ export function evaluateRules(rules, target) {
         return 0;
     });
     const top = sorted[0];
-    return {
-        allowed: top.effect === "allow",
-        matchedRule: top,
-    };
+    return { allowed: top.effect === "allow", matchedRule: top, applicable };
 }
 //# sourceMappingURL=rule.core.js.map

package/dist/rule/ruleCompiler.d.ts

@@ -4,16 +4,22 @@
  * @module rule/ruleCompiler
  */
 import type { PermissionRule, Permission } from "../permissionTypes/index.js";
-/** Compiled rule index for O(1) lookup by resource:action. */
-interface RuleIndex {
+/** Compiled rule index for fast lookup by resource:action. */
+export interface RuleIndex {
     /** Exact matches: "post:update" → rules. */
     readonly exact: ReadonlyMap<string, readonly PermissionRule[]>;
-    /** Resource wildcards: "post:*" → rules. */
+    /** Resource wildcards: "post:*" → rules, keyed by resource. */
     readonly resourceWildcard: ReadonlyMap<string, readonly PermissionRule[]>;
-    /** Action wildcards: "*:read" → rules. */
+    /** Action wildcards: "*:read" → rules, keyed by action. */
     readonly actionWildcard: ReadonlyMap<string, readonly PermissionRule[]>;
     /** Global wildcards: "*:*" → rules. */
     readonly globalWildcard: readonly PermissionRule[];
+    /**
+     * Rules using a namespace wildcard (`billing.*`), which no exact key can
+     * index. Scanned linearly — small in practice, and leaving them out of the
+     * index entirely is what made them silently unmatchable.
+     */
+    readonly patterned: readonly PermissionRule[];
 }
 /**
  * Compile a set of rules into an optimized index.
@@ -21,7 +27,10 @@ interface RuleIndex {
 export declare function compileRules(rules: readonly PermissionRule[]): RuleIndex;
 /**
  * Find all rules from the compiled index that match a target permission.
+ *
+ * The result is de-duplicated: a rule listing several resources or actions is
+ * indexed under each, and returning it more than once would let one rule
+ * count twice when the decision is combined.
  */
 export declare function findMatchingRules(index: RuleIndex, target: Permission): readonly PermissionRule[];
-export {};
 //# sourceMappingURL=ruleCompiler.d.ts.map

package/dist/rule/ruleCompiler.js

@@ -3,6 +3,11 @@
  *
  * @module rule/ruleCompiler
  */
+import { ruleMatches } from "./rule.core.js";
+/** True when a pattern needs a linear scan rather than a map lookup. */
+function isPatterned(pattern) {
+    return pattern !== "*" && pattern.endsWith(".*");
+}
 /**
  * Compile a set of rules into an optimized index.
  */
@@ -11,63 +16,74 @@ export function compileRules(rules) {
     const resourceWildcard = new Map();
     const actionWildcard = new Map();
     const globalWildcard = [];
+    const patterned = [];
+    const push = (map, key, rule) => {
+        const bucket = map.get(key);
+        if (bucket)
+            bucket.push(rule);
+        else
+            map.set(key, [rule]);
+    };
     for (const rule of rules) {
         const resources = normalizeToArray(rule.resource);
         const actions = normalizeToArray(rule.action);
+        let indexed = false;
         for (const resource of resources) {
             for (const action of actions) {
+                if (isPatterned(resource) || isPatterned(action)) {
+                    if (!indexed) {
+                        patterned.push(rule);
+                        indexed = true;
+                    }
+                    continue;
+                }
                 if (resource === "*" && action === "*") {
                     globalWildcard.push(rule);
                 }
                 else if (resource === "*") {
-                    const key = action;
-                    if (!actionWildcard.has(key))
-                        actionWildcard.set(key, []);
-                    actionWildcard.get(key).push(rule);
+                    push(actionWildcard, action, rule);
                 }
                 else if (action === "*") {
-                    const key = resource;
-                    if (!resourceWildcard.has(key))
-                        resourceWildcard.set(key, []);
-                    resourceWildcard.get(key).push(rule);
+                    push(resourceWildcard, resource, rule);
                 }
                 else {
-                    const key = `${resource}:${action}`;
-                    if (!exact.has(key))
-                        exact.set(key, []);
-                    exact.get(key).push(rule);
+                    push(exact, `${resource}:${action}`, rule);
                 }
             }
         }
     }
-    const index = {
-        exact,
-        resourceWildcard,
-        actionWildcard,
-        globalWildcard,
-    };
-    return index;
+    return { exact, resourceWildcard, actionWildcard, globalWildcard, patterned };
 }
 /**
  * Find all rules from the compiled index that match a target permission.
+ *
+ * The result is de-duplicated: a rule listing several resources or actions is
+ * indexed under each, and returning it more than once would let one rule
+ * count twice when the decision is combined.
  */
 export function findMatchingRules(index, target) {
     const results = [];
-    const key = `${target.resource}:${target.action}`;
+    const seen = new Set();
+    const add = (rules) => {
+        if (!rules)
+            return;
+        for (const rule of rules) {
+            if (seen.has(rule))
+                continue;
+            seen.add(rule);
+            results.push(rule);
+        }
+    };
     // 1. Exact matches
-    const exactRules = index.exact.get(key);
-    if (exactRules)
-        results.push(...exactRules);
+    add(index.exact.get(`${target.resource}:${target.action}`));
     // 2. Resource wildcard: "post:*" matches "post:update"
-    const resWildcard = index.resourceWildcard.get(target.resource);
-    if (resWildcard)
-        results.push(...resWildcard);
+    add(index.resourceWildcard.get(target.resource));
     // 3. Action wildcard: "*:read" matches "post:read"
-    const actWildcard = index.actionWildcard.get(target.action);
-    if (actWildcard)
-        results.push(...actWildcard);
+    add(index.actionWildcard.get(target.action));
     // 4. Global wildcard: "*:*"
-    results.push(...index.globalWildcard);
+    add(index.globalWildcard);
+    // 5. Namespace wildcards, which need a real match test
+    add(index.patterned.filter((rule) => ruleMatches(rule, target)));
     return results;
 }
 function normalizeToArray(value) {

package/dist/utils/utils.helper.d.ts

@@ -6,6 +6,10 @@
 import type { PermissionActor } from "../permissionTypes/index.js";
 /**
  * Create a permission check cache key.
+ *
+ * @deprecated Use `permissionCacheKey` from `@zudojs/permissions`. Two key
+ * formats meant entries written with one were invisible to the invalidation
+ * that understood the other; this now delegates to the canonical builder.
  */
 export declare function createCacheKey(actorId: string, permission: string, resourceId?: string): string;
 /**
@@ -27,6 +31,10 @@ export declare function extractAction(permission: string): string;
 export declare function buildPermission(resource: string, action: string): string;
 /**
  * Create a quick actor object.
+ *
+ * @deprecated Use `createPermissionActor`. This used to build an actor whose
+ * role and permission arrays were not frozen, so two functions with the same
+ * job produced objects with different mutability.
  */
 export declare function createActor(id: string, options?: {
     readonly type?: string;

package/dist/utils/utils.helper.js

@@ -3,12 +3,18 @@
  *
  * @module utils/utils
  */
+import { permissionCacheKey } from "../cache/cache.core.js";
+import { createPermissionActor } from "../actor/actor.core.js";
+import { formatPermission, parsePermissionSafe, } from "../permission/permission.core.js";
 /**
  * Create a permission check cache key.
+ *
+ * @deprecated Use `permissionCacheKey` from `@zudojs/permissions`. Two key
+ * formats meant entries written with one were invisible to the invalidation
+ * that understood the other; this now delegates to the canonical builder.
  */
 export function createCacheKey(actorId, permission, resourceId) {
-    const base = `${actorId}:${permission}`;
-    return resourceId ? `${base}:${resourceId}` : base;
+    return permissionCacheKey(actorId, permission, resourceId);
 }
 /**
  * Extract the resource type from a permission string.
@@ -17,8 +23,7 @@ export function createCacheKey(actorId, permission, resourceId) {
  * @example extractResource("billing.invoice:refund") → "billing.invoice"
  */
 export function extractResource(permission) {
-    const lastColon = permission.lastIndexOf(":");
-    return lastColon > 0 ? permission.slice(0, lastColon) : permission;
+    return parsePermissionSafe(permission)?.resource ?? permission;
 }
 /**
  * Extract the action from a permission string.
@@ -26,25 +31,22 @@ export function extractResource(permission) {
  * @example extractAction("post:update") → "update"
  */
 export function extractAction(permission) {
-    const lastColon = permission.lastIndexOf(":");
-    return lastColon > 0 ? permission.slice(lastColon + 1) : "";
+    return parsePermissionSafe(permission)?.action ?? "";
 }
 /**
  * Build a permission string from resource and action.
  */
 export function buildPermission(resource, action) {
-    return `${resource}:${action}`;
+    return formatPermission(resource, action);
 }
 /**
  * Create a quick actor object.
+ *
+ * @deprecated Use `createPermissionActor`. This used to build an actor whose
+ * role and permission arrays were not frozen, so two functions with the same
+ * job produced objects with different mutability.
  */
 export function createActor(id, options) {
-    return Object.freeze({
-        id,
-        type: options?.type,
-        roles: options?.roles,
-        permissions: options?.permissions,
-        deniedPermissions: options?.deniedPermissions,
-    });
+    return createPermissionActor(id, options);
 }
 //# sourceMappingURL=utils.helper.js.map