@zudojs/permissions 1.0.0 → 1.2.0

package/dist/evaluator/evaluator.pipeline.js

@@ -4,7 +4,8 @@
  * @module evaluator/evaluator.pipeline
  */
 import { resolveRolePermissions } from "../role/roleHierarchy.js";
-import { matches } from "../permission/permission.core.js";
+import { matches, permissionsOverlap, parsePermissionSafe, } from "../permission/permission.core.js";
+import { isWildcardTarget } from "../rule/rule.pattern.js";
 import { AuthorizationAbortedError, PermissionResolverError, PolicyError, PolicyTimeoutError, } from "../permissionErrors/index.js";
 /**
  * Normalize a thrown value into an `Error` before it reaches `onError`.
@@ -126,6 +127,23 @@ export function selectPolicies(policies, permissionStr) {
     policy.permissions.some((pattern) => matches(pattern, permissionStr)))
         .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
 }
+/**
+ * Policies narrower than a wildcard target, which may deny it but not grant it.
+ *
+ * `can(actor, "post:*")` asks about every action under `post`. A policy
+ * registered for `post:delete` does not cover that question, so its allow
+ * must not grant it — but its denial is a denial of part of it, and a
+ * wildcard check must not side-step it.
+ */
+function narrowerPolicies(policies, applicable, permissionStr) {
+    const target = parsePermissionSafe(permissionStr);
+    if (!target || !isWildcardTarget(target))
+        return [];
+    return policies
+        .filter((policy) => !applicable.includes(policy) &&
+        policy.permissions.some((pattern) => permissionsOverlap(pattern, permissionStr)))
+        .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+}
 /**
  * Evaluate policies for a context.
  *
@@ -139,7 +157,8 @@ export async function evaluatePolicies(context, policies, options, authOptions)
     }
     const permissionStr = `${context.permission.resource}:${context.permission.action}`;
     const applicable = selectPolicies(policies, permissionStr);
-    if (applicable.length === 0) {
+    const denyOnly = narrowerPolicies(policies, applicable, permissionStr);
+    if (applicable.length === 0 && denyOnly.length === 0) {
         return { decision: null, cacheable: true, evaluated: [] };
     }
     // The per-call timeout wins, but the engine-level default is what makes a
@@ -147,7 +166,7 @@ export async function evaluatePolicies(context, policies, options, authOptions)
     const timeoutMs = authOptions?.policyTimeout ?? options.policyTimeout;
     const evaluated = [];
     let cacheable = true;
-    for (const policy of applicable) {
+    for (const policy of [...applicable, ...denyOnly]) {
         assertNotAborted(context.signal ?? authOptions?.signal);
         evaluated.push(policy.name);
         if (policy.cacheable === false)
@@ -184,6 +203,9 @@ export async function evaluatePolicies(context, policies, options, authOptions)
             };
         }
     }
+    if (applicable.length === 0) {
+        return { decision: null, cacheable, evaluated };
+    }
     return {
         decision: Object.freeze({
             allowed: true,

package/dist/http/httpMiddleware.core.d.ts

@@ -10,6 +10,7 @@ import type { PermissionActor, AuthorizationOptions } from "../permissionTypes/i
 import type { PermissionEngine } from "../evaluator/authorizationEngine.js";
 import type { HttpMiddleware, HttpMiddlewareContext } from "./httpTypes.js";
 import { type DeniedResponseOptions } from "./httpHelpers.js";
+import { type ResourceExtractor } from "./httpResource.helper.js";
 /** Options shared by the permission middleware. */
 export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
     /**
@@ -30,13 +31,18 @@ export interface AuthorizeMiddlewareOptions extends DeniedResponseOptions {
     readonly forwardSignal?: boolean;
     /** Builds per-request metadata for conditions and policies. */
     readonly extractMetadata?: (context: HttpMiddlewareContext) => Record<string, unknown> | undefined;
+    /** Reports a failure the guard turned into a denial (a failed resource load). */
+    readonly onError?: (error: unknown, source: string) => void;
 }
 /** Options for the requirePermission middleware. */
 export interface RequirePermissionMiddlewareOptions extends AuthorizeMiddlewareOptions {
     /** The permission to check (e.g. "post:update"). */
     readonly permission: string;
-    /** Extracts the resource from the request (optional). */
-    readonly extractResource?: (context: HttpMiddlewareContext) => unknown;
+    /**
+     * Loads the resource the permission is checked against (optional). May be
+     * async; it is awaited, and a loader that throws or rejects denies (403).
+     */
+    readonly extractResource?: ResourceExtractor;
 }
 /** Options for {@link createActorMiddleware}. */
 export interface ActorMiddlewareOptions extends AuthorizeMiddlewareOptions {
@@ -72,8 +78,11 @@ export declare function createRequirePermissionMiddleware(engine: PermissionEngi
 export declare function authorize(engine: PermissionEngine, permission: string, options?: Omit<RequirePermissionMiddlewareOptions, "permission">): HttpMiddleware;
 /** Options for {@link createRequirePermissionsMiddleware}. */
 export interface RequirePermissionsMiddlewareOptions extends AuthorizeMiddlewareOptions {
-    /** Extracts the resource checked for every permission (optional). */
-    readonly extractResource?: (context: HttpMiddlewareContext) => unknown;
+    /**
+     * Loads the resource checked for every permission (optional). May be
+     * async; it is awaited, and a loader that throws or rejects denies (403).
+     */
+    readonly extractResource?: ResourceExtractor;
     /**
      * `"all"` (default) requires every permission; `"any"` requires one.
      */
@@ -83,7 +92,8 @@ export interface RequirePermissionsMiddlewareOptions extends AuthorizeMiddleware
  * Create middleware that checks multiple permissions.
  *
  * Under `"all"` the first denial short-circuits: evaluating the rest costs
- * policy calls and timeouts for an answer that is already decided.
+ * policy calls and timeouts for an answer that is already decided. An empty
+ * permission list denies in either mode.
  */
 export declare function createRequirePermissionsMiddleware(engine: PermissionEngine, permissions: readonly string[], options?: RequirePermissionsMiddlewareOptions): HttpMiddleware;
 //# sourceMappingURL=httpMiddleware.core.d.ts.map

package/dist/http/httpMiddleware.core.js

@@ -7,6 +7,7 @@
  * @module http/httpMiddleware
  */
 import { createForbiddenResponse, createUnauthorizedResponse, } from "./httpHelpers.js";
+import { loadResource } from "./httpResource.helper.js";
 // ─── State Keys ───────────────────────────────────────────────────────────
 /** State key for the current actor. */
 export const ACTOR_STATE_KEY = "permissions:actor";
@@ -64,8 +65,12 @@ export function createRequirePermissionMiddleware(engine, options) {
         const actor = await resolveActor(context, options);
         if (!actor)
             return createUnauthorizedResponse(options);
-        const resource = options.extractResource?.(context);
-        const decision = await engine.check(actor, options.permission, resource, buildAuthorization(context, options));
+        const loaded = await loadResource(context, options.extractResource, options.onError);
+        if (!loaded.ok) {
+            context.state.set(DECISION_STATE_KEY, loaded.decision);
+            return createForbiddenResponse(loaded.decision, options);
+        }
+        const decision = await engine.check(actor, options.permission, loaded.resource, buildAuthorization(context, options));
         context.state.set(DECISION_STATE_KEY, decision);
         if (!decision.allowed)
             return createForbiddenResponse(decision, options);
@@ -85,7 +90,8 @@ export function authorize(engine, permission, options = {}) {
  * Create middleware that checks multiple permissions.
  *
  * Under `"all"` the first denial short-circuits: evaluating the rest costs
- * policy calls and timeouts for an answer that is already decided.
+ * policy calls and timeouts for an answer that is already decided. An empty
+ * permission list denies in either mode.
  */
 export function createRequirePermissionsMiddleware(engine, permissions, options = {}) {
     const mode = options.mode ?? "all";
@@ -93,7 +99,15 @@ export function createRequirePermissionsMiddleware(engine, permissions, options
         const actor = await resolveActor(context, options);
         if (!actor)
             return createUnauthorizedResponse(options);
-        const resource = options.extractResource?.(context);
+        // An empty list is a configuration error, not a grant: under "all" it
+        // used to fall through to next() for any authenticated actor.
+        if (permissions.length === 0) {
+            return createForbiddenResponse({ allowed: false, reason: "no_permissions", publicReason: "Access denied" }, options);
+        }
+        const loaded = await loadResource(context, options.extractResource, options.onError);
+        if (!loaded.ok)
+            return createForbiddenResponse(loaded.decision, options);
+        const resource = loaded.resource;
         const authorization = buildAuthorization(context, options);
         const results = new Map();
         let lastDenial;

package/dist/http/httpResource.helper.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resource loading for the permission guards.
+ *
+ * @module http/httpResource.helper
+ */
+import type { PermissionDecision } from "../permissionTypes/index.js";
+import type { HttpMiddlewareContext } from "./httpTypes.js";
+/** Loads the resource a permission is checked against. May be async. */
+export type ResourceExtractor = (context: HttpMiddlewareContext) => unknown | Promise<unknown>;
+/** The resource, or the denial to answer with when it could not be loaded. */
+export type ResourceOutcome = {
+    readonly ok: true;
+    readonly resource: unknown;
+} | {
+    readonly ok: false;
+    readonly decision: PermissionDecision;
+};
+/** The decision recorded when the resource loader fails. */
+export declare const RESOURCE_ERROR_DECISION: PermissionDecision;
+/**
+ * Run the extractor and await it.
+ *
+ * The guard used to hand the engine whatever the extractor returned — for an
+ * async loader, a Promise — so every resource condition saw `undefined`:
+ * deny rules on a locked or foreign resource never fired, and a loader that
+ * rejected let the request through while its rejection went unhandled. A
+ * loader that throws or rejects now denies; the error goes to `onError`.
+ */
+export declare function loadResource(context: HttpMiddlewareContext, extract: ResourceExtractor | undefined, onError?: (error: unknown, source: string) => void): Promise<ResourceOutcome>;
+//# sourceMappingURL=httpResource.helper.d.ts.map

package/dist/http/httpResource.helper.js

@@ -0,0 +1,32 @@
+/**
+ * Resource loading for the permission guards.
+ *
+ * @module http/httpResource.helper
+ */
+/** The decision recorded when the resource loader fails. */
+export const RESOURCE_ERROR_DECISION = Object.freeze({
+    allowed: false,
+    reason: "resource_error",
+    publicReason: "Access denied",
+});
+/**
+ * Run the extractor and await it.
+ *
+ * The guard used to hand the engine whatever the extractor returned — for an
+ * async loader, a Promise — so every resource condition saw `undefined`:
+ * deny rules on a locked or foreign resource never fired, and a loader that
+ * rejected let the request through while its rejection went unhandled. A
+ * loader that throws or rejects now denies; the error goes to `onError`.
+ */
+export async function loadResource(context, extract, onError) {
+    if (!extract)
+        return { ok: true, resource: undefined };
+    try {
+        return { ok: true, resource: await extract(context) };
+    }
+    catch (error) {
+        onError?.(error, "extractResource");
+        return { ok: false, decision: RESOURCE_ERROR_DECISION };
+    }
+}
+//# sourceMappingURL=httpResource.helper.js.map

package/dist/http/httpTypes.d.ts

@@ -16,20 +16,33 @@ export interface HttpMiddlewareContext {
     readonly signal: AbortSignal;
     readonly metadata: Readonly<Record<string, unknown>>;
 }
+/**
+ * A request's headers, params or query as either shape a caller may hold.
+ *
+ * The real `@zudojs/http` request exposes plain frozen objects
+ * (`Readonly<Record<…>>`); this mirror used to say `ReadonlyMap`, so code
+ * written against it called `.get()` on an object that has none. Both shapes
+ * are accepted, and the accessor methods below are the portable way to read.
+ */
+export type HttpRequestBag<V> = ReadonlyMap<string, V> | Readonly<Record<string, V | undefined>>;
 /** HTTP request context from @zudojs/http. */
 export interface HttpRequestContext {
     readonly id: string;
     readonly method: string;
     readonly url: string;
     readonly path: string;
-    readonly headers: ReadonlyMap<string, string>;
-    readonly params: ReadonlyMap<string, string>;
-    readonly query: ReadonlyMap<string, string | readonly string[] | undefined>;
+    readonly headers: HttpRequestBag<string>;
+    readonly params: HttpRequestBag<string>;
+    readonly query: HttpRequestBag<string | readonly string[]>;
+    /** Case-insensitive header lookup, as `@zudojs/http` provides it. */
+    getHeader?(name: string): string | undefined;
+    /** Route parameter lookup, as `@zudojs/http` provides it. */
+    getParam?(name: string): string | undefined;
 }
 /** HTTP response context from @zudojs/http. */
 export interface HttpResponseContext {
     readonly status: number;
-    readonly headers: Headers | Record<string, string>;
+    readonly headers: Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
     readonly body?: unknown;
 }
 /** HTTP middleware state from @zudojs/http. */

package/dist/http/index.d.ts

@@ -2,14 +2,16 @@
  * HTTP middleware adapter for @zudojs/permissions.
  *
  * The HTTP types are mirrored locally in `httpTypes.ts` so this package has no
- * hard dependency on @zudojs/http, which is an optional peer. The mirror is
- * structural: anything satisfying the real `HttpMiddlewareContext` satisfies
- * the local one, so the middleware composes with the real pipeline. Keep the
- * two in step when @zudojs/http changes — nothing here can check it for you.
+ * dependency on @zudojs/http at all — http sits in a higher architecture tier,
+ * so it cannot be a dependency or a peer. The mirror is structural: anything
+ * satisfying the real `HttpMiddlewareContext` satisfies the local one, so the
+ * middleware composes with the real pipeline. A test runs the guard inside
+ * the real `HttpMiddlewarePipeline` to keep the two in step.
  *
  * @module http
  */
 export { createActorMiddleware, createRequirePermissionMiddleware, authorize, createRequirePermissionsMiddleware, ACTOR_STATE_KEY, DECISION_STATE_KEY, DECISIONS_STATE_KEY, type AuthorizeMiddlewareOptions, type ActorMiddlewareOptions, type RequirePermissionMiddlewareOptions, type RequirePermissionsMiddlewareOptions, } from "./httpMiddleware.core.js";
 export { createForbiddenResponse, createUnauthorizedResponse, createJsonResponse, type DeniedResponseOptions, type PermissionHttpResponse, } from "./httpHelpers.js";
-export type { HttpMiddleware, HttpMiddlewareContext, HttpRequestContext, HttpResponseContext, HttpMiddlewareState, } from "./httpTypes.js";
+export { loadResource, RESOURCE_ERROR_DECISION, type ResourceExtractor, type ResourceOutcome, } from "./httpResource.helper.js";
+export type { HttpRequestBag, HttpMiddleware, HttpMiddlewareContext, HttpRequestContext, HttpResponseContext, HttpMiddlewareState, } from "./httpTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -2,13 +2,15 @@
  * HTTP middleware adapter for @zudojs/permissions.
  *
  * The HTTP types are mirrored locally in `httpTypes.ts` so this package has no
- * hard dependency on @zudojs/http, which is an optional peer. The mirror is
- * structural: anything satisfying the real `HttpMiddlewareContext` satisfies
- * the local one, so the middleware composes with the real pipeline. Keep the
- * two in step when @zudojs/http changes — nothing here can check it for you.
+ * dependency on @zudojs/http at all — http sits in a higher architecture tier,
+ * so it cannot be a dependency or a peer. The mirror is structural: anything
+ * satisfying the real `HttpMiddlewareContext` satisfies the local one, so the
+ * middleware composes with the real pipeline. A test runs the guard inside
+ * the real `HttpMiddlewarePipeline` to keep the two in step.
  *
  * @module http
  */
 export { createActorMiddleware, createRequirePermissionMiddleware, authorize, createRequirePermissionsMiddleware, ACTOR_STATE_KEY, DECISION_STATE_KEY, DECISIONS_STATE_KEY, } from "./httpMiddleware.core.js";
 export { createForbiddenResponse, createUnauthorizedResponse, createJsonResponse, } from "./httpHelpers.js";
+export { loadResource, RESOURCE_ERROR_DECISION, } from "./httpResource.helper.js";
 //# sourceMappingURL=index.js.map

package/dist/permission/index.d.ts

@@ -3,6 +3,6 @@
  *
  * @module permission
  */
-export { parsePermission, parsePermissionSafe, isValidPermission, matches, matchesPermission, formatPermission, } from "./permission.core.js";
+export { parsePermission, parsePermissionSafe, isValidPermission, matches, matchesPermission, permissionsOverlap, formatPermission, } from "./permission.core.js";
 export { createPermissionRegistry, type PermissionRegistry, type PermissionRegistryOptions, type RegisteredPermission, } from "./permissionRegistry.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/permission/index.js

@@ -3,6 +3,6 @@
  *
  * @module permission
  */
-export { parsePermission, parsePermissionSafe, isValidPermission, matches, matchesPermission, formatPermission, } from "./permission.core.js";
+export { parsePermission, parsePermissionSafe, isValidPermission, matches, matchesPermission, permissionsOverlap, formatPermission, } from "./permission.core.js";
 export { createPermissionRegistry, } from "./permissionRegistry.js";
 //# sourceMappingURL=index.js.map

package/dist/permission/permission.core.d.ts

@@ -32,6 +32,18 @@ export declare function matches(pattern: string, target: string): boolean;
  * Check if a permission pattern matches a structured Permission object.
  */
 export declare function matchesPermission(pattern: string, permission: Permission): boolean;
+/**
+ * Check if two permission patterns can name a common permission.
+ *
+ * This is the test a *deny* needs. For a concrete target it is exactly
+ * {@link matches}; for a wildcard target such as `post:*` it also holds when
+ * the deny is narrower (`post:delete`), which `matches` does not see.
+ *
+ * @example permissionsOverlap("post:delete", "post:*") → true
+ * @example permissionsOverlap("*:delete", "post:*") → true
+ * @example permissionsOverlap("post:delete", "post:read") → false
+ */
+export declare function permissionsOverlap(a: string, b: string): boolean;
 /**
  * Parse a permission string, returning null on invalid format instead of throwing.
  */

package/dist/permission/permission.core.js

@@ -4,7 +4,7 @@
  * @module permission/permission
  */
 import { InvalidPermissionError } from "../permissionErrors/index.js";
-import { patternStrMatches } from "../rule/rule.core.js";
+import { patternStrMatches, patternsOverlap } from "../rule/rule.pattern.js";
 /**
  * Valid permission format: `resource:action`.
  *
@@ -62,6 +62,25 @@ export function matchesPermission(pattern, permission) {
     return (patternStrMatches(parsed.resource, permission.resource) &&
         patternStrMatches(parsed.action, permission.action));
 }
+/**
+ * Check if two permission patterns can name a common permission.
+ *
+ * This is the test a *deny* needs. For a concrete target it is exactly
+ * {@link matches}; for a wildcard target such as `post:*` it also holds when
+ * the deny is narrower (`post:delete`), which `matches` does not see.
+ *
+ * @example permissionsOverlap("post:delete", "post:*") → true
+ * @example permissionsOverlap("*:delete", "post:*") → true
+ * @example permissionsOverlap("post:delete", "post:read") → false
+ */
+export function permissionsOverlap(a, b) {
+    const left = parsePermissionSafe(a);
+    const right = parsePermissionSafe(b);
+    if (!left || !right)
+        return false;
+    return (patternsOverlap(left.resource, right.resource) &&
+        patternsOverlap(left.action, right.action));
+}
 /**
  * Parse a permission string, returning null on invalid format instead of throwing.
  */

package/dist/policy/policyRegistry.d.ts

@@ -8,6 +8,12 @@ import type { PermissionPolicyDefinition } from "../permissionTypes/index.js";
 export interface PolicyRegistryOptions {
     /** Allow overwriting an existing policy. Defaults to false. */
     readonly allowOverride?: boolean;
+    /**
+     * Reject permission patterns that are not `resource:action`. Defaults to
+     * true — a policy scoped to a pattern that never matches never runs, so a
+     * mistyped lockdown would deny nothing.
+     */
+    readonly validatePermissions?: boolean;
 }
 /** A policy registry, usable directly as the engine's `policies` source. */
 export interface PolicyRegistry {
@@ -19,6 +25,12 @@ export interface PolicyRegistry {
     all(): readonly PermissionPolicyDefinition[];
     remove(name: string): boolean;
     clear(): void;
+    /**
+     * Be told whenever the policy set changes. Returns an unsubscribe function.
+     * An engine built on this registry subscribes itself, so a policy change
+     * is not bypassed by a cached decision.
+     */
+    subscribe(listener: () => void): () => void;
 }
 /**
  * Create a policy registry.

package/dist/policy/policyRegistry.js

@@ -5,6 +5,8 @@
  */
 import { DuplicatePolicyError } from "../permissionErrors/index.js";
 import { selectPolicies } from "../evaluator/evaluator.pipeline.js";
+import { validatePolicy } from "../evaluator/engineSupport/index.js";
+import { createChangeNotifier } from "../utils/utils.notifier.js";
 /**
  * Create a policy registry.
  *
@@ -13,6 +15,8 @@ import { selectPolicies } from "../evaluator/evaluator.pipeline.js";
 export function createPolicyRegistry(options) {
     const policies = new Map();
     const allowOverride = options?.allowOverride ?? false;
+    const validatePermissions = options?.validatePermissions ?? true;
+    const changes = createChangeNotifier();
     return {
         /**
          * Register a policy.
@@ -20,12 +24,22 @@ export function createPolicyRegistry(options) {
          * Re-registering a name is rejected unless `allowOverride` was set: a
          * second `define("owner-only", …)` used to replace the first in silence,
          * which is an authorization rule vanishing without a trace.
+         *
+         * @throws {InvalidPermissionError} when a permission pattern is malformed.
          */
         define(definition) {
+            if (validatePermissions)
+                validatePolicy(definition);
             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]),
+            }));
+            changes.notify();
         },
         get(name) {
             return policies.get(name);
@@ -50,10 +64,17 @@ export function createPolicyRegistry(options) {
             return [...policies.values()];
         },
         remove(name) {
-            return policies.delete(name);
+            const removed = policies.delete(name);
+            if (removed)
+                changes.notify();
+            return removed;
         },
         clear() {
             policies.clear();
+            changes.notify();
+        },
+        subscribe(listener) {
+            return changes.subscribe(listener);
         },
     };
 }

package/dist/role/roleRegistry.d.ts

@@ -26,7 +26,25 @@ export interface RoleRegistry {
     all(): readonly RoleDefinition[];
     remove(name: string): boolean;
     clear(): void;
+    /**
+     * Be told whenever the role set changes (`define`, a `remove` that removed
+     * something, `clear`). Returns an unsubscribe function.
+     *
+     * An engine built on this registry subscribes itself, which is what makes
+     * revoking a role take effect on the next check instead of whenever
+     * somebody remembers to call `engine.invalidateRoles()`.
+     */
+    subscribe(listener: () => void): () => 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,26 @@
  */
 import { DuplicateRoleError, InvalidRoleError, RoleNotFoundError, } from "../permissionErrors/index.js";
 import { isValidPermission } from "../permission/permission.core.js";
+import { invalidRulePattern } from "../evaluator/engineSupport/index.js";
+import { createChangeNotifier } from "../utils/utils.notifier.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.
  *
@@ -14,6 +34,7 @@ export function createRoleRegistry(options) {
     const roles = new Map();
     const allowOverride = options?.allowOverride ?? false;
     const validatePermissions = options?.validatePermissions ?? true;
+    const changes = createChangeNotifier();
     return {
         /**
          * Register a role definition.
@@ -36,11 +57,19 @@ export function createRoleRegistry(options) {
                             `valid "resource:action" permission`);
                     }
                 }
+                for (const rule of definition.rules ?? []) {
+                    const invalid = invalidRulePattern(rule);
+                    if (invalid !== undefined) {
+                        throw new InvalidRoleError(`Role "${definition.name}" has a rule on "${invalid}", which is ` +
+                            `not a valid "resource:action" pattern`);
+                    }
+                }
             }
             if (roles.has(definition.name) && !allowOverride) {
                 throw new DuplicateRoleError(definition.name);
             }
-            roles.set(definition.name, Object.freeze({ ...definition }));
+            roles.set(definition.name, freezeRoleDefinition(definition));
+            changes.notify();
         },
         get(name) {
             return roles.get(name);
@@ -61,10 +90,17 @@ export function createRoleRegistry(options) {
             return [...roles.values()];
         },
         remove(name) {
-            return roles.delete(name);
+            const removed = roles.delete(name);
+            if (removed)
+                changes.notify();
+            return removed;
         },
         clear() {
             roles.clear();
+            changes.notify();
+        },
+        subscribe(listener) {
+            return changes.subscribe(listener);
         },
     };
 }

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

@@ -4,23 +4,7 @@
  * @module rule/rule
  */
 import type { PermissionRule, Permission, PermissionContext, RuleCombiningAlgorithm, RuleEvaluation } from "../permissionTypes/index.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}.
- */
-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;
+export { ruleMatches, patternStrMatches } from "./rule.pattern.js";
 /**
  * Evaluate a set of rules against a target permission.
  *
@@ -29,9 +13,15 @@ export declare function patternStrMatches(pattern: string, target: string): bool
  * 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.
@@ -44,8 +34,10 @@ export declare function evaluateRules(rules: readonly PermissionRule[], target:
  * 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 declare function evaluateRulesSync(rules: readonly PermissionRule[], target: Permission, options?: {
     readonly algorithm?: RuleCombiningAlgorithm;